subs2summary: transcrição e resumo de vídeos do YouTube, em ferramenta aberta e reproduzível

Há uma quantidade crescente de conteúdo audiovisual relevante — entrevistas, análises políticas, documentários, aulas — que circula quase exclusivamente em vídeo. Para pesquisa, ensino e arquivamento, o vídeo é um formato opaco: não dá para buscar dentro dele, não dá para citar com precisão, não dá para reler rapidamente. A informação está lá, mas praticamente inacessível ao trabalho intelectual sistemático.

As legendas automáticas do YouTube poderiam ser uma saída — a maioria dos vídeos longos já as possui. Mas o formato em que chegam (WebVTT com marcações de karaokê, linhas duplicadas a cada rolagem, timestamps espalhados no meio das frases) é inútil para leitura humana ou para alimentar um modelo de linguagem.

Foi para resolver esse gargalo que construí o subs2summary: uma ferramenta de linha de comando que baixa as legendas automáticas, limpa-as em texto corrido legível, detecta o formato do vídeo e prepara um sumário. Está disponível no GitHub, sob licença MIT, e foi pensada desde o início para ser aberta e reproduzível.

O que a ferramenta faz

O pipeline tem quatro estágios, cada um executável de forma independente e idempotente — ou seja, re-executar um estágio reaproveita o que já foi produzido, sem refazer trabalho desnecessário.

Uma URL de entrada, três artefatos em disco: a legenda original, a transcrição limpa e o sumário. O produto principal é o .txt: uma transcrição em prosa corrida, com parágrafos delimitados por minutos, pronta para leitura, citação ou processamento posterior.

Aberta e reproduzível por design

A decisão mais importante no projeto foi fazê-lo funcionar sem amarras. Isso se traduz em três escolhas concretas.

Zero dependências Python

Todo o código usa apenas a biblioteca padrão do Python (argparse, re, subprocess, pathlib, urllib, dataclasses). Não há requirements.txt, não há pip install, não há conflito de versões. A única dependência externa é o yt-dlp — que é Unlicense (domínio público) e é invocado como binário externo via subprocess, sem acoplamento de licença. Isso significa que o projeto inteiro pode ser licenciado sob MIT sem nenhuma reserva.

As chamadas ao LLM também usam urllib.request puro, sem o pacote openai ou httpx. São cerca de trinta linhas de código que falam o protocolo Chat Completions diretamente — o suficiente para interoperar com qualquer endpoint compatível.

Qualquer LLM, sem amarras a fornecedor

O estágio de sumarização funciona com qualquer endpoint compatível com a API da OpenAI. Na prática, isso inclui:

• a própria OpenAI (se for a sua escolha);
• serviços autônomos e locais: Ollama, vLLM, LM Studio;
• provedores nacionais e regionais;
• qualquer gateway ou proxy que fale esse protocolo — que já é o padrão de facto da indústria.

A configuração é por variáveis de ambiente (OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL) ou por flags de linha de comando. Sem credenciais, a ferramenta degrada graciosamente: emite um template estruturado com marcadores para preenchimento manual, em vez de simplesmente falhar. Isso torna o sumário possível mesmo offline — a transcrição limpa, que é o produto principal, nunca depende de LLM.

Estágios idempotentes

Cada estágio pode ser re-executado isoladamente. Se a transcrição já foi limpa, re-rodar --stage clean apenas relê o .vtt existente. Se o sumário não ficou bom, re-roda-se apenas --stage summarise com outro modelo ou outro prompt. Isso torna o pipeline auditável e reproduzível: a partir da mesma URL, qualquer pessoa obtém os mesmos artefatos, e cada passo é verificável.

Como usar

O uso básico é uma linha:

python3 yt_sumarios.py "https://www.youtube.com/watch?v=<ID>"

Isso executa os quatro estágios em sequência e grava os artefatos em output/. Para rodar estágios individuais:

python3 yt_sumarios.py "<url>" --stage clean       # só limpa o .vtt existente
python3 yt_sumarios.py "<url>" --stage summarise   # gera o sumário (LLM) ou template

Para sumarização via LLM, basta configurar o endpoint:

export OPENAI_BASE_URL="https://llm.exemplo.com/v1"
export OPENAI_API_KEY="..."
export OPENAI_MODEL="meu-modelo"
python3 yt_sumarios.py "<url>"

O idioma da legenda é configurável (--lang en, --lang es, …); o padrão é português.

Disponibilidade

O código está público em github.com/DistintiveLab/subs2summary, sob licença MIT. São dois arquivos Python (yt_sumarios.py, o orquestrador; clean_subtitle.py, o limpador de VTT), mais o README e a licença. Sem build, sem empacotamento, sem dépendencias para instalar — git clone e rodar.

A motivação é pragmática. Ferramentas fechadas e serviços em nuvem desaparecem, mudam de preço, mudam de API. Um pipeline que depende apenas da biblioteca padrão do Python, de um baixador de legendas de domínio público e de um protocolo de LLM padronizado tem boas chances de continuar funcionando daqui a alguns anos. E, se parar de funcionar, o código está lá para ser consertado — por qualquer pessoa, em qualquer lugar.

A transcrição limpa e o sumário são os produtos. A ferramenta é apenas o caminho — aberto, curto e reproduzível — para chegar até eles.