ingest-youtube – YouTube-zu-Vault-Konnektor
Zieht YouTube-Transkripte als abfragbare, typisierte Gedächtniseinträge in ein Markdown-Vault, auf die nachgelagerte Skills (Wissensgraph-Extraktion, Sprachfingerabdruck-Training, Content-Wiederverwendung, Aktionspunkt-Extraktion) zugreifen können.
Gleiches Muster wie ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, ingest-gmail. YouTube hinzuzufügen bedeutet einen neuen Normalisierer, keine neue Architektur.
Wann verwenden
- Benutzer fügt eine YouTube-URL ein und fragt nach einem Transkript oder einer Zusammenfassung
- Benutzer sagt
/ingest-youtube <url>für ein einzelnes Video - Benutzer bittet darum, einen Talk/Podcast/Vortrag zu erfassen, zu synchronisieren, zu importieren oder zu transkribieren
NICHT verwenden für:
- Herunterladen der tatsächlichen Videodatei (verwende
yt-dlpdirekt mit-f best) - Kanalweites Importieren oder
--days-Fenster; dieses Skript importiert eine Video-URL auf einmal - Live-Streams (Transkripte sind nicht stabil)
- Nicht-YouTube-Quellen (Vimeo, Twitch, Twitter Spaces haben eigene Konnektoren)
- Einmalige Transkript-Lesevorgänge, bei denen der Benutzer keine Vault-Datei möchte (führe
yt-dlp --write-auto-subdirekt aus und leite an stdout weiter)
Funktionsweise
- Eingabe als eine YouTube-Video-URL parsen.
- Prüfen, ob
yt-dlpinstalliert ist. Falls nicht, beendet sich das Skript mit Installationsanweisungen:brew install yt-dlp(macOS) oderpip3 install --user yt-dlp. - URL als einzelnes http(s) YouTube-Video validieren und
yt-dlp --ignore-config --list-subs -- <url>aufrufen, um verfügbare Untertitel aufzulisten. - Untertitel-Priorität: Manuelle Untertitel > automatisch generierte Untertitel. Manuelle Untertitel erhalten die vom Ersteller bereitgestellte Zeichensetzung und Sprecherbeschriftungen; automatisch generierte sind Großbuchstaben ohne Zeichensetzung.
- Den Untertitel mit der höchsten Priorität als VTT herunterladen über
yt-dlp --write-sub --sub-lang <lang> --skip-download. Standard-Sprachpräferenz:en,es(zuerst Englisch, dann Spanisch). - VTT-Zeitmarkierungen entfernen und zu sauberen Prosa-Absätzen zusammenführen. Doppelte Zeilen entfernen (automatisch generierte VTTs haben Zeilenverdopplungen). Sprecherbeschriftungen erhalten, falls die Quelle sie hatte.
- Video-Metadaten (Titel, Kanal, Upload-Datum, Dauer, video_id, URL) über
yt-dlp --print-json --skip-downloadabrufen. - Kanalnamen und Videotitel in Slugs umwandeln. Schreiben nach
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md. - Transkript auf Auslöseschlüsselwörter scannen (Entscheidung, Rahmenwerk, Modell, Prinzip, "die Lektion ist", Playbook, Anti-Pattern, Fallstudie). Für jede Übereinstimmung einen Schreib-Seed-Stub unter
Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.mderstellen, damit der Seed im Captures-Aggregator landet. - Zusammenfassung ausgeben: Dateipfad, Transkript-Wortanzahl, Sprache, erkannte Seeds.
Aufruf
python3 ingest.py <youtube-url> [--vault <pfad>] [--lang <code>]
Standardwerte:
--vault:$VAULT_ROOTUmgebungsvariable oder aktuelles Verzeichnis--lang:en,es(zuerst Englisch, dann Spanisch; passt zu einem häufigen bilingualen Standard)--whisper: als zukünftiges Fallback-Flag akzeptiert, aber diese Version schreibt einen Stub, wenn keine Untertitel verfügbar sind
Ausgabe-Vertrag
Die Vault-Datei unter External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md hat Frontmatter:
---
type: external-input
source: youtube
video_id: <11-Zeichen-ID>
url: https://www.youtube.com/watch?v=<id>
channel: <kanal-name>
channel_url: https://www.youtube.com/<handle>
title: <video-titel>
upload_date: <YYYY-MM-DD>
duration_seconds: <int>
language: <ISO-Code>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <ISO 8601-Zeitstempel>
---
Textkörper ist das bereinigte Transkript als Absatzprosa. Wenn die Quelle Sprecherbeschriftungen hatte, als **<sprecher>:** <text> pro Wechsel formatieren.
Idempotenz
Das erneute Importieren derselben Video-URL überschreibt dieselbe Vault-Datei. Die Seed-Stub-Dateinamen hashen die video_id, sodass dasselbe Quellvideo über mehrere Durchläufe hinweg denselben Stub-Dateinamen erzeugt. Wiederholungen aktualisieren, verdoppeln nie.
Fehlende Untertitel
Wenn yt-dlp --list-subs keine manuellen oder automatischen Untertitel zurückgibt, schreibt das Skript einen Stub-Vault-Eintrag mit den Video-Metadaten und der Quell-URL, anstatt still zu scheitern. Das --whisper-Flag ist für einen zukünftigen lokalen Transkriptions-Fallback reserviert und meldet derzeit, dass der Fallback nicht implementiert ist.
Für einen manuellen Fallback heute lade Audio mit yt-dlp herunter, transkribiere es mit deinem lokalen Whisper-Workflow und füge Untertitel oder Transkripttext hinzu, bevor du den Import erneut ausführst.
Einschränkungen
- Importiert eine YouTube-Video-URL pro Durchlauf; Kanal-Handles, Playlists und
--days-Fenster sind außerhalb des Rahmens. - Hängt von den von
yt-dlpzurückgegebenen Untertiteln ab; Videos ohne Untertitel erzeugen einen Metadaten-Stub, kein Transkript. - Lädt in dieser Version keine Videodateien herunter und führt keine integrierte Whisper-Transkription durch.
- Netzwerkverfügbarkeit, YouTube-Untertitelzugriff und lokales
yt-dlp-Verhalten bestimmen, ob der Import erfolgreich ist.
Akzeptanztest
Gegen das erste jemals hochgeladene YouTube-Video ausführen:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
Erwartete Ausgabe:
Wrote 39 words to /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Language: en. Subtitle source: manual.
Die Ausgabedatei enthält gültiges Frontmatter und einen sauberen Prosatextkörper.
Abhängigkeiten
yt-dlp(erforderlich): installieren überbrew install yt-dlpoderpip3 install --user yt-dlpwhisper-cpp(optional für einen manuellen Fallback außerhalb dieses Skripts)
Quelle
Gebündelt in adelaidasofia/ai-brain-starter, einem Verifikations-Framework um einen KI-Agenten, sodass Gedächtnis sich anhäuft statt korrumpiert. Der Skill ist Teil der ingest-*-Familie von Vault-Konnektoren.