PageScribe

Photograph the open spread of a book, page by page. PageScribe reads the text off each photo in the background, puts the pages back in order by their printed page numbers, and writes them into a single .txt file named after the book. The photos themselves are shrunk down and kept alongside the text.

You never have to wait for recognition: shoot the next spread while the previous one is still being read.

What it does

• One photo = one two-page spread. The camera screen shows the spread and a shutter; each shot is dropped straight into the book's queue.
• Background OCR. A WorkManager chain drains the queue, so you can keep shooting. Progress is shown on the shelf, in the book, and on the camera screen, and as a notification.
• A text file per book. Pages are ordered by the folio (printed page number) they carry, not by the order you happened to photograph them. The finished file is <book title>.txt.
• Figures and captions are dropped. Isolated short lines that sit under picture content (with their one or two credit lines) are filtered out, while a short line over blank paper is kept.
• Small archived photos. Each source JPEG is scaled so the smallest text line on the page is about 20 px tall, converted to greyscale, and encoded at the lowest quality on a ladder that still keeps the text region close to the original. The smaller of JPEG and WebP wins. A ~350 KB source becomes a ~35 KB archive.

Everything lives in app-private storage (files/books/<title>/); the Export text button hands the assembled .txt to the system share sheet, from where it can go to Drive, email, or the Files app.

Screens

• Shelf (MainActivity) — one row per book, plus a + to create one.
• Capture (CaptureActivity) — CameraX preview, flash toggle, shutter, and a jump to the book.
• Book (BookActivity) — the pages read so far, the log, Export text, Capture, and Delete book.

How the pipeline works

Each queued photo goes through SpreadProcessor:

1. Decode the JPEG (EXIF rotation honoured), longest edge OCR_MAX_EDGE.
2. Find the gutter between the two pages as a tilted line, so a slightly skewed shot still splits cleanly. Falls back to the image centre.
3. Run ML Kit text recognition over the whole spread (bundled Latin model, so it works offline).
4. Split the recognised lines by the gutter and read each half's folio — the bare page number near the outer edge, top or bottom.
5. Drop captions: short, narrow lines isolated below picture content.
6. Reflow the body into paragraphs, gluing hyphenated line breaks and trimming running heads.
7. Write pages/%04d.txt (folio = sort key) and archive the image.

At the end, assembleTextFile sorts the page files by folio, joins each page to the next when a sentence runs across the spread, and writes <title>.txt.

Storage layout

files/books/<sanitized title>/
  meta.properties        book title, created-at
  queue/                 photos waiting to be read (claimed by the worker)
  work/                  in-flight photos
  pages/                 %04d.txt, one per recognised page
  images/                the archived (shrunk) photos, same numbering
  failed/                photos given up on after MAX_JOB_ATTEMPTS
  log.txt                human-readable progress log
  failures.properties    why each failed photo failed
  <title>.txt            the assembled book

The queue is crash-safe: PageScribeApp.onCreate reclaims photos orphaned in work/ older than two minutes and re-arms the worker, and failed photos are retried up to MAX_JOB_ATTEMPTS before being parked in failed/.

Building

./gradlew :app:assembleDebug        # APK at app/build/outputs/apk/debug/
./gradlew :app:testDebugUnitTest    # 83 unit tests (JVM + Robolectric)

Install on a connected device:

adb install -r app/build/outputs/apk/debug/app-debug.apk

Release builds read signing credentials from keystore.properties at the repo root (git-ignored); without it a release APK is produced unsigned.

Tech

• Kotlin, Material Components, minSdk 26, targetSdk 36.
• CameraX 1.6.2 for preview and capture.
• ML Kit text-recognition 16.0.1 (bundled Latin model — no Play services, no network).
• WorkManager 2.12.0 for the durable OCR queue.

Note: from targetSdk 35 on, Android enforces edge-to-edge and the built-in AppCompat action bar is no longer inset correctly, so each screen uses a MaterialToolbar in an AppBarLayout and applies the system-bar insets itself (util/EdgeToEdge.kt).

Tests

app/src/test/ holds 83 JVM/Robolectric tests covering the parts that do not need a camera:

Suite	What it covers
GutterDetectorTest	tilted-gutter fit and centre fallback
PageNumberDetectorTest	folio geometry and margin isolation
PageNumberResolverTest	choosing the right folio per half
CaptionFilterTest	dropping captions under figures, keeping orphans
ParagraphReflowTest	hyphen gluing, running heads, across-page join
BitmapsTest	EXIF-aware downsample and scaling
ImageArchiverTest	archive scale and JPEG/WebP quality ladder
BookRepositoryTest	create/list/delete and navigation
BookTest	queue claim/fail/complete and text assembly

Known limitations

• The archive size is driven by the smallest text on the page, so a page with a tiny folio or caption archives a little larger than a body-text floor would suggest.
• A figure that interrupts a paragraph produces a paragraph break (treated as a section break).
• Two-page spreads whose text runs past the gutter (an illustration, or a very wide table) can only be split at the fitted gutter line.