# 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. Confirm the boundaries, exclude a
   sidebar you do not want read, correct the title, then **Approve**.
4. **Listen.** An approved article can be narrated with the default voice, or
   sent to podcast mode.

**Expected result:** the article plays from its headline to its final paragraph.
Page furniture (running heads, page numbers), adverts and pull quotes are never
read aloud.

### 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

To be completed with the P1 interface. Planned: keyboard-navigable contents
tree and review screen, sentence highlighting that respects
`prefers-reduced-motion`, large touch targets for playback, and a driving mode
that advances images without requiring interaction.

### 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.