YouTube Transcript (yt-dlp captions)

核心用法

yt_transcript 是一个专门用于提取YouTube视频字幕/转录文本的命令行工具。它通过封装 yt-dlp 实现核心功能，支持直接解析视频URL或11位视频ID。运行时优先获取创作者上传的手动字幕，若不存在则自动降级至YouTube自动生成的字幕。

输出格式灵活：默认返回带时间戳的JSON分段结构（start、duration、text），也可通过 --text 切换为纯文本模式，--no-ts 可移除时间戳。语言筛选通过 --lang 参数实现。所有结果默认缓存至本地SQLite数据库，避免重复请求。

显著优点

• 权威数据源：直接对接YouTube官方字幕流，不依赖第三方转录服务商，数据可信度与隐私可控性更强
• 双重降级机制：手动字幕 → 自动生成字幕 → YouTube网页版转录面板（youtubei get_transcript），提升覆盖率
• 隐私优先设计：明确不调用外部API，视频ID/URL仅与YouTube官方交互
• 本地缓存加速：SQLite持久化存储，重复查询毫秒级响应
• 安全路径约束：cookies与缓存路径被严格限制在批准目录（~/.config/yt-transcript/ 及 {baseDir}/cache/），降低凭证泄露风险

潜在缺点与局限性

• 依赖外部工具：必须预先安装 python3 与 yt-dlp，对非技术用户门槛较高
• 网络访问受限：VPS或数据中心IP频繁触发YouTube反爬机制，需额外配置cookies文件
• 字幕覆盖盲区：若视频创作者关闭字幕且自动识别不可用（如音乐视频、低质量音频），则完全无法提取
• 无实时转录能力：仅处理已有字幕，不支持音频直接转文本（需依赖YouTube的语音识别结果）
• Cookie管理负担：虽然设计为"可选"，但实际生产环境（服务器部署）几乎必需，且需手动维护Netscape格式cookies.txt

适合人群

• 研究人员、内容分析师：批量提取视频文本用于NLP分析、关键词索引
• 开发者构建AI摘要工作流：将YouTube内容转为LLM可处理的文本输入
• 隐私敏感用户：拒绝第三方转录服务，坚持本地/官方直连方案
• 多语言学习者：通过 --lang 提取特定语言字幕辅助学习

常规风险

| 风险类型 | 说明 |

|---------|------|

| **账号封禁** | 高频请求+数据中心IP易触发YouTube风控，cookies对应的Google账号可能被限制 |

| **凭证泄露** | cookies.txt含敏感登录态，若误提交至版本控制或共享目录将导致账号接管 |

| **版权合规** | 提取的转录文本仍受原视频版权约束，大规模分发需评估合理使用边界 |

| **依赖失效** | `yt-dlp` 需随YouTube前端更新频繁迭代，长期未更新可能导致功能断裂 |

| **缓存膨胀** | SQLite数据库无自动清理机制，高频使用需手动维护存储空间 |

核心用法

yt_transcript 是一款基于 yt-dlp 的 YouTube 字幕提取工具，支持从现有字幕（手动或自动生成）获取转录文本。主要功能包括：

• 字幕来源优先级：优先获取人工字幕，回退至自动生成字幕
• 输出格式：JSON 分段格式（默认）或纯文本（--text）
• 时间戳控制：可选包含或隐藏时间戳（--no-ts）
• 本地缓存：使用 SQLite 数据库存储结果，加速重复查询
• Cookie 认证：支持通过 cookies.txt 应对 YouTube 反爬虫机制

典型命令：

python3 yt_transcript.py <youtube_url_or_id> --lang en --text

显著优点

1. 直接依赖成熟工具：基于 yt-dlp（youtube-dl 活跃分支），该工具社区维护良好、更新频繁
2. 灵活的输出选项：JSON 适合程序化处理，纯文本便于直接阅读
3. 本地缓存机制：SQLite 缓存减少重复请求，提升效率
4. 安全意识：Cookie 路径强制限制在 ~/.config/yt-transcript/，避免意外泄露
5. 输入验证：仅接受标准 YouTube URL 或 11 位视频 ID，降低注入风险

潜在缺点与局限性

严重：文档与实现不一致

SKILL.md 明确声明"此发布版本不调用第三方转录服务"，但安全审计发现代码中存在三个第三方备用通道（yt-to-text.com、downsub.com、noteey.com）。当 YouTube 直接访问失败时，视频 ID 会被发送至这些非官方服务，构成数据外泄风险。

其他局限：

• 依赖用户自行安装 yt-dlp，环境配置门槛存在
• 子进程调用 yt-dlp 存在潜在安全风险（虽已做输入验证）
• 第三方服务的隐私政策不明，数据保护水平未知
• 缓存可能构成用户观看历史记录，无自动过期机制

适合人群

• 需要批量获取 YouTube 字幕的研究者、内容创作者
• 具备技术背景、能自行审查代码的用户
• 在受控网络环境（非敏感 IP）使用的场景
• 能接受手动配置 Cookie 应对反爬虫的高级用户

不适合：对数据隐私要求极高、无法容忍任何第三方数据传输的用户。

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 第三方数据外传 | **高** | 备用通道自动发送视频 ID 至非 YouTube 服务 |

| 隐私合规 | 中 | 未完整披露第三方数据收集，GDPR/CCPA 存疑 |

| 子进程执行 | 中 | `subprocess.run` 调用外部程序 |

| Cookie 泄露 | 低 | 路径已限制，但需用户自律存储位置 |

| 来源可信度 | 信息 | T3 级个人开发者，社区验证有限 |

建议：在隔离环境中运行，使用 --no-third-party 类选项（如可用）禁用备用通道，或优先审查代码移除第三方调用后再使用。