Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

fix(editor): keep the preview's boosted audio from clipping at the speakers

EtienneLescot9446101ba431
diff --git a/src/components/ai-edition/VirtualPreview.audio.test.ts b/src/components/ai-edition/VirtualPreview.audio.test.ts
index fdd6cac58..d87e65816 100644
--- a/src/components/ai-edition/VirtualPreview.audio.test.ts
+++ b/src/components/ai-edition/VirtualPreview.audio.test.ts
@@ -5,7 +5,10 @@ import {
applyPreviewAudioSettings,
MUSIC_DUCK,
nextMusicDuckDb,
+ PREVIEW_AUDIO_CEILING,
+ PREVIEW_AUDIO_HEADROOM,
type PreviewAudioGraph,
+ previewCeilingCurve,
resolveAudioTrackPlayback,
resolveTimelineAudioPlayback,
timelineAudioFadeAt,
@@ -18,6 +21,8 @@ function fakeGraph(): PreviewAudioGraph {
gain: { gain: { value: Number.NaN } } as GainNode,
voice: { gain: { value: Number.NaN } } as GainNode,
analyser: {} as AnalyserNode,
+ headroom: {} as GainNode,
+ ceiling: {} as WaveShaperNode,
};
}
@@ -139,6 +144,48 @@ describe("applyPreviewAudioSettings", () => {
});
});
+describe("previewCeilingCurve", () => {
+ const curve = previewCeilingCurve();
+ /** What the preview plays for a mix at `level`: the headroom gain, then a WaveShaperNode as
+ * the Web Audio spec defines it (clamped to [-1, 1], linear between curve points). */
+ const played = (level: number) => {
+ const input = Math.min(1, Math.max(-1, level / PREVIEW_AUDIO_HEADROOM));
+ const position = ((input + 1) / 2) * (curve.length - 1);
+ const below = Math.floor(position);
+ const above = Math.min(curve.length - 1, below + 1);
+ return curve[below] + (curve[above] - curve[below]) * (position - below);
+ };
+
+ it("plays everything under the export's ceiling exactly as the export writes it", () => {
+ for (let level = -PREVIEW_AUDIO_CEILING; level <= PREVIEW_AUDIO_CEILING; level += 0.001) {
+ expect(Math.abs(played(level) - level)).toBeLessThan(1e-5);
+ }
+ });
+
+ it("keeps a boosted peak within full scale instead of letting the device clip it", () => {
+ // 1.226 is the measured case: a −7.1 dBFS peak under an 8.9 dB loudness boost. Far up
+ // the knee float32 rounds the curve onto 1 itself, which is full scale, not past it.
+ let previous = PREVIEW_AUDIO_CEILING;
+ for (const level of [0.9, 1, 1.226, 2, 4, 16, 64]) {
+ const out = played(level);
+ expect(out).toBeGreaterThanOrEqual(previous);
+ expect(out).toBeLessThanOrEqual(1);
+ expect(played(-level)).toBeCloseTo(-out, 9);
+ previous = out;
+ }
+ expect(played(1.226)).toBeLessThan(1);
+ });
+
+ it("leaves the identity without a corner", () => {
+ // Same slope on both sides of the knee, so the shaping starts as a bend, not a click.
+ const step = 1e-3;
+ const below = (played(PREVIEW_AUDIO_CEILING) - played(PREVIEW_AUDIO_CEILING - step)) / step;
+ const above = (played(PREVIEW_AUDIO_CEILING + step) - played(PREVIEW_AUDIO_CEILING)) / step;
+ expect(below).toBeCloseTo(1, 2);
+ expect(above).toBeCloseTo(1, 1);
+ });
+});
+
describe("resolveTimelineAudioPlayback", () => {
// A 6s track placed 10s into the RAW timeline, playing the source from 2s in.
const track: AxcutAudioTrack = {
diff --git a/src/components/ai-edition/VirtualPreview.playback.test.tsx b/src/components/ai-edition/VirtualPreview.playback.test.tsx
index 66a08bbd1..c2be74392 100644
--- a/src/components/ai-edition/VirtualPreview.playback.test.tsx
+++ b/src/components/ai-edition/VirtualPreview.playback.test.tsx
@@ -314,6 +314,7 @@ class FakeGainNode extends FakeAudioNode {
gain = { value: 1 };
}
let createdGains: FakeGainNode[] = [];
+let createdShapers: Array<FakeAudioNode & { curve: Float32Array | null }> = [];
class FakeAudioContext {
state = "running";
destination = new FakeAudioNode();
@@ -329,11 +330,17 @@ class FakeAudioContext {
createAnalyser = vi.fn(() =>
Object.assign(new FakeAudioNode(), { fftSize: 2048, getFloatTimeDomainData: vi.fn() }),
);
+ createWaveShaper = vi.fn(() => {
+ const node = Object.assign(new FakeAudioNode(), { curve: null });
+ createdShapers.push(node);
+ return node;
+ });
}
describe("VirtualPreview imported audio track boost", () => {
beforeEach(() => {
createdGains = [];
+ createdShapers = [];
vi.stubGlobal("AudioContext", FakeAudioContext);
});
@@ -384,6 +391,31 @@ describe("VirtualPreview imported audio track boost", () => {
expect(trackGain?.gain.value).toBeCloseTo(2, 3); // boosted, NOT clamped to 1
expect(audioEl.volume).toBe(1); // volume left at unity so it doesn't double-attenuate
});
+
+ // The loudness boost and the trim can push a loud take past full scale; only the ceiling
+ // keeps the audio device from clipping it (#911). Nothing may bypass it on the way out.
+ it("reaches the speakers only through the ceiling", () => {
+ const sources: VideoSource[] = [{ id: "a1", src: "file:///tmp/a1.mp4", label: "a1" }];
+ const { container } = render(
+ <VirtualPreview
+ videoSources={sources}
+ clips={[clip("c1", "a1", 0, 10, 0)]}
+ onTimeChange={vi.fn()}
+ />,
+ );
+ const videoEl = container.querySelector("video");
+ if (!videoEl) throw new Error("no <video>");
+ driveVideo(videoEl as HTMLVideoElement);
+ act(() => fireEvent.loadedMetadata(videoEl));
+
+ const ceiling = createdShapers.at(-1);
+ expect(ceiling?.curve).toBeInstanceOf(Float32Array);
+ const speakers = ceiling?.connect.mock.calls[0]?.[0];
+ expect(speakers).toBeDefined();
+ for (const gain of createdGains) {
+ expect(gain.connect).not.toHaveBeenCalledWith(speakers);
+ }
+ });
});
// The recording's sound is a second element over the same file: a muted <video> is the clock
diff --git a/src/components/ai-edition/VirtualPreview.tsx b/src/components/ai-edition/VirtualPreview.tsx
index 5980c3654..a6777d8f4 100644
--- a/src/components/ai-edition/VirtualPreview.tsx
+++ b/src/components/ai-edition/VirtualPreview.tsx
@@ -309,12 +309,54 @@ export interface PreviewAudioGraph {
voice: GainNode;
/** Listens to the voice — the recording and every voiceover — to duck the music. */
analyser: AnalyserNode;
+ /** Between `gain` and the speakers: `headroom` scales the mix into `ceiling`'s input range,
+ * and `ceiling` keeps it under full scale (see `previewCeilingCurve`). */
+ headroom: GainNode;
+ ceiling: WaveShaperNode;
+}
+
+/** The export limiter's ceiling, `LIMITER_CEILING` in audio.rs: −1.5 dBFS. */
+export const PREVIEW_AUDIO_CEILING = 0.841_395_1;
+/** Loudest mix the ceiling stage reads, as a multiple of full scale: +24 dB, a full-scale file
+ * under the largest loudness boost and the largest output trim. Louder lands on the curve's
+ * flat end, which the curve has reached long before. */
+export const PREVIEW_AUDIO_HEADROOM = 16;
+
+/**
+ * The curve of the WaveShaperNode in front of the preview's speakers. Without it, the loudness
+ * boost (up to +12 dB) and the output trim push a loud take's peaks past full scale, and the
+ * audio device clips them: the preview saturates where the export, whose limiter holds them
+ * at −1.5 dBFS, does not (measured on a real take: a −7.1 dBFS peak raised 8.9 dB, 92 samples
+ * over).
+ *
+ * It is the identity up to the export's ceiling, then a tanh knee that leaves the identity
+ * with the same slope and rises towards full scale without reaching it. A curve, not a
+ * limiter, because a curve has no state (see `applyPreviewAudioSettings`): everything under
+ * the ceiling plays exactly as the export writes it, and only the peaks the export limits
+ * are shaped, here by their own level rather than by a gain riding over 5 ms. A WaveShaper
+ * reads its input on [−1, 1], so `headroom` divides the mix by `PREVIEW_AUDIO_HEADROOM` on
+ * the way in and the curve's values are real levels. The point count is odd so that silence
+ * is a point of its own.
+ */
+export function previewCeilingCurve(points = 8193): Float32Array<ArrayBuffer> {
+ const knee = PREVIEW_AUDIO_CEILING;
+ const curve = new Float32Array(points);
+ for (let index = 0; index < points; index += 1) {
+ const level = ((index / (points - 1)) * 2 - 1) * PREVIEW_AUDIO_HEADROOM;
+ const magnitude = Math.abs(level);
+ curve[index] =
+ Math.sign(level) *
+ (magnitude <= knee
+ ? magnitude
+ : knee + (1 - knee) * Math.tanh((magnitude - knee) / (1 - knee)));
+ }
+ return curve;
}
/**
- * The preview's audio processing is static gains only, and that is deliberate: each is the
- * same `10 ** (dB / 20)` scalar the export applies natively, so what the editor plays is
- * what the export writes.
+ * The preview's gains are static, and that is deliberate: each is the same
+ * `10 ** (dB / 20)` scalar the export applies natively, so what the editor plays is what
+ * the export writes.
*
* - `gainDb` is the output trim, `finish_audio`'s gain.
* - `voiceGainDb` is the loudness normalisation of the recording being played. The
@@ -324,7 +366,8 @@ export interface PreviewAudioGraph {
* Nothing with state belongs here. The export runs on the assembled timeline (trimmed,
* speed-adjusted, concatenated); the preview runs on the untouched source file, seeked. A
* filter or a compressor would see a different signal on each side and drift. That is why
- * the export's peak limiter, which only acts above −1.5 dBFS, has no counterpart here.
+ * the export's peak limiter has a stateless stand-in here, `previewCeilingCurve`, rather
+ * than a compressor.
*/
export function applyPreviewAudioSettings(
graph: PreviewAudioGraph | null,
@@ -621,15 +664,21 @@ export function VirtualPreview({
audioContextRef.current = context;
audioSourceNodesRef.current = new WeakMap();
}
+ const ceiling = context.createWaveShaper();
+ ceiling.curve = previewCeilingCurve();
+ ceiling.connect(context.destination);
+ const headroom = context.createGain();
+ headroom.gain.value = 1 / PREVIEW_AUDIO_HEADROOM;
+ headroom.connect(ceiling);
const gain = context.createGain();
- gain.connect(context.destination);
+ gain.connect(headroom);
const voice = context.createGain();
voice.connect(gain);
// 1024 samples: about 21 ms of voice per reading, one reading per frame.
const analyser = context.createAnalyser();
analyser.fftSize = 1024;
voice.connect(analyser);
- return { context, gain, voice, analyser };
+ return { context, gain, voice, analyser, headroom, ceiling };
} catch {
return null;
}
@@ -699,6 +748,8 @@ export function VirtualPreview({
graph.voice.disconnect();
graph.analyser.disconnect();
graph.gain.disconnect();
+ graph.headroom.disconnect();
+ graph.ceiling.disconnect();
};
}, [
primaryAudioEl,