mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
Vance IngallsandClaude Opus 4.6
61c5257402
* fix(ci): update publish workflow to use bun install pnpm-lock.yaml was removed in the bun migration but publish.yml still referenced it. Use bun for install/build, keep pnpm for publish (publishConfig overrides + --provenance). * docs: update stale pnpm references to bun across docs and scripts Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
133 lines
5.3 KiB
Plaintext
133 lines
5.3 KiB
Plaintext
---
|
|
title: "@hyperframes/studio"
|
|
description: "Visual composition editor with live preview, timeline view, and hot reload."
|
|
---
|
|
|
|
The studio package provides a browser-based visual editor for creating and previewing Hyperframes compositions. It gives you a real-time preview of your video, a visual timeline of all clips, and player controls for seeking and playback — all updating live as you edit your HTML.
|
|
|
|
```bash
|
|
npm install @hyperframes/studio
|
|
```
|
|
|
|
## When to Use
|
|
|
|
**Use `@hyperframes/studio` when you need to:**
|
|
- Build a custom composition editor UI (e.g., embedded in your own web application)
|
|
- Integrate the Hyperframes preview player into a larger product
|
|
- Extend the editor with custom panels, toolbars, or integrations
|
|
|
|
**Use a different package if you want to:**
|
|
- Preview compositions during development — use the [CLI](/packages/cli) (`npx hyperframes dev`), which launches the studio for you
|
|
- Render compositions to MP4 — use the [CLI](/packages/cli) or [producer](/packages/producer)
|
|
- Capture frames programmatically — use the [engine](/packages/engine)
|
|
|
|
<Tip>
|
|
**For most development workflows, you do not need to install the studio directly.** Running `npx hyperframes dev` starts the studio automatically with hot reload. Install `@hyperframes/studio` only if you are embedding the editor into your own application.
|
|
</Tip>
|
|
|
|
## Running the Studio
|
|
|
|
### Via the CLI (recommended)
|
|
|
|
```bash
|
|
npx hyperframes dev
|
|
```
|
|
|
|
This starts the studio development server, opens your composition in the browser, and watches for file changes. This is the easiest way to get a live preview.
|
|
|
|
### From the monorepo
|
|
|
|
```bash
|
|
# From the root
|
|
bun run dev
|
|
|
|
# Or target the studio package directly
|
|
bun run --filter @hyperframes/studio dev
|
|
```
|
|
|
|
The studio starts at `http://localhost:3000` by default.
|
|
|
|
## Features
|
|
|
|
### Live Preview
|
|
|
|
The studio renders your composition in an iframe using the Hyperframes runtime. What you see in the preview is exactly what will be captured during rendering — the same runtime code, the same seek logic, the same clip lifecycle.
|
|
|
|
Changes to your HTML are picked up automatically through hot reload, so you can edit `index.html` in your editor and see the result in the browser within milliseconds.
|
|
|
|
### Timeline View
|
|
|
|
The timeline panel provides a visual representation of your composition's structure:
|
|
|
|
- Each clip appears as a colored bar on its track
|
|
- Bar position and width reflect `data-start` and `data-duration`
|
|
- Tracks are stacked by `data-track-index` (higher tracks render in front)
|
|
- Relative timing references (e.g., `data-start="intro"`) are resolved and displayed as absolute positions
|
|
|
|
This makes it easy to understand the temporal structure of complex compositions with many overlapping clips.
|
|
|
|
### Player Controls
|
|
|
|
The studio includes a full set of playback controls:
|
|
|
|
- **Play / Pause** — start and stop playback
|
|
- **Seek** — click anywhere on the timeline to jump to that point
|
|
- **Scrub** — drag the playhead to scrub through the composition frame by frame
|
|
- **Frame step** — advance or rewind one frame at a time for precise positioning
|
|
|
|
### Hot Reload
|
|
|
|
File changes are detected and applied without restarting the server. The preview maintains its current playback position when possible, so you can tweak an animation at the 5-second mark without having to seek back to it after every save.
|
|
|
|
## Architecture
|
|
|
|
The studio is a React application with the following structure:
|
|
|
|
1. **Iframe preview** — your composition HTML is loaded in an isolated iframe with the Hyperframes runtime injected. This ensures the preview uses the same rendering path as production.
|
|
|
|
2. **Runtime bridge** — the studio communicates with the iframe via `postMessage` to control playback (play, pause, seek) and receive state updates (current time, duration, readiness).
|
|
|
|
3. **Timeline component** — parses the composition using `@hyperframes/core` to extract clip timing data and renders the visual timeline panel.
|
|
|
|
4. **File watcher** — a development server (Vite-based) watches your project files and triggers hot module replacement when changes are detected.
|
|
|
|
## Embedding in Your Own Application
|
|
|
|
If you are building a product that includes a composition editor, you can use the studio's components directly:
|
|
|
|
```typescript
|
|
import { Player, Timeline } from '@hyperframes/studio';
|
|
|
|
// Embed the preview player
|
|
<Player
|
|
src="./my-composition/index.html"
|
|
width={1920}
|
|
height={1080}
|
|
autoPlay={false}
|
|
/>
|
|
|
|
// Embed the timeline view
|
|
<Timeline compositionHtml={htmlString} />
|
|
```
|
|
|
|
<Info>
|
|
The studio depends on `@hyperframes/core` for parsing and runtime injection. You do not need to install core separately — it is included as a dependency.
|
|
</Info>
|
|
|
|
## Related Packages
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="CLI" icon="terminal" href="/packages/cli">
|
|
Launches the studio via `npx hyperframes dev` — the easiest way to preview compositions.
|
|
</Card>
|
|
<Card title="Core" icon="cube" href="/packages/core">
|
|
Types, parsing, and runtime that the studio uses for preview and timeline rendering.
|
|
</Card>
|
|
<Card title="Producer" icon="film" href="/packages/producer">
|
|
Renders the compositions you build in the studio to finished MP4 files.
|
|
</Card>
|
|
<Card title="Engine" icon="gear" href="/packages/engine">
|
|
The capture engine that powers production rendering of your compositions.
|
|
</Card>
|
|
</CardGroup>
|