SuperAPI AI 工具集

papercut-voice

写作与研究

查看项目

更新于 10-26 16:18

技能介绍

Papercut Voice 是 Papercut Explainer 系列技能中的一个环节,专门负责旁白生成与时间轴标注。它要求 narration 文件夹中最终存在两类产物:voice/final_narrator/<id>.wav(每行脚本一个 WAV)和 timing_narrator.js(每个词的起止时间)。该技能通过三种路径之一完成这些产物,并随后构建字幕和场景计划。完整脚本参考位于 library/voice/README.md。

使用前需要完成预检:设置 PAPERCUT_LIB 环境变量(可从 ~/.config/papercut-explainer/config.env 读取,否则询问一次),并执行 . "$PAPERCUT_LIB/env.sh" 将 ASR_PY、QWEN_TTS_PY 等配置载入 shell。还需要一个已搭建脚手架的项目(papercut-build 第一步),其中 narration/script.json 和 papercut/episode.json(含场景)存在。new_episode.sh 会把 build_timing.py 复制到 narration/。

如果用户已有 TTS,直接使用,不要重新构建(路径 B,若为 Qwen3-TTS 则用路径 A)。询问一次用户选择哪条路径及其运行位置。各路径需求如下:路径 A(本地 Qwen3-TTS)需要 library/voice/setup_tts.sh 创建的 voice venv(模型下载 2.3-4.2 GB),安装模式为 Full;路径 B(自备录音或其他 TTS)需要 ASR 后端(mlx-whisper 或 faster-whisper)以及 librosa + numpy 用于音高分析,安装于 ASR_PY 和 QWEN_TTS_PY 指定的 Python 中,安装模式为 Full 或手动安装这些包;路径 C(占位)需要 ffmpeg,macOS 上 --say 可用,安装模式为 Standard。如果路径所需超出当前安装,运行 ./install.sh --doctor 并转交 papercut-setup。缺少 ASR 时,build_timing.py 仅按每秒 2.75 词估算,字幕会与真实音频漂移。

路径 A:本地 Qwen3-TTS。从系列文件夹执行 cp $PAPERCUT_LIB/voice/voice.example.json voice/voice.json(每个系列一次,然后编辑),再运行 $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,并设置 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 和音高分析,每行选一个,修剪,响度归一化到 -16 LUFS,对最终版重新运行 ASR 并写出 timing_narrator.js。试听后,将修正放入 voice/picks_override.json({"l3_name": 2})并以 SKIP_PICK=1 重新运行。Voice Design(用文字描述声音)是 Qwen3-TTS 的一种模式,narrate.py 不驱动它;需在别处生成并使用路径 B。

路径 B:自备录音或其他 TTS。将每行一个 WAV 放入 voice/final_narrator/<id>.wav,或将原始 take 作为 voice/takes/narrator/<id>_<k>.wav 并按上述运行 finalize.sh。对于已完成的行,转录它们,写出 voice/chosen_narrator.json 为 {id: "voice/final_narrator/<id>.wav"},然后在 narration/ 中运行 $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。

路径 C:占位。从 narration/ 文件夹运行 python3 $PAPERCUT_LIB/tools/placeholder_vo.py [--wps 3.0] [--say [VOICE]]。它仅根据 script.json 写出静音 WAV(或 macOS say 语音,使用 --say)和 timing_narrator.js,按词长分配词时间。--wps 3.5 到 4 近似目标语速(默认 3.0)。可以先构建并计时 reel,之后再配音:替换 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 秒上限来留白,而不是削减停顿,也绝不要为了得到它而放慢速度。强调:每行倚重的一两个词(数字、转折词、结论)来自脚本的 staging 表,作为每行 instruct 传入。语调:对话式且略带趣味,不是播音员能量。问题听起来像真问题,catch line 听起来好奇,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 ...。

字幕和时间轴:从 papercut/ 中,一旦 episode.json 有场景,运行 python3 $PAPERCUT_LIB/tools/build_vo.py(产出 public/vo/voiceover.wav、public/vo/captions.json、src/plan.json)和 python3 $PAPERCUT_LIB/tools/timing_md.py(产出 STORYBOARD.md 的 Timing 部分)。captions.json 是 Remotion Caption[];场景边界来自词时间戳;合成长度是 plan.json 的 durationInFrames。build_vo.py 会标记任何短于 1.2 秒的场景。没有库时,使用 Remotion captions 技能(whisper.cpp)或任何返回词时间戳的语音转文字工具转录 WAV。字幕是每个词一个撕裂标签,每页 1-3 个词,每秒 3.5-4 个词(../papercut-explainer/references/style-guide.md,第 11 和 13 节)。

交接:下一步是 papercut-build(存根、场景、声音、渲染)。它读取 src/plan.json 和 papercut/STORYBOARD.md 的 Timing 部分。任何后续语音更改都会重新运行 build_vo.py 和 timing_md.py;场景缓存然后重新渲染所有内容。