fix(cli): normalize-audio --reference stops short of the peak ceiling instead of refusing (#7254)

* fix(cli): normalize-audio --reference stops short of the peak ceiling instead of refusing

* docs(cli): the README says normalize-audio stops short of the ceilings instead of refusing
This commit is contained in:
Miguel Ángel
2026-11-05 18:47:49 +00:00
committed by GitHub
parent 8df4f21c20
commit 2f2195515b
6 changed files with 119 additions and 63 deletions
+3 -2
View File
@@ -1007,8 +1007,9 @@ npx hyperframes normalize-audio --reference target-audio --target user-audio --j
`--reference` and `--target` are `<audio>` element ids, with or without `#`.
The reference stays unchanged; the command accounts for both clips' current
`data-volume` and writes the target's absolute matched gain. It measures
`data-media-start` and `data-duration`, rejects remote or out-of-project sources,
and refuses a result that exceeds Studio's +12 dB ceiling or would clip. Dry-run
`data-media-start` and `data-duration` and rejects remote or out-of-project sources.
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. Dry-run
is deliberate: inspect the measurement before passing `--write`. Use
`--tolerance <LU>` to change the default 0.5 LU no-op threshold.
+3 -2
View File
@@ -67,8 +67,9 @@ 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` and refuses unsafe boosts
that exceed Studio's +12 dB ceiling or would clip.
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`
@@ -126,3 +126,38 @@ describe("normalize-audio on a clip inside a mounted scene", () => {
}
});
});
describe("reference normalize-audio command", () => {
it("writes the most gain that stays under -1.5 dBTP and says how far under the reference that leaves it", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-normalize-reference-test-"));
const log = vi.spyOn(console, "log").mockImplementation(() => {});
try {
const path = join(dir, "index.html");
const html =
`<audio id="speaker-opening" src="open.wav" data-volume="1"></audio>` +
`<audio id="speaker-closing" src="close.wav" data-volume="1"></audio>`;
writeFileSync(path, html);
writeFileSync(join(dir, "open.wav"), "audio bytes");
writeFileSync(join(dir, "close.wav"), "audio bytes");
measureAudio
.mockResolvedValueOnce({ integratedLufs: -15, truePeakDbfs: -3 })
.mockResolvedValueOnce({ integratedLufs: -18, truePeakDbfs: -3 });
await runCommand(normalizeAudioCommand, {
rawArgs: [dir, "--reference", "speaker-opening", "--target", "speaker-closing", "--write"],
});
const printed = log.mock.calls.map((call) => String(call[0])).join("\n");
expect(printed).toContain(
"Reaches -16.5 LUFS, 1.5 dB under the reference (stopped short of -1.5 dBTP).",
);
expect(readFileSync(path, "utf8")).toContain(
`<audio id="speaker-closing" src="close.wav" data-volume="1.188502"></audio>`,
);
} finally {
log.mockRestore();
measureAudio.mockReset();
rmSync(dir, { recursive: true, force: true });
}
});
});
@@ -142,22 +142,36 @@ describe("audioNormalizationPlan", () => {
expect(plan.projectedLufs).toBeCloseTo(plan.referenceLufs, 6);
});
it("refuses a gain beyond Studio's +12 dB ceiling", () => {
expect(() =>
audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -5, truePeakDbfs: -1 },
{ id: "target", volume: 1, integratedLufs: -30, truePeakDbfs: -30 },
),
).toThrow(/\+12 dB/i);
it("stops a boost at Studio's +12 dB ceiling and names it", () => {
const plan = audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -5, truePeakDbfs: -1 },
{ id: "target", volume: 1, integratedLufs: -30, truePeakDbfs: -30 },
);
expect(plan.limitedBy).toBe("gain-ceiling");
expect(plan.gainDb).toBeCloseTo(12, 6);
expect(plan.projectedLufs).toBeCloseTo(-18, 6);
});
it("refuses a boost that would clip", () => {
expect(() =>
audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -10, truePeakDbfs: -1 },
{ id: "target", volume: 1, integratedLufs: -15, truePeakDbfs: -2 },
),
).toThrow(/clip/i);
it("stops a boost that would pass -1.5 dBTP there, as the absolute target does", () => {
const plan = audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -10, truePeakDbfs: -1 },
{ id: "target", volume: 1, integratedLufs: -15, truePeakDbfs: -2 },
);
expect(plan.limitedBy).toBe("true-peak");
expect(plan.gainDb).toBeCloseTo(0.5, 6);
expect(plan.projectedTruePeakDbfs).toBeCloseTo(-1.5, 6);
expect(plan.referenceLufs - plan.projectedLufs).toBeCloseTo(4.5, 6);
});
it("names no limit when the match fits", () => {
const plan = audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -15.5, truePeakDbfs: -3.2 },
{ id: "target", volume: 1, integratedLufs: -11.7, truePeakDbfs: -0.2 },
);
expect(plan.limitedBy).toBeNull();
});
});
+14 -7
View File
@@ -190,8 +190,7 @@ async function normalizeAudio(options: NormalizeAudioOptions): Promise<Normalize
tolerance,
);
const filePath = resolve(project.dir, targetTag.file);
const heldByLimit =
plan.mode === "absolute" && targetTag.volume > 0 && absoluteOutcome(plan, tolerance) === "held";
const heldByLimit = targetTag.volume > 0 && heldAtLimit(plan, tolerance);
const wrote = options.write && !withinTolerance && !heldByLimit;
if (wrote) {
writeAtomically(
@@ -202,6 +201,11 @@ async function normalizeAudio(options: NormalizeAudioOptions): Promise<Normalize
return { ok: true, wrote, withinTolerance, tolerance, filePath, ...plan };
}
function heldAtLimit(plan: ModePlan, tolerance: number): boolean {
if (plan.mode === "absolute") return absoluteOutcome(plan, tolerance) === "held";
return plan.limitedBy !== null && Math.abs(plan.changeDb) <= tolerance;
}
const LIMIT_TEXT: Record<LoudnessLimit, string> = {
"gain-ceiling": "stopped at the +12 dB authoring ceiling",
"true-peak": "stopped short of -1.5 dBTP",
@@ -213,6 +217,13 @@ function printMeasuredLine(result: NormalizeAudioResult): void {
`${c.bold(`#${result.referenceId}`)} ${result.referenceLufs.toFixed(1)} LUFS → ` +
`${c.bold(`#${result.targetId}`)} ${result.targetLufs.toFixed(1)} LUFS`,
);
if (result.limitedBy) {
const short = result.referenceLufs - result.projectedLufs;
console.log(
`Reaches ${result.projectedLufs.toFixed(1)} LUFS, ${short.toFixed(1)} dB under the reference ` +
`(${LIMIT_TEXT[result.limitedBy]}).`,
);
}
return;
}
const limit = result.limitedBy ? ` (${LIMIT_TEXT[result.limitedBy]})` : "";
@@ -231,11 +242,7 @@ function printHumanResult(result: NormalizeAudioResult): void {
return;
}
if (
result.mode === "absolute" &&
result.previousVolume > 0 &&
absoluteOutcome(result, result.tolerance) === "held"
) {
if (result.previousVolume > 0 && heldAtLimit(result, result.tolerance)) {
console.log(c.dim("Cannot get closer to the target; the gain is unchanged."));
return;
}
+36 -38
View File
@@ -74,6 +74,7 @@ export interface AudioNormalizationPlan {
changeDb: number;
projectedLufs: number;
projectedTruePeakDbfs: number;
limitedBy: LoudnessLimit | null;
}
function authoredNumber(
@@ -381,7 +382,7 @@ export function gainDb(volume: number): number {
return volume > 0 ? 20 * Math.log10(volume) : Number.NEGATIVE_INFINITY;
}
/** Calculate the target's absolute authored gain while keeping the reference unchanged. */
/** The target's gain that matches the reference's played loudness; past a ceiling it stops as fittedGain does. */
export function audioNormalizationPlan(
referenceTrack: NormalizationTrack,
targetTrack: NormalizationTrack,
@@ -391,32 +392,24 @@ export function audioNormalizationPlan(
}
const referenceLufs = referenceTrack.integratedLufs + gainDb(referenceTrack.volume);
const targetLufs = targetTrack.integratedLufs + gainDb(targetTrack.volume);
const wantedGainDb = referenceLufs - targetTrack.integratedLufs;
if (wantedGainDb > MAX_AUDIO_GAIN_DB + 1e-9) {
throw new Error(
`Matching #${targetTrack.id} needs ${wantedGainDb.toFixed(1)} dB, beyond the +${MAX_AUDIO_GAIN_DB} dB authoring ceiling. ` +
`A gap this large belongs in the source file, not the mixer: mixer gain raises the noise floor with the signal. ` +
`Normalize ${targetTrack.id}'s asset offline (e.g. ffmpeg loudnorm), or lower #${referenceTrack.id} instead.`,
);
}
const volume = 10 ** (wantedGainDb / 20);
const projectedTruePeakDbfs = targetTrack.truePeakDbfs + wantedGainDb;
if (projectedTruePeakDbfs > 0) {
throw new Error(
`Matching #${targetTrack.id} would clip at +${projectedTruePeakDbfs.toFixed(1)} dBFS; limit or preprocess the source first`,
);
}
const previousGainDb = gainDb(targetTrack.volume);
const { appliedGainDb, limitedBy } = fittedGain(
referenceLufs - targetTrack.integratedLufs,
targetTrack.truePeakDbfs,
previousGainDb,
);
return {
referenceId: referenceTrack.id,
targetId: targetTrack.id,
referenceLufs,
targetLufs,
previousVolume: targetTrack.volume,
volume,
gainDb: wantedGainDb,
changeDb: wantedGainDb - gainDb(targetTrack.volume),
projectedLufs: targetTrack.integratedLufs + wantedGainDb,
projectedTruePeakDbfs,
volume: 10 ** (appliedGainDb / 20),
gainDb: appliedGainDb,
changeDb: appliedGainDb - previousGainDb,
projectedLufs: targetTrack.integratedLufs + appliedGainDb,
projectedTruePeakDbfs: targetTrack.truePeakDbfs + appliedGainDb,
limitedBy,
};
}
@@ -522,9 +515,8 @@ export interface AbsoluteLoudnessPlan {
/**
* The authored gain that brings one clip's played window to an absolute
* loudness. Unlike reference matching it never refuses: past the +12 dB
* authoring ceiling or the true-peak ceiling it applies the most that fits and
* names which limit stopped it.
* loudness; past the +12 dB authoring ceiling or the true-peak ceiling it
* applies the most that fits and names which limit stopped it (fittedGain).
*/
export function absoluteLoudnessPlan(
track: NormalizationTrack,
@@ -533,21 +525,12 @@ export function absoluteLoudnessPlan(
if (track.integratedLufs <= SILENCE_LUFS) {
throw new Error(`#${track.id} is silent in the played window; there is nothing to normalize`);
}
const wantedGainDb = targetLufs - track.integratedLufs;
const peakRoomDb = NORMALIZE_TRUE_PEAK_CEILING_DBFS - track.truePeakDbfs;
const limits: Array<[LoudnessLimit | null, number]> = [
[null, wantedGainDb],
["gain-ceiling", MAX_AUDIO_GAIN_DB],
["true-peak", peakRoomDb],
];
const [limitedBy, limitedGainDb] = limits.reduce((lowest, candidate) =>
candidate[1] < lowest[1] - 1e-9 ? candidate : lowest,
);
const previousGainDb = track.volume > 0 ? gainDb(track.volume) : 0;
const limitCannotCutAWantedBoost = wantedGainDb > previousGainDb;
const appliedGainDb = limitCannotCutAWantedBoost
? Math.max(limitedGainDb, previousGainDb)
: limitedGainDb;
const { appliedGainDb, limitedBy } = fittedGain(
targetLufs - track.integratedLufs,
track.truePeakDbfs,
previousGainDb,
);
return {
targetId: track.id,
targetLufs,
@@ -562,6 +545,21 @@ export function absoluteLoudnessPlan(
};
}
/** The most of `wantedGainDb` under both ceilings and the limit that stopped it; never cuts a gain asked to rise. */
function fittedGain(wantedGainDb: number, truePeakDbfs: number, previousGainDb: number) {
const limits: Array<[LoudnessLimit | null, number]> = [
[null, wantedGainDb],
["gain-ceiling", MAX_AUDIO_GAIN_DB],
["true-peak", NORMALIZE_TRUE_PEAK_CEILING_DBFS - truePeakDbfs],
];
const [limitedBy, limitedGainDb] = limits.reduce((lowest, candidate) =>
candidate[1] < lowest[1] - 1e-9 ? candidate : lowest,
);
const appliedGainDb =
wantedGainDb > previousGainDb ? Math.max(limitedGainDb, previousGainDb) : limitedGainDb;
return { appliedGainDb, limitedBy };
}
export type AbsoluteOutcome = "matched" | "held" | "change";
export function absoluteOutcome(plan: AbsoluteLoudnessPlan, tolerance: number): AbsoluteOutcome {