mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
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>
This commit is contained in:
Vance Ingalls
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
10621e7903
commit
9f8e5ba5a1
@@ -0,0 +1,26 @@
|
||||
# Compositions
|
||||
|
||||
A composition is an HTML document that defines a video timeline.
|
||||
|
||||
## Structure
|
||||
Every composition needs a root element with `data-composition-id`:
|
||||
```html
|
||||
<div id="root" data-composition-id="root" data-width="1920" data-height="1080">
|
||||
<!-- Elements go here -->
|
||||
</div>
|
||||
```
|
||||
|
||||
## Nested Compositions
|
||||
Embed one composition inside another:
|
||||
```html
|
||||
<div data-composition-src="./intro.html" data-start="0" data-duration="5"></div>
|
||||
```
|
||||
|
||||
## Listing Compositions
|
||||
Use `npx hyperframes compositions` to see all compositions in a project.
|
||||
|
||||
## Variables
|
||||
Compositions can expose variables for dynamic content:
|
||||
```html
|
||||
<div data-composition-id="card" data-var-title="string" data-var-color="color">
|
||||
```
|
||||
@@ -0,0 +1,22 @@
|
||||
# Data Attributes
|
||||
|
||||
Core attributes for controlling element timing and behavior.
|
||||
|
||||
## Timing
|
||||
- `data-start="0"` — Start time in seconds
|
||||
- `data-duration="5"` — Duration in seconds
|
||||
- `data-track-index="0"` — Timeline track number (controls z-ordering)
|
||||
|
||||
## Media
|
||||
- `data-media-start="2"` — Media playback offset / trim point (seconds)
|
||||
- `data-volume="0.8"` — Audio/video volume, 0 to 1
|
||||
- `data-has-audio="true"` — Indicates video has an audio track
|
||||
|
||||
## Composition
|
||||
- `data-composition-id="root"` — Unique ID for composition wrapper (required)
|
||||
- `data-width="1920"` — Composition width in pixels
|
||||
- `data-height="1080"` — Composition height in pixels
|
||||
- `data-composition-src="./intro.html"` — Nested composition source
|
||||
|
||||
## Element Visibility
|
||||
Add `class="clip"` to timed elements so the runtime can manage their visibility lifecycle.
|
||||
@@ -0,0 +1,23 @@
|
||||
# GSAP Animation
|
||||
|
||||
HyperFrames uses GSAP for animation. Timelines are paused and controlled by the runtime.
|
||||
|
||||
## Setup
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
|
||||
<script>
|
||||
const tl = gsap.timeline({ paused: true });
|
||||
tl.to("#title", { opacity: 1, duration: 0.5 }, 0);
|
||||
window.__timelines = window.__timelines || {};
|
||||
window.__timelines["root"] = tl;
|
||||
</script>
|
||||
```
|
||||
|
||||
## Key Rules
|
||||
- Always create timelines with `{ paused: true }`
|
||||
- Register timelines on `window.__timelines` with the composition ID as key
|
||||
- Position parameter (3rd arg) sets absolute time: `tl.to(el, vars, 1.5)`
|
||||
- Supported methods: `set`, `to`, `from`, `fromTo`
|
||||
|
||||
## Supported Properties
|
||||
opacity, x, y, scale, scaleX, scaleY, rotation, width, height, visibility
|
||||
@@ -0,0 +1,23 @@
|
||||
# Rendering
|
||||
|
||||
Render compositions to MP4 with `npx hyperframes render`.
|
||||
|
||||
## Local Mode (default)
|
||||
Uses Puppeteer (bundled Chromium) + system FFmpeg. Fast for iteration.
|
||||
Requires: FFmpeg installed (`brew install ffmpeg` or `apt install ffmpeg`).
|
||||
|
||||
## Docker Mode (--docker)
|
||||
Deterministic output with exact Chrome version and fonts. For production.
|
||||
Requires: Docker installed and running.
|
||||
|
||||
## Options
|
||||
- `-f, --fps` — 24, 30, or 60 (default: 30)
|
||||
- `-q, --quality` — draft, standard, high (default: standard)
|
||||
- `-w, --workers` — Parallel workers 1-8 (default: auto)
|
||||
- `--gpu` — Use GPU encoding (NVENC, VideoToolbox, VAAPI)
|
||||
- `-o, --output` — Custom output path
|
||||
|
||||
## Tips
|
||||
- Use `draft` quality for fast previews during development
|
||||
- Use `npx hyperframes benchmark` to find optimal settings
|
||||
- 4 workers is usually the sweet spot for most compositions
|
||||
@@ -0,0 +1,15 @@
|
||||
# Templates
|
||||
|
||||
Built-in templates available via `npx hyperframes init --template <name>`.
|
||||
|
||||
## blank
|
||||
Empty 1920x1080 composition with GSAP timeline wired up. Start from scratch.
|
||||
|
||||
## title-card
|
||||
Animated title and subtitle with GSAP fade-in/out. Good for intro cards.
|
||||
|
||||
## video-edit
|
||||
Video element with trimming, audio, and track controls. Starting point for video editing.
|
||||
|
||||
## Custom Templates
|
||||
Any directory with an `index.html` can serve as a template. Copy it manually or build your own init workflow.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Troubleshooting
|
||||
|
||||
## "No composition found"
|
||||
Your directory needs an `index.html`. Run `npx hyperframes init` to create one.
|
||||
|
||||
## "FFmpeg not found"
|
||||
Local rendering requires FFmpeg. Install it:
|
||||
- macOS: `brew install ffmpeg`
|
||||
- Ubuntu: `sudo apt install ffmpeg`
|
||||
- Windows: Download from https://ffmpeg.org/download.html
|
||||
|
||||
## Lint errors
|
||||
Run `npx hyperframes lint` to check for common issues:
|
||||
- Missing `data-composition-id` on root element
|
||||
- Missing `class="clip"` on timed elements
|
||||
- Overlapping timelines or invalid data attributes
|
||||
|
||||
## Preview not updating
|
||||
Make sure you're editing the `index.html` in the project directory. The preview server watches for file changes and auto-reloads.
|
||||
|
||||
## Render looks different from preview
|
||||
Use `--docker` mode for deterministic output. Local renders may differ due to font availability and Chrome version.
|
||||
Reference in New Issue
Block a user