YouTube Summary (Resumo do YouTube)

Resumo do YouTube (YouTube Summary)

Pipeline: obter transcrição -> ler tudo -> escrever um resumo estruturado em Markdown -> renderizar PDF. scripts/fetch_transcript.py cuida do primeiro passo e scripts/md_to_pdf.py do último. Você escreve o resumo no meio.

1. Acesso: apenas o que o usuário já pode assistir

• Vídeos públicos e não listados não precisam de login. Sempre tente primeiro sem cookies.
• Um vídeo privado ou de membros faz o script sair com NEEDS_SIGNIN. Você só pode prosseguir lendo cookies de um navegador onde a conta do próprio usuário que recebeu acesso está logada.
  • Pergunte qual navegador (e perfil, se ele usa mais de um) antes de passar --browser. Cookies são suas credenciais.
  • Avise que a documentação do yt-dlp adverte que o uso automatizado de uma conta logada pode resultar em limitação de taxa ou banimento. Para os próprios envios do usuário, o download pelo YouTube Studio ou Google Takeout é a alternativa sem riscos, e o script aceita o arquivo local resultante.
• Nunca tente burlar configurações de privacidade, bloqueios regionais, DRM ou paywalls, e nunca use a conta de outra pessoa. Se a conta do usuário não puder ver o vídeo, avise e pare.
• "Este vídeo é privado", mesmo com --browser, geralmente significa que a conta com acesso não é a conta padrão logada no navegador. Sugira --browser chrome:"Profile 2" ou fazer login com essa conta em um perfil novo.

2. Obter a transcrição (em segundo plano: vídeos longos demoram)

Use uma pasta de trabalho durável, nunca uma área de rascunho de sessão, que pode ser limpa no meio do trabalho: ~/youtube-summaries/<video-id-ou-nome-do-arquivo>/. Inicie o trabalho em segundo plano para que ele sobreviva ao fim da sessão:

OUT=~/youtube-summaries/<id>; mkdir -p "$OUT"
nohup python3 -I ~/.claude/skills/youtube-summary/scripts/fetch_transcript.py "<url-ou-arquivo>" \
  --out "$OUT" [--browser chrome] [--lang en|auto] [--force-audio] [--audio mp3|m4a|wav] \
  > "$OUT/run.log" 2>&1 &!

Em seguida, espere com um loop until em Bash em vez de fazer polling: until grep -qE '^(DONE|FAILED|NEEDS_SIGNIN)' "$OUT/status"; do sleep 15; done; cat "$OUT/status".

O que o script faz:

• Analisa metadados, depois usa legendas manuais, recorrendo a legendas automáticas;
• Sem legendas, baixa o áudio e o transcreve com mlx-whisper large-v3-turbo no Apple Silicon (openai-whisper em outros lugares). Ele obtém ffmpeg do imageio-ffmpeg se nenhum estiver instalado;
• Remove as alucinações de silêncio do Whisper ("Thank you.") e as repetições contínuas em legendas automáticas;
• Escreve transcript.txt como parágrafos de 2 minutos [h:mm], além de meta.json.

Tempo: cerca de 4–5 minutos de transcrição por hora de áudio em um Mac com chip M-series e 8 GB, além do tempo de download. Informe ao usuário o tempo de espera esperado e, se ele pedir progresso, reporte a porcentagem de download ou o último timestamp em run.log.

Use --force-audio quando as legendas automáticas forem ruins (música, sotaques carregados, idioma errado). Use --lang auto para vídeos em outros idiomas.

Extração de áudio: passe --audio mp3 (ou m4a/wav) sempre que o usuário quiser o áudio em si: "me dê o mp3", "extraia o áudio", uma versão em podcast ou para ouvir offline. O arquivo é salvo como <título>.<formato> em $OUT, e seu caminho é registrado como audio_file em meta.json. As legendas ainda são usadas para a transcrição quando disponíveis, portanto solicitar o áudio não força uma transcrição lenta. Se o usuário quiser apenas o áudio e nenhum resumo, pare após esta etapa e informe o arquivo.

3. Leia tudo, depois resuma

Leia o transcript.txt inteiro; o usuário geralmente quer todos os detalhes. Acima de ~60.000 palavras, leia em partes ordenadas e faça anotações por parte antes de escrever.

Escreva $OUT/summary.md com suas próprias palavras: um resumo, não uma transcrição. Citações curtas são aceitáveis; longos trechos literais não. Estrutura padrão (adapte as seções ao vídeo):

# <Título do vídeo>

| | |
|---|---|
| Vídeo | <título> |
| Canal | <canal> |
| Link | <url> |
| Duração | <duração> |
| Palestrante(s) | <apenas nomes realmente mencionados no vídeo> |
| Transcrição | <legendas manuais / legendas automáticas / transcrição local com Whisper> |

## 1. Em resumo
- 5-8 marcadores: o que o vídeo cobre e as principais conclusões

## Linha do tempo
| Tempo | Tópico |
|---|---|
| 0:00 | ... |

## 2. <Seção por capítulo/tópico, na ordem do vídeo>
### <Sub-tópico>
- todos os fatos concretos, números, nomes, definições, exemplos, etapas, avisos e recomendações
- demonstrações e tutoriais como etapas numeradas; comparações como tabelas

## Fatos principais / conclusões
| Item | Valor |

## Notas sobre este resumo
> Como a transcrição foi produzida; termos ouvidos erroneamente que você corrigiu; declarações que o palestrante errou (com a correção); qualquer coisa inaudível ou incerta.

Por que esta forma: a linha do tempo permite que o leitor pule para o vídeo; as tabelas coletam os fatos que as pessoas pesquisam depois; a seção de notas mantém você honesto sobre erros de transcrição. A conversão de fala para texto distorce nomes de produtos e jargões, então corrija-os pelo contexto e liste as correções. Verifique os fatos que o palestrante afirma incorretamente em vez de repeti-los.

Mantenha o corpo com fontes: tudo acima da seção Notas deve vir da transcrição ou do meta.json. Os leitores tratam o documento como um registro do que o vídeo diz, portanto coisas que você sabe sobre o vídeo (quem é o palestrante, onde foi filmado, sua história) não pertencem ao corpo, mesmo quando você tem certeza. Se esse contexto realmente ajudar, coloque-o em Notas e rotule como "fora do vídeo". Nunca atribua nomes ou pronomes que o vídeo não fornece. Se a descrição do vídeo não estiver relacionada ao conteúdo (descrições reutilizadas ou spam são comuns), ignore-a e avise em Notas.

Dimensione o documento conforme o vídeo. Use <!-- pagebreak --> apenas para iniciar uma nova parte importante de um documento longo (por exemplo, cada capítulo de uma transmissão de várias horas), nunca após a tabela de capa. Um clipe de 2 minutos deve caber em uma ou duas páginas.

4. Renderize e verifique o PDF

uv run ~/.claude/skills/youtube-summary/scripts/md_to_pdf.py "$OUT/summary.md" "$OUT/<Título>.pdf"

Renderize a página 1 e uma página densa como PNG e observe-as antes de relatar: uvx --with pypdfium2 --with pillow python -c "...". Em seguida, forneça ao usuário:

• o caminho absoluto do PDF e o número de páginas;
• uma visão geral de 3-5 linhas;
• quaisquer ressalvas: transcrição gerada automaticamente, seções que estavam inaudíveis.

O arquivo de áudio pode ser grande. Mencione-o e deixe o usuário decidir se deseja excluí-lo.

Solução de problemas

• Sign in to confirm you're not a bot / HTTP 403 em um vídeo público: aguarde e tente novamente. Se persistir, é um problema de IP ou limite de taxa. Não entre em loop.
• Avisos de runtime JS do yt-dlp: o script passa --js-runtimes node quando Deno está ausente. Node 22+ é necessário.
• Nenhuma palavra na transcrição, ou transcrição cheia de lixo: verifique o idioma (--lang auto) ou execute novamente com --force-audio.