ingest-youtube — YouTube 到知識庫連接器
將 YouTube 文字稿擷取到 Markdown 知識庫中,成為可查詢的類型化記憶条目,供後續技能(知識圖譜提取、語音指紋訓練、內容重製、行動項目提取)使用。
與 ingest-slack、ingest-whatsapp、ingest-notion、ingest-linear、ingest-github、ingest-gmail 的模式相同。新增 YouTube 意味著加入一個新的正規化器,而非新的架構。
使用時機
- 使用者貼上 YouTube URL 並要求文字稿或摘要
- 使用者輸入
/ingest-youtube <url>處理單一影片 - 使用者要求將講座/Podcast/主題演講內容捕捉、同步、攝入、轉錄或拉入知識庫
不適合用於:
- 下載實際影片檔案(請直接使用
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。 - 驗證 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)。 - 將頻道名稱和影片標題轉為 slug 格式。寫入
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:保留作為未來 fallback 旗標,但此版本在無字幕可用時會寫入存根
輸出合約
知識庫檔案位於 External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-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 會覆蓋同一個知識庫檔案。種子存根檔案名稱會對 video_id 進行雜湊處理,因此同一來源影片在重新執行時會產生相同的存根檔案名稱。重新執行會重新整理,絕不重複。
缺少字幕
若 yt-dlp --list-subs 未回傳任何手動或自動字幕,腳本會寫入一個包含影片元數據和來源 URL 的存根知識庫筆記,而非靜默失敗。--whisper 旗標保留作為未來本地轉錄的後備方案,目前會回報該後備方案尚未實作。
若要手動使用 fallback,請先用 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(選用,作為此腳本外的手動 fallback)
來源
收錄於 adelaidasofia/ai-brain-starter,這是一個針對 AI 代理的驗證框架,讓記憶得以累積而非破壞。此技能是 ingest-* 系列知識庫連接器的一部分。