# Video Subtitle Generator

> 全自动视频字幕生成工具，支持语音识别、简繁转换、字幕烧录。用于为视频自动生成中文字幕并嵌入视频中。当用户需要为视频添加字幕、生成字幕文件、或将字幕嵌入视频时使用此技能。

- Skill: `lwmxiaobei/video-subtitle-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lwmxiaobei/video-subtitle-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lwmxiaobei/video-subtitle-generator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lwmxiaobei (https://skillmd.com/u/lwmxiaobei)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lwmxiaobei/video-subtitle-generator

---


# 视频字幕生成器

全自动视频字幕生成工作流，从视频到带字幕视频的完整解决方案。

## 功能

1. **音频提取** - 从视频中提取音频用于语音识别
2. **语音识别** - 使用 OpenAI Whisper 将语音转为文字
3. **简繁转换** - 自动将繁体中文转换为简体中文
4. **字幕校验** - 自动修复语音识别错误（如 "clawd" → "Claude"）
5. **字幕嵌入** - 将字幕烧录到视频中，生成硬字幕

## 使用方法

### 方式一：使用脚本（推荐）

直接运行脚本完成全流程：

```bash
python scripts/generate_subtitles.py <视频文件路径> [输出目录]
```

示例：
```bash
python scripts/generate_subtitles.py /path/to/video.mp4 /output/folder
```

### 方式二：分步执行

如果需要更精细的控制，可以分步执行：

```python
from scripts.generate_subtitles import (
    extract_audio,
    transcribe_with_whisper,
    convert_traditional_to_simplified,
    correct_subtitles,
    burn_subtitles
)

# 1. 提取音频
extract_audio("video.mp4", "audio.wav")

# 2. 语音识别
transcribe_with_whisper("audio.wav", "subtitles.srt")

# 3. 简繁转换
convert_traditional_to_simplified("subtitles.srt", "subtitles_cn.srt")

# 4. 字幕校验修正
correct_subtitles("subtitles_cn.srt", "subtitles_cn.srt")

# 5. 烧录字幕
burn_subtitles("video.mp4", "subtitles_cn.srt", "output.mp4")
```

## 依赖安装

```bash
# 核心依赖
pip install openai-whisper opencc-python-reimplemented moviepy

# AI 智能校验（可选）
pip install openai

# FFmpeg（系统依赖）
# macOS: brew install ffmpeg
# Ubuntu: apt-get install ffmpeg
# Windows: 下载并添加到 PATH
```

**环境变量（用于 AI 校验）：**

```bash
# 方式一：阿里云 DashScope（默认，推荐国内用户）
export OPENAI_API_KEY="sk-xxxx"
# 自动使用 https://dashscope.aliyuncs.com/compatible-mode/v1
# 默认模型: qwen-plus

# 方式二：OpenAI
export OPENAI_API_KEY="sk-xxxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"
# 默认模型: gpt-4o-mini

# 方式三：其他兼容 OpenAI 的 API
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://your-api-endpoint.com/v1"
```

**获取阿里云 API Key：** https://help.aliyun.com/zh/dashscope/developer-reference/acquisition-of-api-key

## 字幕样式

默认字幕样式：
- **字体**：自动检测系统字体（优先使用冬青黑体/黑体）
- **颜色**：金黄色文字（yellow）+ 黑色描边
- **字号**：30px
- **位置**：底部居中，距底部 90px

自定义样式：
```python
burn_subtitles(
    video_path="video.mp4",
    srt_path="subtitles.srt",
    output_path="output.mp4",
    font_path="/path/to/font.ttf",  # 自定义字体
    text_color="white"              # 自定义颜色
)
```

## 字幕自动校验

提供两种字幕校验方式：**AI 智能校验**（推荐）和**规则映射校验**。

### 方式一：AI 智能校验（推荐）

使用大语言模型理解上下文，智能识别和修正语音识别错误，无需手动维护映射表。

**优势：**
- 理解上下文语义，准确修正同音词
- 自动识别专有名词（Claude、Skills、API 等）
- 无需维护映射表
- 支持批量处理

**使用方法（阿里云 DashScope - 默认）：**

```bash
# 设置阿里云 API 密钥
export OPENAI_API_KEY="your-dashscope-api-key"

# 使用 AI 校验生成字幕（自动使用阿里云 qwen-plus 模型）
python scripts/generate_subtitles.py video.mp4 --method llm

# 提供视频内容描述，提高准确度
python scripts/generate_subtitles.py video.mp4 --method llm --context "这是一个关于 Claude Code 的技术教程"

# 仅对已有字幕进行 AI 校验
python scripts/llm_subtitle_corrector.py input.srt output.srt "视频内容描述"
```

**使用方法（OpenAI）：**

```bash
# 设置 OpenAI API 密钥
export OPENAI_API_KEY="sk-xxxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"

# 使用 AI 校验
python scripts/generate_subtitles.py video.mp4 --method llm
```

**Python 中使用：**

```python
from scripts.llm_subtitle_corrector import LLMSubtitleCorrector

# 使用阿里云 DashScope（默认，推荐国内用户）
corrector = LLMSubtitleCorrector()

# 或使用 OpenAI
corrector = LLMSubtitleCorrector(
    api_key="your-openai-key",
    base_url="https://api.openai.com/v1",
    model="gpt-4o-mini"
)

with open("input.srt", "r", encoding="utf-8") as f:
    content = f.read()

# 提供上下文帮助 AI 理解
context = "这是一个关于 Claude Skills 的技术讲解视频"
corrected_content, corrections = corrector.correct_srt(content, context)
```

### 方式二：规则映射校验

使用内置的映射表快速修正常见错误，无需 API 密钥。

**适用场景：**
- 没有 API 密钥
- 处理简单明确的错误
- 追求处理速度

**使用方法：**

```bash
# 默认使用规则校验
python scripts/generate_subtitles.py video.mp4

# 或使用显式参数
python scripts/generate_subtitles.py video.mp4 --method rule
```

**自动修正的错误类型：**

| 错误 | 修正 |
|------|------|
| clawd, clawed | Claude |
| scales, skales | Skills |
| 密集 | 秘籍 |
| 打交到 | 打交道 |
| 谣声已变 | 摇身一变 |
| 人功智能 | 人工智能 |

**使用自定义词典：**

```bash
python scripts/subtitle_corrector.py input.srt output.srt custom_dict.json
```

### 校验方法对比

| 特性 | AI 智能校验 | 规则映射校验 |
|------|-------------|--------------|
| 准确度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 速度 | 较慢（需 API 调用） | 快（本地处理） |
| 维护成本 | 无需维护 | 需维护映射表 |
| 上下文理解 | ✅ 支持 | ❌ 不支持 |
| 专有名词识别 | ✅ 自动 | ⚠️ 需手动添加 |
| API 依赖 | 需要 | 不需要 |
| 支持的 API | 阿里云 DashScope<br>OpenAI<br>其他兼容 API | 无需 API |
| 默认模型 | qwen-plus（阿里云）<br>gpt-4o-mini（OpenAI） | - |

**建议：** 初次处理使用 AI 校验获得高质量结果，后续如有特定需求再使用规则校验微调。

## 输出文件

执行完成后会生成：
- `{视频名}_原始.srt` - Whisper 生成的原始字幕（繁体）
- `{视频名}_简体.srt` - 简体中文字幕文件（已校验修正）
- `{视频名}_字幕版.mp4` - 带硬字幕的视频

## 命令行参数

```bash
python scripts/generate_subtitles.py <视频文件> [输出目录] [选项]

选项：
  --method {rule,llm}    校验方法：rule=规则映射（默认），llm=AI智能校验
  --context TEXT         视频内容描述（帮助AI理解上下文）
  --correct-only         仅执行字幕校验，跳过前面的步骤

示例：
  # 基础用法（规则校验）
  python scripts/generate_subtitles.py video.mp4

  # 使用 AI 智能校验
  python scripts/generate_subtitles.py video.mp4 --method llm --context "Claude 技术教程"

  # 仅校验已有字幕
  python scripts/generate_subtitles.py subtitles.srt --correct-only --method llm
```

## 注意事项

1. **处理时间**：一个 7 分钟的视频大约需要 10-15 分钟处理
2. **硬件要求**：语音识别需要足够的内存，建议使用 8GB+ 内存
3. **字体问题**：如果中文字体显示异常，请确保系统安装了中文字体
4. **Whisper 模型**：默认使用 base 模型，可在代码中修改为 tiny/small/medium/large