Papercut 配音
每一个后期阶段都需要在 narration 文件夹中准备两个东西:voice/final_narrator/<id>.wav(每个脚本行一个 WAV)和 timing_narrator.js(每个单词的起始和结束时间)。本技能通过三种路径之一生成它们,然后构建字幕和场景计划。完整脚本参考请见 $MOTION_LIB/core/voice/README.md。
前置检查
- 库:
$MOTION_LIB,否则检查~/.config/motion-explainer/config.env中的MOTION_LIB=行,再询问一次。将其导出,并运行. "$MOTION_LIB/env.sh"以加载ASR_PY、QWEN_TTS_PY及其他配置值到 shell 中。 - 一个已初始化的项目(
motion-build,步骤 1),包含narration/script.json和包含scenes的video/episode.json。new_episode.sh会将build_timing.py复制到narration/中。 - 如果用户已经安装了 TTS,则直接使用现有 TTS,无需重新构建(如果是 Qwen3-TTS 则走路径 A,否则走路径 B)。询问一次用户使用的 TTS 是哪个以及在哪里运行。否则询问用户选择哪条路径,并说明所需条件:
| 路径 | 需要 | 安装模式 |
|---|---|---|
| A. 本地 Qwen3-TTS | 来自 $MOTION_LIB/core/voice/setup_tts.sh 的语音 venv(模型下载 2.3-4.2 GB) | 完整 |
| B. 自行录音或其他 TTS | 一个 ASR 后端(mlx-whisper 或 faster-whisper)以及 ASR_PY 和 QWEN_TTS_PY 所指向的 Python 环境中的 librosa + numpy(用于音调处理) | 完整,或手动安装这些包 |
| C. 占位语音 | ffmpeg;macOS 系统需要 --say 参数 | 标准 |
如果路径需要的组件超出当前安装范围,请运行 ./install.sh --doctor 并交由 motion-setup 处理。如果没有 ASR,build_timing.py 只能按 2.75 词/秒估算,因此字幕会与实际音频产生偏移。
路径 A:本地 Qwen3-TTS
在系列文件夹中执行:
cp $MOTION_LIB/core/voice/voice.example.json voice/voice.json # 每个系列执行一次;编辑它
$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)和instruct。推荐设置:CustomVoice 1.7B,选择 Ryan 或 Aiden,instruct 为 "friendly, natural, conversational, like telling a friend; clear pauses between sentences; stress the key word of each line"。takes_per_line默认为 3。tempo保持为 1.0(其他值需要rubberband)。qa_targets设置音调范围和 ASR 匹配度(0.9)。- 脚本行可以携带
tts(用于发音的改写文本;字幕保持text)及其自身的instruct。num.json将数字映射为口语单词(如{"13,000": "thirteen thousand"}),以防止 ASR 匹配因数字而失败。 - 一次只运行一个 TTS 进程;1.7B 模型非常耗内存。
finalize.sh对每个 take 运行 ASR 和音调处理,为每行挑选一个 take,进行修剪、响度标准化至 -16 LUFS,再对最终结果运行 ASR,并写入timing_narrator.js。试听后,将修正内容放入voice/picks_override.json(如{"l3_name": 2}),然后使用SKIP_PICK=1重新运行。- 语音设计(用文字描述语音)是 Qwen3-TTS 的一种模式,
narrate.py不驱动该模式。请在其他地方生成后,通过路径 B 使用。
路径 B:自行录音或其他 TTS
- 将每行对应的一个 WAV 文件放入
voice/final_narrator/<id>.wav,或者将原始 take 放入voice/takes/narrator/<id>_<k>.wav并像路径 A 那样运行finalize.sh。 - 对于已完成的台词,进行转写,写入
voice/chosen_narrator.json为{id: "voice/final_narrator/<id>.wav"},然后在narration/目录下执行:
$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
路径 C:占位语音
在 narration/ 文件夹中执行:
python3 $MOTION_LIB/core/tools/placeholder_vo.py [--wps 3.0] [--say [VOICE]]
它会生成静音 WAV 文件(如果使用 --say 参数,则使用 macOS 的 say 命令生成语音)以及仅基于 script.json 生成的 timing_narrator.js,按单词长度分配时间。--wps 3.5 到 4 可接近目标语速(默认 3.0)。可以先构建和计时画面,之后重新配音:替换 WAV 文件,重新运行 finalize.sh,再重新运行 build_vo.py,单词提示会自动更新。
交付规则
配音应该自然、从容且带有强调。观众必须在第一次收听时就理解每一行。
- 呼吸空间。 在每个句子结尾和列表节拍之间(如 "Fine. Fine. Fine.")要有真实的停顿。以每行之间 0.3-0.4 秒(
episode.json中的gap,默认 0.22;gaps可在指定行后添加额外停顿)开始,根据听觉调整。停顿仅放在句子或从句边界:在短语内部插入 0.2 秒的间隙,例如 "copied it, | by taking...",听起来会有滞后感。使用 30 秒的天花板时间来换取空气,而不是减少停顿,且永远不要为了凑时间而放慢语速。 - 重音强调。 每行所强调的一两个词(数字、转折词、评判词)来自脚本的分镜表。将它们作为每行的
instruct传入。 - 语调。 交谈感且略带趣味,而不是播音员的能量。问句听起来像真正的疑问,重点句听起来充满好奇,CTA 要温暖。旁白者仍然不搞笑;画面负责搞笑。
- 克隆模型(无指令)。 对于克隆语音(
ref_audio+ref_text,Base 模型),可调节的杠杆是文本和 take。将停顿写入标点符号(列表节拍之间使用句号,简短问句自成一句)。生成一个连续 take 的多个种子(SEED_BASE、takes_per_line),选择在目标词上音调变化最大且 ASR 达到 0.9 或更好的那个,然后单独重新录制一个平淡的行(ONLY=l4_peak)并在句子边界处拼接。仅克隆你有权使用的语音。 - 一次性生成整个脚本 能获得一致的韵律:生成一个 take,用
split_take.py按行切割,然后在episode.json中设置"gap": 0。如果用户偏好,按场景生成也可以。 - 在全量运行前,向用户播放前三行:使用
ONLY=l1_hook,l2_...,l3_... narrate.sh ...。
字幕与计时
在 video/ 目录下,一旦 episode.json 包含 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 # STORYBOARD.md 的“计时”部分
captions.json 是一个 Remotion Caption[];场景边界来自单词时间戳;组合长度为 plan.json 中的 durationInFrames。build_vo.py 会标记任何时长不足 1.2 秒的场景。如果没有库,可以使用 Remotion 字幕技能(whisper.cpp)或任何能返回单词时间戳的语音转文字工具来转写 WAV。
字幕采用每个单词一个撕裂标签,每页 1-3 个单词,语速为 3.5-4 词/秒($MOTION_LIB/style/$MOTION_STYLE/docs/style-guide.md,第 11 和 13 节)。
交接
接下来的步骤是 motion-build(存根、场景、音效、渲染)。它会读取 src/plan.json 和 video/STORYBOARD.md 的“计时”部分。任何后续的语音变更只需重新运行 build_vo.py 和 timing_md.py;场景缓存会重新渲染所有内容。