* fix(producer): a wedged effect scan or screenshot-session open trips the 60 s stall watchdog The sequential streaming watchdog raced only the capture call. Session init (where the fast-capture effect scan runs) and opening the screenshot session for effect frames waited on CDP's protocol timeout instead, which scales with output area up to 30 minutes, so a starved page hung a render for ~25 minutes before the watchdog saw the next frame. The effect scan now gives up when a chunk outlasts its 120 s budget, opening the effect-frame session gets its own no-progress window, and session init gets a 300 s one; each trip retries on a fresh session like any other stall. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(cli): one local render at a time per machine; a second waits and says for whom Renders started side by side from different sessions starve each other until frames stop landing. `hyperframes render` now takes a machine-wide slot (a lock file in the HyperFrames cache directory, held by pid) after its preflight and holds it for the render or the whole batch. A second render waits and prints the pid and project it is waiting behind; `--no-wait` fails at once instead. A holder whose process is gone is taken over, and HYPERFRAMES_RENDER_LOCK=off restores side-by-side renders. `--workers` is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(lint): flag fonts a cloud render cannot resolve, including the font shorthand Lint read only `font-family`, so `font: 500 16px "PingFang SC", sans-serif` passed while the renderer, which reads the shorthand too, drew the installed Mac font locally and the cloud refused it. The shorthand now counts for font_family_without_font_face (its parser moves to @hyperframes/parsers so core and lint share one), and a new font_face_local_only warning names an @font-face whose only sources are local(): it renders here and falls back in the cloud. The rule's hint and the format reference stop recommending local() for OS fonts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a cloud render that refuses a font says which project files use it The cloud's "fonts that could not be resolved: PingFang SC" named no composition. For a render submitted from a local project, the failure now lists each refused family with the project files that name it, and says how to ship the font so the cloud can use it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(cli): keep comment shares and exports within the gates, and split the single-render notes out of executeHeldRender Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(parsers): read a spaced line-height slash and var() before the size in the font shorthand `font: 16px / 1.5 Inter` was read as the family `/ 1.5 Inter`, and `font: var(--weight) 16px Inter` as `16px Inter`, because a var() counted as the size. The parser now follows the shorthand grammar: optional style, variant, weight and width keywords (or var()), then a length, percentage, keyword or calc() size, then a `/ line-height` in any spacing. When no size can be told apart from a var(), it says so: lint skips that declaration instead of reporting a missing font, and the renderer keeps its best guess. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): say the render slot is one per user account, not per machine The lock lives in the account's HyperFrames cache folder, so renders by two user accounts never queued behind each other while the messages, flag help and docs said "this machine". They now say "per user account" and that HYPERFRAMES_CACHE_DIR set to a shared folder shares the slot across accounts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): reclaim a render lock or takeover file left half-written A lock or `.break` file that exists but cannot be parsed (a crash mid-write where hard links are unavailable) was never reclaimed: a waiting render waited forever and --no-wait refused forever. Once such a file is older than any real write (5 s by mtime) it counts as abandoned: the lock goes through the same `.break` takeover as a dead holder's, and a takeover file is removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(producer): opening the capture session counts against the setup stall budget The sequential streaming attempt opened its own capture session (Chrome launch and new page) before the setup watchdog and outside the attempt's cleanup, so a wedged launch still waited for the protocol timeout. Opening now shares the 300 s setup window with session initialisation, a trip fails the attempt like any other sequential stall, and a session that finishes opening after its attempt gave up is closed instead of leaking a browser. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(parsers): keep the shorthand result type module-private Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): reclaim an unreadable render lock only when its writer is provably gone Where hard links are unavailable the lock is created by an exclusive open and then written, so a contender paused between the two leaves an unreadable lock while it is still alive. The 5 s mtime grace took such a lock over, and both processes then held the slot. Each contender now writes an owner marker under a name only it can take (pid plus random suffix, holding its process identity) before it creates the lock, keeps it while it holds the slot, and removes it otherwise. An unreadable lock or `.break` is reclaimed only when no other contender's marker belongs to a live process; markers of dead processes, or of a reused pid, are deleted. No reclaim is decided by time alone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor: split acquireRenderLock and the streaming-stage session stub under the complexity gate acquireRenderLock hands contender setup and a single marked claim to their own functions, and the test stub for createCaptureSession splits its held-open cases from the fake session it builds, so neither exceeds Fallow's cognitive or CRAP thresholds. Behaviour is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(ci): raise the CLI and engine size budgets for the watchdog, lock and font-lint additions Main's CLI unpacked size was already ~0.99% over its budget; the render lock and owner markers push it past the 1% tolerance. The CLI unpacked budget takes the same value as #7169 and #7170 (25,159,107) so the PRs merge cleanly. The engine's packed size grows by about 4.7 KB for the effect-scan and session-open watchdogs; its packed budget moves to 5% above the measured 467,097, as the budget file's headroom rule sets it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(parsers): a var() size glued to its line height is the shorthand's size `font: 700 var(--size)/1.1 "Inter"` read as no family at all: the token was tested whole against var(), and the slash after it hid that it was the size, so the renderer injected no face for Inter. A var() followed by `/ line-height` (glued or spaced) can only be the size, and is now read as one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(parsers): split the shorthand size search out of parseFontShorthand Keeps parseFontShorthand under Fallow's cognitive-complexity gate; behaviour is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): render lock never removes another render's takeover, knows a reused pid, works in a shared folder and on Windows - A `.break` takeover file is removed only by the render that wrote it. One whose writer is gone stops the render with the file to delete, instead of being removed on an earlier reading, which could remove a live `.break` written since and let two renders hold the slot. The takeover re-reads the lock under its own `.break` right before replacing it. - The lock record keeps its holder's process start time, so a pid that now belongs to another process (an OOM-killed render in a container with a persisted cache) no longer holds the slot forever. - The `locks` folder is created writable for every account, so accounts sharing HYPERFRAMES_CACHE_DIR take turns instead of the second failing with EACCES; a folder this account cannot write in says how to fix it, and another account's file that cannot be removed is left, not fatal. - Windows: no PowerShell start-time lookup per check (pid liveness only), a file another handle holds (EPERM/EBUSY/EACCES) reads as held, a lock that vanished is retried once instead of in a tight loop, and a wait stops when its signal aborts. The tests end every acquire they start before removing their folder, and the paused contender writes through its open descriptor. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(ci): raise the lint packed size budget for the font-shorthand rule With main's audio-attribute rule (#7169) merged in, the font-shorthand and local()-only font findings take @hyperframes/lint's packed tarball to 181925 bytes, over the 179338 budget. The new budget is that measurement plus the usual 5% headroom. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
hyperframes
CLI for creating, previewing, and rendering HTML video compositions.
Install
npm install -g hyperframes
Or use directly with npx:
npx hyperframes <command>
Requirements: Node.js >= 22, FFmpeg
Commands
init
Scaffold a new Hyperframes project from a template:
npx hyperframes init my-video
cd my-video
preview
Start the live preview studio in your browser:
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:
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:
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:
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:
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 for all options, including video proxy settings.
lint
Validate your Hyperframes HTML:
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:
npx hyperframes compositions
benchmark
Run rendering benchmarks:
npx hyperframes benchmark ./my-composition.html
doctor
Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
npx hyperframes doctor
browser
Manage the bundled Chrome/Chromium installation:
npx hyperframes browser
info
Print version and environment info:
npx hyperframes info
docs
Open the documentation in your browser:
npx hyperframes docs
upgrade
Check for updates and show upgrade instructions:
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:
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
Related packages
@hyperframes/core— types, parsers, frame adapters@hyperframes/engine— rendering engine@hyperframes/producer— render pipeline@hyperframes/studio— composition editor UI