Vídeo de walkthrough de PR
Crie um vídeo narrado para percorrer um pull request. Este é um artefato interno, que oferece o mesmo benefício que um vídeo criado pelo autor do pull request no Loom — percorrer as alterações de código, explicando o que foi feito e por que, para que qualquer espectador possa entender o PR rapidamente.
Entrada: Uma URL de pull request do GitHub (ex.: https://github.com/tldraw/tldraw/pull/7924). Se for fornecido apenas um número de PR ou outra descrição, assuma que o PR está no repositório tldraw/tldraw.
Saída: Um vídeo MP4 em 1280×720 (30 fps) com narração em áudio, legendas amarelas sobre fundo preto com temporização via whisper, e slides padronizados de introdução/encerramento, salvo em out/pr-<número>-walkthrough.mp4.
Todos os arquivos intermediários (áudio, manifesto, scripts) vão para tmp/pr-<número>/ relativo ao diretório desta skill. Este diretório está no .gitignore. Apenas o .mp4 final fica em out/.
Execute comandos que referenciam ./scripts ou ./video a partir do diretório desta skill.
Filosofia
Este é um walkthrough da perspectiva do autor. O objetivo é o mesmo que se o autor do PR se sentasse com alguém e mostrasse as alterações — mostrando código específico, explicando o que mudou e por que, em uma ordem que construa entendimento. O espectador deve sair entendendo tanto o que o código faz quanto como pensar sobre as mudanças.
Isso significa:
- A narração comanda tudo. Escreva a narração do walkthrough primeiro, como uma explicação contínua do PR. Depois, descubra o que deve estar na tela em cada momento para apoiar o que está sendo dito.
- Mostre o código. O visual padrão é um diff de código ou arquivo fonte. Slides de texto são a exceção (introdução, transições breves, encerramento), não a regra. Quando a narração fala sobre uma função, o espectador deve estar olhando para essa função.
- Percorra as mudanças em uma ordem lógica, não necessariamente a ordem dos arquivos ou dos commits — mas sempre ancorado em código concreto, não em descrições abstratas.
- Explique o "porquê", não apenas o "o quê". O código na tela mostra o que mudou. A narração adiciona a lógica — por que essa abordagem, que problema resolve, que casos de borda trata.
Fluxo de trabalho
Passo 1: Entenda o PR
Leia os commits, diff e descrição do PR. Entenda o arco narrativo:
- Que problema isso resolve?
- Qual é a abordagem?
- Quais são os mecanismos principais?
gh pr view <número> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat
Ignore arquivos gerados. Ao ler o diff, ignore arquivos que são gerados automaticamente em vez de editados manualmente. Eles adicionam ruído sem informar o walkthrough. Exemplos comuns neste repositório:
**/api-report.md,**/api-report.api.md— relatórios de superfície de API gerados**/*.api.json,**/temp/*.api.json— saída do extrator de APIapps/docs/content/reference/**— documentação de referência geradapnpm-lock.yaml,package-lock.json— arquivos de lock**/CHANGELOG.md— changelogs gerados automaticamente- Qualquer arquivo que as ferramentas do repositório regenerem (snapshots, dumps de esquema, assets empacotados)
Se não tiver certeza se um arquivo é gerado, verifique se há um comentário de cabeçalho como "DO NOT EDIT" ou veja se o repositório tem um comando gerador que o produza. Filtre-os ao escolher quais arquivos incluir em slides de diff/code.
Passo 2: Escreva a narração
Escreva a narração como texto contínuo, dividido em segmentos lógicos. Cada segmento é uma batida do walkthrough — um conceito, uma mudança ou um grupo de mudanças relacionadas. Salve como tmp/pr-<número>/SCRIPT.md.
A narração deve soar como o autor explicando o PR a um colega: "Então, aqui está o que estamos fazendo... O problema central era X... A abordagem que tomei foi Y... Se você olhar para esta função aqui..."
Estrutura: introdução → contexto/problema → walkthrough do código → resumo. Veja Estrutura do roteiro abaixo.
Se os commits são simples e bem organizados (frequentemente em um branch com -clean no nome), você pode seguir suas mensagens e descrições para guiar sua narração. Caso contrário, examine o código e crie sua própria narrativa. Introduza conceitos em uma ordem que se baseie nos anteriores.
Evite redundância, especialmente entre a introdução e o primeiro segmento de conteúdo.
Passo 3: Gere áudio e timestamps
Gere clipes de áudio por segmento com uma chamada TTS por segmento. Isso evita completamente segmentação, alinhamento e divisão — cada segmento é curto o suficiente para uma única chamada TTS confiável.
Escreva um arquivo narration.json, depois execute a ferramenta CLI generate-audio.sh:
./scripts/generate-audio.sh narration.json tmp/pr-<número>/
Chave de API: Obtida automaticamente do arquivo .env do repositório (GEMINI_API_KEY).
Formato do JSON de narração
{
"style": "Leia a narração do walkthrough a seguir em um tom calmo, constante e profissional. Fale em um ritmo medido, como se o autor de um pull request estivesse mostrando as alterações de código a um colega.",
"voice": "Iapetus",
"slides": [
"Este pull request adiciona resolução de binding consciente de grupo à ferramenta de seta...",
"O problema central era que os bindings de seta quebravam quando a forma alvo estava...",
"Se você olhar para o método getBindingTarget em ArrowBindingUtil.ts..."
]
}
style— Instruções de persona e ritmo de voz. Mantenha curto e específico.voice— Nome da voz Gemini (padrão:Iapetus).slides— Array de texto da narração, uma entrada por segmento.
Como funciona
- Para cada segmento, o script monta um prompt: preâmbulo de estilo + texto do segmento.
- Uma chamada de API para
gemini-3.1-flash-tts-previewpor segmento gera um clipe WAV diretamente. - Cada clipe é validado (verificação de duração vs contagem de palavras) e repetido automaticamente se a saída for ruim.
- Silêncio inicial e final é removido de cada clipe.
Saída: Clipes de áudio por segmento (audio-00.wav, ...) e um arquivo durations.json mapeando cada nome de arquivo de áudio para sua duração em segundos.
Dependências: ffmpeg / ffprobe. Nenhum pacote Python necessário além da biblioteca padrão.
NÃO use tags de marcação [pause long] ou [pause medium] no texto da narração — o modelo pode lê-las literalmente em voz alta.
Passo 4: Escreva o manifesto
Leia durations.json do passo 3 para cada comprimento de clipe, depois escreva manifest.json junto com os arquivos de áudio. Ele lista uma entrada por slide, em ordem, cada uma com seu type, audio, e durationInSeconds.
Veja references/manifest.md para os tipos de slide e seus campos.
Passo 5: Renderize o vídeo
Execute o script render.sh:
./video/render.sh \
tmp/pr-<número>/manifest.json \
out/pr-<número>-walkthrough.mp4
O script:
- Copia os arquivos de áudio/imagem referenciados para
video/assets/. - Executa a transcrição whisper em cada arquivo de áudio →
video/transcripts/audio-NN.json(idempotente — só retranscreve se o áudio for mais novo que o transcript existente). - Executa
build.mjs <manifest>para gerarvideo/index.html— uma composição hyperframes com clipes temporizados para cada slide, timeline GSAP para transições e foco de código, e clipes de legenda amarela sobre fundo preto com horários de início/fim derivados dos transcripts do whisper. - Verifica a composição e renderiza quadros em 1920×1080 via
npx hyperframes render. - Redimensiona para 1280×720 / 30fps e recompacta com ffmpeg (CRF 26 + AAC 96k) para o MP4 final pequeno mas nítido.
Dependências: Node.js 22+, ffmpeg, Python 3 (usado pelo render.sh para analisar o manifesto). hyperframes é invocado via npx --yes, então nenhum passo de instalação. Whisper roda localmente (modelo small.en, ~150MB no primeiro download).
Sincronização de legendas via whisper
As legendas aparecem como texto amarelo em uma pílula preta sólida, ancorada na parte inferior do quadro. Seus horários de início/fim vêm de transcrições whisper a nível de palavra agrupadas em chunks de 5 a 7 palavras, quebrando cedo em pausas naturais (intervalos >450ms = limites de frase). Uma implicação: whisper transcreve nomes de marcas/código foneticamente — "tldraw" → "TL Draw", "OverlayUtil" → "overlay util". Isso é aceitável para legendas, mas pode ser normalizado posteriormente por uma tabela de substituição em build.mjs.
Controles de tamanho de arquivo
A renderização padrão visa ~30-60 MB para um vídeo de 8 minutos. Para ajustar:
--crf <n>na etapa de redução do ffmpeg dentro derender.sh— 22 é quase sem perdas, 26 é o padrão, 30+ é muito menor. CRF 28-30 é uma boa faixa para um resultado de qualidade de documentação.- A renderização hyperframes em 1080p usa
-q draft --crf 30para manter o arquivo intermediário pequeno (a redução domina o tamanho final de qualquer forma).
Organização de arquivos
A saída final fica no diretório desta skill. Todos os arquivos intermediários vão para tmp/ (gitignored):
pr-walkthrough/
├── SKILL.md # Este arquivo
├── scripts/ # Ferramentas CLI (versionadas)
│ └── generate-audio.sh # narration.json → WAVs por slide + durations.json
├── video/ # Projeto hyperframes (versionado)
│ ├── hyperframes.json # Configuração hyperframes
│ ├── meta.json # Meta do projeto
│ ├── build.mjs # manifest.json → composição index.html
│ ├── render.sh # manifest.json → MP4 720p (pipeline completo)
│ ├── assets/ # Preenchido automaticamente na renderização (gitignored)
│ ├── transcripts/ # JSON a nível de palavra do whisper (gitignored, cache)
│ └── renders/ # Renderizações intermediárias em 1080p (gitignored)
├── out/ # Saídas finais (gitignored)
│ └── pr-XXXX-walkthrough.mp4
└── tmp/ # Arquivos intermediários (gitignored)
└── pr-XXXX/
├── SCRIPT.md # Roteiro da narração
├── narration.json # Entrada para generate-audio.sh
├── durations.json # Nome do arquivo de áudio → duração em segundos
├── manifest.json # Entrada para render.sh
└── audio-XX.wav # Clipes de áudio por segmento
Configuração da API
- Chave de API Gemini: Armazenada como
GEMINI_API_KEYno arquivo.envda raiz do projeto. Usada para TTS e alinhamento de áudio. - Modelo TTS:
gemini-3.1-flash-tts-preview - Voz TTS:
Iapetus(sempre)
Estrutura do roteiro
O walkthrough segue um arco narrativo consistente. Nem toda seção precisa de seu próprio segmento — combine ou pule seções com base na complexidade do PR. O objetivo é 8 a 12 segmentos no total, com a grande maioria mostrando código.
Introdução (1 segmento)
O cartão de introdução: logotipo tldraw + título do PR + data. A narração deve ser uma única frase que enquadra o que este PR faz em alto nível. Não entre em detalhes ainda.
Tipo de slide do manifesto: intro.
Contexto (0-1 segmentos)
Breve orientação antes de mergulhar no código. Qual era a situação antes deste PR? Que problema ou necessidade motivou o trabalho? Mantenha curto — apenas enquadramento suficiente para que o walkthrough do código faça sentido.
- Seja concreto: "Os bindings de seta quebravam quando a forma alvo estava dentro de um grupo" e não "Havia problemas com bindings"
- Nomeie a área do código afetada
Se o contexto puder ser explicado enquanto mostra o primeiro pedaço de código relevante, pule o segmento de contexto isolado e integre-o ao primeiro segmento de código.
Tipo de slide do manifesto: text ou diff (se mostrando o código problemático).
Walkthrough de código (6-10 segmentos)
A parte principal do vídeo. Percorra as alterações reais de código, mostrando diffs e arquivos específicos enquanto explica o que foi feito e por quê.
Cada segmento deve mostrar código. Use slides diff para mudanças e slides code para código de referência não alterado.
Diretrizes:
- Nomeie arquivos e funções. Cada segmento narrado deve fazer referência a pelo menos um arquivo ou função específica.
- Mostre o diff. O visual de cada segmento deve ser o diff real sendo discutido. Use
git diff main..HEAD -- path/to/filepara obter o diff, depois extraia os hunks relevantes. - Ordene por entendimento, não por arquivo. Apresente as mudanças na ordem que constrói compreensão. Se um novo tipo é definido em um arquivo e consumido em outro, mostre a definição primeiro.
- Explique o "porquê", não apenas o "o quê". O diff mostra o que mudou — a narração adiciona a lógica, os casos de borda que trata, as alternativas que foram consideradas.
- Pule boilerplate, mas mencione-o. Não dedique um segmento a cada mudança de importação ou exportação de tipo, mas mencione de passagem: "Há também algumas exportações de tipo adicionadas em
index.ts— são apenas re-exportações dos novos tipos que veremos a seguir." - Agrupe mudanças pequenas relacionadas. Se três arquivos receberam a mesma correção de uma linha, um segmento pode cobrir todos os três. Mencione cada arquivo pelo nome.
Resumo (1 segmento)
Recapitule brevemente o que o PR realizou. Este é um encerramento curto — uma ou duas frases resumindo a mudança geral, mencionando quaisquer limitações conhecidas ou trabalho futuro, se relevante.
Tipo de slide do manifesto: text.
Encerramento (1 segmento, silencioso)
O logotipo tldraw, 3 segundos de silêncio. Sempre inclua este como o último slide.
Tipo de slide do manifesto: outro com durationInSeconds: 3.
Dicas para escrever a narração
- Seja específico sobre o código. Diga "Em
BindingUtil.ts, o manipuladoronAfterChangeagora verifica ancestrais de grupo" — não "O sistema de binding foi atualizado." Nomeie arquivos e funções para que o espectador possa conectar a narração ao que está na tela. - Cada segmento = uma mudança ou grupo intimamente relacionado de mudanças. Se você não puder apontar para um diff específico para o segmento, provavelmente é muito abstrato.
- Escreva como o autor. O tom deve ser explicativo e natural — como se estivesse mostrando seu trabalho a alguém. "Então, o principal aqui é..." ou "A parte complicada era..." são aceitáveis.
- Evite redundância entre a introdução e o primeiro segmento de conteúdo.
- Mencione arquivos que não são mostrados. Se um PR toca em 15 arquivos, mas apenas 6 são interessantes, reconheça brevemente os outros: "As mudanças restantes são exportações de tipo e fixtures de teste."
- Aponte para 5 a 7 minutos de narração total.
Lista de verificação
- Leia todos os commits do PR e entenda o diff completo
- Escreva a narração em SCRIPT.md (8 a 12 segmentos)
- Gere áudio por segmento (voz Iapetus)
- Leia durations.json para obter as durações por segmento
- Escreva manifest.json com os tipos de slide e durações
- Renderize o vídeo final
- Verifique o resultado: som, legendas, transições, qualidade visual
Arquivos de referência
references/manifest.md— Tipos de slide e campos do manifesto
Observações
- Esta skill depende da disponibilidade da API Gemini para TTS. Para fallback ou teste, você pode substituir o provedor TTS editando
generate-audio.sh. - O pipeline usa hyperframes para composição. Veja a documentação do hyperframes para personalização avançada de layout e estilo.
- As legendas whisper são uma boa primeira versão, mas podem conter erros fonéticos. Uma tabela de substituição pós-processamento pode ser adicionada em
build.mjsse necessário.