用途
video-transcribe 用于获取视频中最忠实的带时间戳文字稿，并明确告知该文字稿是否可信。它支持 YouTube URL、演讲视频或本地视频文件。当用户想要视频里的原话时使用，例如“转写这个”“给我文字稿”“他们说了什么”“抓取字幕”。
不适用场景：用户想要书面笔记或摘要（应使用 video-notes），或想要画面与屏幕文字（应使用 video-keyframes）。如果用户要的是笔记，video-notes 会自行调用本技能，不要直接运行本技能。
主要能力
- 按优先级逐级获取文字稿：创作者手动字幕 → 视频自身语言的自动字幕 → 本地 ASR（Apple Silicon 上使用带 Metal 的 whisper.cpp，否则使用 faster-whisper）。
- 从不使用自动翻译字幕。YouTube 将翻译字幕命名为
<目标语言>-<源语言>（如 en-de 表示“来自德语的英语”），机器翻译叠加机器转写会放大两种错误率。脚本会先解析视频自身语言；当 yt-dlp 报告 language: NA（常见情况）时，回退到翻译列表的共享源语言子标签。 - 输出 transcript.json（毫秒级时间片段）和 metadata.json。
- 给出质量判定：pass、warning 或 fail，并附带原因代码。
- 采集与质量判定完全确定性，不涉及模型。
使用方式
运行提取脚本：
python3 "${CLAUDE_SKILL_DIR}/scripts/fetch_transcript.py" "<url-or-file>" --out <workdir>
常用参数：
--lang de：视频未声明语言时的首选语言。--asr-model medium：音频较难时使用。--no-asr：失败而非转写。--force：覆盖已有输出。--cookies-from-browser chrome和--sleep-requests 2：应对 IP 被限流或触发机器人检查，作用于每一次 yt-dlp 调用。
在用户期望输出位置旁创建 <workdir>，并在创建时写入包含 * 的 .gitignore，避免污染其仓库。
脚本会打印 JSON 摘要；失败时以非零退出码结束，并在 stderr 输出 {"error","message","fix"}。请按 fix 操作，不要自行发挥。
使用前先读质量判定
quality 字段为 pass、warning 或 fail：
- pass：直接使用。
- warning：可以使用，但在回答中向用户复述原因代码。
- fail：退出码为 1。不要在其上构建任何内容，说明原因并提供修复方案。
原因代码包括：empty_transcript、suspiciously_short、short_for_duration、low_characters_per_minute、highly_repetitive、repetitive、very_low_timed_coverage、low_timed_coverage、large_segment_gap。
highly_repetitive 几乎总意味着两种情况之一：Whisper 在静音处循环，或滚动字幕未去重。两者都会使文字稿无法用于引用。可用 --asr-model medium 重试，或直接报告。
报告结果
告知用户文字稿来自哪一级——manual、auto 或 asr——以及语言。手动字幕是创作者自己的文本；asr 文字稿是猜测。这一区别影响用户对引用的信任程度。
字幕优先级阶梯及顺序原因
- 手动/创作者字幕：有真实标点、大小写和说话人标签。
- 视频自身语言的自动字幕：无标点，但时间对齐。
- 本地 ASR（Apple Silicon 上使用带 Metal 的 whisper.cpp，否则使用 faster-whisper）。
详细选择规则见 references/caption-ladder.md。
输出
<workdir>/
├── transcript.json # {kind, track, quality:{status,reasons,metrics}, segments:[{start_ms,end_ms,text}]}
└── metadata.json # {source, video_id, title, channel, url, duration_s, upload_date, language, chapters, ...}
时间戳为整数毫秒。面向人类时渲染为 HH:MM:SS；不要把格式化字符串作为事实来源存储，也不要自行计算时间戳——使用文件中的值。
失败模式
- missing_dependency：缺少 yt-dlp / ffmpeg。运行修复命令，不要继续。
- bot_check：YouTube 返回机器人挑战。执行
yt-dlp -U，然后使用--cookies-from-browser chrome；数据中心 IP 无解。 - rate_limited：字幕请求返回 HTTP 429。实测重试、更换客户端和 cookies 均无效。需更换网络或等待数小时。ASR 仍可用。
- restricted：私有/仅会员/年龄限制。需要浏览器 cookies，或改用本地文件。
- no_asr_backend：无字幕且无 Whisper。按 fix 安装后端，或接受无文字稿。
- transcript_quality_fail：质量门禁拒绝。报告原因代码，不要在其上构建。
另外两点：
- yt-dlp 需要 JS 运行时。近期版本警告无 JS 运行时的提取已弃用，且部分格式会缺失。若提取质量下降，可安装 deno。
- 零字节字幕文件不是文字稿。脚本会删除空产物，而不是将其解析为看似成功的空结果。
适用场景与限制
适用于用户可访问内容的个人笔记。从 YouTube 下载与其服务条款冲突，字幕可能受版权保护。不要用它整体重新发布文字稿。