SkelegonDK/code-explainer-video

Vídeo explicativo de código

Walkthroughs narrados e animados de código para desenvolvedores. O espectador é um engenheiro: mostre código real, nomeie arquivos e funções reais, explique por que e como, nunca simplifique para analogias para não desenvolvedores.

Stack: template Code Hike do Remotion (código com destaque sintático que se transforma entre os passos), Mermaid para diagramas de arquitetura, ElevenLabs para narração (o conector ElevenLabs, ou a API com uma chave) e legendas embutidas. Carregue a skill remotion-best-practices ao alterar o código Remotion em template/.

Arquivos ao lado deste SKILL.md ("o diretório da skill"):

• template/: os arquivos fonte do Remotion copiados para cada projeto de vídeo.
• references/voice.md: leia no passo 8, antes de gerar a narração.
• references/long-form.md: leia primeiro quando o vídeo tiver 15-30 minutos; ele divide o trabalho em capítulos que passam pelos passos 2-9.

1. Entrada: três perguntas, nesta ordem, antes de qualquer trabalho

Faça uma pergunta por vez (AskUserQuestion quando disponível). Não pule nem as mescle.

1. O que você precisa entender? Obtenha o alvo (uma linha, bloco, função, arquivo, fluxo ou arquitetura inteira) e o motivo (corrigir um bug, adicionar uma funcionalidade, revisar um PR, onboard). Se a resposta for vaga ("a parte de autenticação"), leia o código primeiro e ofereça de 2 a 4 ângulos concretos para escolher, por exemplo, "como uma requisição é autenticada de ponta a ponta" vs. "como as sessões são armazenadas e expiradas".
2. Quanto tempo deve levar? Ofereça: ~30 s (uma linha ou bloco), 1-2 min (uma função ou módulo), ~5 min (um subsistema ou fluxo), 15-30 min (onboarding de código, construído como capítulos por agentes paralelos). Se não souber, recomende um com base no que encontrou no passo 1.
3. Meu entendimento está correto? Após ler o código, envie de volta:
   • a pergunta que o vídeo responde, em uma frase;
   • a duração e a quantidade de beats;
   • o esboço: uma linha por beat (o que está na tela + o ponto que ele faz);
   • qualquer coisa que esteja deixando de fora propositalmente. Construa apenas após um "sim". Revise e reconfirme em caso de "não". Este passo existe porque a narração custa créditos ElevenLabs e as renderizações levam minutos.

Quando executar sem supervisão (ninguém para responder), escolha a leitura mais razoável, declare-a no topo da sua resposta e prossiga.

2. Pesquise o código antes de escrever uma palavra

• Leia o código real. Rastreie chamadas até suas definições; não infira comportamento a partir de nomes. Para um código grande, distribua com um subagente somente leitura por área, se seu agente suportar subagentes, e mantenha apenas suas conclusões.
• Cada afirmação na narração deve mapear para um arquivo e linha que você leu. Mantenha um notes.md de afirmação → caminho:linha enquanto pesquisa; use-o ao corrigir problemas encontrados no passo 7.
• Observe o que um desenvolvedor tropeçaria: efeitos colaterais ocultos, suposições de ordenação, caminhos de erro, configurações que alteram comportamento, nomes que enganam.

3. Planeje os beats de acordo com o orçamento de tempo

Um beat é um visual mais 1-3 frases de narração. A narração roda a cerca de 150 palavras por minuto (2,5 palavras/s); cada beat recebe uma pausa de cauda de 0,6 s.

Orçamento	Beats	Palavras
30 s	3-4	~70
1-2 min	6-12	150-280
5 min	20-30	~700
15-30 min	capítulos de 3-5 min, veja references/long-form.md

Regras de beat:

• Abra com a pergunta que está sendo respondida e feche com um resumo de uma linha. Sem enrolação introdutória, sem "neste vídeo".
• Arquitetura primeiro, depois aprofunde: diagrama, depois o código do ponto de entrada e, em seguida, a linha interessante.
• Explique o propósito, não as linhas. Cada beat de código diz para que serve o código e como ele se conecta ao beat anterior, depois aponta para a(s) linha(s) que importam. Nunca percorra um bloco linha por linha.
• Beats de código: no máximo 16 linhas (a parte inferior do quadro é reservada para legendas) e 80 caracteres por linha. Corte linhas irrelevantes e substitua-as por um comentário // .... Beats consecutivos que mostram o mesmo trecho com destaque diferente animam suavemente, então reutilize trechos e mova o destaque.
• Destaque o que a narração está falando com um comentário Code Hike diretamente acima dele: // !mark (próxima linha) ou // !mark(1:4) (próximas quatro linhas). Use a sintaxe de comentário da linguagem (# !mark em Python).
• Beats de diagrama: flowchart do Mermaid com no máximo 8 nós. Use TD para cadeias com mais de quatro nós. Mantenha nós idênticos em beats de diagrama consecutivos e mova apenas a linha class X hot, para que o layout não salte.
• A narração é escrita para ser ouvida: frases curtas, diga os identificadores como os desenvolvedores dizem ("a função handle-request"), não leia código símbolo por símbolo em voz alta, não fale números de linha.

4. Configuração do projeto (uma vez por vídeo)

Defina SKILL_DIR como o diretório da skill e, em seguida:

npx create-video@latest --yes --code-hike explainer && cd explainer
npx remotion add @remotion/media && npm rm twoslash-cdn && rm public/code*
rm src/calculate-metadata/process-snippet.ts src/annotations/Callout.tsx src/annotations/Error.tsx src/ProgressBar.tsx src/ReloadOnCodeChange.tsx
cp -R "$SKILL_DIR/template/." .
command -v mmdc || npm i -g @mermaid-js/mermaid-cli

Twoslash é removido propositalmente: ele sinaliza cada importação não resolvida em um trecho de código como um erro vermelho. Os arquivos copiados substituem a composição do template por uma orientada por beats/:

• scripts/build.mjs converte beats/ em public/beats/ (áudio, diagramas renderizados, manifest.json) e mede a duração do áudio de cada beat.
• src/Main.tsx reproduz os beats em sequência: título, código ou diagrama, áudio, legendas.
• src/annotations/Mark.tsx implementa o destaque !mark. src/Captions.tsx temporiza os trechos de legenda em cada áudio de beat.

5. Escreva os beats

Um par de arquivos por beat em beats/, numerados para ordenar (01, 02, … 10):

• NN.txt: primeira linha opcional # <título na tela> (use caminho/para/arquivo.ts:42-60 para beats de código, um cabeçalho curto para diagramas), depois a narração.
• Um visual: NN.<ext> com o trecho de código (a extensão define a linguagem de destaque: .ts, .py, .go, …) ou NN.mmd com um diagrama Mermaid. Destaque um nó do diagrama com classDef hot fill:#facc15,color:#000,stroke:#facc15 e class NodeId hot.

Exemplo de par:

beats/04.txt
# src/auth/session.ts:31-44
As sessões são renovadas preguiçosamente. A verificação de expiração só é executada quando uma requisição chega, então uma sessão ociosa nunca é limpa aqui.

beats/04.ts
export async function getSession(id: string) {
  const s = await store.get(id);
  // !mark(1:3)
  if (s && s.expiresAt < Date.now()) {
    return renew(s);
  }
  return s;
}

6. Passagem de rascunho (sem créditos)

1. Execute node scripts/build.mjs sem beats/*.mp3 e sem chave; ele escreve áudio placeholder silencioso na duração estimada e imprime o total. Se estiver mais de 15% acima ou abaixo do orçamento, corte ou adicione beats agora.
2. Renderize stills dos momentos com mais conteúdo na tela e do momento em que cada destaque aparece (cerca de 1,5 s após o início de um beat): npx remotion still Main out/check.png --frame=<n> --scale=0.5. Olhe para eles. Corrija linhas transbordando, diagramas ilegíveis e destaques na linha errada.

7. Verificação independente de fatos (antes de qualquer narração ser gerada)

O autor de um roteiro é a pior pessoa para verificá-lo. Tenha um revisor que não o escreveu verificar cada afirmação contra o código. Faça isso mesmo quando executar sem supervisão.

• Se seu agente suportar subagentes, inicie um novo. Dê a ele o caminho do repositório, todos os beats/NN.txt e seus visuais, e este briefing, mas não notes.md ou seu esboço, para que forme sua própria leitura do código:

  Verifique este roteiro explicativo contra o código. Liste cada afirmação factual na narração e nos títulos na tela. Para cada, encontre o código que a confirma ou contradiz, rastreando chamadas até suas definições. Retorne uma linha por afirmação: beat | afirmação | correto / errado / não verificável | caminho:linha | por quê. Também sinalize trechos de código que diferem da fonte (exceto cortes // ... e comentários !mark), títulos cujo intervalo path:linha está errado, qualquer coisa importante sobre este código que o roteiro afirma de forma enganosa, e beats de código cuja narração percorre as linhas sem dizer para que serve o código.

• Caso contrário, faça uma segunda passagem você mesmo: para cada afirmação, reabra o código citado e verifique-o lá, não contra notes.md.

Corrija toda afirmação errada, corte ou suavize toda não verificável e reescreva beats linha por linha sinalizados em torno de seu propósito. Reexecute a compilação do rascunho e envie apenas os beats alterados para uma segunda verificação.

8. Voz e renderização

1. Leia references/voice.md e gere um arquivo de narração por beat com a primeira opção disponível: o conector ElevenLabs, uma chave de API ElevenLabs, outro provedor de texto para fala, ou nenhum (vídeo silencioso com legendas). Use uma voz para todo o vídeo.
2. Execute node scripts/build.mjs novamente. Ele usa beats/NN.mp3 quando presente, então alterar um beat significa apenas substituir esse arquivo.
3. Renderize uma vez: npx remotion render Main out/explainer.mp4. Verifique se as durações do vídeo e do áudio correspondem (ffprobe -v error -show_entries stream=codec_type,duration -of csv=p=0 out/explainer.mp4) e, a menos que o vídeo seja destinado a ser silencioso, que o áudio não esteja (ffmpeg -i out/explainer.mp4 -af volumedetect -vn -f null - 2>&1 | grep mean_volume; o áudio placeholder lê cerca de -91 dB).

9. Antes de entregar

• Assista, ou pelo menos ouça, o primeiro e o último beats e um no meio. Se um identificador for pronunciado incorretamente, soletre-o foneticamente em NN.txt e grave apenas aquele beat novamente. As legendas mostram o texto da narração, então uma soletração fonética aparece lá também; mantenha as soletrações legíveis.
• Qualquer narração que mudou após o passo 7 passa novamente por ele.
• Entregue o mp4 com um resumo de uma linha da pergunta que ele responde. Nunca faça upload ou publique em nenhum lugar sem permissão explícita.