ingest-youtube — YouTube 至知识库连接器
将 YouTube 转录拉取为 Markdown 知识库条目,作为可查询的已类型化记忆条目,供下游技能(知识图谱提取、语音特征训练、内容再利用、行动项提取)使用。
模式与 ingest-slack、ingest-whatsapp、ingest-notion、ingest-linear、ingest-github、ingest-gmail 相同。添加 YouTube 意味着新增一个归一化器,而非新架构。
何时使用
- 用户粘贴 YouTube URL 并请求转录或摘要
- 用户输入
/ingest-youtube <url>处理单个视频 - 用户要求捕获、同步、收录、转录或拉取一个演讲/播客/主题演讲到知识库
不要用于:
- 下载实际视频文件(直接使用
yt-dlp配合-f best) - 频道级别的收录或
--days窗口;本脚本一次只收录一个 YouTube 视频 URL - 直播流(转录不稳定)
- 非 YouTube 来源(Vimeo、Twitch、Twitter Spaces 有各自的连接器)
- 用户不需要知识库文件的一次性转录读取(直接运行
yt-dlp --write-auto-sub并输出到 stdout)
工作原理
- 将输入解析为一个 YouTube 视频 URL。
- 验证
yt-dlp是否已安装。若未安装,脚本退出并显示安装说明:brew install yt-dlp(macOS)或pip3 install --user yt-dlp。 - 验证 URL 为单个 http(s) YouTube 视频,并调用
yt-dlp --ignore-config --list-subs -- <url>枚举可用字幕。 - 字幕优先级:手动字幕 > 自动生成字幕。手动字幕保留了创作者提供的标点和说话人标签;自动生成字幕为全大写且无标点。
- 通过
yt-dlp --write-sub --sub-lang <lang> --skip-download下载最高优先级字幕为 VTT 格式。默认语言偏好:en,es(英语优先,西班牙语其次)。 - 去除 VTT 时间标记并合并为干净的散文段落。去重重复行(自动生成的 VTT 存在行重复)。如果来源有说话人标签,则予以保留。
- 通过
yt-dlp --print-json --skip-download拉取视频元数据(标题、频道、上传日期、时长、video_id、URL)。 - 将频道名称和视频标题转化为别名。写入
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md。 - 扫描转录中的触发关键词(decision、framework、model、principle、“the lesson is”、playbook、anti-pattern、case study)。每匹配一个,在
Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.md创建一个写作种子存根,使种子进入捕获聚合器。 - 打印摘要:文件路径、转录字数、语言、检测到的种子。
调用方式
python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]
默认值:
--vault:$VAULT_ROOT环境变量或当前目录--lang:en,es(英语优先,西班牙语其次;匹配常见的双语默认值)--whisper:接受作为未来的回退标志,但本版本在无可用字幕时仅写入存根
输出契约
知识库文件位于 External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md,包含前置元数据:
---
type: external-input
source: youtube
video_id: <11-char ID>
url: https://www.youtube.com/watch?v=<id>
channel: <channel-name>
channel_url: https://www.youtube.com/<handle>
title: <video title>
upload_date: <YYYY-MM-DD>
duration_seconds: <int>
language: <ISO code>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <ISO 8601 timestamp>
---
正文为清理后的散文段落转录。如果来源有说话人标签,格式化为每轮 **<speaker>:** <text>。
幂等性
重新收录同一个视频 URL 会覆盖同一个知识库文件。种子存根文件名哈希了 video_id,因此同一来源视频在多次运行中产生相同的存根文件名。重新运行会刷新,但绝不重复。
缺少字幕
如果 yt-dlp --list-subs 无手动或自动字幕返回,脚本会写入一个带有视频元数据和来源 URL 的存根知识库笔记,而非静默失败。--whisper 标志保留用于未来的本地转录回退,当前会报告该回退未实现。
如需手动回退,先用 yt-dlp 下载音频,再用本地 Whisper 工作流程进行转录,并在重新运行收录前添加字幕或转录文本。
局限性
- 每次运行仅收录一个 YouTube 视频 URL;频道句柄、播放列表和
--days窗口不在范围之内。 - 依赖
yt-dlp返回的字幕;无字幕的视频会产生元数据存根,而非转录。 - 此版本不下载视频文件或执行内置 Whisper 转录。
- 网络可用性、YouTube 字幕访问以及本地
yt-dlp行为决定收录是否成功。
验收测试
针对 YouTube 上首个上传的视频运行:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
预期输出:
Wrote 39 words to /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Language: en. Subtitle source: manual.
输出文件包含有效的前置元数据和干净的散文正文。
依赖项
yt-dlp(必需):通过brew install yt-dlp或pip3 install --user yt-dlp安装whisper-cpp(可选,用于本脚本之外的手动回退)
来源
包含于 adelaidasofia/ai-brain-starter,这是一个围绕 AI 代理的验证框架,使记忆能够累积而非损坏。该技能属于 ingest-* 系列知识库连接器家族。