ingest-youtube — Conector YouTube-para-cofre

Puxa transcrições do YouTube para um cofre markdown como entradas de memória tipada consultáveis que habilidades downstream (extração de grafo de conhecimento, treinamento de impressão digital de voz, reutilização de conteúdo, extração de itens de ação) podem usar.

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 um URL do YouTube e pede uma transcrição ou resumo
• O usuário diz /ingest-youtube <url> para um único vídeo
• O usuário pede para capturar, sincronizar, ingerir, transcrever ou puxar uma palestra/podcast/keynote para o cofre

NÃO use para:

• Baixar o arquivo de vídeo real (use yt-dlp diretamente com -f best)
• Ingestão em nível de canal ou janelas de --days; este script ingere um URL de vídeo por vez
• Transmissões ao vivo (as transcrições não são estáveis)
• Fontes que não são do YouTube (Vimeo, Twitch, Twitter Spaces têm seus próprios conectores)
• Leituras de transcrição únicas onde o usuário não quer um arquivo no cofre (execute yt-dlp --write-auto-sub diretamente e redirecione para stdout)

Como funciona

1. Analisa a entrada como um URL de vídeo do YouTube.
2. Verifica se yt-dlp está instalado. Se não estiver, o script sai com instruções de instalação: brew install yt-dlp (macOS) ou pip3 install --user yt-dlp.
3. Valida o URL como um único vídeo do YouTube http(s) e chama yt-dlp --ignore-config --list-subs -- <url> para listar as legendas disponíveis.
4. Prioridade de legendas: legendas manuais > legendas geradas automaticamente. Legendas manuais preservam a pontuação e os rótulos de locutor fornecidos pelo criador; legendas automáticas são em maiúsculas + sem pontuação.
5. 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).
6. Remove os marcadores de tempo do VTT e mescla em parágrafos de prosa limpa. Deduplica linhas repetidas (VTTs gerados automaticamente têm linhas duplicadas). Preserva os rótulos de locutor se a fonte os tiver.
7. Puxa metadados do vídeo (título, canal, data de upload, duração, video_id, URL) via yt-dlp --print-json --skip-download.
8. Cria um slug para o nome do canal e o título do vídeo. Escreve em External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md.
9. Escaneia a transcrição em busca de palavras-chave gatilho (decisão, framework, modelo, princípio, "a lição é", playbook, anti-padrão, estudo de caso). Para cada correspondência, cria um rascunho de semente de escrita em Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.md para que a semente caia no agregador de capturas.
10. Imprime um resumo: caminho do arquivo, contagem de palavras da transcrição, idioma, sementes detectadas.

Invocação

python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]

Padrões:

• --vault: variável de ambiente $VAULT_ROOT ou 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 rascunho quando nenhuma legenda está disponível

Contrato de Saída

O arquivo do cofre em External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md tem frontmatter:

---
type: external-input
source: youtube
video_id: <11-char ID>
url: https://www.youtube.com/watch?v=<id>
channel: <channel-name>
channel_url: https://www.youtube.com/<handle>
title: <video title>
upload_date: <YYYY-MM-DD>
duration_seconds: <int>
language: <ISO code>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <ISO 8601 timestamp>
---

O corpo é a transcrição limpa como prosa em parágrafos. Se a fonte tinha rótulos de locutor, formate como **<speaker>:** <text> por turno.

Idempotência

Re-ingerir o mesmo URL de vídeo sobrescreve o mesmo arquivo do cofre. Os nomes dos arquivos de semente de rascunho usam hash do video_id, então o mesmo vídeo de origem produz o mesmo nome de arquivo de rascunho em reexecuções. Reexecuções atualizam, nunca duplicam.

Legendas Ausentes

Se yt-dlp --list-subs retornar legendas manuais ou automáticas, o script escreve uma nota de rascunho no cofre com os metadados do vídeo e o URL de origem em vez de falhar silenciosamente. O sinalizador --whisper é reservado para um fallback de transcrição local futuro e atualmente relata que o fallback não está implementado.

Para um fallback manual hoje, baixe o áudio com yt-dlp, transcreva-o com seu fluxo de trabalho local do Whisper e adicione legendas ou texto de transcrição antes de reexecutar a ingestão.

Limitações

• Ingere um URL de vídeo do YouTube por execução; canais, playlists e janelas de --days estão fora do escopo.

…