Remotion para HyperFrames
Confirme a rota antes de construir. Use isso apenas para portar o código-fonte de uma composição Remotion (React) existente para HyperFrames. Criar uma composição nova (mesmo que inspirada em um vídeo Remotion) → os fluxos de trabalho de criação /
/general-video. Fora do escopo (unidirecional, somente Remotion): sem exportação reversa (HyperFrames → Remotion ou qualquer framework), e uma fonte não-Remotion (After Effects, Framer Motion, React / CSS simples) não tem uma fonte Remotion para traduzir → recrie via/general-video. Não tem certeza, ou apenas uma menção passageira ao Remotion? Leia/hyperframesprimeiro.
Visão Geral
Traduza composições de vídeo Remotion (baseadas em React) para composições HyperFrames (HTML + GSAP). A maioria dos idiomas do Remotion tem equivalentes diretos em HyperFrames — a tradução é mecânica para ~80% das composições típicas. Esta habilidade codifica o mapeamento e protege contra os 20% com perdas, recusando-se a traduzir padrões que não se encaixam no modelo orientado a seek do HF e recomendando, em vez disso, o padrão de interoperação em tempo de execução do PR #214.
A habilidade vem com um conjunto de teste em camadas (T1–T4, 4 fixtures no total) que classifica as traduções em relação a limites de SSIM medidos. Não traduza sem executar a avaliação — uma tradução que "parece correta" mas renderiza 0,05 SSIM a menos do que a linha de base validada está silenciosamente errada.
Quando usar
Use esta habilidade SOMENTE quando o usuário solicitar explicitamente a migração do Remotion. Exemplos de frases de gatilho:
- "portar meu projeto Remotion para HyperFrames"
- "converter este código Remotion para HyperFrames"
- "migrar do Remotion"
- "traduzir esta composição Remotion"
- "reescrever isto como HTML HyperFrames"
NÃO use esta habilidade quando:
- (a) O usuário está criando uma composição nova do HyperFrames, mesmo que ele tenha ou esteja fazendo teste A/B com um vídeo Remotion semelhante.
- (b) O usuário menciona Remotion de passagem sem solicitar migração.
- (c) O usuário compartilha código Remotion como material de referência em vez de pedir uma tradução.
- (d) O usuário pede "o mesmo vídeo que o meu Remotion" sem solicitar explicitamente a migração do código-fonte — trate isso como uma construção HyperFrames nova.
NÃO SUPORTADO (recuse — não é isso que esta habilidade faz):
- A direção reversa. Exportar uma composição HyperFrames de volta para Remotion (ou para qualquer outro framework) não é um fluxo de trabalho — a tradução é Remotion → HyperFrames apenas. Diga isso claramente.
- Fontes não-Remotion. Um projeto After Effects (
.aep), uma animação Framer Motion / React simples / CSS, ou a fonte de qualquer outra ferramenta não é uma composição Remotion — não há fonte Remotion para traduzir. Recrie-a nativamente via/general-video, ou recuse se HyperFrames não puder representá-la.
Em caso de dúvida, opte por criar uma composição HyperFrames nativa com /general-video (o fluxo geral de criação do HyperFrames).
Fluxo de Trabalho
Etapa 1: Lint da Fonte
Execute scripts/lint_source.py sobre o diretório fonte Remotion. O lint detecta padrões que não podem ser traduzidos limpidamente:
- Bloqueadores (recuse + recomende interoperação):
useState,useReducer,useEffect/useLayoutEffectcom dependências não vazias,calculateMetadataassíncrono, bibliotecas React de UI de terceiros (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Avisos (traduza após descartar a construção): configuração
@remotion/lambda,delayRender,useCallback,useMemo, hooks personalizados. - Informação (traduza com nota):
staticFile,interpolateColors.
Se qualquer bloqueador disparar, pare. Leia references/escape-hatch.md e exiba a mensagem de recomendação. Avisos não param a tradução — descarte a construção ofensiva na etapa 3 e anote a lacuna em TRANSLATION_NOTES.md. A configuração @remotion/lambda é o caso de aviso canônico: a habilidade descarta a importação + chamadas renderMediaOnLambda(...) mas traduz o resto da composição.
Etapa 2: Planeje a Tradução
Leia references/api-map.md — o índice de cada API do Remotion e seu equivalente HF ou referência por tópico. Identifique quais referências de tópico você precisará com base no que a fonte usa:
| Fonte contém | Carregar referência |
|---|---|
Composition, defaultProps, schema, calculateMetadata | parameters.md |
Sequence, Series, Loop, AbsoluteFill, Freeze | sequencing.md |
useCurrentFrame, interpolate, spring, Easing, interpolateColors | timing.md |
Audio, Video, Img, IFrame, staticFile, delayRender | media.md |
TransitionSeries, @remotion/transitions | transitions.md |
@remotion/lottie | lottie.md |
@remotion/google-fonts/<Family>, Font.loadFont, @font-face | fonts.md |
Não carregue todos — carregue apenas o que a fonte específica precisar.
Etapa 3: Gere a Composição HF
Emita index.html com:
- Tag
<div id="stage">raiz carregando odata-composition-idda composição,data-start="0",data-duration(em segundos),data-fps,data-width,data-height, mais umdata-*por prop escalar. - Uma lista plana de divs de cena com
data-start/data-duration/data-track-index. <style>inline para layout; CSS define o estadofromde toda propriedade animada.- Uma única tag
<script>no final contendo umagsap.timeline({paused: true})pausada. Cada derivaçãouseCurrentFrame()do Remotion se torna um tween nesta timeline no offset correto. window.__timelines["<composition-id>"] = tl;registra a timeline com o runtime do HF.
Subcomponentes React personalizados são inline como HTML repetido usando a interface de props como modelo (veja parameters.md para o padrão data-* por instância).
Etapa 4: Valide
Execute o harness de avaliação — references/eval.md para o guia completo. Caminho rápido:
# Renderizar linha de base Remotion (após npm install na fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# Renderizar tradução HF
cd ../hf-src && npx hyperframes render --output ../hf.mp4
# Diferença SSIM
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Limiar: ~0,02 abaixo de p05 do nível de complexidade da fonte (veja a tabela de limiares validados em eval.md). Se a diferença falhar, execute scripts/frame_strip.sh para ver quais quadros divergiram, depois releia a referência de timing/sequenciamento/mídia relevante.
Crítico: ambas as renderizações devem usar formato de pixel correspondente. Defina Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") no remotion.config.ts da fonte Remotion — caso contrário, a diferença mede diferenças de codificador (~0,05 de impacto SSIM), não a fidelidade da tradução.
Etapa 5: Documente as Lacunas
Qualquer coisa que não tenha sido traduzida limpidamente (rampas de volume descartadas, apresentações personalizadas aproximadas, fontes substituídas) gera um TRANSLATION_NOTES.md escrito ao lado da saída HF. Veja references/limitations.md para o formato.
O que esta habilidade explicitamente NÃO faz
- Traduzir máquinas de estado React. Composições que conduzem animação via
useState+useEffectnão são alvos determinísticos de captura de quadro no modelo orientado a seek do HyperFrames. Recomende o padrão de interoperação em tempo de execução. - Executar o pipeline de renderização do Remotion juntamente com HyperFrames. Esse é o padrão de interoperação em tempo de execução do PR #214 — uma solução separada para composições que falham no lint desta habilidade.
(@remotion/lambda não é um bloqueador — a configuração Lambda é implantação, não animação. A habilidade descarta como aviso e traduz o resto. Veja references/escape-hatch.md.)
Como avaliar sua própria tradução
Execute o orquestrador do conjunto de teste:
./assets/test-corpus/run.sh
Ele executa T1, T2, T3 (renderizar + diferença) e T4 (validação de lint), imprime uma tabela de aprovação/reprovação por nível e emite um relatório JSON agregado. Use isso para verificar se a habilidade está funcionando de ponta a ponta em um checkout limpo — e como uma verificação de regressão após editar qualquer referência.
Linha de base validada (a partir de 2026-04-27):
| Nível | Forma da Composição | SSIM Médio | Limiar |
|---|---|---|---|
| T1 | fade-in de elemento único | 0,974 | 0,95 |
| T2 | multi-cena + spring + áudio + imagem | 0,985 | 0,95 |
| T3 | orientado a dados, subcomponentes personalizados, contagem | 0,953 | 0,90 |
| T4 | escape-hatch (8 casos de lint) | 8/8 passam | n/a |