akdavid4real/effectcraft-motion

Kit de motion graphics EffectCraft

Um fluxo de trabalho testado para criar motion graphics corporativos de 60 segundos no EffectCraft que tenham aparência profissional, estejam sincronizados e livres dos bugs clássicos: quadros vazios entre cenas, sobreposição de falas, texto coberto por decorações, números que desaparecem e efeitos sonoros fora do ritmo.

O design vem da aparência e dos layouts, não do zero. Escolha um dos cinco looks testados, escreva cada cena como uma chamada scene() com seu conteúdo e temporização de palavras, e o layout lida com tamanho, grade, cor e movimento. Agentes que inventam um estilo acabam com degradês escuros, texturas brilhantes e texto centralizado pequeno; essa é a maior razão pela qual um promo gerado parece amador.

Qualquer agente pode usar isso. Tudo executa a partir do shell (effectcraft-cli através de scripts/ec.py). MCP é opcional. Localização do kit: a pasta que contém este arquivo (chame-a de $KIT).

Não é este kit: vídeos de história com figuras esquemáticas / personagens (tela dividida "jeito errado vs jeito certo") usam o skill stick-figure-story.

Regras de ouro (as razões estão em references/)

1. Os tempos vêm dos dados, não de palpites. O plano de cenas está em timeline.json. Scripts de cena usam SC("s3") e W("s3", "palavra") (o tempo absoluto em que uma palavra é falada). Nunca digite um tempo como 23.6.
2. Olhe para cada cena que você construir. Renderize frames de pré-visualização (ec.py frames) e abra os PNGs. Código que roda sem erros ainda pode renderizar errado.
3. "Pronto" significa que os gates passaram. timeline.py check tem 0 FAIL, ec.py qa tem 0 FAIL, ec.py qa-video tem 0 FAIL, e você olhou para a folha de contato. Relate os resultados honestamente, incluindo avisos.
4. Use um look e os layouts (references/looks.md). Compare dois looks antes de escolher. Pelo menos um terço das cenas deve ser visual (telefone / ícones / fluxo / barras, ou uma cena personalizada com um objeto). Código de cena personalizado é para o que nenhum layout cobre (um mapa, um mock-up de produto), e ainda usa a paleta do look P(S.bg) e os tamanhos de tipo LOOK.type.
5. Leia references/pitfalls.md antes de escrever qualquer script EffectCraft. Leia references/motion-design.md, references/looks.md e references/techniques.md (grade de batidas, SFX alinhados ao pico, morphs contínuos, lista de proibições) antes de projetar cenas.
6. A marca não é sua para editar (references/brand.md). Mostre o arquivo de logotipo real, nunca o nome digitado como marca nominativa. Escreva o slogan caractere por caractere. Não invente nomes de produtos, rótulos de botões ou estatísticas. Preencha o bloco "brand" em timeline.json para que ec.py qa verifique isso.
7. Passar no QA não é o mesmo que ter um bom design. Planeje o script de cores, os visuais e o momento marcante antes de escrever as cenas, e avalie o filme em uma revisão de diretor de criação antes de renderizar (references/design-review.md, comparado com references/benchmark_sheet.png). 7b. UI de produto real (SaaS, filmes de aplicativo): siga references/ui-footage.md: capture apenas dados de amostra, corte para um painel, mostre-o legível (55%+ de largura) ou reconstrua-o como UI animada, uma tela por tomada, sem paredes coloridas de miniaturas, sem números inventados, e construa aqui para que os gates de QA rodem.
8. Anúncios de alta energia / hipercinéticos (estilo TikTok, um impacto em cada palavra falada): siga references/high-energy.md e templates/hyper.jsx em vez dos layouts calmos.
9. Relate o que a renderização mostra, não o que você planejou. Antes de escrever o relatório ou a entrega, extraia frames do MP4 final (não da pré-visualização) no meio e no último meio segundo de cada cena, e verifique cada afirmação: cada linha na tela é longa o suficiente para ler, cada etapa desenhada é realmente visível, a captura de tela é legível, a duração corresponde ao briefing e ao nome do arquivo? Leia cada transcrição de voz contra o script, e ouça o nome da marca. Em testes, a entrega de um agente descreveu quatro etapas de diagrama, três promessas e "BridgeAxis Technologies"; o filme mostrou a última etapa 0,3 s antes do corte, as promessas por meio segundo, capturas de tela ilegíveis, e uma voz dizendo "Bridge Access". timeline.py check e ec.py qa agora alertam sobre erros de voz ilegíveis e texto legível por menos de min_read segundos: corrija esses avisos, não os explique. Execute na configuração de raciocínio mais alta que seu agente tiver: a execução descuidada foi em uma "Baixa".

Estrutura do projeto

<projeto>/
  timeline.json        plano de cenas + cues de SFX + música (comece de $KIT/templates/timeline.example.json)
  audio_meta.json      arquivos de voz + timestamps de palavras (da etapa de áudio)
  soundtrack.wav       gerado por timeline.py mix
  assets/voice|sfx|bgm|icons|fonts
  scripts/lib.jsx      cópia de $KIT/templates/lib.jsx (defina COMP; o look fornece cores e fontes)
  scripts/look.jsx     escrito por `ec.py look NOME --accent HEX`
  scripts/timing.jsx   gerado (timeline.py emit) - nunca edite
  scripts/wipes.jsx    gerado (timeline.py emit) - execute POR ÚLTIMO
  scripts/reset.jsx, s1.jsx ... s8.jsx
  qa/                  pré-visualizações e folhas de contato

Execute todos os comandos a partir de <projeto>/. ec.py lê o caminho do projeto e o nome da composição de timeline.json.

Fluxo de trabalho A: novo vídeo

0. Briefing. Pergunte antes de construir: marca/site para combinar, humor (alto / calmo / técnico / luxuoso), duração e proporção de aspecto, voz (gênero/tom), e se música/SFX são desejados. Adivinhar a direção criativa é o motivo mais comum pelo qual um primeiro corte é rejeitado.

1. Configuração

mkdir -p <projeto>/{scripts,assets/{voice,sfx,bgm,icons},qa} && cd <projeto>
cp $KIT/templates/lib.jsx $KIT/templates/reset.jsx $KIT/templates/s1.jsx scripts/
cp $KIT/templates/timeline.example.json timeline.json   # edite nomes de projeto/composição/saída
python3 $KIT/scripts/ec.py fonts                         # instala as fontes dos looks (uma vez por máquina)

Defina COMP em scripts/lib.jsx para o nome da composição da linha do tempo. Anote a cor de destaque da marca (logotipo, CSS do site, produto). Se a marca tiver um site, leia seu CSS para o destaque e fontes. Coloque os arquivos de logotipo em assets/logo/ e preencha o bloco "brand" em timeline.json: nome, slogan exato, arquivos de logotipo, e quaisquer nomes de produtos ou URLs aprovados (references/brand.md).

2. Roteiro e voz. Escreva 8 linhas (gancho, problema, marca, 2–3 benefícios, prova, cartão final); 60 s contém cerca de 110–130 palavras faladas. Gere um arquivo de áudio por linha e obtenha timestamps de palavras em audio_meta.json neste formato:

{"voices": [{"id": "s1", "path": "assets/voice/s1.wav", "duration_s": 6.45,
             "words": [{"word": "Todo", "start": 0.30, "end": 0.59}, ...]}]}

Primeiro execute python3 $KIT/scripts/ec.py doctor. Ele lista o que esta máquina tem e como instalar qualquer coisa faltando. Quando disser ready, não pesquise ou instale alternativas (edge-tts, Whisper, piper, Playwright): as ferramentas abaixo são as testadas. Sem voz alguma, temporize as cenas com deslocamentos "in+0.5" em vez de palavras; $KIT/demo/ é um exemplo completo sem áudio (ec.py demo renderiza).

• Voz (padrão): Kokoro local, voz feminina af_heart. Grátis, sem conta. O modelo é armazenado em cache em ~/.cache/hyperframes/tts/ (baixado uma vez na primeira execução):

  export HYPERFRAMES_PYTHON=~/.venvs/kokoro/bin/python   # OBRIGATÓRIO: o venv com kokoro-onnx
  npx hyperframes tts "Texto da linha um." -v af_heart -o assets/voice/s1.wav   # um arquivo por linha
  

  Sem HYPERFRAMES_PYTHON ele falha com "O pacote kokoro-onnx não está instalado". Não faça pip-install de nada: defina a variável.
• Timestamps de palavras: npx hyperframes transcribe assets/voice/s1.wav --json. Ele usa o modelo Parakeet, armazenado em cache em ~/.cache/hyperframes/parakeet após a primeira execução (engine auto o escolhe). O Parakeet é adequado para vozes TTS limpas como Kokoro. Não passe -e whisper aqui: o engine Whisper do hyperframes (whisper.cpp) não está configurado. Para vozes gravadas reais com sotaques, o skill de edição de filmagem usa faster-whisper large-v3-turbo (~/.venvs/asr). Copie as palavras e seus tempos de início e fim em audio_meta.json.
• Música e SFX: o engine de áudio media-use (node <skills>/media-use/audio/scripts/audio.mjs --request audio_request.json --out audio_meta.json --only bgm,sfx). Ele recupera do catálogo do HeyGen por descrição, por exemplo "bgm": {"mode": "retrieve", "query": "piano calmo e quente"}. <skills> é ~/.claude/skills para Claude Code, ~/.agents/skills para Codex/OpenCode/DeepSeek.
• O text-to-speech do HeyGen (através do engine ou do CLI heygen) é a voz alternativa, mas a cota gratuita acaba. Quando isso acontecer, use Kokoro. A recuperação de música e SFX também precisa do CLI heygen logado (heygen auth login --oauth) a menos que HEYGEN_API_BASE esteja definido; sem isso, sfx ainda responde da biblioteca integrada do media-use, e o usuário pode fornecer seu próprio arquivo de música.

Anote qual provedor e voz você realmente usou.

3. Linha do tempo

python3 $KIT/scripts/timeline.py beats      # andamento da música, batidas, inícios de compasso, drop -> beats.json (precisa de "music")
python3 $KIT/scripts/timeline.py suggest    # propõe entrada/saída de cena + voice_at; com beats.json, as cenas terminam nas batidas
# cole em timeline.json, defina o "bg" de cada cena (light/dark/accent), adicione cues de SFX ancorados a palavras
python3 $KIT/scripts/timeline.py words      # cada palavra com seu tempo absoluto
python3 $KIT/scripts/timeline.py check      # DEVE ter 0 FAIL
python3 $KIT/scripts/timeline.py emit       # escreve scripts/timing.jsx + scripts/wipes.jsx
python3 $KIT/scripts/timeline.py mix        # escreve soundtrack.wav (-14 LUFS)

Corte na batida: timeline.py snap move cortes existentes para batidas onde a voz ainda cabe; nas cenas, BEAT(n), DOWNBEAT(n), nearBeat(t) e T.drop temporizam impactos e estalos na música (references/techniques.md). O SFX "at" pode ser um número, "beat:12", "downbeat:3", "drop", "s2:late" (a palavra "late" na voz de s2; "s2:the#2" = 2º "the"), "wipe:s3" (a transição para s3), "in:s3" ou "out:s3". Adicione "offset", "vol", "max" (comprimento de corte) e "align": "peak" (o momento mais alto do som atinge a âncora: use-o para impactos e estalos).

4. Planeje, depois escreva as cenas. Primeiro escreva o plano em qa/design_review.md (references/design-review.md, parte 1-6): o script de cores com uma linha por cena, o visual que mostra o que cada linha diz, o herói de cada cena, e o momento marcante.

Dê a cada cena um fundo em timeline.json ("bg": "light" | "dark" | "accent") e execute novamente timeline.py emit. Alterne-os para que cada corte leia como um novo capítulo. Use "accent" para os 1-2 momentos mais altos, geralmente o pico emocional. Coloque a revelação da marca e o cartão final no fundo onde o logotipo real lê melhor (geralmente light), não no accent. Depois escreva scripts/s1.jsx ... sN.jsx, cada um com uma chamada scene() com um layout (especificações: topo de templates/layouts.jsx; guia: references/looks.md):

// scripts/s2.jsx
scene("s2", "list", { label: "O problema",
  items: [["Chegadas atrasadas.", "atrasadas"], ["Surpresas na alfândega.", "alfândega"], ["Rastreamento que não diz *nada.*", "rastreamento", "nada"]],
  punch: ["Tarde demais.", "tarde"] });

*palavra* marca a parte de destaque de uma linha. Os tempos são palavras de timeline.py words ("palavra", "palavra#2", "palavra+0.3", "in+0.2"), escritas sem pontuação. Os layouts crescem ou encolhem o texto para preencher o quadro, então escreva o texto que você quer e deixe o layout dimensioná-lo. Mantenha as linhas na tela curtas: elas são manchetes, não a narração. Apenas para algo que nenhum layout cobre (um mapa, um mock-up de produto), copie $KIT/templates/scene_template.jsx.

Faça pelo menos um terço das cenas visuais. Um filme que são apenas palavras em fundos parece uma apresentação de slides, por mais boa que seja a tipografia. Layouts visuais colocam um objeto na tela sobre o qual a voz está falando: phone (o produto em uma tela de telefone: uma página de pagamento, um pedido, uma atualização de rastreamento), icons (2-4 pictogramas desenhados com rótulos), flow (paradas unidas por uma linha que preenche à medida que cada uma é falada: cliente → telefone → banco, armazém → porto → porta) e bars (2-4 barras que crescem: taxas, tempos de espera, antes/depois). Escolha as cenas onde a voz descreve uma coisa ou um processo, não uma afirmação.

scene("s4", "flow", { label: "Como funciona", title: ["Recebido no *mesmo dia.*", "dinheiro", "mesmo"],
  nodes: [{ icon: "shop", label: "Você vende", at: "vende" }, { icon: "phone", label: "Tapnest", at: "app" },
          { icon: "bank", label: "Sua conta", at: "conta", note: "Mesmo dia" }] });

Os ícones são desenhados pelo kit (sem arquivos): phone card bank cash clock check tick shop bolt chart truck box pin lock user people chat globe send star plane doc. Uma cena visual personalizada também conta quando suas camadas de imagem/objeto têm "VIS" em seus nomes (por exemplo, "s5 VIS mapa"); ec.py qa avisa quando menos de um terço das cenas são visuais. Não copie layouts.jsx para o projeto: ec.py o carrega do kit, e uma cópia congela a versão antiga.

5. Escolha o look (leia references/looks.md primeiro). Selecione dois looks que se encaixam na marca de maneiras diferentes, pegue o destaque da marca, e compare-os em SUAS cenas:

python3 $KIT/scripts/ec.py new
python3 $KIT/scripts/ec.py import soundtrack.wav assets/icons/*.png
python3 $KIT/scripts/ec.py compare editorial swiss --accent FF5B1F   # -> qa/look_compare.png: ABRA-O
python3 $KIT/scripts/ec.py look editorial --accent FF5B1F             # aplique o vencedor

6. Construa e pré-visualize

python3 $KIT/scripts/ec.py run s1 s2 s3 s4 s5 s6 s7 s8 wipes   # s1 cria a comp + soundtrack
python3 $KIT/scripts/ec.py frames 2 4 6.5                      # ABRA qa/frames.png e olhe

Pré-visualize dois ou três momentos de cada cena. Para corrigir uma cena, edite-a e execute ec.py rebuild sN (limpa apenas aquela cena, reconstrói, reexecuta os wipes). Para reconstruir tudo (por exemplo, após mudar o look): ec.py run reset s1 ... sN wipes. O look fornece a transição; para substituí-la, escreva seu próprio scripts/wipes.jsx sem a linha de cabeçalho "GENERATED" (emit então o deixa em

[truncado para tradução]