explainer-kit

Vídeo explicativo

Você cria vídeos explicativos que um espectador específico entende e que estão certos. Duas coisas decidem o resultado: as regras em references/STYLE.md (vindas de feedback real de revisores) e o hábito de calcular e verificar cada número que você mostra. A renderização é a parte fácil.

Mapa do repositório: biblioteca animkit/ (referência da API animkit/README.md), ferramentas tools/, exemplos examples/, dois episódios prontos episodes_example/ (copie os formatos de storyboard e cenas; o formato CLAIMS está em references/VERIFY.md), seu trabalho vai em episodes/<ID>_<topic>/.

0. Antes de tudo

1. Ambiente funciona? python -I -B -X utf8 tools/selftest.py deve imprimir all OK. Se config/animkit.json estiver faltando, execute python -X utf8 tools/setup_config.py (a configuração é por checkout: um novo clone ou git worktree precisa dela novamente, ou defina ANIMKIT_CONFIG). Problemas: SETUP.md.
2. Pergunte ao usuário apenas o que você não pode definir por padrão (uma mensagem, curta):
   • tópico e o material de origem (notas de aula, um artigo, uma página); você precisa de uma fonte para cada afirmação;
   • público e o que eles já sabem (define a profundidade, references/STORYBOARD.md §Público);
   • duração; versão traduzida / narração / locução desejada?
   • você pode executar modelos reais (GPU, downloads)? Padrão: não, use uma cena sintética com ground truth conhecido.
   • Padrões se não respondidos: 1080×1440, 30 fps, apenas legendas, sem voz, uma rodada de revisão planejada.
3. Crie episodes/<ID>_<topic>/ com STATUS.md (estágio / próximo passo / aguardando / tempo desde date).

1. O pipeline (detalhes e comandos: references/PIPELINE.md)

Estágio	Você produz	Portão antes do próximo estágio
A. Estudo	resumo da fonte; análise opcional de vídeo de referência (references/REFERENCES.md)	você pode enunciar o mecanismo como entrada → fórmula → formas → pequeno exemplo numérico → porquê
B. Storyboard	storyboard.md, CLAIMS_to_verify.md, episode.json (+ elements_needed.md se faltar algo na biblioteca)	usuário OK no resumo para episódios longos; rodada de verificação independente 1 feita e correções aplicadas (references/VERIFY.md)
C. Cenas	shots/sNN_*.py, cada um com @shot.check	--check-only passa; folha de contato inspecionada; renderização completa; avisos de check.json corrigidos
D. Montagem	render/<ID>.mp4 (tools/concat.py), review/round1/review.html (tools/review_page.py)	você assistiu às folhas de cada cena; números na tela = CLAIMS
E. Rodadas de revisão	review/roundN/feedback.md (notas do usuário), review/roundN+1/changes.md, re-renderizações	cada item de feedback respondido; novas afirmações verificadas (máx. 2 rodadas por item)
F. Opcional	versão traduzida (references/I18N.md), narração (references/NARRATION.md), locução (references/TTS.md)	cada uma tem sua própria verificação

Escreva as cenas diretamente no idioma do vídeo (inglês nos exemplos): legendas, títulos e rótulos são strings simples no script. --lang é apenas para uma segunda versão traduzida.

Micro caminho (≤ 60 s, 1–3 cenas). Mesmos estágios, mais leves. Lista mínima de arquivos em episodes/<ID>_<topic>/:

1. storyboard.md: uma tabela, uma linha por legenda (intervalo de tempo, legenda, o que muda na tela, computado ou ilustrativo). Esqueleto: templates/storyboard_skeleton.md.
2. CLAIMS_to_verify.md: uma linha por número / fato na tela (afirmação, fonte, como verificar, medido / computado / inferido / artigo).
3. shots/s01_<name>.py a partir de templates/shot_template.py, com um @shot.check que afirma cada número computado como a string mostrada.
4. Verificação: um subagente novo com templates/verifier_prompt.md com escopo em todas as linhas de CLAIMS; aplique suas correções (redação antiga riscada).
5. Renderização: --check-only → --sheet-only (olhe sheet.jpg) → renderização completa.
6. episode.json + tools/concat.py apenas se houver 2+ cenas; tools/review_page.py <EP> --round 1 para a página de revisão (uma rodada). Não pule a tabela de afirmações, o @shot.check ou a inspeção da folha de contato.

2. Regras que nunca são opcionais

• Cada visual computável é computado (projeções, pesos de atenção, redimensionamentos, retroprojeções, retas ajustadas) e afirmado em @shot.check, incluindo a string exibida: ck.eq("profundidade na tela", f"{z:.3f}", "1.976"). Formate a partir da precisão total; nunca rearredonde um valor impresso. Visuais ilustrativos recebem shot.tag("Ilustração"); desenhos com redução de dimensão dizem isso.
• Cada número tem uma fonte (seção § / tabela / equação do artigo, arquivo de código oficial + linha, ou nosso próprio script) em CLAIMS_to_verify.md, rotulado medido / computado / inferido / artigo. Comparações indicam métrica, unidade e se menor ou maior é melhor; porcentagens indicam seu denominador.
• Cada símbolo é definido onde aparece, toda vez; termos que o espectador pode não conhecer recebem uma janela pop-up lateral (animkit.Popup) que os explica brevemente e fecha.
• Uma legenda = uma alteração visual, ≤ 12 palavras e não mais larga que o quadro (a renderização avisa; a 42 px isso é frequentemente ~8 palavras longas por linha, máx. 2 linhas), 2–3 s cada, nada estático.
• Imagem primeiro, depois a fórmula, iluminada termo a termo, cada termo colorido ou vinculado à sua parte na imagem.
• Nossos próprios testes são rotulados como nossos (não o experimento do artigo) na primeira vez e com a mesma tag depois.
• Verificação independente: quem escreveu uma afirmação não a verifica; uma correção é uma nova afirmação; no máximo duas rodadas, depois aplique como redigido e faça uma verificação pontual. A redação antiga é riscada (~~antigo~~ → novo), nunca excluída silenciosamente.
• Nenhum fato inventado na tradução ou narração: eles só podem dizer o que as legendas / CLAIMS verificados dizem.
• Lista de verificação completa: references/STYLE.md (§A conteúdo, §B ritmo, §C gramática visual, §D pré-entrega, §E feedback do revisor que se tornou regra). Leia antes de escrever o storyboard e novamente antes de cada rodada de revisão.

3. Estilo de trabalho

• Leia a seção da API que você precisa em animkit/README.md (é longa: use grep para o elemento, depois leia essa parte). Copie padrões da cena mais próxima em episodes_example/ em vez de inventar layouts. templates/shot_template.py é uma cena completa mínima.
• Itere em uma cena com --still t1 t2 (quadros PNG) e --sheet-only (folha de contato de 12 quadros); renderizações completas por último. Olhe a folha você mesmo cada vez (sobreposições, texto fora da tela, caixas = glifos faltando, legendas sobre a imagem). Stills não são atualizados por renderizações posteriores: execute --still novamente após cada edição.
• Cenas 3D: animkit/README.md §Cenas 3D (PinholeCam, OrbitCam convenção az / el: az=90, el=0 é uma vista lateral). Diagramas 2D como uma vista lateral de orifício: §Vista lateral 2D (Plot2D com escala igual).
• Execute Python como python -I -B -X utf8; nunca edite arquivos da biblioteca enquanto outra sessão renderiza (references/PITFALLS.md).
• Mantenha STATUS.md curto e atual; registre esforço em effort_log.csv (item,size,start,end,render_s,iterations,note).
• Episódios longos ou muitas cenas: divida o trabalho em várias sessões / subagentes como em references/DISPATCH.md (orçamento de contexto ≈ 300k por sessão principal, ≤ 150k por subagente único, arquivo de handoff antes de trocar).

4. Entrega

Diga ao usuário: o caminho do vídeo, o caminho da página de revisão (review/roundN/review.html, abra em um navegador; ela tem uma caixa de comentários por cena e um botão "copiar tudo"), o que é computado vs ilustrativo, o que foi verificado e por quem, perguntas em aberto. Quando as notas deles voltarem, salve-as literalmente como review/roundN/feedback.md (uma linha por id de cena, ex. E03-02: ...), responda a cada uma, e transforme qualquer preferência geral em uma nova linha nas suas regras locais do episódio (adicione a um STYLE_local.md em episodes/), para que o próximo episódio comece com ela.

Índice de referência

Arquivo	Leia quando
references/PIPELINE.md	começando; comandos de estágio, formatos de arquivo, portões
references/STYLE.md	escrevendo o storyboard; antes de cada rodada de revisão
references/STORYBOARD.md	estágio B: profundidade do público, formatos de storyboard + CLAIMS, padrões de história
references/REFERENCES.md	estudando vídeos de referência / artigos de origem
references/VERIFY.md + templates/verifier_prompt.md	após CLAIMS, após execuções de modelo, após narração / tradução
references/REVIEW.md	estágio D–E: página de revisão, arquivo de feedback, rodadas
references/I18N.md	uma versão traduzida de um episódio em inglês (--lang)
references/NARRATION.md	roteiro falado por segmento visual
references/TTS.md	locução TTS local, temporização, mixagem
references/DISPATCH.md	trabalho multi-sessão / subagente, custo, etiqueta de máquina compartilhada
references/PITFALLS.md	algo quebra; antes de alterar a biblioteca
templates/	prompts para sessões e subagentes, arquivos esqueleto, um modelo de cena