Communitygithub.com

tldraw/tldraw

Crie um vídeo narrado que percorre um pull request com slides de código e narração em áudio. Use quando solicitado a criar um PR walkthrough, um vídeo de PR ou um vídeo de walkthrough.

O que é tldraw?

Esta skill permite a criação automatizada de vídeos narrados para revisão de pull requests, funcionando como uma alternativa assíncrona e escalável a vídeos gravados manualmente (como no Loom). Ao receber uma URL de um PR do GitHub, a skill gera um vídeo MP4 em 1280×720 (30 fps) que inclui narração em áudio, legendas amarelas sobre fundo preto com temporização precisa (via whisper) e slides padronizados de introdução e encerramento. O fluxo de trabalho é composto por cinco etapas principais: (1) compreensão do PR através de comandos como `gh pr view` e `git diff`, ignorando arquivos gerados automaticamente; (2) escrita do roteiro de narração em segmentos lógicos (introdução, contexto, walkthrough do código e resumo); (3) geração de áudio segmento por segmento usando a API Gemini TTS (`gemini-3.1-flash-tts-preview`) com a voz "Iapetus"; (4) criação de um manifesto que associa cada slide ao seu áudio e duração; e (5) renderização final do vídeo com legendas sincronizadas, transições e redução de resolução. A skill é ideal para equipes de desenvolvimento que desejam documentar mudanças complexas de forma eficiente, permitindo que revisores entendam rapidamente o "porquê" por trás do código. É suportada em qualquer ambiente que tenha Node.js 22+, ffmpeg e Python 3, e usa whisper localmente para transcrição.

Funciona com✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/tldraw/tldraw/tree/HEAD/skills/pr-walkthrough

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 API
  • apps/docs/content/reference/** — documentação de referência gerada
  • pnpm-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

  1. Para cada segmento, o script monta um prompt: preâmbulo de estilo + texto do segmento.
  2. Uma chamada de API para gemini-3.1-flash-tts-preview por segmento gera um clipe WAV diretamente.
  3. Cada clipe é validado (verificação de duração vs contagem de palavras) e repetido automaticamente se a saída for ruim.
  4. 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:

  1. Copia os arquivos de áudio/imagem referenciados para video/assets/.
  2. 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).
  3. Executa build.mjs <manifest> para gerar video/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.
  4. Verifica a composição e renderiza quadros em 1920×1080 via npx hyperframes render.
  5. 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 de render.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 30 para 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_KEY no arquivo .env da 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/file para 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 manipulador onAfterChange agora 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.mjs se necessário.

Habilidades Relacionadas