--- name: youtube-narrator description: > YouTube 视频中文配音自动化工具 (v3.0 弹性时间轴版)。核心特性：语义合并字幕、弹性时间轴配音、智能防重叠。解决语速忽快忽慢和声音截断问题，提供纪录片级的自然配音体验。关键词：视频配音、YouTube、中文解说、弹性时间轴、自动对齐 allowed-tools: - Read - Write - Edit - Bash - Glob - AskUserQuestion model: claude-sonnet-4-5-20250514 --- # YouTube 中文配音自动化工具 (v3.0 弹性时间轴版) > 将英文 YouTube 视频转换为中文配音版本，采用"弹性时间轴"技术，优先保证语速自然流畅。 ## ⚠️ 重要提示 **禁止创建新脚本！** 所有需要的脚本都已存在于 `$HOME\/.claude\/skills\/youtube-narrator\/scripts\/` 目录中。如果遇到脚本不存在的错误，请检查脚本名称是否正确。 **可用脚本列表**: - `download_video.py` - 下载视频和字幕 - `vtt_to_json.py` - 解析 VTT 字幕为 JSON - `semantic_merge.py` - 语义合并（可选，AI 也可直接处理） - `generate_synced_narration.py` - 弹性配音生成 - `generate_summary.py` - 生成社交媒体文案模板 - `utils.py` - 工具函数 --- ## 工作流程 ### 阶段 1: 环境检测运行以下命令确保工具就绪： ```bash yt-dlp --version && python3 -c "import edge_tts; print('✅ edge-tts')" && ffmpeg -version | head -1 ``` ### 阶段 2: 获取视频 URL 如果用户没有提供 YouTube 链接，使用 AskUserQuestion 询问。 ### 阶段 3: 下载视频和字幕 **必须使用以下命令**（不要自己写下载逻辑）： ```bash SKILL_DIR="$HOME\/.claude\/skills\/youtube-narrator" OUTPUT_DIR=$(pwd) python3 "$SKILL_DIR\/scripts\/download_video.py" "" "$OUTPUT_DIR" ``` 下载完成后，当前目录会生成： - `.mp4` - 视频文件 - `.en.vtt` - 英文字幕文件 ### 阶段 4: 解析 VTT 字幕 **必须使用以下命令**（不要自己写解析逻辑）： ```bash SKILL_DIR="$HOME\/.claude\/skills\/youtube-narrator" python3 "$SKILL_DIR\/scripts\/vtt_to_json.py" ".en.vtt" "original_subtitles.json" ``` ### 阶段 5: 语义合并 (Semantic Merge) 将零碎字幕合并为 5-15 秒的完整意群。 **方式 A - 使用脚本**（推荐）： ```bash SKILL_DIR="$HOME\/.claude\/skills\/youtube-narrator" python3 "$SKILL_DIR\/scripts\/semantic_merge.py" "original_subtitles.json" "merged_subtitles.json" ``` **方式 B - AI 直接处理**： 1. 读取 `original_subtitles.json` 2. 按以下规则合并： - 将连续的短句（<3秒）合并 - 在句子结束处（. ! ?）分割 - 目标时长：5-15 秒\/段 3. 输出格式： ```json [ { "start": 0.08, "end": 12.88, "text": "The CEO of one of the major AI labs predicted last year..." } ] ``` 4. 保存为 `merged_subtitles.json` ### 阶段 6: 意群翻译 (Chunk Translation) **AI 直接执行翻译**（不需要脚本）： 1. 读取 `merged_subtitles.json` 2. 逐段翻译为中文，遵循原则： - **口语化**：像人说话一样自然 - **情绪对齐**：匹配原文情感 - **长度适中**：中文字数约为原文时长 × 4.5 字\/秒 3. 输出格式： ```json [ { "start": 0.08, "end": 12.88, "ids": [0, 1, 2, 3, 4, 5], "original": "The CEO of one of the major AI labs...", "translation": "某大型AI实验室的CEO去年预测..." } ] ``` 4. 保存为 `merged_translations.json` **注意**：`ids` 字段是必须的，表示这个翻译块对应原始字幕的哪些行（索引从0开始）。 ### 阶段 7: 确认翻译展示前 5 条翻译结果给用户，询问是否继续或需要调整。 ### 阶段 8: 选择语音与倍速使用 AskUserQuestion 询问用户： **配音角色选项**： - `zh-CN-XiaoxiaoNeural` (女声, 推荐) - `zh-CN-YunxiNeural` (男声) - `zh-CN-YunyangNeural` (男声, 年轻) - `zh-CN-XiaoxiaoMultilingualNeural` (女声, 多语言) **倍速选项**： - `1.0` (默认) - `1.1` - `1.2` - `1.3` ### 阶段 9: 弹性配音生成 **必须使用以下命令**（不要自己写配音逻辑）： ```bash SKILL_DIR="$HOME\/.claude\/skills\/youtube-narrator" OUTPUT_DIR=$(pwd) python3 "$SKILL_DIR\/scripts\/generate_synced_narration.py" \ "$OUTPUT_DIR\/.mp4" \ "$OUTPUT_DIR\/.en.vtt" \ "$OUTPUT_DIR\/merged_translations.json" \ "$OUTPUT_DIR\/final_output" \ --voice \ --speed ``` 替换： - `` - 视频ID（如 wYs6HWZ2FdM） - `` - 用户选择的语音（如 zh-CN-XiaoxiaoNeural） - `` - 用户选择的倍速（如 1.2） ### 阶段 10: 生成总结文案 **必须使用以下命令**： ```bash SKILL_DIR="$HOME\/.claude\/skills\/youtube-narrator" OUTPUT_DIR=$(pwd) python3 "$SKILL_DIR\/scripts\/generate_summary.py" \ "$OUTPUT_DIR\/merged_translations.json" \ "$OUTPUT_DIR\/final_output\/summary.md" ``` 脚本会输出视频的全部中文文本。根据输出内容，编辑 `final_output\/summary.md` 文件，填充： - **核心关键词**：5-8 个 SEO 关键词 - **一句话总结**：概括核心价值 - **核心观点**：3-5 个要点 - **平台文案**：小红书、抖音、公众号风格 ### 阶段 11: 交付结果向用户展示： - 最终视频路径：`final_output\/final_video_x.mp4` - 字幕文件：`final_output\/subtitles.srt` - 推广文案：`final_output\/summary.md` - 处理统计信息 --- ## 错误处理 - **TTS 生成失败**：脚本会自动重试 3 次 - **ffmpeg 报错**：检查视频编码格式，尝试重新下载 - **翻译失败**：检查 ANTHROPIC_API_KEY 环境变量 ## 文件结构 ``` <工作目录>\/ ├── .mp4 # 原始视频 ├── .en.vtt # 英文字幕 ├── original_subtitles.json # 解析后的原始字幕 ├── merged_subtitles.json # 语义合并后的英文意群 ├── merged_translations.json # 中文翻译（含 ids 字段） └── final_output\/ ├── final_video.mp4 # 最终视频 ├── final_video_1.2x.mp4 # 指定倍速版本 ├── subtitles.srt # 中文字幕 ├── final_mix.mp3 # 混音音轨 └── summary.md # 社交媒体文案 ```