ingest-youtube — YouTube 到筆記庫連接器
將 YouTube 影片字幕拉入 Markdown 筆記庫,成為可查詢的類型化記憶條目,供下游技能(知識圖譜萃取、語音指紋訓練、內容再利用、行動項目萃取)操作。
模式與 ingest-slack、ingest-whatsapp、ingest-notion、ingest-linear、ingest-github、ingest-gmail 相同。加入 YouTube 只需新增一個正規化器,而非新架構。
使用時機
- 使用者貼上 YouTube 網址並要求取得字幕或摘要
- 使用者輸入
/ingest-youtube <url>處理單一影片 - 使用者要求將講座/播客/主題演講存入筆記庫(capture、sync、ingest、transcribe、pull)
請勿用於:
- 下載實際影片檔案(請直接使用
yt-dlp搭配-f best) - 頻道層級擷取或
--days時間範圍;此腳本一次只處理一個影片網址 - 直播(字幕不穩定)
- 非 YouTube 來源(Vimeo、Twitch、Twitter Spaces 各有專用連接器)
- 一次性閱讀字幕但無需建立筆記庫檔案(直接執行
yt-dlp --write-auto-sub並輸出到 stdout)
運作原理
- 將輸入解析為一個 YouTube 影片網址。
- 確認
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取得影片元數據(標題、頻道、上傳日期、時長、video_id、網址)。 - 將頻道名稱與影片標題轉為 slug 格式。寫入
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md。 - 掃描字幕中的觸發關鍵字(decision、framework、model、principle、「the lesson is」、playbook、anti-pattern、case study)。每個匹配結果會建立一個寫作草稿 stub,存放於
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:接受此旗標作為未來備援方案,但此版本在無可用字幕時只會寫入一個 stub
輸出合約
位於 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 時間戳>
---
正文為清理後的段落散文。若來源有說話者標籤,則每段對話格式為 **<說話者>:** <文字>。
冪等性
重新擷取同一個影片網址會覆蓋同一個筆記庫檔案。草稿 stub 的檔名會包含 video_id 的雜湊值,因此同一來源影片在不同執行中會產生相同的 stub 檔名。重新執行只會刷新,不會重複。
無字幕時的處理
若 yt-dlp --list-subs 未傳回任何手動或自動字幕,腳本會寫入一個包含影片元數據與來源網址的 stub 筆記庫檔案,而非直接失敗。--whisper 旗標保留給未來本機語音辨識備援方案,目前會報告該備援尚未實作。
今日的手動備援方案:使用 yt-dlp 下載音訊,透過你本機的 Whisper 流程進行轉錄,然後在重新執行擷取前加入字幕或轉錄文字。
限制
- 每次執行只處理一個 YouTube 影片網址;頻道句柄、播放清單與
--days時間範圍不在範圍內。 - 依賴
yt-dlp回傳的字幕;無字幕的影片只會產生元數據 stub,不會有轉錄內容。 - 此版本不下載影片檔案,也不執行內建的 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-* 系列筆記庫連接器的一部分。