* fix(cli): a check or snapshot that times out says which step it was on
check's idle deadline named only the phase ("while checking samples") and snapshot's
CDP timeout named nothing. check now adds the sample, craft frame or overlap probe it
was on, and snapshot adds the seek or capture of the frame it was on, with its time.
* fix(cli): a snapshot timeout no longer tells the user to raise a setting they do not have
Puppeteer's protocol timeout message ends "Increase the 'protocolTimeout' setting in
launch/connect calls". snapshot has no such option, so the step it was on is now the
last thing the message says.
* feat(cli): check reports where its seek loop spends its time
check_report carried one seek_loop_ms, which lumps the layout grid, the craft pass
(up to 600 frames) and the overlap pass with its hold probes. It now also carries
grid_ms, craft_ms, overlap_ms and composition_s, so a slow check can be tied to a
pass. Nothing about what check does or prints changes.
* chore(cli): drop the pass-timings doc comment so the comment share does not rise
* fix(cli): a Chrome that fails to start says how it ended, and a slow start says so
A failed launch only reported "Protocol error (Target.setDiscoverTargets): Target closed". It now
runs the browser once more on its own with the same flags and reports its exit code (Windows
codes named: missing runtime, out of memory, security software), its last stderr lines, or that
it stayed up. The CLI and the engine's render launch both use it. A start slower than 5 s prints
"Chrome is still starting...", and a --timeout that looks like seconds says it is milliseconds.
* chore(cli): cut the Chrome launch diagnosis comments to the comment limit
* fix(cli): the Chrome startup check runs Chrome as puppeteer does and can be cancelled
The check started the browser with only the caller's flags, so a full Chrome ran headful and
was blamed for a missing X server. It now uses puppeteer's default arguments (headless
included). The check is stopped when the CLI is stopped, and the GPU probe, whose failure
falls back to software anyway, skips it.
* fix(cli): a Chrome launch error is never replaced by a failure to explain it
The startup diagnosis asks puppeteer for its default arguments before re-running
Chrome. If that call fails, its error used to replace the launch error the caller
needed. The launch error is now reported as it was. The core package size budget
rises to cover the new chromeStartup module (about 4.7 KB unpacked).
* refactor(engine): the Chrome startup diagnosis lives in the engine, not core
Both callers launch Chrome through the engine (the CLI already imports it), so the
engine owns the diagnosis. Core's package size budget is back to its old value.
* ci: a release PR runs a fast release check, not the heavy suites
* ci: keep the release check's header within the comment limit
* ci: shorten the release check's usage line
* ci: trim the release check's comments
* ci: the release check's classifier hands the manifest test to a helper
The file-change test fetches an asset and never reads the response, so the file stays
open and Windows fails the later folder move with EPERM (it failed a merge-queue run).
The helper now reads each body to its end.
* fix(studio-server): history lock retries a busy url write and releases on failure
* style(studio-server): wrap the fs mock
* style(studio-server): format the owner lock test
* fix(cli): check stops making video copies after 10 minutes, and --timeout takes units
The copy phase of check had no overall limit: a source that kept moving was never
stopped, and stdout stays silent the whole time. It now ends after 10 minutes with
an error naming the files still unfinished and the elapsed seconds; finished copies
are reused on the next run. The stderr progress lines are unchanged.
--timeout on check and snapshot is milliseconds, so "--timeout 45" waited 45 ms.
It now accepts 45s, 2m and 45000ms, and a bare number under 1000 warns on stderr
that it is milliseconds. Output on stdout is unchanged.
* chore(cli): cut the --timeout parser comment to the comment limit
* fix(cli): drop the 10 minute wall clock on check's video copies
A copy that keeps making progress must not be cut by a clock, and a re-run would
only start it over. The copy already ends when ffmpeg stops reporting progress
for 3 minutes (finished pieces are kept for the next run), so the phase is
bounded on no progress. The --timeout warning now names the value actually used
when check raises a small value to its 500 ms floor.
* fix(cli): take JSON flags from a file or stdin so PowerShell can pass them
* fix(cli): read BOM-prefixed and UTF-16 JSON from a file or stdin
* style(cli): format the JSON flag reader
* test(cli): feed the bytes PowerShell pipes to the JSON reader
* style(cli): shorten the JSON flag reader's comments
* style(cli): one line for the JSON flag reader's comment
* fix(core): retiming a parked scene in the preview takes effect without a reload
* fix(core): an edit that leaves a parked scene without a start or length in seconds reloads instead
* fix(core): a video after a cut starts early by its measured start delay, so it plays in sync
* test(player): playbench reports how far the picture after a cut runs behind the playhead
* fix(core): a looping video no longer skews the learned video start delay
* fix(core): the video start delay is learned in less code and capped at 100 ms under test
Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Joel Gallardo <joel.gallardo@heygen.com>
Co-authored-by: heygengenesis[bot] <262951085+heygengenesis[bot]@users.noreply.github.com>
* fix(core): the npm package no longer ships the unminified media sync runtime
* style(core): a two-line comment for the media clip's volume keyframes
* style(core): the moved media clip type keeps only the comments its names do not say
* feat(cli): capture accepts a local HTML file again
Adds an explicit --local-file mode. The file's directory (or --local-root) is served
on a loopback port that only Chrome may reach outside the capture proxy; all other
traffic keeps the public-address policy. The URL argument stays public HTTP(S) only.
* fix(cli): local capture output names the file, not the loopback server
In --local-file mode, meta.json, AGENTS.md, extracted files and the returned result
used the temporary 127.0.0.1 origin. One rewriter maps that origin to file:// URLs
under the root, and meta.json records the file as its source. Root and served paths
now resolve with the same native realpath, which Windows needs.
* fix(cli): local capture reads its files from disk and resolves real paths natively
The asset downloader read the local page server with Node's fetch, which an environment proxy
(NODE_USE_ENV_PROXY with HTTP_PROXY) intercepts, so local images and fonts were dropped. It now
reads the file from disk under the server's own checks.
Root and served paths both use the native realpath. The JS realpath kept Windows 8.3 short names
while fs/promises expanded them, so every file answered 404 on Windows.
The default root is the directory the file was named in, so a symlinked entry can no longer widen
it to wherever the link points.
The local-file docs move below the capture policy text so their heading does not swallow it.
* refactor(cli): capture settles a watchdog outcome in one place
* fix(cli): escape every RegExp metacharacter in the local origin rewriter
---------
Co-authored-by: Jerrai <jerrai@heygen.com>
* fix(cli): snapshot counts and lists the stills that are on disk, and fails when some are not
The summary counted frames the run had captured, not files that exist, and printed paths
relative to the project. It now checks every still on disk, prints absolute paths, says
"N of M" when some are missing or empty, names them, and exits non-zero.
* fix(cli): snapshot says when it clears an earlier run's stills from the folder
Without --keep, a run removes the stills an earlier run left in the folder before it captures,
so two runs into one -o folder silently erased the first. The behaviour stays; the console
and --json now say "cleared N stills from an earlier run in <folder>". The on-disk comment is
also cut to the comment limit.
* fix(cli): snapshot judges the stills it wrote, not the frames it was asked for
A --zoom target that is not visible skips a frame on purpose, with a warning, and that frame never
reaches the written list. Comparing the files on disk with the requested count turned that into a
failed run. Only a written still that is missing or empty fails now.
* test(producer): the stall tests jump fake time to the next timer instead of a second at a time
A 400 s scenario took 400 steps of 50 real event-loop turns plus file IO, which crept
past the unit timeout on a loaded runner. Idle windows now cost one step.
* test(producer): stub the memory sampler so the stall tests' timer jumps skip the idle windows
The sampler is a faked 250 ms interval, so it was the next timer on every jump and the
jump was never longer than 250 ms.
* fix(cli): Kokoro speech works when its espeak data folder path passes 260 characters on Windows
* test(cli): cache test follows the synth script version
Chrome's profile lockfile is held for a moment after the browser exits, so removing the
capture profile threw EBUSY and a finished capture exited 1. The profile and staging
removals now go through a core helper that retries transient locks and, for cleanup of
finished work, warns instead of failing.
* test(producer): probe a variable-bound clip under a host with values
* fix(producer): probe a variable-bound clip its mount or defaults rebind
* style(producer): variable media fixtures in small steps
* test(producer): list the real-render variable mount test in the integration lane
* style(producer): keep probeStage's comment share at the base
* feat(cli): capture can route its traffic through an opt-in upstream proxy
HYPERFRAMES_CAPTURE_PROXY=http://host:port sends the capture browser proxy's
forwarded requests and CONNECT tunnels, and every publicRequest download,
to that proxy by hostname instead of dialing a checked public IPv4. Unset,
behaviour is unchanged.
* fix(cli): keep capture comment share flat and close the new CodeQL findings
Test fixtures record what they receive instead of echoing request data, and
capture --video strips line breaks from a failed download's message before
logging it.
* fix(cli): proxied HTTP downloads send no URL fragment, and a malformed proxy credential is refused
The absolute-form request to the upstream used the URL's href, so a fragment such as
sprite.svg#icon went on the request line, which the pinned path never sends and strict proxies
refuse. A malformed percent-escape in the proxy credentials threw a bare URIError instead of the
usual "not a valid proxy URL" error. The test servers label their echoes text/plain.
* fix(cli): strip line breaks from capture --video errors in the form CodeQL recognizes
* fix(cli): capture --video logs errors through a recognized newline sanitizer
---------
Co-authored-by: Jerrai <jerrai@heygen.com>
* fix(engine): renders on a Mac decode a clip in software when the media engine refuses it
* refactor(engine): name the software decode retry condition instead of commenting it
render, check and snapshot open project history, which looks for a running
preview by probing 100 loopback ports and 5190. Behind an egress fence every
probe is refused and reported. Setting HYPERFRAMES_NO_PREVIEW_DISCOVERY=1 makes
historyDeps.findServer return null without a request, so history opens directly.
Refs #6204
* fix(player): each take plays its own audio when the browser blocks autoplay
* fix(player): a parent audio proxy of a video clip is seeked when its lag holds, not rate-chased
* style(core): keep the steering policy's comment share where it was
* fix(core): a video no longer runs ahead of the playhead or past its out-point
* fix(core): keep a looping video playing when the playhead wraps before it
* perf(aws-lambda): each chunk logs where its seconds went
The chunk_capture event now carries the handler's setup time and the renderer's own stage timings (plan check, browser boot, capture, encode, total), which the renderer already measured but the logs dropped. Lets a fleet run be split into start-up, capture and tail per chunk.
* perf(aws-lambda): chunk logs also time the Chrome path resolution
On the container image the compressed Chrome may be unpacked on every cold chunk; chromeMs separates that from the plan download in setupMs.
* feat(cli): write one diagnostic report when a command stays silent for 60 s
* feat(cli): load the hang report only when it is asked for
* fix(cli): the hang report is written without announcing itself on stderr
* fix(cli): the hang report leaves out environment values or is not written, and is written once
* refactor(cli): shorten the hang report comment to the line limit
* fix(cli): history show --diff works without git on PATH
* fix(cli): unifiedDiff passes lint and fallow: blocks, shared direction rule, split test
* refactor(cli): split the diff walk and its backtrack into small steps
* fix(lint): a media src whose file name holds # or ? says to write it percent-encoded
* refactor(lint): the url-safe hint encodes with the shared encodeUrlPath
* fix(engine): a stalled BeginFrame capture resumes from the first unwritten frame
A wedged worker used to throw away every frame already written and restart the
whole render on a screenshot session. Fresh BeginFrame workers now continue from
the first unwritten frame (once; a second stall still takes the screenshot
fallback), and the stall message names each worker's in-flight frame and step.
Force-closing the wedged Chrome no longer crashes the CLI with an unhandled
pipe ECONNRESET.
* chore(engine): cut the stall-resume comments to the comment limit
The explanations live in the PR body.
* fix(studio): a timeline edit that lands on the clip's own values saves nothing instead of failing
* chore: re-run checks against the updated PR description
* feat(engine): encoders cap peak bitrate and place keyframes on a set interval
* style(engine): shorten the rate-cap comment
* style(engine): drop the doc lines the comment ratchet flagged
* feat(producer): mp4 renders honour a keyframe interval and a peak bitrate cap on every encoder path
* style(producer): shorten the delivery encoder file headers
* style(producer): drop a comment line from the segment manifest
* style(producer): shorten the integration test header
* test: delivery encoder tests follow the ffprobe argv contract and run in the integration lane
* feat: the render request, server and Lambda plan carry the keyframe interval and peak bitrate cap
* fix(studio): the Studio render route passes the keyframe interval and bitrate cap to the encoder
* chore(studio-server): drop a comment the helper's name already says
* feat(cli): render and lambda render take --keyframe-interval, --max-bitrate and --buffer-size
* fix(core): audio clips join on time and their volume lane follows the audio
An incoming <audio> clip is now pre-seeked to its in-point like a video, and
a playing audio element that drifts is steered by rate instead of seeked
while it sounds. A routed clip's volume lane and fades are re-aimed at the
element's own position whenever it starts, is seeked or changes rate.
* fix(core): sounding audio is nudged at most 10%, and a larger lag seeks under a short dip
Speech audibly changes tempo past a 10% rate nudge, and a bare seek clicks.
Audio that holds a lag rate cannot close in about a second is seeked under a
15 ms dip on its routed graph; an unrouted element is seeked plainly. Video
keeps its steps.
* fix(core): a routed clip's automation has one owner, its element, looping included
A rate change re-aimed a routed clip's lane on the context clock and again
when the element took the new rate. Only the element re-aims it now. A
looping element's wrapped position is placed on the pass the transport is in,
so a looping bed's lane follows it too.
* style(core): wrap a steering comment to the line limit
* refactor(core): one drift policy for playing media, exported for the parent proxy
The steering steps, the audio cap and limit, and the steering state move to
runtime/mediaSteer.ts as steerMedia(el, offset, baseRate, settled) and
forgetSteering(el), exported as @hyperframes/core/runtime/media-steer so the
player's parent-frame proxy uses the same policy instead of a second one.
* style(core): trim the drift policy's comments to the package's share
* fix(core): the dipped seek lands on the frame-start media time
Routes the one currentTime write this branch adds through mediaElementTime,
so Chrome's truncated currentTime cannot land it a frame early.
* test(core): expect the plain audio seek at the frame-start media time
* fix(engine): a scratch folder Windows refuses to delete no longer fails a finished audio mix
* fix(engine): audio scratch files Windows refuses to delete no longer fail a render
* fix(engine): a rename Windows keeps refusing falls back to a copy so the audio mix finishes
* fix(engine): audio scratch left behind is counted in the render log
* style(engine): wrap the long rename fallback test call
* refactor(engine): split the rename fallback decision out of the retry loop
* fix(engine): the rename copy fallback is opt-in and scratch leftovers are counted per render
* style(engine): keep renameWithRetry's comment share at the base
* style(engine): drop the blank line left by the comment cut
* fix(producer): compile probes each unique media source once however many elements use it
* test(producer): run the probe-count test in the integration lane
* fix(core): preview seeks land on the composition's own frame rate
* fix(studio): frame step, frame readout and ruler use the composition's frame rate
* fix(studio): an end trim previews the clip's last frame at the composition's frame rate
* refactor(studio): ruler labels follow the ticks' frame rate and fps parsing splits by form
* style(studio): format the ruler label helper and its test
* chore(inspector): raise the package size budget to the measured size plus headroom
* chore(cli): tag the studio download link with where it was shown
The terminal hint, hyperframes open and the browser editor button now add
src=cli or src=browser-editor to the download link. The download route
already records src, so these downloads stop landing in no source.
* chore(cli): drop the DownloadSource doc comment the type name already says
* chore(cli): leave the no-build fallback link untagged, since only the download route reads src
/guides/open-design was folded into design-tools in August and the 4K
guide was retitled "Render in 4K"; Google stopped showing us for "open
design" and "4k render". The titles name them again.
* docs(studio-app): name the Windows app's words, keys and settings folder
The app says PC where a Mac says Mac and takes Ctrl where a Mac takes Cmd;
its settings live in %APPDATA%\HyperFrames. Cut out object here needs the
Mac image engine (Apple silicon, macOS 14+); Remove background runs on any
computer.
* docs(guides): split picture and video cut out requirements
Pictures cut out on Apple silicon with macOS 14+ or Intel with macOS
13.3+ (imageModels.mjs DARWIN_FLOOR); video cut out needs Apple silicon
(imageIpc.mjs models.video checks arm64).
* fix(cli): check and snapshot fail fast on a missing browser path and say while Chrome downloads
* fix(cli): a non-interactive Chrome download gives up after one stall, naming the env var and doctor
Mintlify search keywords on the FAQ (pricing, price, cost, free...) and
the skills guide (npx skills, skills add...). Last week pricing searches
found a clicked result 8% of the time and npx skills 0%.
Miguel Ángel