ingest-youtube — Conector YouTube para vault
Converte transcrições do YouTube em entradas de memória tipadas e consultáveis no seu vault de markdown. Essas entradas podem ser usadas por skills auxiliares (como extração de grafos de conhecimento, treinamento de impressão digital de voz, reaproveitamento de conteúdo, extração de itens de ação).
Mesmo padrão dos conectores ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, ingest-gmail. Adicionar YouTube significa um novo normalizador, não uma nova arquitetura.
Quando usar
- Usuário cola uma URL do YouTube e pede uma transcrição ou resumo
- Usuário digita
/ingest-youtube <url>para um vídeo específico - Usuário pede para capturar, sincronizar, ingerir, transcrever ou puxar uma palestra/podcast/keynote para o vault
NÃO use para:
- Baixar o arquivo de vídeo real (use
yt-dlpdiretamente com-f best) - Ingestão de canais inteiros ou janelas
--days; este script ingere uma URL de vídeo por vez - Transmissões ao vivo (as transcrições não são estáveis)
- Fontes que não sejam YouTube (Vimeo, Twitch, Twitter Spaces têm seus próprios conectores)
- Leituras de transcrição avulsas onde o usuário não quer um arquivo no vault (execute
yt-dlp --write-auto-subdiretamente e redirecione para stdout)
Como funciona
- Interpreta a entrada como uma URL de vídeo do YouTube.
- Verifica se
yt-dlpestá instalado. Se não estiver, o script exibe instruções de instalação:brew install yt-dlp(macOS) oupip3 install --user yt-dlp. - Chama
yt-dlp --list-subs <url>para listar as legendas disponíveis. - Prioridade das legendas: legendas manuais > legendas automáticas. Legendas manuais preservam pontuação e identificadores de falantes fornecidos pelo criador; as automáticas são em maiúsculas e sem pontuação.
- Baixa a legenda de maior prioridade no formato VTT via
yt-dlp --write-sub --sub-lang <lang> --skip-download. Preferência de idioma padrão:en,es(inglês primeiro, espanhol segundo). - Remove os marcadores de tempo VTT e mescla em parágrafos de prosa limpa. Remove linhas duplicadas (VTTs automáticos costumam repetir linhas). Preserva identificadores de falantes se a origem os tiver.
- Extrai metadados do vídeo (título, canal, data de upload, duração, video_id, URL) via
yt-dlp --print-json --skip-download. - Cria um slug a partir do nome do canal e do título do vídeo. Escreve em
External Inputs/YouTube/<slug-do-canal>/<AAAA-MM-DD>-<slug-do-video>.md. - Escaneia a transcrição em busca de palavras-chave (decisão, framework, modelo, princípio, "a lição é", playbook, anti-padrão, estudo de caso). Para cada correspondência, cria um rascunho de captura em
Meta/Captures/<AAAA-MM-DD>-youtube-<slug-do-canal>-<id-do-video>.mdpara que o rascunho apareça no agregador de capturas. - Exibe um resumo: caminho do arquivo, contagem de palavras da transcrição, idioma, rascunhos detectados.
Invocação
python3 ingest.py <url-do-youtube> [--vault <caminho>] [--lang <código>]
Padrões:
--vault: variável de ambiente$VAULT_ROOTou diretório atual--lang:en,es(inglês primeiro, espanhol segundo; compatível com um padrão bilíngue comum)--whisper: aceito como uma flag futura de fallback, mas esta versão escreve um rascunho quando não há legendas disponíveis
Contrato de saída
O arquivo do vault em External Inputs/YouTube/<slug-do-canal>/<AAAA-MM-DD>-<slug-do-video>.md tem o seguinte frontmatter:
---
type: external-input
source: youtube
video_id: <ID de 11 caracteres>
url: https://www.youtube.com/watch?v=<id>
channel: <nome-do-canal>
channel_url: https://www.youtube.com/<handle>
title: <título-do-vídeo>
upload_date: <AAAA-MM-DD>
duration_seconds: <int>
language: <código ISO>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <timestamp ISO 8601>
---
O corpo é a transcrição limpa em parágrafos de prosa. Se a origem tiver identificadores de falantes, o formato será **<falante>:** <texto> por turno.
Idempotência
Reingerir a mesma URL de vídeo sobrescreve o mesmo arquivo do vault. Os nomes dos rascunhos de captura usam hash do video_id, então a mesma fonte de vídeo produz o mesmo nome de arquivo de rascunho em execuções repetidas. Reexecuções atualizam, nunca duplicam.
Legendas ausentes
Se yt-dlp --list-subs não retornar legendas manuais ou automáticas, o script escreve uma nota de vault de rascunho com os metadados do vídeo e a URL de origem, em vez de falhar silenciosamente. A flag --whisper está reservada para um fallback futuro de transcrição local e atualmente informa que o fallback não foi implementado.
Para um fallback manual hoje, baixe o áudio com yt-dlp, transcreva-o com seu fluxo de trabalho Whisper local e adicione legendas ou texto da transcrição antes de reexecutar a ingestão.
Limitações
- Ingere uma URL de vídeo do YouTube por execução; handles de canal, playlists e janelas
--daysestão fora do escopo. - Depende das legendas retornadas pelo
yt-dlp; vídeos sem legendas produzem um rascunho de metadados, não uma transcrição. - Não baixa arquivos de vídeo nem realiza transcrição Whisper embutida nesta versão.
- Disponibilidade de rede, acesso a legendas do YouTube e comportamento local do
yt-dlpdeterminam se a ingestão é bem-sucedida.
Teste de aceitação
Execute contra o primeiro vídeo do YouTube:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
Saída esperada:
Wrote 39 words to /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Language: en. Subtitle source: manual.
O arquivo de saída contém frontmatter válido e um corpo de prosa limpo.
Dependências
yt-dlp(obrigatório): instale viabrew install yt-dlpoupip3 install --user yt-dlpwhisper-cpp(opcional para fallback manual fora deste script)
Fonte
Incluso em adelaidasofia/ai-brain-starter, um kit de verificação em torno de um agente de IA para que a memória se acumule em vez de corromper. O skill faz parte da família de conectores de vault ingest-*.