# youtube-narrator

> YouTube 视频中文配音自动化工具 (v3.0 弹性时间轴版)。 核心特性：语义合并字幕、弹性时间轴配音、智能防重叠。 解决语速忽快忽慢和声音截断问题，提供纪录片级的自然配音体验。 关键词：视频配音、YouTube、中文解说、弹性时间轴、自动对齐

- Author: epingpong
- Repository: jerrydinguk-coder/youtube-narrator
- Version: 20260126005901
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/jerrydinguk-coder/youtube-narrator
- Web: https://mule.run/skillshub/@@jerrydinguk-coder/youtube-narrator~youtube-narrator:20260126005901

---

---
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" "<YOUTUBE_URL>" "$OUTPUT_DIR"
```

下载完成后，当前目录会生成：
- `<video_id>.mp4` - 视频文件
- `<video_id>.en.vtt` - 英文字幕文件

### 阶段 4: 解析 VTT 字幕

**必须使用以下命令**（不要自己写解析逻辑）：

```bash
SKILL_DIR="$HOME/.claude/skills/youtube-narrator"
python3 "$SKILL_DIR/scripts/vtt_to_json.py" "<video_id>.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/<video_id>.mp4" \
    "$OUTPUT_DIR/<video_id>.en.vtt" \
    "$OUTPUT_DIR/merged_translations.json" \
    "$OUTPUT_DIR/final_output" \
    --voice <voice_id> \
    --speed <speed_value>
```

替换：
- `<video_id>` - 视频ID（如 wYs6HWZ2FdM）
- `<voice_id>` - 用户选择的语音（如 zh-CN-XiaoxiaoNeural）
- `<speed_value>` - 用户选择的倍速（如 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_<speed>x.mp4`
- 字幕文件：`final_output/subtitles.srt`
- 推广文案：`final_output/summary.md`
- 处理统计信息

---

## 错误处理

- **TTS 生成失败**：脚本会自动重试 3 次
- **ffmpeg 报错**：检查视频编码格式，尝试重新下载
- **翻译失败**：检查 ANTHROPIC_API_KEY 环境变量

## 文件结构

```
<工作目录>/
├── <video_id>.mp4              # 原始视频
├── <video_id>.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              # 社交媒体文案
```