youtube-analysis

YouTube 分析

从 YouTube 视频中提取文字稿，并生成结构化概念分析，包括核心观点、论据、技术术语、要点和多层次摘要，全程无需 API 密钥或 MCP 服务。

参考文件

文件	用途
scripts/fetch_transcript.py	核心文字稿与元数据获取工具（CLI + 可导入）
scripts/analyze_video.py	编排工具：获取 → 组织结构 → 导出脚手架
scripts/utils.py	URL 解析、时间戳格式化、文字稿分块
references/analysis-patterns.md	各类视频的提示词模式
assets/output-template.md	最终输出的 Markdown 模板

工作流

User provides YouTube URL
        │
        ▼
┌─────────────────────┐
│  Step 0: Deps check │
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 1: Parse URL  │
└────────┬────────────┘
         ▼
┌─────────────────────┐     ┌──────────────┐
│  Step 2: Transcript │────▶│  yt-dlp      │
│  (youtube-t-api)    │fail │  (fallback)  │
└────────┬────────────┘     └──────┬───────┘
         │◀───────────────-────────┘
         ▼
┌─────────────────────┐
│  Step 3: Metadata   │
│  (yt-dlp --dump-json│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 4: Claude     │
│  analyzes transcript│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 5: Export MD  │
└─────────────────────┘

步骤 0：确保依赖已安装

运行任何脚本前，请确认已安装依赖：

uv pip install youtube-transcript-api yt-dlp -q

或者直接使用 uv run 运行脚本：

uv run --with youtube-transcript-api --no-project python scripts/fetch_transcript.py "URL"

验证：

python -c "from youtube_transcript_api import YouTubeTranscriptApi; print('OK')"
yt-dlp --version

步骤 1：解析并验证 URL

使用 scripts/utils.py:parse_youtube_url() 提取视频 ID。支持以下格式：

格式	示例
标准观看页	youtube.com/watch?v=dQw4w9WgXcQ
短链接	youtu.be/dQw4w9WgXcQ
Shorts	youtube.com/shorts/dQw4w9WgXcQ
嵌入式	youtube.com/embed/dQw4w9WgXcQ
直播	youtube.com/live/dQw4w9WgXcQ
带参数	youtube.com/watch?v=dQw4w9WgXcQ&t=120&list=PLxxx
纯 ID	dQw4w9WgXcQ
移动版	m.youtube.com/watch?v=dQw4w9WgXcQ
音乐	music.youtube.com/watch?v=dQw4w9WgXcQ

如果解析失败，请让用户提供标准格式的 URL。

步骤 2：提取文字稿

运行 fetch_transcript.py 获取文字稿：

cd <skill_dir>/scripts
python fetch_transcript.py "YOUTUBE_URL" --lang en

脚本会将 JSON 输出到 stdout。脚本会：

1. 主要方式：使用 youtube-transcript-api 直接抓取字幕（无需 API 密钥）
2. 备用方式：如果主要方式失败，则使用 yt-dlp --write-sub --write-auto-sub 提取字幕文件
3. 语言处理：优先尝试请求的语言，失败后回退到任何可用的文字稿

返回的 JSON 包含带时间戳的单独片段，以及合并后的 transcript_text 字段。

或者作为模块导入（analyze_video.py 会使用）：

from fetch_transcript import fetch_video
data = fetch_video("https://youtube.com/watch?v=VIDEO_ID", lang="en")

步骤 3：提取元数据

fetch_transcript.py 会通过 yt-dlp --dump-json 自动获取元数据：

• 标题、频道名称
• 时长（秒）
• 上传日期（YYYY-MM-DD）
• 描述（脚手架中显示前 500 个字符）
• 观看次数
• 标签

无需单独操作——fetch_video() 会返回所有内容。

步骤 4：概念分析

这部分由你（Claude）完成。 脚本提供原始数据；分析工作由你执行。

分析深度

根据用户的要求或视频时长选择：

深度	适用场景	要填写的部分
quick	用户希望快速了解概况，或视频时长 < 10 分钟	TL;DR、核心概念、要点
standard	大多数视频的默认选项	模板中的所有部分
deep	用户希望深入解析，或视频时长 > 30 分钟	所有部分 + 按时间戳逐段分析

分析流程

1. 阅读 JSON 输出中的完整转录文本
2. 识别视频类型（或使用用户提供的提示）。有关特定类型的指导，请参阅 references/analysis-patterns.md
3. 提取关键概念：主要观点、论据和主张——每项作为一个项目符号，并附简短说明
4. 识别技术术语：视频中给出的定义
5. 摘录重要陈述：转述关键引述，并标注大致时间戳
6. 综合要点：观众应考虑采取的行动
7. 撰写 TL;DR：用一到三句话概括核心信息
8. 推荐相关主题：根据提及的概念，指出观众接下来可以深入了解的内容

深度分析

使用 utils.chunk_transcript() 将转录文本拆分为 5 分钟的片段，然后为每个片段进行分析并标注时间戳：

from utils import chunk_transcript
chunks = chunk_transcript(data["transcript"], chunk_minutes=5)
for chunk in chunks:
    print(f"[{chunk['start_formatted']} - {chunk['end_formatted']}]")
    print(chunk["text"])

或者使用 --depth deep 运行编排器：

python analyze_video.py "YOUTUBE_URL" --depth deep

视频类型模式

类型	重点提取内容	参阅
讲座	论点、论据、引文、定义	references/analysis-patterns.md
教程	步骤、工具、先决条件、注意事项	references/analysis-patterns.md
访谈	观点、分歧、观点归属	references/analysis-patterns.md
播客	话题脉络、意见、建议	references/analysis-patterns.md
技术演讲	架构、权衡、基准测试、经验教训	references/analysis-patterns.md
圆桌讨论	共识与分歧、各位发言者的观点	references/analysis-patterns.md

有关各类型的详细提取指南，请阅读 references/analysis-patterns.md。

第 5 步：导出为 Markdown

编排器会生成一个模板：

cd <skill_dir>/scripts
python analyze_video.py "YOUTUBE_URL" --output ./analysis.md --depth standard --type auto

标志：

• --output PATH：写入位置（默认：./{sanitized_title}.md）
• --depth quick|standard|deep：分析深度
• --type auto|lecture|tutorial|interview|podcast|tech-talk|panel：视频类型提示
• --lang CODE：转录文本语言（默认：en）
• --json：输出原始 JSON，而非 Markdown 模板

模板包含已填充的元数据和 [TO BE ANALYZED] 占位符。Claude 会用实际分析结果替换这些占位符。

推荐工作流：运行 fetch_transcript.py 获取 JSON，在上下文中进行分析，然后直接使用 assets/output-template.md 作为结构指南，生成最终 Markdown。编排器适用于批量处理，或用户需要将内容写入文件时。

错误处理

错误	退出代码	原因	解决方法
URL 解析失败	1	URL 格式无效或不受支持	请用户提供标准的 YouTube URL
无转录文本	2	视频没有字幕（手动或自动生成）	告知用户；建议更换视频
视频不可用	1	视频为私有、已删除或受到地域限制	告知用户相关限制
年龄限制	1	需要身份验证	告知用户；yt-dlp 可能可以通过 Cookie 使用
元数据获取失败	0	yt-dlp 网络问题	转录仍可正常使用；元数据显示为“Unknown”
语言不可用	0	请求的语言不可用	自动回退到可用语言
未安装 yt-dlp	1	缺少依赖项	执行第 0 步安装依赖项

限制

• 无法进行视觉分析：仅处理转录文本；不会捕获幻灯片、图表、屏幕上的代码和演示内容。相关时请在输出中注明。
• 自动字幕质量：自动生成的字幕可能包含错误，尤其是技术术语、专有名词和非英语口音。
• 音乐视频：歌词可能没有字幕。仅包含音乐的内容会产生较差的结果。
• 直播：正在进行的直播可能没有完整转录文本，或无法获取转录文本。
• 速率限制：向 YouTube 发送过多请求可能会触发临时屏蔽。处理多个视频时，请间隔发送请求。
• 语言覆盖范围：英语的效果最佳。其他语言的效果取决于字幕的可用性和质量。
• 说话人归属：转录文本很少标明具体说话人。Claude 会在可能的情况下根据上下文推断。