Instalação do plugin: Antes dos comandos de configuração ou atualização, siga as regras de instalação de plugin quando este skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
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 e sem efeitos quando tudo está atualizado; caso contrário, ele atualiza este skill mais os skills de domínio principal dos quais ele depende antes que você possa usá-los.
Remotion para HyperFrames
A porta de entrada é
/hyperframes. Use este skill apenas para portar o código-fonte de uma composição Remotion (React) existente para HyperFrames, unidirecional. Criar uma composição nova, recriar a partir de uma fonte não-Remotion (After Effects, Framer Motion, React / CSS puro — não há código-fonte Remotion para traduzir), uma menção passageira ao Remotion, ou qualquer incerteza → leia/hyperframesprimeiro: a camada de intenção é responsável por todas as decisões de rota.
Visão Geral
Traduz 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% que podem causar perda de qualidade, recusando-se a traduzir padrões que não se encaixam no modelo baseado em seek do HF e recomendando o padrão de interop em tempo de execução do PR #214.
O skill é fornecido com um conjunto de teste em camadas (T1–T4, 4 fixtures no total) que avalia 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 abaixo da linha de base validada está silenciosamente errada.
Quando usar
Use este skill APENAS quando o usuário pedir explicitamente para migrar do Remotion. Exemplos de frases de gatilho:
- "porta meu projeto Remotion para HyperFrames"
- "converte este código Remotion para HyperFrames"
- "migra do Remotion"
- "traduz esta composição Remotion"
- "reescreve isso como HTML do HyperFrames"
NÃO use este skill quando:
- (a) O usuário está criando uma composição nova do HyperFrames, mesmo que ele 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 meu Remotion" sem pedir explicitamente para migrar o código-fonte — trate como uma nova construção HyperFrames.
NÃO SUPORTADO (recuse — este skill não faz isso):
- A direção inversa. Exportar uma composição HyperFrames de volta para o 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 do After Effects (
.aep), uma animação Framer Motion / React puro / CSS, ou qualquer outra ferramenta não é uma composição Remotion — não há código-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 do HyperFrames).
Fluxo de Trabalho
Passo 1: Lint do código-fonte
Execute scripts/lint_source.py sobre o diretório de origem Remotion. O lint detecta padrões que não podem ser traduzidos de forma limpa:
- Bloqueadores (recuse + recomende interop):
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 descartar o construto): configuração
@remotion/lambda,delayRender,useCallback,useMemo, hooks personalizados. - Informação (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 param a tradução — descarte o construto problemático no passo 3 e anote a lacuna em TRANSLATION_NOTES.md. A configuração @remotion/lambda é o caso canônico de aviso: o skill descarta a importação + chamadas renderMediaOnLambda(...) mas traduz o resto da composição.
Passo 2: Planeje a tradução
Leia references/api-map.md — o índice de cada API do 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 o código-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 todas — carregue apenas o que o código-fonte específico precisa.
Pesquise no catálogo ativo por qualquer efeito visual que a tabela não mapeia. Quando o código-fonte descreve um visual sem equivalente na API do HF — uma sobreposição de scanline/CRT, um efeito de glitch ou aberração cromática, um wipe de shader, um tratamento de grão de filme — execute npx hyperframes catalog --query "<o efeito, em português claro>" --json antes de escrevê-lo manualmente em GSAP. A pesquisa não precisa de nada instalado: sem projeto, sem add anterior, sem conta. Ela classifica todo o registro hospedado (~400 blocos e componentes) de qualquer diretório, e o transitions.md já usa esta rota para clockWipe() / iris() via npx hyperframes add sdf-iris. Um componente real está mais próximo do código-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 adequado, e registre a substituição em TRANSLATION_NOTES.md de qualquer forma.
Passo 3: Gere a composição HF
Emita index.html com:
<div id="stage">raiz carregando odata-composition-id,data-start="0",data-duration(em segundos),data-fps,data-width,data-heightda composição, além de umdata-*por property escalar.- Uma
<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 (o 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 offset 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 embutidos como HTML repetido usando a interface de props como template (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 na fixture)
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 do p05 do nível de complexidade do código-fonte (veja a tabela de limites validados em eval.md). Se a diferença falhar, execute scripts/frame_strip.sh para ver quais quadros divergiram, e então releia a referência relevante de tempo/sequenciamento/mídia.
Crítico: ambas as renderizações devem usar formato de pixel correspondente. Defina Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") no remotion.config.ts do código-fonte Remotion — caso contrário, a diferença medirá diferenças de codificador (~0.05 de penalidade SSIM), não fidelidade de tradução.
Passo 5: Documente lacunas
Qualquer coisa que não tenha sido traduzida de forma limpa (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 este skill 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 baseado em seek do HyperFrames. Recomende o padrão de interop em tempo de execução. - Executar o pipeline de renderização do Remotion junto com o HyperFrames. Esse é o padrão de interop 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 é sobre implantação, não animação. O skill descarta isso como um 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 (renderização + 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 o skill está funcionando de ponta a ponta em uma verificação limpa — e como um teste de regressão após editar qualquer referência.
Linha de base validada (em 27/04/2026):
| Nível | 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 aprovado | n/a |