Machine Build Manual — Volume 3: The Voice
GOAL Investment Inc. · INSURED · BONDED · VERIFIED · EST. 2007
A production guide for the voice layer of a local-first machine fleet. Volume 1 covered architecture, Volume 2 the build. This volume covers narration: the media node, speech synthesis, chunking, assembly, publishing, and the release checks that keep private information out of a public recording.
How to use this volume
This volume assumes Volumes 1 and 2 are complete: you have a working media node, a model server, a secure transfer path and a credential vault. Placeholders still look like <MEDIA-IP>.
One warning before you start. Audio is the least reversible thing you will publish. A typo in a web page can be corrected in a minute; a name read aloud in the wrong place is already in someone's download folder, someone's car, and someone's phone. Part 7 exists because of that.
Part 1 — What the voice layer is for
Four commercial uses, in the order they pay for the build:
- Published audio books. Narration of published work, whether sold or distributed to your community.
- Product narration. Short spoken updates for products, pitch decks, and dataset briefs.
- Training course audio. Guided lessons pushed to the knowledge node for students and staff.
- Spoken status briefings. The machine reporting its own condition to a person who is driving.
The topology
Keep voice work on one node and let the other nodes ask for it. One node owns synthesis, manuscript processing, and assembly; the others request output, they do not each build their own pipeline. That is the "one owner per domain" rule from Volume 1, applied to sound.
Rate and pitch are configuration, not code. A slower read (around 0.85x) suits instructional material; a faster read (around 1.15x) suits summaries. Make it a parameter you set per job.
Part 2 — Choosing a synthesis service
You are choosing three things: quality, output format, and how gracefully it fails.
Quality tiers. Most providers offer a standard and a higher fidelity tier. Standard is usually 24 kHz mono; the higher tier is often 44.1 kHz. Voice quality differences are audible on a good speaker and rarely audible on a phone. Pick standard for bulk work and high fidelity for product you are selling.
Voice profiles. Providers publish a small set of named voices with distinct character. Assign them by job, in writing, and never by mood:
| Character | Sound | Give it |
|---|---|---|
| Female executive | Warm, clear, crisp | Audio books, briefings, courses (primary) |
| Neutral, direct | Balanced, systematic | System status, telemetry reports |
| Male narrative | Warm, explanatory | Case studies, technical background |
| Male storyteller | Expressive, dynamic | Fiction, saga readings |
| Deep male | Authoritative, grave | Critical alerts, security warnings |
| Bright female | Energetic, clear | Product demos, onboarding guides |
Two voices per domain, one named as the fallback. When a voice is retired by the provider, the fallback is what saves your catalogue from sounding broken while you re-record.
Sample text is your contract. Before you narrate a 300-page book, synthesize the first page and listen to it. Every naming problem you will ever have with generated speech - a surname, a town, a part number - shows up in the first page.
Part 3 — Credentials
Non-negotiable, and the same rule as Volume 2:
- The key lives in an encrypted environment variable on the media node, read by name at runtime.
- It is never written into the source file, a document, a log, or a chat message. If you paste a key into a chat, consider it burned and rotate it.
- The same key is not copied across every node. One node holds it; the rest ask that node.
- A 401 means the key is wrong or missing. A 429 means the quota is exhausted or you are going too fast. They are different problems with different fixes, and neither is fixed by retrying harder.
Part 4 — The audio book pipeline
Four stages, each independently checkable.
4.1 Chunking the manuscript
Synthesis requests have a length limit, so the manuscript is split. Split on paragraph boundaries, never mid-sentence, and keep each chunk a few thousand characters. A cut in the middle of a sentence is audible; a cut between paragraphs can be made seamless with padding.
def chunk_text(text, limit=3500):
chunks, current = [], ""
for para in text.split("\n\n"):
if len(current) + len(para) + 2 <= limit:
current += para + "\n\n"
else:
if current.strip():
chunks.append(current.strip())
current = para + "\n\n"
if current.strip():
chunks.append(current.strip())
return chunks
Write the chunk list to disk before you synthesize anything. When a run dies at chunk 94 of 174, that list is the difference between a resume and a restart.
4.2 Batch generation with backoff
Generate one chunk per request, and treat the provider as unreliable even when it is healthy:
- Retry with exponential backoff on 429 and on network errors. Start around two seconds and double.
- Cap the retries. A chunk that fails five times is a fail you record, not a loop you leave running overnight.
- Write each chunk to its own file, named by index, and never overwrite a file that already exists and is non-zero. Resuming is then automatic.
- Record progress in a small JSON file: last chunk completed, successes, failures, characters used. An unattended run with no progress file is a run you will repeat from the beginning.
4.3 Assembly
Concatenate the chunks in index order, with a short silence between them - a few hundred milliseconds is enough to separate chapters, and too much makes the recording feel stalled. Then write the metadata: title, author, album, track, and a cover image. A file without tags looks broken in every player, even when the audio is perfect.
Loudness is worth normalising while you are here. Around -16 LUFS plays consistently across phones, cars and laptops; without it, one chapter is quiet and the next is loud.
4.4 Verify the join
Before publishing, check the assembled file the way you check anything else in this fleet:
- The file exists and is non-zero.
- Its duration is plausible against the word count. (Roughly 150 spoken words per minute; a 20,000 word volume landing at 6 minutes means the chunks did not all make it.)
- Chapter count in the audio matches chapter count in the manuscript.
- Seek to three random points and listen for five seconds each. A repeated sentence at a chunk boundary is the single most common assembly defect, and it is inaudible on a skim.
Part 5 — Product narration and course audio
Product narration. Short, 2 to 5 minutes, one voice, no music. Write for the ear: short sentences, no parentheses, no acronyms you have not said aloud once. Read it aloud yourself before you synthesize it - if you stumble, so will the voice.
Course audio. Build lessons from a fixed structure so students can navigate by ear:
- Module intro, about 30 seconds
- Core instruction, 3 to 5 minutes
- Practical exercise brief, about 1 minute
- Module summary, about 30 seconds
Name the files predictably (module-01/lesson-01-intro.mp3) so a course player can be generated from the folder listing. Add a standard opening and closing bumper to every lesson, and normalise the loudness so a student does not reach for the volume between lessons.
Moving audio between nodes. Push finished course audio from the media node to the knowledge node over SSH with key authentication, and verify by checksum on arrival. Do not leave key authentication as "probably set up" - prove a passwordless connection from the media node to the knowledge node before you automate anything.
Part 6 — Troubleshooting
| Symptom | Usual cause | Action |
|---|---|---|
| HTTP 401 | Key missing, wrong, or revoked | Check the environment variable by name; rotate the key |
| HTTP 429 | Rate limit or exhausted quota | Back off, slow the batch, check the account's remaining allowance |
| Socket timeout | Network or provider slowdown | Retry with longer backoff; do not shorten the timeout |
| Clipped or truncated chunk | Request cut at the provider | Regenerate that chunk alone; compare duration to neighbours |
| Volume varies between chapters | No loudness normalisation | Normalise the assembled file |
| A sentence repeated at a boundary | Overlapping chunks | Re-chunk on paragraph boundaries and re-assemble |
| Silent gaps or a missing chapter | A failed chunk was never regenerated | Check the per-chunk file list for missing or zero-byte indices |
| Two voices or echoes | Two generation processes running | Add a single-instance lock, as in Volume 2, Part 7 |
Part 7 — Before you publish: the release check
This is the part most builds skip, and it is the part that keeps a company out of trouble.
Text that you would never publish gets into audio easily, because the manuscript was written for internal use and the voice reads exactly what it is given. Internal specifications read aloud become public specifications the moment the file plays on a web page.
Run three checks on every recording before it goes anywhere.
1. Scan the script, not just the audio. Grep the manuscript for anything that must not be public: personal names, staff names, email addresses, phone numbers, account or user names, server names, private network addresses, file paths, keys, and anything that identifies a customer.
grep -niE "([0-9]{1,3}\.){3}[0-9]{1,3}|@|user(name)?|[A-Za-z]:\\\\|/home/|/Users/|pass(word)?|token|key" manuscript.md
2. Transcribe the finished audio back to text and scan the transcript. This is the only check that catches what the voice actually said, including the parts you thought were only in the appendix. Transcribing a 48-minute file is cheap; discovering your real name and your internal addresses in a public recording is not.
# transcribe, then run the same grep against the transcript
whisper audio.mp3 --language en --output_format txt
grep -niE "<your-real-name>|([0-9]{1,3}\.){3}[0-9]{1,3}|ftp|credential" audio.txt
3. Confirm what is actually reachable. A link removed from a page is not the same as a file removed from the server. Test the URL, not the page. If the file still answers 200, it is still public.
Two rules that follow from those checks:
- Separate internal architecture from public education. A specification of your own fleet - addresses, hostnames, credentials, inventory - is an internal document. A manual that teaches someone to build their own is a different document with the same subjects and none of your specifics. Write the second one deliberately; it does not appear by deleting a few lines from the first.
- Nothing gated is secret. Anything that plays in a browser can be downloaded. Treat a public audio file as a press release.
The three volumes together
Volume 1: the architecture and the rules. Volume 2: the build. Volume 3: the voice.
A complete build ends with a fleet that can wake itself, inspect itself, decide what to do, do it, prove it, record it, and tell a person what it found - without asking permission for any of it, and without ever saying anything in public that should have stayed on your own network.
One Fix.
GOAL INVESTMENT INC.