how-to-guide

How to Integrate HyperFrames for HTML/CSS/GSAP Motion Graphics Overlays in video-use

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

HyperFrames integrates with video-use through slot-based animation directories that render HTML/CSS/GSAP compositions into video overlays via the EDL pipeline.

The video-use repository treats animation overlays as independent assets rendered outside the core editing pipeline. HyperFrames serves as the recommended engine when authoring web-based compositions using HTML, CSS, and GSAP, with final renders composited onto video through the JSON-based Edit Decision List (EDL).

Prerequisites: Node.js Setup

HyperFrames requires Node.js 22+ and npm, but only when actively working with animation slots. According to the installation guide in install.md at line 159, these dependencies are not required for the core video-use pipeline—only when creating or rendering HyperFrames slots.

Verify your environment before initializing any slots:

node --version  # Must be 22 or higher

npm --version

Creating the Animation Slot

Each HyperFrames animation lives in an isolated slot directory under edit/animations/. This slot-based architecture keeps the main repository untouched and enables parallel development across multiple animations, as specified in Hard Rule 10 of SKILL.md at line 31.

Create a new slot for your motion graphics:

mkdir -p edit/animations/slot_hf01
cd edit/animations/slot_hf01

The slot_<id> naming convention (e.g., slot_hf01, slot_hf02) organizes assets locally while maintaining clean separation from the core editing logic.

Scaffolding a HyperFrames Project

Initialize the HyperFrames project within the slot directory using the hyperframes init command. As documented in SKILL.md at lines 210-212, this scaffolds the required configuration files and installs dependencies.

Run the initialization non-interactively:

npx --yes hyperframes init . \
    --example blank \
    --non-interactive \
    --skip-skills

This command generates:

  • index.html: Starter HTML composition
  • hyperframes.json: Configuration file for render settings
  • node_modules/: Required npm packages for GSAP and rendering

Developing HTML/CSS/GSAP Motion Graphics

Edit index.html inside the slot directory to create your motion graphics using standard web technologies. The page runs headless in Chromium during render, supporting any web-compatible animation.

Example GSAP animation in edit/animations/slot_hf01/index.html:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    body { margin:0; background:#0a0a0a; overflow:hidden; }
    #box { width:200px; height:200px; background:#ff5a00; }
  </style>
</head>
<body>
  <div id="box"></div>

  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.2/dist/gsap.min.js"></script>
  <script>
    // Animate the box from left to right over 5 seconds
    gsap.to("#box", { x: 1500, duration: 5, ease: "power2.out" });
  </script>
</body>
</html>

Validation and Rendering

Before final output, validate the composition for errors and render to a video file. HyperFrames provides lint and validate commands for quality checks.

Validate the project:

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

Render to video format based on transparency needs:

  • MP4: For opaque overlays with background
  • WebM: For alpha-transparent overlays

# Opaque overlay

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

# Transparent overlay (alpha channel)

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

The rendered file remains in the slot directory (edit/animations/slot_hf01/render.mp4) for EDL referencing.

Referencing Overlays in the EDL

Add the rendered animation to edit/edl.json to composite it onto the final video. The EDL entry specifies the file path and timing relative to the output timeline.

As implemented in SKILL.md at line 24, video-use automatically applies the setpts=PTS-STARTPTS+T/TB time shift required for correct overlay synchronization.

Example EDL entry:

{
  "overlays": [
    {
      "file": "edit/animations/slot_hf01/render.mp4",
      "start_in_output": 12.0,
      "duration": 5.0
    }
  ]
}

Running the Final Render Pipeline

Execute helpers/render.py to process the EDL, concatenate source segments, and composite HyperFrames overlays. The script handles the setpts timing adjustments automatically and burns subtitles as the final step per the pipeline hard rules.

python helpers/render.py edit/edl.json -o final.mp4

The render pipeline extracts each source segment, applies the HyperFrames overlay at the specified timestamp, and outputs the final composite video.

Summary

  • Slot-based architecture: Create isolated directories under edit/animations/slot_<id>/ for each HyperFrames project
  • Web-native authoring: Develop motion graphics using standard HTML, CSS, and GSAP in index.html
  • Headless rendering: Use hyperframes render to generate MP4 (opaque) or WebM (transparent) video files
  • EDL integration: Reference rendered files in edit/edl.json with precise timing; video-use handles automatic setpts synchronization via helpers/render.py
  • Parallel development: Multiple animation slots can be developed simultaneously without touching the main repository

Frequently Asked Questions

What Node.js version is required for HyperFrames integration?

Node.js 22 or higher is required, along with npm. According to install.md at line 159, these dependencies are only necessary when creating or rendering HyperFrames slots, not for the core video-use editing pipeline.

How do I create transparent overlays with HyperFrames?

Use the --format webm flag when rendering to preserve the alpha channel. Standard MP4 output encodes opaque backgrounds, while WebM format maintains transparency for overlay compositing.

Where does the final video compositing happen?

The helpers/render.py script consumes edit/edl.json and handles all compositing. It reads overlay entries, applies the required setpts=PTS-STARTPTS+T/TB timing shift documented in SKILL.md at line 24, and renders the final output sequence.

Can I develop multiple HyperFrames animations simultaneously?

Yes. The slot-based architecture (edit/animations/slot_<id>/) supports parallel development across multiple subdirectories. As noted in Hard Rule 10 of SKILL.md at line 31, this design allows multiple animations to be built in parallel without repository conflicts.

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 →