DOCSEARCHbyAlgolia
Submit Docs

HyperFrames Framework

repository·main·Indexed 12 days ago

https://github.com/heygen-com/hyperframes

A framework for converting web technologies (HTML, CSS, animations) into deterministic MP4 videos, optimized for AI coding agents and automated workflows. Includes a CLI for rendering and linting, a core library for parsing and generating compositions, and an AWS Lambda SDK (@hyperframes/aws-lambda) for distributed rendering via Step Functions and S3.

Tokens
568.9K
Snippets
1.5K
Records
2.2K
Agent score
98%

What's inside HyperFrames

  1. Overview of the Apple Terminal Basic block

    main

    The code-snippet-apple-terminal-basic is a pre-built visual block that recreates a macOS Terminal.app session.

    Key Features:

    • Visual Style: White background, black text, and macOS window chrome (traffic light buttons and centered title bar).
    • Animations: Uses GSAP for per-character typing of shell commands and sequential revealing of output lines.
    • Cursor Behavior: Includes a solid cursor that blinks three times at the end of the sequence before holding steady.
    • Self-contained: The block is a single HTML file that relies only on the GSAP CDN for animations.

  2. Overview of @hyperframes/gcp-cloud-run

    main

    The @hyperframes/gcp-cloud-run package is a Google Cloud Platform (GCP) adapter for HyperFrames distributed rendering. It provides the orchestration and storage glue to run OSS render primitives (plan → renderChunk × N → assemble) on Google Cloud using Cloud Run and Cloud Workflows.

    It provides two main surfaces:

    1. Server-side handler (./server): A Cloud Run HTTP service that dispatches rendering actions (plan, renderChunk, or assemble) based on the request body's Action field. It manages the bridge between Google Cloud Storage (GCS) and the container's local filesystem.
    2. Client-side SDK (./sdk): A Node.js-compatible SDK used to drive the deployed stack. It includes methods for triggering renders, checking progress, and managing deployments without manual GCS or Workflows boilerplate.

    Note: This package is not a dependency of @hyperframes/producer; you must install it separately.

  3. Overview of @hyperframes/studio features

    main

    @hyperframes/studio is a React-based composition editor that provides a visual interface for building video compositions. Key features include:

    • Visual timeline: Allows you to drag, resize, and arrange elements on tracks.
    • Code editor: Powered by CodeMirror, it supports editing HTML and GSAP scripts with syntax highlighting and autocomplete.
    • Live preview: Enables real-time visualization of changes during the editing process.
    • Composition inspector: Provides a way to view and modify specific element properties.

  4. Overview of the ui-focus-zoom component

    main

    The ui-focus-zoom component is a specialized UI primitive designed for cinematic app surface transitions. It establishes a full app surface, then uses a camera to zoom and pan to a specific anchored region on cue, holding that state.

    Key characteristics:

    • Camera Motion: Uses a single world wrapper transform (translate(x, y) scale(S)). Pan is clamped to ensure the scaled world always covers the viewport.
    • Motion Envelope: Features a 0.9s entrance (settle), a camera move lasting 1.1s (clamped by zoom_at), an optional soft halo bloom, and an elastic hold with micro-drift that ends in absolute stillness.
    • Elasticity: The root is sized by the host clip using cqmin units and does not rely on fixed data-width or data-height.
    • Timeline: The timeline is registered at window.__timelines["ui-focus-zoom"].

  5. Overview of Hyperframes CLI commands

    main

    The Hyperframes CLI is categorized by the task you want to accomplish:

    TaskCommands
    Start a projectinit, add, catalog
    Bring in source materialcapture, transcribe, tts, remove-background, media-treatment, beats
    Preview or sharepreview, present, play, publish
    Find problemslint, check, snapshot, keyframes, compare, grade-compare
    Create a filerender, benchmark
    Render to cloudcloud, lambda, cloudrun
    Fix setupdoctor, browser, upgrade, docs, info, compositions
    Connect toolsauth, skills, figma, telemetry, feedback

    Note: validate, inspect, and layout are deprecated. Use check instead.

  6. What is HyperFrames?

    main

    HyperFrames is an open-source framework designed to turn HTML into video. The workflow follows a three-step pattern:

    1. Request: You describe the video you want.
    2. Build: An AI agent builds an editable project consisting of HTML, CSS, and JavaScript.
    3. Play/Render: The HyperFrames engine plays or renders the project into a video.

    Key characteristics:

    • Agent-built: The AI agent handles the code generation (HTML/CSS/JS) based on your description.
    • Editable: Outputs are structured project folders rather than flattened video files, allowing for manual or agentic edits using Studio or other developer tools.
    • Reliable render: Instead of relying on real-time playback (which can cause dropped frames on slow hardware), HyperFrames requests each exact frame from the project to ensure a consistent final render.

  7. Overview of @hyperframes/core modules

    main

    The @hyperframes/core package provides the fundamental building blocks for the Hyperframes video framework, including:

    • Types: Definitions for TimelineElement, CompositionSpec, Asset, canvas dimensions, and defaults.
    • Parsers: Tools like parseHtml (extracts timeline elements from HTML) and parseGsapScript (parses GSAP animations).
    • Generators: Tools like generateHyperframesHtml (produces valid Hyperframes HTML from a composition spec).
    • Compiler: Utilities like compileTimingAttrs to resolve data-start and data-duration into absolute times.
    • Linter: Validation tools like lintHyperframeHtml to check for missing attributes or overlapping tracks.
    • Runtime: An IIFE script injected into the browser that manages seeking, media playback, and the window.__hf protocol.
    • Frame Adapters: Pluggable drivers for animation runtimes (GSAP, Lottie, CSS, etc.).

  8. Quick Reference for Faceless Explainer Workflow

    main

    The faceless-explainer skill is a specialized workflow for creating synthetic explainer videos. Unlike captured-asset workflows, it relies on synthetic assets (typography, abstract graphics, diagrams, data-viz) rather than real-world footage.

    Supported Formats

    Formats are derived from the destination and must be set once in the STORYBOARD.md frontmatter:

    • Landscape: 1920x1080
    • Portrait: 1080x1920
    • Square: 1080x1080

    Workflow Differences

    • No Capture Step: Uses synthetic tokens.json and visible-text.txt instead of Step 1 capture.
    • No Asset Staging: Does not use asset-descriptions.md or capture/assets/. The asset_candidates field is empty by default.
    • Visual Generation: Every visual is invented by Step 5 workers (typography, abstract graphics, diagrams, data-viz).
    • User Assets: The only real asset path allowed is a user-supplied image in public/<basename>.

    Available Background Scripts

    These scripts are located under scripts/ and supplement the hyperframes CLI:

    • build-frame: Adopts and brand-remixes a frame preset into frame.md (includes caption skin).
    • audio: Handles TTS, transcription, BGM, SFX, and duration syncing.
    • captions: Manages captioning.
    • transitions: Injects and verifies transitions.
    • assemble-index: Final assembly step.

  9. Features of the Apple Terminal Man Page snippet

    main

    The code-snippet-apple-terminal-man-page block provides a high-fidelity macOS Terminal.app recreation with the following characteristics:

    • Visual Style: Pale yellow background with black text, mimicking the Man Page profile.
    • Window Chrome: Includes macOS-style traffic light buttons (close, minimize, fullscreen) and a centered title bar.
    • Animations:
      • Per-character typing animation using GSAP for the shell command.
      • Sequential reveal of output lines after the command execution.
      • Blinking cursor effect at the end of the sequence.
    • Dependencies: Self-contained HTML that relies only on the GSAP CDN.

  10. What @hyperframes/engine does

    main

    The engine is a seekable web-page-to-video rendering engine. It works by opening an HTML composition in a headless Chrome instance, seeking frame-by-frame using Chrome's HeadlessExperimental.beginFrame API, capturing screenshots, and encoding them into video using FFmpeg.

    It is framework-agnostic and supports any web content (GSAP, Lottie, Three.js, CSS animations) that implements the window.__hf seek protocol.

  11. Understand the stitched-text-draw component

    main

    The stitched-text-draw component is a visual effect where text is rendered as if being sewn with thread. Letters are drawn stroke-by-stroke with a leading 'needle dot' and trailing 'needle-hole dots' at stitch boundaries. The animation includes a 'thread-tail' overshoot that retracts as the stroke finishes, simulating thread being pulled snug.

    Key characteristics:

    • Alphabet: Supports A-Z, 0-9, and spaces. Other characters are rendered as spaces.
    • Character Limit: Clamped to a maximum of 12 characters.
    • Animation Style: Uses a backOut ease for per-stroke movement, creating a ~10% overshoot. It features an elastic HOLD at the end of the animation.
    • Rendering Logic: Uses stroke-dashoffset for the reveal mechanic rather than SVG masks to ensure reliable repainting during timeline seeks.

  12. Features of the Apple Terminal Grass snippet

    main

    The code-snippet-apple-terminal-grass block provides a high-fidelity macOS Terminal.app simulation with the following characteristics:

    • Visual Style: Faithful recreation of the 'Grass' profile (black background with #00C100 green text).
    • Window Chrome: Includes macOS-style window decorations, including a title bar and traffic light buttons (close, minimize, fullscreen).
    • Animations:
      • Per-character typing animation using GSAP.
      • Sequential reveal of output lines after the command execution.
      • A blinking cursor that blinks three times before holding steady.
    • Dependencies: Self-contained HTML that only requires the GSAP CDN.