Primeiro, mantenha este skill atualizado — confirme com o usuário antes de executar:
npx hyperframes skills update remotion-to-hyperframes. Uma operação rápida sem efeitos quando tudo está atualizado; caso contrário, ele atualiza este skill e os skills de domínio principais dos quais depende antes de você usá-los.
Remotion para HyperFrames
A porta de entrada é
/hyperframes. Use este apenas para portar uma composição Remotion existente (React) para HyperFrames, em uma única direção. Para criar uma nova composição, recriar a partir de uma fonte não-Remotion (After Effects, Framer Motion, React/ CSS puro — não há fonte Remotion para traduzir), uma menção passageira a Remotion ou qualquer incerteza → leia/hyperframesprimeiro: a camada de intenção decide cada rota.
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 no HyperFrames — a tradução é mecânica para ~80% das composições típicas. Este skill codifica o mapeamento e protege contra os 20% problemáticos, recusando-se a traduzir padrões que não se encaixam no modelo orientado a seek do HF e recomendando o padrão de interoperação em tempo de execução do PR #214 como alternativa.
O skill inclui um corpus de teste em camadas (T1–T4, 4 dispositivos no total) que classifica as traduções com base em limites SSIM medidos. Não traduza sem executar a avaliação — uma tradução que "parece correta", mas renderiza 0.05 SSIM abaixo da linha de base validada, está silenciosamente errada.
Quando usar
Use este skill SOMENTE quando o usuário pedir explicitamente para migrar do Remotion. Exemplos de frases de ativação:
- "portar meu projeto Remotion para HyperFrames"
- "converter este código Remotion para HyperFrames"
- "migrar do Remotion"
- "traduzir esta composição Remotion"
- "reescrever isso como HTML HyperFrames"
NÃO use este skill quando:
- (a) O usuário está criando uma nova composição HyperFrames, mesmo que tenha ou esteja testando A/B um vídeo Remotion semelhante.
- (b) O usuário menciona Remotion de passagem sem pedir 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 pedir explicitamente para migrar a fonte — trate isso como uma nova construção HyperFrames.
NÃO SUPORTADO (recuse — não é o que este skill faz):
- A direção inversa. Exportar uma composição HyperFrames de volta para Remotion (ou para qualquer outro framework) não é um fluxo de trabalho — a tradução é apenas Remotion → HyperFrames. Diga isso claramente.
- Fontes não-Remotion. Um projeto After Effects (
.aep), uma animação Framer Motion / React puro / CSS, ou qualquer outra fonte de ferramenta não é uma composição Remotion — não há fonte Remotion para traduzir. Recrie-a nativamente via/general-video, ou recuse se o HyperFrames não puder representá-la.
Em caso de dúvida, prefira criar uma composição HyperFrames nativa com /general-video (o fluxo geral de criação HyperFrames).
Fluxo de trabalho
Passo 1: Lint da fonte
Execute scripts/lint_source.py no diretório de origem Remotion. O lint detecta padrões que não podem ser traduzidos de forma limpa:
- Bloqueadores (recuse + recomende interoperação):
useState,useReducer,useEffect/useLayoutEffectcom dependências não vazias,calculateMetadataassíncrono, bibliotecas de UI React de terceiros (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Avisos (traduza após remover o construto): configuração
@remotion/lambda,delayRender,useCallback,useMemo, hooks personalizados. - Informações (traduza com nota):
staticFile,interpolateColors.
Se algum bloqueador for acionado, pare. Leia references/escape-hatch.md e apresente a mensagem de recomendação. Avisos não interrompem a tradução — remova o construto ofensivo no passo 3 e registre a lacuna em TRANSLATION_NOTES.md. A configuração @remotion/lambda é o caso canônico de aviso: o skill remove a importação + chamadas renderMediaOnLambda(...) mas traduz o restante da composição.
Passo 2: Planeje a tradução
Leia references/api-map.md — o índice de cada API Remotion e seu equivalente no 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 precisa.
Pesquise no catálogo ativo qualquer efeito visual que a tabela não mapeie. Quando a fonte pinta um visual sem equivalente na API do HF — uma sobreposição scanline/CRT, um passe de glitch ou aberração cromática, um wipe com shader, um tratamento de grão de filme — execute npx hyperframes catalog --query "<o efeito, em inglês simples>" --json antes de escrevê-lo manualmente no GSAP. A pesquisa não precisa de nada instalado: nenhum projeto, nenhum add anterior, nenhuma conta. Ela classifica todo o registro hospedado (~400 blocos e componentes) de qualquer diretório, e transitions.md já usa essa rota para clockWipe() / iris() via npx hyperframes add sdf-iris. Um componente real está mais próximo da fonte do que uma aproximação manual, então geralmente aumenta o SSIM em vez de diminuí-lo — mas a diferença de renderização no Passo 4 ainda é o árbitro. Escreva o efeito manualmente quando a pesquisa não retornar nada que se encaixe, e registre a substituição em TRANSLATION_NOTES.md de qualquer maneira.
Passo 3: Gere a composição HF
Emita index.html com:
- Raiz
<div id="stage">carregandodata-composition-id,data-start="0",data-duration(em segundos),data-fps,data-width,data-height, mais umdata-*por prop escalar. - Um
<div>host por cena comdata-composition-src="compositions/<scene>.html"edata-start/data-duration/data-track-index. A raiz não contém layout aninhado. - Um
compositions/<scene>.htmlpor cena (uma sub-composição<template>): seu<style>inline para layout (CSS define o estadofromde cada propriedade animada), sua marcação e umagsap.timeline({paused: true})no tempo local da cena. Cada derivação deuseCurrentFrame()do Remotion se torna um tween nessa timeline no deslocamento dentro da cena. window.__timelines["<scene-id>"] = tl;em cada arquivo de cena, ewindow.__timelines["<composition-id>"]para a timeline da raiz (possivelmente vazia).
Subcomponentes React personalizados são incorporados como HTML repetido usando a interface de props como modelo (veja parameters.md para o padrão data-* por instância).
Passo 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 no dispositivo)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# Renderizar tradução HF
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
# Diferença SSIM
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Limiar: ~0.02 abaixo de p05 da camada 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 tempo/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 SSIM de impacto), e não fidelidade de tradução.
Passo 5: Documente lacunas
Qualquer coisa que não tenha sido traduzida de forma limpa (ramos de volume removidos, 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 este skill explicitamente NÃO faz
- Traduzir máquinas de estado React. Composições que dirigem 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 junto com o 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 deste skill.
(@remotion/lambda não é um bloqueador — a configuração Lambda é implantação, não animação. O skill o remove como um aviso e traduz o restante. Veja references/escape-hatch.md.)
Como classificar sua própria tradução
Execute o orquestrador do corpus de teste:
./assets/test-corpus/run.sh
Ele executa T1, T2, T3 (renderização + diferença) e T4 (validação de lint), imprime uma tabela de aprovação/reprovação por camada e emite um relatório JSON agregado. Use isso para verificar se o skill está funcionando de ponta a ponta em uma cópia limpa — e como uma verificação de regressão após editar qualquer referência.
Linha de base validada (a partir de 27/04/2026):
| Camada | Forma da composição | SSIM médio | Limiar |
|---|---|---|---|
| T1 | fade-in de elemento único | 0.974 | 0.95 |
| T2 | múltiplas cenas + 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 aprovados | n/a |