ingest-youtube — Conector de YouTube a vault
Convierte transcripciones de YouTube en entradas de memoria tipada y consultable dentro de un vault de markdown, listas para que habilidades posteriores (extracción de grafos de conocimiento, entrenamiento de huella de voz, reutilización de contenido, extracción de elementos de acción) puedan actuar sobre ellas.
Mismo patrón que ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, ingest-gmail. Agregar YouTube significa un nuevo normalizador, no una nueva arquitectura.
Cuándo usarlo
- El usuario pega una URL de YouTube y pide una transcripción o resumen
- El usuario dice
/ingest-youtube <url>para un solo video - El usuario pide capturar, sincronizar, ingestar, transcribir o extraer una charla/podcast/conferencia al vault
NO usar para:
- Descargar el archivo de video real (usa
yt-dlpdirectamente con-f best) - Ingesta de todo un canal o ventanas de
--days; este script ingesta 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 de transcripción únicas donde el usuario no quiere un archivo en el vault (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. - Valida la URL como un único video de YouTube http(s) y llama a
yt-dlp --ignore-config --list-subs -- <url>para enumerar los subtítulos disponibles. - Prioridad de subtítulos: subtítulos manuales > subtítulos automáticos. Los manuales conservan la puntuación y etiquetas de hablante del creador; 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. Preferencia de idioma predeterminada:en,es(inglés primero, español segundo). - Elimina las marcas de tiempo del VTT y fusiona en párrafos de prosa limpia. Deduplica líneas repetidas (los VTT automáticos tienen líneas duplicadas). Conserva las etiquetas de hablante si la fuente las tenía.
- Extrae metadatos del video (título, canal, fecha de subida, duración, video_id, URL) mediante
yt-dlp --print-json --skip-download. - Convierte a slug el nombre del canal y el título del video. Escribe en
External Inputs/YouTube/<slug-canal>/<YYYY-MM-DD>-<slug-video>.md. - Escanea la transcripción en busca de palabras clave (decisión, framework, modelo, principio, "la lección es", playbook, antipatrón, caso de estudio). Por cada coincidencia, crea un stub de semilla de escritura en
Meta/Captures/<YYYY-MM-DD>-youtube-<slug-canal>-<id-video>.mdpara que la semilla llegue al agregador de capturas. - Muestra un resumen: ruta del archivo, recuento de palabras de la transcripción, idioma, semillas detectadas.
Invocación
python3 ingest.py <url-youtube> [--vault <ruta>] [--lang <código>]
Valores predeterminados:
--vault: variable de entorno$VAULT_ROOTo directorio actual--lang:en,es(inglés primero, español segundo; coincide con un bilingüe común)--whisper: aceptado como bandera de fallback futuro, pero esta versión escribe un stub cuando no hay subtítulos disponibles
Contrato de salida
El archivo en External Inputs/YouTube/<slug-canal>/<YYYY-MM-DD>-<slug-video>.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 hablante, se formatean como **<hablante>:** <texto> por turno.
Idempotencia
Re-ingestar la misma URL de video sobrescribe el mismo archivo del vault. Los nombres de los archivos stub de semilla hashean el video_id, por lo que el mismo video fuente produce el mismo nombre de stub en ejecuciones repetidas. 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 stub en el vault con los metadatos del video y la URL fuente, en lugar de fallar silenciosamente. La bandera --whisper está reservada para un futuro fallback de transcripción local y actualmente informa que el fallback no está implementado.
Para un fallback manual hoy, descarga el audio con yt-dlp, transcríbelo con tu flujo de trabajo local de Whisper y agrega subtítulos o texto de transcripción antes de volver a ejecutar la ingesta.
Limitaciones
- Ingesta 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 un stub de metadatos, no una transcripción. - No descarga archivos de video ni realiza transcripción Whisper integrada en esta versión.
- La disponibilidad de 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 subido a YouTube:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
Salida esperada:
Se escribieron 39 palabras en /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Idioma: en. Fuente de subtítulos: manual.
El archivo de salida contiene frontmatter válido y un cuerpo de prosa limpia.
Dependencias
yt-dlp(obligatorio): instalar conbrew install yt-dlpopip3 install --user yt-dlpwhisper-cpp(opcional para un fallback manual fuera de este script)
Fuente
Incluido en adelaidasofia/ai-brain-starter, un harness de verificación para un agente de IA donde la memoria se compone en lugar de corromperse. El skill es parte de la familia de conectores de vault ingest-*.