Motion Forge: Guia Principal da Skill Industrial Code-to-Video (Code2Video)

Este projeto é uma Skill industrial Code-to-Video totalmente autossuficiente e distribuível. O sistema é baseado em um núcleo unificado de múltiplas tecnologias Remotion 4.x + React 19 + TypeScript + Three.js (@remotion/three) + Canvas 2D + SVG, com 265 cartões de efeitos atômicos e desacoplados (divididos em 9 grandes domínios profissionais), uma base visual subjacente (_shared/), uma bancada de trabalho de depuração local visual e rigorosos portões de qualidade G1/G2.

Sumário

Arquitetura Principal e Cinco Leis Técnicas Inegociáveis
Procedimento Operacional Padrão dos Dois Portões de Qualidade (SOP G1 e G2)
Sistema de Pipelines Independentes por Cenário (Scenario Pipelines)
Panorama de Ativos dos 265 Cartões de Efeitos e Filosofia de Decisão do Diretor (Creative & Open Motion Design)
Protocolo de Storyboard Film IR e Especificações de Renderização Multi-Tecnologia
Ciclo de Vida Completo da Ferramenta CLI e Interação com a Bancada Local
Lista de Verificação de Entrega Final e Solução de Problemas

1. Arquitetura Principal e Cinco Leis Técnicas Inegociáveis

Antes de escrever qualquer storyboard de vídeo ou código de renderização, o Agente deve aderir às seguintes cinco disciplinas de design inegociáveis:

Princípio de Desacoplamento Absoluto e Clock Local (Apenas Frame Local):
- Cada cena (scene) usa apenas números de frame locais (de frame 0 a durationInFrames). É estritamente proibido codificar carimbos de data/hora absolutos de todo o vídeo (absoluteFrame ou from) dentro de uma cena. O clock absoluto de todo o vídeo é compilado pela camada Core através da acumulação da linha do tempo;
- É estritamente proibido que as cenas importem componentes internos umas das outras. Todo o estado compartilhado entre cenas deve ser passado através das props do Film IR;
- Os cartões de efeitos (Cards) devem conter apenas lógica matemática de movimento e lógica visual. É estritamente proibido codificar textos específicos do projeto ou caminhos de imagens de negócios dentro dos cartões.
Determinismo de Clock de Frame como Função Pura (Frame-Deterministic Execution):
- Todas as deformações de animação, deslocamentos de objetos e transformações de transparência devem ser funções de cálculo matemático puro do frame local atual frame: $Valor = f(frame)$;
- É estritamente proibido usar requestAnimationFrame, setInterval, setTimeout do navegador ou linhas do tempo externas autoexecutáveis;
- É estritamente proibido usar Math.random() sem semente (é obrigatório usar random(seed) interno do Remotion com semente), garantindo que, independentemente de quando o frame seja buscado, os pixels da imagem sejam 100% idempotentes e consistentes.
Princípio de Loop Fechado com Ativos Reais Locais (Local Assets Only):
- O mecanismo de renderização é proibido de conectar-se diretamente a URLs externos não verificados durante a composição do vídeo (para evitar falta de rede, proteção contra hotlinking e latência de solicitação);
- Imagens externas, clipes de vídeo e trilhas sonoras de áudio devem ser baixados antecipadamente pelos Providers para o diretório local do projeto e registrados de forma unificada em assets.json. Ativos ausentes devem ser explicitamente marcados e relatados ao usuário. É estritamente proibido usar placeholders silenciosos ou dados falsos.
Filosofia de Renderização Unificada de Múltiplas Tecnologias (Multi-Tech Rendering):
- Layout e UI interativa usam HTML/CSS + animações elásticas (Spring);
- Contornos geométricos, linhas de conexão, gráficos e máscaras usam interpolação de caminhos SVG;
- Partículas, fluidos e dezenas de milhares de pontos de movimento de alta frequência usam Canvas 2D;
- Modelos 3D, iluminação espacial e movimentos de câmera 3D usam Three.js (@remotion/three);
- Todas as tecnologias obedecem uniformemente ao clock de sincronização de frames useCurrentFrame() do Remotion.
Princípio de Projeto de Engenharia Independente (Standalone Project):
- Este diretório da skill deve conter apenas padrões de processo, referências de cartões de efeitos, modelos de tempo de execução genéricos e o gerador de projetos forge create. Todo o conteúdo do projeto do usuário (core/, cards/, scenes/, ativos public/, film.json, package.json, bancada de trabalho e saídas de renderização) deve ser colocado no próprio diretório do projeto do usuário, com npm ci independente, verificação e renderização independentes, e deve ser capaz de ser executado independentemente do diretório da skill;
- É estritamente proibido escrever código/ativos específicos do projeto no diretório da skill, e também é estritamente proibido usar links simbólicos para montar o conteúdo do projeto de volta no diretório da skill. O forge create copia o tempo de execução, os cartões de efeitos e o Film padrão como arquivos reais para o projeto, e os componentes de cena específicos do projeto são escritos diretamente em scenes/ do projeto;
- O output/projects/ dentro do diretório da skill e o processo de portão se aplicam apenas aos exemplos fornecidos com a skill. Os registros de revisão G1/G2 para projetos reais são salvos no diretório do projeto.
Inicialização de Novo Projeto (Entrada: caminho absoluto do projeto e ativos de entrada; Saída: esqueleto do projeto que pode instalar dependências independentemente):
1. Execute npm run forge -- create --dir /absolute/project --input <input> [--audio-kind song|instrumental] [--name <id>] no diretório do modelo. O destino deve ser um diretório vazio fora do modelo. O comando gera uma cópia completa do tempo de execução, copia os ativos locais para public/assets/<id>/ e cria um rascunho do projeto;
2. Após a inicialização, entre em PROJECT_ROOT e execute npm ci, npm run validate -- --project <id>. O código, os ativos, o Film IR, o status de aprovação e a saída do projeto real são auto-contidos em PROJECT_ROOT/output/projects/<id>/ e PROJECT_ROOT/public/;
3. Use apenas caminhos relativos sob public/ para ativos locais; fontes remotas são registradas apenas como metadados de origem, sem entrar em referências de renderização. Se faltarem ativos, pare imediatamente. Não permita que o projeto use caminhos absolutos ou links simbólicos externos para se passar por um projeto independente;
4. Para todos os comandos subsequentes, primeiro execute cd <PROJECT_ROOT> e, em seguida, execute os scripts dentro do projeto. Produtos de renderização e registros de revisão não podem ser gravados de volta no diretório do modelo;
5. O diretório do modelo é usado apenas como fonte somente leitura durante create. Após a geração, os imports, dependências npm, scripts e referências de ativos no projeto não devem mais apontar para esse diretório.

Ramificações de Falha e Caminhos de Recuperação

Condição de Disparo	Tratamento de Primeira Linha	Em caso de falha persistente ou necessidade de alteração
O diretório raiz do projeto não está claro, ou está prestes a escrever no diretório da skill	Pare a gravação, confirme o caminho absoluto do projeto com o usuário; os comandos subsequentes usarão o diretório do projeto como diretório de trabalho	Sem um caminho claro, discuta apenas o plano, não crie arquivos
Ativos essenciais estão faltando, ilegíveis ou com direitos autorais incertos	Relate o caminho e o motivo específicos, pause as cenas afetadas; não use placeholders silenciosos ou invente ativos	O usuário fornece os ativos faltantes ou aprova explicitamente uma alternativa, e então o G1 é revisado de forma síncrona
G1 não confirmado ou solicitação de alteração	Permaneça na fase de design, revise `film.json` e `design-review.md`	Não crie cenas de amostra, não execute comandos de aprovação G1
A cena de amostra apresenta tela preta, dessincronização de áudio e vídeo, texto fora dos limites ou qualidade insatisfatória	Mantenha o bloqueio G2, localize a cena específica e corrija, renderize apenas a cena de amostra novamente	Envie para G2 novamente; não substitua a verificação da amostra pela renderização de todo o vídeo
A narrativa, o layout, a duração, os ativos ou o áudio já aprovados são alterados	Invalide as conclusões originais de G1/G2, volte ao G1 para reconfirmar o escopo afetado	Após a aprovação do novo G1, recrie e confirme a cena de amostra com áudio
Falha no comando de construção, validação ou renderização	Mantenha logs completos, corrija a causa raiz e execute o mesmo comando novamente; não comente erros ou pule validações	Se ainda falhar, pare a entrega, relate claramente os itens bloqueados e as verificações concluídas
A varredura de independência descobre caminhos absolutos externos, dependências `file:` ou links simbólicos apontando para o diretório da skill	Copie o código ou ativos necessários para o projeto, altere para referências internas do projeto	Reinstale e renderize em uma cópia isolada; não declare como independente até que passe

2. Procedimento Operacional Padrão dos Dois Portões de Qualidade (SOP G1 e G2)

Para evitar que o Agente "imagine do nada, empilhe código cegamente, cause grave desperdício computacional e desvio de expectativa", o sistema impõe dois portões de qualidade (Two-Gate Review). É estritamente proibido pular os portões e renderizar diretamente o vídeo completo!

[Entrada do Usuário]
   ↓
[Análise de Requisitos e Preparação de Ativos]
   ↓
[Esboço do Film IR]
   ↓
【🔴 CHECKPOINT G1: Confirmação do Storyboard e Design】 → Apresente ao usuário um roteiro e quadro visual bem formatados, PARE e aguarde aprovação
   ↓ (Após aprovação do usuário, execute npm run forge -- approve-design)
[Criação da Cena de Amostra com Áudio]
   ↓
【🔴 CHECKPOINT G2: Confirmação da Cena de Amostra com Áudio】 → Renderize o vídeo da cena representativa, o usuário revisa a qualidade visual e auditiva real e o alinhamento áudio-visual, PARE e aguarde aprovação
   ↓ (Após aprovação do usuário, execute npm run forge -- approve-sample)
[Montagem do Código Completo e Renderização em Lote]
   ↓
[Entrega Final (MP4 + Projeto Editável + Bancada)]

2.1 Portão G1: Confirmação do Storyboard e Design Visual (Design Review)

Antes de escrever qualquer código de renderização complexo, o Agente deve primeiro completar o "Plano de Design de Storyboard e Visual G1" e apresentar ao usuário um documento de revisão Markdown bem formatado, contendo pelo menos:

Atributos Básicos: Tipo de vídeo, público-alvo, proporção de tela (paisagem 16:9 / retrato 9:16), duração total alvo e taxa de quadros (ex: 30fps);
Tema Visual: Cor principal, cor de fundo, cor principal do texto, cor de destaque (Accent), família de fontes;
Seleção de Clock Principal: Alinhamento com narração / alinhamento com letras de música / grade de batidas musicais / duração de leitura de texto;
Tabela Detalhada do Roteiro do Storyboard (deve ser apresentada ao usuário estritamente no formato de tabela abaixo):

Nº da Cena	Nome da Cena	Propósito Narrativo e Semântica (Semantic)	Narração	Texto na Tela (On-Screen Text)	Descrição Visual	Cartão de Efeito Principal (Primary)	Cartão de Câmera (Camera)	Cartão de Transição (Transition)	Duração Local (Frames/Seg)
S01	Abertura Impactante	Gancho (Hook): Criar suspense	Por que 90% das transformações de IA nas empresas param na fase de demonstração?	"Por que 90% das transformações de IA nas empresas fracassam?"	Título de alto contraste enorme centralizado + placa de fundo vermelha de alerta brilhante	`typography/halation-bloom`	`camera/slow-push`	`transition/cube-rotate`	90f (3.0s)
S02	Exibição de Dados	Prova (Data): Mostrar estatísticas sombrias	Veja dois números: 78% param na fase de brinquedo, 12% geram retorno negativo.	"78% param na fase de brinquedo12% geram ROI negativo"	Painel de comparação de duas colunas esquerda-direita + gráfico de areia com números dinâmicos	`data/particle-sand-fill`	Nenhum	`transition/whip-pan`	150f (5.0s)

🔴 CHECKPOINT · PARE: Após apresentar ao usuário, a rodada deve ser encerrada e o usuário deve ser questionado se concorda com o planejamento do storyboard; não execute aprovação, criação de cena de amostra ou renderização de todo o vídeo na mesma rodada.
Sinal de Aprovação: Somente depois que o usuário confirmar explicitamente o G1 em uma resposta subsequente, o Agente deve executar em PROJECT_ROOT:
```
npm run forge -- approve-design --project <project-id>
```

2.2 Portão G2: Confirmação da Cena de Amostra com Áudio (Sample Review)

Após a confirmação do G1, não renderize imediatamente o vídeo completo. Deve-se selecionar a cena mais representativa, visualmente mais complexa e que contenha elementos reais de áudio e vídeo (geralmente a cena de Gancho ou a cena de clímax principal), criar e renderizar como um vídeo de cena de amostra:

Comando de Renderização:

npm run forge -- render --project <project-id> --scope sample

Pontos de Verificação de Qualidade:
- O áudio e o vídeo estão perfeitamente sincronizados? As legendas entram 1~2 quadros antes do início da fala?
- O texto na tela está obstruído, quebrado em linhas de forma inadequada ou fora da zona segura?
- A velocidade do efeito corresponde à emoção da música? Há sensação de respiração?
🔴 CHECKPOINT · PARE: Após fornecer o vídeo real da cena de amostra e os resultados da verificação de qualidade, a rodada deve ser encerrada e o usuário deve revisar; não aprove o G2 em nome do usuário.
Sinal de Aprovação: Somente depois que o usuário confirmar explicitamente a cena de amostra, execute em PROJECT_ROOT:
```
npm run forge -- approve-sample --project <project-id>
```
Somente após a conclusão da aprovação G2, a máquina de estados do projeto desbloqueia a permissão para a renderização final de todo o vídeo!

3. Sistema de Pipelines Independentes por Cenário (Scenario Pipelines)

A lógica de processamento ponta a ponta para diferentes tipos de entrada é dividida em arquivos de guia independentes, armazenados no diretório pipelines/. O Agente deve consultar o guia correspondente com base no tipo real de entrada do usuário:

Tipo de Cenário	Entrada e Tipo de Vídeo Aplicáveis	Arquivo de Guia de Pipeline Independente Correspondente
Cenário 1: URL para Vídeo	Blog, WeChat Official Account, SaaS Landing Page, Documentação Técnica, Comunicado de Imprensa	`pipelines/url-to-video.md`
Cenário 2: Áudio Musical Puro para Vídeo	Música instrumental, Música Eletrônica, Trilha Sonora Épica; Vídeo Filosófico, Beat Sync Flash, Ensaio de Humor	`pipelines/instrumental-to-video.md`
Cenário 3: Música com Vocais para Vídeo	Música Completa (vocais + acompanhamento); MV com Letras Dinâmicas, Curta-metragem de História Musical	`pipelines/song-to-video.md`
Cenário 4: Tema Puro com Planejamento Autônomo para Vídeo	Tema/Proposição em uma Frase; Ciência Aprofundada, Filosofia Humana, Insights de Negócios, Curta de Conhecimento Geral	`pipelines/theme-to-video.md`
Cenário 5: Mixagem de Ativos Multimídia do Usuário	Imagens próprias do usuário, capturas de tela, clipes de vídeo curtos, gravações de narração; Demonstração de Produto, Vlog	`pipelines/assets-to-video.md`
Especificação Geral de Planejamento de Conteúdo	Planejamento estruturado de tópico/URL, arco narrativo, rastreamento de fatos e conversão para Film IR	`pipelines/content-planning.md`
Guia de Extensão de Cenário	Como estender para novas entradas (ex: tabelas, apresentações de slides, podcast de duas pessoas, etc.)	`pipelines/extending-pipeline.md`

4. Panorama de Ativos dos 265 Cartões de Efeitos e Filosofia de Decisão do Diretor (Creative & Open Motion Design)

Os 265 cartões de efeitos atômicos integrados ao sistema são os pincéis visuais do Agente para criar vídeos.

4.1 Princípio de Seleção Aberta: Imaginação Artística Sem Limites

É estritamente proibido copiar mecanicamente e impor limitações dogmáticas: Este sistema nunca restringe que "certos tipos de vídeo devem usar certos cartões". Pelo contrário, incentivamos o Agente a combinar e inovar de forma autônoma com base na tensão emocional do texto, no suspense narrativo e nas batidas auditivas;
O Agente é o verdadeiro diretor visual: Os cartões de efeitos são um conjunto de blocos de construção modulares. Você pode usar o interaction/command-palette-summon, originalmente destinado a produtos de tecnologia, para expressar a "recuperação de conhecimento" de um pensador antigo; ou usar o flip card mecânico de aeroporto typography/split-flap-flip para mostrar viagem no tempo ou contagem regressiva da vida;
Ajuste Livre de Parâmetros Infinitos: Cada cartão expõe parâmetros ricos (como rigidez da mola, gravidade, raio de desfoque, número de partículas, etc.), e o Agente pode personalizar livremente a sensação de movimento individual em params dentro de film.json.

4.2 Panorama dos Ativos de Efeitos dos Nove Grandes Domínios (265 Cartões)

Todos os 265 cartões foram encapsulados de forma padronizada, suportam modo adaptativo duplo (paisagem/retrato) e são totalmente coesos e desacoplados por domínio:

Categoria (Kind)	Diretório e Total de Cartões	Função Visual Principal	Ativos de Cartões Representativos (Podem ser Referenciados Diretamente no Código)
`camera` (Movimento de Câmera)	`cards/camera/` (21 cartões)	Pan, tilt, dolly, zoom no espaço, distância focal da lente, distorção de perspectiva, criando profundidade espacial em uma imagem plana	`dolly-zoom` (Zoom de deslizamento Hitchcock), `slow-push` (Empurrão lento e profundo), `slow-pull` (Recuo gradual), `shot-crash-zoom-punch` (Zoom de impacto), `space-camera-moves` (Rolagem espacial 3D), `tension-camera-moves` (Tensão de inclinação do horizonte), `overhead-camera-moves` (Pan e tilt aéreos de grande amplitude), `whip-pan` (Pan rápido), `orbit-drift` (Deriva orbital)
`typography` (Tipografia)	`cards/typography/` (52 cartões)	Entrada de título, ritmo de legenda, reforço de citação, terminal de código, decodificação de caracteres	`split-flap-flip` (Flip card mecânico retrô de aeroporto), `scramble-decode` (Decodificação de matriz de caracteres embaralhados), `halation-bloom` (Explosão de luz com halo de filme), `type-rhythm-sync` (Alinhamento de legenda com batida), `tracking-expand-reveal` (Expansão de espaçamento de caracteres), `terminal-typewriter` (Máquina de escrever de terminal de hacker), `keyword-reveal` (Revelação gradual de palavra-chave), `quote-card` (Cartão de citação elegante), `highlighter-sweep` (Marca-texto), `cel-flash-stomp` (Flash de impacto定格)
`interaction` (Componentes e Interação)	`cards/interaction/` (58 cartões)	Objetos miméticos, componentes interativos, cartões flutuantes, pop-ups e colaboração de cursor	`command-palette-summon` (Convocação flutuante Cmd+K), `stack-reveal` (Revelação de pilha de cartões), `popup-book-rise` (Levantamento de livro pop-up de papel), `masking-tape-slap` (Fita crepe), `autolayout-gap-dial` (Discagem de layout automático), `carousel-3d` (Carrossel 3D), `theme-switch-moves` (Ondulação de troca de tema), `collab-cursor-moves` (Concerto de múltiplos cursores), `type-and-filter` (Filtro de digitação), `glassmorphism-card` (Painel de vidro fosco)
`data` (Dados e Gráficos)	`cards/data/` (20 cartões)	Sedimentação de partículas físicas, linhas quebradas dinâmicas e gráficos de barras, painéis, corrida de números	`particle-sand-fill` (Sedimentação de areia por gravidade), `counter-confetti` (Corrida de números + confete), `number-counter` (Contagem rolante), `chart-grow` (Crescimento de gráfico de barras/linhas), `chart-live-moves` (Fluxo de dados em tempo real), `gauge-readout-moves` (Salto de ponteiro de medidor), `before-after-slider-scrub` (Controle deslizante de comparação antes/depois), `scroll-brake-moves` (Parada brusca de rolagem)
`effects` (Efeitos Especiais e Iluminação)	`cards/effects/` (22 cartões)	Flare de luz, varredura HUD, cristal 3D rotativo, campo de partículas atmosféricas	`three-crystal` (Cristal 3D rotativo Three.js), `light-play-moves` (Difusão de luz de varredura), `spotlight-sweep-moves` (Varrimento de holofote), `glow-flyline-moves` (Linhas de voo brilhantes), `fui-hud-moves` (Expansão de wireframe tecnológico), `impact-feedback` (Onda de choque de impacto de anime), `canvas-particles` (Dezenas de milhares de partículas fluidas), `flying-words` (Nuvem de palavras em movimento)
`rhythm` (Edição e Ritmo)	`cards/rhythm/` (8 cartões)	Corte rítmico, flash beat, divisão de tela, montagem	`beat-cut-moves` (Corte rápido com flash de batida), `speed-ramp-freeze` (Congelamento com anotação de velocidade variável), `quad-split-parallel-scenes` (Quatro telas paralelas), `panel-grid-moves` (Reorganização de painéis de quadrinhos), `rhythm-interrupt-moves` (Avanço de corte e impacto), `trailer-grammar-moves` (Tela preta de impacto de trailer)
`commercial` (Cenas Comerciais)	`cards/commercial/` (43 cartões)	Cena de apresentação de produto, abertura e encerramento de marca, introdução de tema, logotipo final	`hook` (Cena de gancho de ponto de dor), `price-card` (Cartão de preço e plano), `features` (Lista de recursos em fluxo), `store-card` (Cartão de localização da loja), `fact-sheet` (Lista de fatos), `brand-ink-open` (Abertura de tinta de marca), `logo-shrink-wordmark-lockup` (Encolhimento de logotipo), `ui-to-brand-morph` (Morfagem de UI para logotipo da marca)
`transition` (Transição de Cena)	`cards/transition/` (26 cartões)	Transformação espaço-temporal e transição visual nos limites da cena, eliminando cortes bruscos	`cube-rotate` (Giro multidimensional de cubo 3D), `clock-wipe` (Apagamento com ponteiro de relógio), `bubble-swarm-takeover` (Máscara de enxame de bolhas), `color-block-step-wipe` (Apagamento por bloco de cor), `paper-plane-messenger` (Avião de papel em movimento), `push-through` (Empurrão através), `whip-pan` (Pan rápido e desfocado), `dark-tunnel` (Túnel escuro em movimento)
`media` (Exibição Multimídia)	`cards/media/` (15 cartões)	Composição de entrada de imagens externas, clipes de vídeo e Picture-in-Picture	`media-pop-in` (Aparecimento leve e rápido), `split-compare` (Comparação com controle deslizante de tela dividida esquerda-direita), `svg-path` (Extensão de caminho vetorial), `video-pip-float` (Picture-in-Picture flutuante), `photo-polaroid-scatter` (Dispersão de fotos Polaroid)

Base Subjacente (cards/_shared/): Fornece primitivas de renderização comuns para toda a biblioteca (como SpeedBlur desfoque de movimento, softShadow sombra suave física dupla, Stage refletor de luz de palco) e cálculo adaptativo de tamanho de fonte tipográfica comercial, não exposto como cartão independente.

4.3 Combinações Clássicas de Inspiração para Seis Tipos de Vídeo (Apenas como Inspiração, Sinta-se Livre para Inovar)

Abaixo estão apenas referências de combinação de inspiração para estilos comuns, não regras rígidas. O Agente pode misturar e combinar livremente com base na criatividade real:

Ciência e Conhecimento Geral (Science Explainer):
- Combinação de Inspiração: typography/scramble-decode (Decodificação de caracteres) + data/particle-sand-fill (Demonstração de magnitude com areia física) + media/svg-path (Conexão de conceitos) + transition/color-block-step-wipe.
Filosofia e Ensaio Profundo (Philosophical Essay):
- Combinação de Inspiração: typography/halation-bloom (Explosão de luz de filme de alto brilho) + camera/dolly-zoom (Abstração de profundidade espacial) + typography/quote-card (Citação elegante) + effects/canvas-particles (Poeira fraca).
Produto de Tecnologia e Lançamento de Funcionalidade (Product Promo):
- Combinação de Inspiração: effects/three-crystal (Aparição de componente 3D) + interaction/command-palette-summon (Convulsão de produtividade) + data/counter-confetti (Recorde de desempenho) + transition/cube-rotate.
Estratégia de Negócios e Painel de Dados (Business & Strategy):
- Combinação de Inspiração: data/gauge-readout-moves (Ponteiro de medidor) + data/chart-live-moves (Crescimento de curva) + typography/highlighter-sweep (Marca de dados) + transition/clock-wipe.
Emoção Musical e MV Dinâmico (Music Story & Lyrics):
- Combinação de Inspiração: typography/type-rhythm-sync (Faixa de batida de verso) + typography/cel-flash-stomp (Acento de refrão定格) + camera/shot-crash-zoom-punch (Impacto de batida) + transition/whip-pan.
Vintage Artesanal e Scrapbook (Scrapbook & Handcrafted):
- Combinação de Inspiração: interaction/masking-tape-slap (Fita adesiva) + interaction/popup-book-rise (Livro pop-up) + typography/split-flap-flip (Flip card mecânico) + transition/paper-plane-messenger.

4.4 Especificações de Montagem de Quatro Slots e Limites de Qualidade Objetivos

Cada cena em film.json suporta quatro slots desacoplados no atributo motion:

{
  "motion": {
    "camera": { "cardId": "camera/slow-push", "params": { "scale": 1.15 } },
    "primary": { "cardId": "data/particle-sand-fill", "params": { "gravity": 1.2 } },
    "text": { "cardId": "typography/halation-bloom", "params": { "bloomIntensity": 0.8 } },
    "transitionOut": { "cardId": "transition/cube-rotate", "params": { "direction": "left" } }
  }
}

Limites de Qualidade Objetivos (Devem Ser Mantidos):
1. Foco Visual Claro: Em uma mesma cena, a imagem deve ter um protagonista claro. Se um efeito de componente primary intenso for usado, o movimento da câmera camera deve ser suave e respiratório; se um shot-crash-zoom-punch forte for usado para a câmera, o conteúdo do componente deve permanecer relativamente estático, evitando uma profusão de movimentos que cause tontura visual;
2. Tempo de Retenção Cognitiva Suficiente (Cognitive Hold Time): Após a conclusão da animação de entrada e expansão, o texto e a estrutura central da tela devem manter um período de estabilidade de pelo menos 45 a 90 quadros (1,5 s a 3,0 s), garantindo que o espectador possa ler e compreender calmamente. É estritamente proibido cortar imediatamente após a animação terminar;
3. Correspondência do Comprimento do Texto com a Proporção da Tela: Para uma única linha de texto em modo paisagem, recomenda-se não exceder 22 caracteres chineses; para modo retrato, recomenda-se não exceder 14 caracteres chineses, para evitar quebras de linha sobrepostas ou saídas da zona segura do vídeo.

5. Protocolo de Storyboard Film IR e Especificações de Renderização Multi-Tecnologia

film.json é a única fonte de verdade semântica de todo o projeto.

5.1 Estrutura Padrão do Film IR

{
  "id": "project-slug",
  "title": "Título do Vídeo do Projeto",
  "genre": "explainer",
  "brief": {
    "goal": "Objetivo narrativo principal",
    "audience": "Público-alvo",
    "tone": "Tom e estilo"
  },
  "output": { "width": 1920, "height": 1080, "fps": 30 },
  "theme": {
    "background": "#0a0f1d",
    "foreground": "#f8fafc",
    "accent": "#38bdf8",
    "fontFamily": "Inter, PingFang SC, sans-serif"
  },
  "scenes": [
    {
      "id": "scene-01",
      "title": "Nome da Cena",
      "intent": "Intenção narrativa",
      "semantic": "hook",
      "durationInFrames": 90,
      "onScreenText": ["Título principal na tela", "Texto explicativo do subtítulo"],
      "layout": { "kind": "center-headline" },
      "renderer": "html",
      "sceneComponent": "scene/stack-explainer",
      "motion": {
        "camera": { "cardId": "camera/slow-push" },
        "primary": { "cardId": "interaction/stack-reveal" },
        "text": { "cardId": "typography/scramble-decode" },
        "transitionOut": { "cardId": "transition/cube-rotate" }
      },
      "props": {},
      "qa": { "keyFrames": [20, 45, 80] }
    }
  ]
}

5.2 Mecanismo de Adaptação Dupla (16:9 ↔ 9:16)

Todas as cenas e cartões suportam dimensionamento responsivo de forma unificada. Use um contêiner de proporção base no código da cena:

import React from 'react';
import { useVideoConfig } from 'remotion';

export const AdaptiveStage: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const { width, height } = useVideoConfig();
  const isPortrait = height > width;
  const baseWidth = isPortrait ? 1080 : 1920;
  const baseHeight = isPortrait ? 1920 : 1080;

  return (
    <div style={{
      width: baseWidth,
      height: baseHeight,
      transform: `scale(${width / baseWidth})`,
      transformOrigin: 'top left',
      overflow: 'hidden',
    }}>
      {children}
    </div>
  );
};

Nota para o Agente: Sempre envolva o conteúdo da cena com este AdaptiveStage para garantir que os cartões funcionem corretamente em ambas as proporções. Os cartões da biblioteca cards/_shared/ já são compatíveis, mas componentes de cena personalizados devem usá-lo explicitamente.

6. Ciclo de Vida Completo da Ferramenta CLI e Interação com a Bancada Local

6.1 Visão Geral dos Comandos

Comando	Descrição	Caminho de Execução
`forge create`	Cria um novo projeto a partir de um modelo	`PROJECT_ROOT` (cria novo diretório)
`forge validate`	Valida a estrutura do projeto, ativos e Film IR	`PROJECT_ROOT`
`forge approve-design`	Registra a aprovação G1 no histórico de revisões	`PROJECT_ROOT`
`forge render`	Renderiza uma cena de amostra ou o vídeo completo	`PROJECT_ROOT`
`forge approve-sample`	Registra a aprovação G2, desbloqueando a renderização completa	`PROJECT_ROOT`
`forge preview`	Inicia a bancada local de depuração visual	`PROJECT_ROOT`
`forge audit`	Executa varredura de independência e verificação de aderência	`PROJECT_ROOT`

6.2 Bancada Local de Depuração Visual

Após iniciar npm run forge preview -- --project <project-id>, a bancada fornece:

Navegação visual por cena com timeline;
Depuração de parâmetros de cartão em tempo real;
Visualização de sobreposição de texto e ativos;
Reprodução de áudio sincronizada;
Métricas de desempenho (tempo de renderização por frame, uso de memória).

7. Lista de Verificação de Entrega Final e Solução de Problemas

7.1 Lista de Verificação de Entrega Final

Antes de declarar a conclusão, o Agente deve verificar:

A renderização foi concluída com sucesso?
O arquivo de saída (MP4) está no diretório output/projects/<id>/?
A varredura de independência (forge audit) passou?
Todos os ativos necessários estão incluídos em public/?
O histórico de revisões G1 e G2 está registrado?
O projeto pode ser reconstruído independentemente em outro ambiente?

7.2 Problemas Comuns e Soluções

Problema	Causa Provável	Solução
Tela preta durante a renderização	Cena sem componente principal ou erro de importação	Verifique se `sceneComponent` existe e está exportado corretamente
Áudio dessincronizado	Desalinhamento entre a duração do texto e o áudio	Ajuste `durationInFrames` ou use o timeline da bancada
Cartão de efeito não encontrado	ID do cartão incorreto em `film.json`	Verifique a ortografia e o caminho do cartão
Erro de dependência durante `npm ci`	Dependências ausentes no `package.json` do projeto	Certifique-se de que o modelo de criação inclui todas as dependências

Aviso de Direitos Autorais: Todos os ativos, cartões de efeitos e modelos neste sistema são fornecidos apenas como referência. Os usuários são responsáveis por garantir que o conteúdo de seus projetos não infringe direitos de terceiros.

hyqlai/motion-forge

O que é motion-forge?

Perguntar na sua IA favorita

Documentação