ingest-youtube — Connecteur YouTube vers coffre Markdown
Extrait les transcriptions YouTube dans un coffre Markdown en tant qu'entrées de mémoire typées et interrogables, que les compétences en aval (extraction de graphes de connaissances, entraînement d'empreintes vocales, réutilisation 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 seule vidéo - L'utilisateur demande de capturer, synchroniser, ingérer, transcrire ou récupérer une conférence/podcast/keynote dans le coffre
Ne PAS utiliser pour :
- Télécharger le fichier vidéo lui-même (utilisez
yt-dlpdirectement avec-f best) - Ingestion de toute une chaîne ou fenêtres
--days; ce script ingère une URL vidéo à la fois - Flux en direct (les transcriptions ne sont pas stables)
- Sources non YouTube (Vimeo, Twitch, Twitter Spaces ont leurs propres connecteurs)
- Lectures de transcription ponctuelles où l'utilisateur ne souhaite pas de fichier dans le coffre (exécutez
yt-dlp --write-auto-subdirectement et redirigez vers stdout)
Comment ça fonctionne
- Analyser l'entrée comme une URL YouTube.
- Vérifier que
yt-dlpest installé. Sinon, le script se termine avec des instructions d'installation :brew install yt-dlp(macOS) oupip3 install --user yt-dlp. - Appeler
yt-dlp --list-subs <url>pour énumérer les sous-titres disponibles. - Priorité des sous-titres : sous-titres manuels > légendes automatiques. Les sous-titres manuels conservent la ponctuation et les étiquettes de locuteur fournies par le créateur ; les légendes 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 sont souvent doublés). Conserver les étiquettes de locuteur si la source en avait.
- Extraire 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>/<YYYY-MM-DD>-<slug-vidéo>.md. - Analyser la transcription pour détecter des mots-clés déclencheurs (decision, framework, model, principle, "the lesson is", playbook, anti-pattern, case study). Pour chaque correspondance, créer un brouillon de capture dans
Meta/Captures/<YYYY-MM-DD>-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 <path>] [--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 par défaut bilingue courante)--whisper: accepté comme indicateur de repli futur, mais cette version écrit un brouillon lorsqu'aucun sous-titre n'est disponible
Contrat de sortie
Le fichier du coffre à External Inputs/YouTube/<slug-chaîne>/<YYYY-MM-DD>-<slug-vidéo>.md possède le frontmatter suivant :
---
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: <YYYY-MM-DD>
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 en paragraphes. Si la source avait des étiquettes de locuteur, formater comme **<locuteur>:** <texte> par tour.
Idempotence
Ré-ingérer la même URL vidéo écrase le même fichier du coffre. Les noms de fichiers des brouillons de capture intègrent le video_id, donc la même vidéo source produit le même nom de fichier de brouillon entre les exécutions. Les réexécutions rafraîchissent, ne dupliquent jamais.
Sous-titres manquants
Si yt-dlp --list-subs ne renvoie aucun sous-titre manuel ou automatique, le script écrit une note de base dans le coffre 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 flux de travail Whisper local, et ajoutez des sous-titres ou le texte de la transcription avant de réexécuter l'ingestion.
Limitations
- Ingère une seule URL vidéo YouTube par exécution ; les handles de chaîne, les listes de lecture et les fenêtres
--dayssont hors de portée. - Dépend des sous-titres renvoyés par
yt-dlp; les vidéos sans sous-titres produisent une note de base avec métadonnées, pas une transcription. - Ne télécharge pas les fichiers vidéo et n'effectue pas 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 : manual.
Le fichier de sortie contient un frontmatter valide et un corps de prose propre.
Dépendances
yt-dlp(requis) : installez viabrew install yt-dlpoupip3 install --user yt-dlpwhisper-cpp(optionnel 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 IA pour que la mémoire se compose au lieu de se corrompre. La compétence fait partie de la famille de connecteurs de coffre ingest-*.