---
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.