whiteboard-explainer

Vídeos explicativos em quadro branco

O núcleo do estilo: a voz e a imagem se movem juntas. Tudo é desenhado, escrito, sublinhado e circulado enquanto é dito, e cada slide é construído progressivamente. Leia references/style-guide.md antes de escrever o storyboard; ele contém as cores, as regras para palavras na tela, revelação progressiva, a tabela de sincronia e a estrutura geral do vídeo.

Comece cada vídeo a partir de template/ (copie, não comece do zero): copie o template/ desta skill para <project>/video/, depois execute source env.sh && cargo build --release. O binário é target/release/explainer (explainer.exe no Windows; R ... no env.sh o executa). O template é uma demo de ~95 s ("busca binária em cerca de um minuto") com quatro cenas para copiar; template/README.md tem todos os comandos. Execute os scripts Python a partir da pasta do projeto como python -I narration/<x>.py com numpy, soundfile, librosa, faster-whisper e pillow instalados. O que contém:

• src/kit.rs: o kit de desenho (traços feitos à mão, texto hand/note, underline, circle, arrow, stamp, counter, Card para figuras de papel com mark/ring/spot/zoom, camera, shrink_aside, ícones). Use-o por completo.
• src/lib.rs: despacho de cenas, chips de capítulo com o mergulho de 0,1 s, tabela de imagens, SceneCues (c.w(beat, "palavra") = quando uma palavra é falada). Cenas de demonstração: s_intro.rs (abertura fria, título, recapitulação final), s_idea.rs (um slide construído sobre palavras faladas), s_figure.rs (cartão de figura com ring/mark/note/spot e um zoom), s_quiz.rs (o quiz mcq com um carimbo de armadilha).
• src/objs.rs: objetos reutilizáveis (mcq, grid, token, vecbar, hbar, code_panel, chat_card, quote_card, axes/trace, vec_arrow, photo, ...) mais uma seção "este vídeo": coloque os objetos recorrentes de cada vídeo lá para que todas as cenas os desenhem de forma idêntica.
• src/duck.rs: o sprite do apresentador (posição dos pés, balanço de fala a partir do envelope de voz, pontos por cena: grande na abertura fria / quizzes / final, pequeno no canto inferior direito nos demais). Sem sprites → sem apresentador.
• src/t3d.rs (opcional): cubos em modo imediato e View3 para inserções 3D de tensores/arrays.
• narration/: script.py (cenas → beats, PAUSE para quizzes), tts.py (configurações de voz; encontra o say.py do local-tts), build_vo.py (voz + cache por linha + modelagem de pausas + tempo + alinhamento de palavras com faster-whisper → audio/narration.wav, src/cues.rs, src/envelope.rs), words.py (verifica todas as chaves c.w(...), braços de dispatch faltantes e placeholders restantes; escreve WORDS.md), est_cues.py (dicas provisórias e uma faixa silenciosa antes da voz existir), audit_vo.py / tts_try.py (auditoria de pronúncia), make_srt.py (legendas com mapa DISPLAY, OVERRIDE e --review), envelope.py, glitch.py (verificação do arquivo final).
• tools/: prep_figs.py (escreve src/figs.rs a partir de figs/*.png), get_pet.py (baixa um sprite de apresentador), font_metrics.py, make_demo_fig.py, lowprio.py (executa um trabalho com prioridade ociosa).
• media/: as fontes. Apenas arquivos de mídia podem ficar no nível superior (include_media_dir! entra em pânico com outros), então os textos de licença ficam em media/licenses/.
• HELPERS.md: as instruções para cada auxiliar de cena (regras, mapa de arquivos, ciclo de construção e verificação).
• STORYBOARD.md: o storyboard da demo, mostrando o nível de detalhe que os auxiliares precisam.
• THIRD_PARTY.md: licenças de fontes, sprites, fframes e FFmpeg.

Requisitos

• Rust (estável) e fframes 1.3.0 do crates.io (fixado em template/Cargo.toml; verifique seus termos de licença para seu uso).
• Bibliotecas compartilhadas do FFmpeg (build "shared" do FFmpeg 7+) e LLVM/libclang para o build do fframes. template/env.sh lê FFMPEG_DIR e LIBCLANG_PATH; no Windows, coloque também o bin do FFmpeg no PATH, tanto para cargo quanto para o binário compilado (sem as DLLs, ele sai com código 127 silenciosamente quando redirecionado).
• Python 3.10+ com faster-whisper (alinhamento de palavras, auditoria) e numpy.
• A skill local-tts (mesmo plugin) para a voz. Uma GPU ajuda muito; tudo também funciona em CPU.
• Um sprite de apresentador (opcional): um pet do Codex de github.com/gennadi-kuzmin/awesome-codex-pets (células de 192x208). python -I tools/get_pet.py --list, depois python -I tools/get_pet.py <pet-id> baixa e recorta um em sprites/. A licença MIT desse repositório cobre seu código; verifique os direitos artísticos de cada pet antes de publicar um vídeo. Escolha um brilhante (pets escuros desaparecem no quadro preto). Sem sprite, o vídeo renderiza sem apresentador.

Versão do fframes e a skill oficial

Novos vídeos usam fframes 1.3.0. A skill oficial do criador, fframes-video, cobre a API geral e muda a cada lançamento, então leia-a para qualquer coisa que esta skill não cubra: seu SKILL.md, depois references/api.md, audio.md, design.md e 3d.md. Instale-a com npx skills add https://fframes.studio -g -a claude-code -y (peça ao usuário para executá-la se suas permissões bloquearem instalações); os mesmos arquivos estão em github.com/dmtrKovalenko/fframes em skills/fframes-video/. Esta skill mantém apenas o que é específico deste estilo: a aparência, o pipeline e as lições abaixo. Quando as duas discordarem sobre renderização, as pegadinhas abaixo vencem.

Novidades na 1.3 que valem a pena usar:

• Cenas 3D (fframes::three_d): veja a próxima seção.
• Verificações mais nítidas: frame 3s --crop x,y,w,h (um recorte ampliado em pixels de vídeo, para traços delicados e rótulos pequenos), frame --ids (contornos e nomes de cada elemento com um id), strip 2s,5s,9s (tempos escolhidos lado a lado) e inspect --pops (encontra coisas que aparecem ou desaparecem em um quadro; agrupa as piscadas do apresentador). --pops verifica os quadros, não o mp4 codificado, então ainda execute glitch.py no arquivo final.
• Lottie: recurso lottie, frame.play_lottie(ctx, "x.json", LottieOptions { .. }) para um ícone animado pronto. Os traços do kit desenhado à mão continuam sendo o padrão; use Lottie apenas quando combinar com o visual de quadro branco.
• include_media_dir!(pub struct M, "media", stereo) mantém arquivos estéreo como estéreo.

Cenas 3D em um vídeo de quadro branco

Use 3D apenas quando profundidade ou uma câmera em movimento for a explicação: uma pilha de camadas da qual se levanta uma, formas de tensor, uma hierarquia de memória, um dispositivo físico, uma superfície de perda, um cartão de figura de artigo que inclina. Texto, rótulos, gráficos e setas permanecem em SVG desenhado à mão. Mantenha-se a um ou dois momentos 3D por capítulo: o vídeo ainda é um quadro branco. references/three_d_example.rs é um teste de 4 s (uma pilha de camadas girando com uma camada sendo levantada, um rótulo à mão preso a ela, um cartão de artigo desenhado em svgr em um plano 3D).

• fframes = { version = "=1.3.0", features = ["compile-time-svgtree", "cli", "3d", "wgpu"] }. O 3D funciona com o renderizador de quadros em CPU: com wgpu, o 3D renderiza na GPU e é lido de volta (120 quadros em 1080p: 1,4 s em uma RTX 4070 Laptop, 4,2 s com Renderer::cpu()). Quando a GPU estiver ocupada, mude os renderizadores para .cpu() (o exemplo lê FF_3D=cpu) e nada mais muda. Os tipos wgpu podem precisar de #![recursion_limit = "256"] no main.rs.
• Aparência do quadro: Background::Transparent sobre o retângulo BG do kit, piso Material::shadow_catcher, ToneMapping::Neutral para que a paleta do kit permaneça fiel, e Material::standard(c).roughness(0.45).clearcoat(0.4) para objetos encorpados que sejam legíveis no tamanho da strip.
• Rótulos à mão em objetos 3D: camera.project(scene.local_to_world(id, local), w, h) fornece o pixel dentro da inserção; adicione o x/y da inserção. Desenhe o rótulo com o kit, na palavra de gatilho.
• Figuras de artigos em 3D: ctx.render_svgr(svgr!(..), w, h) → Texture::from_image(&img) em um Geometry::plane com Material::unlit(0xffffff). O mesmo caminho coloca uma figura PNG em um cartão.
• Um objeto que se move deve permanecer dentro da caixa do seu renderizador de inserção, ou será cortado na borda.
• Construa a cena uma vez em new(), clone e poseie-a por quadro (veja o 3d.md oficial).
• Visualizações de tensor / array: o modo imediato funciona bem. A função da cena constrói um Vec<Cube> de t a cada quadro (as posições são aritmética simples, então blocos colapsam, dividem, desenrolam, preenchem fantasmas), renderiza uma inserção com uma geometria rounded_box compartilhada e projeta pontos para setas desenhadas à mão. Escreva números de cubo apenas na camada frontal e pule rótulos de cubos esmaecidos (alfa < 0,6) ou eles aparecerão por baixo. Uma inspeção completa com 3D é lenta (~10 min para 5.400 quadros): execute-a em segundo plano.
• Mantenha um rótulo fixo claro de cada objeto em todo o movimento da câmera (verifique um quadro estático no início e no fim da cena) e comece uma cena 3D depois que um shrink_aside tiver terminado, não durante.

Fluxo de trabalho

1. Pesquise a fonte em research/paper_notes.md: cada número com sua tabela/página, além de armadilhas de redação (percentual vs. pontos, etc.). Extraia as figuras do artigo como imagens (figs/, cartões brancos no vídeo). Mostre os diagramas e figuras originais do artigo na tela.
2. Roteiro (narration/script.py): ~150 ppm, 1 frase por batida, escrita para a voz ("Swee Bench", "T zero", números por extenso). Abertura fria com o número mais surpreendente → título + cartão do artigo → roteiro → capítulos → 3-4 quizzes (pergunta, opções A-D, PAUSE, resposta) → pôster de veredito reutilizando os mesmos objetos desenhados anteriormente → letras miúdas → final. Verifique o comprimento após a construção da voz; corte linhas ou aumente TEMPO (1,06 funciona) em vez de apressar.
   • Quizzes são múltipla escolha difíceis e precisas (guia de estilo seção 6): perguntas de raciocínio, quatro opções cujas respostas erradas são equívocos reais, exatamente uma resposta defensável. Escreva research/quiz_keys.md (cada opção justificada com referência de página/tabela, números derivados computados em Python) e verifique-o antes de construir a voz.
   • Ensine, não resuma. Construa cada ideia do zero com um exemplo trabalhado em números reais. Defina cada termo na linha que o introduz e reduza jargão a algo cotidiano ("um nó é apenas um trabalho"). Comece a maioria das batidas com uma palavra de conexão ("Então,", "Agora,", "Mas") para que as transições sejam audíveis. Mantenha-se perto de 150 ppm: o desenho precisa de tempo.
   • Introduza cada símbolo adequadamente antes de usá-lo; repita um breve lembrete na linha que o usa.
   • Faça soar como uma pessoa, não AI. Leia references/natural-narration.md antes de escrever, depois execute python -I scripts/aispeak_scan.py <project>/narration/script.py. Corrija preparações encenadas ("Aqui está o cerne"), reformulações não-X-mas-Y, fechamentos citáveis e perguntas auto-respondidas antes de construir a voz.
   • Evite linhas com fragmentos de dois pontos ("Primeiro: ...", "Três benchmarks."): a voz pausa ali e a próxima linha soa abrupta. A primeira palavra de uma cena sozinha ("Sonda.") pode ser engolida: escreva "A seguir, sonda.". Dê a "Obrigado por assistir!" sua própria batida.
3. Storyboard (STORYBOARD.md): por cena, qual elemento aparece em qual palavra de gatilho, sua posição aproximada (x, y), tamanho e cor, qual figura/recorte, e os objetos recorrentes + significados das cores. Concreto o suficiente para implementar, não para projetar. Reserve a área do chip (canto superior esquerdo) e a área do apresentador (canto inferior direito).
4. Voz: narration/build_vo.py vocaliza através do say.py da skill local-tts, encontrado via LOCAL_TTS_SAY, depois ~/.claude/skills/local-tts/, depois ~/.claude/plugins/**. GPU ocupada? GGML_BACKEND=CPU e WHISPER_DEVICE=cpu. Cache por linha; reformular uma linha força uma nova tomada. shape() limita cada silêncio dentro de um clipe pela pontuação antes dele (0,14 s nenhum, 0,24 ,, 0,3 :;, 0,42 .?!), com 0,5 s entre linhas (0,7 após uma pergunta). Audite a voz antes de desenhar as cenas: audit_vo.py transcreve cada clipe sem o script como prompt (o Whisper com prompt do build_vo esconde pronúncias erradas) e compara com o script. Ignore grafias americanas e homófonos; corrija leituras incorretas reais, testando correções com tts_try.py (dentro da frase inteira: um nome pode estar bom sozinho e distorcido no meio da linha). Leituras incorretas conhecidas estão nas pegadinhas da skill local-tts. Reexecute a auditoria após cada regravação (Qwen ocasionalmente duplica uma palavra, "the the"). Voz não está pronta ainda? est_cues.py escreve dicas provisórias e uma faixa silenciosa, e as cenas se reajustam quando build_vo.py sobrescreve ambos.
5. Kit + 1-2 cenas exemplares desenhadas por você e verificadas em tamanho real, para que os auxiliares tenham uma referência de qualidade.
6. Distribua grupos de cenas para subagentes paralelos (modelos pequenos e rápidos com alto esforço de raciocínio fazem isso bem quando as instruções são concisas; um modelo mais forte só é necessário para os exemplares). Coloque os objetos recorrentes em objs.rs e preencha HELPERS.md primeiro, com caminhos absolutos para research/. Copie o projeto para work/<group>/ por agente (pule renderizações e o cache de narração) com o diretório de destino vinculado por hard link (cp -al target work/g/target, ou um CARGO_TARGET_DIR por auxiliar; depois exclua os artefatos da crate explainer dessa cópia) para economizar disco e tempo de compilação. Cada auxiliar edita apenas seu src/s_<group>.rs, compila, executa words.py e inspect, verifica strips e quadros completos. Mescle copiando seus s_*.rs de volta; diferencie outros arquivos primeiro.
   • Mantenha os auxiliares rápidos. As compilações são o gargalo: mantenha [profile.release] incremental = true + codegen-units = 256 (recompilação de ~50 s → ~25 s) e execute no máximo ~4 auxiliares por vez; dê grupos posteriores a quem terminar primeiro. Um grupo = 2 cenas de peso semelhante; separe um quiz ou uma cena densa. Orçamento: no máximo 3 rodadas de compilação e verificação por cena, uma strip de 12 quadros mais @end, depois liste dúvidas restantes em vez de polir. Uma rodada de correção direcionada por auxiliar é barata.
   • Verifique os fatos deles: confira cada número na tela com paper_notes e compute cada exemplo trabalhado (auxiliares já inventaram números, transportes indo para o lado errado e uma demo que revelou a resposta de um quiz posterior). Verifique se as fotos correspondem à narração.
   • Revise as strips e quadros de cada auxiliar você mesmo (as imagens de verificação deles podem estar desatualizadas), depois envie correções concretas. A falha comum deles é agrupar cada fase na metade superior em tipo pequeno: dê intervalos y e px...