Skip to content

Commit f9e8cab

Browse files
fix(cli): a render says when it lowered the whole mix, and how to keep the level (#6938)
1 parent aa77770 commit f9e8cab

5 files changed

Lines changed: 64 additions & 4 deletions

File tree

‎docs/reference/audio-effects.mdx‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -143,9 +143,13 @@ the others down.
143143
- `data-volume`, a `volume` lane, fades and a group fader each scale only their
144144
own track or group. Doubling a voice moves the voice +6 dB; how much the whole
145145
mix moves depends on what else is playing at that moment.
146-
- Nothing limits the sum. Loud tracks that overlap can pass 0 dBFS and clip in
147-
the exported AAC. Leave headroom, or put a `limiter` or `truepeak` on the
148-
[master bus](#the-master-bus-data-fx-chain-on-the-composition-root).
146+
- Nothing limits the sum. Loud tracks that overlap can pass 0 dBFS. Leave headroom,
147+
or put a `truepeak` on the
148+
[master bus](#the-master-bus-data-fx-chain-on-the-composition-root); a `limiter`
149+
can let fast peaks through.
150+
- Export keeps the delivered file under -1 dBTP. If a peak passes that, it lowers
151+
the **whole mix** by one flat amount, quiet passages included, and the CLI prints
152+
an `audio_lowered` warning.
149153
- The render's master gain, `PRODUCER_AUDIO_GAIN` (default `1`), multiplies the
150154
finished sum once, before the master bus chain.
151155
- To check a level, compare the export against its source scaled by the

‎packages/cli/src/commands/render.test.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -534,6 +534,29 @@ describe("renderLocal browser GPU config", () => {
534534
expect(cpuSamplerState.samplers.map((s) => s.stopped)).toEqual([true, true]);
535535
});
536536

537+
it("warns that the whole mix was lowered, and the render still completes", async () => {
538+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
539+
producerState.executeImpl = async (job: { audioLoweredDb?: number }) => {
540+
job.audioLoweredDb = 7.3;
541+
};
542+
543+
const result = await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
544+
fps: { num: 30, den: 1 },
545+
quality: "standard",
546+
format: "mp4",
547+
gpu: false,
548+
browserGpuMode: "software",
549+
hdrMode: "auto",
550+
quiet: true,
551+
throwOnError: true,
552+
});
553+
554+
expect(warn).toHaveBeenCalledWith(expect.stringContaining("[audio_lowered] Audio lowered 7.3"));
555+
expect(result?.outcome).toBe("completed");
556+
expect(result?.warnings?.map((warning) => warning.code)).toEqual(["audio_lowered"]);
557+
warn.mockRestore();
558+
});
559+
537560
it("cleans orphaned browser trees before starting a local render", async () => {
538561
orphanCleanupState.killed = 1;
539562

‎packages/cli/src/commands/render.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ import { macosOldChromeCrashRemediation } from "../browser/macosOldChromeCrash.j
137137
import { windowsChromeCrashRemediation } from "../browser/windowsCrash.js";
138138
import { killOrphanedProcessesForRender } from "../utils/orphanCleanup.js";
139139
import { createRenderCancellationScope } from "../utils/renderCancellation.js";
140+
import { audioLoweredWarning } from "../utils/audioLoweredWarning.js";
140141
import {
141142
markRenderSucceeded,
142143
runPostRenderStep,
@@ -1254,6 +1255,8 @@ async function executeLocalRender(
12541255
console.warn(c.warn(` [${warning.code}] ${warning.message}`));
12551256
}
12561257
}
1258+
const audioLowered = audioLoweredWarning(job.audioLoweredDb);
1259+
if (audioLowered) console.warn(c.warn(` [${audioLowered.code}] ${audioLowered.message}`));
12571260
runPostRenderStep("trackRenderMetrics", () =>
12581261
trackRenderMetrics(job, elapsed, options, false, cpuUsage),
12591262
);
@@ -1290,7 +1293,10 @@ async function executeLocalRender(
12901293
renderTimeMs: elapsed,
12911294
durationMs,
12921295
outcome,
1293-
warnings: job.warnings.map((warning) => ({ code: warning.code, message: warning.message })),
1296+
warnings: [
1297+
...job.warnings.map((warning) => ({ code: warning.code, message: warning.message })),
1298+
...(audioLowered ? [audioLowered] : []),
1299+
],
12941300
};
12951301
}
12961302

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
import { describe, expect, it } from "vitest";
2+
import { audioLoweredWarning } from "./audioLoweredWarning";
3+
4+
describe("audioLoweredWarning", () => {
5+
it("names the cut and the fix", () => {
6+
const warning = audioLoweredWarning(7.3);
7+
expect(warning?.code).toBe("audio_lowered");
8+
expect(warning?.message).toContain("7.3 dB across the whole mix");
9+
expect(warning?.message).toContain("truepeak");
10+
});
11+
12+
it("says nothing when the mix was not lowered", () => {
13+
expect(audioLoweredWarning(undefined)).toBeNull();
14+
});
15+
});
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
/** The delivery step's flat cut to the whole mix, in words: it changes every quiet passage, so it is not a log line. */
2+
export function audioLoweredWarning(
3+
audioLoweredDb: number | undefined,
4+
): { code: string; message: string } | null {
5+
if (audioLoweredDb === undefined) return null;
6+
return {
7+
code: "audio_lowered",
8+
message:
9+
`Audio lowered ${audioLoweredDb.toFixed(1)} dB across the whole mix, because a peak passed the delivery ceiling. ` +
10+
"To keep the level, put a truepeak limiter with its ceiling at -3 on the mix; a limiter node can let fast peaks through.",
11+
};
12+
}

0 commit comments

Comments
 (0)