Transcrição do YouTube

Visão Geral

Transforme uma URL do YouTube em um artefato de leitura refinado, não em um despejo bruto de legendas. Prefira as legendas nativas do YouTube primeiro e, em seguida, recorra à fala para texto somente quando as legendas estiverem ausentes, inutilizáveis ou materialmente incompletas.

Fluxo de Trabalho

Confirme se a entrada é uma URL do YouTube.
Reúna metadados e inspecione se legendas nativas ou legendas geradas automaticamente estão disponíveis.
Decida o idioma esperado da transcrição antes da extração. Se o usuário solicitar uma transcrição em inglês, passe --language en. Se o usuário solicitar a preservação do idioma original, prefira a faixa de idioma falado quando conhecido; caso contrário, trate o idioma como não resolvido até a verificação.
Prefira a extração de legendas, pois é mais rápida e barata que o ASR.
Inspecione o report.json imediatamente após a busca e verifique se selected_language corresponde ao idioma pretendido antes de montar ou renderizar qualquer coisa.
Recorra à fala para texto somente se a extração de legendas falhar, for materialmente incompleta ou as faixas de legenda disponíveis forem ambíguas quanto ao idioma.
Reúna metadados: título, data de publicação, canal, URL e capítulos de origem quando disponíveis.
Normalize a transcrição em parágrafos legíveis, em vez de fragmentos de legendas.
Construa um documento com título, data, metadados de origem, sumário, lista de capítulos e corpo da transcrição.
Salve o produto final como um PDF dentro da pasta do projeto atual.
Adicione tradução para chinês somente quando a solicitação pedir explicitamente.

Contrato de Ambiente

Espere que o ambiente forneça:

python3
Acesso à rede para ler a página do YouTube e qualquer fonte de transcrição
yt-dlp para extração de metadados e legendas no caminho preferencial de legendas
Uma ferramenta ASR local compatível com Whisper ou uma API de transcrição hospedada para fallback
Os scripts agrupados em scripts/

Se alguma capacidade necessária estiver faltando, diga exatamente qual dependência está indisponível e pare antes de afirmar que a transcrição está completa.

Seleção de Fonte

Caminho preferencial de legendas

Prefira este caminho quando legendas nativas ou legendas automáticas do YouTube existirem.

Busque metadados e disponibilidade de legendas primeiro.
Baixe a melhor faixa de legenda no idioma pretendido.
Se existirem legendas manuais e automáticas, prefira as manuais.
Se o usuário especificar um idioma alvo para a transcrição, passe-o explicitamente com --language.
Se o usuário não especificar um idioma, preserve o idioma falado somente quando conhecido ou inferível de forma confiável. Se as faixas de legenda disponíveis abrangerem vários idiomas e o idioma falado não for conhecido, pare o caminho de legendas e trate-o como ambíguo, em vez de escolher um arbitrariamente.
Se as legendas forem parciais, mal dessincronizadas ou omitirem grandes seções faladas, mude para ASR.
Após a busca de legendas, inspecione o report.json e rejeite o resultado se selected_language não corresponder ao idioma pretendido da transcrição.

Ferramentas úteis se disponíveis no ambiente:

yt-dlp para extração de metadados e legendas
O wrapper de extração canônico em scripts/ quando presente

Caminho de fallback ASR

Use ASR somente quando a extração de legendas não estiver disponível ou não for boa o suficiente.

Baixe ou acesse o áudio do YouTube.
Execute a transcrição no idioma de origem quando conhecido.
Preserve o idioma original na transcrição.
Não traduza por padrão.
Use a transcrição como fonte de verdade para o artigo legível final e PDF.

Opções comuns se disponíveis:

Whisper local / faster-whisper
API de transcrição hospedada

Política de Falha

Pare e explique a falha se alguma das seguintes condições for verdadeira:

A entrada não é uma URL do YouTube válida
Os metadados não podem ser buscados
As legendas estão indisponíveis e nenhum fallback ASR está disponível
O download de áudio falha para o caminho ASR
A transcrição é muito incompleta para suportar um sumário confiável

Continue com um aviso quando o trabalho for possível, mas a qualidade for limitada:

As legendas existem, mas parecem parciais, ruidosas ou dessincronizadas
O ASR termina, mas a pontuação ou os limites de fala são fracos
Os limites dos capítulos devem ser inferidos a partir do texto ruidoso da transcrição

Pare e execute novamente com um idioma explícito quando:

O usuário esperava uma transcrição em inglês e report.json selecionou uma faixa não-inglesa
O usuário esperava preservação do idioma de origem, mas o idioma da legenda selecionada é ambíguo ou claramente traduzido

Contrato de Saída

A menos que o usuário solicite o contrário, produza um PDF polido na pasta do projeto atual contendo:

Título
Data de publicação
Linha de origem com canal ou origem
Sumário ou subtítulo
Lista de capítulos perto do topo
Corpo da transcrição legível no idioma original
Marcadores de timestamp grossos apenas quando úteis, como a cada 20 minutos

Não retorne um bloco gigante e não estruturado de texto de legenda como produto principal.

Regras de Formatação

Modele a experiência de leitura com base em postagens longform da OpenAI, como o artigo "Harness Engineering": espaçamento generoso, hierarquia de título forte, metadados compactos, quebras de seção claras e larguras de parágrafo legíveis.

Comece com uma linha superior ou rótulo de seção, como Transcrição do YouTube.
Coloque o título primeiro.
Mantenha a página 1 livre do rótulo de cabeçalho de página repetido e do bloco divisor superior.
Na página 2 e posteriores, coloque o divisor superior de modo que sua distância até o topo da página corresponda à distância do divisor inferior até o final da página.
Coloque o rótulo de página Sissi Skill - Transcrição do YouTube para PDF logo acima do divisor superior na página 2 e posteriores.
Coloque a data de publicação e os metadados de origem diretamente abaixo do título.
Coloque a lista de capítulos perto do topo do documento.
Reinsira os títulos dos capítulos dentro do corpo da transcrição em suas posições correspondentes quando os metadados do capítulo existirem.
Mantenha os parágrafos curtos e legíveis.
Justifique os parágrafos do corpo para que a largura do bloco de texto corresponda à largura da linha divisória.
Mescle fragmentos de legendas em parágrafos em prosa.
Remova sobreposições repetidas causadas pela segmentação de legendas.
Remova ruídos óbvios, como setas repetidas ou marcadores de música isolados, a menos que sejam editorialmente úteis.
Não invente nomes de falantes.
Não emita ruídos densos de timestamp.
Insira marcadores de 20 minutos apenas como auxílios de navegação grossos.
Se o vídeo for mais curto que 20 minutos, omita os marcadores completamente.
Reserve uma faixa de espaço em branco no rodapé em todas as páginas e separe-a do corpo do texto com uma régua horizontal cinza.
Deixe o texto do corpo próximo ao divisor do rodapé, de modo que a linha final fique aproximadamente uma linha acima dele, sem sobreposição.

Heurísticas de Legibilidade

Ao normalizar legendas:

Desduplique repetições exatas de janelas de legenda sobrepostas.
Divida o texto longo em parágrafos com base em lacunas de tempo, finais de frase e comprimento do parágrafo.
Prefira comprimentos de parágrafo que pareçam prosa de ensaio, não fluxos de legendas.
Preserve a pontuação se a fonte a fornecer.
Se a pontuação da fonte for ruim, adicione apenas a pontuação mínima necessária para a legibilidade.

Sumário e Capítulos

Após construir a transcrição, crie:

Um sumário conciso focado no argumento principal ou nos principais aprendizados do vídeo
Uma lista de capítulos com títulos curtos

Se os dados de origem já contiverem metadados de capítulo confiáveis, reutilize-os. Caso contrário, infira capítulos a partir de mudanças de tópico na transcrição.

Exemplos

Exemplo 1: Pacote de transcrição de podcast

Usuário diz: "Transforme esta entrevista do YouTube em um PDF de transcrição limpo."
Ações:
1. Busque metadados e disponibilidade de legendas.
2. Prefira legendas manuais quando disponíveis.
3. Normalize parágrafos da transcrição.
4. Gere sumário e lista de capítulos.
5. Renderize PDF na pasta do projeto atual.
Resultado: PDF de transcrição em estilo de artigo, mais sumário e divisão de capítulos.

Exemplo 2: Sumário mais transcrição de uma palestra de abertura

Usuário diz: "Extraia a transcrição desta palestra de abertura e resuma cada seção."
Ações:
1. Extraia legendas ou use fallback ASR.
2. Reutilize capítulos de origem quando presentes, caso contrário, infira-os.
3. Construa um sumário conciso alinhado à estrutura de capítulos.
4. Salve o PDF final e retorne o sumário no chat.
Resultado: Artefato de leitura utilizável em vez de texto de legenda bruto.

Exemplo 3: Preservar idioma de origem

Usuário diz: "Faça uma transcrição legível desta palestra em espanhol do YouTube."
Ações:
1. Preserve a transcrição em espanhol.
2. Não traduza a menos que explicitamente solicitado.
3. Sinalize problemas de qualidade da fonte se as legendas forem fracas.
Resultado: Pacote de transcrição em espanhol com notas de qualidade honestas.

Exemplo 4: Solicitação explícita de tradução

Usuário diz: "Crie um PDF de transcrição deste vídeo do YouTube e adicione uma tradução para o chinês."
Ações:
1. Extraia a transcrição de origem primeiro.
2. Produza a transcrição polida no idioma de origem.
3. Adicione tradução para o chinês porque foi explicitamente solicitada.
Resultado: Pacote de transcrição que distingue claramente o texto de origem do texto traduzido.

Localização da Saída

Salve o PDF final dentro da pasta do projeto atual, a menos que o usuário solicite outro caminho. Prefira um nome de arquivo slugificado derivado do título do vídeo.

Exemplo:

./cult-leaders-have-terrible-pitches.pdf

Scripts Auxiliares

Use scripts/fetch_youtube_transcript.py como o ponto de entrada canônico de extração. Ele deve ser o primeiro script no fluxo, pois centraliza validação de URL, busca de metadados, seleção de legendas, verificações de qualidade e fallback ASR opcional. Use scripts/asr_faster_whisper.py quando as legendas estiverem indisponíveis e o áudio puder ser baixado. Ele escreve JSON de segmentos para o caminho de fallback usando um modelo faster-whisper local.

Use scripts/assemble_transcript.py para transformar segmentos temporizados em prosa de transcrição legível com marcadores grossos. Quando os títulos dos capítulos precisarem ser inseridos no corpo da transcrição em posições precisas, também escreva metadados de parágrafo em JSON a partir do mesmo script e passe-os para o renderizador de PDF. Se existirem capítulos de origem confiáveis, também passe-os para assemble_transcript.py para que os limites dos parágrafos possam se alinhar com os limites dos capítulos antes da renderização do PDF.

Use scripts/render_blog_pdf.py para transformar metadados, sumário, capítulos e texto da transcrição em um PDF polido sem dependências externas de PDF. Use scripts/validate_transcript_skill.py durante o desenvolvimento para executar verificações de regressão offline para análise VTT, limpeza de sobreposição, inserção de marcadores, metadados de transcrição com reconhecimento de capítulo e renderização de PDF. Use scripts/package_skill_release.py antes da distribuição para construir um zip limpo que exclui arquivos apenas do repositório, como README.md, .git/, tests/ e __pycache__/.

Fluxo típico:

python scripts/fetch_youtube_transcript.py "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir ./youtube_transcript_work --language en
sed -n '1,120p' ./youtube_transcript_work/report.json
python scripts/asr_faster_whisper.py ./downloaded-audio.m4a --output ./youtube_transcript_work/segments.json --model small --device cpu --compute-type int8 --beam-size 1 --vad-filter
python scripts/assemble_transcript.py ./youtube_transcript_work/segments.json --output transcript.txt
python scripts/assemble_transcript.py ./youtube_transcript_work/segments.json --output transcript.txt --metadata-output transcript-metadata.json --chapter-breaks-json ./youtube_transcript_work/chapters.json
# Em seguida, leia título/data/canal de ./youtube_transcript_work/metadata.json e passe-os para o renderizador.
python scripts/render_blog_pdf.py \
  --title "Cult Leaders Have Terrible Pitches" \
  --date "2025-09-16" \
  --channel "The Knowledge Project Podcast" \
  --summary-file summary.txt \
  --chapters-json ./youtube_transcript_work/chapters.json \
  --transcript-metadata-json transcript-metadata.json \
  --transcript transcript.txt \
  --output ./cult-leaders-have-terrible-pitches.pdf
python scripts/validate_transcript_skill.py
python scripts/package_skill_release.py

Verificações de Qualidade

Antes de retornar o resultado, verifique:

O idioma da transcrição corresponde ao conteúdo de origem, a menos que a tradução tenha sido explicitamente solicitada
report.json mostra um selected_language que corresponde ao idioma pretendido da transcrição
A transcrição está materialmente completa
A lista de capítulos é coerente
Os títulos de capítulos inline aparecem nas posições corretas da transcrição quando os capítulos de origem existem
Se os timestamps de capítulos adjacentes estiverem a menos de um minuto de distância, mescle-os em um único título de capítulo inline
Omita timestamps dos títulos de capítulos inline dentro do corpo da transcrição
O documento tem título, data e metadados de origem
O PDF foi escrito com sucesso dentro da pasta do projeto
O texto do corpo é justificado e alinhado à mesma largura das réguas divisoras
Nenhuma página permite que o texto do corpo cruze a faixa de espaço em branco do rodapé
O documento final é legível como um artigo, não como legendas brutas

Se a qualidade da extração for ruim, diga isso brevemente e declare se a fraqueza vem das legendas de origem ou do ASR.

Solução de Problemas

Nenhuma legenda encontrada

Causa: O vídeo não tem legendas manuais ou geradas automaticamente.
Ação: Use ASR somente se uma dependência ASR estiver disponível. Caso contrário, pare e reporte a capacidade faltante.

Legendas parecem incompletas

Causa: A faixa de legenda omite seções faladas ou está materialmente dessincronizada.
Ação: Mude para ASR quando disponível e diga por que o caminho de legendas foi rejeitado.

Faixa de idioma errada selecionada

Causa: Múltiplas faixas de legenda existem e a errada foi escolhida automaticamente.
Ação: Execute fetch_youtube_transcript.py novamente com um --language explícito quando o idioma alvo for conhecido. Se o idioma falado não for conhecido e as faixas de legenda disponíveis forem multilíngues, pare o caminho de legendas como ambíguo, em vez de selecionar uma arbitrariamente.

Fallback ASR indisponível

Causa: Nenhum caminho de transcrição local ou hospedado existe.
Ação: Reporte a dependência faltante em vez de fingir que a transcrição está completa.

PDF renderiza, mas a formatação está degradada

Causa: Blocos de transcrição muito longos, metadados ausentes ou posicionamento de capítulo ruidoso.
Ação: Revertifique a normalização da transcrição, as entradas de capítulo e as entradas de renderização antes de retornar o arquivo.

Usuário quer apenas um sumário

Causa: O

SissiMeow/codex-skill-YouTube-Transcript-PDF

O que é codex-skill-YouTube-Transcript-PDF?

Perguntar na sua IA favorita

Documentação