mirror of https://github.com/heygen-com/hyperframes.git synced 2026-11-14 21:29:34 +00:00

Files

T

Vance IngallsandClaude Opus 4.6 9f8e5ba5a1 initial code (#2 )

* feat: initial code port from hyperframes-internal

Port all OSS-ready packages from the internal monorepo:
- @hyperframes/core — shared types, HTML generation, GSAP utilities, runtime
- @hyperframes/cli — CLI for creating, previewing, and rendering compositions
- @hyperframes/engine — framework-agnostic rendering engine (BeginFrame + FFmpeg)
- @hyperframes/producer — video rendering pipeline (Puppeteer + FFmpeg)
- @hyperframes/ui-player — browser-based video player component
- @hyperframes/studio — composition editor (React frontend + Hono backend)

Includes regression test suite with Docker-based test harness.

All HeyGen-internal references, deployment infrastructure, and
proprietary assets have been removed. Package names migrated
from @app/* to @hyperframes/*.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: scrub internal codenames and stale references from OSS port

- Replace static.heygen.ai runtime URLs in test fixtures
- Remove internal CDN publish script (publish-hyperframe-runtime.ts)
- Replace sandbox-studio, sandbox-interceptor, __magicEditRuntime
  with neutral names (studio, hyperframe-runtime, __hyperframeRuntime)
- Fix stale Vault API / localhost references in docs
- Remove broken deprecated_studio link

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: remove remaining internal codenames and stale references

- Delete stale producer README.md and PIPELINE.md (referenced nonexistent files)
- Replace "Cerberus" codename with "HyperFrames" in test design reviews
- Replace magic-edit postMessage identifiers with hf-preview/hf-parent
- Rename debug-magic-edit-timeline.ts to debug-timeline.ts
- Replace "Motion Cut" with "HyperFrames" in Timeline comments
- Fix studio/CLI references to nonexistent archive package
  (use local data/projects/ dir, stub render proxy)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-21 22:43:56 -07:00

docs

initial code (#2 )

2026-03-21 22:43:56 -07:00

scripts

initial code (#2 )

2026-03-21 22:43:56 -07:00

src

initial code (#2 )

2026-03-21 22:43:56 -07:00

package.json

initial code (#2 )

2026-03-21 22:43:56 -07:00

README.md

initial code (#2 )

2026-03-21 22:43:56 -07:00

tsconfig.json

initial code (#2 )

2026-03-21 22:43:56 -07:00

vitest.config.ts

initial code (#2 )

2026-03-21 22:43:56 -07:00

README.md

HyperFrames Core

Create videos by writing HTML. The HTML is the source of truth - timing, layout, content. Scripts define how clips animate.

HyperFrames Core is the foundational library for video composition. It defines the data attributes and HTML structure that represent video timelines, with GSAP animations to bring clips to life.

Frame adapter direction:

../FRAME.md - repository-level frame model and deterministic renderer direction
adapters/README.md - adapter contract and contribution guide

Philosophy

HTML = Scene description (content, timing, layout)
CSS  = Styling
JS   = GSAP animations (motion)

Every element in the video timeline is represented as an HTML element with data attributes that define its position in time.

Documentation

Schema

The specification for valid HyperFrames HTML:

schema.md - Element types, data attributes, HTML patterns

Guides

For AI agents and developers working with HyperFrames:

Document	Description
Cheat Sheet	Quick reference for common actions
Position Guide	Natural language → position mappings
Text Style Guide	Natural language → text style mappings
Motion Design Guide	Creating and editing motion designs
Caption Guide	Adding captions to videos

Quick Start

Using the Editor (Recommended)

pnpm install
pnpm dev

This starts the studio dev server.

Writing Compositions Manually

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
    <style>
      * {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      html,
      body {
        width: 100%;
        height: 100%;
        overflow: hidden;
        background: #000;
      }
      #stage {
        position: relative;
        width: 1920px;
        height: 1080px;
        overflow: hidden;
      }
    </style>
  </head>
  <body>
    <div id="stage">
      <video id="el-1" data-start="0" data-end="10" src="video.mp4" muted playsinline></video>
      <div id="el-2" data-start="2" data-end="6" data-type="text">
        <div>Hello World</div>
      </div>
    </div>
    <script>
      const tl = gsap.timeline({ paused: true });
      // Add animations...
    </script>
  </body>
</html>

Element Types

Type	HTML Tag	Purpose
video	`<video>`	Video clips
image	`<img>`	Static images
text	`<div data-type="text">`	Text overlays
audio	`<audio>`	Music, sound effects
composition	`<div data-type="composition">`	Motion designs

Data Attributes

Attribute	Purpose	Required
`data-start`	When element appears (seconds)	Yes
`data-end`	When element disappears (seconds)	No
`data-name`	Display name in UI	No
`data-layer`	Z-index for stacking	No

See schema.md for the complete reference.

Remember: HTML is the storyboard. CSS is the art direction. JS is just for motion.