sampx/youtube-master

youtube-master — YouTube 字幕获取 + 视频总结

一键获取 YouTube 视频字幕并按意图总结。字幕通过 InnerTube API 直接获取，无 API key，自动处理反爬和缓存。

Script Directory

{baseDir} = SKILL.md 所在目录路径。${BUN_X} 运行时检测：已安装 bun → bun；否则提示安装。

脚本位于 {baseDir}/scripts/：

• main.ts — 字幕获取 CLI（主入口）

核心流程

Step 1: 识别 YouTube URL

支持多种格式，正则或肉眼识别均可：

• 完整 URL：https://www.youtube.com/watch?v=VIDEO_ID
• 短 URL：https://youtu.be/VIDEO_ID
• Shorts：https://www.youtube.com/shorts/VIDEO_ID
• 嵌入 URL：https://www.youtube.com/embed/VIDEO_ID
• 纯视频 ID：VIDEO_ID（11 字符，字母数字混合）

Step 2: 获取字幕

固定输出到 .wopal-space/.tmp/，避免污染工作空间：

${BUN_X} {baseDir}/scripts/main.ts '<youtube-url>' \
  --languages zh,en \
  --chapters \
  --output-dir .wopal-space/.tmp/youtube-transcript

关键点：

• URL 必须单引号（zsh glob 问题，? 会触发匹配失败）
• 默认参数：--languages zh,en --chapters（中文优先、按章节分段）
• 输出目录固定：.wopal-space/.tmp/youtube-transcript

Step 3: 读取字幕文件

脚本完成后读取：

• meta.json — 视频元数据（标题、频道、时长、章节、封面路径）
• transcript.md — 格式化字幕（按章节分段、带时间戳）

路径格式：.wopal-space/.tmp/youtube-transcript/{channel-slug}/{title-slug}/

Step 4: 判断用户意图

根据用户请求选择总结模式：

• "总结"/"概要"/"讲了什么" → 速览（默认）
• "详细总结"/"完整分析" → 详细
• "分析"/"知识点"/"教程" → 分析
• 提出具体问题 → 信息提取

Step 5: 输出总结

读取 references/summary-templates.md，选择对应模板：

1. 提取 meta.json 中的标题、频道、时长、URL
2. 处理 transcript.md 内容
3. 按模板格式输出总结

总结模式

| 模式 | 适用场景 | 输出结构 | |------|----------|----------| | 速览（默认） | 快速了解视频核心观点 | 标题 + 3-5 要点 + 推荐指数 | | 详细 | 深入理解完整内容 | 章节总结 + 要点列表 + 术语解释 | | 分析 | 教程/讲座/技术视频 | 知识点表格 + 实操步骤 + 延伸资源 | | 信息提取 | 回答具体问题 | 直接回答，引用时间戳原文 |

长视频（字幕超 5000 字）优先用速览模式；如需详细分析可分章节处理。

字幕获取选项

| 选项 | 说明 | 默认 | |------|------|------| | --languages <codes> | 语言优先级，逗号分隔 | en | | --chapters | 按视频描述中的章节分段 | off | | --no-timestamps | 移除时间戳标记 | off | | --translate <code> | 翻译字幕（如 zh-Hans） | | | --list | 列出可用字幕语言（不下载） | | | --speakers | 输出 speaker-identification 格式 | off | | --refresh | 强制刷新缓存 | | | --output-dir <dir> | 输出目录 | youtube-transcript |

常用组合：

# 列出可用字幕
${BUN_X} {baseDir}/scripts/main.ts '<url>' --list

# 英文字幕 + 章节 + 无时间戳
${BUN_X} {baseDir}/scripts/main.ts '<url>' --languages en --chapters --no-timestamps

# 中文翻译
${BUN_X} {baseDir}/scripts/main.ts '<url>' --translate zh-Hans

输出目录结构

.wopal-space/.tmp/youtube-transcript/
├── .index.json                     # 视频ID → 目录映射（缓存查找）
└── {channel-slug}/{title-slug}/
    ├── meta.json                   # 元数据（title, channel, duration, chapters）
    ├── transcript-raw.json         # 原始字幕片段（缓存）
    ├── transcript-sentences.json   # 按句子分割的字幕
    ├── transcript.md               # Markdown 字幕（章节分段）
    └── imgs/cover.jpg              # 视频封面（可选）

缓存机制：首次获取后保存 raw 数据，后续请求直接读取缓存（无需网络请求）。--refresh 强制刷新。

错误处理

| 场景 | 处理方式 | |------|----------| | 无字幕 | 告知用户视频无字幕，建议 --list 查看可用语言 | | 语言不存在 | 建议先用 --list 查看可用字幕，然后选择正确语言代码 | | 视频不可用 | 明确报错：已删除/私有/地区限制 | | 反爬/Blocked | 脚本自动重试 alternate clients + yt-dlp 兜底；如仍失败提示设置 YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER | | 年龄限制 | 需要登录验证，提示设置浏览器 cookies |

反爬失败时的解决方案：

# 使用浏览器 cookies
YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari \
  ${BUN_X} {baseDir}/scripts/main.ts '<url>' --languages zh,en

Speaker Identification（可选）

--speakers 模式需要 AI 后处理：

1. 运行脚本获取 raw transcript：

   ${BUN_X} {baseDir}/scripts/main.ts '<url>' --speakers --output-dir .wopal-space/.tmp/youtube-transcript
   

2. 读取 {baseDir}/prompts/speaker-transcript.md

3. 处理 raw transcript：识别对话者（从标题/频道/描述提取姓名）、标注对话轮次、按章节分段

4. 输出带 speaker label 的格式化字幕

此模式适用于访谈/对话类视频。

参考

• 总结模板：references/summary-templates.md（选择总结模式时读取）
• Speaker 识别提示词：prompts/speaker-transcript.md（仅 --speakers 模式读取）