核心用法
baoyu-youtube-transcript 是一款专用于下载 YouTube 视频字幕、转录文本和封面的命令行工具。用户只需提供视频 URL 或视频 ID，即可通过 InnerTube API 直接获取官方字幕数据，无需申请 API Key 或登录浏览器。工具支持多种输出格式（Markdown、SRT 字幕文件），可指定语言优先级、开启时间戳、按章节分段，甚至通过 AI 后处理实现说话人识别。
典型工作流程为：用户输入 YouTube 链接 → 工具自动解析视频信息 → 下载并缓存原始字幕数据 → 根据参数生成格式化输出。首次获取后，所有数据（元信息、原始字幕、分段句子、封面图）均缓存至本地目录，后续换格式输出无需重复请求网络，大幅提升效率。
显著优点
1. 零配置开箱即用：无需 YouTube API Key，不依赖浏览器环境，直接调用 YouTube 内部 API，降低使用门槛。
2. 多语言与翻译支持：可指定语言优先级（如 zh,en,ja），支持自动翻译到目标语言，满足跨语言内容处理需求。
3. 智能缓存机制：首次下载后自动缓存元数据、原始字幕、分段句子和封面图，后续格式转换（如从 Markdown 换到 SRT）完全离线完成，节省时间和带宽。
4. 丰富的输出选项：支持带时间戳的 Markdown、纯文本、SRT 字幕文件；可选章节分段（自动解析视频描述中的时间戳）、说话人识别（需 AI 后处理），适应字幕制作、内容分析、视频剪辑等多种场景。
5. 可靠的降级策略：当 YouTube 反爬机制触发时，自动切换客户端身份并回退至 yt-dlp，提升成功率；同时支持通过环境变量配置浏览器 Cookie 处理年龄限制或登录验证视频。
潜在缺点与局限性
1. 网络依赖与反爬风险：虽然内置多重重试和 yt-dlp 回退，但高频请求仍可能触发 YouTube 的 IP 封锁，需控制使用频率。
2. 说话人识别需额外 AI 处理：--speakers 功能仅输出原始结构数据，真正的说话人标签需要调用子代理（如 Claude Sonnet）进行后处理，增加一次 LLM 调用成本。
3. 缓存目录管理：长期使用会积累大量缓存文件，需用户定期手动清理 youtube-transcript/ 目录以避免磁盘占用过大。
4. 部分视频无法获取：私密视频、删除视频、区域限制视频、完全关闭字幕的视频以及部分年龄验证视频仍无法下载。
适合的目标群体
- 内容创作者与视频编辑：需要快速获取视频文案、制作字幕文件或分析竞品内容
- 研究人员与学术用户：收集 YouTube 教育内容、访谈、讲座的文本资料进行定性分析
- 语言学习者：下载多语言字幕进行对照学习，或翻译为母语辅助理解
- 自媒体运营者：提取热门视频文案结构、章节设置作为内容策划参考
- 开发者与自动化工作流：集成到内容抓取、知识库构建、多模态数据处理 pipeline 中
常规使用风险
- 性能风险：首次下载大型视频（如 2 小时直播回放）时，字幕数据量大，缓存写入和句子分段处理可能耗时数秒；建议对超长视频预留处理时间。
- 依赖项风险：工具基于 Bun 运行时，若系统未安装 Bun 且
npx不可用，需用户手动安装，可能影响首次使用体验。 - 外部工具风险：
yt-dlp回退机制需要用户环境预装该工具，或在触发回退时由 Agent 自动解决安装，存在命令注入防护（当前已通过参数白名单限制）。 - 隐私合规风险：可选的
YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER环境变量会读取浏览器 Cookie，用户需自行权衡是否对敏感账号启用此功能。