mARTin-B78
85080f4b82
Some checks are pending
Test and SonarQube / quality (push) Waiting to run
Ingestion now streams each page's image and recognised text into a
console-styled preview panel (Baidu Unlimited-OCR demo style) as pages
finish, instead of a bare progress bar -- raw text is written to a
per-job ingest_preview.json file since the background-job result field
strips text-like keys for data minimization.
Split-screen review boxes and their matching list rows now show a
centred icon for the region's kind and, when a region on a shared page
belongs to a different article, a badge naming that article, so a
claimed region is never mistaken for unclaimed text.
Added a "Draw it" mode: click-drag a box directly on the page image to
add a region the layout engine missed, as typed/OCRed text or as a new
figure (add_manual_region, POST /api/magazine/{doc_id}/pages/{page}/regions).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
128 lines
6.3 KiB
Markdown
128 lines
6.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. While it runs, a live preview shows each page's
|
|
image next to its recognised text as soon as that page finishes, so you can
|
|
see ingestion actually working page by page instead of watching a bare
|
|
progress bar.
|
|
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 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. 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.
|