Launch voice

Tool manual under launch-film. Start at skills/launch-film/SKILL.md: it holds the core, the hook-plus-body template and the lessons. Where this page differs, launch-film wins.

In a modern launch film the voice leads and the picture illustrates it word by word: when the voice says "tagged", something gets tagged. That only works when every word has a timestamp.

Providers

• Default: Higgsfield on your own account. text2speech_v2 (engines elevenlabs, minimax, seed_speech, and others per voice) for casting across about 100 preset voices, about 0.3 credits a line. Seed Audio for a narrator you steer with a prompt and audio references. scripts/hf_voice.py wraps the CLI.
• Free scratch voice: scripts/scratch_voice.py makes placeholder takes with macOS say (or espeak-ng on Linux). Build and time the whole film on it, label every review "scratch voice", then swap the real takes in.
• Free local clone: scripts/clone_local.py (Chatterbox, MIT) clones your approved narrator from 8 to 10 s of their lines. A stand-in, not a master. Only clone a voice you have the rights to.
• ElevenLabs direct (paid plan with a commercial licence): the cleanest way to add new lines in an approved narrator's voice. Make an Instant Voice Clone from about 60 s of the narrator's own approved lines (only a voice you have the rights to). The free plan has no commercial licence, so never use it for a published film. Keep the API key in your secret manager or environment, never in the repo.
• Review voices inside a full film, never as loose clips. Keep a list of rejected voices so they are never proposed again.

New lines in an approved narrator's voice

When the copy changes after the narrator is approved, keep every existing take and add only the new lines. A new line in a different voice is a regression, even when it is clear.

• Clone settings that held up: eleven_v4 at stability about 0.7 and similarity about 0.9, no audio tags, each line generated with its neighbours as previous_text and next_text so it is read in context.
• Pick by speaker similarity, not by ear alone. Generate several takes, score each against the narrator's own lines with a speaker-embedding model (for example SpeechBrain ECAPA); the narrator's own lines score highest, and the best clone takes come close. Then pace the winners in post to the narrator's measured syllables per second.
• Energy means pace, not pitch. "More energy" is a deeper, faster, gapless read, not a higher, excited one. Tags like [excited] raise the pitch without changing the pace.
• A hook of short phrases: read alone, a clone lifts short phrases well above the narrator's pitch and can mishear names. Read the whole hook as 1 request (respell a name it gets wrong), pace it, then cut it into its phrases at the silences and place each on its moment. If it still sits high, lower it with a PSOLA pitch shift that keeps the formants (Praat via parselmouth) and re-check the speaker match. Write the aligned word times to a file the film's pages read, so every cut follows the voice.

Casting

1. python3 skills/launch-voice/scripts/hf_voice.py cast "<the film's opening line>" film/vo/audition speaks the line with every preset voice (about 34 credits for about 110 voices), checks each take with whisper, and measures pace and pitch movement. ranking.md lists exact takes first, nearest 2.5 words a second and about 2 semitones of movement (conversational, not announced). --only Name,Name recasts a few.
2. Take the top 6 or so across genders into the full script (hf_voice.py lines), then fit them (below). A voice that needs more than 12 % speed-up to fit is too slow for the script: drop it or cut words.
3. Build a full film per surviving voice and let the owner pick. ElevenLabs takes varied least in pace and pitch in our tests, so it is the default engine.

Length and pace

• Target 2.2 to 2.7 spoken words a second. A strong reference launch ran 2.4 (151 words in 63 s).
• A 20 s film carries about 45 words; 30 s about 70; 60 s about 140. Cut words before you speed the voice up.
• One line per storyboard frame, 6 to 20 words, phrased so the key noun or verb falls on a beat.

Procedure for the film template

1. The script lives in film/film.json lines. Record 1 file per line into film/vo/body/line-<id>.wav: real takes with hf_voice.py lines (write the lines as {"lines": [{"line": "02", "text": "..."}]}), or scratch takes with python3 skills/launch-voice/scripts/scratch_voice.py film/film.json (add --hook film/hooks/<name> to voice a hook line too).
2. Run python3 skills/launch-voice/scripts/prep_lines.py film/film.json (--align force to insist on forced alignment; with uv installed it fetches torch on the first run, about 2 GB). It writes film/vo/body/lines.json with each line's duration and word times: forced alignment when torch is available, else whisper.cpp, else an even estimate flagged estimate.
3. film/build.py places the lines on the film timeline and every picture cue follows its word. A new take is 1 prep run plus a rebuild.

Procedure for a free-form film

1. vo/script-lines.json ({"lines": [{"line": "01", "text": "..."}]}), then one file per line: hf_voice.py lines vo/script-lines.json vo/takes/<voice> --voice <Name>. Text, voice, engine and job ids land in lines.json.
2. Fit: python3 skills/launch-voice/scripts/fit_lines.py vo/placement.plan.json vo/takes/<voice> vo/versions/<voice>. The plan gives each line its earliest start, its breath gap and, where a frame must end, end_by. Pauses over 0.25 s inside a line shrink to 0.22 s; a run of lines that still overflows is sped up as one, capped at 12 %. Then stitch: python3 skills/launch-voice/scripts/stitch.py vo/versions/<voice>/placement.json vo/versions/<voice> vo/versions/<voice>/vo.wav.
3. Word times per line. For anything a visual must land on, use forced alignment: uv run -q --with torch --with torchaudio --with soundfile python skills/launch-voice/scripts/force_align.py line.wav "the exact words". For a quick read, align_lines.py runs whisper.cpp line by line. Anchors resolve in speaking order (each the first match after the previous one), so any voice re-times the film. A single whisper pass over the whole film drifts near line ends; per-line passes do not.
4. Hand the word times to launch-motion (anchor each build to its word) and launch-sound (events follow words).

Vintage narrator

For an archival or documentary opening: python3 skills/launch-voice/scripts/vintage.py IN.wav OUT.wav --crackle crackle.wav band-limits to 150 Hz to 5.8 kHz, adds tape saturation, a slow wow and a real vinyl crackle bed (generate 1 with Seed Audio). Seed Audio can also speak a line in a vintage narrator voice directly ("a warm, deep 1960s documentary narrator on an old vinyl record ... exactly these words: ..."); it reads slowly and may rephrase ("gotta" became "got to"), so check with whisper.

Sync rules

• A key word lands with its visual within 2 frames. Start builds on the word's first frame; if you let a visual lead its word, keep it under 4 frames and do it everywhere.
• Let the voice breathe at scene changes: 0.25 to 0.5 s between lines.
• The last line ends at least 1 s before the logo; the logo gets its own near silence (launch-mix drop-out).

When the voice provider is unavailable

Build against the scratch voice, label every review as scratch, and keep the picture anchored to the aligned words, so swapping in the real voice is 1 prep run plus a render. Never switch voice providers or accounts without the owner's go.

Fixes

• A line runs long by under 5 %: ffmpeg -af atempo=1.04. More than that: rewrite the line.
• A word is mispronounced: respell it phonetically in the line's say field (for hf_voice.py), never in the script.
• Whisper mishears a soft ending: use forced alignment or shorten the anchor prefix; do not re-record.
• Digits: spell them out in the text you align ("twenty four", not "24").
• The whisper base model mishears product names. Check final words with the small model or larger (WHISPER_MODEL).