Files
hyperframes/docs/guides/remotion-interop.md
T
Miguel ÁngelandClaude Opus 4.6 d9a1236ed1 feat(core): add Remotion adapter for framework interoperability
Add a runtime adapter that bridges Remotion compositions into HyperFrames'
deterministic capture pipeline. Remotion React components render inside
HyperFrames HTML compositions via a simple registration contract:

  window.__hfRemotion.push({ seekTo, pause, durationInFrames, fps })

The adapter converts HyperFrames' time-based seeks to Remotion's frame-based
seeks, enabling both GSAP and React to render in the same frame.

What's included:

- Runtime adapter (packages/core/src/runtime/adapters/remotion.ts)
- Adapter package (packages/adapter-remotion/) with mount helper + primitives
- Interop guide (docs/guides/remotion-interop.md)
- Working example (examples/remotion-adapter/)

Bug fixes discovered during development:

- fix(cli): use function replacement in validate to avoid $& expansion
- fix(producer): same $& bug in CDN script inlining
- fix(producer): externalize postcss in esbuild config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 17:37:22 +02:00

12 KiB

Remotion + HyperFrames Interop Guide

Use Remotion compositions inside HyperFrames, or HyperFrames compositions inside Remotion. No rewrites — both frameworks render in the same video.

Quick start

Use a Remotion composition in HyperFrames

# 1. Create a HyperFrames project
npx hyperframes init my-video

# 2. In a subdirectory, set up your Remotion code
mkdir remotion-src && cd remotion-src
npm init -y
npm install remotion @remotion/player react react-dom esbuild

# 3. Write your Remotion component (see examples below)
# 4. Bundle it for the browser
npx esbuild entry.tsx --bundle --outfile=../dist/bundle.js \
  --format=iife --platform=browser --target=es2020 \
  --jsx=automatic --minify \
  --define:process.env.NODE_ENV='"production"'

# 5. Reference the bundle in your HyperFrames index.html
# 6. Render
cd ..
npx hyperframes render

Using Remotion compositions in HyperFrames

How it works

HyperFrames has a Remotion runtime adapter that discovers Remotion instances registered on window.__hfRemotion and seeks them frame-by-frame during capture. This is the same mechanism HyperFrames uses for GSAP, Lottie, Three.js, and CSS animations — the adapter converts HyperFrames' time-based seeks into Remotion's frame-based seeks.

HyperFrames capture engine
  │
  ├─ GSAP adapter     → timeline.seek(time)
  ├─ Lottie adapter   → anim.goToAndStop(time)
  ├─ Remotion adapter  → player.seekTo(frame)  ← new
  └─ ...

Step 1: Write your Remotion component

Write a standard Remotion composition. It uses useCurrentFrame, interpolate, spring, Sequence, AbsoluteFill — all the real @remotion/core APIs. This component works in both Remotion's renderer and HyperFrames.

// remotion-src/MyComposition.tsx
import React from "react";
import { useCurrentFrame, useVideoConfig, AbsoluteFill, interpolate, spring, Sequence } from "remotion";

const TitleCard: React.FC = () => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const scale = spring({ frame, fps, config: { damping: 12 } });
  const opacity = interpolate(frame, [0, 15], [0, 1], { extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
      <div style={{ fontSize: 72, fontWeight: 800, color: "#fff", transform: `scale(${scale})`, opacity }}>
        Hello from Remotion
      </div>
    </AbsoluteFill>
  );
};

export const MyComposition: React.FC = () => (
  <AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>
    <Sequence from={0} durationInFrames={90}>
      <TitleCard />
    </Sequence>
  </AbsoluteFill>
);

Step 2: Create the browser entry point

This file mounts the Remotion Player and registers it with HyperFrames.

// remotion-src/entry.tsx
import React, { useRef, useEffect } from "react";
import { createRoot } from "react-dom/client";
import { Player, type PlayerRef } from "@remotion/player";
import { MyComposition } from "./MyComposition";

const FPS = 30;
const DURATION_IN_FRAMES = 90; // 3 seconds

function App() {
  const playerRef = useRef<PlayerRef>(null);

  useEffect(() => {
    // Pause on mount — HyperFrames drives the timeline
    playerRef.current?.pause();

    // Register with HyperFrames' Remotion adapter
    window.__hfRemotion = window.__hfRemotion || [];
    window.__hfRemotion.push({
      seekTo: (frame: number) => playerRef.current?.seekTo(frame),
      pause: () => playerRef.current?.pause(),
      durationInFrames: DURATION_IN_FRAMES,
      fps: FPS,
    });
  }, []);

  return (
    <Player
      ref={playerRef}
      component={MyComposition}
      durationInFrames={DURATION_IN_FRAMES}
      compositionWidth={1920}
      compositionHeight={1080}
      fps={FPS}
      style={{ width: "100%", height: "100%" }}
      controls={false}
      autoPlay={false}
      loop={false}
      clickToPlay={false}
    />
  );
}

const root = createRoot(document.getElementById("remotion-root")!);
root.render(<App />);

Step 3: Bundle for the browser

npx esbuild remotion-src/entry.tsx --bundle --outfile=dist/bundle.js \
  --format=iife --platform=browser --target=es2020 \
  --jsx=automatic --minify \
  --define:process.env.NODE_ENV='"production"'

This produces a single JS file containing React, Remotion Player, and your composition.

Step 4: Use in HyperFrames HTML

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Video</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js"></script>
    <style>
      body, html { margin: 0; padding: 0; width: 1920px; height: 1080px; overflow: hidden; }
    </style>
  </head>
  <body>
    <div
      id="main-canvas"
      data-composition-id="my-video"
      data-width="1920"
      data-height="1080"
      data-duration="3"
    >
      <!-- Track 0: GSAP background (native HyperFrames) -->
      <div id="bg" class="clip" data-start="0" data-duration="3" data-track-index="0"
           style="position:absolute;inset:0;background:#0a0a0a;">
      </div>

      <!-- Track 1: Remotion composition -->
      <div id="remotion-layer" class="clip" data-start="0" data-duration="3" data-track-index="1"
           style="position:absolute;inset:0;">
        <div id="remotion-root" style="width:1920px;height:1080px;"></div>
      </div>

      <!-- Track 2: GSAP text overlay (native HyperFrames) -->
      <div id="overlay" class="clip" data-start="0" data-duration="3" data-track-index="2"
           style="position:absolute;bottom:40px;width:1920px;text-align:center;">
        <div id="overlay-inner" style="opacity:0;">
          <span style="font-family:monospace;font-size:16px;color:rgba(255,255,255,0.3);">
            REMOTION + GSAP + HYPERFRAMES
          </span>
        </div>
      </div>

      <script>
        const tl = gsap.timeline({ paused: true });
        tl.to('#overlay-inner', { opacity: 1, duration: 1, ease: 'power2.out' }, 0.5);
        window.__timelines = window.__timelines || {};
        window.__timelines['my-video'] = tl;
      </script>

      <!-- Load the bundled Remotion composition -->
      <script src="dist/bundle.js"></script>
    </div>
  </body>
</html>

Step 5: Render

npx hyperframes lint
npx hyperframes render --fps 30

Mixing GSAP and Remotion

GSAP and Remotion layers coexist in the same composition. HyperFrames seeks both adapters in sync on every frame:

  • Use GSAP for backgrounds, overlays, captions, motion graphics
  • Use Remotion for complex procedural animations, data-driven content, anything that benefits from React's component model
  • Use both in the same frame — they render independently on separate tracks

Using HyperFrames compositions in Remotion

You can embed a HyperFrames HTML composition inside a Remotion project using an iframe.

How it works

HyperFrames' runtime listens for postMessage control messages (this is how the HyperFrames studio works). A Remotion component can load a HyperFrames composition in an iframe and seek it by posting messages on each frame.

The Remotion component

// src/HyperFramesLayer.tsx
import React, { useRef, useEffect, useCallback } from "react";
import { useCurrentFrame, useVideoConfig, AbsoluteFill } from "remotion";

interface HyperFramesLayerProps {
  /** URL serving the HyperFrames composition (e.g., http://localhost:3002) */
  src: string;
  /** Width of the HyperFrames composition */
  width?: number;
  /** Height of the HyperFrames composition */
  height?: number;
}

export const HyperFramesLayer: React.FC<HyperFramesLayerProps> = ({
  src,
  width = 1920,
  height = 1080,
}) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const iframeRef = useRef<HTMLIFrameElement>(null);

  // Seek the HyperFrames composition to the current frame
  useEffect(() => {
    const iframe = iframeRef.current;
    if (!iframe?.contentWindow) return;

    iframe.contentWindow.postMessage(
      {
        source: "hf-parent",
        type: "control",
        action: "seek",
        frame,
        seekMode: "commit",
      },
      "*",
    );
  }, [frame]);

  // Pause on mount
  useEffect(() => {
    const iframe = iframeRef.current;
    if (!iframe?.contentWindow) return;

    const onLoad = () => {
      iframe.contentWindow!.postMessage(
        { source: "hf-parent", type: "control", action: "pause" },
        "*",
      );
    };
    iframe.addEventListener("load", onLoad);
    return () => iframe.removeEventListener("load", onLoad);
  }, []);

  return (
    <AbsoluteFill>
      <iframe
        ref={iframeRef}
        src={src}
        width={width}
        height={height}
        style={{
          border: "none",
          width: "100%",
          height: "100%",
        }}
      />
    </AbsoluteFill>
  );
};

Usage in a Remotion composition

// src/Root.tsx
import { Composition } from "remotion";
import { HyperFramesLayer } from "./HyperFramesLayer";

// 1. Start the HyperFrames preview server:
//    npx hyperframes preview my-hf-project --port 3002

// 2. Use it in your Remotion composition:
export const MyVideo: React.FC = () => (
  <HyperFramesLayer src="http://localhost:3002" />
);

export const Root: React.FC = () => (
  <Composition
    id="MyVideo"
    component={MyVideo}
    durationInFrames={150}
    fps={30}
    width={1920}
    height={1080}
  />
);

Workflow

# Terminal 1: Start HyperFrames preview
npx hyperframes preview my-hf-project --port 3002

# Terminal 2: Start Remotion studio
npx remotion studio

Note: For Remotion's server-side rendering (npx remotion render), the iframe approach requires the HyperFrames preview server to be running. For production use, consider converting HyperFrames compositions to Remotion components instead.


The adapter registration contract

The entire bridge between Remotion and HyperFrames is this interface:

interface RemotionInstance {
  seekTo: (frame: number) => void;
  pause: () => void;
  durationInFrames: number;
  fps: number;
}

// Register in your browser script:
window.__hfRemotion = window.__hfRemotion || [];
window.__hfRemotion.push(instance);

HyperFrames' runtime adapter discovers these instances and calls seekTo(frame) during capture. That's the entire protocol.

Multiple Remotion compositions

You can mount multiple Remotion compositions in the same HyperFrames project. Each one registers independently:

<div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="1">
  <div id="remotion-root-a" style="width:1920px;height:1080px;"></div>
</div>
<div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="1">
  <div id="remotion-root-b" style="width:1920px;height:1080px;"></div>
</div>

Each bundle registers its own __hfRemotion entry. The adapter seeks all instances in sync.


When to use which

Scenario Use
New project, simple animations HyperFrames (HTML + GSAP)
Complex procedural/data-driven animation Remotion (React)
Existing Remotion project, want HyperFrames rendering Remotion adapter (this guide)
Existing HyperFrames project, want to add React components Remotion adapter (this guide)
Captions, overlays on top of Remotion content GSAP layers + Remotion layer in same HyperFrames composition
Gradual migration from Remotion Start with adapter, rewrite scenes one at a time

Project structure

A typical hybrid project:

my-video/
  index.html              ← HyperFrames composition (orchestration)
  compositions/
    captions.html          ← Native HyperFrames captions
  remotion-src/
    MyComposition.tsx      ← Remotion component
    entry.tsx              ← Browser entry point
    package.json           ← Remotion + React deps
  dist/
    bundle.js              ← Bundled Remotion (generated)
  assets/
    audio.mp3

HyperFrames handles orchestration, captions, backgrounds, and rendering. Remotion handles complex animated scenes. Both render in the same video.