ingest-youtube — Connecteur YouTube vers coffre-fort
Récupère les transcriptions YouTube dans un coffre-fort markdown sous forme d'entrées de mémoire typées et interrogeables, que les compétences en aval (extraction de graphe de connaissances, entraînement d'empreinte vocale, reformatage de contenu, extraction d'actions) peuvent exploiter.
Même modèle que ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, ingest-gmail. Ajouter YouTube signifie un nouveau normalisateur, pas une nouvelle architecture.
Quand l'utiliser
- L'utilisateur colle une URL YouTube et demande une transcription ou un résumé
- L'utilisateur dit
/ingest-youtube <url>pour une vidéo unique - L'utilisateur demande de capturer, synchroniser, ingérer, transcrire ou récupérer une conférence/podcast/keynote dans le coffre-fort
Ne PAS utiliser pour :
- Télécharger le fichier vidéo lui-même (utilisez directement
yt-dlpavec-f best) - L'ingestion d'une chaîne entière ou des fenêtres
--days; ce script ingère une seule URL vidéo à la fois - Les flux en direct (les transcriptions ne sont pas stables)
- Les sources non YouTube (Vimeo, Twitch, Twitter Spaces ont leurs propres connecteurs)
- Une lecture de transcription ponctuelle où l'utilisateur ne veut pas de fichier dans le coffre-fort (exécutez
yt-dlp --write-auto-subdirectement et redirigez vers stdout)
Comment ça fonctionne
- Analyser l'entrée comme une seule URL vidéo YouTube.
- Vérifier que
yt-dlpest installé. Sinon, le script s'arrête avec des instructions d'installation :brew install yt-dlp(macOS) oupip3 install --user yt-dlp. - Valider l'URL comme une vidéo YouTube unique avec http(s) et appeler
yt-dlp --ignore-config --list-subs -- <url>pour lister les sous-titres disponibles. - Priorité des sous-titres : sous-titres manuels > sous-titres automatiques. Les sous-titres manuels conservent la ponctuation et les étiquettes de locuteur fournies par le créateur ; les sous-titres automatiques sont en majuscules et sans ponctuation.
- Télécharger le sous-titre de plus haute priorité au format VTT via
yt-dlp --write-sub --sub-lang <lang> --skip-download. Langue par défaut :en,es(anglais d'abord, espagnol ensuite). - Supprimer les marqueurs temporels VTT et fusionner en paragraphes de prose propres. Dédupliquer les lignes répétées (les VTT automatiques ont des lignes doublées). Conserver les étiquettes de locuteur si la source les avait.
- Récupérer les métadonnées de la vidéo (titre, chaîne, date de publication, durée, video_id, URL) via
yt-dlp --print-json --skip-download. - Slugifier le nom de la chaîne et le titre de la vidéo. Écrire dans
External Inputs/YouTube/<slug-chaîne>/<AAAA-MM-JJ>-<slug-vidéo>.md. - Analyser la transcription pour les mots-clés déclencheurs (décision, cadre, modèle, principe, "la leçon est", playbook, anti-modèle, étude de cas). Pour chaque correspondance, créer un brouillon de départ d'écriture dans
Meta/Captures/<AAAA-MM-JJ>-youtube-<slug-chaîne>-<id-vidéo>.mdafin que le brouillon atterrisse dans l'agrégateur de captures. - Afficher un résumé : chemin du fichier, nombre de mots de la transcription, langue, brouillons détectés.
Invocation
python3 ingest.py <youtube-url> [--vault <chemin>] [--lang <code>]
Valeurs par défaut :
--vault: variable d'environnement$VAULT_ROOTou répertoire courant--lang:en,es(anglais d'abord, espagnol ensuite ; correspond à une valeur bilingue courante)--whisper: accepté comme indicateur de repli futur, mais cette version écrit un brouillon quand aucun sous-titre n'est disponible
Contrat de sortie
Le fichier du coffre-fort dans External Inputs/YouTube/<slug-chaîne>/<AAAA-MM-JJ>-<slug-vidéo>.md a l'en-tête frontmatter :
---
type: external-input
source: youtube
video_id: <ID à 11 caractères>
url: https://www.youtube.com/watch?v=<id>
channel: <nom-chaîne>
channel_url: https://www.youtube.com/<handle>
title: <titre-vidéo>
upload_date: <AAAA-MM-JJ>
duration_seconds: <int>
language: <code ISO>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <horodatage ISO 8601>
---
Le corps est la transcription nettoyée sous forme de prose par paragraphes. Si la source avait des étiquettes de locuteur, formater comme **<locuteur>:** <texte> par tour de parole.
Idempotence
Ré-ingérer la même URL vidéo écrase le même fichier du coffre-fort. Les noms de fichiers des brouillons de départ utilisent un hachage de l'ID vidéo, donc la même vidéo source produit le même nom de fichier de brouillon lors des ré-exécutions. Les ré-exécutions rafraîchissent, ne dupliquent jamais.
Sous-titres manquants
Si yt-dlp --list-subs ne retourne aucun sous-titre manuel ou automatique, le script écrit une note de brouillon dans le coffre-fort avec les métadonnées de la vidéo et l'URL source au lieu d'échouer silencieusement. L'indicateur --whisper est réservé pour un futur repli de transcription locale et signale actuellement que le repli n'est pas implémenté.
Pour un repli manuel aujourd'hui, téléchargez l'audio avec yt-dlp, transcrivez-le avec votre workflow Whisper local, et ajoutez les sous-titres ou le texte de transcription avant de relancer l'ingestion.
Limitations
- Ingère une seule URL vidéo YouTube par exécution ; les poignées de chaîne, les playlists et les fenêtres
--daysne sont pas prises en charge. - Dépend des sous-titres retournés par
yt-dlp; les vidéos sans sous-titres produisent un brouillon de métadonnées, pas une transcription. - Ne télécharge pas les fichiers vidéo ni n'effectue de transcription Whisper intégrée dans cette version.
- La disponibilité réseau, l'accès aux sous-titres YouTube et le comportement local de
yt-dlpdéterminent si l'ingestion réussit.
Test d'acceptation
Exécutez sur la première vidéo YouTube jamais mise en ligne :
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
Sortie attendue :
Écrit 39 mots dans /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Langue : en. Source des sous-titres : manuel.
Le fichier de sortie contient un en-tête frontmatter valide et un corps de prose propre.
Dépendances
yt-dlp(obligatoire) : installer viabrew install yt-dlpoupip3 install --user yt-dlpwhisper-cpp(facultatif pour un repli manuel en dehors de ce script)
Source
Inclus dans adelaidasofia/ai-brain-starter, un harnais de vérification autour d'un agent d'IA pour que la mémoire s'accumule au lieu de se corrompre. La compétence fait partie de la famille ingest-* de connecteurs de coffre-fort.