mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
139 lines
5.7 KiB
Plaintext
139 lines
5.7 KiB
Plaintext
---
|
|
title: "@hyperframes/studio-server"
|
|
description: "Mount the Studio project and preview API in your own server."
|
|
---
|
|
|
|
`@hyperframes/studio-server` is the backend used by Studio. It serves projects
|
|
and previews, applies source mutations, creates thumbnails, and starts render
|
|
jobs.
|
|
|
|
Most users do not need it. The CLI wires the server and Studio together when
|
|
you run `npx hyperframes preview`. Use this package only when your own
|
|
application must host the Studio backend.
|
|
|
|
```bash
|
|
npm install @hyperframes/studio-server
|
|
```
|
|
|
|
## Mount the API
|
|
|
|
`createStudioApi()` returns a Hono application. The adapter is the boundary
|
|
between Studio and your project storage, bundler, linter, and renderer.
|
|
|
|
```ts
|
|
import type { Hono } from "hono";
|
|
import {
|
|
createStudioApi,
|
|
type StudioApiAdapter,
|
|
} from "@hyperframes/studio-server";
|
|
|
|
export function mountStudioApi(
|
|
app: Hono,
|
|
adapter: StudioApiAdapter,
|
|
) {
|
|
app.route("/api", createStudioApi(adapter));
|
|
}
|
|
```
|
|
|
|
When it is served from loopback (`localhost`, `127.0.0.1` or `[::1]`), Studio
|
|
sends its API requests without cookies, so they don't queue behind the
|
|
preview's media. On any other origin it sends them as usual, so remote and
|
|
proxied setups (Codespaces, tunnels, an access proxy) keep their cookies by
|
|
default. A loopback host that authenticates its mounted API with same-origin
|
|
cookies sets `VITE_STUDIO_API_SAME_ORIGIN_CREDENTIALS=true`, at build time or at
|
|
runtime in `window.__HF_STUDIO_ENV__`; it costs that host the connection
|
|
speedup.
|
|
Studio reads the flag once, when its modules load, so set
|
|
`window.__HF_STUDIO_ENV__` before loading Studio; the CLI injects it, but a host
|
|
that mounts the API itself must inject it too.
|
|
|
|
A `StudioApiAdapter` supplies:
|
|
|
|
- project listing and resolution;
|
|
- composition bundling and linting;
|
|
- render output storage and job startup;
|
|
- optional thumbnails, sessions, registry installation, and background removal.
|
|
|
|
Use the interface exported by your installed version as the exact contract. It
|
|
changes as Studio gains capabilities.
|
|
|
|
`bundle(projectDir, options)` must pass `options` through to `bundleToSingleHtml`,
|
|
spread over your own options. The preview sets `stampHfIds` there so each element
|
|
is served with the id its source file mints. If a host drops it, a composition
|
|
the bundler inlines can be served with ids that a later save does not mint.
|
|
|
|
```ts
|
|
bundle: (dir, options) => bundleToSingleHtml(dir, { runtime: "inline", ...options }),
|
|
```
|
|
|
|
## Serve GSAP from your own mirror
|
|
|
|
Studio can load the GSAP dependencies it adds from a local or private mirror
|
|
when jsDelivr is unavailable. Set `HYPERFRAMES_GSAP_BASE_URL` before starting
|
|
the preview server or creating the Studio API:
|
|
|
|
```bash
|
|
HYPERFRAMES_GSAP_BASE_URL=http://127.0.0.1:8080/vendor/npm \
|
|
npx hyperframes preview ./my-video
|
|
```
|
|
|
|
Serve the GSAP distribution files under that URL with this layout, using the
|
|
versions your compositions need:
|
|
|
|
```text
|
|
<mirror-root>/gsap@3.15.0/dist/gsap.min.js
|
|
<mirror-root>/gsap@3.15.0/dist/CustomEase.min.js
|
|
<mirror-root>/gsap@3.15.0/dist/MotionPathPlugin.min.js
|
|
```
|
|
|
|
Studio uses the mirror for the GSAP, CustomEase, and MotionPathPlugin scripts
|
|
it adds to previews, including dependencies loaded when you edit motion.
|
|
Keep `gsap@<version>` in authored GSAP URLs so the server can infer which
|
|
plugin version to add. When it cannot infer a version, it uses the framework's
|
|
default, currently `3.15.0`.
|
|
|
|
The base must be an absolute HTTP(S) URL without credentials, a query string,
|
|
or a fragment. Surrounding whitespace and trailing slashes are removed.
|
|
An unset or empty value uses `https://cdn.jsdelivr.net/npm`; an invalid
|
|
nonempty value stops API startup with a configuration error.
|
|
|
|
The server reads this setting once at startup. Restart it after changing the
|
|
value. For a managed CLI preview, run `npx hyperframes preview ./my-video --stop`
|
|
before starting it again with the new setting. Cached preview HTML is keyed
|
|
by the normalized mirror URL, so a different mirror takes effect after restart
|
|
without deleting the preview cache.
|
|
|
|
This setting changes only dependencies Studio adds. Your composition's own
|
|
script, font, image, and media URLs stay as authored; serve those locally too
|
|
for an offline project. If the selected mirror is unavailable or lacks a
|
|
requested file, Studio does not retry that dependency through jsDelivr.
|
|
|
|
## Other entry points
|
|
|
|
| Import | Purpose |
|
|
| --- | --- |
|
|
| `@hyperframes/studio-server/source-mutation` | Apply guarded changes to composition source |
|
|
| `@hyperframes/studio-server/screenshot-clip` | Calculate element screenshot geometry |
|
|
| `@hyperframes/studio-server/safe-path` | Resolve paths inside a project and walk its files, without the server |
|
|
| `@hyperframes/studio-server/hf-ids` | Stamp stable element ids into a project's HTML, without the server |
|
|
| `@hyperframes/studio-server/history` | Open a project's undo history, without the server |
|
|
| `@hyperframes/studio-server/manual-edits-render-script` | Reapply Studio manual edits during render |
|
|
| `@hyperframes/studio-server/studio-motion-render-script` | Reapply Studio motion edits during render |
|
|
| `@hyperframes/studio-server/draft-markers` | Work with draft gesture markers |
|
|
| `@hyperframes/studio-server/finite-mutation` | Guard source mutations against non-finite values |
|
|
| `@hyperframes/studio-server/media-proxy-preview` | Support proxied media in preview |
|
|
|
|
`@hyperframes/core/studio-api` remains a deprecated compatibility re-export.
|
|
New integrations should import from `@hyperframes/studio-server`.
|
|
|
|
## Related topics
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="@hyperframes/studio" icon="palette" href="/packages/studio">
|
|
Embed lower-level Studio interface components.
|
|
</Card>
|
|
<Card title="Studio guide" icon="display" href="/studio">
|
|
Use the complete editor that ships with HyperFrames.
|
|
</Card>
|
|
</CardGroup>
|