mARTin-B78
813e06c914
Magazine P1:
- Images shown automatically during playback (assign_images_to_articles
links each figure to the article whose column it falls in; the client
shows the last image reached in reading order as playback advances).
- "Play all articles" queues every approved article and advances
automatically at the end of each rather than stopping.
- Word-level highlighting, explicitly documented as an ESTIMATE (no
forced-alignment/timestamp source exists): each word's share of the
sentence's real measured audio duration is proportional to its
character length. A checkbox turns it off; sentence highlighting
(measured, not estimated) is unaffected.
- Driving mode: full-screen overlay, two oversized controls, reuses
whatever is already playing/queued.
- Sidebars/pull-out boxes excluded from narration automatically
(mark_sidebars: an anomalously narrow column vs. the page's regular
grid). Fixed a real defect found while building this: a full-width
headline was left in the column-width analysis and could bridge two
genuinely separate columns into one, hiding a real sidebar column
entirely -- caught by a failing test before the fix.
Second OCR engine + fallback ladder:
- KDL Frontier Parser nano wired in via vision_ocr_page_chain (ordered
engine list, first usable result wins, tesseract last resort).
Confirmed live: ~3x faster than Baidu (~12s vs ~40s/page) but returns
plain text with NO coordinate markers, unlike Baidu's labeled regions.
_whole_page_region treats the whole response as one ambiguous
full-page block (gated by ocr_quality_score) rather than discarding
usable text just because it lacks layout structure.
OCR engines page + a real UI bug:
- The OCR & Document Parsing page had no .s-engines-page[data-page="ocr"]
markup at all -- renderLocalContainers already supported an OCR grid
generically, but $('dc-grid-ocr') was always null, so the card grid
silently never rendered. Added an Active OCR Engine panel mirroring
Active Language Model exactly, plus the Local grid -- both configured
engines now appear as ready-made cards, no "Add Custom" dialog needed.
- Fixed the audiobook pipeline's "Previous/Next" nav bar bleeding into
every .section-head in the document (confirmed live on the Engines
page: a "Cast Audiobook" button and "STEP 1/8" hint that made no sense
there). Changed from a blocklist (naming each unrelated section as
noticed) to an allowlist of the pipeline's three actual destinations.
Verified live end-to-end: play-all queue building and manual advance,
word-span markup, driving-mode toggle, OCR page showing both engines as
local cards, zero stray nav bars on the Engines page, no console errors.
20 new backend tests (156 total in the magazine module).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
114 lines
5.3 KiB
Markdown
114 lines
5.3 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 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).
|
|
- 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.
|
|
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. Sidebars and pull-out boxes are
|
|
already unticked for you — tick one back in if you actually want it read.
|
|
Confirm the boundaries, correct the title, then **Approve**.
|
|
4. **Listen.** An approved article can be narrated with the default voice, or
|
|
sent to podcast mode. 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. **Driving mode**
|
|
(the button next to the article title) switches to two large controls and
|
|
nothing else, for listening without looking at 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.
|
|
|
|
### 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. |
|
|
|
|
### Privacy
|
|
|
|
Ingestion, OCR and storage are entirely local to the container. Podcast mode is
|
|
the exception: **the article's text is sent to whatever LLM `llm_url` points
|
|
at.** If that is a hosted API rather than a model on your own network, the
|
|
article 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 two large, high-contrast controls
|
|
(skip, play/pause) with nothing else to interact with, 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.
|