将博客文章或散文转换为带词级时间戳的旁白视频脚本

把书面文档拆分为场景、生成 TTS 旁白音频并输出词级同步字幕，用于视频旁白制作。

适用场景

解决思路

1. 先安装依赖：Deno、Python 3.12（含 venv）、ffmpeg、whisper-cpp（通过 @remotion/install-whisper-cpp 安装），并把 Qwen3-TTS 模型文件放入 tts/model/ 目录（约 7.8GB，含 config.json、generation_config.json、model.safetensors、tokenizer_config.json、vocab.json、merges.txt、speech_tokenizer/ 等）
2. 首次配置 Python 虚拟环境：cd .claude/skills/document-to-narration/tts && python3.12 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt，并额外执行 pip install openai-whisper
3. 准备文档：使用带清晰 H1/H2 标题结构、论证分段明确、朗读自然的 Markdown 文档
4. 拆分场景：运行 deno run --allow-read --allow-write scripts/split-to-scenes.ts input.md --output ./output/，可选加 --adapt 应用口语化改写，或用 --dry-run 预览断点
5. 按场景边界启发式判断断点：强边界（几乎必断）包括 H2 标题变化、'Here's the thing'/'The point is' 类转折句、引入重要比喻、显式枚举（First.../Second...）、显著视角切换；中等边界（考虑断开）包括长短段落交替、例子到原理的过渡、段首的 But/However/Meanwhile、先问后答模式；弱边界（通常保持在一起）包括同一例子内的段落衔接、同一论点的连续证据、铺垫到笑点/揭示的递进
6. 控制场景长度：目标每场景 100-300 词（30-90 秒音频），最少 50 词，最多 500 词
7. 生成单条完整旁白音频（推荐）：运行 python scripts/narrate-full.py ./output/scenes/，可选 --force 强制重生成、--speaker 指定说话人（默认 jwynia）、--output 指定输出路径（默认 ../full-narration.wav），输出单个 full-narration.wav 以保证音量与节奏一致
8. 转写并获取词级时间戳：运行 python scripts/transcribe-full.py ./output/full-narration.wav，可选 --model 指定 Whisper 模型（tiny/base/small/medium/large/large-v2/large-v3，默认 medium）、--output-dir 指定输出目录，输出 .vtt 词级字幕和 .json captions 数组
9. 提取场景时间边界：运行 python scripts/extract-scene-boundaries.py ./output/scenes/ ./output/full-narration.json，可选 --json 输出 JSON 数组、--typescript 输出供 Video.tsx 使用的 TypeScript 代码，得到场景编号、slug、起始时间和时长
10. 也可用一键流水线：deno run -A scripts/full-pipeline.ts /path/to/essay.md --output ./output/essay-name/，可选 --adapt 应用口语化、--skip-tts 仅生成文本、--skip-transcribe 跳过转写
11. 避免逐场景 TTS（legacy 的 narrate-scenes.py）：它会为每个场景单独生成音频，音量与节奏不一致，拼接时会出现跳变和削波，应改用 narrate-full.py 单次生成
12. 避免反模式：不要机械地按段落或标题切分（The Paragraph Slicer），要按修辞单元而非结构单元切分；不要把整节保留为单场景（The Wall of Text），要找到节内的自然停顿点；不要逐字照搬书面文本（The Verbatim Transcriber），要应用口语化改写；也不要过度改写以致丢失作者声音（The Over-Adapter），保留作者语气、反问句、刻意重复和关键措辞
13. 启用 --adapt 时按规则改写：括号插入语改为破折号或独立句；e.g. 改为 for example；i.e. 改为 that is；长嵌套从句拆成多句；分号改为句号；*强调* 改为符合语境的重读
14. Whisper 需要 16kHz 单声道 WAV，流水线会自动用 ffmpeg -i input.wav -ar 16000 -ac 1 output_16khz.wav 转换
15. 检查输出目录结构：scenes/ 下含 01-opening-hook.txt/.wav/.vtt 等文件，以及 manifest.json（含 source、created_at、total_scenes、total_duration_seconds 和每个场景的 number、slug、word_count、audio_duration_seconds、files、captions 数组）
16. 与 Remotion 集成：把 manifest 场景列表传给 remotion-designer，每个场景作为一个视觉设计单元，用词级时间戳驱动文字动画；在 Video.tsx 中用 Sequence 按场景时长排布 Audio 和 CaptionRenderer

适用边界 · 注意事项

• 内容已经是场景/脚本格式时
• 需要实时语音合成（本技能是批处理）
• 处理对话或多说话人内容（仅支持单一声音）