[miguel-heygen]

What

hyperframes render now warns when it lowered the whole mix, and says how to keep the level. The render still completes as before.

Why

Export keeps the delivered file under -1 dBTP. If a peak passes that, it lowers the whole file by one flat amount, quiet passages included. On the CLI the only trace was an INFO log line among the render's output, so a mix several dB quieter looked like a limiter bug.

A limiter node makes this easy to hit: it compares a smoothed level with its ceiling, so a fast peak can pass untouched and the delivery step then cuts everything. In real exports with a -2 dB limiter, a quiet steady tone with short loud bursts came out lowered by 1.2 dB with one clip and 7.3 dB with two overlapping clips. A truepeak node at -3 on the same two clips caused no cut.

Related work

The Studio export panel already shows this cut from the same audioLoweredDb; this brings the CLI level with it. Replacing the flat cut with a true-peak limit is a follow-up PR.

How

• audioLoweredWarning (in packages/cli/src/utils/) words the cut as an audio_lowered warning.
• renderLocal prints it and adds it to the result's warnings. outcome stays completed, so --no-best-effort does not start failing these renders.
• docs/reference/audio-effects.mdx now says what export does above the ceiling, and points to truepeak rather than limiter for holding the sum.
• Not changed: how any export sounds. The Docker render path has no job state here and prints nothing new.

Test plan

• Unit tests added: audioLoweredWarning.test.ts, and warns that the whole mix was lowered, and the render still completes in render.test.ts.
• fails without the fix: packages/cli/src/commands/render.test.ts › renderLocal browser GPU config › warns that the whole mix was lowered, and the render still completes
• Removing the print fails it; removing the result entry fails it.
• packages/cli: both test files passed 3 runs in a row (116 tests); tsc --noEmit clean; oxlint and oxfmt on the changed files.
• Manual testing performed: real hyperframes render runs on Linux. A film whose mix was cut printed [audio_lowered] Audio lowered 7.3 dB across the whole mix… and exited 0. A film with no cut printed nothing new.
• Comments follow CONTRIBUTING.md "Comments"

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 1, 2026, 4:19 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 120 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (2)

• seqrotatenudge-none-pct-r0-root-z100: tracking 0.03, pressJump 0, drop 0, reload 3.03, render 0.04, renderKey -, undo false, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.08, renderKey -, undo true, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.08, renderKey -, undo true, teleport true
• seqplainkeys-none-px-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

[heygengenesis]

Approving at a36890ac. I found no blocker.

• Fails without the fix: I put main's render.ts back and the named test renderLocal browser GPU config › warns that the whole mix was lowered, and the render still completes failed (expected "warn" to be called…). With the PR, render.test.ts and audioLoweredWarning.test.ts both pass (116/116).
• Contract: the producer sets audioLoweredDb only when it actually applied a cut (enforceAacTruePeak returns loweredDb only on the corrected path), so renders with no cut print nothing. outcome stays completed, and nothing in the CLI reads the returned warnings in a way that would flip exit status or --no-best-effort.
• Docs: the -1 dBTP claim matches AAC_DELIVERY_TRUE_PEAK_DBFS = -1, and the truepeak ceiling range (−24–0) allows the suggested -3.

Nit (non-blocking): a cut between 0 and 0.05 dB would print as "0.0 dB". The correction headroom probably makes that unreachable.