remotion-to-hyperframes

$2b

• (a) The user is authoring a new HyperFrames composition, even if they have or are A/B-testing a similar Remotion video.

• (b) The user mentions Remotion in passing without asking for migration.

• (c) The user shares Remotion code as reference material rather than asking for a translation.

• (d) The user asks for "the same video as my Remotion one" without explicitly asking to migrate the source — treat that as a fresh HyperFrames build.

When in doubt, default to authoring a native HyperFrames composition with the hyperframes skill instead.

Workflow

Step 1: Lint the source

Run scripts/lint_source.py over the Remotion source directory. The lint detects patterns that can't translate cleanly:

• Blockers (refuse + recommend interop): useState, useReducer, useEffect/useLayoutEffect with non-empty deps, async calculateMetadata, third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).

• Warnings (translate after dropping the construct): @remotion/lambda config, delayRender, useCallback, useMemo, custom hooks.

• Info (translate with note): staticFile, interpolateColors.

If any blocker fires, stop. Read references/escape-hatch.md and surface the recommendation message. Warnings don't stop translation — drop the offending construct in step 3 and note the gap in TRANSLATION_NOTES.md. @remotion/lambda config is the canonical warning case: the skill drops the import + renderMediaOnLambda(...) calls but translates the rest of the composition.

Step 2: Plan the translation

Read references/api-map.md — the index of every Remotion API and its HF equivalent or per-topic reference. Identify which topic references you'll need based on what the source uses:

Source contains

Load reference

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

Don't load all of them — load only what the specific source needs.

Step 3: Generate the HF composition

Emit index.html with:

• Root <div id="stage"> carrying the composition's data-composition-id, data-start="0", data-duration (in seconds), data-fps, data-width, data-height, plus one data-* per scalar prop.

• A flat list of scene divs with data-start / data-duration / data-track-index.

• Inline <style> for layout; CSS sets the from state of every animated property.

• A single <script> tag at the bottom containing one paused gsap.timeline({paused: true}). Every Remotion useCurrentFrame() derivation becomes a tween on this timeline at the right offset.

• window.__timelines["<composition-id>"] = tl; registers the timeline with HF's runtime.

Custom React subcomponents inline as repeated HTML using the prop interface as the template (see parameters.md for the per-instance data-* pattern).

Step 4: Validate

Run the eval harness — references/eval.md for the full guide. Quick path:

# Render Remotion baseline (after npm install in the fixture)

cd remotion-src &#x26;&#x26; npx remotion render <CompositionId> out/baseline.mp4

# Render HF translation

cd ../hf-src &#x26;&#x26; npx hyperframes render --output ../hf.mp4

# SSIM diff

../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

Threshold: ~0.02 below p05 of the source's complexity tier (see eval.md's validated thresholds table). If the diff fails, run scripts/frame_strip.sh to see which frames diverged, then re-read the relevant timing/sequencing/media reference.

Critical: both renders must use matching pixel format. Set Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in the Remotion source's remotion.config.ts — otherwise the diff measures encoder differences (~0.05 SSIM hit), not translation fidelity.

Step 5: Document gaps

Anything that didn't translate cleanly (volume ramps dropped, custom presentations approximated, fonts substituted) gets a TRANSLATION_NOTES.md written next to the HF output. See references/limitations.md for the format.

What this skill explicitly does NOT do

• Translate React state machines. Compositions that drive animation via useState + useEffect are not deterministic frame-capture targets in HyperFrames' seek-driven model. Recommend the runtime interop pattern.

• Run Remotion's render pipeline alongside HyperFrames. That's the runtime interop pattern from PR #214 — a separate solution for compositions that fail this skill's lint.

(@remotion/lambda is not a blocker — Lambda config is deployment, not animation. The skill drops it as a warning and translates the rest. See references/escape-hatch.md.)

How to grade your own translation

Run the test corpus orchestrator:

./assets/test-corpus/run.sh

It runs T1, T2, T3 (render + diff) and T4 (lint validation), prints a per-tier pass/fail table, and emits an aggregate JSON report. Use this to verify the skill is working end-to-end on a clean checkout — and as a regression check after editing any reference.

Validated baseline (as of 2026-04-27):

Tier

Composition shape

Mean SSIM

Threshold

T1

single-element fade-in

0.974

0.95

T2

multi-scene + spring + audio + image

0.985

0.95

T3

data-driven, custom subcomponents, count-up

0.953

0.90

T4

escape-hatch (8 lint cases)

8/8 pass

n/a