mathruffian-dot/soil-motion-deck

SOIL Apresentação com Animação Pedagógica: Uma Criação, Dois Produtos

Produto	Conteúdo	Para Quem
A Apresentação (.pptx)	Slides pedagógicos feitos com os seis motores SOIL. 2–4 páginas 🎬 com trechos de animação embutidos, sem áudio, sem legendas; o professor narra ao vivo	Projeção em aula
B Vídeo (MP4)	Vídeo explicativo completo do mesmo conteúdo: narração, legendas, esquema de três cores	Pré-aula, reposição, upload

Os dois produtos compartilham a mesma animação: primeiro faz-se B, depois recortam-se os trechos das páginas 🎬 da "versão gêmea silenciosa" de B e embutem-se em A. Assim a animação é feita apenas uma vez e a duração coincide exatamente.

Este skill apenas "conecta" os dois fluxos. A execução segue exatamente as instruções dos dois skills upstream:

• soil-teaching-deck (mathruffian-dot/soil-teaching-deck): seis motores, papéis de página, layout visual, estrutura sanduíche, instalação da fonte F-0.
• motion-explainer (mathruffian-dot/claude-motion-explainer), junto com os skills motion-design, review-loop e HyperFrames oficiais que ele traz: roteiro, narração, produção de quadros, legendas, esquema de três cores, revisão, exportação.

0. Ambiente e Caminhos

Este documento usa três códigos; antes de começar, encontre suas localizações reais:

Código	O que é	Localização comum
<smd>	Pasta deste skill	~/.claude/skills/soil-motion-deck (Claude Code), ~/.agents/skills/soil-motion-deck (Codex)
<me>	Pasta do skill motion-explainer	Mesma, pasta motion-explainer
<soil>	Pasta do skill SOIL	Mesma, pasta soil-teaching-deck

ls -d ~/.claude/skills/{soil-motion-deck,motion-explainer,soil-teaching-deck,review-loop} ~/.agents/skills/{soil-motion-deck,motion-explainer,soil-teaching-deck,review-loop} 2>/dev/null

PowerShell (quando não houver bash no Windows):

Get-ChildItem "$HOME\.claude\skills","$HOME\.agents\skills" -Directory -ErrorAction SilentlyContinue | Select-Object FullName

Outros agentes (ex.: Gemini CLI): procure pastas com o mesmo nome na pasta de skills do agente.

Se faltar algum, peça ao usuário que instale conforme o README do respectivo repositório (cada repositório consiste em copiar a pasta skills/ ou skill/ para a pasta de skills do agente). O install.py do SOIL só instala na primeira pasta que encontrar e aguarda o usuário pressionar Enter. Se o próprio agente for instalar, copie diretamente: cp -r soil-teaching-deck/skill <pasta_de_skills>/soil-teaching-deck.

Outros requisitos:

• Requisitos dos dois skills upstream: Node.js 22+, ffmpeg, Python 3, HyperFrames e um TTS: edge-tts (padrão), não requer GPU, a maioria das pessoas usa este; ou Breeze TTS 2 (avançado, requer GPU NVIDIA, apenas para pesquisa e uso não comercial, instale conforme motion-explainer/references/tts-setup.md somente se o usuário solicitar).
• Apresentação: PptxGenJS 3.12.0 (instale com o templates/package.json deste skill, veja §5), fontes GenSekiGothic2 H/B/M (instale conforme F-0 do SOIL).
• Miniaturas: Windows com PowerPoint é o ideal (thumbs.py usa o PowerPoint diretamente para exportar, as fontes e capas de vídeo ficam idênticas à aula). Sem isso, use LibreOffice + poppler, apenas para verificar o layout, as capas de vídeo podem não aparecer.
• Versões testadas: HyperFrames 0.8.168, PptxGenJS 3.12.0.

Agentes sem sub-agent (ex.: algumas configurações do Codex, Gemini): onde o motion-explainer diz "enviar cada quadro para um sub-agent em paralelo", faça você mesmo os quadros um por um em sequência; os arquivos lidos e a ordem são os mesmos.

1. Entrevista Inicial (perguntar tudo de uma vez)

1. Matéria, unidade, público-alvo, duração da aula (pergunta complementar do SOIL).
2. Quais produtos: A+B (padrão), apenas A, apenas B. Mesmo que queira apenas A, faça B primeiro: a narração define o ritmo de cada quadro, a animação fica natural. Apenas não entregue B; não é preciso deixar o usuário ouvir a narração.
3. Esquema de cores. O padrão é "três cores do vídeo + sanduíche SOIL":
   • O vídeo (e a janela de animação nos slides) usa o esquema de três cores do motion-explainer: fundo preto #121212, texto branco #F2F0EA, destaque laranja #FF7A1A.
   • Os slides (capa, página de ação, conclusão) são páginas escuras com as cores do vídeo; as páginas de conteúdo são claras, com a animação em uma "janela de reprodução" escura.
4. Voz da narração: conforme as regras do motion-explainer.

A entrevista inicial do motion-explainer (plataforma, duração, voz, três cores) já foi feita aqui, não pergunte novamente. A duração também não está limitada à sugestão "60–90 segundos" dele: a duração é igual ao comprimento da narração, normalmente 15–25 segundos por página 🎬, mais alguns quadros antes e depois.

2. Motores SOIL Um a Três, Marcar as Páginas 🎬 de Animação

Execute os motores um (posicionamento conceitual), dois (posicionamento contextual) e três (estrutura de páginas) conforme soil-teaching-deck. Após cada motor, peça confirmação ao usuário. Na tabela de papéis de página do motor três, adicione uma coluna animate para as páginas que receberão animação. Use o marcador 🎬, não ★ (o ★ do SOIL significa "página chave", que é diferente):

Página 6: Por que é sempre verdade? Quebra-cabeça de áreas 🎬
- Papel da página: página de processo
- Único ponto principal: O quadrado grande e os triângulos não mudaram, então a área vazia é igual
- animate: { frame: 04-proof, poster: last }

frame é o nome do arquivo (sem .html) daquele quadro no vídeo, que será fixado na escrita do storyboard na §3: o src daquele quadro em STORYBOARD.md é compositions/frames/04-proof.html, então escreva 04-proof. A duração de cada trecho é definida pela narração, não aqui.

Quais páginas valem a pena animar (2–4 páginas no total, cada trecho 15–25 segundos): páginas onde "mudança ao longo do tempo" é o próprio ponto central.

Adequado	Exemplo
Dedução, demonstração, processo	Quebra-cabeça de áreas, reação química, caminho da luz
Acúmulo ou comparação de quantidades	Contagem de quadrados 9 + 16 = 25, crescimento de barras
Inversão de mitos	Afirmação errada → X → virar para a afirmação correta
Relações espaciais	Rotação, translação, planificação, quadrado inclinado

Não adequado: definições, tabelas, exercícios, resumo; estas páginas usam apenas os layouts visuais do SOIL.

3. Escrever o Roteiro do Vídeo a partir do Fluxo dos Slides (Transição)

Os quadros do vídeo seguem o fluxo dos slides. Primeiro, escreva uma tabela de correspondência no BRIEF.md do projeto de vídeo. Os nomes de arquivo são decididos aqui:

Slide	Quadro (nome do arquivo)	O que a narração diz	Uso
2 Introdução do problema	01-ladder	Problema contextual do motor um	Apenas no vídeo
🎬 3	02-squares	O único ponto principal deste slide	Recortado como p03
4–5 Conceito	03-names	Conceito geral + nomes	Apenas no vídeo
🎬 6	04-proof	O único ponto principal deste slide	Recortado como p06
…	…	…	…
13 Resumo	07-takeaway	"Uma frase para levar" do motor um	Apenas no vídeo

Os nomes dos trechos recortados usam p + número de dois dígitos da página (p03, p06), coincidindo com o nome em video(s, "p06", …) no build_deck.js.

Em seguida, escreva SCRIPT.md (um ## Line N por quadro) e STORYBOARD.md (o src de cada quadro usa o nome da tabela acima) conforme o formato do motion-explainer. O material da narração vem diretamente dos motores SOIL:

• "Três equívocos comuns" do motor um → as três falas do quadro de inversão de mitos.
• "Uma frase para levar" do motor um → a fala do último quadro, sem alteração; o slide de resumo também usa a mesma frase.
• O "único ponto principal" de cada página 🎬 → a última frase da narração daquele quadro.
• Estime o comprimento com 4–4.5 caracteres chineses por segundo. A narração de um quadro 🎬 tem cerca de 70–100 caracteres (15–25 segundos).

Ao enviar o quadro 🎬 para o worker, o _dispatch_context.md deve incluir estas quatro instruções (elas serão usadas isoladamente, quando o trecho for reproduzido sem áudio e sem legendas):

1. Compreensível apenas pela imagem: números, rótulos e conclusões chave devem estar escritos na tela, não apenas ditos.
2. Comece do zero, termine na conclusão: o estado final deve estar completo e parado por pelo menos 1 segundo, pois servirá como capa no slide.
3. Conteúdo importante não deve ficar na área de legendas (y > 896 px): as legendas do vídeo o cobririam, e no slide, embora não haja legendas, o mesmo quadro deve funcionar nos dois contextos.
4. A transição entre quadros consecutivos (mesma escada, mesmo triângulo) é feita normalmente; a edição removerá automaticamente a sobreposição das transições.

A seguir, siga exatamente o fluxo do motion-explainer: narração → câmera → cada quadro (com sub-agent em paralelo, sem sub-agent em sequência) → montagem, legendas, cores → rascunho para revisão → exportação B.

4. Versão Gêmea Silenciosa → Recortar os Trechos 🎬

Use caminhos absolutos ou execute a partir da mesma pasta. Abaixo, $FILM representa o caminho completo do projeto de vídeo:

python <smd>/scripts/make_silent.py --project "$FILM"            # Cria $FILM-silent: remove todas as faixas de áudio e legendas
(cd "$FILM-silent" && npx hyperframes render --quality high --output renders/silent.mp4)
python <smd>/scripts/cut_clips.py --project "$FILM" --video "$FILM-silent/renders/silent.mp4" \
    --map p03=02-squares p06=04-proof p09=06-myths@first --out "$FILM/deck/media"

• cut_clips.py lê o início e a duração de cada quadro no index.html e recorta desde onde a sobreposição com o quadro anterior termina até onde a sobreposição com o próximo quadro começa. Independentemente de a transição ser crossfade, push-slide ou zoom-through, não mistura quadros adjacentes. Ele imprime a duração de cada trecho e a escreve nas notas do apresentador.
• A imagem de capa padrão é o último quadro (parado na conclusão). Para especificar por trecho, adicione @first ou @segundos após o mapeamento (ex.: p09=06-myths@first). Para uma página de mito em que não se quer revelar a resposta antes do tempo, use @first.
• Qualquer modificação no vídeo (qualquer quadro, cores, duração): reexecutar make_silent.py, exportar e cut_clips.py. A versão gêmea é uma captura instantânea; não acompanha automaticamente as alterações.

5. Fazer a Apresentação (Motores SOIL Quatro a Seis)

1. Execute o motor quatro (revisão cognitiva) e o motor cinco (estilo) conforme as regras do SOIL. O esquema de cores do motor cinco deve ser o escolhido no passo 1.
2. Crie a pasta da apresentação. Use obrigatoriamente o package.json deste skill: o package.json na raiz do projeto HyperFrames tem "type": "module"; sem o seu próprio package.json, o require falhará.

mkdir -p "$FILM/deck" && cp <smd>/templates/package.json <smd>/templates/deck_helpers.js "$FILM/deck/"
cp <smd>/templates/example_pythagoras.js "$FILM/deck/build_deck.js"     # Comece a partir do exemplo
(cd "$FILM/deck" && npm install)

3. Modifique build_deck.js. O início deve ser exatamente assim. Use sempre LAYOUT_WIDE (13,333 × 7,5 polegadas): a referência PptxGenJS do SOIL usa LAYOUT_16x9 (10 polegadas de largura) e a fonte Microsoft JhengHei; não copie isso aqui, as coordenadas em deck_helpers.js são projetadas para 13,333 polegadas de largura. As fontes seguem as regras do SOIL: título GenSekiGothic2 TW H, corpo GenSekiGothic2 TW M.

const path = require("path");
const pptxgen = require("pptxgenjs");
const { makeDeck } = require("./deck_helpers");
const pptx = new pptxgen();
pptx.layout = "LAYOUT_WIDE";
const D = makeDeck(pptx, { theme: { bg: "121212", fg: "F2F0EA", accent: "FF7A1A" }, mediaDir: path.join(__dirname, "media") });
const s = D.lightSlide("Processo・Animação");
D.title(s, "Por que é sempre verdade? Quebra-cabeça de áreas");
D.video(s, "p06", 0.6, 2.0, 8.0);   // Janela de reprodução de 8 polegadas de largura (16:9) à esquerda, com aviso "Clique para reproduzir" abaixo
// À direita x = 9.0, largura 3,9 polegadas: colocar um resumo dos passos ou pontos principais da animação, para que a página seja compreensível mesmo sem reprodução
pptx.writeFile({ fileName: path.join(__dirname, "Nome_da_Unidade.pptx") });

4. Layout da página 🎬: animação à esquerda (8,0 × 4,5 polegadas), 2–3 linhas de passos ou conclusão à direita. Nas notas do apresentador, escreva: duração do trecho, onde pausar para perguntar aos alunos, respostas esperadas.
5. As demais páginas seguem os papéis de página e layouts visuais do SOIL. As respostas dos exercícios vão nas notas do apresentador, não no slide.
6. node build_deck.js. Se os trechos ainda não estiverem recortados, video() colocará um placeholder; o layout pode ser ajustado antes.

Se o usuário já tem uma apresentação SOIL: PptxGenJS não pode modificar um .pptx existente. Siga o "modo de diagnóstico e modificação" do SOIL: leia o conteúdo de cada página (python -m markitdown <arquivo>.pptx; se não tiver markitdown, peça ao usuário para colar o texto), recrie as páginas a serem mantidas exatamente como estão no build_deck.js, converta as páginas selecionadas para o layout 🎬 e gere o arquivo inteiro novamente. Na entrega, explique que é um novo arquivo reconstruído; o arquivo original não foi alterado.

6. Revisão

python <smd>/scripts/thumbs.py "$FILM/deck/<apresentação>.pptx" --out "$FILM/deck/thumbs"   # Um PNG por página + visão geral deck-*.png

Não é necessário procurar o thumbnail.py mencionado na documentação do SOIL (skill pptx); use este thumbs.py. Examine a visão geral página por página, conferindo a lista abaixo:

• A capa da página 🎬 é a do quadro da animação, não um quadro preto ou texto placeholder
• A janela de animação não está coberta por outros textos ou gráficos; o aviso de reprodução abaixo está visível
• Cada página tem apenas um ponto principal; estrutura sanduíche (capa, ação e conclusão em fundo escuro; páginas de conteúdo em fundo claro)
• A cor de destaque da apresentação e do vídeo está na mesma faixa (nas páginas claras, pode-se usar um tom mais escuro da mesma cor, ex.: #E8601A com #FF7A1A do vídeo); números e termos são consistentes entre os dois
• As notas do apresentador têm duração, pontos de pausa para perguntas e respostas
• As respostas dos exercícios foram verificadas
• A revisão do vídeo B segue o review-loop (um quadro por cláusula, examinando um por um)

7. Entrega

Entregue os caminhos do .pptx e do MP4, e explique:

• Quais são as páginas 🎬, suas durações e qual quadro foi usado como capa.
• O computador que for reproduzir deve ter as fontes GenSekiGothic2 instaladas (o .pptx não incorpora fontes; sem elas, o sistema usará fontes alternativas).
• O vídeo já está embutido no .pptx; PowerPoint e Keynote podem reproduzi-lo diretamente. O Google Slides, ao importar, pode não preservar o vídeo embutido; para usar o Google Slides, faça upload dos media/*.mp4 para o Drive e insira os vídeos manualmente.
• Peça ao usuário para ouvir a narração com os próprios ouvidos (o ASR não percebe entonação). Para corrigir palavras pronunciadas incorretamente, use o fix_voice.py do motion-explainer; após a correção, é necessário recortar novamente os trechos e reconstruir a apresentação.

references/lessons.md contém os problemas encontrados na primeira implementação (Teorema de Pitágoras, 13 páginas, 3 animações, vídeo de 110 segundos).