nodejs-audio-visualizer 5.1.0 → 5.3.0

package/src/highlight.ts

@@ -1,291 +1,451 @@
-/** Output length per segment when `audio.autoHighlight` is true (seconds). */
-
-import { waitForEventLoop } from "./waitForEventLoop";
-
-export const HIGHLIGHT_DURATION_SEC = 15;
-
-export interface BeatFrameEvent {
-  frameIndex: number;
-  intensity: number;
-}
-
-export interface HighlightAudioSegment {
-  seekSeconds: number;
-  durationSeconds: number;
-}
-
-/** One auto-highlight segment before concatenation (for separate output files). */
-export interface HighlightRun {
-  startFrame: number;
-  highlightFrames: number;
-  spectrums: number[][];
-  beatFrameIndices: number[];
-  beatIntensities: number[];
-  audioSegment: HighlightAudioSegment;
-}
-
-function buildHighlightRun(
-  fps: number,
-  seg: { startFrame: number; highlightFrames: number },
-  spectrums: number[][],
-  beatEvents: BeatFrameEvent[],
-): HighlightRun {
-  const { startFrame, highlightFrames } = seg;
-  const spectrumsSlice = spectrums.slice(startFrame, startFrame + highlightFrames);
-  const beatsInWindow = beatEvents
-    .filter(b => b.frameIndex >= startFrame && b.frameIndex < startFrame + highlightFrames)
-    .sort((a, b) => a.frameIndex - b.frameIndex);
-  const beatFrameIndices = beatsInWindow.map(b => b.frameIndex - startFrame);
-  const beatIntensities = beatsInWindow.map(b => b.intensity);
-  return {
-    startFrame,
-    highlightFrames,
-    spectrums: spectrumsSlice,
-    beatFrameIndices,
-    beatIntensities,
-    audioSegment: {
-      seekSeconds: startFrame / fps,
-      durationSeconds: highlightFrames / fps,
-    },
-  };
-}
-
-function frameEnergy(spectrum: number[]): number {
-  let s = 0;
-  for (let i = 0; i < spectrum.length; i++) {
-    const v = spectrum[i];
-    s += v * v;
-  }
-  return s;
-}
-
-function rangesOverlap(
-  aStart: number,
-  aEndExclusive: number,
-  ranges: Array<{ start: number; endExclusive: number }>,
-): boolean {
-  for (const r of ranges) {
-    if (aStart < r.endExclusive && aEndExclusive > r.start) {
-      return true;
-    }
-  }
-  return false;
-}
-
-async function buildFrameEnergies(
-  spectrums: number[][],
-  totalFrames: number,
-): Promise<Float64Array> {
-  const energies = new Float64Array(totalFrames);
-  for (let i = 0; i < totalFrames; i++) {
-    energies[i] = frameEnergy(spectrums[i] ?? []);
-    await waitForEventLoop();
-  }
-  return energies;
-}
-
-/**
- * Chooses the fixed-length window whose frames have the highest summed spectral energy
- * (typical chorus / drop vs a single loud intro transient).
- * Skips windows that overlap any excluded range.
- */
-async function findBestHighlightStart(
-  energies: Float64Array,
-  totalFrames: number,
-  windowFrames: number,
-  excludeRanges: Array<{ start: number; endExclusive: number }>,
-): Promise<number | null> {
-  if (totalFrames <= windowFrames) {
-    if (!rangesOverlap(0, totalFrames, excludeRanges)) {
-      return 0;
-    }
-    return null;
-  }
-
-  let minE = Infinity;
-  let maxE = -Infinity;
-  for (let i = 0; i < totalFrames; i++) {
-    const e = energies[i];
-    if (e < minE) {
-      minE = e;
-    }
-    if (e > maxE) {
-      maxE = e;
-    }
-    await waitForEventLoop();
-  }
-
-  const prefix = new Float64Array(totalFrames + 1);
-  for (let i = 0; i < totalFrames; i++) {
-    prefix[i + 1] = prefix[i] + energies[i];
-    await waitForEventLoop();
-  }
-
-  const maxStart = totalFrames - windowFrames;
-  let bestStart: number | null = null;
-  let bestScore = -Infinity;
-
-  for (let start = 0; start <= maxStart; start++) {
-    if (rangesOverlap(start, start + windowFrames, excludeRanges)) {
-      await waitForEventLoop();
-      continue;
-    }
-    const score = prefix[start + windowFrames] - prefix[start];
-    if (score > bestScore) {
-      bestScore = score;
-      bestStart = start;
-    }
-    await waitForEventLoop();
-  }
-
-  if (bestStart === null) {
-    return null;
-  }
-
-  if (maxE <= minE) {
-    const center = Math.floor((totalFrames - windowFrames) / 2);
-    let bestDist = Infinity;
-    let tieBreak: number | null = null;
-    for (let start = 0; start <= maxStart; start++) {
-      if (rangesOverlap(start, start + windowFrames, excludeRanges)) {
-        await waitForEventLoop();
-        continue;
-      }
-      const dist = Math.abs(start - center);
-      if (dist < bestDist) {
-        bestDist = dist;
-        tieBreak = start;
-      }
-      await waitForEventLoop();
-    }
-    return tieBreak;
-  }
-
-  return bestStart;
-}
-
-
-/**
- * Picks up to `segmentCount` non-overlapping 15s windows with highest summed spectral energy each,
- * sorts them chronologically, concatenates spectrums, and remaps beat indices.
- */
-export async function computeHighlightSlice(
-  fps: number,
-  totalFrames: number,
-  spectrums: number[][],
-  beatEvents: BeatFrameEvent[],
-  segmentCount = 1,
-): Promise<{
-  startFrame: number;
-  highlightFrames: number;
-  spectrums: number[][];
-  beatFrameIndices: number[];
-  beatIntensities: number[];
-  audioSeekSeconds: number;
-  audioDurationSeconds: number;
-  audioSegments: HighlightAudioSegment[];
-  runs: HighlightRun[];
-}> {
-  const highlightFramesTarget = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
-
-  if (totalFrames <= 0) {
-    return {
-      startFrame: 0,
-      highlightFrames: 0,
-      spectrums: [],
-      beatFrameIndices: [],
-      beatIntensities: [],
-      audioSeekSeconds: 0,
-      audioDurationSeconds: 0,
-      audioSegments: [],
-      runs: [],
-    };
-  }
-
-  if (totalFrames <= highlightFramesTarget) {
-    const audioSegments: HighlightAudioSegment[] = [
-      {
-        seekSeconds: 0,
-        durationSeconds: totalFrames / fps,
-      },
-    ];
-    const fullSeg = { startFrame: 0, highlightFrames: totalFrames };
-    const fullRun = buildHighlightRun(fps, fullSeg, spectrums, beatEvents);
-    return {
-      startFrame: 0,
-      highlightFrames: totalFrames,
-      spectrums: spectrums.slice(),
-      beatFrameIndices: fullRun.beatFrameIndices,
-      beatIntensities: fullRun.beatIntensities,
-      audioSeekSeconds: 0,
-      audioDurationSeconds: totalFrames / fps,
-      audioSegments,
-      runs: [fullRun],
-    };
-  }
-
-  const highlightFrames = highlightFramesTarget;
-  const energies = await buildFrameEnergies(spectrums, totalFrames);
-  const excludeRanges: Array<{ start: number; endExclusive: number }> = [];
-  const rawSegments: Array<{ startFrame: number; highlightFrames: number }> = [];
-
-  const n = Math.max(1, Math.floor(segmentCount));
-  for (let k = 0; k < n; k++) {
-    const startFrame = await findBestHighlightStart(
-      energies,
-      totalFrames,
-      highlightFrames,
-      excludeRanges,
-    );
-    if (startFrame === null) {
-      break;
-    }
-    rawSegments.push({ startFrame, highlightFrames });
-    excludeRanges.push({ start: startFrame, endExclusive: startFrame + highlightFrames });
-  }
-
-  rawSegments.sort((a, b) => a.startFrame - b.startFrame);
-
-  const runs = rawSegments.map(seg =>
-    buildHighlightRun(fps, seg, spectrums, beatEvents),
-  );
-
-  const slicedSpectrums: number[][] = [];
-  const beatFrameIndices: number[] = [];
-  const beatIntensities: number[] = [];
-  let outOffset = 0;
-
-  for (const seg of rawSegments) {
-    const chunk = spectrums.slice(seg.startFrame, seg.startFrame + seg.highlightFrames);
-    slicedSpectrums.push(...chunk);
-
-    const beatsInSeg = beatEvents
-      .filter(b => b.frameIndex >= seg.startFrame && b.frameIndex < seg.startFrame + seg.highlightFrames)
-      .sort((a, b) => a.frameIndex - b.frameIndex);
-    for (const b of beatsInSeg) {
-      beatFrameIndices.push(b.frameIndex - seg.startFrame + outOffset);
-      beatIntensities.push(b.intensity);
-    }
-    outOffset += seg.highlightFrames;
-  }
-
-  const totalHighlightFrames = slicedSpectrums.length;
-  const audioSegments: HighlightAudioSegment[] = rawSegments.map(seg => ({
-    seekSeconds: seg.startFrame / fps,
-    durationSeconds: seg.highlightFrames / fps,
-  }));
-
-  const first = audioSegments[0] ?? { seekSeconds: 0, durationSeconds: 0 };
-
-  return {
-    startFrame: rawSegments[0]?.startFrame ?? 0,
-    highlightFrames: totalHighlightFrames,
-    spectrums: slicedSpectrums,
-    beatFrameIndices,
-    beatIntensities,
-    audioSeekSeconds: first.seekSeconds,
-    audioDurationSeconds: first.durationSeconds,
-    audioSegments,
-    runs,
-  };
-}
+/** Output length per segment when `audio.autoHighlight` is true (seconds). */
+
+import { waitForEventLoop } from "./waitForEventLoop";
+
+export const HIGHLIGHT_DURATION_SEC = 15;
+
+export interface BeatFrameEvent {
+  frameIndex: number;
+  intensity: number;
+}
+
+/**
+ * How far (seconds) a highlight boundary may move to land on a beat. The final length can
+ * therefore differ from `HIGHLIGHT_DURATION_SEC` by up to twice this value.
+ */
+export const MAX_BEAT_SNAP_SEC = 1.5;
+/** Beats per bar used when preferring highlight lengths made of whole bars. */
+const BEATS_PER_BAR = 4;
+/** Cost (in beats of boundary shift) for each beat the length is away from a whole bar. */
+const OFF_BAR_PENALTY = 3;
+/** Grid beats past the analyzed tempo region snap to a detected onset within this share of a beat. */
+const GRID_ONSET_SNAP_SHARE = 0.2;
+
+/** Tempo grid used to snap highlight cuts to beats (subset of `TempoEstimate`). */
+export interface HighlightBeatGrid {
+  periodFrames: number;
+  phaseFrame: number;
+  /** Beat times in seconds from the start of the audio. */
+  beatsSec?: number[];
+}
+
+export interface HighlightAudioSegment {
+  seekSeconds: number;
+  durationSeconds: number;
+}
+
+/** One auto-highlight segment before concatenation (for separate output files). */
+export interface HighlightRun {
+  startFrame: number;
+  highlightFrames: number;
+  spectrums: number[][];
+  beatFrameIndices: number[];
+  beatIntensities: number[];
+  audioSegment: HighlightAudioSegment;
+}
+
+function buildHighlightRun(
+  fps: number,
+  seg: { startFrame: number; highlightFrames: number },
+  spectrums: number[][],
+  beatEvents: BeatFrameEvent[],
+): HighlightRun {
+  const { startFrame, highlightFrames } = seg;
+  const spectrumsSlice = spectrums.slice(startFrame, startFrame + highlightFrames);
+  const beatsInWindow = beatEvents
+    .filter(b => b.frameIndex >= startFrame && b.frameIndex < startFrame + highlightFrames)
+    .sort((a, b) => a.frameIndex - b.frameIndex);
+  const beatFrameIndices = beatsInWindow.map(b => b.frameIndex - startFrame);
+  const beatIntensities = beatsInWindow.map(b => b.intensity);
+  return {
+    startFrame,
+    highlightFrames,
+    spectrums: spectrumsSlice,
+    beatFrameIndices,
+    beatIntensities,
+    audioSegment: {
+      seekSeconds: startFrame / fps,
+      durationSeconds: highlightFrames / fps,
+    },
+  };
+}
+
+function frameEnergy(spectrum: number[]): number {
+  let s = 0;
+  for (let i = 0; i < spectrum.length; i++) {
+    const v = spectrum[i];
+    s += v * v;
+  }
+  return s;
+}
+
+function rangesOverlap(
+  aStart: number,
+  aEndExclusive: number,
+  ranges: Array<{ start: number; endExclusive: number }>,
+): boolean {
+  for (const r of ranges) {
+    if (aStart < r.endExclusive && aEndExclusive > r.start) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function buildFrameEnergies(
+  spectrums: number[][],
+  totalFrames: number,
+): Promise<Float64Array> {
+  const energies = new Float64Array(totalFrames);
+  for (let i = 0; i < totalFrames; i++) {
+    energies[i] = frameEnergy(spectrums[i] ?? []);
+    await waitForEventLoop();
+  }
+  return energies;
+}
+
+/**
+ * Chooses the fixed-length window whose frames have the highest summed spectral energy
+ * (typical chorus / drop vs a single loud intro transient).
+ * Skips windows that overlap any excluded range.
+ */
+async function findBestHighlightStart(
+  energies: Float64Array,
+  totalFrames: number,
+  windowFrames: number,
+  excludeRanges: Array<{ start: number; endExclusive: number }>,
+): Promise<number | null> {
+  if (totalFrames <= windowFrames) {
+    if (!rangesOverlap(0, totalFrames, excludeRanges)) {
+      return 0;
+    }
+    return null;
+  }
+
+  let minE = Infinity;
+  let maxE = -Infinity;
+  for (let i = 0; i < totalFrames; i++) {
+    const e = energies[i];
+    if (e < minE) {
+      minE = e;
+    }
+    if (e > maxE) {
+      maxE = e;
+    }
+    await waitForEventLoop();
+  }
+
+  const prefix = new Float64Array(totalFrames + 1);
+  for (let i = 0; i < totalFrames; i++) {
+    prefix[i + 1] = prefix[i] + energies[i];
+    await waitForEventLoop();
+  }
+
+  const maxStart = totalFrames - windowFrames;
+  let bestStart: number | null = null;
+  let bestScore = -Infinity;
+
+  for (let start = 0; start <= maxStart; start++) {
+    if (rangesOverlap(start, start + windowFrames, excludeRanges)) {
+      await waitForEventLoop();
+      continue;
+    }
+    const score = prefix[start + windowFrames] - prefix[start];
+    if (score > bestScore) {
+      bestScore = score;
+      bestStart = start;
+    }
+    await waitForEventLoop();
+  }
+
+  if (bestStart === null) {
+    return null;
+  }
+
+  if (maxE <= minE) {
+    const center = Math.floor((totalFrames - windowFrames) / 2);
+    let bestDist = Infinity;
+    let tieBreak: number | null = null;
+    for (let start = 0; start <= maxStart; start++) {
+      if (rangesOverlap(start, start + windowFrames, excludeRanges)) {
+        await waitForEventLoop();
+        continue;
+      }
+      const dist = Math.abs(start - center);
+      if (dist < bestDist) {
+        bestDist = dist;
+        tieBreak = start;
+      }
+      await waitForEventLoop();
+    }
+    return tieBreak;
+  }
+
+  return bestStart;
+}
+
+function nearestOnset(sortedOnsets: number[], frame: number): number | null {
+  let lo = 0;
+  let hi = sortedOnsets.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (sortedOnsets[mid] < frame) {
+      lo = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+  let best: number | null = null;
+  for (const i of [lo - 1, lo]) {
+    if (i >= 0 && i < sortedOnsets.length) {
+      const v = sortedOnsets[i];
+      if (best === null || Math.abs(v - frame) < Math.abs(best - frame)) {
+        best = v;
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * Beat frames (sorted, unique, within [0, totalFrames]) where a highlight may start or end.
+ * With a tempo grid: tracked beats from the analyzed region, then the regular grid beyond it
+ * (each grid beat nudged onto a nearby detected onset to follow slight tempo drift).
+ * Without one: the detected onset beats.
+ */
+export function buildBeatCandidates(
+  fps: number,
+  totalFrames: number,
+  beatEvents: BeatFrameEvent[],
+  beatGrid?: HighlightBeatGrid | null,
+): number[] {
+  const onsets = Array.from(new Set(beatEvents.map(b => b.frameIndex)))
+    .filter(f => f >= 0 && f <= totalFrames)
+    .sort((a, b) => a - b);
+  const period = beatGrid?.periodFrames ?? 0;
+  if (!beatGrid || !(period > 0) || !isFinite(period)) {
+    return onsets;
+  }
+
+  const frames = new Set<number>();
+  let lastTracked = -Infinity;
+  for (const t of beatGrid.beatsSec ?? []) {
+    const f = Math.round(t * fps);
+    if (f >= 0 && f <= totalFrames) {
+      frames.add(f);
+      lastTracked = Math.max(lastTracked, f);
+    }
+  }
+
+  const maxOnsetShift = period * GRID_ONSET_SNAP_SHARE;
+  const firstN = Math.ceil(-beatGrid.phaseFrame / period);
+  for (let n = firstN; ; n++) {
+    const gridFrame = beatGrid.phaseFrame + n * period;
+    if (gridFrame > totalFrames) {
+      break;
+    }
+    if (gridFrame <= lastTracked + period / 2) {
+      continue;
+    }
+    const onset = nearestOnset(onsets, gridFrame);
+    const f = onset !== null && Math.abs(onset - gridFrame) <= maxOnsetShift
+      ? onset
+      : Math.round(gridFrame);
+    if (f >= 0 && f <= totalFrames) {
+      frames.add(f);
+    }
+  }
+  return Array.from(frames).sort((a, b) => a - b);
+}
+
+/**
+ * Moves a fixed-length window's start and end onto beats (each by at most `maxShiftFrames`),
+ * preferring lengths that span whole bars when the beat period is known.
+ * Boundaries without a nearby beat stay where they are.
+ */
+export function snapSegmentToBeats(
+  seg: { startFrame: number; highlightFrames: number },
+  totalFrames: number,
+  beatFrames: number[],
+  maxShiftFrames: number,
+  periodFrames?: number,
+): { startFrame: number; highlightFrames: number } {
+  const rawStart = seg.startFrame;
+  const rawEnd = seg.startFrame + seg.highlightFrames;
+  const near = (target: number, max: number) =>
+    beatFrames.filter(f => Math.abs(f - target) <= maxShiftFrames && f >= 0 && f <= max);
+  const startCands = near(rawStart, totalFrames - 1);
+  const endCands = near(rawEnd, totalFrames);
+  if (startCands.length === 0) {
+    startCands.push(rawStart);
+  }
+  if (endCands.length === 0) {
+    endCands.push(Math.min(rawEnd, totalFrames));
+  }
+
+  const period = periodFrames && periodFrames > 0 && isFinite(periodFrames) ? periodFrames : 0;
+  const shiftUnit = period > 0 ? period : Math.max(1, maxShiftFrames);
+  let best: { startFrame: number; endFrame: number } | null = null;
+  let bestCost = Infinity;
+  for (const s of startCands) {
+    for (const e of endCands) {
+      if (e - s < seg.highlightFrames / 2) {
+        continue;
+      }
+      let cost = (Math.abs(s - rawStart) + Math.abs(e - rawEnd)) / shiftUnit;
+      if (period > 0) {
+        const beats = Math.round((e - s) / period);
+        const offBar = Math.abs(beats - BEATS_PER_BAR * Math.round(beats / BEATS_PER_BAR));
+        cost += offBar * OFF_BAR_PENALTY;
+      }
+      if (cost < bestCost) {
+        bestCost = cost;
+        best = { startFrame: s, endFrame: e };
+      }
+    }
+  }
+  if (!best) {
+    return seg;
+  }
+  return { startFrame: best.startFrame, highlightFrames: best.endFrame - best.startFrame };
+}
+
+/**
+ * Picks up to `segmentCount` non-overlapping ~15s windows with highest summed spectral energy each,
+ * moves their boundaries onto beats (see `snapSegmentToBeats`), sorts them chronologically,
+ * concatenates spectrums, and remaps beat indices.
+ */
+export async function computeHighlightSlice(
+  fps: number,
+  totalFrames: number,
+  spectrums: number[][],
+  beatEvents: BeatFrameEvent[],
+  segmentCount = 1,
+  beatGrid?: HighlightBeatGrid | null,
+): Promise<{
+  startFrame: number;
+  highlightFrames: number;
+  spectrums: number[][];
+  beatFrameIndices: number[];
+  beatIntensities: number[];
+  audioSeekSeconds: number;
+  audioDurationSeconds: number;
+  audioSegments: HighlightAudioSegment[];
+  runs: HighlightRun[];
+}> {
+  const highlightFramesTarget = Math.ceil(HIGHLIGHT_DURATION_SEC * fps);
+
+  if (totalFrames <= 0) {
+    return {
+      startFrame: 0,
+      highlightFrames: 0,
+      spectrums: [],
+      beatFrameIndices: [],
+      beatIntensities: [],
+      audioSeekSeconds: 0,
+      audioDurationSeconds: 0,
+      audioSegments: [],
+      runs: [],
+    };
+  }
+
+  if (totalFrames <= highlightFramesTarget) {
+    const audioSegments: HighlightAudioSegment[] = [
+      {
+        seekSeconds: 0,
+        durationSeconds: totalFrames / fps,
+      },
+    ];
+    const fullSeg = { startFrame: 0, highlightFrames: totalFrames };
+    const fullRun = buildHighlightRun(fps, fullSeg, spectrums, beatEvents);
+    return {
+      startFrame: 0,
+      highlightFrames: totalFrames,
+      spectrums: spectrums.slice(),
+      beatFrameIndices: fullRun.beatFrameIndices,
+      beatIntensities: fullRun.beatIntensities,
+      audioSeekSeconds: 0,
+      audioDurationSeconds: totalFrames / fps,
+      audioSegments,
+      runs: [fullRun],
+    };
+  }
+
+  const highlightFrames = highlightFramesTarget;
+  const energies = await buildFrameEnergies(spectrums, totalFrames);
+  const excludeRanges: Array<{ start: number; endExclusive: number }> = [];
+  const rawSegments: Array<{ startFrame: number; highlightFrames: number }> = [];
+  const beatFrames = buildBeatCandidates(fps, totalFrames, beatEvents, beatGrid);
+  const maxShiftFrames = Math.round(MAX_BEAT_SNAP_SEC * fps);
+
+  const n = Math.max(1, Math.floor(segmentCount));
+  for (let k = 0; k < n; k++) {
+    const startFrame = await findBestHighlightStart(
+      energies,
+      totalFrames,
+      highlightFrames,
+      excludeRanges,
+    );
+    if (startFrame === null) {
+      break;
+    }
+    const snapped = snapSegmentToBeats(
+      { startFrame, highlightFrames },
+      totalFrames,
+      beatFrames,
+      maxShiftFrames,
+      beatGrid?.periodFrames,
+    );
+    rawSegments.push(snapped);
+    // Padded so the next raw window, once snapped, cannot reach back into this one.
+    excludeRanges.push({
+      start: snapped.startFrame - maxShiftFrames,
+      endExclusive: snapped.startFrame + snapped.highlightFrames + maxShiftFrames,
+    });
+  }
+
+  rawSegments.sort((a, b) => a.startFrame - b.startFrame);
+
+  const runs = rawSegments.map(seg =>
+    buildHighlightRun(fps, seg, spectrums, beatEvents),
+  );
+
+  const slicedSpectrums: number[][] = [];
+  const beatFrameIndices: number[] = [];
+  const beatIntensities: number[] = [];
+  let outOffset = 0;
+
+  for (const seg of rawSegments) {
+    const chunk = spectrums.slice(seg.startFrame, seg.startFrame + seg.highlightFrames);
+    slicedSpectrums.push(...chunk);
+
+    const beatsInSeg = beatEvents
+      .filter(b => b.frameIndex >= seg.startFrame && b.frameIndex < seg.startFrame + seg.highlightFrames)
+      .sort((a, b) => a.frameIndex - b.frameIndex);
+    for (const b of beatsInSeg) {
+      beatFrameIndices.push(b.frameIndex - seg.startFrame + outOffset);
+      beatIntensities.push(b.intensity);
+    }
+    outOffset += seg.highlightFrames;
+  }
+
+  const totalHighlightFrames = slicedSpectrums.length;
+  const audioSegments: HighlightAudioSegment[] = rawSegments.map(seg => ({
+    seekSeconds: seg.startFrame / fps,
+    durationSeconds: seg.highlightFrames / fps,
+  }));
+
+  const first = audioSegments[0] ?? { seekSeconds: 0, durationSeconds: 0 };
+
+  return {
+    startFrame: rawSegments[0]?.startFrame ?? 0,
+    highlightFrames: totalHighlightFrames,
+    spectrums: slicedSpectrums,
+    beatFrameIndices,
+    beatIntensities,
+    audioSeekSeconds: first.seekSeconds,
+    audioDurationSeconds: first.durationSeconds,
+    audioSegments,
+    runs,
+  };
+}