YouTube Fetcher to Markdown
把 YouTube 视频一键转为带完整元数据的 Obsidian 归档笔记：字幕、章节、可点击时间戳，无需 API 密钥。
- Star 数
- ★ 495
- 最近更新
- 16 天前
- License
- MIT
- 主语言
- Python
- FA 评分
- 83/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- Obsidian 用户建立视频知识库：把课程、讲座字幕连同元数据归档进 vault，用 Dataview 按频道、日期、语言查询。
- 不适合
- 需要完全离线运行的团队：抓取依赖 YouTube 字幕接口与网络
- 需要语音识别、说话人区分或画面分析的场景
- 私有、受限或未开放字幕的视频
- 源码审查
- 83/100 · 表现良好
这个 Agent 能做什么，适合哪些场景？
YouTube Fetcher to Markdown（JimmySadek/youtube-fetcher-to-markdown）是一个可移植的 AI-agent 技能，核心是一个 Python 脚本 scripts/fetch_transcript.py，把 YouTube 链接转换成结构化的归档 Markdown 笔记。每次捕获包含完整字幕、标题、频道、时长、上传日期、描述、章节、实际字幕语言及来源信息，写入带 YAML frontmatter 的单个文件，便于在 Obsidian 中用 Dataview 查询，也可移植到 Logseq 或纯文本工作流。脚本通过 YouTube 的非公开字幕接口（经由 youtube-transcript-api）和 oEmbed 获取数据，yt-dlp 为可选依赖，用于更丰富的元数据。它支持手动与自动生成字幕、语言偏好排序、严格语言匹配、显式 YouTube 机器翻译，并可导出 txt、JSON、SRT、WebVTT 格式。安装遵循可移植的 SKILL.md 格式，同一命令可用于 Codex、Claude Code、Cursor、Windsurf、Gemini CLI 等兼容 agent，也可直接手动运行 Python 脚本。项目采用 MIT 许可证，无需 API 密钥、无托管服务。
运行 python3 scripts/fetch_transcript.py "https://youtu.be/VIDEO_ID" 后，脚本依次执行：1) 解析多种 YouTube 输入格式（标准观看 URL、youtu.be 短链、/embed/、/shorts/、/live/、/v/、移动端与 YouTube Music 链接、youtube-nocookie 嵌入链接、11 位视频 ID），拒绝仿冒主机；2) 通过 youtube-transcript-api 的非公开字幕接口抓取手动或自动生成字幕，按 --lang 语言偏好（如 --lang fr,de）或 --lang auto 选择轨道，可用 --strict-lang 禁用英语回退，用 --translate en 触发显式 YouTube 机器翻译；3) 通过 yt-dlp（可选）或 oEmbed 获取标题、频道、时长、上传日期、描述与章节，--no-metadata 可跳过两者；4) 生成一个 Markdown 文件，如 ~/yt_transcripts/2026-03-04_标题_[视频ID].md，内含 YAML frontmatter（title、channel、url、video_id、fetched、language、caption_type、duration、upload_date、tags 等字段）、元数据表格、视频描述和完整字幕；5) --timestamps 添加可点击的时间戳链接，--format 可切换 txt//srt/vtt 导出，--stdout 只打印结果不写文件。写入使用目标旁的临时文件并配合硬链接或独占创建；目标已存在时默认保留并以退出码 3 退出，--force 才完整覆盖。输出位置优先级为 --output、--output-dir、YOUTUBE_FETCHER_DIR、默认 ~/yt_transcripts/。
- Obsidian 用户建立视频知识库：把课程、讲座字幕连同元数据归档进 vault，用 Dataview 按频道、日期、语言查询。
- 内容研究者收集素材：抓取竞品或主题相关视频的描述、章节与字幕，导出 SRT/VTT 供后续剪辑或分析。
- 多语言学习者：用
--lang ja --strict-lang强制要求日文字幕，或用--translate en获取标注为机器翻译的英文版本。 - AI agent 用户（Claude Code、Codex、Cursor 等）：安装为技能后，对话中粘贴 YouTube 链接即可让 agent 自动产出任笔记文件。
- 播客/直播记录者：批量归档 /live/ 或 YouTube Music 链接的可访问字幕，保留来源 URL 与抓取日期的可审计记录。
如何安装或部署这个 Agent？
1) 安装技能：npx skills add JimmySadek/youtube-fetcher-to-markdown，或克隆仓库：git clone https://github.com/JimmySadek/youtube-fetcher-to-markdown.git。2) 在技能目录创建隔离的 Python 环境（支持 Python 3.8–3.14，推荐 3.10+）：python3 -m venv .venv，然后 .venv/bin/python -m pip install -r requirements.txt，再用 .venv/bin/python scripts/fetch_transcript.py --check-deps 验证依赖。Windows PowerShell 对应命令为 py -m venv .venv 与 .venv\Scripts\python.exe ...。3) 可选安装 yt-dlp 以获取描述、章节、时长和上传日期：.venv/bin/python -m pip install yt-dlp，并把其可执行文件放入 PATH（激活环境即可）。无需任何 API 密钥。
如何使用这个 Agent？
基本用法：python3 scripts/fetch_transcript.py "https://youtu.be/VIDEO_ID"（先激活 .venv 或使用完整解释器路径）。常用示例：保存到 Obsidian vault：python3 scripts/fetch_transcript.py URL --output-dir ~/Notes/MyVault；设置持久目录：export YOUTUBE_FETCHER_DIR=~/Notes/MyVault；语言偏好：python3 scripts/fetch_transcript.py --lang fr,de -- URL；严格日文字幕：--lang ja --strict-lang -- URL；机器翻译：--lang auto --translate en -- URL；查看可用字幕语言：--list -- URL；其他导出：--format srt URL、--format --output captions.json URL、--stdout --timestamps -- URL。输出位置按 --output > --output-dir > YOUTUBE_FETCHER_DIR > ~/yt_transcripts/ 的优先级决定。agent 使用时应相对于已安装的 SKILL.md 解析脚本路径，并使用隔离环境的解释器。
这个 Agent 有哪些优点和局限？
- 归档完整性突出：不只是裸字幕文本，还包括来源 URL、频道、语言、描述、章节和可预测的文件名，全部在一个本地文件内。
- 语言处理细致：支持有序语言偏好、区域变体（es 可匹配 es-MX）、严格匹配模式和显式标注来源的机器翻译，且语言选择结果记录在 frontmatter 中。
- 文件安全设计严谨：所有格式默认保留已存在文件（退出码 3），写入经临时文件与硬链接/独占创建，符号链接目标拒绝覆盖，支持安全的原地刷新。
- 可移植性强：遵循 SKILL.md 格式，同一安装命令适配 Codex、Claude Code、Cursor、Windsurf、Gemini CLI；也可完全脱离 agent 手动运行。
- 依赖 YouTube 的非公开字幕接口，YouTube 改版或网络封锁可能导致抓取失败，离线测试通过不代表可访问。
- 私有、受限或禁用字幕的视频无法处理，脚本不会伪造或总结缺失的字幕。
- 可选的 yt-dlp 元数据依赖需要额外安装并配置 PATH，否则只能通过 oEmbed 获取有限的标题/频道信息。
- 不做语音识别（Whisper）、说话人识别或视频内容分析；字幕中的识别错误会原样保留。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| YouTube Fetcher to Markdown 当前 | 83 · 表现良好 | Agent 插件 / 技能免费 | ★ 495 | 16 天前 | Python | Codex · Claude Code |
| LLM Wiki | 85 · 表现良好 | Agent 插件 / 技能免费 + 模型费 | ★ 1.4k | 20 天前 | Python | Codex · Claude Code |
| OpenKB 开放知识库 | 59 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 4.8k | 3 个月前 | Python | Codex · Claude Code · OpenAI API · Claude API |
| COG 第二大脑 | 64 · 存在缺口 | Agent 插件 / 技能免费 + 模型费 | ★ 1.3k | 20 天前 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示权限最小化做得好：仅联系 YouTube captions/oEmbed，yt-dlp 子进程禁用配置/缓存/播放列表且有超时（测试验证）；文件写入原子化、拒绝覆盖与符号链接目标。扣分项：--force 为破坏性替换且无撤销机制，回滚仅靠'文件未被碰'的默认行为；源归属上 LICENSE 版权名 'GimySadek' 与仓库 'JimmySadek' 不一致；依赖仅是版本范围，无依赖完整性/审计说明。
测试与 README 声明高度一致（语言选择、文件保护、退出码、超时均有契约测试），失败信息经测试验证具有可操作性且不泄露细节（如超时错误隐藏代理密码）。扣分：对外部 YouTube 接口的可用性无法静态保证，README 自己承认 'passing offline tests cannot guarantee access'。
面向 Obsidian 用户、命令行用户与多种 Agent（Codex/Claude Code 等），URL 形态覆盖广并有测试，能力边界（不下载音视频、不做 Whisper、不做说话人识别）表述明确，多平台环境与 venv 指南齐全。扣分：SKILL.md 本体未在证据中，触发精度只能由打包测试间接佐证。
信息架构清晰、安装说明覆盖三平台、示例丰富、故障排查表和退出码表完整、局限性坦率。扣分项：无仓库内 CHANGELOG（仅链接外部 release notes）；命名上 main/master 双分支为历史兼容保留，存在混淆风险；LICENSE 版权人姓名与仓库名不一致；维护者身份未经验证，发布流程文档化但无法静态核实执行。
输出可用性高：YAML frontmatter、Dataview 兼容、多格式导出、时间戳链接均有测试佐证；成本极低（无 API key、纯本地、可选依赖）。扣分：同类转录抓取工具众多，边际价值主要在元数据整合与防覆盖安全上，属改进而非独有能力。
README 声明大量由测试文件直接佐证（退出码 3、原子写、语言回退、机器翻译标记）；specs/ 验证记录被引用但内容不在证据内，无法核对；区分了事实与快照数据（'dated adoption numbers are snapshots'），机器翻译明确标注非人工。扣分：验证证据文档本身不可审查，且部分声明（如 Windows 行为、CI 全绿）只能信任陈述。
- --force 会完全替换目标文件（包括用户批注），不可恢复，使用前务必备份；默认行为（退出码 3）会保留已有文件。
- LICENSE 版权人 'GimySadek' 与仓库所有者 'JimmySadek' 不一致，且发布者未经验证，采信前请自行确认来源仓库与提交历史。
- 依赖未做完整性锁定（无哈希/lockfile），安装前请审查 requirements.txt 并在隔离环境中安装。
- 依赖 YouTube 未公开接口，随时可能失效或被封锁；脚本不提供任何绕过手段，请勿自行添加 Cookie/代理等改动。
- 主分支为 main，master 仅为历史镜像，请勿在 master 上开发或引用其作为规范来源。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v2.0.1 v2.0.1: clearer safety boundaries, no behaviour change
发布说明摘录
A small safety-and-clarity release. Nothing changes in how the skill works. Run npx skills update to get it. Why The skills.sh listing showed a security audit failure from Gen Agent Trust Hub (Socket and Snyk pass). The audit itself called the skill's safety posture good. It flagged a link to a young website domain in an old planning page, a metadata file, and a code-loading pattern. This release removes those triggers. Changed - Removed a link to codeguilds.dev from an old planning page; that domain fails URL-reputation checks. …在 GitHub 查看 ↗ -
v2.0.0 v2.0.0: Video Fetcher to Markdown (formerly YouTube Fetcher)
发布说明摘录
YouTube Fetcher is now Video Fetcher to Markdown The skill outgrew its name: it now reads Instagram, TikTok, X, Vimeo, Facebook and other sites, not only YouTube. Nothing breaks for existing users. - Installed with npx skills add? Run npx skills update and you get v2.0.0. The skill is still named youtube-fetcher, and the old repository address redirects here. - Cloned with git? git pull follows the redirect; you can also point your remote at the new address. - Old links, stars and forks all carry over. …在 GitHub 查看 ↗ -
v1.2.0 YouTube Fetcher v1.2.0
发布说明摘录
YouTube Fetcher v1.2.0 makes everyday capture safer and works better across languages, while keeping the portable, no-API-key workflow. Improvements - Protect existing Markdown, JSON, SRT, plain-text, and WebVTT files. Refresh an existing default note in place and preserve its permissions. - Select captions using ordered language preferences, regional variants, --lang auto, or --strict-lang. - Request YouTube machine translation explicitly with --translate, with source language and translation provenance recorded in Markdown. …在 GitHub 查看 ↗