ingest-youtube — Conector de YouTube a bóveda
Extrae transcripciones de YouTube a una bóveda Markdown como entradas de memoria consultables que los skills posteriores (extracción de grafos de conocimiento, entrenamiento de huellas de voz, reutilización de contenido, extracción de elementos de acción) pueden procesar.
Mismo patrón que ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, ingest-gmail. Añadir YouTube implica un nuevo normalizador, no una nueva arquitectura.
Cuándo usarlo
- El usuario pega una URL de YouTube y solicita una transcripción o resumen
- El usuario escribe
/ingest-youtube <url>para un video individual - El usuario solicita capturar, sincronizar, ingerir, transcribir o extraer una charla/podcast/conferencia a la bóveda
NO usar para:
- Descargar el archivo de video real (usa
yt-dlpdirectamente con-f best) - Ingesta de canales completos o ventanas de
--days; este script ingiere una URL de video a la vez - Transmisiones en vivo (las transcripciones no son estables)
- Fuentes que no sean YouTube (Vimeo, Twitch, Twitter Spaces tienen sus propios conectores)
- Lecturas únicas de transcripciones donde el usuario no desea un archivo en la bóveda (ejecuta
yt-dlp --write-auto-subdirectamente y redirige a stdout)
Cómo funciona
- Analiza la entrada como una URL de video de YouTube.
- Verifica que
yt-dlpesté instalado. Si no, el script termina con instrucciones de instalación:brew install yt-dlp(macOS) opip3 install --user yt-dlp. - Ejecuta
yt-dlp --list-subs <url>para listar los subtítulos disponibles. - Prioridad de subtítulos: subtítulos manuales > subtítulos automáticos. Los manuales preservan la puntuación y etiquetas de orador; los automáticos están en mayúsculas y sin puntuación.
- Descarga el subtítulo de mayor prioridad como VTT mediante
yt-dlp --write-sub --sub-lang <lang> --skip-download. Idioma por defecto:en,es(inglés primero, español segundo). - Elimina las marcas de tiempo VTT y fusiona en párrafos de prosa limpios. Elimina líneas duplicadas (los VTT automáticos duplican líneas). Preserva las etiquetas de orador si la fuente las tenía.
- Obtiene los metadatos del video (título, canal, fecha de subida, duración, video_id, URL) mediante
yt-dlp --print-json --skip-download. - Convierte el nombre del canal y el título del video a slug. Escribe en
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md. - Escanea la transcripción en busca de palabras clave (decisión, marco, modelo, principio, "la lección es", manual, antipatrón, caso de estudio). Por cada coincidencia, crea una semilla de escritura en
Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.mdpara que la semilla llegue al agregador de capturas. - Imprime resumen: ruta del archivo, recuento de palabras de la transcripción, idioma, semillas detectadas.
Invocación
python3 ingest.py <youtube-url> [--vault <ruta>] [--lang <código>]
Valores por defecto:
--vault: variable de entorno$VAULT_ROOTo directorio actual--lang:en,es(inglés primero, español segundo; coincide con un bilingüe común por defecto)--whisper: aceptado como bandera de reserva futura, pero esta versión escribe una semilla cuando no hay subtítulos disponibles
Contrato de salida
El archivo de la bóveda en External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md tiene frontmatter:
---
type: external-input
source: youtube
video_id: <ID de 11 caracteres>
url: https://www.youtube.com/watch?v=<id>
channel: <nombre-del-canal>
channel_url: https://www.youtube.com/<handle>
title: <título-del-video>
upload_date: <YYYY-MM-DD>
duration_seconds: <int>
language: <código ISO>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <marca de tiempo ISO 8601>
---
El cuerpo es la transcripción limpia en prosa en párrafos. Si la fuente tenía etiquetas de orador, el formato es **<orador>:** <texto> por turno.
Idempotencia
Re-ingerir la misma URL de video sobrescribe el mismo archivo de la bóveda. Los nombres de los archivos de semillas incluyen un hash del video_id, por lo que el mismo video fuente produce el mismo nombre de archivo de semilla en cada ejecución. Las re-ejecuciones actualizan, nunca duplican.
Subtítulos faltantes
Si yt-dlp --list-subs no devuelve subtítulos manuales ni automáticos, el script escribe una nota de bóveda de semilla con los metadatos del video y la URL fuente en lugar de fallar silenciosamente. La bandera --whisper está reservada para una futura transcripción local de respaldo y actualmente informa que el respaldo no está implementado.
Para un respaldo manual hoy, descarga el audio con yt-dlp, transcríbelo con tu flujo de trabajo local de Whisper y añade subtítulos o texto de transcripción antes de volver a ejecutar la ingesta.
Limitaciones
- Ingiere una URL de video de YouTube por ejecución; los handles de canal, listas de reproducción y ventanas
--daysestán fuera del alcance. - Depende de los subtítulos devueltos por
yt-dlp; los videos sin subtítulos producen una semilla de metadatos, no una transcripción. - No descarga archivos de video ni realiza transcripción Whisper integrada en esta versión.
- La disponibilidad de la red, el acceso a subtítulos de YouTube y el comportamiento local de
yt-dlpdeterminan si la ingesta tiene éxito.
Prueba de aceptación
Ejecuta contra el primer video de YouTube subido:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
Salida esperada:
Wrote 39 words to /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Language: en. Subtitle source: manual.
El archivo de salida contiene un frontmatter válido y un cuerpo de prosa limpio.
Dependencias
yt-dlp(requerido): instala mediantebrew install yt-dlpopip3 install --user yt-dlpwhisper-cpp(opcional para un respaldo manual fuera de este script)
Fuente
Incluido en adelaidasofia/ai-brain-starter, un entorno de verificación para un agente de IA para que la memoria se acumule en lugar de corromperse. El skill es parte de la familia de conectores de bóveda ingest-*.