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时间窗口;此脚本一次仅摄取一个视频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。 - 调用
yt-dlp --list-subs <url>枚举可用字幕。 - 字幕优先级:手动字幕 > 自动生成字幕。手动字幕保留创作者提供的标点和说话人标签;自动字幕为全大写且无标点。
- 通过
yt-dlp --write-sub --sub-lang <lang> --skip-download下载最高优先级的VTT字幕。默认语言偏好:en,es(英语优先,西班牙语其次)。 - 去除VTT时间戳标记,合并为干净的散文段落。剔除重复行(自动生成VTT常出现行重复)。如果源字幕包含说话人标签,则保留。
- 通过
yt-dlp --print-json --skip-download拉取视频元数据(标题、频道、上传日期、时长、视频ID、URL)。 - 将频道名和视频标题进行slug化处理。写入到
External Inputs/YouTube/<频道slug>/<YYYY-MM-DD>-<视频slug>.md。 - 扫描转录内容中是否出现触发关键词(decision、framework、model、principle、“the lesson is”、playbook、anti-pattern、case study)。每匹配一个,在
Meta/Captures/<YYYY-MM-DD>-youtube-<频道slug>-<视频ID>.md创建写作种子存根,使种子进入捕获聚合器。 - 打印摘要:文件路径、转录字数、语言、检测到的种子数量。
调用方式
python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]
默认值:
--vault:$VAULT_ROOT环境变量或当前目录--lang:en,es(英语优先,西班牙语其次;匹配常见的双语默认值)--whisper:作为未来回退标志被接受,但此版本在无字幕可用时仅写入存根
输出契约
位于External Inputs/YouTube/<频道slug>/<YYYY-MM-DD>-<视频slug>.md的知识库文件包含前置信息:
---
type: external-input
source: youtube
video_id: <11字符ID>
url: https://www.youtube.com/watch?v=<id>
channel: <频道名>
channel_url: https://www.youtube.com/<handle>
title: <视频标题>
upload_date: <YYYY-MM-DD>
duration_seconds: <整数>
language: <ISO代码>
subtitle_source: manual | auto | whisper
word_count: <整数>
ingested_at: <ISO 8601时间戳>
---
正文为清理后的散文段落。如果源字幕包含说话人标签,则按**<说话人>:** <文本>格式呈现。
幂等性
重新摄取同一视频URL会覆盖同一知识库文件。种子存根文件名包含视频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-*系列知识库连接器的一部分。