feat(cli): add normalize-audio to match one clip's loudness to another

[miguel-heygen]

Measures two authored <audio> clips with FFmpeg's integrated EBU R128 loudness and writes the target's matching data-volume, leaving the reference untouched. Dry run by default; --write persists.

npx hyperframes normalize-audio --reference bed --target vo
npx hyperframes normalize-audio --reference bed --target vo --write
npx hyperframes normalize-audio --reference bed --target vo --json

Measuring the window the composition actually plays

Two ways to get this wrong, both of which produce a plausible-but-wrong gain:

• data-end bounds a clip's timeline window just as data-duration does. The parser, the runtime and the render mixer all honour it.
• -ss / -t belong before -i. After it they bound the output, and with -f null there is no output worth bounding — ffmpeg keeps feeding the filter graph and ebur128 integrates audio the clip never plays.

On a fixture whose played window is −61.8 LUFS inside a file that measures −27.9 LUFS whole, either mistake reports the wrong number and --write "corrects" an already-matched clip by tens of dB.

Writing safely

Two EBU R128 passes run between reading the composition and writing it, each bounded only by a two-minute timeout, and the skill docs tell agents to keep Studio open on the project meanwhile. The attribute patch is re-applied to a fresh read and written through a temp file and a rename, so a concurrent Studio edit is not reverted and a crash cannot leave a half-written composition.

Agent contract

Under --json the failures are documents too — an agent doing JSON.parse(stdout) on a bare error line throws. The command is registered in the curated --help listing so an agent enumerating capabilities can discover it.

A pair needing more than the +12 dB authoring ceiling has a source-file problem rather than a mixer one — mixer gain raises the noise floor with the signal — so the refusal names the remedy instead of just declining.

Stack

Based on u1-audio-gain-core, whose shared gain module it imports. Retarget to main before merging. Independent of u2-studio-gain-surface; the two may land in either order.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Aug 19, 2026, 12:11 AM

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

[jrusso1020]

Reviewed at 585ede92, full pass — nothing else was posted when I started. Read normalize-audio.ts end to end plus its tests, and resolved the attribute question against the schema doc rather than against the diff.

Strengths

• The -ss/-t-before--i note is the good kind of comment (normalize-audio.ts:390-398): it states the wrong behaviour, the right behaviour, and the measurement that separates them (-33.8 vs -61.8 LUFS on the same window). That is a comment the next person cannot accidentally undo.
• data-end as a first-class trim (authoredDuration, :209-218) is the non-obvious half of "measure what the composition plays", and it is covered in both directions plus the degenerate case (normalize-audio.test.ts:45-68, including data-end not outlasting its start).
• The write path takes concurrency seriously and says why (:494-513): re-reading before patching because two ffmpeg passes have elapsed, temp-file-plus-rename so a crash cannot truncate a composition, and a one-attribute patch so scripts and comments stay byte-stable.
• --json failures are documents too (:404-409). A command built for agents that emits a bare error line on stderr breaks every caller doing JSON.parse(stdout); getting this right up front is cheaper than retrofitting it.

Nit

--tolerance is validated after the expensive work. normalizeAudio (:496-499) calls measuredPlan(...) and only then parsedTolerance(options.tolerance). So --tolerance nonsense spends up to two 120-second ffmpeg passes before failing on an argument that could have been rejected immediately. Hoisting the parsedTolerance call above measuredPlan is the whole fix.

Notes (checked, no action needed — published so nobody re-derives them)

• Reading only data-media-start is correct here, and I nearly filed it as a bug. readMediaStart in packages/core/src/runtime/playbackRate.ts:21-30 gives data-playback-start precedence, which reads like a supported alias this command ignores. It is not the right ceiling for this path: docs/reference/html-schema.mdx:125 states that the engine's audio mixer — the thing that feeds ffmpeg -ss — reads only data-media-start, and that <audio> should use exactly that name. Since the point is matching loudness in the render, agreeing with the mixer is right. Flagging it because it is the first thing a reviewer working from playbackRate.ts will report.
• Silence and clipping are both already guarded, so the usual two failure modes for a loudness matcher are closed: muted input is rejected (:307-309, and !(volume > 0) catches NaN as well as 0), the boost ceiling is refused with the remedy named rather than silently clamped (:313-320), and the projected true peak is checked before anything is written (:323-328). A near-silent reference still resolves to a large attenuation rather than an error, which is arguably what "match this" means — and it cannot reach a hard mute, since ebur128 floors around -70 LUFS and formatAudioGain keeps six decimals, so the written value stays above zero.
• resolveLocalAudioPath (:263-283) rejects absolute paths, URL schemes, protocol-relative sources and .. traversal, and handles the malformed-percent-encoding case explicitly.
• The body says to retarget to main. Already done — base is main, one commit ahead, and the gain module it imports is present there.

Merge order — worth coordinating with #3305

This PR and #3305 both rewrite the hyperframes-audio entry in skills-manifest.json, both starting from c96ccac4b1127b8c. Same line, different values, so whichever merges second hits a real conflict.

Regenerate rather than picking a side: your references/diagnosis.md and #3305's SKILL.md are both inside that one bundle, so once both are on main the correct hash is a third value neither PR carries. Picking a side fails quietly — the sync check runs on pull requests, so nothing on main's tip goes red, and the drift only surfaces on the next PR that touches the skill.

Verdict: APPROVE
Reasoning: The measurement window, the refusal cases and the write path are all correct and independently checked; the only finding is a one-line reordering of argument validation.

— Rames Jusso

[terencecho]

Well-scoped LUFS matcher; math and edge-handling both hold up.

• Effective-loudness math (audioNormalizationPlan): wantedGainDb = referenceLufs - target.integratedLufs correctly makes the target's effective LUFS equal the reference's effective LUFS (accounting for both clips' current data-volume).
• Windowing (loudnessMeasureArgs): -ss/-t before -i — critical when using -f null, and the unit test pins that ordering; also honors data-end via authoredDuration, so a trimmed clip is measured on the window that actually plays.
• Clip guard: rejects gains whose true-peak projection exceeds 0 dBFS, using ebur128=peak=true (true peak, not sample peak) — the right thing.
• Ceiling: wantedGainDb > MAX_AUDIO_GAIN_DB is on the absolute authored gain (not the delta), which matches the shared Studio/render ceiling, and error copy correctly points at source-file preprocessing rather than trying to save it in the mixer.
• Locale: parseEbur128Summary scrapes I: / Peak: from the ebur128 C-format summary — locale-independent (unlike, e.g., loudnorm state strings), so no fail-open on non-English Windows.
• Path safety (resolveLocalAudioPath): remote, absolute, and .. traversal all rejected; Windows separator is handled.
• Concurrency: re-reads index.html after the ~2 min measurement window before applying the one-attribute patch, then atomic temp-file + rename — a Studio edit made during measurement is preserved.
• Agent contract: --json mode also emits errors as parseable documents, and command is registered in the curated --help grouping so agents enumerating capabilities discover it.

CI green including Windows render / tests / CLI-npx smoke.

[miguel-heygen]

Nit fixed — parsedTolerance now runs before measuredPlan rather than after it. Confirmed the cost you described: two EBU R128 passes, each bounded at 120s, both spent before failing on an argument that was wrong from the start.

Being straight about coverage: it isn't pinned by a test. The ordering is internal to normalizeAudio and neither it nor parsedTolerance is exported, so covering it would mean restructuring for a spy rather than asserting a behaviour. Happy to do that if you'd rather it were pinned.

Manifest collision, confirmed: this PR and #3305 both rewrite the hyperframes-audio hash c96ccac4b1127b8c — to 6bdb36e157... here and 1c01419737... there. Whichever lands second takes the conflict, and neither value is right afterwards since the two edit different files inside the same bundle. I'll regenerate with bun packages/cli/scripts/gen-skills-manifest.ts on the second one instead of resolving by hand.

Thanks for going after the failure modes rather than the diff — muted input, the boost ceiling refusing with a remedy instead of clamping, and the true-peak check before any write were the three I most wanted a second pair of eyes on.

[somanshreddy]

Independent pass — verified the two headline correctness points by re-execution. Reads clean; nits + one test gap, no blockers.

What I verified at the execution layer

• -ss/-t before -i. loudnessMeasureArgs pushes -ss/-t (input-side) then -i file … -af ebur128=peak=true -f null - — so ebur128 integrates only the played window, not the whole file. Pinned by the indexOf("-ss") < indexOf("-i") test.
• Window = data-duration, else data-end−data-start, seeking data-media-start. authoredDuration prefers data-duration, falls back to end − start; -ss uses mediaStart. I confirmed this matches the render mixer's own windowing in producer/src/services/audioExtractor.ts (extractAudioTrack derives duration identically and seeks by element.mediaStart) — so the measured window is exactly what renders. This parity is the subtle thing that makes the gain correct, and it holds.
• Gain math. wantedGainDb = referenceLufs − target.integratedLufs (absolute, measured from the target's raw integrated loudness → the written data-volume is absolute, not compounded), volume = 10^(wantedGainDb/20). I re-ran the plan in Node for the test vectors and a boosted-input case; results match (-3.8 dB → 0.645654, projected peak/LUFS correct). The +12 dB ceiling (dB) and formatAudioGain's linear clamp (MAX_AUDIO_GAIN = 3.981) agree exactly, so a passing plan is never silently clamped; muted input and projected-clip are refused before any write with the remedy named — matching Rames's read.
• Dry-run never mutates; --write gates on write && !withinTolerance and writes atomically (temp + rename).

Nits (non-blocking)

1. Agree with Rames: hoist --tolerance parsing. Confirmed measuredPlan() runs both ~120s FFmpeg passes before parsedTolerance() validates the argument — a bad --tolerance wastes up to ~4 min before failing on a pure arg error. Validate it first.
2. Orchestration is untested. The pure helpers (loudnessMeasureArgs, audioNormalizationPlan, authoredDuration) are well covered, but normalizeAudio() itself — dry-run-does-not-write, --write writes, withinTolerance skips, the deliberate re-read-of-index.html-before-write (so a Studio edit during the two FFmpeg passes isn't clobbered), and the --json failure envelope — has no test. Those are the riskiest lines; a fake-ffmpeg orchestration test would pin the safety contract.
3. Docs artifact: the cli.mdx insertion re-emits ## Look at it, producing a duplicated heading, and files normalize-audio under it while the summary table correctly lists it under "Bring in source material".

Solid PR — the measurement correctness (the easy thing to get subtly wrong) is right and, importantly, matches the render path.

[jrusso1020]

Re-review at 5cd1d5b8. My earlier APPROVED sits at 585ede92 and no longer speaks to this head. The --tolerance hoist is correct; the reason I'm not re-approving yet is CI, and it's one file.

The nit is closed, and the hoist is safe

parsedTolerance (packages/cli/src/commands/normalize-audio.ts:486) is a pure validator — it reads options.tolerance, throws on non-finite or negative, and touches nothing the measurement produces. So moving it above measuredPlan has no dependency to get wrong, and a typo'd --tolerance now fails before the two 120s EBU R128 passes instead of after them. Exactly the change I asked for.

On your coverage note: I wouldn't restructure for a spy. The ordering isn't user-observable except as elapsed time, so a spy asserting call order would pin the implementation rather than the behaviour, and it'd be the kind of test that breaks on the next refactor while proving nothing. The coverage worth having is the one @somanshreddy named — the normalizeAudio orchestration paths (dry-run vs --write, within-tolerance short-circuit, the re-read before write, --json on failure). Those are user-observable, and a fixture project driven through the command end-to-end reaches them without exporting anything or introducing a spy. That's an important-tier gap, not a blocker.

Why three checks are red — one file, one command (net-new)

Format, Preflight (lint + format) (both runs) and preview-regression are all red, and they are all the same cause:

$ oxfmt --check .
packages/cli/README.md (45ms)
Format issues found in above 1 files. Run without `--check` to fix.

One file. The cascade from it is worth spelling out because preview-regression reads like a preview bug and isn't one:

1. packages/cli/README.md isn't oxfmt-formatted → Format and Preflight (lint + format) fail.
2. preview-parity declares needs: [changes, preflight] (.github/workflows/preview-regression.yml:64), so the failed preflight skips it.
3. The preview-regression gate then runs with PREVIEW_FILTER_RESULT: true and PREVIEW_PARITY_RESULT: skipped, and its test is != "success" → exit 1. It's failing closed on a check that never ran, which is the right behaviour for a gate — it just isn't a preview defect.

The part that actually matters: the same needs chain means the required Test context was never created at this head. Not failing — absent. I diffed the required set against what exists:

required contexts: 8
--- 3306 @ 5cd1d5b8 ---  NEVER RAN: Test
--- 3310 @ dfca6186  ---  all required contexts present

So there is currently no test signal on 5cd1d5b8 at all, and the merge gate can't clear on reviews alone while a required context is missing. regression did run and passed; Test is the hole. bun run format (or oxfmt packages/cli/README.md) fixes the file, and preflight, Test, preview-parity and preview-regression all follow from it.

nit — the same coercion that caused the #3305 blocker, benignly

parsedTolerance uses Number(raw), and Number("") is 0, which is finite and not negative. So --tolerance "" is accepted as "require an exact match" rather than rejected. It's the same Number()-on-empty family as the data-volume bug on #3305, just harmless here since nobody passes an empty string on purpose. A raw.trim() === "" guard closes it if you're touching the function anyway.

Confirmed, not re-litigated

• Input-side -ss/-t: verified at source myself — extractAudioTrack pushes both before -i (packages/producer/src/services/audioExtractor.ts:130-138), so the render path seeks rather than decode-and-discards.
• @somanshreddy separately verified that the measurement window equals the mixer's window, and re-ran the gain plan against the test vectors. I'm citing that rather than restating it — it's their verification, not mine.
• The muted-input, +12 dB ceiling and true-peak-before-write guards I checked last round are unchanged by this commit.

Merge order

Your plan is the right one, and it's still live on the audio bundle: main has hyperframes-audio at c96ccac4b1127b8c, this PR moves it to 6bdb36e157..., #3305 moves it to 1c01419737.... #3310's half already resolved itself — it landed, and #3305 regenerated on top of it in bc757a8d rather than hand-picking. Same treatment here for whichever of the two goes second.

Verdict: COMMENT — the code change is right and my nit is closed, but I'm not stamping a head where the required Test context never ran. Format the one file and I'll re-review; I expect to approve.

— Rames Jusso

[miguel-heygen]

The format failure was mine and the trace is exactly right — thank you for following the chain rather than stopping at the red check.

packages/cli/README.md lost a blank line between the preview prose and the new ### normalize-audio heading. It happened when I resolved this PR's rebase against the just-merged #3310: both branches added CLI sections to the same docs, I resolved by hand, and never let the formatter near the result. Fixed and pushed; oxfmt --check is clean on the tracked tree now.

Two things from your read I want to acknowledge rather than gloss:

preview-regression reading as a preview defect. It isn't one. Preflight fails → preview-parity is needs-dependent so it skips → the gate tests != "success" and fails closed on the skip. You also checked whether #3310 introduced that gate and confirmed it never touched .github/. That saved the obvious wrong conclusion, which was mine to draw.

The absent Test context is the part that actually mattered. Same needs chain, so it was never created — not failing, missing. A merge gate that can't clear on reviews alone is the safe direction, but it means my "41 checks passing" reading of this PR was reporting on a run with no test signal in it. I'd been treating check counts as evidence; they weren't.

Coverage gap — agreed, and it's the right one. normalizeAudio() orchestration (dry-run vs --write, tolerance no-op, the re-read before write, --json failure envelope) is untested, and those are the riskiest lines in the file. It's also why the --tolerance hoist isn't pinned: nothing there is exported, so covering either means restructuring for injection. I'd rather do that as a follow-up than bolt a spy onto this PR — say the word if you'd sooner have it here.

The hyperframes-audio hash still collides with #3305. Whichever of us lands second, I regenerate with bun packages/cli/scripts/gen-skills-manifest.ts rather than resolving by hand — on #3305 just now that produced f6516b74cb6e5d58 for hyperframes-core, a third value neither branch carried, which is the concrete version of your point.