mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
ukimsanov
119 lines
5.3 KiB
Plaintext
119 lines
5.3 KiB
Plaintext
---
|
|
title: "How HyperFrames fits into an application"
|
|
sidebarTitle: "Developer overview"
|
|
description: "Understand the composition contract, editing surfaces, Player, CLI, and rendering layers before choosing an integration."
|
|
---
|
|
|
|
Building on HyperFrames means using an editable HTML composition as the shared source for automation, playback, editing, and rendering.
|
|
|
|
## Start with the composition contract
|
|
|
|
A composition is a finite HTML document with an explicit viewport, timed clips, media, and one or more paused animation timelines.
|
|
|
|
```html
|
|
<div
|
|
id="main"
|
|
data-composition-id="intro"
|
|
data-start="0"
|
|
data-duration="5"
|
|
data-width="1920"
|
|
data-height="1080"
|
|
>
|
|
<img
|
|
id="product"
|
|
class="clip"
|
|
data-start="0"
|
|
data-duration="5"
|
|
data-track-index="1"
|
|
src="./assets/product.png"
|
|
/>
|
|
</div>
|
|
|
|
<script>
|
|
window.__timelines = window.__timelines || {};
|
|
const timeline = gsap.timeline({ paused: true });
|
|
window.__timelines.intro = timeline;
|
|
</script>
|
|
```
|
|
|
|
The runtime reads the timing attributes, controls clip visibility and media playback, and seeks registered animation timelines. The HTML remains inspectable and editable by normal web tooling.
|
|
|
|
Use the [composition and schema reference](/reference/html-schema) when generating compositions or building a new authoring surface.
|
|
|
|
## Choose the smallest integration surface
|
|
|
|
| What the application must do | Start with | First useful result |
|
|
| ------------------------------------------------------- | --------------------------- | ------------------------------------------------ |
|
|
| Validate, preview, render, or automate projects | CLI | Check and render one known project |
|
|
| Query and change composition HTML | SDK | Find one element, change it, and save |
|
|
| Embed a seekable composition | Player | Play and seek one composition in a page |
|
|
| Build an editor | SDK + Player | Edit the source and reflect it in a live preview |
|
|
| Render from a Node service | Producer | Turn one composition into an encoded file |
|
|
| Control frame capture or build rendering infrastructure | Engine | Capture exact frames from a seekable page |
|
|
| Run managed or distributed renders | Cloud, Lambda, or Cloud Run | Submit one project and retrieve the result |
|
|
|
|
Do not start with the rendering engine when the CLI already performs the complete job. Do not add the SDK when the application only needs playback.
|
|
|
|
## CLI: operate complete projects
|
|
|
|
The CLI is the highest-level technical surface. It creates projects, opens Studio, validates compositions, captures review frames, renders files, publishes projects, and drives cloud render backends.
|
|
|
|
```bash
|
|
npx hyperframes check
|
|
npx hyperframes render --output video.mp4
|
|
```
|
|
|
|
Use the [CLI guide](/developers/cli) for the everyday commands and the [complete CLI reference](/packages/cli) for flags and automation.
|
|
|
|
## SDK: inspect and edit
|
|
|
|
`@hyperframes/sdk` opens composition HTML, gives elements stable `hf-id` identifiers, applies typed edit operations, emits JSON patches, supports undo and redo, and persists through adapters.
|
|
|
|
```ts
|
|
import { openComposition } from "@hyperframes/sdk";
|
|
|
|
const html = `<div class="clip" data-start="0" data-duration="5"
|
|
data-hf-id="hf-title">Old title</div>`;
|
|
|
|
const comp = await openComposition(html);
|
|
comp.setText("hf-title", "A new title");
|
|
const updatedHtml = comp.serialize();
|
|
```
|
|
|
|
Use it for agents, backend jobs, custom editors, versioned template systems, or any application that must change the source rather than merely play it.
|
|
|
|
Start with the [SDK quickstart](/sdk/quickstart).
|
|
|
|
## Player: embed and seek
|
|
|
|
`@hyperframes/player` is a web component that loads a composition in an isolated iframe and exposes video-like playback controls.
|
|
|
|
```html
|
|
<script type="module" src="https://cdn.jsdelivr.net/npm/@hyperframes/player"></script>
|
|
<hyperframes-player src="/compositions/intro.html" controls></hyperframes-player>
|
|
```
|
|
|
|
Use its JavaScript API to play, pause, seek, change playback rate, and listen for timeline events. It does not edit or render the composition.
|
|
|
|
See the [Player reference](/packages/player).
|
|
|
|
## Rendering: choose the layer you need
|
|
|
|
- **CLI** — complete local and automated rendering.
|
|
- **Producer** — the Node rendering pipeline: capture, encode, and audio mix.
|
|
- **Engine** — lower-level seekable page capture and exact-frame control.
|
|
- **Managed cloud** — hosted rendering without operating Chrome or FFmpeg.
|
|
- **AWS Lambda or Google Cloud Run** — infrastructure you deploy and control.
|
|
|
|
Most applications should begin with the CLI or Producer. Reach for Engine only when building a specialized capture or rendering system.
|
|
|
|
Use [rendering infrastructure](/deploy/overview) to compare hosted, local, and self-managed paths.
|
|
|
|
## The complete mental model
|
|
|
|
```text
|
|
composition → inspect or edit → play or render
|
|
```
|
|
|
|
Every surface works on the same source. Choose the smallest layer that produces the result your application needs, then move lower only when the higher-level layer removes control you genuinely require.
|