Skip to content

Commit 78a8240

Browse files
committed
docs: add audiobook publishing design spec
1 parent 558728f commit 78a8240

1 file changed

Lines changed: 114 additions & 0 deletions

File tree

‎AUDIOBOOK_ARCHITECTURE.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
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

Comments
 (0)