O que ingest-youtube — Conector YouTube-para-vault faz?
Converte transcrições do YouTube em entradas de memória tipadas e consultáveis no vault que outras habilidades (extração de grafo de conhecimento, treinamento de impressão vocal, reaproveitamento de conteúdo, extração de itens de ação) podem utilizar.
Este é o mesmo padrão de 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
- O usuário cola uma URL do YouTube e pede uma transcrição ou resumo
- O usuário digita
/ingest-youtube <url>para um único vídeo - O usuário pede para capturar, sincronizar, ingerir, transcrever ou obter 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 todo um canal ou janelas de
--days; este script ingere uma URL de vídeo por vez - Transmissões ao vivo (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 únicas de transcrição onde o usuário não quer um arquivo no vault (use
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. - Valida a URL como um único vídeo http(s) do YouTube e chama
yt-dlp --ignore-config --list-subs -- <url>para listar as legendas disponíveis. - Prioridade de legendas: legendas manuais > legendas automáticas. Legendas manuais preservam pontuação e rótulos de falantes fornecidos pelo criador; legendas automáticas são em maiúsculas e sem pontuação.
- Baixa a legenda de maior prioridade como 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 gerados automaticamente têm linhas duplicadas). Preserva rótulos de falantes se a fonte os tiver.
- Obtém 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 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. - Examina a transcrição em busca de palavras-chave de gatilho (decisão, framework, modelo, princípio, "a lição é", playbook, anti-padrão, estudo de caso). Para cada correspondência, cria um stub de escrita em
Meta/Captures/<AAAA-MM-DD>-youtube-<slug-do-canal>-<video-id>.md, fazendo com que o stub apareça no agregador de capturas. - Exibe um resumo: caminho do arquivo, contagem de palavras da transcrição, idioma, stubs detectados.
Invocação
python3 ingest.py <youtube-url> [--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; corresponde a um padrão bilíngue comum)--whisper: aceito como um sinalizador de fallback futuro, mas esta versão escreve um stub quando nenhuma legenda está disponível
Contrato de saída
O arquivo do vault em External Inputs/YouTube/<slug-do-canal>/<AAAA-MM-DD>-<slug-do-video>.md tem 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 prosa em parágrafos. Se a fonte tinha rótulos de falantes, formate como **<falante>:** <texto> por turno.
Idempotência
Reingerir a mesma URL de vídeo sobrescreve o mesmo arquivo do vault. Os nomes de arquivo dos stubs fazem hash do video_id, então o mesmo vídeo fonte produz o mesmo nome de arquivo de stub 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 stub no vault com os metadados do vídeo e a URL fonte em vez de falhar silenciosamente. O sinalizador --whisper está reservado para uma futura transcrição local de fallback e atualmente informa que o fallback não está implementado.
Para um fallback manual hoje, baixe o áudio com yt-dlp, transcreva 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 canais, playlists e janelas
--daysestão fora do escopo. - Depende das legendas retornadas por
yt-dlp; vídeos sem legendas produzem um stub de metadados, não uma transcrição. - Não baixa arquivos de vídeo nem executa 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 já enviado ao 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 um fallback manual fora deste script)
Fonte
Empacotado em adelaidasofia/ai-brain-starter, uma estrutura de verificação em torno de um agente de IA para que a memória se acumule em vez de se corromper. A habilidade faz parte da família de conectores de vault ingest-*.