fix(export): address review feedback on multi-track audio mixing

- Preserve the signed startFrame so AAC preroll (negative timestamp) no
  longer collides with the timestamp-zero frame; mixPlanarSources already
  discards pre-zero frames.
- Keep the sole decodable stream instead of returning null, so a partial
  decode failure can't fall back to the demuxer's best stream and export
  silence.
- Log per-track sample rates when a cross-rate mix is skipped.
- Document the hard-clip trade-off in mixPlanarSources.
- Tests: pin the source-copy audioStreamCount>1 blocker, cover the signed
  startFrame case, and tighten the browser RMS thresholds (0.01 -> 0.05).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: barnaclebarnes

src/lib/exporter/audioEncoder.test.ts

@@ -132,6 +132,21 @@ describe("mixPlanarSources", () => {
 		]);
 	});
 
+	it("discards samples before frame zero from a negative startFrame (AAC preroll)", () => {
+		// AAC preroll gives the first decoded frame a negative timestamp, so the source's
+		// startFrame is signed. The preroll samples (timeline < 0) must be dropped while
+		// the real timestamp-zero sample keeps its true offset.
+		const withPreroll = {
+			planes: [new Float32Array([0.9, 0.5, 0.5])],
+			startFrame: -2,
+		};
+
+		const mixed = mixPlanarSources([withPreroll], 1, 2);
+
+		// Frames -2 and -1 (0.9, 0.5) are discarded; frame 0 keeps the real sample.
+		expect(Array.from(mixed[0])).toEqual([expect.closeTo(0.5, 5), expect.closeTo(0, 5)]);
+	});
+
 	it("upmixes a mono source to stereo before mixing", () => {
 		const mono = { planes: [new Float32Array([0.3, 0.3])], startFrame: 0 };
 		const stereo = {

src/lib/exporter/audioEncoder.ts

@@ -153,8 +153,11 @@ export interface PlanarAudioSource {
  * into one track before encoding.
  *
  * Each source is first downmixed to `targetChannels`, then summed sample-aligned at
- * its `startFrame`. The result is clamped to [-1, 1] so a loud overlap can't wrap or
- * overflow the encoder. Sources of differing lengths and offsets are supported;
+ * its `startFrame`. The result is hard-clamped to [-1, 1] so a loud overlap can't wrap
+ * or overflow the encoder. Hard clipping (rather than a 1/N gain pre-sum or soft-knee
+ * limiter) can add harmonic distortion when two sources are simultaneously near unity —
+ * an acceptable trade-off for a screen recorder, where keeping both tracks at full level
+ * matters more than headroom. Sources of differing lengths and offsets are supported;
  * samples past `totalFrames` are dropped.
  */
 export function mixPlanarSources(
@@ -384,8 +387,11 @@ export class AudioProcessor {
 		const numberOfChannels = decoded[0].numberOfChannels;
 		// Absolute timeline position of this stream's first sample (mic tracks often
 		// start slightly after the video, e.g. start_time ~0.17s), so mixing keeps
-		// every track locked to the same source-time origin the video uses.
-		const startFrame = Math.max(0, Math.round((decoded[0].timestamp / 1_000_000) * sampleRate));
+		// every track locked to the same source-time origin the video uses. Kept signed:
+		// AAC preroll carries a negative timestamp, and clamping it to zero would land the
+		// preroll and the real timestamp-zero frame on the same offset. mixPlanarSources()
+		// discards frames before zero, so the signed origin stays correct.
+		const startFrame = Math.round((decoded[0].timestamp / 1_000_000) * sampleRate);
 
 		let totalFrames = 0;
 		for (const d of decoded) {
@@ -435,12 +441,17 @@ export class AudioProcessor {
 		}
 
 		if (sources.length === 0) return null;
-		// A single decodable stream can't be "mixed" — fall back to the normal path.
-		if (sources.length === 1) return null;
+		// If only one of several streams decoded, keep it rather than falling back to the
+		// demuxer's best stream — that fallback can re-select the stream that just failed
+		// to decode and export silence. mixPlanarSources() handles a single source fine.
 
 		const sampleRate = sources[0].sampleRate;
 		if (sources.some((s) => s.sampleRate !== sampleRate)) {
-			console.warn("[AudioProcessor] Audio streams differ in sample rate; skipping mix");
+			console.warn(
+				`[AudioProcessor] Audio streams differ in sample rate; skipping mix (rates: ${sources
+					.map((s) => s.sampleRate)
+					.join(", ")}Hz)`,
+			);
 			return null;
 		}
 

src/lib/exporter/audioMixExport.browser.test.ts

@@ -57,9 +57,9 @@ describe("Multi-track audio export (real browser)", () => {
 		const { rms, hasAudio } = await measureAudioRms(result.blob!);
 		expect(hasAudio).toBe(true);
 		// Silence (the first track alone) sits near 0; the mixed-in 440 Hz tone lifts
-		// RMS well above the noise floor. A comfortable threshold below the tone's
-		// real level (~0.08) but far above silence.
-		expect(rms).toBeGreaterThan(0.01);
+		// RMS to ~0.08. Threshold sits below the tone's real level but well above the
+		// noise floor, so a near-silent fallback (the old #108 bug) still fails.
+		expect(rms).toBeGreaterThan(0.05);
 	});
 
 	it("mixes both audio tracks through the speed-region (offline) path too", async () => {
@@ -85,6 +85,6 @@ describe("Multi-track audio export (real browser)", () => {
 
 		const { rms, hasAudio } = await measureAudioRms(result.blob!);
 		expect(hasAudio).toBe(true);
-		expect(rms).toBeGreaterThan(0.01);
+		expect(rms).toBeGreaterThan(0.05);
 	});
 });

src/lib/exporter/videoExporter.test.ts

@@ -129,6 +129,29 @@ describe("getSourceCopyFastPathBlockers", () => {
 			}),
 		).toContain("output-size 1920x1080 differs from source 1920x1032");
 	});
+
+	// A verbatim source copy would carry over every audio track; most players play only
+	// the first, which on native macOS captures is often the silent system track — the
+	// #108 bug. Multi-track sources must be blocked from the copy path so they get mixed.
+	it("blocks the copy path when the source has multiple audio tracks (#108)", () => {
+		expect(
+			getSourceCopyFastPathBlockers(createConfig(), {
+				width: 1920,
+				height: 1080,
+				audioStreamCount: 2,
+			}),
+		).toContain("source has multiple audio tracks (must be mixed)");
+	});
+
+	it("does not report the audio-track blocker for a single-track source", () => {
+		expect(
+			getSourceCopyFastPathBlockers(createConfig(), {
+				width: 1920,
+				height: 1080,
+				audioStreamCount: 1,
+			}),
+		).not.toContain("source has multiple audio tracks (must be mixed)");
+	});
 });
 
 // The original bug measured the timeout from the encoder's last *output* event