how-to-guide

How to Leverage HyperFrames for Browser-Native Animation Overlays in video-use

July 8, 2026 browser-use/video-use ↗

HyperFrames slots in video-use let you author HTML/CSS/GSAP animations in the browser, render them as standalone video files with alpha channels, and composite them onto your edit via FFmpeg's filtergraph.

The video-use repository treats every animation engine as a plug-in that produces short video clips for compositing. When you leverage HyperFrames for browser-native animation overlays, you get full CSS layout capabilities, responsive sizing, and GSAP's timeline engine running entirely in the browser, with outputs that integrate seamlessly into the FFmpeg-based rendering pipeline.

Understanding the HyperFrames Architecture

In video-use, animation slots are directories under edit/animations/slot_<id>/. According to the repository's SKILL.md, marking a slot as a HyperFrames slot invokes the HyperFrames CLI with npx --yes hyperframes inside this directory. This architecture isolates the heavy-weight rendering step from the rest of the pipeline, allowing helpers/render.py to treat the output like any other overlay source.

Because HyperFrames runs entirely in the browser, the generated overlay is a true browser-native animation. You can use any CSS feature, responsive media queries, or GSAP easing, and the result is encoded to a lossless video (or WebM with an alpha channel) that FFmpeg composites over your base footage.

Creating a HyperFrames Slot

To scaffold a new animation slot, create the directory structure and initialize the HyperFrames project:


# Inside the edit directory of your video-use session

mkdir -p edit/animations/slot_01
cd edit/animations/slot_01
npx --yes hyperframes init . --example blank --non-interactive --skip-skills

This creates the working environment where you will author your HTML/CSS/GSAP composition. The repository's install.md notes that Node.js 22+ is required, and HyperFrames is installed lazily on first use.

Authoring Browser-Native Animations

Inside the slot directory, write a regular HTML/CSS/GSAP composition—the same files you would use for a web page. Because HyperFrames runs in the browser, you get deterministic rendering of complex web animations.

Here is an example index.html that creates a sliding box animation:

<!DOCTYPE html>
<html>
<head>
  <style>
    body {margin:0;overflow:hidden;background:transparent;}
    #box {width:200px;height:200px;background:#0a84ff;position:absolute;top:50%;left:-250px;}
  </style>
</head>
<body>
  <div id="box"></div>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3"></script>
  <script>
    gsap.to("#box", {duration:2, x:300, ease:"power2.out"});
  </script>
</body>
</html>

This approach supports UI motion (e.g., product-demo widgets), kinetic typography synchronized to speech, and transparent WebM outputs for mockups that sit on top of live-action footage.

Validating and Rendering Overlays

Before compositing, validate the animation to ensure deterministic, frame-accurate output. The HyperFrames CLI provides linting and validation commands:

npx --yes hyperframes lint .
npx --yes hyperframes validate .

These checks guarantee that the HTML/CSS/JS can be rendered deterministically, which is crucial for frame-accurate overlay generation in the video-use pipeline.

Render the final output as a standalone video file:


# For standard overlays

npx --yes hyperframes render . -o render.mp4

# For alpha channel transparency

npx --yes hyperframes render . -o overlay.webm --format webm

The output file is a stand-alone video that contains the animation exactly as it should appear in the final edit.

Compositing with FFmpeg in render.py

The helpers/render.py file reads the project's edl.json and processes any entry containing an "overlays" array. For each overlay entry, the helper applies a PTS-shift (setpts=PTS-STARTPTS+T/TB) so that frame 0 of the rendered HyperFrames video aligns with the start time defined in the overlay window.

Add the overlay to your edl.json:

{
  "overlays": [
    {
      "file": "edit/animations/slot_01/overlay.webm",
      "start": 12.0,
      "duration": 4.5,
      "layer": 1
    }
  ]
}

Run the final render:

python -m helpers.render edl.json -o final.mp4

The overlay is composited before subtitles are added, as render.py enforces subtitles as the last filter per the hard rule in the video-use pipeline. This ensures your browser-native animation sits correctly between the base video and any text layers.

Summary

  • HyperFrames slots live in edit/animations/slot_<id>/ and are initialized via the HyperFrames CLI.
  • Authoring uses standard HTML/CSS/GSAP with full browser capabilities, including responsive design and complex easing.
  • Validation via hyperframes lint and hyperframes validate ensures deterministic rendering for frame-accurate overlays.
  • Rendering produces standalone MP4 or WebM files (with alpha channel support) that serve as compositing sources.
  • Integration happens in helpers/render.py, which applies PTS-shifting to synchronize overlays with the timeline and composites them via FFmpeg before subtitle generation.

Frequently Asked Questions

What video format should I use for transparent overlays?

Use WebM with alpha channel. When rendering with HyperFrames, specify --format webm to generate a file that supports transparency, allowing the overlay to sit on top of live-action footage without a background color.

How does video-use synchronize HyperFrames animations with the timeline?

The render.py helper applies a PTS-shift using the FFmpeg expression setpts=PTS-STARTPTS+T/TB. This shifts the presentation timestamp of the overlay video so that its first frame aligns with the start time defined in the edl.json overlay entry.

Can I use responsive CSS media queries in HyperFrames animations?

Yes. Because HyperFrames runs entirely in the browser, you have access to the full CSS feature set, including responsive media queries, CSS Grid, Flexbox, and modern JavaScript APIs. The browser-native rendering captures the exact visual output as a video file.

Where does the final compositing happen in the video-use pipeline?

The final compositing occurs in helpers/render.py, which builds an FFmpeg filtergraph. Overlays are processed according to the "overlays" array in edl.json, composited over the base video, and subtitles are always added as the final filter step.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →