video-to-subtitle-summary

一个 Codex / Claude Code Skill，自动将短视频平台（抖音、小红书、B 站、YouTube 等）视频或本地视频/音频文件转换为字幕文本并生成 AI 摘要。

核心流程：

• 在线视频： 提供视频链接 → 自动下载视频或直接抓字幕 → 生成字幕 → AI 总结
• 本地文件： 提供本地视频/音频路径 → 提取音频（如需） → 选择字幕后端 → 生成字幕 → AI 总结

默认字幕后端是本地 faster-whisper，也支持通过环境变量切换到火山引擎 VC。 YouTube 链接会优先用 yt-dlp 直接抓取人工字幕或自动字幕，不需要 AI Douyin/TikHub，也不会默认下载视频或跑 ASR。

English

更新说明

当前版本支持两种字幕转写后端：

• faster-whisper：默认方案，本地转写，不依赖火山引擎
• volcengine：可选方案，使用火山引擎音视频字幕服务

这意味着：

• 默认情况下不需要注册和开通火山引擎
• 只有在 ASR_BACKEND=volcengine 时，才需要配置 BYTEDANCE_VC_TOKEN 和 BYTEDANCE_VC_APPID
• 如果你更看重本地化与零 API 转写费用，保持默认即可
• 如果你更偏好云端转写能力，切换环境变量即可

抖音、小红书、B 站默认推荐使用 AI Douyin 解析下载直链：注册后可用免费额度试用，成功解析一次扣 1 积分。已有 TikHub 用户也可以改用自有 TIKHUB_TOKEN。YouTube 直接由 yt-dlp 抓字幕。ASR 字幕识别后端由 ASR_BACKEND 控制。

一键免部署方案

不想本地安装和配置环境时，可直接使用在线版本：

• https://top9.cc

私有化部署支持

支持程序私有化部署，可落地到企业服务器或内网环境，满足数据隔离与合规要求。

如需私有化部署方案、技术支持或商务合作，请联系：[email protected]

效果展示

输入一个视频链接或本地文件路径，自动输出：

## 视频分析结果

### 视频信息
| 项目 | 内容 |
|------|------|
| 视频ID | 7456789012345 |
| 作者 | 某知识博主 |
| 时长 | 3:25 |

### AI生成标题
深度解析 2024 年 AI 发展趋势与个人应对策略

### AI摘要
视频主要讨论了 2024 年 AI 技术的发展趋势，包括大模型的演进方向、
AI 在各行业的落地应用，以及普通人如何把握 AI 时代的机遇...

### 核心要点
1. 大模型正在从“通用智能”向“专业智能”演进
2. AI 应用层的创业机会远大于基础模型层
3. 掌握 AI 工具使用能力将成为职场核心竞争力

### 生成文件
- 视频: /tmp/video_analysis/7456789012345/video.mp4
- 音频: /tmp/video_analysis/7456789012345/audio.mp3
- SRT字幕: /tmp/video_analysis/7456789012345/subtitle.srt
- 纯文本: /tmp/video_analysis/7456789012345/text.txt

前置条件

快速安装

1. 选择字幕后端

默认推荐 faster-whisper：

ASR_BACKEND=faster-whisper

如需使用火山引擎：

ASR_BACKEND=volcengine

2. 按后端安装依赖

方案 A：faster-whisper（默认）

python3 ~/.codex/skills/video-to-subtitle-summary/scripts/install_faster_whisper.py

安装 helper 会先测速 PyPI 镜像，选择最快可用源，再创建独立 venv 安装。默认按 CPU 路径运行；检测到 NVIDIA/CUDA 时会自动切到 GPU。Apple Silicon 会继续走 CPU 路径。GPU 安装细节见 docs/faster-whisper-setup.md。

方案 B：火山引擎 VC（可选）

按照 docs/bytedance-vc-setup.md 开通服务并获取 APPID / Token。

2.5 安装 FFmpeg

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows (使用 Chocolatey)
choco install ffmpeg

2.8 安装 yt-dlp（B 站 / YouTube 需要）

# macOS
brew install yt-dlp

# 通用（需要 Python）
python3 -m pip install -U yt-dlp

3. 复制 Skill 到 Codex / Claude Code

# 克隆仓库
git clone https://github.com/imlewc/video-to-subtitle-summary-skill.git video-to-subtitle-summary

# Codex
mkdir -p ~/.codex/skills
cp -r video-to-subtitle-summary ~/.codex/skills/video-to-subtitle-summary

# Claude Code
mkdir -p ~/.claude/skills
cp -r video-to-subtitle-summary ~/.claude/skills/video-to-subtitle-summary

4. 配置环境变量

如需处理抖音、小红书或 B 站，推荐注册 AI Douyin 并创建 API Key；YouTube 不需要视频解析代理。已有 TikHub 用户可改用自有 TikHub Token。然后配置你要使用的字幕后端。

方式一：使用 .env 文件（推荐）

cp .env.example ~/.codex/skills/video-to-subtitle-summary/.env
# 编辑 .env 文件填入你的配置

方式二：写入 Shell 配置

# 添加到 ~/.zshrc 或 ~/.bashrc
export ASR_BACKEND="faster-whisper"

# 默认推荐：AI Douyin 代理（成功解析下载直链后扣 1 积分）
export VIDEO_INFO_PROVIDER="ai-douyin"
export AI_DOUYIN_API_BASE="https://top9.cc"
export AI_DOUYIN_API_KEY="your_ai_douyin_api_key"

# 可选视频接口获取方案：自有 TikHub Token
export TIKHUB_TOKEN=""

export FW_MODEL_SIZE="small"
export FW_DEVICE="auto"
export FW_COMPUTE_TYPE=""
export FW_PYTHON=""

export BYTEDANCE_VC_TOKEN="your_bytedance_vc_token"
export BYTEDANCE_VC_APPID="your_bytedance_vc_appid"

说明：

• ASR_BACKEND：可选，默认 faster-whisper
• VIDEO_INFO_PROVIDER：可选，默认 ai-douyin；可改为 tikhub
• AI_DOUYIN_API_BASE / AI_DOUYIN_API_KEY：默认推荐的视频解析代理；抖音/小红书/B 站需要；YouTube 不需要；成功解析下载直链后扣 1 积分
• TIKHUB_TOKEN：可选视频接口获取方案；当 VIDEO_INFO_PROVIDER=tikhub 或 AI Douyin 不可用时使用
• AI Douyin 返回 402 insufficient balance 时，表示免费额度用完或余额不足，可在平台充值积分，或切换为自有 TikHub Token
• FW_MODEL_SIZE / FW_DEVICE / FW_COMPUTE_TYPE：仅 faster-whisper 使用
• FW_PYTHON：可选，指定安装了 faster-whisper 的 Python；留空时优先使用安装 helper 创建的默认 venv
• BYTEDANCE_VC_TOKEN / BYTEDANCE_VC_APPID：仅 volcengine 使用

使用方法

在线视频

在 Claude Code 中直接发送视频链接即可（支持抖音、小红书、B 站、YouTube 等）：

请帮我提取这个视频的字幕并总结：https://v.douyin.com/xxxxxx/

请帮我总结这个小红书视频：https://www.xiaohongshu.com/explore/xxxxxx

请帮我总结这个B站视频：https://www.bilibili.com/video/BVxxxxxxxxxx/

请帮我总结这个 YouTube 视频：https://www.youtube.com/watch?v=O87FdYIPeQk

或者使用 skill 命令：

/video-to-subtitle-summary https://v.douyin.com/xxxxxx/

本地文件

直接提供本地视频或音频文件路径：

请帮我提取字幕并总结：/Users/me/Downloads/video.mp4

/video-to-subtitle-summary ~/Desktop/recording.mp3

本地文件模式会自动跳过视频下载步骤，音频文件还会跳过音频提取步骤，无需 AI Douyin/TikHub 视频解析代理。

YouTube 字幕直抓

YouTube 链接优先执行：

python3 ~/.codex/skills/video-to-subtitle-summary/scripts/download_youtube_subtitles.py \
  "https://www.youtube.com/watch?v=O87FdYIPeQk" \
  --output-dir /tmp/video_analysis/O87FdYIPeQk \
  --languages zh-Hans,zh-Hant,zh,en

生成 /tmp/video_analysis/O87FdYIPeQk/subtitle.srt 和 /tmp/video_analysis/O87FdYIPeQk/text.txt。如果视频没有可抓取字幕，再回退到下载音频并使用 ASR_BACKEND 转写。

查看自己的 AI Douyin 历史任务

已配置 AI_DOUYIN_API_KEY 后，可以查询当前 API Key 对应用户的历史任务：

python3 ~/.codex/skills/video-to-subtitle-summary/scripts/list_ai_douyin_tasks.py \
  --page 1 \
  --page-size 20

可选筛选：

python3 ~/.codex/skills/video-to-subtitle-summary/scripts/list_ai_douyin_tasks.py --status completed
python3 ~/.codex/skills/video-to-subtitle-summary/scripts/list_ai_douyin_tasks.py --search "关键词" --json

该脚本默认读取 skill 目录 .env 或环境变量中的 AI_DOUYIN_API_BASE / AI_DOUYIN_API_KEY，调用 GET /api/v1/tasks，只返回当前用户自己的任务。

安装指南

费用说明

默认方案 faster-whisper 不会产生火山字幕接口费用。 首次运行 faster-whisper 会下载模型文件，之后会复用本地缓存。

项目结构

video-to-subtitle-summary/
├── README.md                     # 项目介绍（本文件）
├── README_en.md                  # English README
├── LICENSE                       # MIT 协议
├── SKILL.md                      # Skill 本体
├── .env.example                  # 环境变量模板
├── scripts/
│   ├── download_video_candidates.py
│   ├── download_youtube_subtitles.py
│   ├── install_faster_whisper.py
│   ├── list_ai_douyin_tasks.py
│   └── transcribe_faster_whisper.py
├── tests/
│   ├── test_download_video_candidates.py
│   ├── test_download_youtube_subtitles.py
│   ├── test_install_faster_whisper.py
│   ├── test_list_ai_douyin_tasks.py
│   └── test_transcribe_faster_whisper.py
└── docs/
    ├── ai-douyin-setup.md
    ├── tikhub-setup.md
    ├── faster-whisper-setup.md
    └── bytedance-vc-setup.md

License

MIT