mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
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:
@@ -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.
|
||||
|
||||
|
||||
@@ -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();
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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 {
|
||||
|
||||
Reference in New Issue
Block a user