nodejs-audio-visualizer 5.5.2 → 5.6.3

package/src/tests/highlight.test.ts

@@ -1,397 +1,397 @@
-import { expect } from 'chai';
-import {
-  computeHighlightSlice,
-  HIGHLIGHT_DURATION_SEC,
-  MAX_BEAT_SNAP_SEC,
-  buildBeatCandidates,
-  snapSegmentToBeats,
-  snapDropToBeat,
-} from '../highlight';
-
-const dummySpectrums = (n: number) => Array.from({ length: n }, () => [0]);
-
-/** Non-zero spectrum only on [rangeStart, rangeEnd) so frame energy is concentrated there. */
-function spectrumsWithEnergyInRange(
-  n: number,
-  rangeStart: number,
-  rangeEndExclusive: number,
-  binValue = 1,
-): number[][] {
-  return Array.from({ length: n }, (_, i) =>
-    i >= rangeStart && i < rangeEndExclusive ? [binValue] : [0],
-  );
-}
-
-describe('computeHighlightSlice', function() {
-  it('centers window when energy is flat (e.g. silence)', async function() {
-    const fps = 30;
-    const totalFrames = 1000;
-    const spectrums = dummySpectrums(totalFrames);
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const expectedStart = Math.floor((totalFrames - highlightFrames) / 2);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, []);
-
-    expect(result.highlightFrames).equal(highlightFrames);
-    expect(result.startFrame).equal(expectedStart);
-    expect(result.spectrums.length).equal(highlightFrames);
-    expect(result.audioSeekSeconds).equal(expectedStart / fps);
-    expect(result.audioDurationSeconds).equal(highlightFrames / fps);
-    expect(result.audioSegments).deep.equal([
-      { seekSeconds: expectedStart / fps, durationSeconds: highlightFrames / fps },
-    ]);
-    expect(result.runs).have.length(1);
-    expect(result.runs[0].highlightFrames).equal(highlightFrames);
-  });
-
-  it('clamps to track end when the loudest stretch is only in the final window', async function() {
-    const fps = 30;
-    const totalFrames = 1000;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const maxStart = totalFrames - highlightFrames;
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, maxStart, totalFrames);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
-      { frameIndex: 950, intensity: 1 },
-    ]);
-
-    expect(result.startFrame).equal(maxStart);
-    expect(result.highlightFrames).equal(highlightFrames);
-    expect(result.spectrums.length).equal(highlightFrames);
-    expect(result.audioSegments).deep.equal([
-      { seekSeconds: maxStart / fps, durationSeconds: highlightFrames / fps },
-    ]);
-    expect(result.runs).have.length(1);
-  });
-
-  it('uses full track when shorter than highlight duration', async function() {
-    const fps = 30;
-    const totalFrames = 400;
-    const spectrums = dummySpectrums(totalFrames);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
-      { frameIndex: 100, intensity: 1 },
-    ]);
-
-    expect(result.startFrame).equal(0);
-    expect(result.highlightFrames).equal(totalFrames);
-    expect(result.spectrums.length).equal(totalFrames);
-    expect(result.beatFrameIndices).deep.equal([100]);
-    expect(result.audioSeekSeconds).equal(0);
-    expect(result.audioDurationSeconds).equal(totalFrames / fps);
-    expect(result.audioSegments).deep.equal([
-      { seekSeconds: 0, durationSeconds: totalFrames / fps },
-    ]);
-    expect(result.runs).have.length(1);
-    expect(result.runs[0].spectrums.length).equal(totalFrames);
-  });
-
-  it('remaps beat indices into the highlight window', async function() {
-    const fps = 30;
-    const totalFrames = 1000;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 300, 300 + highlightFrames);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
-      { frameIndex: 300, intensity: 1 },
-      { frameIndex: 400, intensity: 0.5 },
-      { frameIndex: 800, intensity: 0.2 },
-    ]);
-
-    expect(result.startFrame).equal(300);
-    expect(result.beatFrameIndices).deep.equal([0, 100]);
-    expect(result.audioSegments).deep.equal([
-      { seekSeconds: 300 / fps, durationSeconds: highlightFrames / fps },
-    ]);
-    expect(result.runs).have.length(1);
-  });
-
-  it('picks the window with the highest summed spectral energy', async function() {
-    const fps = 30;
-    const totalFrames = 1000;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const loud = 10;
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 10, 10 + highlightFrames, loud);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
-      { frameIndex: 10, intensity: 99 },
-      { frameIndex: 200, intensity: 0.4 },
-      { frameIndex: 500, intensity: 0.9 },
-    ]);
-
-    expect(result.startFrame).equal(10);
-    // The end moves from frame 460 onto the nearby beat at 500.
-    expect(result.highlightFrames).equal(490);
-    expect(result.audioSegments).deep.equal([
-      { seekSeconds: 10 / fps, durationSeconds: 490 / fps },
-    ]);
-    expect(result.runs).have.length(1);
-  });
-
-  it('returns empty slice for zero frames', async function() {
-    const result = await computeHighlightSlice(30, 0, [], []);
-    expect(result.highlightFrames).equal(0);
-    expect(result.spectrums).deep.equal([]);
-    expect(result.beatFrameIndices).deep.equal([]);
-    expect(result.audioSegments).deep.equal([]);
-    expect(result.runs).deep.equal([]);
-  });
-
-  it('concatenates two non-overlapping highlights chronologically with segmentCount 2', async function() {
-    const fps = 30;
-    const totalFrames = 1000;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const loudA = 10;
-    const loudB = 5;
-    const spectrumsA = spectrumsWithEnergyInRange(totalFrames, 0, 450, loudA);
-    const spectrumsB = spectrumsWithEnergyInRange(totalFrames, 500, 950, loudB);
-    const spectrums = spectrumsA.map((row, i) => {
-      const b = spectrumsB[i];
-      const v = (row[0] || 0) + (b[0] || 0);
-      return v > 0 ? [v] : [0];
-    });
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
-      { frameIndex: 50, intensity: 1 },
-      { frameIndex: 550, intensity: 1 },
-    ], 2);
-
-    expect(result.highlightFrames).equal(highlightFrames * 2);
-    expect(result.spectrums.length).equal(highlightFrames * 2);
-    expect(result.startFrame).equal(0);
-    expect(result.audioSegments).deep.equal([
-      { seekSeconds: 0, durationSeconds: highlightFrames / fps },
-      { seekSeconds: 500 / fps, durationSeconds: highlightFrames / fps },
-    ]);
-    expect(result.beatFrameIndices).deep.equal([50, 500]);
-    expect(result.runs).have.length(2);
-    expect(result.runs[0].startFrame).equal(0);
-    expect(result.runs[1].startFrame).equal(500);
-    expect(result.runs[0].spectrums.length).equal(highlightFrames);
-    expect(result.runs[1].spectrums.length).equal(highlightFrames);
-  });
-
-  it('ignores extra segmentCount when only one full highlight window fits', async function() {
-    const fps = 30;
-    const totalFrames = 600;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 0, highlightFrames, 1);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 3);
-
-    expect(result.highlightFrames).equal(highlightFrames);
-    expect(result.audioSegments).have.length(1);
-    expect(result.runs).have.length(1);
-  });
-
-  it('starts the whole lead-in before the drop when leadInFrames is given', async function() {
-    const fps = 10;
-    const totalFrames = 1000;
-    // Quiet until frame 600, loud after: the drop is at 600.
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 600, totalFrames);
-    const beats = Array.from({ length: 200 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 43);
-
-    expect(result.runs).have.length(1);
-    expect(result.runs[0].startFrame).equal(557);
-    expect(result.runs[0].leadInFrames).equal(43);
-    // The lead-in comes on top of the ~15s that follow the drop.
-    expect(result.runs[0].highlightFrames).equal(43 + Math.ceil(HIGHLIGHT_DURATION_SEC * fps));
-  });
-
-  it('pads the lead-in with silence before the track start when only an early drop fits', async function() {
-    const fps = 10;
-    // A full 130-frame lead-in needs a drop at 130+, but ~15s must follow it: only 100 fits.
-    const totalFrames = 250;
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 100, totalFrames);
-    const beats = Array.from({ length: 50 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 130);
-    const run = result.runs[0];
-
-    expect(run.startFrame).equal(-30);
-    expect(run.leadInFrames).equal(130);
-    expect(run.spectrums).have.length(run.highlightFrames);
-    expect(run.spectrums.slice(0, 30).every(s => s.every(v => v === 0))).equal(true);
-    expect(run.beatFrameIndices[0]).equal(30);
-    expect(run.audioSegment).deep.equal({
-      seekSeconds: 0,
-      durationSeconds: (run.highlightFrames - 30) / fps,
-      delaySeconds: 3,
-    });
-  });
-
-  it('picks a separate drop for each highlight', async function() {
-    const fps = 10;
-    const totalFrames = 2000;
-    const spectrums = Array.from({ length: totalFrames }, (_, i) =>
-      (i >= 500 && i < 800) || (i >= 1400 && i < 1700) ? [1] : [0],
-    );
-    const beats = Array.from({ length: 400 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 2, null, 30);
-
-    expect(result.runs.map(run => run.startFrame + (run.leadInFrames as number))).deep.equal([500, 1400]);
-    expect(result.runs.map(run => run.leadInFrames)).deep.equal([30, 30]);
-  });
-
-  it('ends the lead-in on the energy onset even when beats are off it', async function() {
-    const fps = 10;
-    const totalFrames = 1000;
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 602, totalFrames);
-    // Beats every 5 frames, none on the onset at 602.
-    const beats = Array.from({ length: 200 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 43);
-
-    expect(result.runs[0].startFrame + (result.runs[0].leadInFrames as number)).equal(602);
-    expect(result.runs[0].leadInFrames).equal(43);
-  });
-
-  it('ends the lead-in on a nearby grid beat when a tempo grid is given', async function() {
-    const fps = 10;
-    const totalFrames = 1000;
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 602, totalFrames);
-    const beats = Array.from({ length: 200 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
-    // Grid beats every 10 frames on multiples of 10: 600 is 2 frames (0.2 beat) from the onset.
-    const grid = { periodFrames: 10, phaseFrame: 0 };
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, grid, 43);
-
-    expect(result.runs[0].startFrame).equal(557);
-    expect(result.runs[0].leadInFrames).equal(43);
-  });
-
-  it('keeps the full lead-in rather than ending it past the drop or on a weak rise', async function() {
-    const fps = 10;
-    const totalFrames = 600;
-    // Big drop at 140, then a small bump at 300; a 200-frame lead-in doesn't fit before 140.
-    const spectrums = Array.from({ length: totalFrames }, (_, i) =>
-      i < 140 ? [0.1] : i < 300 ? [1] : [1.1],
-    );
-    const beats = Array.from({ length: 120 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 200);
-
-    expect(result.runs[0].startFrame).equal(-60);
-    expect(result.runs[0].leadInFrames).equal(200);
-  });
-
-  it('puts the lead-in before the energy window when no drop is found', async function() {
-    const fps = 10;
-    const totalFrames = 1000;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 600, totalFrames);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 1, null, 900);
-
-    // The window starts at 600; the rest of the lead-in is silence before the track start.
-    expect(result.runs[0].startFrame).equal(-300);
-    expect(result.runs[0].leadInFrames).equal(900);
-    expect(result.runs[0].highlightFrames).equal(900 + highlightFrames);
-    expect(result.runs[0].audioSegment.delaySeconds).equal(30);
-  });
-
-  it('snaps highlight start and end onto detected beats', async function() {
-    const fps = 30;
-    const totalFrames = 1000;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 300, 300 + highlightFrames);
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
-      { frameIndex: 290, intensity: 1 },
-      { frameIndex: 600, intensity: 1 },
-      { frameIndex: 760, intensity: 1 },
-    ]);
-
-    expect(result.startFrame).equal(290);
-    expect(result.highlightFrames).equal(760 - 290);
-    expect(result.audioSegments).deep.equal([
-      { seekSeconds: 290 / fps, durationSeconds: (760 - 290) / fps },
-    ]);
-    expect(result.beatFrameIndices).deep.equal([0, 310]);
-  });
-
-  it('snaps to a tempo grid and prefers a whole number of bars', async function() {
-    const fps = 30;
-    const totalFrames = 2000;
-    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-    const spectrums = spectrumsWithEnergyInRange(totalFrames, 505, 505 + highlightFrames);
-    // 120 BPM at 30 fps: a beat every 15 frames, a bar every 60.
-    const beatGrid = { periodFrames: 15, phaseFrame: 5 };
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 1, beatGrid);
-
-    expect((result.startFrame - 5) % 15).equal(0);
-    expect(result.highlightFrames % 60).equal(0);
-    expect(Math.abs(result.startFrame - 505)).lte(MAX_BEAT_SNAP_SEC * fps);
-    expect(Math.abs(result.highlightFrames - highlightFrames)).lte(2 * MAX_BEAT_SNAP_SEC * fps);
-  });
-
-  it('keeps several snapped highlights from overlapping', async function() {
-    const fps = 30;
-    const totalFrames = 3000;
-    const spectrums = Array.from({ length: totalFrames }, (_, i) => [1 + Math.sin(i / 50)]);
-    const beatGrid = { periodFrames: 14, phaseFrame: 3 };
-
-    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 4, beatGrid);
-
-    for (let i = 1; i < result.runs.length; i++) {
-      const prev = result.runs[i - 1];
-      expect(result.runs[i].startFrame).gte(prev.startFrame + prev.highlightFrames);
-    }
-  });
-});
-
-describe('buildBeatCandidates', function() {
-  it('uses onsets when no tempo grid is given', function() {
-    expect(buildBeatCandidates(30, 100, [
-      { frameIndex: 40, intensity: 1 },
-      { frameIndex: 10, intensity: 1 },
-      { frameIndex: 10, intensity: 1 },
-    ])).deep.equal([10, 40]);
-  });
-
-  it('uses tracked beats, then the grid nudged onto nearby onsets', function() {
-    const frames = buildBeatCandidates(10, 60, [{ frameIndex: 41, intensity: 1 }], {
-      periodFrames: 10,
-      phaseFrame: 0,
-      beatsSec: [0.1, 1.1, 2.1],
-    });
-    expect(frames).deep.equal([1, 11, 21, 30, 41, 50, 60]);
-  });
-});
-
-describe('snapSegmentToBeats', function() {
-  it('leaves a segment unchanged when no beat is close enough', function() {
-    const seg = { startFrame: 100, highlightFrames: 200 };
-    expect(snapSegmentToBeats(seg, 1000, [10, 900], 20)).deep.equal(seg);
-  });
-});
-
-describe('snapDropToBeat', function() {
-  it('moves the drop and its start together onto a beat within a fifth of a beat', function() {
-    const drop = { startFrame: 60, dropFrame: 103 };
-    snapDropToBeat(drop, [80, 100, 120], 20);
-    expect(drop).deep.equal({ startFrame: 57, dropFrame: 100 });
-  });
-
-  it('keeps the drop when the nearest beat is too far', function() {
-    const drop = { startFrame: 60, dropFrame: 105 };
-    snapDropToBeat(drop, [80, 100, 120], 20);
-    expect(drop).deep.equal({ startFrame: 60, dropFrame: 105 });
-  });
-
-  it('keeps the drop without a tempo period', function() {
-    const drop = { startFrame: 60, dropFrame: 101 };
-    snapDropToBeat(drop, [80, 100, 120]);
-    expect(drop).deep.equal({ startFrame: 60, dropFrame: 101 });
-  });
-
-  it('does not push a lead-in that fit in the track back past its start', function() {
-    const drop = { startFrame: 1, dropFrame: 43 };
-    snapDropToBeat(drop, [40], 20);
-    expect(drop).deep.equal({ startFrame: 1, dropFrame: 43 });
-  });
-});
+import { expect } from 'chai';
+import {
+  computeHighlightSlice,
+  HIGHLIGHT_DURATION_SEC,
+  MAX_BEAT_SNAP_SEC,
+  buildBeatCandidates,
+  snapSegmentToBeats,
+  snapDropToBeat,
+} from '../highlight';
+
+const dummySpectrums = (n: number) => Array.from({ length: n }, () => [0]);
+
+/** Non-zero spectrum only on [rangeStart, rangeEnd) so frame energy is concentrated there. */
+function spectrumsWithEnergyInRange(
+  n: number,
+  rangeStart: number,
+  rangeEndExclusive: number,
+  binValue = 1,
+): number[][] {
+  return Array.from({ length: n }, (_, i) =>
+    i >= rangeStart && i < rangeEndExclusive ? [binValue] : [0],
+  );
+}
+
+describe('computeHighlightSlice', function() {
+  it('centers window when energy is flat (e.g. silence)', async function() {
+    const fps = 30;
+    const totalFrames = 1000;
+    const spectrums = dummySpectrums(totalFrames);
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const expectedStart = Math.floor((totalFrames - highlightFrames) / 2);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, []);
+
+    expect(result.highlightFrames).equal(highlightFrames);
+    expect(result.startFrame).equal(expectedStart);
+    expect(result.spectrums.length).equal(highlightFrames);
+    expect(result.audioSeekSeconds).equal(expectedStart / fps);
+    expect(result.audioDurationSeconds).equal(highlightFrames / fps);
+    expect(result.audioSegments).deep.equal([
+      { seekSeconds: expectedStart / fps, durationSeconds: highlightFrames / fps },
+    ]);
+    expect(result.runs).have.length(1);
+    expect(result.runs[0].highlightFrames).equal(highlightFrames);
+  });
+
+  it('clamps to track end when the loudest stretch is only in the final window', async function() {
+    const fps = 30;
+    const totalFrames = 1000;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const maxStart = totalFrames - highlightFrames;
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, maxStart, totalFrames);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
+      { frameIndex: 950, intensity: 1 },
+    ]);
+
+    expect(result.startFrame).equal(maxStart);
+    expect(result.highlightFrames).equal(highlightFrames);
+    expect(result.spectrums.length).equal(highlightFrames);
+    expect(result.audioSegments).deep.equal([
+      { seekSeconds: maxStart / fps, durationSeconds: highlightFrames / fps },
+    ]);
+    expect(result.runs).have.length(1);
+  });
+
+  it('uses full track when shorter than highlight duration', async function() {
+    const fps = 30;
+    const totalFrames = 400;
+    const spectrums = dummySpectrums(totalFrames);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
+      { frameIndex: 100, intensity: 1 },
+    ]);
+
+    expect(result.startFrame).equal(0);
+    expect(result.highlightFrames).equal(totalFrames);
+    expect(result.spectrums.length).equal(totalFrames);
+    expect(result.beatFrameIndices).deep.equal([100]);
+    expect(result.audioSeekSeconds).equal(0);
+    expect(result.audioDurationSeconds).equal(totalFrames / fps);
+    expect(result.audioSegments).deep.equal([
+      { seekSeconds: 0, durationSeconds: totalFrames / fps },
+    ]);
+    expect(result.runs).have.length(1);
+    expect(result.runs[0].spectrums.length).equal(totalFrames);
+  });
+
+  it('remaps beat indices into the highlight window', async function() {
+    const fps = 30;
+    const totalFrames = 1000;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 300, 300 + highlightFrames);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
+      { frameIndex: 300, intensity: 1 },
+      { frameIndex: 400, intensity: 0.5 },
+      { frameIndex: 800, intensity: 0.2 },
+    ]);
+
+    expect(result.startFrame).equal(300);
+    expect(result.beatFrameIndices).deep.equal([0, 100]);
+    expect(result.audioSegments).deep.equal([
+      { seekSeconds: 300 / fps, durationSeconds: highlightFrames / fps },
+    ]);
+    expect(result.runs).have.length(1);
+  });
+
+  it('picks the window with the highest summed spectral energy', async function() {
+    const fps = 30;
+    const totalFrames = 1000;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const loud = 10;
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 10, 10 + highlightFrames, loud);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
+      { frameIndex: 10, intensity: 99 },
+      { frameIndex: 200, intensity: 0.4 },
+      { frameIndex: 500, intensity: 0.9 },
+    ]);
+
+    expect(result.startFrame).equal(10);
+    // The end moves from frame 460 onto the nearby beat at 500.
+    expect(result.highlightFrames).equal(490);
+    expect(result.audioSegments).deep.equal([
+      { seekSeconds: 10 / fps, durationSeconds: 490 / fps },
+    ]);
+    expect(result.runs).have.length(1);
+  });
+
+  it('returns empty slice for zero frames', async function() {
+    const result = await computeHighlightSlice(30, 0, [], []);
+    expect(result.highlightFrames).equal(0);
+    expect(result.spectrums).deep.equal([]);
+    expect(result.beatFrameIndices).deep.equal([]);
+    expect(result.audioSegments).deep.equal([]);
+    expect(result.runs).deep.equal([]);
+  });
+
+  it('concatenates two non-overlapping highlights chronologically with segmentCount 2', async function() {
+    const fps = 30;
+    const totalFrames = 1000;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const loudA = 10;
+    const loudB = 5;
+    const spectrumsA = spectrumsWithEnergyInRange(totalFrames, 0, 450, loudA);
+    const spectrumsB = spectrumsWithEnergyInRange(totalFrames, 500, 950, loudB);
+    const spectrums = spectrumsA.map((row, i) => {
+      const b = spectrumsB[i];
+      const v = (row[0] || 0) + (b[0] || 0);
+      return v > 0 ? [v] : [0];
+    });
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
+      { frameIndex: 50, intensity: 1 },
+      { frameIndex: 550, intensity: 1 },
+    ], 2);
+
+    expect(result.highlightFrames).equal(highlightFrames * 2);
+    expect(result.spectrums.length).equal(highlightFrames * 2);
+    expect(result.startFrame).equal(0);
+    expect(result.audioSegments).deep.equal([
+      { seekSeconds: 0, durationSeconds: highlightFrames / fps },
+      { seekSeconds: 500 / fps, durationSeconds: highlightFrames / fps },
+    ]);
+    expect(result.beatFrameIndices).deep.equal([50, 500]);
+    expect(result.runs).have.length(2);
+    expect(result.runs[0].startFrame).equal(0);
+    expect(result.runs[1].startFrame).equal(500);
+    expect(result.runs[0].spectrums.length).equal(highlightFrames);
+    expect(result.runs[1].spectrums.length).equal(highlightFrames);
+  });
+
+  it('ignores extra segmentCount when only one full highlight window fits', async function() {
+    const fps = 30;
+    const totalFrames = 600;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 0, highlightFrames, 1);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 3);
+
+    expect(result.highlightFrames).equal(highlightFrames);
+    expect(result.audioSegments).have.length(1);
+    expect(result.runs).have.length(1);
+  });
+
+  it('starts the whole lead-in before the drop when leadInFrames is given', async function() {
+    const fps = 10;
+    const totalFrames = 1000;
+    // Quiet until frame 600, loud after: the drop is at 600.
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 600, totalFrames);
+    const beats = Array.from({ length: 200 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 43);
+
+    expect(result.runs).have.length(1);
+    expect(result.runs[0].startFrame).equal(557);
+    expect(result.runs[0].leadInFrames).equal(43);
+    // The lead-in comes on top of the ~15s that follow the drop.
+    expect(result.runs[0].highlightFrames).equal(43 + Math.ceil(HIGHLIGHT_DURATION_SEC * fps));
+  });
+
+  it('pads the lead-in with silence before the track start when only an early drop fits', async function() {
+    const fps = 10;
+    // A full 130-frame lead-in needs a drop at 130+, but ~15s must follow it: only 100 fits.
+    const totalFrames = 250;
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 100, totalFrames);
+    const beats = Array.from({ length: 50 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 130);
+    const run = result.runs[0];
+
+    expect(run.startFrame).equal(-30);
+    expect(run.leadInFrames).equal(130);
+    expect(run.spectrums).have.length(run.highlightFrames);
+    expect(run.spectrums.slice(0, 30).every(s => s.every(v => v === 0))).equal(true);
+    expect(run.beatFrameIndices[0]).equal(30);
+    expect(run.audioSegment).deep.equal({
+      seekSeconds: 0,
+      durationSeconds: (run.highlightFrames - 30) / fps,
+      delaySeconds: 3,
+    });
+  });
+
+  it('picks a separate drop for each highlight', async function() {
+    const fps = 10;
+    const totalFrames = 2000;
+    const spectrums = Array.from({ length: totalFrames }, (_, i) =>
+      (i >= 500 && i < 800) || (i >= 1400 && i < 1700) ? [1] : [0],
+    );
+    const beats = Array.from({ length: 400 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 2, null, 30);
+
+    expect(result.runs.map(run => run.startFrame + (run.leadInFrames as number))).deep.equal([500, 1400]);
+    expect(result.runs.map(run => run.leadInFrames)).deep.equal([30, 30]);
+  });
+
+  it('ends the lead-in on the energy onset even when beats are off it', async function() {
+    const fps = 10;
+    const totalFrames = 1000;
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 602, totalFrames);
+    // Beats every 5 frames, none on the onset at 602.
+    const beats = Array.from({ length: 200 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 43);
+
+    expect(result.runs[0].startFrame + (result.runs[0].leadInFrames as number)).equal(602);
+    expect(result.runs[0].leadInFrames).equal(43);
+  });
+
+  it('ends the lead-in on a nearby grid beat when a tempo grid is given', async function() {
+    const fps = 10;
+    const totalFrames = 1000;
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 602, totalFrames);
+    const beats = Array.from({ length: 200 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
+    // Grid beats every 10 frames on multiples of 10: 600 is 2 frames (0.2 beat) from the onset.
+    const grid = { periodFrames: 10, phaseFrame: 0 };
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, grid, 43);
+
+    expect(result.runs[0].startFrame).equal(557);
+    expect(result.runs[0].leadInFrames).equal(43);
+  });
+
+  it('keeps the full lead-in rather than ending it past the drop or on a weak rise', async function() {
+    const fps = 10;
+    const totalFrames = 600;
+    // Big drop at 140, then a small bump at 300; a 200-frame lead-in doesn't fit before 140.
+    const spectrums = Array.from({ length: totalFrames }, (_, i) =>
+      i < 140 ? [0.1] : i < 300 ? [1] : [1.1],
+    );
+    const beats = Array.from({ length: 120 }, (_, i) => ({ frameIndex: i * 5, intensity: 1 }));
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, beats, 1, null, 200);
+
+    expect(result.runs[0].startFrame).equal(-60);
+    expect(result.runs[0].leadInFrames).equal(200);
+  });
+
+  it('puts the lead-in before the energy window when no drop is found', async function() {
+    const fps = 10;
+    const totalFrames = 1000;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 600, totalFrames);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 1, null, 900);
+
+    // The window starts at 600; the rest of the lead-in is silence before the track start.
+    expect(result.runs[0].startFrame).equal(-300);
+    expect(result.runs[0].leadInFrames).equal(900);
+    expect(result.runs[0].highlightFrames).equal(900 + highlightFrames);
+    expect(result.runs[0].audioSegment.delaySeconds).equal(30);
+  });
+
+  it('snaps highlight start and end onto detected beats', async function() {
+    const fps = 30;
+    const totalFrames = 1000;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 300, 300 + highlightFrames);
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [
+      { frameIndex: 290, intensity: 1 },
+      { frameIndex: 600, intensity: 1 },
+      { frameIndex: 760, intensity: 1 },
+    ]);
+
+    expect(result.startFrame).equal(290);
+    expect(result.highlightFrames).equal(760 - 290);
+    expect(result.audioSegments).deep.equal([
+      { seekSeconds: 290 / fps, durationSeconds: (760 - 290) / fps },
+    ]);
+    expect(result.beatFrameIndices).deep.equal([0, 310]);
+  });
+
+  it('snaps to a tempo grid and prefers a whole number of bars', async function() {
+    const fps = 30;
+    const totalFrames = 2000;
+    const highlightFrames = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+    const spectrums = spectrumsWithEnergyInRange(totalFrames, 505, 505 + highlightFrames);
+    // 120 BPM at 30 fps: a beat every 15 frames, a bar every 60.
+    const beatGrid = { periodFrames: 15, phaseFrame: 5 };
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 1, beatGrid);
+
+    expect((result.startFrame - 5) % 15).equal(0);
+    expect(result.highlightFrames % 60).equal(0);
+    expect(Math.abs(result.startFrame - 505)).lte(MAX_BEAT_SNAP_SEC * fps);
+    expect(Math.abs(result.highlightFrames - highlightFrames)).lte(2 * MAX_BEAT_SNAP_SEC * fps);
+  });
+
+  it('keeps several snapped highlights from overlapping', async function() {
+    const fps = 30;
+    const totalFrames = 3000;
+    const spectrums = Array.from({ length: totalFrames }, (_, i) => [1 + Math.sin(i / 50)]);
+    const beatGrid = { periodFrames: 14, phaseFrame: 3 };
+
+    const result = await computeHighlightSlice(fps, totalFrames, spectrums, [], 4, beatGrid);
+
+    for (let i = 1; i < result.runs.length; i++) {
+      const prev = result.runs[i - 1];
+      expect(result.runs[i].startFrame).gte(prev.startFrame + prev.highlightFrames);
+    }
+  });
+});
+
+describe('buildBeatCandidates', function() {
+  it('uses onsets when no tempo grid is given', function() {
+    expect(buildBeatCandidates(30, 100, [
+      { frameIndex: 40, intensity: 1 },
+      { frameIndex: 10, intensity: 1 },
+      { frameIndex: 10, intensity: 1 },
+    ])).deep.equal([10, 40]);
+  });
+
+  it('uses tracked beats, then the grid nudged onto nearby onsets', function() {
+    const frames = buildBeatCandidates(10, 60, [{ frameIndex: 41, intensity: 1 }], {
+      periodFrames: 10,
+      phaseFrame: 0,
+      beatsSec: [0.1, 1.1, 2.1],
+    });
+    expect(frames).deep.equal([1, 11, 21, 30, 41, 50, 60]);
+  });
+});
+
+describe('snapSegmentToBeats', function() {
+  it('leaves a segment unchanged when no beat is close enough', function() {
+    const seg = { startFrame: 100, highlightFrames: 200 };
+    expect(snapSegmentToBeats(seg, 1000, [10, 900], 20)).deep.equal(seg);
+  });
+});
+
+describe('snapDropToBeat', function() {
+  it('moves the drop and its start together onto a beat within a fifth of a beat', function() {
+    const drop = { startFrame: 60, dropFrame: 103 };
+    snapDropToBeat(drop, [80, 100, 120], 20);
+    expect(drop).deep.equal({ startFrame: 57, dropFrame: 100 });
+  });
+
+  it('keeps the drop when the nearest beat is too far', function() {
+    const drop = { startFrame: 60, dropFrame: 105 };
+    snapDropToBeat(drop, [80, 100, 120], 20);
+    expect(drop).deep.equal({ startFrame: 60, dropFrame: 105 });
+  });
+
+  it('keeps the drop without a tempo period', function() {
+    const drop = { startFrame: 60, dropFrame: 101 };
+    snapDropToBeat(drop, [80, 100, 120]);
+    expect(drop).deep.equal({ startFrame: 60, dropFrame: 101 });
+  });
+
+  it('does not push a lead-in that fit in the track back past its start', function() {
+    const drop = { startFrame: 1, dropFrame: 43 };
+    snapDropToBeat(drop, [40], 20);
+    expect(drop).deep.equal({ startFrame: 1, dropFrame: 43 });
+  });
+});