AnmolChandiok/ae-editable-project

Projeto do After Effects editável a partir de um vídeo feito com código

O objetivo é um projeto que um motion designer possa abrir e trabalhar como se tivesse construído manualmente. O texto é real, os caminhos são camadas de forma, cada objeto é uma pré-composição nomeada e a câmera é um nulo que pode ser reanimado com keyframes. O oposto é uma sequência de quadros renderizados colocados em uma composição, que não pode ser editada, portanto nunca entregue isso como animação principal.

A abordagem tem três etapas:

1. Exportar a cena a partir dos mesmos dados que o renderizador desenha.
2. Escrever como scene.json.
3. Fazer o After Effects construir o projeto por conta própria, executando um ExtendScript gerado.

Você nunca escreve um .aep binário manualmente.

dados do renderizador ──exportar──▶ scene.json + assets/ ──make_jsx.js──▶ build.jsx ──After Effects──▶ project.aep (+ stills de verificação)

Scripts inclusos (em scripts/):

• aelib.jsx: o construtor que roda dentro do After Effects. Ele lê a cena e cria composições, camadas, keyframes, máscaras, efeitos, mates, marcadores e áudio, depois salva o .aep e um log de construção.
• make_jsx.js: node make_jsx.js [--portable] scene.json build.jsx. Verifica a cena (ativos ausentes, pais inválidos, ordem das pré-composições) e escreve um build.jsx autocontido. Com --portable, os caminhos são relativos ao build.jsx, permitindo zipar a pasta e executar em outro computador, incluindo Windows. Use para tudo que você entregar.
• run_in_ae.sh: run_in_ae.sh build.jsx /caminho/absoluto/Projeto.aep [timeout]. No macOS, executa a construção no After Effects instalado, aguarda e imprime o log.

Leia references/scene-spec.md antes de escrever o exportador. Ele define cada campo, easing, os nomes de efeitos verificados, faixas de valores e as armadilhas que custam tempo.

Fluxo de trabalho

1. Inventariar o que o vídeo desenha

Leia o renderizador e liste tudo que aparece na tela e como se move:

• O mundo ou fundo.
• Cada objeto ou documento.
• Cada pedaço de texto.
• O movimento da câmera.
• Momentos sincronizados com palavras ou batidas.
• O visual: granulação, brilho, vinheta, motion blur, fades.
• O áudio.

Para cada item, anote de onde vêm seus números (constantes, funções geométricas, arquivos de temporização).

2. Mapear cada elemento para sua forma nativa no After Effects

Escolha a forma que um motion designer construiria manualmente:

No código	No After Effects
Movimento de câmera sobre um mundo (translação, escala, rotação)	Um nulo de CÂMERA. Ponto de Ancoragem = o ponto para onde a câmera olha, em coordenadas do mundo. Escala = zoom. Rotação = rotação. Posição = centro da comp. Vincule todas as camadas do mundo a ele. Então tela = posição + R·escala·(p − âncora), que é exatamente a transformação da câmera do canvas, então as camadas do mundo mantêm as coordenadas que o código usa.
Trepidação manual, choques de impacto	Uma expressão na posição e rotação do nulo, controlada por Controles Deslizantes nomeados para o que fazem ("Intensidade da trepidação", "Força do impacto")
Um objeto ou documento (impresso, papel, cartão, livro)	Sua própria pré-composição contendo borda, foto, texto, uma sombra de contato e um sólido "Dim". Crie em 2× e dimensione a camada para 50%. Ative colapso. Anime a entrada na camada da pré-composição.
Caminhos vetoriais (costas, regras, círculos, linhas)	Camadas de forma, um grupo por peça lógica, nomeados
Texto	Camadas de texto com a string real e o nome da fonte PostScript. Nunca use imagens de texto pré-renderizadas.
Bitmaps que o código gera (fotos placeholder, texturas de papel)	Exporte como PNG/JPG, nomeie de forma que seja fácil trocar ("FOTO — substitua-me")
Escrita que aparece palavra por palavra na narração	Uma camada de texto com reveal: { times: [...] }. O construtor cria keyframes de máscara Write-on por palavra (medida no AE), e o texto permanece editável.
Uma linha se desenhando	Trim Paths end keyframes 0→100
Carimbo / batida	Keyframes de escala/opacidade mais uma entrada na lista de impactos da câmera
Foco no herói / escurecendo outros	Um sólido preto "Dim" com Preservar Transparência dentro de cada pré-composição, mais um sólido Dim em espaço de tela sobre o fundo, com keyframes de opacidade
Visual de filme	Camadas de ajuste nomeadas ("VISUAL — Brilho suave", "VISUAL — Grão de filme"), um sólido de vinheta com máscara invertida esmaecida, um sólido de fade, e motion blur de composição nas camadas do mundo. Nomeie todos para que sejam fáceis de desativar.
Áudio	Faixas separadas (voz, música/efeitos) como camadas de áudio, mais as linhas de narração como marcadores de composição

3. Exportar da fonte de verdade

Adicione um caminho de exportação ao renderizador existente em vez de redigitar números. Por exemplo, exponha seus internos (module.exports, uma flag --export, ou importando seus módulos) e escreva export_ae.js / export_ae.py. Ele deve produzir scene.json e uma pasta assets/. Assim, o projeto AE e o MP4 nunca podem divergir, e reexportar após uma mudança de história é um comando.

Fazendo o movimento corresponder:

• Câmera e outras curvas. Coloque keyframes nos momentos significativos (inícios e fins de pausa, aterrissagens), não em todos os quadros. Dê a cada keyframe a velocidade real da curva naquele ponto com 33,333% de influência: isso reproduz exatamente uma cúbica Hermite. Onde um movimento também faz algo no meio (zoom de afastamento, zoom em espaço logarítmico), adicione keyframes em ¼, ½ e ¾ do movimento com suas próprias derivadas. Calcule derivadas numericamente a partir da própria função de câmera do renderizador.
• Velocidades com sinal. As velocidades de rotação, escala e opacidade são sinalizadas. Propriedades espaciais (posição, ponto de ancoragem) usam apenas magnitude.
• Keyframes por quadro são aceitáveis apenas para coisas genuinamente irregulares, como uma cintilação. Todo o resto deve ser fácil de pegar e mover.
• Retemporização. Leia temporizações do mesmo arquivo que o renderizador usa (ex.: timings.json), para que retemporizar a narração retemporize o projeto.

Escreva para o humano que vai abrir:

• Nomeie cada camada pelo que é ("Círculo de tinta (desenha em 'Ponta do Kestrel')", "Dim do mapa (foco no herói)").
• Coloque um comment de uma linha em qualquer coisa não óbvia.
• Use rótulos para agrupar e dê ao nulo da câmera um rótulo distinto.
• Linhas de narração vão como marcadores de composição.

4. Construir e verificar

node <skill>/scripts/make_jsx.js --portable --quiet scene.json build.jsx   # build.jsx fica ao lado de assets/
<skill>/scripts/run_in_ae.sh build.jsx "/caminho/absoluto/Meu Projeto.aep" 1500

• Pré-requisito (uma vez, no AE): Configurações → Scripts e Expressões → ative "Permitir que scripts escrevam arquivos e acessem rede". Sem isso, salvar e o log de construção falham. Se o executor expirar, essa configuração (ou uma caixa de diálogo aberta no AE) é a causa usual; peça ao usuário para verificar.
• Não descarta trabalho. Se o projeto AE aberto tiver alterações não salvas, a construção para e informa no log. Nunca ignore isso descartando o projeto do usuário; peça que ele salve ou feche. Use --quiet para construções automatizadas para que a mensagem vá para o log, não para uma caixa de diálogo que bloqueia o AE. Regere sem --quiet para o build.jsx que você entrega, para que quem executar manualmente veja a mensagem.
• O log de construção (<Projeto>.build-log.txt) lista toda camada, efeito ou propriedade que falhou. Trate qualquer problema como um bug na cena e corrija no exportador, não no AE.
• Stills de verificação. Defina project.stills para 5–8 momentos reveladores: um momento sincronizado com palavra, meio da queda, uma pausa do herói, o título. O construtor os renderiza a partir da comp principal. Eles renderizam de forma assíncrona após o salvamento, e o executor os aguarda. São PNGs de 16 bits que o ffmpeg nem sempre lê, então visualize-os com sips -s format jpeg -Z 1920 in.png --out out.jpg.
• Compare lado a lado com quadros da renderização original nos mesmos momentos. Verifique enquadramento, qual objeto é o herói, se as revelações de texto acertam a palavra, e cor e brilho. Depois corrija o exportador e reconstrua. O brilho no AE é muito mais forte que um "screen de uma cópia desfocada" do canvas, então comece com um limiar alto (~200 de 255) e intensidade baixa (~0,2).

Se o After Effects não estiver nesta máquina, ou a pessoa que vai editar estiver em outro computador, não tente executá-lo. Entregue a pasta portátil (build.jsx, assets/, scene.json, README). Eles executam com Arquivo → Scripts → Executar Arquivo de Script… e o .aep é salvo ao lado de build.jsx. O README deve informar que é necessário ativar a configuração de escrita de arquivos de script primeiro, e que as fontes devem estar instaladas.

5. Entregar

Entregue uma pasta contendo:

• <Nome>.aep
• assets/
• build.jsx e scene.json, para que o projeto possa ser reconstruído
• o script exportador
• um README.md curto que diga como:
  • mover a câmera: crie keyframes no Ponto de Ancoragem (para onde ela olha) e Escala (zoom) do nulo CÂMERA
  • trocar uma foto: no painel Projeto, selecione o ativo e use Arquivo → Substituir Footage
  • retemporizar uma palavra: arraste os keyframes Write-on dessa camada, ou reexporte após alterar temporizações
  • ativar/desativar as camadas de visual
  • alterar texto: clique duas vezes nele
  • quais fontes devem estar instaladas

Diga claramente ao usuário:

• o que é correspondido exatamente (layout, temporização, keyframes)
• o que é aproximado (o brilho, grão e cor do AE diferem um pouco da composição do canvas)
• o que você verificou com stills e o que não verificou (ex.: reprodução completa)

Coisas que já deram errado antes

Estas são as razões por trás das convenções acima:

• Sombras e desfoques em camadas de forma ou texto não escalam com a câmera, porque seus efeitos são aplicados após a transformação. Use sólidos com máscaras para brilhos e sombras em espaço do mundo.
• Pré-composições ficam suaves quando a câmera dá zoom. Corrija com transformações de colapso e crie em 2×.
• Máscaras esmaecidas são cortadas na borda do sólido. Faça sólidos de brilho muito maiores que o brilho.
• Fontes devem ser nomes PostScript. Verifique fontes desconhecidas no AE com uma sonda rápida: defina textDocument.font e leia de volta.
• ExtendScript é ES3 e lê mal ternários encadeados (a ? b : c ? d : e): use uma tabela de consulta ou if/else. Se alterar aelib.jsx, teste em uma cena pequena primeiro (uma camada de texto, uma forma, uma pré-composição) antes da construção completa.