|
| 1 | +# Audiobook Publishing Design |
| 2 | + |
| 3 | +> Human-in-the-loop design checkpoint for adding an optional audio edition to the existing book. |
| 4 | +
|
| 5 | +## Objective |
| 6 | + |
| 7 | +Publish a useful audiobook without turning audio production into a release constraint for the written book. Text remains the canonical edition. Audio is a manually produced derivative that may be incomplete or temporarily lag behind the text. |
| 8 | + |
| 9 | +## Scope |
| 10 | + |
| 11 | +- **Initial pilot:** `prompting-101.mdx`. |
| 12 | +- **Book release:** introduction, nine chapters, and About in the order defined by `website/chapters.ts`. |
| 13 | +- **Deferred:** `website/developer-tools/` as optional appendices. |
| 14 | +- **Narration:** one primary narrator using `gemini-2.5-pro-preview-tts`. |
| 15 | +- **Delivery format:** MP3 files served with the GitHub Pages website. |
| 16 | + |
| 17 | +## Decisions |
| 18 | + |
| 19 | +1. `website/docs/*.{md,mdx}` remains the canonical book; `website/chapters.ts` remains its ordering authority. |
| 20 | +2. Audio does not need to update in the same commit as text. Missing or stale audio is acceptable. |
| 21 | +3. Gemini generation happens only in a human-operated environment. It can take time, costs tokens, and requires credentials that are unavailable to CI. |
| 22 | +4. Long chapters may be generated in smaller working sections to limit model drift. The working files are assembled and encoded locally into the final MP3. |
| 23 | +5. A human listens to the exact final MP3 before committing it. The commit is the acceptance record; there is no separate approval system. |
| 24 | +6. Final MP3s are committed directly to the repository. WAV files, Git LFS, manifests, content hashes, and hash-addressed storage are unnecessary. |
| 25 | +7. Files use stable, human-readable chapter paths, for example: |
| 26 | + |
| 27 | + ```text |
| 28 | + website/static/audio/introduction.mp3 |
| 29 | + website/static/audio/how-llms-work.mp3 |
| 30 | + website/static/audio/prompting-101.mp3 |
| 31 | + ``` |
| 32 | + |
| 33 | +8. The existing website build bundles whichever MP3s are committed. CI does not generate audio, verify text/audio synchronization, or require a Gemini API key. |
| 34 | +9. Audio cross-references use chapter titles rather than numbers because numbering currently differs between ordering metadata and prose. |
| 35 | + |
| 36 | +## Repository impact |
| 37 | + |
| 38 | +### Add |
| 39 | + |
| 40 | +- Committed chapter MP3s under `website/static/audio/`. |
| 41 | +- A small local generation workflow or script for Gemini calls, chapter assembly, and MP3 encoding. |
| 42 | +- Versioned production guidance for the narrator, model, director prompt, pronunciations, and encoding settings. |
| 43 | +- An optional audio-player association for each chapter that currently has an MP3. |
| 44 | + |
| 45 | +### Change |
| 46 | + |
| 47 | +- Adapt figures, interactives, tables, prompts, and substantial code into concise spoken explanations during audio production. |
| 48 | +- Show audio controls only where a committed chapter file exists. |
| 49 | +- Disclose that the audio edition may lag behind the written edition. |
| 50 | + |
| 51 | +### Remove |
| 52 | + |
| 53 | +- Nothing from the canonical book. |
| 54 | +- From narration only: raw URLs, decorative visual detail, exhaustive reference data, and line-by-line code syntax. Essential meaning stays in the narration; full detail remains on the website. |
| 55 | + |
| 56 | +## Production workflow |
| 57 | + |
| 58 | +1. Choose a chapter whose current text is worth recording. |
| 59 | +2. Prepare narration from the chapter, translating visual and reference-heavy material into spoken meaning. |
| 60 | +3. Generate manageable sections with Gemini in a credentialed local environment. |
| 61 | +4. Assemble the selected sections and encode the chapter as MP3 using the documented settings. |
| 62 | +5. Listen to the exact final MP3 end to end, correcting generation, joins, pronunciation, pacing, or encoding issues as needed. |
| 63 | +6. Save it at the chapter’s human-readable path and commit it with any related player metadata. |
| 64 | +7. Regenerate it later when the value of updating it justifies the time and model cost. |
| 65 | + |
| 66 | +Temporary generations and rejected candidates stay outside the repository. The committed MP3 is the durable result of the expensive generation and listening work. |
| 67 | + |
| 68 | +## Website deployment |
| 69 | + |
| 70 | +The ordinary Docusaurus/GitHub Pages pipeline handles audio as static content: |
| 71 | + |
| 72 | +```text |
| 73 | +committed website/static/audio/*.mp3 |
| 74 | + -> existing website build |
| 75 | + -> GitHub Pages artifact |
| 76 | + -> browser audio player |
| 77 | +``` |
| 78 | + |
| 79 | +The deployment performs no TTS generation and needs no Gemini credentials. A clean checkout already contains every audio byte it can publish. Chapters without committed audio remain fully usable as written content. |
| 80 | + |
| 81 | +## Consistency model |
| 82 | + |
| 83 | +Audio is eventually consistent with the book by design: |
| 84 | + |
| 85 | +- a text-only commit is valid; |
| 86 | +- an audio-only update is valid; |
| 87 | +- an old MP3 may remain available after its chapter changes; |
| 88 | +- a chapter may have no MP3; |
| 89 | +- Git history records every published audio revision; |
| 90 | +- the deployed commit identifies the exact MP3 bytes served by GitHub Pages. |
| 91 | + |
| 92 | +This project favors low maintenance and incremental community contribution over continuous audiobook completeness. |
| 93 | + |
| 94 | +## Pilot acceptance criteria |
| 95 | + |
| 96 | +The `prompting-101.mdx` pilot is complete when: |
| 97 | + |
| 98 | +- its visual, code, table, and prompt content has an understandable spoken treatment; |
| 99 | +- the exact final MP3 has been listened to end to end; |
| 100 | +- the MP3 is committed at `website/static/audio/prompting-101.mp3`; |
| 101 | +- the chapter exposes a working browser audio player; |
| 102 | +- the normal GitHub Pages build serves the MP3 without Gemini credentials; |
| 103 | +- missing audio for every other chapter has no effect on the site build or reading experience. |
| 104 | + |
| 105 | +## Open implementation decisions |
| 106 | + |
| 107 | +- [ ] Choose the voice, director prompt, pronunciation guidance, and MP3 encoding settings. |
| 108 | +- [ ] Choose the local generation and chapter-assembly tooling. |
| 109 | +- [ ] Choose the chapter audio-player metadata and UI. |
| 110 | +- [ ] Choose the wording and placement of the audio-edition freshness disclosure. |
| 111 | + |
| 112 | +## Implementation checkpoint |
| 113 | + |
| 114 | +- [ ] **Proceed with the `prompting-101.mdx` pilot using this design.** |
0 commit comments