mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* feat(cli): surface outdated CLI and skills to agents; add hyperframes update Single commit of #7094 on top of main (no merge commits through the signed GraphQL path). Includes: 2h update/skills check interval and stale-cache recheck; `_meta.checkedAt`, `_meta.skillsOutdated`, `_meta.skillsMissing`; `_meta.updateNotice`, one sentence for the agent to relay to the person, at most once a day per project (brew/npx-aware command, omitted under CI, the update-check opt-out and agent plugins); `hyperframes update [--check] [--yes] [--json]` (CLI then skills at the installed CLI's tag; brew version read back); doctor names the running binary and its channel; the hyperframes-cli skill gets one line to pass the notice on, naming no command. Keeps main's install-target skills check (#7120) in updateSkills. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): update notice names a command that moves this install - `_meta.updateNotice` (and `update --check`'s skills command) now name a command that moves the running install: a global npm/pnpm/bun/brew CLI runs its own `hyperframes update` (or just its manager's command when only the CLI is behind), since `npx hyperframes` would run a project's copy or a fresh npx one; a project-local CLI moves with its project's manager by lockfile (`npm install`/`pnpm add`/`bun add`/`yarn add hyperframes@<v>`), which `update --yes` now names too instead of `npx hyperframes@latest`. - `update`'s confirmation hint states a fact and names no step for the agent: "Updating is the person's call; `update --check` only reports." - `upgrade --json`, `upgrade --project --json` and every `skills` JSON output leave out `_meta.updateNotice` (NO_UPDATE_NOTICE), like `update`. - dailyNotice: a null/non-object file reads as empty and is repaired; a future timestamp is stale; writes go through a 0600 tmp file + rename; withMeta never throws from the notice. - Docs: --json without --yes exits 2; plugin `update` exits 1 (plugin_managed); full `_meta` sample; per-install notice commands. `update --check` says "npm registry not reached" instead of "latest". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
216 lines
6.3 KiB
Markdown
216 lines
6.3 KiB
Markdown
# hyperframes
|
|
|
|
CLI for creating, previewing, and rendering HTML video compositions.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install -g hyperframes
|
|
```
|
|
|
|
Or use directly with npx:
|
|
|
|
```bash
|
|
npx hyperframes <command>
|
|
```
|
|
|
|
**Requirements:** Node.js >= 22, FFmpeg
|
|
|
|
## Commands
|
|
|
|
### `init`
|
|
|
|
Scaffold a new Hyperframes project from a template:
|
|
|
|
```bash
|
|
npx hyperframes init my-video
|
|
cd my-video
|
|
```
|
|
|
|
### `preview`
|
|
|
|
Start the live preview studio in your browser:
|
|
|
|
```bash
|
|
npx hyperframes preview
|
|
# Studio: http://localhost:3002/#project/my-video
|
|
# Server: http://localhost:3002
|
|
|
|
npx hyperframes preview --port 4567
|
|
```
|
|
|
|
In an interactive terminal, the preview stays attached until you press
|
|
Ctrl+C. In a non-interactive shell such as a coding-agent session, the same
|
|
command starts a managed preview that survives after the command returns. Use
|
|
`--background` or `--foreground` to choose explicitly, and manage persistent
|
|
previews with `--status`, `--stop`, `--list`, and `--kill-all`. Add `--json` to
|
|
managed lifecycle commands for machine-readable output. `--foreground --json`
|
|
prints the ready-session envelope once, then remains attached until stopped.
|
|
|
|
### `audio`
|
|
|
|
Measure where sounds land: onsets, the moment each sound peaks, loudness and
|
|
silence. Give files, or query the film's own clips in film time:
|
|
|
|
```bash
|
|
npx hyperframes audio sfx/whoosh.mp3
|
|
npx hyperframes audio --at 12 --json
|
|
```
|
|
|
|
### `normalize-audio`
|
|
|
|
Measure two local authored audio clips with integrated LUFS and match the target
|
|
to the unchanged reference. The command is a dry run unless `--write` is passed:
|
|
|
|
```bash
|
|
npx hyperframes normalize-audio --reference target-audio --target user-audio
|
|
npx hyperframes normalize-audio --reference target-audio --target user-audio --write
|
|
```
|
|
|
|
It updates only the target element's `data-volume` and refuses unsafe boosts
|
|
that exceed Studio's +12 dB ceiling or would clip.
|
|
|
|
### `render`
|
|
|
|
Render a composition to MP4. Run from the project directory; the positional
|
|
argument is the project directory (not a file), so render the project's
|
|
`index.html` directly, or point at a specific composition file with `-c`:
|
|
|
|
```bash
|
|
npx hyperframes render -o output.mp4
|
|
npx hyperframes render -c ./my-composition.html -o output.mp4
|
|
```
|
|
|
|
A render stops when the process that started it exits. To keep one running after
|
|
its launcher exits, set `HYPERFRAMES_RENDER_DETACHED=1` and start it in its own
|
|
process group, e.g. `bash -c 'set -m; HYPERFRAMES_RENDER_DETACHED=1 npx hyperframes render -o out.mp4 < /dev/null > render.log 2>&1 &'`.
|
|
|
|
Piped, non-quiet renders emit a single `@hf-diagnostic ` JSON line when an audio
|
|
failure reaches the CLI error handler. Version 1 has `operation: "render"` and
|
|
at most 16 `audioFailures`: allowlisted stage, reason, owner, retryable, and
|
|
optional subprocess exit code, signal, termination reason and OS code. It omits
|
|
messages, stderr, source paths/URLs, element IDs and command arguments. Consumers
|
|
must ignore unknown versions and fields. This is local CLI output; uploading it
|
|
requires the caller's existing consent and privacy checks. Quiet mode (including
|
|
batch JSON mode) emits no diagnostic line.
|
|
|
|
This covers audio preparation and mix failures, including the typed external
|
|
interruption path. Probe failures retain their existing stage/reason but do not
|
|
gain subprocess evidence here; browser/FX failures remain classified as internal.
|
|
Desktop ingestion and live report delivery are separate changes.
|
|
|
|
### `publish`
|
|
|
|
Upload a project directory and get a hosted URL that keeps working after the CLI exits.
|
|
Published projects are private by default:
|
|
|
|
```bash
|
|
npx hyperframes publish
|
|
npx hyperframes publish ./my-video
|
|
npx hyperframes publish --public
|
|
npx hyperframes publish --yes
|
|
```
|
|
|
|
Signed-out publishing returns an authentication-required claim URL; opening it
|
|
lets someone sign in and claim the project. Sign in first with
|
|
`npx hyperframes auth login` to publish an owned project you can update. Use
|
|
`--public` to make the claimed project visible to anyone. `--yes` only skips the
|
|
confirmation prompt and does not change visibility.
|
|
|
|
Signed-in publishers can use `--update <url-or-id>` to target an existing project
|
|
or `--space <space-id>` to publish into a shared team space. If the requested
|
|
project is missing or inaccessible, publishing can create a new project instead;
|
|
check the printed URL and status.
|
|
|
|
See the [publish reference](https://hyperframes.heygen.com/packages/cli#publish)
|
|
for all options, including video proxy settings.
|
|
|
|
### `lint`
|
|
|
|
Validate your Hyperframes HTML:
|
|
|
|
```bash
|
|
npx hyperframes lint ./my-composition
|
|
npx hyperframes lint ./my-composition --json # JSON output for CI/tooling
|
|
npx hyperframes lint ./my-composition --verbose # Include info-level findings
|
|
```
|
|
|
|
By default only errors and warnings are shown. Use `--verbose` to also display informational findings (e.g., external script dependency notices). Use `--json` for machine-readable output with `errorCount`, `warningCount`, `infoCount`, and a `findings` array.
|
|
|
|
### `compositions`
|
|
|
|
List compositions found in the current project:
|
|
|
|
```bash
|
|
npx hyperframes compositions
|
|
```
|
|
|
|
### `benchmark`
|
|
|
|
Run rendering benchmarks:
|
|
|
|
```bash
|
|
npx hyperframes benchmark ./my-composition.html
|
|
```
|
|
|
|
### `doctor`
|
|
|
|
Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
|
|
|
|
```bash
|
|
npx hyperframes doctor
|
|
```
|
|
|
|
### `browser`
|
|
|
|
Manage the bundled Chrome/Chromium installation:
|
|
|
|
```bash
|
|
npx hyperframes browser
|
|
```
|
|
|
|
### `info`
|
|
|
|
Print version and environment info:
|
|
|
|
```bash
|
|
npx hyperframes info
|
|
```
|
|
|
|
### `docs`
|
|
|
|
Open the documentation in your browser:
|
|
|
|
```bash
|
|
npx hyperframes docs
|
|
```
|
|
|
|
### `upgrade`
|
|
|
|
Check for updates and show upgrade instructions:
|
|
|
|
```bash
|
|
npx hyperframes upgrade
|
|
npx hyperframes upgrade --check --json # machine-readable for agents
|
|
```
|
|
|
|
### `update`
|
|
|
|
Check the CLI and the installed skills for updates in one call, or install both:
|
|
|
|
```bash
|
|
npx hyperframes update --check --json # report only, machine-readable for agents
|
|
npx hyperframes update --yes # upgrade the CLI, then refresh the skills
|
|
```
|
|
|
|
## Documentation
|
|
|
|
Full documentation: [hyperframes.heygen.com/packages/cli](https://hyperframes.heygen.com/packages/cli)
|
|
|
|
## Related packages
|
|
|
|
- [`@hyperframes/core`](../core) — types, parsers, frame adapters
|
|
- [`@hyperframes/engine`](../engine) — rendering engine
|
|
- [`@hyperframes/producer`](../producer) — render pipeline
|
|
- [`@hyperframes/studio`](../studio) — composition editor UI
|