fix(mining): ignore stale captions and improve waveform contrast

- Use active parsed cue text and timings for overlay mining
- Normalize waveform levels against the clip's noise floor

src/core/services/media-timing-waveform.test.ts

@@ -58,16 +58,44 @@ test('speech waveform seeks cached windows by source timestamps', () => {
   assert.equal(args.includes('-map'), false);
 });
 
-test('waveform peaks are normalized without flattening quieter sections', () => {
+test('waveform levels rise with loudness and top out at the reference level', () => {
   const peaks = computeWaveformPeaks(pcm([0, 1_000, -2_000, 4_000, -8_000, 16_000]), 3);
 
   assert.equal(peaks.length, 3);
-  assert.ok((peaks[0] ?? 0) > 0);
-  assert.ok((peaks[0] ?? 0) < (peaks[1] ?? 0));
+  assert.equal(peaks[0], 0);
+  assert.ok((peaks[1] ?? 0) > 0);
   assert.ok((peaks[1] ?? 0) < (peaks[2] ?? 0));
   assert.equal(peaks[2], 1);
 });
 
+test('waveform flattens steady background noise and keeps speech bursts tall', () => {
+  // 20 slices of steady noise at a fixed level with an 18 dB louder "speech" burst in the middle.
+  const noise = 1_000;
+  const samples: number[] = [];
+  for (let slice = 0; slice < 20; slice += 1) {
+    const level = slice >= 8 && slice < 12 ? noise * 8 : noise;
+    for (let sample = 0; sample < 50; sample += 1) {
+      samples.push(sample % 2 === 0 ? level : -level);
+    }
+  }
+
+  const peaks = computeWaveformPeaks(pcm(samples), 20);
+
+  for (const [index, peak] of peaks.entries()) {
+    if (index >= 8 && index < 12) assert.equal(peak, 1);
+    else assert.equal(peak, 0);
+  }
+});
+
+test('waveform stays flat when the whole range is a single steady level', () => {
+  const peaks = computeWaveformPeaks(
+    pcm(Array.from({ length: 400 }, (_, i) => (i % 2 ? 900 : -900))),
+    40,
+  );
+
+  assert.ok(peaks.every((peak) => peak === 0));
+});
+
 test('speech waveform uses a mono downmix when the source has no center activity', async () => {
   const calls: string[][] = [];
   const peaks = await generateSpeechWaveform(

src/core/services/media-timing-waveform.ts

@@ -5,7 +5,13 @@ const WAVEFORM_SAMPLE_RATE = 8_000;
 const WAVEFORM_POINT_COUNT = 480;
 const WAVEFORM_TIMEOUT_MS = 15_000;
 const MAX_WAVEFORM_BYTES = 16 * 1024 * 1024;
-const SPEECH_FILTER = 'highpass=f=120,lowpass=f=4000';
+// Keep the band where speech intelligibility lives; bass, drums, and hum sit below it.
+const SPEECH_FILTER = 'highpass=f=250,lowpass=f=3500';
+const NOISE_FLOOR_PERCENTILE = 0.2;
+const REFERENCE_PERCENTILE = 0.95;
+const NOISE_GATE_DB = 3;
+const MIN_DISPLAY_RANGE_DB = 12;
+const SILENCE_DB = -100;
 const CENTER_CHANNEL_FILTER = `pan=mono|c0=FC,${SPEECH_FILTER}`;
 const DOWNMIX_FILTER = `aformat=channel_layouts=mono,${SPEECH_FILTER}`;
 
@@ -111,11 +117,22 @@ function runFfmpeg(args: string[]): Promise<Buffer> {
   });
 }
 
+function percentile(sortedValues: number[], fraction: number): number {
+  const index = Math.min(sortedValues.length - 1, Math.floor(sortedValues.length * fraction));
+  return sortedValues[index] ?? SILENCE_DB;
+}
+
+/**
+ * Turns mono PCM into 0..1 display heights. Each point is the RMS level of its slice in
+ * dB, measured against the clip's own noise floor (a low percentile of the slices), so
+ * constant background noise draws flat and sustained speech stands out. Peak sampling
+ * would instead follow music transients and lift the floor to nearly speech height.
+ */
 export function computeWaveformPeaks(pcm: Buffer, pointCount = WAVEFORM_POINT_COUNT): number[] {
   const sampleCount = Math.floor(pcm.byteLength / 2);
   if (sampleCount === 0 || pointCount <= 0) return [];
   const resolvedPointCount = Math.min(pointCount, sampleCount);
-  const peaks = Array.from({ length: resolvedPointCount }, () => 0);
+  const levelsDb = Array.from({ length: resolvedPointCount }, () => SILENCE_DB);
 
   for (let point = 0; point < resolvedPointCount; point += 1) {
     const sampleStart = Math.floor((point * sampleCount) / resolvedPointCount);
@@ -123,18 +140,25 @@ export function computeWaveformPeaks(pcm: Buffer, pointCount = WAVEFORM_POINT_CO
       sampleStart + 1,
       Math.floor(((point + 1) * sampleCount) / resolvedPointCount),
     );
-    let peak = 0;
+    let energy = 0;
     for (let sample = sampleStart; sample < sampleEnd; sample += 1) {
-      peak = Math.max(peak, Math.abs(pcm.readInt16LE(sample * 2)) / 32_768);
+      const value = pcm.readInt16LE(sample * 2) / 32_768;
+      energy += value * value;
     }
-    peaks[point] = peak;
+    const rms = Math.sqrt(energy / (sampleEnd - sampleStart));
+    levelsDb[point] = rms > 0 ? Math.max(SILENCE_DB, 20 * Math.log10(rms)) : SILENCE_DB;
   }
 
-  const sortedPeaks = [...peaks].sort((left, right) => left - right);
-  const referenceIndex = Math.min(sortedPeaks.length - 1, Math.floor(sortedPeaks.length * 0.95));
-  const referencePeak = Math.max(sortedPeaks[referenceIndex] ?? 0, 0.01);
-  return peaks.map(
-    (peak) => Math.round(Math.sqrt(Math.min(1, peak / referencePeak)) * 1_000) / 1_000,
+  const sortedLevels = [...levelsDb].sort((left, right) => left - right);
+  const floorDb = percentile(sortedLevels, NOISE_FLOOR_PERCENTILE) + NOISE_GATE_DB;
+  const referenceDb = Math.max(
+    percentile(sortedLevels, REFERENCE_PERCENTILE),
+    floorDb + MIN_DISPLAY_RANGE_DB,
+  );
+  return levelsDb.map(
+    (levelDb) =>
+      Math.round(Math.min(1, Math.max(0, (levelDb - floorDb) / (referenceDb - floorDb))) * 1_000) /
+      1_000,
   );
 }