tts-voice-creator-clone-and-design-2/Manual.md

User manual

Living manual. Every feature updates this file in the same commit as the code.

Sections for the mature features (voice library, Read Aloud, audiobook casting, Rehearser) are still to be written — this file was created alongside the magazine feature and currently documents that area only.

---

Audiobook casting (Read Aloud → Cast as Audiobook)

Purpose

Turn a book into a script with one narrator and one voice per character, ready for the Rehearser and MP3 export.

Prerequisites

• A book open in Read Aloud (PDF or text) and an LLM configured in Settings.

Step by step

1. Open the book, then Cast as Audiobook.
2. The app finds the quotation marks in the text and splits it into narration and spoken lines by itself — this part never changes a word of the book. The LLM is then asked only who speaks each spoken line, in passages of a few thousand characters. A whole novel takes roughly ten minutes (the previous method took hours).
3. Progress shows per passage; Stop Casting keeps what is done and Continue casting resumes.
4. Review the cast as before. Recast unknown re-reads only the lines still marked Unknown, with more context; a line the model cannot place stays Unknown rather than getting a guessed voice. Verify (the second quality run) reads every spoken line a second time with different passage boundaries — about as long as the first cast — and never changes a speaker: lines both readings agree on are marked confirmed (about 4 in 5 of those were right in testing), and lines where they disagree keep the first reading, are flagged in the review list and show what the other reading said. The percentage next to each line means what it says in testing: confirmed lines were about 82 % right, disputed lines about 48 %, lines not yet verified about 76 %. Use the flags to decide where to spend your review time. Neither step can change the book's text, and a stopped or failed run leaves the cast as it was.

Expected result: every word of the book appears exactly once, quoted speech is typed as dialogue and everything else as narration. When the text only refers to a person by role ("der Fremde", "die Baronin"), the line is labelled with that role; later passes merge it into the named character when the book itself ties the two together (e.g. "der Inquisitor Marcian"). Some role labels stay separate — use the character merge in the cast view for those.

Errors, limits and privacy

• If the LLM cannot be reached for a passage, its lines are named from the speech tags around them where possible and otherwise marked Unknown; nothing is lost.
• A book whose speech is not marked with quotation marks (»…«, „…“, “…”, «…») uses the previous whole-passage method automatically. To force the previous method in this browser: localStorage['ab-span-mode'] = '0'.
• The custom attribution prompt in Settings only applies to the older whole-passage method; span mode uses its own fixed instructions (it only asks who speaks each line).
• Book text goes to the LLM you configured, exactly as before; nothing else is sent anywhere. Nothing works offline without a reachable LLM.
• Accuracy: measured against hand-corrected casts of three novels, roughly 90–92 % of all words end up with the right voice and about three quarters of spoken words with the right speaker. Similar-looking characters in the same scene are the usual mix-up; check those in review.

---

Magazines

Purpose

Listen to a magazine or newspaper one article at a time, from its true beginning to its true end, without adverts, sidebars or a neighbouring article spliced into the middle. Each article can be narrated by a single voice, or turned into a podcast discussion between two or three voices you pick.

Prerequisites

• The magazine as a PDF (native text or scanned — both work), or its pages as PNG/JPEG images (scans or phone photos): choose or drop several at once and they become one magazine, pages in filename order (page2 before page10). Up to 300 images of at most 25 MB each; a photo's EXIF rotation is applied. Images carry no text, so every page is read with OCR. Do not mix a PDF with images.
• At least one voice in the library for narration.
• For podcast mode: an LLM configured in Settings (llm_url, llm_model), and two or three voices chosen as hosts.

Step by step

1. Add the magazine. Studio → Add Magazine / Paper. Give it a title and issue, then upload the PDF.
2. Ingest. Ingestion runs in the background — you can close the browser. It renders every page, extracts text (falling back to OCR on scanned pages), classifies each region of the layout, finds the contents page, and proposes articles with page ranges. While it runs, a live preview shows each page's image next to its recognised text as soon as that page finishes -- a detected headline is shown larger, a figure appears as its own picture marker rather than as garbled on-image text, and page furniture is shown dimmed -- so you can see ingestion actually working page by page instead of watching a bare progress bar. This preview is a quick approximation, not the final read: it runs before the layout is fully classified, so a heading guess or an excluded marking here can still change once review opens. The page image also shows the regions as they are found: each box is drawn over the page, coloured by type (headline, paragraph, caption, picture, advert, running head …, see the legend under the page) and numbered in reading order. After all pages are read, the second pass (Recognising paragraphs, headings and advertisements) walks the pages again and the preview follows it, so you can watch boxes change type — the progress bar then reads "… — page 12 of 204". Pictures, charts, tables and code are only recognised in this second pass (the first pass only reads text, and says so under the page); they are drawn as dashed, filled boxes in their own colours — picture orange, chart green, table yellow, code grey — so they stand out from the text boxes, and fitted to the actual picture as soon as that page is labelled (not only once the whole magazine has finished), so the box does not lag behind the real edges of the picture for long. The recognised-text panel shows the actual cropped picture, chart or table for the same reason, rather than a plain "Figure" placeholder, as soon as it has been cropped. The page scan itself (a scanned magazine is one picture per page) is not framed. A proposed picture, chart or table is checked against the page render itself before it is created, so a text area or column gap is not shown as a picture. A real picture can still get a loose or shifted box in some cases; use Refine figures (or re-run detection on the page) to try snapping it again, or fix the box by hand on the review page. If a run is interrupted (for example when the server restarts), the status now says so instead of spinning forever; start it again with Re-run detection.
3. Review the articles. This step is not optional and cannot be skipped. Each proposed article shows its title, author, page range, estimated listening time and a confidence score. The review screen is split: the scanned page on the left with a numbered, icon-labelled box per detected region (title, byline, body text, caption, figure…), and the same regions as text on the right — click either side to highlight the other. Sidebars and pull-out boxes are already unticked for you — tick one back in if you actually want it read. A region already claimed by a different article on the same page is marked with that article's number, so it is never mistaken for unclaimed text. If OCR quality is poor, "OCR again" re-reads just the current page through the configured vision engine (or "OCR again (whole magazine)" from the contents screen for every page, which also resets any articles already reviewed). If a figure's box is drawn in the wrong place or at the wrong size — a common miss, because an OCR engine locates a photo far less precisely than it reads type — "Fix figure boundaries" re-derives every figure box in the issue from the scanned pages themselves. It calls no OCR engine, changes no text and touches no approval, so it is safe to run at any point, including on an issue you are halfway through reviewing; boxes it cannot place confidently are left exactly as they were. If the layout engine missed a region entirely, "Draw it" lets you click-drag a box directly on the page image and add it as text (typed or OCRed) or as a new figure. If a region was found but its box is misplaced, the wrong size, or shouldn't exist at all, "Edit boxes" lets you drag an existing box to move it, drag any of its eight edge/corner handles to resize just that side, or press its × to delete it outright. The per-edge handles matter most when two regions share a boundary — for example a paragraph split wrongly between two boxes — since dragging just the top or bottom handle moves that one shared line without disturbing either box's width or its opposite edge. Moving or resizing opens a small confirm panel — Save keeps the region's existing text at its new position; for a text region, Save & re-OCR also reads the corrected area again and replaces the text with that fresh reading (useful when the box was too small or too large to read cleanly the first time, or after moving a shared boundary). Deleting a region removes it from the page entirely, not just from the article currently under review. Every row in the list on the right also has its own type picker and delete button (the bin icon), so you can fix a region without switching into Edit boxes: change a paragraph into a Headline, a Page number, an Advertisement or any other kind, or turn a text box into an Image (the box is cut out as a figure) and back (the box is read with OCR). Delete asks for confirmation first. The page's reading order is updated after a type change, because a page number or advert is read differently from running text. "Fix reading order" re-reads the order of every page in the issue column by column — left column top to bottom, then the next column — for issues imported before the column detection improved. It changes only the order: text, boxes and approvals stay as they are, although an approved article may now be read in a different (correct) order. Short pull-quotes are read at the end of the page instead of in the middle of a sentence. To set the order yourself, either type a new number into the position box at the front of a row (the region moves there), or press "Order by clicking" and click the boxes on the page in the order they should be read — each clicked box shows its new number, Undo last takes one back, and boxes you skip follow in their current order — then Save order. A page ordered by hand says so above the list and is never reshuffled by Fix reading order, a type change or a newly drawn box (a new box is read last until you move it); "Automatic order" hands the page back to the automatic column order. "Clean up boxes" fixes four problems across the whole issue at once: short text inside a picture (a label on a screenshot, a word on a slide in a photo) becomes Text in picture; boxes of one or two characters become OCR noise; a box that only repeats a bigger box's text (typically a subheading the paragraph box also read) becomes Duplicate, so it is not read twice; and an author line that runs into the article's first sentence is split into the name and a paragraph of its own. None of these are read aloud, nothing is deleted, every change shows in the list and can be undone with the type picker, and a backup of the page layout is kept (layout.backup-<date>.json in the issue's folder). New imports and OCR again do this automatically. Longer text inside a picture is left for you to judge: it can be real text caught in a picture frame that is too big. Each text row also has three quick actions: Edit text (the pencil) opens the region's text in place — fix OCR mistakes and Save text, or put the cursor where one paragraph ends and press Split here to make two regions (the second is read right after the first); Read again re-runs OCR on just that region; and Merge with the next region joins a paragraph the OCR cut in two (a word broken by a hyphen at the line end is closed up again). Everything works from the keyboard too: ↑/↓ move between regions, Space ticks or unticks, Enter edits the text, R reads again, M merges with the next region and Delete deletes (with Undo); letters typed in the text editor are never taken as shortcuts. To fix many boxes at once, press "Select boxes", then click boxes on the page or drag a rectangle over them (every box at least half inside is selected; X selects the focused row from the keyboard). A bar shows how many are selected: change their type in one go, or delete them. Deleting, changing a type, merging and splitting no longer ask "are you sure?" — they happen at once and an Undo button appears above the list (it undoes the latest change, and only while nothing else has changed since). When a region becomes a picture — drawn as one or changed into one — the short text inside it (a chart's legend and axis labels) automatically becomes Text in picture, so there is nothing left to delete by hand. Use "Two-page spread" to see this page next to its facing page (e.g. 22 and 23), each with its own OCR-results list directly beneath it — useful for lining up a figure or a jump that crosses the gutter. Only one page is editable at a time; click "Edit this page" on the other half to switch which one the drawing and editing tools apply to. Confirm the boundaries, correct the title, then Approve. Optionally, click "Describe" under a figure, chart, table or code block to have the configured vision engine generate a one- or two-sentence description for listeners who cannot see the image — e.g. what a chart measures and its general trend, or a table's row/column headings and what stands out. You can edit the generated text, or write your own from scratch, before approving the article. Generating a description changes nothing about existing narration by itself — it is only spoken if you also turn on "Read figure descriptions" in step 4.
4. Listen. An approved article can be narrated with the default voice, or sent to podcast mode. Pick the narrator (and the podcast hosts) from the same searchable voice picker used elsewhere in the app — open it and type to filter the list. Playback synthesises one sentence at a time, staying a few sentences ahead, so you only wait for the first. To avoid waiting at all, press Prepare audio first: it synthesises the whole article now (starting from where you are, then the part before it), shows progress as "Preparing audio 12 / 24", and can be cancelled with the same button. Once it says "Audio ready", Listen plays straight through from the prepared audio. Prepared audio is held in the browser only — closing or reloading the tab, opening another article, or changing the narrator discards it, and Prepare audio must be run again. Use Play all articles (on the contents screen) to listen through every approved article back to back without returning to this screen between them. A figure from the page is shown automatically as playback reaches it. Word highlighting can be turned off if you find it distracting — it is an estimate based on word length, not a measurement, so it will not always land exactly on the spoken word. Turn on "Read figure descriptions" in the reading controls to have any figure descriptions generated during review spoken aloud where they occur in the article; figures without a generated description are silently skipped, exactly as before this option existed. Driving mode (the button next to the article title) is a full-screen, podcast-style player for the generated MP3s: previous/next article, back 15 s / forward 15 s, large play/pause, a seek bar, a speed button (0.75×–2×, remembered), and Text / Images toggles that show or hide the article text as karaoke (the whole article scrolls, the sentence being read is marked and the current word is highlighted; word timing is estimated from the MP3 position) and the article's current picture. Everything is a large touch target and keyboard reachable; the speed also applies to the playlist player. While you order, a panel pinned to the bottom-right of the window shows how many boxes are numbered and holds Save order, Undo last and Cancel (or press Esc). It stays in view however far you scroll, sits above the Back / Approve bar and clear of the page image, and turns green when every box is numbered. Save order is only enabled once you have clicked at least one box; on a phone the panel spans the width of the screen.

Expected result: the article plays from its headline to its final paragraph. Page furniture (running heads, page numbers), adverts, sidebars and pull quotes are never read aloud unless you explicitly include them in review.

Confidence, and what it means

Shown	Meaning
~90%	The contents page listed this article — title and start page are known.
~55%	Detected from a headline alone; check the boundaries carefully.
Low	No body copy found. Usually an advert or a section divider — reject it.

An article is never narrated until you approve it, whatever its confidence.

Podcast mode

Choose two or three voices as hosts. The configured LLM writes a discussion of that article for listeners who have not read it, and each host's turns are synthesised with their voice.

The prompt forbids inventing facts, figures or quotes that are not in the article; if the article reaches no conclusion the hosts say so. It is still a generated discussion, not the author's words — treat it as a summary, and read the original for anything that matters.

Podcast generation is refused for an article you have not approved, because unreviewed boundaries may include a neighbouring article or an advert.

What is wrong on this page, and fixing it automatically

Purpose: see at a glance what is wrong with a page and fix it without hunting for the right button. Steps: open a page in review. The What is wrong on this page panel lists each problem in plain language and marks it on the page: red dashed frame = printed text outside any box (never read); orange edge = a box edge cutting through text; purple dashed outline = two boxes over the same text; yellow dotted outline = words that look mis-read; red wavy underline (in the list) = words no dictionary knows. Each row has its own button (Find missed text, Fit boxes to the text, Verify OCR text, Fix with language model). Fix this page automatically does all of them in one go: fits boxes, adds an inset pull quote, cuts a paragraph that wraps around it, finds missed text, re-reads suspicious words and, when a language model is configured, fixes provable misspellings. Result: the page reloads with what was fixed; Undo (above the list) restores the page as it was. Overlapping boxes have no automatic fix: delete or merge one. Where an article ends: the last box says article ends only when the article is signed off ((rah) et) or a headline/deck/byline follows it (same page or top of the next). Otherwise it shows no end marker — link page N ›; click it to add the text of that page that carries the article on (Undo reverses it). Reading order: applied automatically after import, OCR again and Fix this page automatically; pages whose order you set by hand keep it (Automatic order releases a page). Text flow: green arrows and chips on the page show where the article carries on: an arrow to the next box below, a curved next column arrow, and a chip continues on page N › / ‹ from page N, plus article starts / ends. Tick or untick Show text flow to hide them. In the reading view a small marker (↓, col ›, p.N ›) sits at the word where a paragraph crosses a box, column or page. The markers are labelled for screen readers. Whole magazine: a fresh import now runs this automatically as its last step -- the magazine you open is already as fixed as the machine can make it. Auto-fix all pages (contents view, formerly Quality check / run) repeats it on demand (for instance after a manual box edit) and lists the pages that still need a look (purple badges). Errors: a failed fix shows the reason and changes nothing. Offline / privacy: the box fixes and the audit are local; the OCR re-read and spelling steps use only the engines you configured.

Colours in the article list: a blue row with a not reviewed pill is an article nobody has approved or rejected yet; a green edge means approved.

Undo and Redo

Purpose: take back a change (or put it back) without leaving review. Steps: use Undo / Redo in the sticky bar (at the left of its second row), or Ctrl+Z / Ctrl+Shift+Z (Ctrl+Y). The button tooltip names the change, e.g. "Undo: Deleted 2 regions". The last 20 recorded changes are kept per magazine: region edits and moves, drawing a region, approving/rejecting an article, page linking, auto-fix, reading-order changes, box clean-up and spelling corrections. Errors: a button stays disabled when there is nothing to undo/redo, or when something else has changed the magazine since (for example a whole-magazine run), because undoing then would roll that work back too. A new change ends the redo history. Privacy: the saved states live in the magazine's own undo/ folder; nothing is sent anywhere.

Less manual work: what happens automatically

At import (as its automatic last step, not a separate click any more), and whenever you press Auto-fix all pages: boxes are fitted, inset pull quotes found, wrapped paragraphs cut, continuation pages linked into the article running from the page before, missed text added, suspicious words re-read and (with a language model) provable misspellings fixed. The report then lists only the pages that need a decision about their boxes, with Start with page N; pages that only have words to check are collapsed and optional. Articles that gained pages go back to detected, so re-approve them (the batch tools in Select do many at once). A backup of the layout is kept. The ingest status bar keeps showing progress ("Checking page N of M: …") through this step, so a fresh import simply takes longer before it says done -- an Auto-fix failure (for example an unreachable OCR engine) is reported as an ingest failure rather than a silent gap, but nothing already imported is lost. When the automatic link misses: open the article in review and use Link to page N in the panel: Article continues there adds the text that belongs on that page (from the paragraph that carries the sentence on, up to the next headline), Article starts there adds the opening. Added text is ticked, so untick what does not belong. Undo reverses it.

Clean up boxes: fitting boxes to the text

Clean up boxes (review toolbar) also fits each text box to the ink of its text: a side that cuts through letters grows a little, empty margin is trimmed. Boxes you drew or resized are never changed; a backup of the layout is kept and the message reports how many boxes were fitted.

Inset pull quotes: a quote set into the text in a display colour is added as its own pull quote region (unticked, never read aloud) by OCR again (this page) and Clean up boxes. If a picture or infographic is picked up by mistake, delete the region or change its type.

One paragraph, one block — even across columns and pages

Purpose: a paragraph that continues into the next column or onto a later page is separate regions in the layout. Reading and the MP3 join them before splitting into sentences, so narration never stops mid-sentence at a seam. Prerequisites: none — this happens automatically for every approved article. How it works: consecutive body regions are joined when the first one does not end a sentence and the next one continues it (lower-case start, trailing hyphen or comma, or ending on an article/preposition/conjunction). A word split at the seam is closed up (jähr- + lich → jährlich); a real compound hyphen is kept (KI- + Modelle). Headings, interview turns and finished paragraphs are never glued together, and a caption or figure description between two fragments is moved after the paragraph. Result: the reading view and the exported MP3 speak the fused paragraph as one block; highlighting and "Original page" still follow the region each sentence started in. Errors: if two paragraphs are wrongly joined or a split is missed, correct the region text or reading order in review; the text is recomputed each time. Mobile / accessibility / offline / privacy: no extra controls; nothing leaves the machine.

Pronunciation & spelling (per article)

Open an article and expand Pronunciation & spelling under the player.

Acronyms — purpose: say NAS, ML or SSD the way a listener expects, in the article's language. The language is decided once for the whole article (a short fragment alone is a poor signal); an English quotation inside a German article is spoken with English expansions. Steps: unfamiliar acronyms are listed with the sentence they appear in. Type how the narrator should say one (empty = as printed) — the change applies immediately and stays with the article — or press Let the language model decide: it picks expansion, letter by letter or as a word from the sentence's context and, for English acronyms in a German article, prefers the established German term. Only expansions carry model-written words; letters/word choices are decided by the server. Known acronyms: a built-in list covers common German and English ones (KI, AI, LLM, API, GPU, USB → "U S B", HDMI, z. B. …). The displayed text is never changed.

Spelling — purpose: find OCR and typing errors in German and English text without ever rewriting names or technical terms by guess. What is flagged: a word unknown in the text's language, not a known compound (Softwareentwicklung), not known in the other language (an English term inside a German article is fine), not an acronym, not a name in mid-sentence English, and not a word you kept. A word that recurs three or more times is treated as vocabulary. Marked on the page: in review, flagged words are underlined in the region list and the Spelling button lists them for the page with suggestions. In the reading view the same list is under Pronunciation & spelling. Click a suggestion to correct the word in the region text (review offers Undo), or Keep to add it to this issue's dictionary. Fixed by an agent: Fix with language model (page or article) asks the configured LLM about each flagged word with its sentence. A correction is applied only if it is one of the dictionary's suggestions or a single known word within two edits of the printed one; names and terms the model keeps go into the issue's dictionary, everything else stays marked. The whole-magazine Quality check / run does the same for every page (when an LLM is configured) and lists pages that still have marked words. Errors: "No LLM model configured" — set one in Settings; the marked list still works without it. A stale suggestion ("the text has changed") — reload the list. Mobile / accessibility: the lists are ordinary buttons with labels ("Replace X with Y"); marks are underlined, not colour-only. Privacy: the agent sends only the flagged word and its surrounding sentence to the LLM you configured in Settings; without an LLM nothing leaves the machine.

EPUB with synchronised audio

Purpose. Take an issue to an e-reader or reading app that highlights the sentence being spoken (EPUB 3 Media Overlays).

Prerequisites. At least one approved article with generated audio. Only those are included, in contents order.

Steps. Open the magazine's contents and press EPUB with audio. The book downloads; open it in a reader that supports read-aloud overlays (for example Thorium Reader, Apple Books, or Readium-based apps).

Expected result. One chapter per article, a table of contents, the MP3s inside the file, and each sentence linked to its place in the audio. The file passes the W3C EPUBCheck (0 errors, 0 warnings on a real two-article, twelve-minute test).

How exact is the highlighting. Audio rendered after 2026-09-30 records where every sentence starts and ends, so the highlight is exact. Older audio has no such record: its sentences are placed by estimate, proportionally to their length across the real duration, so the highlight can drift by a sentence or two. The book's description states which it is; to get exact timings for an older article, regenerate its MP3.

Errors. No approved article with audio gives "No approved article has audio yet". Audio whose length cannot be read is skipped. Sidebars and figures are not part of the book.

Mobile / accessibility. The book is reflowable text, so text size and contrast are set in the reader. A screen reader reads the text directly; the overlay is an addition, not a replacement.

Offline. The file is self-contained. Privacy. It contains the magazine's text and your generated audio, so share it only where the magazine's licence allows.

Editing recognised text, and seeing what you changed

Purpose. Fix what OCR got wrong and always be able to see, and undo, what you changed.

Steps. In Review, click a region's text (or its pencil) and press Save text. A region you edited shows an Edited mark. Show changes opens a word-by-word comparison with the text as first recognised: words removed are struck through and marked with a minus, words added are underlined and marked with a plus (never colour alone). Restore recognised text puts the original back. Typing the original back yourself also clears the mark.

Expected result. The first recognised text is kept through any number of edits; reading the region again (Re-OCR) makes the new reading the original. Edits are reversible with Undo as before.

Errors. Empty text is refused (delete the region instead). Very long texts (over about 1,500 words) are compared as one removed block and one added block rather than word by word.

Mobile / accessibility. The buttons are real buttons with an expanded/collapsed state; the comparison is a labelled group that explains the minus/plus convention to a screen reader.

Privacy. The recognised text stays on the server with the magazine; nothing is sent elsewhere.

Find an issue online

Purpose. Pull a magazine issue into the app without leaving for a browser and uploading by hand.

Prerequisites. Internet access for the Internet Archive; for your own library, an OPDS catalogue (Calibre-Web, Kavita or Komga all serve one) added under magazine_opds_catalogs in the app settings as [{"name": "NAS", "url": "http://nas.local:8083/opds/"}]. Catalogues that need a login are not supported yet.

Steps.

1. Open Magazines. In Find an issue online pick a source, type a title or subject, press Search.
2. Read the licence line on each result. The source states it, the app does not judge it.
3. Press Import on a result. The PDF downloads (progress is announced under the search box), the magazine opens and ingestion starts, exactly as after an upload.

Expected result. A new magazine project with the PDF stored locally, then the normal review-before-narration flow.

Errors. A source that is down, rate-limiting or returns something other than a PDF gives a plain message under the search box and nothing is created that you must clean up beyond the empty project shown in your library. Lending-only Internet Archive items are never listed. Only one download runs at a time; a PDF larger than 400 MB is refused.

Mobile / accessibility. The form stacks on a phone; results are a list with labelled Import buttons; status text is a polite live region, so a screen reader hears "N results" and download progress.

Offline. Search and import need the network; everything after import works offline.

Privacy. Your search words go to the chosen source (archive.org, or your own catalogue). Nothing else is sent. Websites that redistribute commercial magazines without a licence are deliberately not supported.

Quality check / run (whole magazine)

Purpose: find every page where text is not inside a box, boxes overlap or cut off letters, or OCR still looks wrong. Prerequisites: the magazine has been ingested. A vision OCR engine (Settings) is optional; without it the word re-reading step is skipped and the result says so. Steps: on the contents screen press "Quality check / run" (first button in the toolbar) and confirm. Progress shows "Checking page N of M". Result: the run (1) adds text regions that independent OCR found outside every box (unticked, so nothing new is read aloud until you approve it), (2) re-reads suspicious words from the page image and only accepts a clearly better reading, (3) measures the page image for ink outside every box, overlapping text boxes, boxes whose edge (left, right, top or bottom) cuts through text, and articles that claim the same regions (the same text would be read twice). Pages that still need a look are listed as buttons under the toolbar; each opens that page in review. Errors: one page failing does not stop the run; it is listed as "check failed". The report is kept in the magazine's folder (quality_report.json) and served at GET /api/magazine/{id}/quality/report. Page colours and live indicator: in the thumbnail grid, pages the run found clean turn blue and pages with problems turn purple, whatever their review state (only a page whose every article was rejected keeps its grey). A purple warning badge with the problem count sits on the thumbnail; hover or focus it to read what was found, click it to open the page in review. The colour reflects the last run — run the check again after fixing pages. While the run is going, the page being worked on pulses and names its step (finding missed text / re-reading suspicious words / measuring box coverage), and finished pages show "✓ checked". Pulsing is disabled under reduced-motion. The same live indicator works for every batch step while the thumbnail grid is showing: reading pages (OCR), finding advertisements / recognising paragraphs during detection, fixing all figure boundaries, and rendering audio (the pages of the article being rendered pulse with "rendering audio n/total"). Advertisement pages: a page where detection found advertisement regions and no article text turns green with a dashed border on its own — nothing on it is read aloud and the quality check skips it. No approval step is needed; a page that mixes an ad with article text is treated as an ordinary page. Mobile / accessibility: the list is a labelled live region of ordinary buttons, keyboard reachable. Offline / privacy: the missed-text pass uses local OCR; the word re-read uses only the vision engine you configured. Nothing else leaves the machine.

Errors

What you see	What happened	What to do
"Upload the PDF first"	The project has no source.pdf.	Upload it, then ingest.
Ingestion failed	The PDF is encrypted or corrupt.	Check it opens in a viewer.
"Approve the article before generating a podcast"	Review gate.	Approve it first.
"No LLM model configured"	llm_model is empty.	Set it in Settings.
"LLM did not return usable JSON"	The model ignored the format.	Retry, or pick a stronger model.
"Article has too little text"	Under 200 characters — usually a stub.	Check the boundaries in review.
A figure box sits over the wrong part of the page	The OCR engine grounded the figure loosely.	Press "Fix figure boundaries"; if the graphic is too pale to detect, draw the region by hand.
"Fix figure boundaries" reports nothing corrected	Every box already matched its page, or none could be placed with confidence.	Nothing is wrong; correct any remaining box by drawing it.
"No vision OCR engine configured" (Describe)	vision_ocr_url/vision_ocr_model are empty.	Set a vision engine in Settings.
"The vision engine returned nothing usable for this figure"	The configured engine (and fallback, if set) returned an empty or degenerate response for this image. Some vision models are transcription-only and cannot produce open-ended descriptions at all, however the prompt is phrased — confirmed with a pure-OCR model that answers its own "Text Recognition:" prompt but returns nothing for any descriptive one.	Configure a genuinely caption-capable vision model as the fallback (vision_ocr_fallback_url/vision_ocr_fallback_model), or write the description by hand.
"Save & re-OCR" on an edited box leaves the old text in place	The corrected area produced an empty or unreadable OCR result — the same engine limitation that can affect figure descriptions applies here too.	Press Save to keep the corrected box position with the existing text, then correct the text by hand if needed, or try "OCR again (this page)" once the box position is saved.

Privacy

Ingestion, OCR and storage are entirely local to the container. Podcast mode is one exception: the article's text is sent to whatever LLM llm_url points at. Generating a figure description is the other: the cropped image is sent to whatever vision_ocr_url (and, on failure, vision_ocr_fallback_url) points at. If either is a hosted API rather than a model on your own network, that content leaves your machine. Narration uses your local TTS stack and sends nothing outward.

Accessibility and mobile

Sentence and word highlighting both respect prefers-reduced-motion (no smooth-scroll animation when it is set; the highlight itself is a colour change, not motion). Driving mode gives large, high-contrast controls (skip, ±15 s, play/pause, speed) — hide Text and Images for a bare screen — for use without looking at the screen — it does not, and should not, replace watching the road. Word-level highlighting can be switched off in the reading controls if it is more distracting than helpful; sentence highlighting keeps working either way. Keyboard navigation of the contents tree and review screen is not yet built.

Offline

Ingested magazines are stored server-side, so any device on the network sees the same library and reading progress. Playback needs the server; there is no offline cache yet.