YouTube视频转录与内容提取:字幕优先、Whisper兜底、批量处理、结构化笔记
---
name: youtube-content
description: "YouTube视频转录与内容提取:字幕优先、Whisper兜底、批量处理、结构化笔记"
platforms: [linux, macos, windows]
---
# YouTube Content
从 YouTube 视频提取内容,转化为结构化输出(笔记、摘要、Thread、博客文章)。
## When to Use
- 用户分享 YouTube 链接(任何格式:标准URL、youtu.be短链、shorts、embeds、纯video ID)
- 需要视频摘要、转录、章节提取
- 需要从视频生成结构化笔记、Twitter/X thread、博客文章
- 批量处理多个视频
## 核心架构:字幕优先路由
```
YouTube URL
│
├── 有字幕(zh-CN/zh-Hans/zh-Hant auto-subs)
│ └── 下载字幕(即时,无需音频) → 生成笔记
│
└── 无字幕
└── 下载音频 → Whisper 转录 → 生成笔记
```
**永远先检查字幕可用性**——字幕是即时的(无需下载),比 Whisper 更准确(尤其是中文自动字幕),每视频节省 ~20min。
## 快速开始
### 依赖
```bash
pip install youtube-transcript-api faster-whisper
```
### 单视频处理
```bash
# 1. 检查字幕
/opt/homebrew/Caskroom/miniconda/base/bin/yt-dlp --cookies-from-browser chrome \
--proxy "http://127.0.0.1:$PROXY" --list-subs "URL" 2>&1 | grep -E "(has |zh-CN|zh-Hans)"
# 2a. 有字幕 → 直接下载
/opt/homebrew/Caskroom/miniconda/base/bin/yt-dlp --cookies-from-browser chrome \
--proxy "http://127.0.0.1:$PROXY" \
--write-auto-sub --sub-lang "zh-CN,zh-Hans,zh-Hant" --convert-subs srt --skip-download \
-o "%(id)s.%(ext)s" "URL"
# 2b. 无字幕 → 下载音频 + Whisper
# 下载音频
/opt/homebrew/Caskroom/miniconda/base/bin/yt-dlp --cookies-from-browser chrome \
--proxy "http://127.0.0.1:$PROXY" \
-x --audio-format mp3 --audio-quality 0 -o "%(id)s.%(ext)s" "URL"
# Whisper 转录(后台运行)
python3 -c "
import faster_whisper
model = faster_whisper.WhisperModel('medium', device='cpu', compute_type='int8')
segments, info = model.transcribe('VIDEO_ID.mp3', language='zh', beam_size=5, vad_filter=True)
with open('VIDEO_ID.txt', 'w') as f:
for seg in segments:
f.write(seg.text.strip() + '\n')
print('=== WHISPER DONE ===')
"
```
### 字幕抓取(Python脚本)
`scripts/fetch_transcript.py` — 通过 youtube-transcript-api 获取字幕,支持多种 URL 格式:
```bash
python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only # 纯文本
python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps # 带时间戳
python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --language zh,en # 指定语言
```
输出格式详见 `references/output-formats.md`。
## 输出格式
根据用户请求选择,默认为**结构化笔记**:
| 格式 | 适用场景 | 特点 |
|------|----------|------|
| **结构化笔记** | 中文视频默认 | 分层大纲、要点高亮、数据表格 |
| Summary | 英文/简短视频 | 5-10句概述 |
| Chapters | 演讲/TED | 时间戳+章节标题 |
| Chapter summaries | 长视频 | 每章+摘要段落 |
| Thread | 社交分享 | Twitter/X 编号格式,每条<280字符 |
| Blog post | 内容创作 | 完整文章,带引言和要点 |
| Quotes | 精选金句 | 带时间戳的名句 |
模板和详细规则见 `references/output-formats.md`。
## 完整处理流程
1. **获取**字幕(优先)或下载音频
2. **转录**(如需要 Whisper)
3. **验证**输出非空且完整
4. **转换**为目标格式
5. **交付**给用户
**长字幕处理**(SRT >1000行):用 `delegate_task` 子代理分段读取(每次500行)生成笔记,避免撑爆主上下文。
## 批量处理
### 代理检测(必须首先执行)
```bash
PROXY=$(networksetup -getwebproxy Wi-Fi | grep -E '^Port' | awk '{print $2}')
```
**⚠️ 代理端口不固定**——取决于当前 VPN/代理工具配置。所有 yt-dlp 命令必须使用 `$PROXY` 变量。
### 🚨 关键规则:禁止并行 Whisper
**Whisper 会占满所有 CPU 核心(300%+),两个并行 Whisper 都会慢 2-3 倍,总耗时比顺序执行更差。**
**每次启动 Whisper 前:**
1. `process(action='list')` 检查是否有 python 进程在运行
2. 如果有 Whisper 进程,**等待它完成**再启动下一个
3. 3+ 个视频 → 使用 `batch_whisper.py`(模型只加载一次)
### 批处理策略
#### 大批量(10+ 个 Whisper 视频):两阶段(推荐)
```
Phase 1: 下载所有音频(单个后台 for 循环)
Phase 2: batch_whisper.py 后台运行,同时用 delegate_task 处理字幕视频笔记
Phase 3: Whisper 全部完成 → 并行 delegate_task 生成所有笔记
```
#### 中批量(3-9 个):batch_whisper.py + 增量笔记
```
Phase 1: 下载所有音频
Phase 2: batch_whisper.py(后台)
Phase 3: 每出现新 .txt → delegate_task 生成笔记
```
#### 小批量(1-2 个):流水线
```
Whisper A 完成 → 同时:delegate_task(A) + Whisper B
```
### batch_whisper.py
`scripts/batch_whisper.py` — 批量 Whisper 转录脚本,模型只加载一次,顺序处理:
```bash
# 找出所有缺 .txt 的 mp3 文件
cd youtube_downloads
VIDEOS=$(for f in *.mp3; do vid="${f%.mp3}"; [ ! -f "${vid}.txt" ] && echo "$f"; done)
# 单后台进程运行
python3 SKILL_DIR/scripts/batch_whisper.py $VIDEOS \
--language zh --model medium --device cpu --compute-type int8
```
后台运行:`background=true, notify_on_complete=true, timeout=3600`
### 子代理笔记生成模板
```python
goal: """读取 /path/to/VIDEO_ID.txt 转录文件,整理成结构化中文笔记。
视频信息:
- 标题:<video title>
- 时长:<duration>
- 频道:<channel name>
要求:
1. 读取完整转录文件(分段读取每次500行)
2. 整理成结构化笔记:📌核心主题、📊关键数据、🔍主要观点、💡关键洞察
3. 忠实原始内容,写入 /path/to/VIDEO_ID_notes.md"""
context: "读取转录文本并整理成结构化中文笔记"
toolsets: ["file"]
```
### 队列状态沟通
**紧凑格式**(默认):`📊 队列更新:✅ N完成 | 🔄 1转录中 | ⏳ X排队`
**表格格式**(≤5项时):
```
| # | ID | 标题 | 时长 | 状态 |
```
状态 emoji:✅ 完成、🔄 处理中、⏳ 排队、⚠️ 错误
## 错误处理
| 错误 | 处理 |
|------|------|
| 无字幕/字幕已禁用 | 自动走 Whisper 流程,无需确认 |
| 私有/不可用视频 | 告知用户验证 URL |
| Members-only | 告知用户需要频道会员,无法绕过 |
| "Sign in to confirm you're not a bot" | 更新 yt-dlp + `--remote-components ejs:github` |
| Whisper 产出空文件(0字节) | 删除重跑,已验证重跑通常成功 |
| Whisper 截断(覆盖率<90%) | 检查最后时间戳 vs 音频时长,不够则重跑 |
更多 yt-dlp/Whisper 坑点和解决方案见 `references/whisper-transcription.md`。
## 环境特定注意事项
- **macOS 代理**:yt-dlp 不继承系统代理,必须显式传 `--proxy`,且端口不固定
- **yt-dlp 双版本陷阱**:macOS 上有 Homebrew(旧)和 conda(新)两个版本,始终用 conda 版本
- **Chrome cookies**:`--cookies-from-browser chrome` 可能静默返回 0 cookies(解密失败),需检查
## 进阶功能
### 标题党检测
部分中文视频标题与内容不符(如标题"2026经济崩盘"实际讲乐观内容)。`delegate_task` 子代理通常能检测到这种不匹配,在笔记中加 ⚠️ 标记。
### 飞书知识库集成
大批量完成后,可整合写入飞书知识库(需 `lark-wiki` + `lark-doc` skills + user auth scopes)。
don't have the plugin yet? install it then click "run inline in claude" again.