leoyishou 视频章节导航条生成器
自动为视频添加动态章节导航条，让观众一目了然当前进度。
一键生成
# 最简用法 - 自动生成 4 个章节
python ~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py video.mp4
# 指定章节数量
python ~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py video.mp4 --chapters 5
# 指定输出路径
python ~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py video.mp4 --output video_with_nav.mp4
工作流程
视频输入 → 音频提取 → ASR 转录 → LLM 章节分析 → .ass 字幕 → 视频合成
- 音频提取: FFmpeg 提取 16kHz 单声道 WAV
- 语音转文字: 火山引擎 ASR 或 Whisper (自动选择)
- 章节分析: OpenRouter (Gemini) 分析内容，生成章节标题和时间点
- 字幕生成: 生成带动态高亮的 .ass 特效字幕
- 视频合成: FFmpeg 将字幕烧录到视频
核心参数
| 参数 | 说明 | 默认 |
|---|---|---|
video |
输入视频路径 | 必填 |
-o, --output |
输出视频路径 | 自动生成 |
-n, --chapters |
章节数量 | 4 |
--asr |
ASR 引擎 (auto/whisper/volcengine) | auto |
--position |
导航条位置 (bottom/top) | bottom |
--dry-run |
试运行，不执行 | - |
环境配置
必需
# OpenRouter API Key (用于 LLM 章节分析)
export OPENROUTER_API_KEY="sk-or-v1-xxx"
可选 - 火山引擎 ASR
如果配置了火山引擎，优先使用（更快更准）：
# 在火山引擎控制台获取
export VOLC_ASR_APPID="your_app_id"
export VOLC_ASR_TOKEN="your_access_token"
获取方式：火山引擎控制台 → 创建应用 → 获取 APP ID 和 Access Token
未配置火山引擎
自动使用 Whisper (需要安装 openai-whisper)：
pip install openai-whisper
导航条效果
导航条显示在视频底部（或顶部），格式如：
01 环境配置 · 02 代码演示 · 03 功能测试 · 04 总结
↑
(当前高亮白色，其他灰色)
随着视频播放，高亮会自动切换到当前章节。
使用示例
在 Claude Code 中
帮我给这个视频加上章节导航条：~/Videos/tutorial.mp4
给 demo.mp4 添加 5 个章节的导航条
命令行
# 基础用法
python ~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py tutorial.mp4
# 5 个章节，导航条在顶部
python ~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py tutorial.mp4 \
--chapters 5 \
--position top
# 强制使用 Whisper
python ~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py tutorial.mp4 \
--asr whisper
# 试运行
python ~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py tutorial.mp4 --dry-run
输出
默认输出文件名为 {原文件名}_with_chapters.mp4，与原视频同目录。
依赖
- FFmpeg: 音频提取、视频合成 (
brew install ffmpeg) - Python 3.10+
- requests: HTTP 请求
- openai-whisper (可选): 本地语音识别
安装依赖：
cd ~/.claude/skills/video-chapter-nav
pip install -r scripts/requirements.txt
故障排查
| 问题 | 解决方案 |
|---|---|
| FFmpeg 未找到 | brew install ffmpeg |
| ASR 失败 | 检查网络；使用 --asr whisper |
| LLM 失败 | 检查 OPENROUTER_API_KEY |
| 字幕不显示 | 检查视频编码是否兼容 |
| 中文乱码 | 确保系统有 PingFang 字体 |
技术说明
ASS 字幕格式
使用 ASS (Advanced SubStation Alpha) 格式实现动态高亮：
- 定义 Active/Inactive 两种样式
- 每个时间段生成一行字幕事件
- 使用
{\rStyle}语法切换样式
为什么不用 PNG 图片叠加？
.ass 字幕方案的优势：
- 渲染速度快（FFmpeg 原生支持）
- 不需要生成中间文件
- 文件体积小
- 更容易调整样式
相关文件
- 主脚本:
~/.claude/skills/video-chapter-nav/scripts/chapter_nav.py - 依赖:
~/.claude/skills/video-chapter-nav/scripts/requirements.txt