mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-01 11:16:58 +00:00
Ular Kimsanov
0390f3f908
* docs(studio): the browser editor in six pages, named the browser editor * docs(studio): mute where the editor has it, and no solo control The audio pages still described a solo control and a group-row mute that the editor does not render. Muting is the speaker button on an audio track (Mute track / Unmute track), the same toggle on a selected clip, and the Muted switch; a group is silenced through its members' tracks. The audio reference drops its solo section for the same reason.
155 lines
6.3 KiB
Plaintext
155 lines
6.3 KiB
Plaintext
---
|
|
title: "@hyperframes/studio"
|
|
description: "For developers: the React components and hooks behind the HyperFrames browser editor. Looking for the Studio app? See Get the Studio app."
|
|
---
|
|
|
|
<Note>
|
|
Looking for the **HyperFrames Studio app**, the one you download to make videos? It's here:
|
|
[Get the Studio app](/studio-app). This page is for developers building on the editor's code.
|
|
</Note>
|
|
|
|
`@hyperframes/studio` contains the React application, editor components, player, timeline, and hooks behind the
|
|
HyperFrames browser editor.
|
|
|
|
To open a project in the browser editor, you don't need this package:
|
|
|
|
```bash
|
|
npx hyperframes preview
|
|
```
|
|
|
|
Install the package only when you are extending Studio or building an editor that
|
|
uses its lower-level parts:
|
|
|
|
```bash
|
|
npm install @hyperframes/studio react react-dom zustand
|
|
```
|
|
|
|
<Warning>
|
|
The exported components are building blocks, not a drop-in embedded editor. Components such as
|
|
`EditorShell`, `NLEPreview`, `Timeline`, `PropertyPanel`, and `FileTree` require project state,
|
|
callbacks, or Studio contexts. Use `StudioApp` when you need the whole editor, or inspect
|
|
the component types before composing a custom host.
|
|
</Warning>
|
|
|
|
When you run Studio from the monorepo, its dev server listens on `http://localhost:5190`.
|
|
|
|
## Entry points
|
|
|
|
| Import | Contains |
|
|
| ------------------------------------- | ------------------------------------------------------------------- |
|
|
| `@hyperframes/studio` | React components, hooks, utilities, and their public types |
|
|
| `@hyperframes/studio/ui` | UI primitives (buttons, menus, popovers, fields) without the editor |
|
|
| `@hyperframes/studio/player` | The `Player` component alone, without the timeline |
|
|
| `@hyperframes/studio/tailwind-preset` | Tailwind preset used by Studio |
|
|
|
|
Peer dependencies are React 19, React DOM 19, and Zustand 4 or 5.
|
|
|
|
## Main exports
|
|
|
|
### Complete application
|
|
|
|
| Export | Use |
|
|
| ----------- | ------------------------------- |
|
|
| `StudioApp` | The complete Studio application |
|
|
|
|
### Editor structure
|
|
|
|
| Export | Use |
|
|
| ----------------------- | ---------------------------------------- |
|
|
| `EditorShell` | Preview, side panels, and timeline shell |
|
|
| `NLEPreview` | Composition preview surface |
|
|
| `CompositionBreadcrumb` | Navigation through nested compositions |
|
|
| `SourceEditor` | Source editor |
|
|
| `PropertyPanel` | Inspector for the selected element |
|
|
| `FileTree` | Project file browser |
|
|
|
|
### Playback and timeline
|
|
|
|
| Export | Use |
|
|
| ---------------------- | -------------------------------------- |
|
|
| `Player` | Composition iframe and playback bridge |
|
|
| `PlayerControls` | Playback, seeking, and frame controls |
|
|
| `Timeline` | Timeline editing surface |
|
|
| `VideoThumbnail` | Video clip thumbnail |
|
|
| `CompositionThumbnail` | Nested-composition thumbnail |
|
|
|
|
### Hooks and utilities
|
|
|
|
| Export | Use |
|
|
| ----------------------------------------------------------- | ----------------------------------------------------- |
|
|
| `useTimelinePlayer` | Read and control the shared player state |
|
|
| `usePlayerStore` | Access the Zustand player store |
|
|
| `useCompositionStack` | Drill into and back out of nested compositions |
|
|
| `useElementPicker` | Select and edit an element through the preview iframe |
|
|
| `resolveSourceFile`, `applyPatch` | Locate and patch source |
|
|
| `parseStyleString`, `mergeStyleIntoTag`, `findElementBlock` | Work with inline source styles and elements |
|
|
|
|
The package also exports `CompositionLevel`, `TimelineElement`, `PickedElement`,
|
|
and `PatchOperation`.
|
|
|
|
## How Studio stays connected to a project
|
|
|
|
1. Studio loads the composition in an iframe with the HyperFrames runtime.
|
|
2. Player controls communicate with that runtime to play, pause, and seek.
|
|
3. The editor and timeline send changes through the Studio API.
|
|
4. The Studio server writes those changes back to the project files.
|
|
5. External file changes refresh the preview while keeping the current position
|
|
when possible.
|
|
|
|
Preview and render use the same seekable composition contract. Preview still
|
|
depends on the browser playing in real time, while render captures frames one at a
|
|
time. A heavy project can therefore stutter during preview and still render every
|
|
frame.
|
|
|
|
## Tailwind preset
|
|
|
|
```typescript
|
|
import studioPreset from "@hyperframes/studio/tailwind-preset";
|
|
|
|
export default {
|
|
presets: [studioPreset],
|
|
};
|
|
```
|
|
|
|
## Preview guides in your own app
|
|
|
|
Host apps can compose the same rulers, safe margins, grid, and snap toolbar that
|
|
Studio uses over their own preview iframe. The provider owns the iframe geometry
|
|
and shared preferences, so the host supplies its current iframe element and chooses the
|
|
parts to render:
|
|
|
|
```tsx
|
|
import {
|
|
GridOverlay,
|
|
PreviewGuides,
|
|
PreviewOverlayProvider,
|
|
SnapToolbar,
|
|
} from "@hyperframes/studio";
|
|
function Preview({ iframe }: { iframe: HTMLIFrameElement | null }) {
|
|
return (
|
|
<PreviewOverlayProvider iframe={iframe}>
|
|
<PreviewGuides />
|
|
<GridOverlay />
|
|
<SnapToolbar />
|
|
</PreviewOverlayProvider>
|
|
);
|
|
}
|
|
```
|
|
|
|
## Related topics
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Use Studio" icon="pen-to-square" href="/studio">
|
|
Learn the complete editing workflow.
|
|
</Card>
|
|
<Card title="Studio server" icon="server" href="/packages/studio-server">
|
|
Connect project files, media, linting, and render jobs.
|
|
</Card>
|
|
<Card title="Player" icon="circle-play" href="/packages/player">
|
|
Embed playback without the editing interface.
|
|
</Card>
|
|
<Card title="SDK" icon="code" href="/sdk/quickstart">
|
|
Query and edit compositions without Studio.
|
|
</Card>
|
|
</CardGroup>
|