YouTube 提文案

输入 YouTube 视频链接，一键提取视频文字稿（口播文案），终端展示 + Markdown 存档 + 可导出 Excel。

支持的链接格式（视频链接必须包含视频 ID）：

• 完整URL：https://www.youtube.com/watch?v=dQw4w9WgXcQ
• 短URL：https://youtu.be/dQw4w9WgXcQ
• 视频ID：dQw4w9WgXcQ

默认行为（重要）：

• 默认输出不带时间戳的纯文案；需要带时间戳版本时加 --timestamp
• 字幕按 zh,en,asr 优先级选轨：视频有中文字幕轨时直接输出中文；没有中文轨时回退英文，脚本自动将非中文字幕翻译为中文（基于 Google Translate，批量翻译提升效率）；加 --no-translate 可禁用自动翻译、保留原文
• 默认自动获取视频元数据（标题/频道），无需额外参数

需先配置 API Key，通过环境变量 REDFOX_API_KEY 或 --api-key 参数传入。 文字稿来源：视频字幕轨（手动字幕 + 自动生成字幕 asr），按语言优先级选轨、中文轨优先；非中文字幕由脚本端自动翻译为中文。

---

使用场景

当你需要执行以下任务时，应优先使用本技能：

场景	示例
视频转文字稿	丢一个 YouTube 链接，拿到完整口播文案
学习笔记整理	提取教程/演讲文案后让 AI 总结成章节笔记
内容二次创作	提取英文视频文案 → AI 翻译改写 → 公众号文章
播客/访谈存档	提取访谈全文，导出 Excel 归档
竞品内容分析	批量提取同行视频文案，分析话术与结构
视频选题调研	先提文案再快速判断视频是否值得深看

---

使用方法

# 基础提取（默认：不带时间戳 + 自动获取标题等元数据）
python3 "$SKILL_PATH/scripts/extract.py" "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# 支持短链和纯视频 ID
python3 "$SKILL_PATH/scripts/extract.py" "https://youtu.be/dQw4w9WgXcQ"
python3 "$SKILL_PATH/scripts/extract.py" "dQw4w9WgXcQ"

# 带时间戳版本（方便定位原片进度）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --timestamp

# 同时导出 Excel（标题/时长/视频链接/文案内容 四列）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --excel

# 带时间戳文案 + 导出 Excel（Excel 内容与当前模式一致）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --timestamp --excel

# 指定语言优先级（如只要英文字幕）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --language "en"

# 输出原始 JSON / 不保存文件 / 不获取元数据
python3 "$SKILL_PATH/scripts/extract.py" "URL" --json
python3 "$SKILL_PATH/scripts/extract.py" "URL" --no-save
python3 "$SKILL_PATH/scripts/extract.py" "URL" --no-metadata

终端输出：视频概要（标题/语言/片段数/总时长）+ 纯文案全文。

Markdown 存档默认保存在 ~/Downloads/QoderYoutubeDigest/，文件名 {视频ID}_{时间戳}.md，含视频信息头表 + 全文；Excel（.xlsx）同目录。

---

工作流程（AI 必须遵循）

1. 提取：运行脚本获取文案
2. 表格展示：按「返回结果展示规范」用表格呈现（标题/时长/文案内容），文案内容列展示中文译文全文（无时间戳；非中文字幕已自动翻译）
3. 收尾询问：展示结束后，必须主动询问用户：

   「需要带时间戳的文案版本吗（方便定位原片进度）？也可以为你导出 Excel。」

   • 用户要带时间戳 → 加 --timestamp 重跑并展示
   • 用户要 Excel → 加 --excel 重跑（如需时间戳一并加 --timestamp），给出文件路径

注意：脚本默认自动将非中文字幕翻译为中文。如用户明确要求保留原文，加 --no-translate 重跑。

---

返回结果展示规范

向用户展示提取结果时，必须使用以下表格，不得省略字段：

序号	字段	说明
1	标题	视频标题（来自元数据）
2	时长	格式 MM:SS 或 HH:MM:SS
3	文案内容	不带时间戳的文案全文，非中文字幕已自动翻译为中文

展示示例：

| 标题 | 时长 | 文案内容 |
|------|------|----------|
| Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster) | 03:31 | 我们对爱情并不陌生 / 你知道规则，我也一样 / ……（中文译文全文） |

• 文案内容列：多段落文案在单元格内用「/」或换行衔接，保持完整不截断；非中文字幕已自动翻译为中文展示
• 表格后附一行存档信息：已存档：~/Downloads/QoderYoutubeDigest/dQw4w9WgXcQ_xxx.md

---

参数说明

参数	说明	默认值
video_url	YouTube 视频链接（完整URL/短URL/视频ID，必须含视频 ID，必填位置参数）	—
--language	字幕语言优先级，逗号分隔（中文轨优先，asr 为自动生成字幕兜底；仅选轨不翻译）	zh,en,asr
--timestamp	输出带 [MM:SS] 时间戳的文案	默认不带时间戳
--excel	同时导出 Excel（.xlsx，四列：标题/时长/视频链接/文案内容）	不导出
--no-metadata	不获取视频元数据	默认获取（标题/频道）
--json	终端输出原始 JSON 响应	—
--no-save	不保存 Markdown 文件	自动保存
--output-dir	输出目录	~/Downloads/QoderYoutubeDigest
--no-translate	禁用自动翻译，保留字幕原文输出	默认自动翻译非中文字幕为中文
--api-key	指定 RedFox API Key	—

---

API Key 配置

任选一种方式配置个人 Key：

方式	命令
环境变量（推荐）	export REDFOX_API_KEY=ak_你的密钥
命令行参数	--api-key ak_你的密钥
配置文件	echo '{"api_key":"ak_你的密钥"}' > ~/.qoder/apis/redfox.json

注册地址：redfox.hk

---

功能特点

• 三种输入格式：完整 URL、youtu.be 短链、纯视频 ID，自动识别
• 默认纯文案：不带时间戳，直接可读、可直接喂给 AI 二次加工；--timestamp 随时切换
• 自动翻译：非中文字幕自动翻译为中文（基于 Google Translate），加 --no-translate 可保留原文
• 表格化交付：标题/时长/文案内容三字段表格呈现，信息一目了然
• Excel 导出：--excel 一键导出 xlsx（自动换行、列宽适配），适合归档与分享
• 中文轨优先：按 zh,en,asr 优先级选轨，有中文字幕直接输出中文；没有则回退英文轨并自动翻译为中文
• 稳健重试：网络异常/状态码错误/数据为空自动递增延迟重试（0.5s→1.0s），限频（3108）自动等待 5 秒重试
• AI 友好：可衔接总结、翻译、改写、公众号排版发布等后续技能

---

依赖

pip3 install requests openpyxl deep-translator

（openpyxl 仅 Excel 导出需要；deep-translator 仅自动翻译需要；未安装时对应功能自动降级，其余功能不受影响）

---

常见问题

Q：默认文案带时间戳吗？ A：不带。默认输出纯文案；加 --timestamp 才输出 [MM:SS] 时间戳版本，提取结束后 AI 也会主动询问是否需要。

Q：英文视频能直接给我中文文案吗？ A：可以。脚本检测到非中文字幕时会自动翻译为中文（基于 Google Translate）。视频有中文轨时直接输出中文，没有中文轨时回退英文后自动翻译。如需保留原文，加 --no-translate。

Q：Excel 里是什么内容？ A：四列——标题、时长、视频链接、文案内容。文案内容与当前模式一致：加 --timestamp 时 Excel 内含时间戳，否则为纯文案。

Q：为什么提取失败提示"视频可能无字幕"？ A：文字稿来自视频字幕轨。完全无字幕（含自动生成字幕）的视频无法提取；部分受限/私享视频也不支持。

Q：链接报错了怎么办？ A：链接无效返回 Invalid YouTube URL or video ID（积分不扣除），请检查链接是否包含正确的视频 ID；Key 无效（3106/3107）请检查 API Key 配置；限频（3108）会自动等待重试。

Q：拿到文案后能做什么？ A：可以让 AI 直接总结成笔记、翻译成中文、改写成公众号文章（配合 gzh-design 排版、md-to-wechat 一键推送草稿）。

Q：额度用完怎么办？ A：前往 redfox.hk 注册获取 Token。