> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How HyperFrames fits into an application

> 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 theme={null}
<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 theme={null}
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 theme={null}
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 theme={null}
<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 theme={null}
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.