* fix(cli): a subfolder of an imported project keeps its received-files record Publish, cloud render and feedback now read the received-files record at the nearest folder at or above the one they stage, so staging a subfolder of an imported project still leaves out the outside files its received files reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a received file counts under any spelling of the same file on disk The received-files lookup now also matches a project file that is the same file on disk as a listed path, so a name respelled in letter case on a case-insensitive disk keeps its received status. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): cloud render prepares only the GIFs staging kept The entry GIF prep before a cloud render upload now reads only the staged copies it is handed. An image whose source staging left out keeps its reference as written and is never read from disk. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): never hand a playlist named as media to ffmpeg A media file whose first bytes are an HLS playlist, an XML manifest or a concat script now stays out of ffprobe and ffmpeg: cloud render leaves it in the zip as authored, the media probe reports it as not media, and the proxy copy refuses it. Real media never starts with these bytes, so it probes and transcodes as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio-server): catch playlists with control bytes, and keep them from stills and audio probes A text playlist or concat script is detected whatever bytes follow its first line; only markup must be all text. A still frame and the audio probe behind waveforms, peaks and loudness now refuse a file the probe reads as not media, as the proxy copy already does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a parent folder's state the CLI cannot read never marks a project received The walk up for a received-files record now skips a parent whose record cannot be reached. Only a record file that is there but cannot be read or parsed counts every file as received. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a drive that reports no file ids matches no received file by identity Some network and virtual drives report a file id of 0 for every file, so the same-file match now gives such a file no identity instead of matching it to every listed file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(studio-server): read a media file's first bytes with a read stream The playlist check reads the first 64 bytes through a bounded read stream instead of a raw file descriptor, and the audio-track probe's doc comment sits on its function again. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(studio-server): raise the packed size budget for the media playlist check Main packs @hyperframes/studio-server close to the 1% tolerance on the 168500 budget, and the playlist check adds about 320 bytes, which put the Build over. Set the budget to 172000. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): open media only through self-contained media demuxers Every ffprobe and ffmpeg input that cloud render offload, the publish proxy bake and Studio's media helpers open now carries a demuxer whitelist built from the supported media extensions: MP4/MOV/M4A/AVIF, Matroska/WebM, MXF, AVI, MPEG-PS/TS, FLV, ASF, Ogg, WAV, MP3, AAC, FLAC, AIFF and the still-image formats. Playlist, manifest and concat demuxers can no longer open, whatever a file's bytes say. The proxy's own concat step is left as it is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): keep media probe argv flat, and expect the demuxer list in loudness args Two probe argv literals built from nested spreads are flat again, so "--" stays the visible second-to-last entry the argv contract checks. The normalize-audio test expects the demuxer list before the input. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): play and present answer only local host names and allowed hosts play and present listen on every interface. Each request now passes the same Host check preview uses: localhost, loopback addresses and this machine's own addresses and names are answered, and any other host name gets a 403 naming HYPERFRAMES_PREVIEW_ALLOWED_HOSTS until it is listed there. Phones and other machines on the network still open them by LAN address or .local name. * fix(cli): a local render of a received composition leaves out files outside the project When the composition a local render opens is listed in the project's received-files record, hyperframes render (full and range) no longer brings in files outside the project. It prints one line naming the references it leaves out and why. An unreadable record counts as received. A project whose entry is the person's own, or that has no record, renders exactly as before. * fix(cli): received-render scan reads safely and treats an unreadable record as unknown The scan behind the received-composition notice skips a file it cannot read, finds url() references with a linear forward scan, and reads at most 2 MB of each file. An unreadable received-files record no longer counts as everything received for local render: the render keeps outside files and names the record it could not read. Publish and cloud upload still treat it as received. The notice now says the render stops on a sub-composition outside the project rather than leaving it out. * fix(cli): the studio render of a received composition leaves out files outside the project The Studio render route applies the same rule as hyperframes render: when the composition it renders is listed in the received-files record, the job does not bring in files outside the project, and the server log names the references it refuses. * chore(cli): name the unreadable received-files record helper without a comment * fix(cli): local render refuses outside files when any composition it plays was received The received-file rule for local render (CLI and Studio) now checks every page and stylesheet the render pulls in, not only the entry, so an own index.html that plays a received scene also reads nothing outside the project, and the notice names the received file. An unreadable, truncated or empty received-files record refuses outside files too, as publish and cloud upload do, and the notice names the record it could not read. * fix(cli): decide a received render from the files the compiler reads Local render (CLI and Studio) now leaves outside-file handling as it is for a project with no received-files record or an empty one, without scanning anything. When the record lists files, the compiler's own read list for the composition decides: the bundler runs out of process with a deadline and reports every project file it reads, so stylesheet imports and files past any scan limit count. A received file in that list, a build that fails or runs past its deadline, or an unreadable record refuses outside files. The scan that names refused references in the notice is advisory only: it guards every file system call, tracks visited files by real path, and caps the files and bytes it reads. * fix(cli,producer): decide a received render with the render compiler's own composition traversal The producer exports renderCompositionFiles, which walks data-composition-src with the same resolution, normalization and private file rules the render's sub-composition pass uses; that pass now calls the same helper. The received-render decision adds those files to the bundler's read list, so leading-slash and percent-encoded references the render reads count. The advisory scan resolves compositions the same way and reads template contents. * fix(cli): refuse outside files in a local render whenever the project has received files A local render (CLI and Studio) reads nothing outside the project when the project's received-files record lists any file, or cannot be read. No static list matches what a render consumes: the page loads its stylesheets and scripts through the browser at capture time, and scripts can load more, so the decision no longer depends on one. The reference scan stays only to name what the notice says is left out. This drops the out-of-process bundler read list and the producer composition walk added for that decision. * fix(cli): refuse outside files only when a received file can load other files A local render (CLI and Studio) reads nothing outside the project when the received-files record cannot be read, or lists a received file that can reference others: an .html, .htm, .css, .js, .mjs, .cjs or .svg name, or content that reads as HTML, SVG or CSS. A project that only received images, video, audio or fonts keeps bringing in outside files as before. * fix(cli): keep outside files only when every received file is positively media, a font or an image A local render keeps bringing in outside files only when each file the received-files record lists has a known media, font or image extension and starts with that type's signature bytes. Any other received file, a listed file that is missing or unreadable, or a mismatch between name and content refuses outside files. An ancestor record's entries now match a subfolder whose name is spelled in another Unicode form; the entry keeps its own spelling on disk. * fix(producer,core): a sub-composition must be an .html file The render compiler and the runtime load a data-composition-src only when it names an .html or .htm file. Any other file, such as an image or video, is refused as a page: render stops naming it, and the runtime reports the load failure without fetching it. * fix(producer,cli): the render and static file servers forbid type sniffing Both servers send X-Content-Type-Options: nosniff with every response, so the browser loads a file only as the type its extension names: an image or video cannot run as a script or apply as a stylesheet. .cjs is served as JavaScript. * test(cli): a received media file in a composition slot is refused as a page * test(cli): an empty nested received-files record cannot hide an outer record's received page * fix(cli): a received media file reached under another name refuses outside files The received-render decision now compares file identities, not names. It walks the project once, bounded by entry count and time, and refuses outside files when a hardlink or a symlink with a name that is not media reaches a received file, or when the walk cannot finish. A received file with no identity matches nothing, as in the received files check. * fix(cli): compare received files by link target and keep outside files for an empty record A received media file and every other project name are now compared by the identity of the file they reach with links followed. A linked folder that leads outside the project, or a file whose identity cannot be read, counts as unchecked and refuses outside files. An empty received-files record keeps outside files without walking the project. * chore: raise the producer unpacked size budget for the composition file checks --------- 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. Where a full match would pass
Studio's +12 dB ceiling or -1.5 dBTP, it applies the most that fits and says how far
under the reference that leaves the target.
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.
Piped, non-quiet renders also emit a single @hf-result JSON line after a local
render succeeds, never after a failure. Version 1 has operation: "render" and
reference_background, the background the render measured from the composition's
root and body: {"kind":"solid","rgb":[r,g,b]}, {"kind":"none"},
{"kind":"unsupported_non_solid"} or {"kind":"unknown"}. A render that applied
motion blur also carries motion_blur: tier ("capture" or "filter", absent
when none ran), movers, failed_frames and a fingerprint of 14 snake_case
counts (absent when the page produced none); it is absent when the render has no
blur summary. Consumers must ignore unknown versions and fields. A --docker render prints no result line from the
launcher. In batch mode each manifest row carries the same reference_background value (null until the row completes, and for a
row that failed).
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