Add _incoming/README.md and record the drop-folder decision in REQUIREMENTS

2026-10-18 01:34:58 -05:00
parent 53d21ea2e5
commit bbc99e9df6
2 changed files with 41 additions and 0 deletions
@@ -0,0 +1,29 @@
+# Drop a PDF here to get an audiobook
+
+**What you do**
+
+1. Put the PDF in this folder (`_incoming/`). In Gitea: open `_incoming`, choose **Add file > Upload file**, drop the PDF, commit to `main`.
+2. That is all. Nothing else to click, nobody to ask.
+
+**What happens next (automatic, no bot)**
+
+A job on the 5060 machine reads the PDF, cleans the text, finds every chapter, writes the narration script and the license note, speaks every chapter in the locked voice (Michael, Chatterbox), builds one MP3 per chapter plus opening credits, closing credits and a retail sample, checks every file against the Audible/ACX numbers, and commits the finished book back to `main`. The PDF moves out of `_incoming/` in that same commit.
+
+**Where the audio appears**
+
+`books/<author-surname-first>/<book-title>/audio/` (one MP3 per chapter, credits, retail sample, `run.log` with the ACX check table).
+Next to it: `text/`, `script/`, `figures/skipped_figures.md`, `book.json`, `warnings.log`, `LICENSE_STATUS.md`, and the PDF.
+Example: `books/clark-glenn/the-man-who-tapped-the-secrets-of-the-universe/audio/`
+
+**How to see progress**
+
+Open the repo's **Actions** tab (https://gitea.vps1.afterthedemo.com/Ty_Tech/old-books/actions). The run named `audiobook` is yours. Green = finished and committed. Red = it stopped, and the log says which step failed and why. A red run commits nothing and leaves the PDF here; fix the cause, then push anything that touches the PDF again, or use **Run workflow** on the Actions page and give it the PDF path.
+Long books take hours. About 1 hour of audio takes about 30 minutes to render.
+
+**Good to know**
+
+- Title and author are read from the PDF. If the PDF has no "By <Name>" line, the file name `Some Title - by First Last.pdf` is used. If neither works, the run fails and says so; then add a small file next to the PDF with the same name and `.json`, for example `my-book.json` containing `{"title": "My Book", "author": "First Last"}`.
+- Scanned pages with no text layer are OCRed automatically. OCR mistakes are listed in `warnings.log`.
+- Dropping the same PDF again skips audio that already exists.
+- License status defaults to unknown and never blocks anything. Nothing is published anywhere outside this repo.
+- Summaries (chapter preview, chapter-end summary, mid-chapter summary) are off. Turn them on per book in `book.json` under `summaries`.
@@ -125,3 +125,15 @@ Status: stack items 1-5 agreed by Ty; items 6-8 follow from his standards (ACX s
 ## Approved to proceed (2026-10-17 10:25 AM PT, Ty by voice call)
 - (C) 39 GB free on / is enough. Proceed on ubudual5060: decommission GPU1 model (save unit file exactly), Docker stack with pipeline and runner together, restart always. Voice loads on demand and unloads when idle. Mac mini is out. Build the pilot (Clark Chapter I) with chime-plus-spoken-label cues, summaries off by default, LICENSE_STATUS.md default unknown.
 - Asked congfbot for GPU1 decommission and Docker set-up. Text stages and pipeline code in progress.
+
+## Voice locked for MVP (2026-10-17 2:42 PM PT, Ty: "Lock in on B for MVP")
+- (C) Engine Chatterbox (original), stock voice Michael.wav, native route POST /tts. Settings: exaggeration 0.25, cfg_weight 0.20, temperature 0.6, seed 7, split_text true, chunk_size 240. Source clip: /workspace/tuning8/B-michael-ex025-cfg020-chunk240.mp3, 21.55 s for paragraph 3.
+- (C) Never use speed_factor: the server time-stretches after generation (log: librosa.effects.time_stretch) and ruins the sound. Never use pitch shifts, voice conversion, or per-phrase pause injection. Cadence comes only from the engine's own settings.
+- (C) Ty's own narrated voice is post-MVP. Ty expects me to be the expert on any tool I recommend: read its docs and code first.
+- The OpenAI-style route /v1/audio/speech ignores exaggeration, cfg_weight and temperature on this server, so the pipeline uses /tts.
+
+## Drop-folder pipeline, no bot in the loop (2026-10-17, Ty)
+- (C) Ty drops a PDF into `_incoming/` in Ty_Tech/old-books and commits it. Deterministic Gitea Actions jobs on the runner (ubudual5060-old-books) do everything: ingest (OCR only for pages without a text layer), structure, clean-up, figures list, script, license, voice, assemble, ACX check, then commit the finished book folder (PDF moved out of `_incoming/` to `books/<first-author>/<book>/`, with text/, script/, figures/skipped_figures.md, audio/, book.json, warnings.log, LICENSE_STATUS.md) back to the branch. No agent runs any step.
+- (C) One command does a whole book: `python3 _pipeline/cli.py process <pdf>`. It fails with exit code 1 and a clear message if any step or any ACX check fails. Warnings are logged, there is no per-book approval gate. Re-running skips audio that already exists unless the script or voice settings changed or `--force` is given.
+- (C) One book at a time (workflow concurrency group). A failed run commits nothing and leaves the PDF in `_incoming/`. The commit-back is a single commit marked `[skip ci]` that also removes the PDF from `_incoming/`, so it cannot start another run.
+- (C) The voice endpoint is a setting (`voice.endpoint`, env `AUDIOBOOK_VOICE_ENDPOINT`, repo variable `AUDIOBOOK_VOICE_ENDPOINT`), default in CI `http://192.168.1.202:8090/tts`. Locked voice settings are unchanged. Never publish anything outside the repo.