[miguel-heygen]

What

hyperframes normalize-audio --reference <a> --target <b> --write no longer refuses when a full match would push the target past Studio's ceilings. It applies the most gain that fits under -1.5 dBTP and the +12 dB authoring ceiling, writes it, and says how far under the reference that leaves the target:

#speaker-opening -15.0 LUFS → #speaker-closing -18.0 LUFS
Reaches -16.5 LUFS, 1.5 dB under the reference (stopped short of -1.5 dBTP).

Why

A report: matching a closing speaker to the opening one refused the write with "Matching #speaker-closing would clip at +1.5 dBFS; limit or preprocess the source first". The absolute mode of the same command (--target with a LUFS goal) already handles this case another way: it never refuses, stops at the same ceilings, and names the limit. One command had two rules for one constraint, and the stricter one left the person with an error and nothing written.

How

• One rule, one owner: fittedGain in loudness.ts picks the most of the wanted gain under both ceilings and names the limit that stopped it. absoluteLoudnessPlan and audioNormalizationPlan both call it. A limit still never cuts gain already authored when the wish is a boost.
• audioNormalizationPlan returns limitedBy like the absolute plan, so --json carries it too.
• The CLI prints how far under the reference the target lands, and leaves the file alone when a limit leaves no gain to change ("Cannot get closer", as the absolute mode does).
• docs/packages/cli.mdx and the CLI README say what the command does now instead of "refuses".
• A match whose peak lands between -1.5 and 0 dBTP used to be written in full; it now stops at -1.5 dBTP, the ceiling the absolute mode already keeps.

Test plan

• Unit tests added/updated

• Manual testing performed

• Documentation updated (if applicable)

• Comments follow CONTRIBUTING.md "Comments": they say why, not what, and a bug fix says what the code must do and how to reproduce the bug

• fails without the fix: with main's loudness.ts and normalize-audio.ts, the 4 new tests fail: "writes the most gain that stays under -1.5 dBTP and says how far under the reference that leaves it" (the command, with --write: the printed line and the written data-volume="1.188502"), "stops a boost at Studio's +12 dB ceiling and names it", "stops a boost that would pass -1.5 dBTP there, as the absolute target does", "names no limit when the match fits". All pass here.

• 3 runs in a row: normalize-audio.test.ts and normalize-audio.command.test.ts (35 tests), and studio-server's loudness.test.ts (47), whose absolute-plan tests now run through the shared fittedGain. oxfmt --check, the comment ratchet and tsc for studio-server clean. The CLI's tsc reports only 5 errors in checkFindingInspect and checkTypes, which import @hyperframes/inspector (not built in that tree); this PR doesn't touch them.

• Not covered: a run on a real recording; the measurement step is mocked in the command test, as the existing command tests do.

[mintlify]

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

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 5, 2026, 6:10 PM

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

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 1 nit · head d40aa021

• nit: packages/cli/README.md:70-71 still says the command "refuses unsafe boosts that exceed Studio's +12 dB ceiling or would clip". docs/packages/cli.mdx got the new wording, but the README didn't, so it now describes the old behavior.

Scope

Read the whole diff, plus normalizeAudio, plannedNormalization and absoluteOutcome. fittedGain gives the same result as the absolute-mode reduce it replaces. With previousGainDb = -Infinity (volume 0), the boost guard is a no-op, so applied = limited. The "under the reference" figure can't go negative, because applied ≤ wanted on both the boost and cut branches. The reference-mode heldAtLimit matches absoluteOutcome === "held" under the !withinTolerance gate. No other callers of audioNormalizationPlan exist outside the CLI. Intended behavior change: matches that land between -1.5 and 0 dBTP used to be written in full and now stop at -1.5 dBTP; the docs cover this.

Fails-without-fix check: with main's loudness.ts and normalize-audio.ts, the 4 named tests fail and the other 31 pass. At head, all 35 CLI tests and 47 studio-server loudness.test.ts tests pass. CI was still running at review time (CI, Docs, CodeQL, Windows render); nothing had failed.

— Genesis V2 reviewer

[heygengenesis]

Verdict: APPROVE — 1 resolved, 0 open, 0 new · d40aa021 → d2b6f0cb (README-only change, rewording to match cli.mdx; same base). Nothing has failed in CI so far.

[github-actions]

Edit accuracy: accurate 267 (base branch 267), smooth 107 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 (8)

• seqplainkeys-none-center-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): fail / pass / pass, passes
• seqplainkeys-none-center-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-center-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-pct-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-pct-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-px-r30-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run

Unstable (2)

• 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
• seqab-none-center-r0-root-z100: tracking 0.03, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true