Machine Build Manual

Volume 3
The Voice

Narration, production and release. Speech synthesis, chunking, assembly, publishing, and the checks that keep private information out of a public recording.

INSURED · BONDED · VERIFIED · EST. 2007
Volumes: 1 — The Foundation2 — The Build3 — The Voice

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:

  1. Published audio books. Narration of published work, whether sold or distributed to your community.
  2. Product narration. Short spoken updates for products, pitch decks, and dataset briefs.
  3. Training course audio. Guided lessons pushed to the knowledge node for students and staff.
  4. 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:


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:

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:


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:

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:


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.