moebiusT7/book-ocr-studio

1---2title: Book OCR Studio3emoji: 📖4colorFrom: green5colorTo: blue6sdk: static7app_file: index.html8pinned: false9license: agpl-3.010short_description: Kindle, PDF and scan OCR on your own PC, with Gemma review11---12 13*The block above is Hugging Face Space metadata; it is not application configuration.*14 15# Book OCR Studio — Local-first book OCR16 17Turn your Kindle books, PDFs and page images into files you can read, search or give to a language model — on your own computer.18 19**Local OCR. Local Gemma review. Local MD, HTML, PDF and EPUB export.**20 21## What it looks like22 23Click any image to enlarge it.24 25**1 · Start.** Upload a PDF or page images, or switch to the Kindle capture tab.26 27<a href="docs/images/01-start.png"><img src="docs/images/01-start.png" width="70%" alt="Start screen: PDF / Images and Kindle capture tabs, page range, GPU mode, Start conversion"></a>28 29**2 · Review against the page image.** Compare the page image with the suggested text; the original OCR is kept until you approve a page.30 31<a href="docs/images/02-review.jpg"><img src="docs/images/02-review.jpg" width="100%" alt="Review screen: source page image beside Original OCR, Gemma suggestions and Changes tabs, with Approve and Restore buttons"></a>32 33<sub>On this page Gemma proposed changing "can neither" to "cannot". The image check did not support it, so the suggestion was deferred and the original reading kept — the note and the deferral message are visible above the Approve / Restore buttons.</sub>34 35**3 · Use the Markdown.** The export keeps a `<!-- source page: n -->` marker per screen, so any LLM answer can be checked against the page.36 37<a href="docs/images/03-markdown.png"><img src="docs/images/03-markdown.png" width="100%" alt="Exported Markdown with source-page markers, and a question answered from it by a local model"></a>38 39The page in image 2 is a public-domain scan (Ruskin, *The Stones of Venice*, 1890 edition, page 50, via Wikimedia Commons); images 1 and 3 use a short synthetic text written for this documentation. The answer in image 3 was produced by the local `gemma4:12b` through Ollama. The images illustrate the interface, not an accuracy level.40 41This is a Linux-focused source beta. See [INSTALL.md](INSTALL.md) for the isolated-environment installer and [RELEASE_NOTES.md](RELEASE_NOTES.md) for the exact validation scope. Compatibility with every GPU, language or Kindle layout is not guaranteed. On Hugging Face, this Space is a static distribution page; processing runs on your own computer.42 43## Workflow44 451. Install Ollama, then follow [INSTALL.md](INSTALL.md). Standard `bash install.sh` prepares Gemma 12B and the included C1 workflow. Then launch `bash run.sh` from the project directory and open `http://127.0.0.1:8507/`.462. Upload one PDF or multiple page images, or open a book in the connected Kindle Chrome window.473. Select a page range or **All pages**. Kindle capture uses `0` for the entire book; a positive capture limit produces a sample.484. Choose a Gemma model and GPU mode, or configure the optional vision connector, then start. Completed pages are saved for recovery.495. Inspect source images, original OCR, suggested text and diffs. Approve suggestions per page if desired.506. Download MD or independently create HTML, PDF or EPUB. Export does not repeat OCR or Gemma inference.51 52## Output formats53 54| Format | Content |55| --- | --- |56| MD | Model-input text with source-screen references, separate unapproved suggestions and review notes |57| HTML | Self-contained source images beside text and suggestions |58| PDF | Source-image pages followed by selectable/searchable reading text and separate suggestions; bookmarks by input screen |59| EPUB 3 | Reflowable reading text with navigation, separate suggestions and embedded source images |60| ZIP | Existing job records, images and review artifacts |61 62Filenames default to `Book title_Author.ext`; when the author is unknown, the title alone is used. Titles and authors remain in their original language. PDF and EPUB are reading copies, not reproductions of publisher typography. Input-screen numbering is not necessarily printed page numbering. Source images preserve layouts that OCR may interpret incorrectly.63 64**Original OCR is never silently replaced by unapproved model suggestions.** The reading text uses original OCR unless a matching candidate has been explicitly approved. Both OCR and model review can be wrong. Check the image for important quotations, numbers and names. A successful review is not proof of correctness.65 66## What stays local67 68- OCR, image-based Gemma review, source images, suggestions and exports stay in the local workflow. No cloud AI service is used by default. If you explicitly enable the optional API connector, images and OCR text are sent to the endpoint you select.69- The app listens on `127.0.0.1:8507`; the optional Chrome bridge uses `127.0.0.1:8508`.70- Initial dependency/model downloads need internet access. Kindle login and reading communicate with Amazon. Browser extensions, translation services and files you choose to upload elsewhere are outside the local processing boundary.71- The app preserves the source language; it does not translate books. Accuracy varies by language, layout and scan quality. Japanese and English samples have been tested; other languages are not universally validated.72 73## License and optional engines74 75Original application code: **AGPL-3.0-only** ([LICENSE](LICENSE)). See [third-party notices](THIRD_PARTY_NOTICES.md) for separate dependency and model terms. No weights, environments or book content are part of the intended source distribution.76 77**Marker is the default OCR engine for new jobs.** YomiToku is an explicit optional choice with CC BY-NC-SA 4.0 terms unless separately licensed. Marker/Surya model weights also have additional conditions: choosing Marker is not a declaration of unrestricted commercial eligibility. Source-only packaging does not remove third-party obligations.78 79## Models and hardware80 81- Default UI model: `gemma4:12b-it-qat`; optional `gemma4:26b-a4b-it-qat`.82- UI profile name: **Möbius Custom C1 for OCR**. This is the app's OCR-specific prompt/review workflow, not a fine-tuned weight release or execution of the entire published C1 governance wrapper.83- OCR: Marker by default; YomiToku is available only as an explicit selection when its separate environment is installed. The shared selector applies to PDF, images and Kindle.84- Single-GPU parallel mode requires **YomiToku + 12B**, explicitly selected, and at least **14.5GB free VRAM**. A 16GB or larger GPU is recommended. A 12GB card does not meet this mode's current requirement.85- Sequential mode runs OCR then Gemma. Two-GPU mode separates them. Automatic scheduling chooses from available resources and recorded timing/bandwidth data; it is not a proven optimal scheduler.86- VRAM failures can fall back from shared GPU to dual GPU, then sequential processing when resources permit. Other applications' GPU jobs are not stopped.87- Existing successful page reviews are preserved when resuming, so changing the selected model does not retroactively change them.88 89## Optional models and API servers90 91Gemma 4 remains recommended. An opt-in **OpenAI-compatible Chat Completions connector** supports user-selected **vision-capable** models. API compatibility alone does not guarantee image/JSON support, full-job completion or accuracy. Local OCR runs first; this app does not manage the chosen server's GPU. See [CONNECTORS.md](CONNECTORS.md) for setup, content transfer, plaintext local credential storage and limitations.92 93## Installation and dependencies94 95The app/Marker environment is `.venv`; optional YomiToku uses a separate `.venv-yomitoku`. `requirements.txt` lists pinned direct app dependencies, and `requirements-yomitoku.txt` lists the optional engine dependencies. The default Python 3.10 install also uses `constraints-linux-py310.txt`, a tested transitive version snapshot without artifact hashes. Python 3.11 and optional YomiToku resolve separately. The installer does not inherit system Python packages. See [INSTALL.md](INSTALL.md) for NVIDIA, Chrome and Ollama prerequisites.96 97PDF export uses PyMuPDF; EPUB uses the Python standard library. No cloud API is needed. The standard installer downloads missing 12B weights locally under their own terms; they are not included in this source ZIP. 26B is an optional additional download. Browser binaries are installed separately.98 99## Local data and source100 101- `app.py`, `kindle_ui.py`: UI102- `oneclick.py`, `kindle_capture.py`, `chrome-extension/`: Kindle capture103- `core.py`, `region_review.py`, `verify_edits.py`: review and source preservation104- `scheduler.py`, `gpu_fallback.py`: GPU selection and fallback105- `delivery.py`, `delivery_ui.py`, `portable_export.py`: on-demand exports106- `review_connector.py`, `connector_ui.py`: optional vision API transport and consent UI107- `jobs/`, `captures/`: private source material and processing state108- `.connector-profiles/`: private endpoint profiles and credentials; never publish109 110Do not include jobs, captures, downloaded books, browser profiles, credentials or personal logs in a public release.111 112## Verification and publication113 114Run `python3 scripts/verify_public.py .` to check a built source package. Public smoke tests use only generated synthetic material. Read [RELEASE_NOTES.md](RELEASE_NOTES.md) for limitations and [HUGGINGFACE.md](HUGGINGFACE.md) for upload instructions. Private experimental books, logs and machine-specific evidence are not included.115 116## Redistributing modified versions117 118See [HUGGINGFACE.md](HUGGINGFACE.md) for owner-facing packaging and upload instructions.119 120## Community ports welcome121 122I built this tool for my own Linux workflow and am sharing it in the hope that others find it useful. If you like it, you're welcome to fork it and port it to Windows, macOS, or other platforms under AGPL-3.0-only. Third-party dependency and model licenses still apply.123 124Pull requests are welcome, but I cannot promise support, testing, or maintenance for other platforms.125