AI Motion Director é uma Skill de agente (Claude) que atua como diretor criativo e engenheiro de motion: parte do objetivo, da emoção e da narrativa, escolhe técnicas de motion graphics pela função que cumprem e produz o vídeo por código (Canvas/HTML renderizado frame a frame em MP4), conferindo o resultado.
- Problema que resolve: vídeos feitos por programação costumam virar vitrine de efeitos soltos, sem narrativa, sem som sincronizado e sem checagem. Aqui a técnica é consequência da intenção, e o que foi planejado, gerado, executado e validado é registrado separadamente.
- Diferenciais: Core pequeno + módulos independentes; catálogo de 72 técnicas pesquisável por intenção/emoção/viabilidade; contratos JSON validáveis entre módulos; render determinístico com som sincronizado (
window.__sfx); regra de evidência (executed/validatedexigem prova); honestidade sobre o que está disponível × testado. - Público e casos de uso: criadores, designers de motion, devs e agentes que precisam de vinhetas, logos animados, shorts/reels verticais, tipografia cinética, visualização de dados animada, roteiros com storyboard, revisão de roteiros/vídeos existentes.
Implementado e verificado (testes em tests/, ver §8): validação de contratos; registro/arquitetura (registry.py check); catálogo de técnicas e busca; seleção de motores com sonda de disponibilidade; montagem de prompts de geração; síntese de SFX determinística e mapa de áudio; pipeline init/check/render/inspect/bundle/status; render Canvas → MP4 (Playwright + Chromium + FFmpeg) com relatório; inspeção técnica de vídeo.
Implementado, não testado: motores svg-gsap, threejs, remotion, manim (receitas e manifestos; sem render de teste), creative-intelligence (conhecimento sem teste automatizável do conteúdo).
Planejado / apenas plano: After Effects/Blender/Cinema 4D, geradores de IA externos (o projeto só gera prompts e plano; não chama essas ferramentas).
O Core (ai-motion-director/SKILL.md, ≤150 linhas, verificado) decide a abordagem, coordena o ciclo, escolhe técnica e motor pela viabilidade real, resolve conflitos, checa coerência e avalia. Ele não carrega catálogo, regras de storytelling, prompts por ferramenta nem implementação de motores: conhece apenas os contratos e quando chamar cada módulo.
| Módulo | Papel | Contrato (consome → produz) |
|---|---|---|
creative-intelligence |
briefing, estratégia, diferencial | → creative-brief |
narrative-intelligence |
narrativa, emoção, roteiro, storyboard | creative-brief → script |
motion-graphics-intelligence |
catálogo de técnicas por função | brief+script → technique-recommendation |
prompt-engineering |
prompts para IA generativa | shot-spec → prompt |
production-engines |
motores, disponibilidade, seleção | script+profile → production-plan |
audio-rhythm |
som e ritmo com dados reais | script → script (cues) |
quality-assurance |
avaliação técnica × criativa | execution-report → qa-report |
production-automation |
preparar, renderizar, inspecionar, reunir | production-plan → execution-report |
Fluxo de decisão: INTENT → PROFILE → MODULES → STYLE ALIAS → ENGINE → SHOT PARAMETERS → FINAL PROMPT/RENDER.
.
├── LICENSE # MIT
├── README.md CHANGELOG.md requirements.txt
├── ai-motion-director.skill # pacote instalável da Skill
├── .github/workflows/ci.yml # CI (não verificado no GitHub)
├── docs/ # CONTRACTS.md, DEVELOPMENT.md
├── tests/ # 83 testes (unittest, stdlib)
└── ai-motion-director/ # a Skill
├── SKILL.md # Core
├── core/core.json
├── modules/<id>/module.json # 8 módulos
├── contracts/*.schema.json # 15 contratos
├── catalog/techniques/*.json# 72 técnicas, 12 arquivos
├── engines/<id>/engine.json # 8 motores
├── profiles/ styles/ prompt-profiles/
├── references/ # documentação por módulo
├── scripts/ # contracts, registry, catalog, engines, prompt_build,
│ # pipeline, render, inspect_video, audio_map, synth_sfx
├── assets/template/ # index.html + motion-kit.js
└── examples/
Evolução independente: nova técnica = soltar um .json em catalog/techniques/; novo motor = pasta em engines/; novo módulo = pasta em modules/ + citar o id no Core; nova ferramenta de prompt = prompt-profiles/*.json. Os testes provam que nada disso exige alterar o Core (exceto citar o id de um módulo novo) nem reescrever o roteiro.
Outras Skills: não se presume chamada nativa entre Skills. A colaboração usa o envelope handoff (tarefa, entradas, contrato esperado, fallback, status) descrito em ai-motion-director/references/interop.md. Integração indisponível nunca bloqueia o fluxo básico (testado com o contrato; nenhuma Skill de terceiros foi integrada de fato).
Entender → Conceber → Comparar → Estruturar → Planejar → Produzir → Avaliar → Aprimorar
- Entender: objetivo, público, emoção, "a única coisa a lembrar", formato (
creative-brief). - Conceber/Comparar: ideia central com metáfora visual; até 3 caminhos com trade-offs.
- Estruturar: arquitetura emocional, roteiro com timecodes e som (
script, validado: cenas contíguas, soma = duração). - Planejar: técnicas pela função (
catalog.py search), motor pela viabilidade (engines.py select). - Produzir:
pipeline.py init→ código (animação = função pura det) →render→render-report.json. - Avaliar:
inspect(técnico) + olharout/folha.png(criativo, registrado à parte). - Aprimorar: correção localizada, novo render e nova checagem.
- Python ≥ 3.9 (testado em 3.13). Arquitetura/contratos/catálogo/motores/prompts: só biblioteca padrão.
- Para renderizar e inspecionar:
pip install -r requirements.txt(numpy, pillow, playwright),python -m playwright install chromium(ouCHROMIUM_PATH), effmpeg/ffprobeno PATH. - Como Skill: instale
ai-motion-director.skillno seu cliente Claude (ou copie a pastaai-motion-director/).
Verificar a instalação:
SK=ai-motion-director
python $SK/scripts/registry.py check # arquitetura inteira
python $SK/scripts/engines.py detect # o que existe de fato neste ambiente
python -m unittest discover -s tests # testes (os de render pulam sem a pilha)Pedidos ao agente:
- "Crie uma animação de logotipo de 5 s para a marca Lumen" — exemplo:
examples/logo-lumen/,examples/logo-briefing-incompleto.md. - "Faça um short vertical de 15 s sobre um dado que surpreende" —
examples/short-vertical-dado.mde.../short-vertical-dado/*.json. - "Desenvolva um roteiro com storyboard para…" — modelos em
references/script-storyboard.md. - "Que técnicas de motion usar para um hook de impacto?" —
catalog.py search. - "Revise esse vídeo/roteiro" — modo Creative Audit.
Comandos:
SK=ai-motion-director
python $SK/scripts/catalog.py search --intent impact --context short-social --feasible A
python $SK/scripts/engines.py select --project-type vertical-short
python $SK/scripts/contracts.py validate script $SK/examples/short-vertical-dado/script.json
python $SK/scripts/pipeline.py init meu-video --profile vertical-short --style tech-premium-dark
python $SK/scripts/pipeline.py render meu-video --still 3 # um frame, rápido
python $SK/scripts/pipeline.py render meu-video # vídeo completo (≈0,5 s/frame em 1080p)
python $SK/scripts/pipeline.py inspect meu-video # medidas + out/folha.png
python $SK/scripts/pipeline.py bundle meu-video # deliver/ + MANIFEST.json
python $SK/scripts/prompt_build.py --listGuia completo: docs/DEVELOPMENT.md; contratos: docs/CONTRACTS.md.
- Técnica: adicione um objeto ao array de um
.jsonemcatalog/techniques/; rodecatalog.py check. - Motor:
engines/<id>/engine.jsoncom requisitos, limites, validação everificationhonesto. - Módulo:
modules/<id>/module.json(+ docs/dados/scripts declarados), cite`id`no Core. - Convenções: não registre
executed/validatedsemevidence; não marqueverifiedsem teste emevidence; o Core fica ≤150 linhas; não crie dependência circular entre módulos; mudar um contrato do Core = subircontract_versione documentar no CHANGELOG. - Testes:
python -m unittest discover -s tests.
| Categoria | Itens |
|---|---|
| Implementado e verificado (83 testes executados localmente) | contratos, registro/arquitetura, catálogo, engines (detecção/seleção), prompt_build, áudio (síntese e mapa), pipeline, render Canvas ponta a ponta, inspeção |
| Implementado, não testado | svg-gsap, threejs, remotion, manim; conteúdo de creative-intelligence |
| Integrações opcionais | motores externos, Skills de terceiros via handoff, geradores de IA, After Effects/Blender (todos só plano) |
| Planejadas | testes reais dos motores acima; perfis de prompt verificados por ferramenta; execução do CI no GitHub |
| Limitações conhecidas | prompt-profiles genéricos e não verificados; render lento (≈0,4–0,7 s/frame em 1080p); bpm_estimate é heurística; avaliação criativa depende de alguém olhar a folha; o CI (.github/workflows/ci.yml) nunca rodou no GitHub; nenhuma promessa de viralização ou conversão |
Licença: MIT (arquivo LICENSE).
Desenvolvimento / Development: Daniel Rodrigues
AI Motion Director is an agent Skill (Claude) that works as a creative director and motion engineer: it starts from goal, emotion and narrative, picks motion-graphics techniques by the function they serve, and produces the video in code (Canvas/HTML rendered frame by frame to MP4), checking the result.
- Problem it solves: programmatic videos tend to become a showcase of unrelated effects, with no narrative, no synced sound and no review. Here technique follows intent, and what was planned, generated, executed and validated is recorded separately.
- Differentiators: small Core + independent modules; a 72-technique catalog searchable by intent/emotion/feasibility; validated JSON contracts between modules; deterministic rendering with synced sound (
window.__sfx); evidence rule (executed/validatedrequire proof); honesty about available × tested. - Audience and use cases: creators, motion designers, developers and agents needing idents, animated logos, vertical shorts/reels, kinetic typography, animated data viz, scripts with storyboards, review of existing scripts/videos.
Implemented and verified (tests in tests/, see §8): contract validation; registry/architecture (registry.py check); technique catalog and search; engine selection with availability probes; generation-prompt builder; deterministic SFX synthesis and audio map; init/check/render/inspect/bundle/status pipeline; Canvas → MP4 render (Playwright + Chromium + FFmpeg) with report; technical video inspection.
Implemented, untested: engines svg-gsap, threejs, remotion, manim (recipes and manifests, no test render); creative-intelligence (knowledge content with no automatable test).
Planned / plan-only: After Effects/Blender/Cinema 4D and external AI generators (the project produces prompts and plans only; it does not call those tools).
The Core (ai-motion-director/SKILL.md, ≤150 lines, enforced) decides the approach, coordinates the cycle, picks technique and engine by real feasibility, resolves conflicts, checks coherence and evaluates. It does not hold the catalog, storytelling rules, per-tool prompts or engine implementations: it only knows the contracts and when to call each module.
| Module | Role | Contract (consumes → produces) |
|---|---|---|
creative-intelligence |
briefing, strategy, differentiator | → creative-brief |
narrative-intelligence |
narrative, emotion, script, storyboard | creative-brief → script |
motion-graphics-intelligence |
technique catalog by function | brief+script → technique-recommendation |
prompt-engineering |
prompts for generative AI | shot-spec → prompt |
production-engines |
engines, availability, selection | script+profile → production-plan |
audio-rhythm |
sound and rhythm from real data | script → script (cues) |
quality-assurance |
technical × creative review | execution-report → qa-report |
production-automation |
prepare, render, inspect, bundle | production-plan → execution-report |
Decision flow: INTENT → PROFILE → MODULES → STYLE ALIAS → ENGINE → SHOT PARAMETERS → FINAL PROMPT/RENDER.
The directory tree is shown in the Portuguese section above (identical; paths are not translated).
Independent evolution: new technique = drop a .json in catalog/techniques/; new engine = a folder in engines/; new module = a folder in modules/ + cite its id in the Core; new prompt tool = prompt-profiles/*.json. Tests demonstrate none of this requires changing the Core (other than citing a new module's id) nor rewriting the script.
Other Skills: native cross-Skill calls are not assumed. Collaboration uses the handoff envelope (task, inputs, expected contract, fallback, status) described in ai-motion-director/references/interop.md. An unavailable integration never blocks the basic flow (tested at the contract level; no third-party Skill is actually integrated).
Understand → Conceive → Compare → Structure → Plan → Produce → Evaluate → Improve (code names: Entender → Conceber → Comparar → Estruturar → Planejar → Produzir → Avaliar → Aprimorar)
- Understand: goal, audience, emotion, "the one thing to remember", format (
creative-brief). - Conceive/Compare: central idea with a visual metaphor; up to 3 paths with trade-offs.
- Structure: emotional architecture, timecoded script and sound (
script, validated: contiguous scenes, sum = duration). - Plan: techniques by function (
catalog.py search), engine by feasibility (engines.py select). - Produce:
pipeline.py init→ code (animation = pure function oft) →render→render-report.json. - Evaluate:
inspect(technical) + look atout/folha.png(creative, recorded separately). - Improve: localized fix, re-render, re-check.
- Python ≥ 3.9 (tested on 3.13). Architecture/contracts/catalog/engines/prompts: standard library only.
- To render and inspect:
pip install -r requirements.txt(numpy, pillow, playwright),python -m playwright install chromium(orCHROMIUM_PATH), andffmpeg/ffprobeon PATH. - As a Skill: install
ai-motion-director.skillin your Claude client (or copy theai-motion-director/folder).
Verify the installation:
SK=ai-motion-director
python $SK/scripts/registry.py check # whole architecture
python $SK/scripts/engines.py detect # what actually exists in this environment
python -m unittest discover -s tests # tests (render tests skip without the stack)Requests to the agent:
- "Create a 5 s logo animation for the brand Lumen" — see
examples/logo-lumen/,examples/logo-briefing-incompleto.md. - "Make a 15 s vertical short about a surprising number" —
examples/short-vertical-dado.mdand.../short-vertical-dado/*.json. - "Write a script with storyboard for…" — templates in
references/script-storyboard.md. - "Which motion techniques for an impact hook?" —
catalog.py search. - "Review this video/script" — Creative Audit mode.
Commands:
SK=ai-motion-director
python $SK/scripts/catalog.py search --intent impact --context short-social --feasible A
python $SK/scripts/engines.py select --project-type vertical-short
python $SK/scripts/contracts.py validate script $SK/examples/short-vertical-dado/script.json
python $SK/scripts/pipeline.py init my-video --profile vertical-short --style tech-premium-dark
python $SK/scripts/pipeline.py render my-video --still 3 # one frame, fast
python $SK/scripts/pipeline.py render my-video # full video (~0.5 s/frame at 1080p)
python $SK/scripts/pipeline.py inspect my-video # measurements + out/folha.png
python $SK/scripts/pipeline.py bundle my-video # deliver/ + MANIFEST.json
python $SK/scripts/prompt_build.py --listFull guide: docs/DEVELOPMENT.md; contracts: docs/CONTRACTS.md.
- Technique: add an object to the array of a
.jsonincatalog/techniques/; runcatalog.py check. - Engine:
engines/<id>/engine.jsonwith requirements, limits, validation and an honestverification. - Module:
modules/<id>/module.json(+ declared docs/data/scripts), cite`id`in the Core. - Conventions: never record
executed/validatedwithoutevidence; never markverifiedwithout a test inevidence; Core stays ≤150 lines; no circular module dependencies; changing a Core contract = bumpcontract_versionand note it in the CHANGELOG. - Tests:
python -m unittest discover -s tests.
| Category | Items |
|---|---|
| Implemented and verified (83 tests run locally) | contracts, registry/architecture, catalog, engines (detection/selection), prompt_build, audio (synthesis and map), pipeline, end-to-end Canvas render, inspection |
| Implemented, untested | svg-gsap, threejs, remotion, manim; creative-intelligence content |
| Optional integrations | external engines, third-party Skills via handoff, AI generators, After Effects/Blender (all plan-only) |
| Planned | real tests for the engines above; tool-verified prompt profiles; running CI on GitHub |
| Known limitations | generic, unverified prompt-profiles; slow render (~0.4–0.7 s/frame at 1080p); bpm_estimate is a heuristic; creative review needs someone to look at the contact sheet; CI (.github/workflows/ci.yml) has never run on GitHub; no promise of virality or conversion |
License: MIT (LICENSE file).
Desenvolvimento / Development: Daniel Rodrigues