Papercut voice
Every later stage needs two things in the narration folder: voice/final_narrator/<id>.wav (one WAV per script line) and timing_narrator.js (a start and end for every word). This skill produces them by one of three paths, then builds the captions and the scene plan. The full reference for the scripts is $MOTION_LIB/core/voice/README.md.
Preflight
- Library:
$MOTION_LIB, else theMOTION_LIB=line in~/.config/motion-explainer/config.env, else ask once. Export it, and. "$MOTION_LIB/env.sh"loadsASR_PY,QWEN_TTS_PYand the other config values into the shell. - A scaffolded project (
motion-build, step 1) withnarration/script.jsonandvideo/episode.jsonholdingscenes.new_episode.shcopiesbuild_timing.pyintonarration/. - If the user already has a TTS installed, use it as it is and don't rebuild it (path B, or A if it is Qwen3-TTS). Ask once which one and where it runs. Otherwise ask which path, and say what it needs:
| Path | Needs | Install mode |
|---|---|---|
| A. Local Qwen3-TTS | the voice venv from $MOTION_LIB/core/voice/setup_tts.sh (model download 2.3-4.2 GB) | Full |
| B. Your own recording or another TTS | an ASR backend (mlx-whisper or faster-whisper) and librosa + numpy for the pitch pass, in the Python that ASR_PY and QWEN_TTS_PY name | Full, or those packages by hand |
| C. Placeholder | ffmpeg; macOS for --say | Standard |
If the path needs more than the install has, run ./install.sh --doctor and hand over to motion-setup. Without ASR, build_timing.py only estimates 2.75 words a second, so captions drift against real audio.
Path A: local Qwen3-TTS
From the series folder:
cp $MOTION_LIB/core/voice/voice.example.json voice/voice.json # once per series; edit it
$MOTION_LIB/core/voice/narrate.sh voice/voice.json episodes/NN-slug/narration
$MOTION_LIB/core/voice/finalize.sh voice/voice.json episodes/NN-slug/narration episodes/NN-slug/narration/voice/takes/narrator [num.json]
voice.json:speaker(CustomVoice: Aiden, Dylan, Eric, Ryan, Serena, Vivian, Sohee, Ono_anna, Uncle_fu) andinstruct. Recommended: CustomVoice 1.7B, Ryan or Aiden, instruct "friendly, natural, conversational, like telling a friend; clear pauses between sentences; stress the key word of each line".takes_per_linedefaults to 3.tempostays 1.0 (other values needrubberband).qa_targetsset the pitch range and the ASR match (0.9).- A script line can carry
tts(respelled text for pronunciation; captions keeptext) and its owninstruct.num.jsonmaps numerals to spoken words ({"13,000": "thirteen thousand"}) so ASR matching doesn't fail on digits. - Run one TTS process at a time; the 1.7B model is memory-hungry.
finalize.shruns ASR and pitch on every take, picks one per line, trims, loudness-normalises to -16 LUFS, re-runs ASR on the finals and writestiming_narrator.js. After listening, put corrections invoice/picks_override.json({"l3_name": 2}) and rerun withSKIP_PICK=1.- Voice Design (describing a voice in words) is a Qwen3-TTS mode that
narrate.pydoesn't drive. Generate with it elsewhere and use path B.
Path B: your own recording or another TTS
- Put one WAV per line in
voice/final_narrator/<id>.wav, or raw takes asvoice/takes/narrator/<id>_<k>.wavand runfinalize.shas above. - For finished lines, transcribe them, write
voice/chosen_narrator.jsonas{id: "voice/final_narrator/<id>.wav"}, then fromnarration/:
$ASR_PY $MOTION_LIB/core/voice/asr.py voice/final_narrator/*.wav > voice/asr_narrator_final.json
CHOSEN=voice/chosen_narrator.json TIMING_OUT=timing_narrator.js python3 build_timing.py voice/asr_narrator_final.json
Path C: placeholder
From the narration/ folder:
python3 $MOTION_LIB/core/tools/placeholder_vo.py [--wps 3.0] [--say [VOICE]]
It writes silent WAVs (or the macOS say voice with --say) and timing_narrator.js from script.json alone, spreading word times by word length. --wps 3.5 to 4 approximates the target pace (default 3.0). The reel can be built and timed first and re-voiced later: swap the WAVs, rerun finalize.sh, rerun build_vo.py, and the word cues follow.
Delivery rules
Delivery is human, unhurried and emphasised. The viewer must follow every line on the first listen.
- Breathing room. A real pause at every sentence end and between list beats ("Fine. Fine. Fine."). Start with 0.3-0.4 s between lines (
gapinepisode.json, default 0.22;gapsadds an extra beat after one named line) and judge by ear. Pauses go at sentence or clause boundaries only: a 0.2 s gap inside a phrase, such as "copied it, | by taking...", reads as lag. Use the 30 s ceiling for air instead of cutting pauses, and never slow the tempo to get it. - Emphasis. The one or two words each line leans on (the number, the twist word, the verdict) come from the script's staging table. Pass them as a per-line
instruct. - Tone. Conversational and a little amused, not announcer energy. Questions sound like real questions, the catch line sounds curious, the CTA is warm. The narrator still doesn't joke; the picture does.
- Clone model (no instructions). With a clone voice (
ref_audio+ref_text, Base model) the levers are the text and the take. Write the pauses into the punctuation (full stops between list beats, a short question as its own sentence). Generate several seeds of one continuous take (SEED_BASE,takes_per_line), pick the one with the most pitch movement on the target words and ASR 0.9 or better, and re-take a flat line alone (ONLY=l4_peak) and splice it at a sentence boundary. Only clone a voice you have the right to use. - Whole script at once gives consistent prosody: generate one take,
split_take.pycuts it per line, then set"gap": 0inepisode.json. Per scene is fine if the user prefers. - Play the first three lines to the user before the full run:
ONLY=l1_hook,l2_...,l3_... narrate.sh ....
Captions and timing
From video/, once episode.json has scenes:
python3 $MOTION_LIB/core/tools/build_vo.py # public/vo/voiceover.wav, public/vo/captions.json, src/plan.json
python3 $MOTION_LIB/core/tools/timing_md.py # Timing section of STORYBOARD.md
captions.json is a Remotion Caption[]; scene boundaries come from the word timestamps; the composition length is plan.json's durationInFrames. build_vo.py flags any scene under 1.2 s. With no library, transcribe the WAV with the Remotion captions skill (whisper.cpp) or any speech-to-text tool that returns word timestamps.
Captions are one torn tag per word, pages of 1-3 words, at 3.5-4 words a second ($MOTION_LIB/style/$MOTION_STYLE/docs/style-guide.md, sections 11 and 13).
Hand-off
Next is motion-build (stubs, scenes, sound, render). It reads src/plan.json and the Timing section of video/STORYBOARD.md. Any later voice change reruns build_vo.py and timing_md.py; the scene cache then re-renders everything.