papercut-voice
Voice a papercut reel and time it to the picture. Three paths, local Qwen3-TTS, your own recording or another TTS, or a placeholder voice. Covers delivery rules, voice.json, captions and scene timing. Use for "set up the voice", "re-voice this", "time the script".
0xS4N4TG · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add 0xS4N4TG/papercut-explainer --skill papercut-voice技能说明
name: papercut-voice description: Voice a papercut reel and time it to the picture. Three paths, local Qwen3-TTS, your own recording or another TTS, or a placeholder voice. Covers delivery rules, voice.json, captions and scene timing. Use for "set up the voice", "re-voice this", "time the script".
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 library/voice/README.md.
Preflight
- Library:
$PAPERCUT_LIB, else thePAPERCUT_LIB=line in~/.config/papercut-explainer/config.env, else ask once. Export it, and. "$PAPERCUT_LIB/env.sh"loadsASR_PY,QWEN_TTS_PYand the other config values into the shell. - A scaffolded project (
papercut-build, step 1) withnarration/script.jsonandpapercut/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 library/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 papercut-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 $PAPERCUT_LIB/voice/voice.example.json voice/voice.json # once per series; edit it
$PAPERCUT_LIB/voice/narrate.sh voice/voice.json episodes/NN-slug/narration
$PAPERCUT_LIB/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 $PAPERCUT_LIB/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 $PAPERCUT_LIB/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 ha