视频转录（video-to-transcript）
把抖音/B站/YouTube 等平台的视频一键转成文字笔记。发个链接或给个本地文件，几分钟后拿到整理好的文字稿：机器转录 + 画面字幕双重识别，LLM 校对错字，输出可直接复制的纯文本和带时间戳版本。本地运行，不上传你的视频。
触发场景
当用户给出以下内容或提出相关需求时触发：
- 抖音/B站/YouTube/小红书/TikTok 视频链接 → 转成文字
- 本地视频文件 → 转录
- 本地音频文件 → 转录
- 生成字幕、提取视频文字、会议录音转纪要
交互示例：
用户：转录这个视频 https://v.douyin.com/xxxxx
Agent：已转录完成。校对版：outputs/human/xxx-校对版.txt，时间戳版：outputs/human/xxx-校对版-时间戳.txt
用户：转录我桌面的会议.mp4
Agent：已转录完成。
执行流程
0. 首次安装确认（硬门槛）
Agent 必须先向用户提问；在用户明确同意前，不得运行任何工具或安装命令。 首次安装时，先原样给出：
本次将在当前工作目录创建独立沙箱：<解析后的绝对路径>/video-transcript-sandbox/。需要联网安装依赖并下载 large-v3 模型，预计占用约 3.3GB，建议至少预留 4GB。是否安装到这里并继续？如需其他位置，请告诉我路径。
“直接装”、任何紧急催促或沉默都不构成同意。必须等待用户明确回复“是”或“继续”，或由用户提供其他路径；得到批准后，运行：
python scripts/setup-sandbox.py "<approved absolute path>"
1. 首次使用：搭建环境（一次性）
执行 scripts/setup-sandbox.py，在当前工作目录安装 Python 依赖 + 下载 faster-whisper large-v3 模型。耗时约 5-10 分钟，需 3GB 磁盘。所有依赖装在沙箱内，不污染系统 Python。跨平台支持 macOS / Windows / Linux。
2. 获取输入
根据输入类型选择处理方式。完整决策树见 references/decision-tree.md，各平台反爬对策见 references/platform-workarounds.md。
- 视频/音频 URL：执行
scripts/download.py <url>，自动完成下载（无需手动干预）：
1. yt-dlp 直连下载音频流
2. 失败 → 自动带浏览器登录状态（cookie）重试
3. 还失败 → 输出人话错误 + 恢复建议（重发链接即可，不会产生脏数据）
极端兜底（下载脚本也失败时）：浏览器抓真实 CDN URL + curl 下载 - 本地视频文件：直接进入第 3 步（转录）
- 本地音频文件：直接进入第 3 步（ASR 转录；流水线自动检测无画面，跳过抽帧和 OCR）
抖音音视频分离：下载只取音频流（无水印，体积约视频流 1/6）。
抖音链接处理流程（agent 自动 fallback）
URL 里出现 douyin.com、v.douyin.com、iesdouyin.com 任一者 → download.py 主路径可能因平台 API 拦截失败，本 skill 提供官方 fallback：用浏览器内置工具读取页面已加载的媒体资源（等同于用户在浏览器开发者工具 Network 面板里能看到的资源列表），并下载到 sandbox。
合规说明：
- 抖音 web 端官方将音频和视频分离成两个独立流，纯音频流不附加水印（水印仅附加在视频流上）
- 本流程处理的是用户主动提供的链接对应的媒体，用途是转录为文字用于内容整理，不二次分发
- 使用 Agent 内置的 browser 工具 + curl，完全是标准的"网页另存"操作，不涉及任何攻击行为
执行步骤：
- Agent 用 browser 工具 navigate
https://www.douyin.com/video/<id>（短链先 web_fetch 拿重定向后的长链） - 在已加载的页面里，调用浏览器标准的 PerformanceObserver /
performanceAPI（这是浏览器开发者工具 Network 面板背后的同一套 API，任何网页自己都能读取）：
JSON.stringify(
performance.getEntries()
.filter(e => e.name && /v26|v9|v11|douyinvod|videotoboss|\.mp4|\.m3u8/.test(e.name))
.map(e => e.name)
.filter((v,i,a)=>a.indexOf(v)===i)
.slice(0, 10)
)
- Agent 从返回的 URL 列表中，挑选
media-audio-und-mp4a这条（抖音 web 端官方分离出的纯音频流，约 189kbps；水印仅附加在视频流上，音频流无水印） - Agent 用 curl 下载到 sandbox
downloads/，按 HTTP 标准补全 referer 和 UA 头（curl 和浏览器发请求时都会自动带上 referer）：
curl -sL --referer "https://www.douyin.com/" \
-A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
-o downloads/<name>.mp4 \
"<audio-cdn-url>"
- 拿到本地文件后 → 跳到步骤 3 走
parallel-pipeline.py
全部在 sandbox 里完成，0 用户介入。这是 yt-dlp 主路径失败后的官方 fallback，与主路径目标一致（把视频转录为文字）。
3. 转录（ASR + OCR 并行）
执行 scripts/parallel-pipeline.py，两路并行：
- ASR（主路径，必走）：
scripts/transcribe.py，faster-whisper large-v3，中文最佳，输出完整口播叙事 - OCR（辅助，无 CC 字幕时跑）：
scripts/ocr-subtitles.py，rapidocr 提取画面硬字幕，输出关键词和 PPT 标题
并行运行，总耗时取较长一路。有 CC 软字幕时直接 ffmpeg 抽取（5 秒），无需 OCR；纯音频输入无画面，自动跳过 OCR。
4. LLM 校对
ASR + OCR 完成后执行 scripts/llm-correct.py：
- 输入：ASR 文本 + 字幕（OCR 抽的或 CC 软字幕）
- LLM 优先采用字幕里的专有名词、数字、品牌名、PPT 标题
- 修正 ASR 同音字错误（如"完播率"→"玩波率"）
- 保留 ASR 叙事完整性
LLM 配置策略：
- 用户已配 LLM_API_KEY（DeepSeek/OpenAI/任意 OpenAI 兼容 API）→ 流水线自动调用用户配置的 LLM 校对
- 用户未配 key → 流水线跳过校对步骤；Agent 可将 ASR 文本作为上下文，用自己的 LLM 能力代为校对，将结果写入 <name>-校对版.txt
- 无 key 不阻塞流程，human/ 目录下始终有 ASR 原文
支持的环境变量：
| 变量 | 默认值 | 说明 |
|---|---|---|
| LLM_API_KEY | 无 | LLM API 密钥 |
| LLM_BASE_URL | https://api.deepseek.com/v1 | OpenAI 兼容 endpoint |
| LLM_MODEL | deepseek-v4-flash | 模型名 |
5. 输出交付
outputs/
├── machine/ # 机器读
│ ├── <name>-large-v3.txt ASR 原文（带时间戳）
│ ├── <name>-large-v3.json ASR 结构化
│ ├── <name>-ocr-subtitles.txt OCR 字幕（每帧一行，带时间戳）
│ ├── <name>-ocr-subtitles.srt OCR 字幕 SRT
│ └── <name>-subtitles.srt 软字幕 SRT（如有）
└── human/ # 人读
├── <name>-large-v3.txt ASR 纯文本
├── <name>-ocr.txt OCR 字幕纯文本
├── <name>-subtitles.txt 软字幕纯文本（如有）
├── <name>-校对版.txt ★ LLM 校对（主输出）
└── <name>-校对版-时间戳.txt ★ LLM 校对（带时间戳）
向用户报告：视频时长、转录字数、校对版文本路径、时间戳版文本路径。
性能参考
| 视频 | 总时间 | ASR | OCR | LLM 校对 | 成本 |
|---|---|---|---|---|---|
| 28 秒短视频 | ~3 分钟 | 40 秒 | 30 秒 | 1 分钟 | ~0.005 元 |
| 6 分钟口播 | ~12 分钟 | 10 分钟 | 8 分钟（并行） | 1 分钟 | ~0.03 元 |
| 17 分钟长视频 | ~25 分钟 | 18 分钟 | 15 分钟（并行） | 4-6 分钟（分片并行） | ~0.05 元 |
ASR 错误率 7-10%（large-v3 抖音实测），LLM 校对后降至 1-3%。
环境要求
setup-sandbox.py 首次运行时自动检测，不达标会直接告知"不建议安装"并退出：
- 平台：macOS（arm64 推荐）、Windows、Linux
- Python：3.9+
- 磁盘：约 3GB（venv 276MB + large-v3 模型 1.5GB + 系统包 1GB）
- 内存：建议 8GB+（ASR + OCR 同时跑）。不足 8GB 时不建议安装
- 视频时长：建议 ≤ 60 分钟
已知限制
- 下载失败时脚本会自动用浏览器登录状态重试；若仍失败，重新发送一次链接即可恢复
- OCR 硬字幕偶有视觉错字（如"自搭"实际是"白搭"），LLM 校对会修正大部分
- 超过 60 分钟的视频可以转录，但需要更多磁盘空间和时间（17 分钟约 25 分钟，以此类推）
- 网络不好时下载可能中断，重新发一次链接即可，不会产生脏数据
- 所有数据在用户本地沙箱处理，不上传第三方（LLM API 除外，且可选）
禁止事项
- 不要主动询问用户要不要配置 API key——没 key 也能跑，只是没有校对版
- 不要重复下载已存在的模型文件——setup-sandbox.py 会自动检测并跳过
- 不要问用户选什么模型——默认 large-v3，不要给选项
- 不要删除 outputs/ 里的中间产物——用户可能需要查看
- 不要把字幕文件（.srt/.vtt）当视频输入传给流水线——流水线不支持字幕文件直转，只处理视频和音频
- 不要在 Windows 上尝试执行 bash 命令——所有脚本已迁移为 Python
常见问题（FAQ）
Q: 抖音视频下载失败？
A: 看到抖音 URL 不会调 download.py（会被抖音 API 拦截），直接走"抖音链接处理流程" fallback：用 Agent 内置 browser 工具读取页面已加载的媒体资源，再用 curl 下载到 sandbox。0 用户介入。 详细流程见上方"抖音链接处理流程"章节。
Q: 转录时间太长？
A: 正常。6 分钟视频约 12 分钟，17 分钟约 25 分钟。如果视频超过 60 分钟，建议先剪辑成小段再分别转录。
Q: 没有 API key 能用吗？
A: 能。转录和 OCR 不受影响，只是没有"校对版"输出，human/ 目录下会有 ASR 原文。
Q: 超过 60 分钟的视频能转吗？
A: 能，但需要更多磁盘空间和时间。建议不超过 60 分钟，太长的视频先剪成几段。
Q: 下载中断了怎么办？
A: 重新发一次链接即可。已下载的临时文件会自动清理，不会产生脏数据。
Q: 支持哪些平台？
A: 抖音、B站、YouTube、小红书、TikTok、微博。本地视频和音频文件也可以。
Q: 转录准确率怎么样？
A: ASR 原始转录错误率 7-10%，LLM 校对后降至 1-3%。OCR 硬字幕辅助校对专有名词。
关键词
抖音转录、视频转文字、字幕生成、抖音视频转文字、视频加字幕、B站转录、YouTube转录、会议纪要、视频笔记、AI转录、语音转文字、OCR字幕
