nodejs-audio-visualizer 5.0.0 → 5.2.0

package/src/beats.ts

@@ -1,68 +1,279 @@
-export interface BeatInfo {
-  isBeat: boolean;
-  intensity: number;
-  energy: number;
-  threshold: number;
-}
-
-export interface BeatDetectorOptions {
-  /** Number of past frames to average for adaptive threshold (~1.5s by default) */
-  historySize?: number;
-  /** Energy must exceed average * this multiplier to trigger a beat */
-  thresholdMultiplier?: number;
-  /** How fast the beat intensity fades between beats (0-1, lower = faster fade) */
-  decayRate?: number;
-  /** Minimum frames between consecutive beats (~150ms by default) */
-  cooldownFrames?: number;
-  /** How many low-frequency spectrum bands contribute to energy (sub-bass + bass) */
-  bassEndIndex?: number;
-}
-
-export const createBeatDetector = (fps: number, options?: BeatDetectorOptions) => {
-  const historySize = options?.historySize ?? Math.round(fps * 1.5);
-  const thresholdMultiplier = options?.thresholdMultiplier ?? 1.4;
-  const decayRate = options?.decayRate ?? 0.85;
-  const cooldownFrames = options?.cooldownFrames ?? Math.round(fps * 0.15);
-  const bassEndIndex = options?.bassEndIndex ?? 8;
-
-  const energyHistory: number[] = [];
-  let framesSinceLastBeat = cooldownFrames;
-  let decayingIntensity = 0;
-
-  return (spectrum: number[]): BeatInfo => {
-    const bassSpectrum = spectrum.slice(0, Math.min(bassEndIndex, spectrum.length));
-    const energy = bassSpectrum.reduce((sum, val) => sum + val * val, 0) / bassSpectrum.length;
-
-    energyHistory.push(energy);
-    if (energyHistory.length > historySize) {
-      energyHistory.shift();
-    }
-
-    const avgEnergy = energyHistory.reduce((sum, e) => sum + e, 0) / energyHistory.length;
-    const variance = energyHistory.reduce((sum, e) => sum + (e - avgEnergy) ** 2, 0) / energyHistory.length;
-    const stdDev = Math.sqrt(variance);
-
-    const threshold = avgEnergy + stdDev * thresholdMultiplier;
-
-    framesSinceLastBeat++;
-
-    const hasEnoughHistory = energyHistory.length >= Math.round(historySize / 3);
-    const isAboveThreshold = energy > threshold && hasEnoughHistory;
-    const isCooldownOver = framesSinceLastBeat >= cooldownFrames;
-    const isBeat = isAboveThreshold && isCooldownOver;
-
-    if (isBeat) {
-      framesSinceLastBeat = 0;
-      decayingIntensity = Math.min(1, (energy - threshold) / (stdDev + 1e-6));
-    } else {
-      decayingIntensity *= decayRate;
-    }
-
-    return {
-      isBeat,
-      intensity: decayingIntensity,
-      energy,
-      threshold,
-    };
-  };
-};
+import MusicTempo from 'music-tempo';
+
+export interface BeatInfo {
+  isBeat: boolean;
+  intensity: number;
+  energy: number;
+  threshold: number;
+}
+
+export interface BeatDetectorOptions {
+  /** Number of past frames to average for adaptive threshold (~1.5s by default) */
+  historySize?: number;
+  /** Energy must exceed average * this multiplier to trigger a beat */
+  thresholdMultiplier?: number;
+  /** How fast the beat intensity fades between beats (0-1, lower = faster fade) */
+  decayRate?: number;
+  /** Minimum frames between consecutive beats (~150ms by default) */
+  cooldownFrames?: number;
+  /** How many low-frequency spectrum bands contribute to energy (sub-bass + bass) */
+  bassEndIndex?: number;
+}
+
+export interface TempoEstimate {
+  bpm: number;
+  periodFrames: number;
+  phaseFrame: number;
+  /** Beat times in seconds from the start of the analyzed audio. */
+  beatsSec?: number[];
+}
+
+export const MIN_TEMPO_BPM = 70;
+export const MAX_TEMPO_BPM = 180;
+export const PREFERRED_TEMPO_BPM_MIN = 90;
+export const PREFERRED_TEMPO_BPM_MAX = 160;
+export const DEFAULT_BASS_END_INDEX = 8;
+/** Longest PCM window passed to music-tempo (seconds), taken from the start of the audio. */
+export const MAX_TEMPO_ANALYSIS_SECONDS = 90;
+const TEMPO_TIME_STEP = 0.01;
+
+export const frameBassEnergy = (spectrum: number[], bassEndIndex = DEFAULT_BASS_END_INDEX): number => {
+  const end = Math.min(bassEndIndex, spectrum.length);
+  if (end <= 0) {
+    return 0;
+  }
+  let sum = 0;
+  for (let i = 0; i < end; i++) {
+    const v = spectrum[i];
+    sum += v * v;
+  }
+  return sum / end;
+};
+
+export const createBeatDetector = (fps: number, options?: BeatDetectorOptions) => {
+  const historySize = options?.historySize ?? Math.round(fps * 1.5);
+  const thresholdMultiplier = options?.thresholdMultiplier ?? 1.4;
+  const decayRate = options?.decayRate ?? 0.85;
+  const cooldownFrames = options?.cooldownFrames ?? Math.round(fps * 0.15);
+  const bassEndIndex = options?.bassEndIndex ?? DEFAULT_BASS_END_INDEX;
+
+  const energyHistory: number[] = [];
+  let framesSinceLastBeat = cooldownFrames;
+  let decayingIntensity = 0;
+
+  return (spectrum: number[]): BeatInfo => {
+    const energy = frameBassEnergy(spectrum, bassEndIndex);
+
+    energyHistory.push(energy);
+    if (energyHistory.length > historySize) {
+      energyHistory.shift();
+    }
+
+    const avgEnergy = energyHistory.reduce((sum, e) => sum + e, 0) / energyHistory.length;
+    const variance = energyHistory.reduce((sum, e) => sum + (e - avgEnergy) ** 2, 0) / energyHistory.length;
+    const stdDev = Math.sqrt(variance);
+
+    const threshold = avgEnergy + stdDev * thresholdMultiplier;
+
+    framesSinceLastBeat++;
+
+    const hasEnoughHistory = energyHistory.length >= Math.round(historySize / 3);
+    const isAboveThreshold = energy > threshold && hasEnoughHistory;
+    const isCooldownOver = framesSinceLastBeat >= cooldownFrames;
+    const isBeat = isAboveThreshold && isCooldownOver;
+
+    if (isBeat) {
+      framesSinceLastBeat = 0;
+      decayingIntensity = Math.min(1, (energy - threshold) / (stdDev + 1e-6));
+    } else {
+      decayingIntensity *= decayRate;
+    }
+
+    return {
+      isBeat,
+      intensity: decayingIntensity,
+      energy,
+      threshold,
+    };
+  };
+};
+
+const foldTempoBpm = (bpm: number): number => {
+  let folded = bpm;
+  while (folded > MAX_TEMPO_BPM && folded / 2 >= MIN_TEMPO_BPM) {
+    folded /= 2;
+  }
+  while (folded < MIN_TEMPO_BPM && folded * 2 <= MAX_TEMPO_BPM) {
+    folded *= 2;
+  }
+  return folded;
+};
+
+const samplesToArray = (samples: ArrayLike<number>, maxLength: number): number[] => {
+  const n = Math.min(samples.length, maxLength);
+  if (Array.isArray(samples) && n === samples.length) {
+    return samples;
+  }
+  const audioData = new Array<number>(n);
+  for (let i = 0; i < n; i++) {
+    audioData[i] = samples[i];
+  }
+  return audioData;
+};
+
+const wrapIntoPeriod = (value: number, period: number): number => {
+  if (!(period > 0) || !isFinite(value)) {
+    return 0;
+  }
+  let wrapped = value - period * Math.floor(value / period);
+  if (wrapped < 0) {
+    wrapped += period;
+  }
+  if (wrapped >= period) {
+    wrapped = 0;
+  }
+  return wrapped;
+};
+
+const circularMeanPhase = (frames: number[], period: number): number => {
+  if (!(period > 0) || frames.length === 0) {
+    return 0;
+  }
+  let sinSum = 0;
+  let cosSum = 0;
+  for (const frame of frames) {
+    const angle = (2 * Math.PI * frame) / period;
+    sinSum += Math.sin(angle);
+    cosSum += Math.cos(angle);
+  }
+  const phase = Math.atan2(sinSum, cosSum) * period / (2 * Math.PI);
+  return wrapIntoPeriod(phase, period);
+};
+
+export const estimateTempo = (
+  samples: ArrayLike<number>,
+  sampleRate: number,
+  fps: number,
+): TempoEstimate | null => {
+  if (!samples || samples.length === 0 || !(sampleRate > 0) || !(fps > 0)) {
+    return null;
+  }
+
+  const maxSamples = Math.max(1, Math.floor(sampleRate * MAX_TEMPO_ANALYSIS_SECONDS));
+  const audioData = samplesToArray(samples, maxSamples);
+  const hopSize = Math.max(1, Math.round(sampleRate * TEMPO_TIME_STEP));
+
+  try {
+    const mt = new MusicTempo(audioData, {
+      hopSize,
+      timeStep: TEMPO_TIME_STEP,
+      minBeatInterval: 60 / MAX_TEMPO_BPM,
+      maxBeatInterval: 60 / MIN_TEMPO_BPM,
+    });
+    const beatInterval = Number(mt.beatInterval);
+    let bpm = Number(mt.tempo);
+    if (!(bpm > 0) && beatInterval > 0) {
+      bpm = 60 / beatInterval;
+    }
+    if (!(bpm > 0)) {
+      return null;
+    }
+
+    bpm = foldTempoBpm(bpm);
+    if (bpm < MIN_TEMPO_BPM * 0.9 || bpm > MAX_TEMPO_BPM * 1.1) {
+      return null;
+    }
+
+    const periodFrames = fps * 60 / bpm;
+    const beatsSec = (mt.beats ?? [])
+      .map(t => Number(t))
+      .filter(t => t >= 0 && isFinite(t));
+    const beatFrames = beatsSec.map(t => t * fps);
+    const phaseFrame = beatFrames.length > 0
+      ? wrapIntoPeriod(circularMeanPhase(beatFrames, periodFrames), periodFrames)
+      : 0;
+
+    return {
+      bpm: Math.round(bpm),
+      periodFrames,
+      phaseFrame,
+      ...(beatsSec.length > 0 ? { beatsSec } : {}),
+    };
+  } catch {
+    return null;
+  }
+};
+
+export const shiftTempoPhase = (
+  tempo: TempoEstimate,
+  startFrame: number,
+): TempoEstimate => {
+  const period = tempo.periodFrames;
+  if (!(period > 0) || startFrame === 0) {
+    return tempo;
+  }
+  return {
+    ...tempo,
+    phaseFrame: wrapIntoPeriod(tempo.phaseFrame - startFrame, period),
+  };
+};
+
+/** Beat-grid phase for a later audio window, using in-window beat times when available. */
+export const tempoForWindow = (
+  tempo: TempoEstimate,
+  startFrame: number,
+  fps: number,
+  windowFrames?: number,
+  localOnsetFrames?: number[],
+): TempoEstimate => {
+  const period = tempo.periodFrames;
+  if (!(period > 0) || !(fps > 0)) {
+    return tempo;
+  }
+  const startSec = startFrame / fps;
+  const endSec = windowFrames != null && windowFrames >= 0
+    ? (startFrame + windowFrames) / fps
+    : Number.POSITIVE_INFINITY;
+  const inWindow = (tempo.beatsSec ?? []).filter(t => t >= startSec && t < endSec);
+  if (inWindow.length > 0) {
+    const localFrames = inWindow.map(t => (t - startSec) * fps);
+    return {
+      ...tempo,
+      phaseFrame: wrapIntoPeriod(circularMeanPhase(localFrames, period), period),
+    };
+  }
+  const onsets = (localOnsetFrames ?? []).filter(frame =>
+    frame > 0 && (windowFrames == null || frame < windowFrames),
+  );
+  if (onsets.length > 0) {
+    return {
+      ...tempo,
+      phaseFrame: wrapIntoPeriod(circularMeanPhase(onsets, period), period),
+    };
+  }
+  return shiftTempoPhase(tempo, startFrame);
+};
+
+export const beatGridFrameIndices = (
+  tempo: Pick<TempoEstimate, 'periodFrames' | 'phaseFrame'>,
+  totalFrames: number,
+  stride = 1,
+): number[] => {
+  const period = tempo.periodFrames;
+  const step = Math.max(1, Math.round(stride));
+  if (!(period > 0) || totalFrames <= 1) {
+    return [];
+  }
+  const frames: number[] = [];
+  const nStart = tempo.phaseFrame > 0 ? 0 : 1;
+  for (let n = nStart; ; n += step) {
+    const frame = Math.round(tempo.phaseFrame + n * period);
+    if (frame >= totalFrames) {
+      break;
+    }
+    if (frame > 0) {
+      frames.push(frame);
+    }
+  }
+  return frames;
+};

package/src/bpmEncoder.ts

@@ -1,97 +1,97 @@
-export interface EncodedBmp {
-  shiftPos: number;
-  rowBytes: number;
-  data: Buffer;
-}
-
-const writeBmpHeader = (buffer: Buffer, width: number, height: number, rgbSize: number) => {
-  const headerInfoSize = 40;
-  const offset = 54;
-  const fileSize = rgbSize + offset;
-
-  let pos = 0;
-  buffer.write('BM', pos, 2); pos += 2;
-  buffer.writeUInt32LE(fileSize, pos); pos += 4;
-  buffer.writeUInt32LE(0, pos); pos += 4;
-  buffer.writeUInt32LE(offset, pos); pos += 4;
-
-  buffer.writeUInt32LE(headerInfoSize, pos); pos += 4;
-  buffer.writeUInt32LE(width, pos); pos += 4;
-  buffer.writeInt32LE(-height, pos); pos += 4;
-  buffer.writeUInt16LE(1, pos); pos += 2;
-  buffer.writeUInt16LE(24, pos); pos += 2;
-  buffer.writeUInt32LE(0, pos); pos += 4;
-  buffer.writeUInt32LE(rgbSize, pos); pos += 4;
-  buffer.writeUInt32LE(0, pos); pos += 4;
-  buffer.writeUInt32LE(0, pos); pos += 4;
-  buffer.writeUInt32LE(0, pos); pos += 4;
-  buffer.writeUInt32LE(0, pos); pos += 4;
-
-  return offset;
-};
-
-export const createBpmEncoder = (imgData: { width: number; height: number; }) => {
-  const width = imgData.width;
-  const height = imgData.height;
-  const extraBytes = width % 4;
-  const rgbSize = height * (3 * width + extraBytes);
-  const offset = 54;
-
-  return (buffer: Buffer): EncodedBmp => {
-    const tempBuffer = Buffer.alloc(offset + rgbSize);
-    const pos = writeBmpHeader(tempBuffer, width, height, rgbSize);
-
-    let i = 0;
-    const rowBytes = 3 * width + extraBytes;
-
-    for (let y = 0; y < height; y++) {
-      for (let x = 0; x < width; x++) {
-        const p = pos + y * rowBytes + x * 3;
-        i++; // a
-        tempBuffer[p] = buffer[i++]; // b
-        tempBuffer[p + 1] = buffer[i++]; // g
-        tempBuffer[p + 2] = buffer[i++]; // r
-      }
-      if (extraBytes > 0) {
-        const fillOffset = pos + y * rowBytes + width * 3;
-        tempBuffer.fill(0, fillOffset, fillOffset + extraBytes);
-      }
-    }
-
-    return {
-      shiftPos: pos,
-      rowBytes,
-      data: tempBuffer
-    };
-  };
-};
-
-export const createBgrFrameEncoder = (imgData: { width: number; height: number }) => {
-  const width = imgData.width;
-  const height = imgData.height;
-  const extraBytes = width % 4;
-  const rowBytes = 3 * width + extraBytes;
-  const rgbSize = height * rowBytes;
-  const offset = 54;
-
-  const tempBuffer = Buffer.alloc(offset + rgbSize);
-  const pos = writeBmpHeader(tempBuffer, width, height, rgbSize);
-
-  return (bgrBuffer: Buffer): EncodedBmp => {
-    if (extraBytes === 0) {
-      bgrBuffer.copy(tempBuffer, pos, 0, width * height * 3);
-    } else {
-      for (let y = 0; y < height; y++) {
-        const srcOffset = y * width * 3;
-        const dstOffset = pos + y * rowBytes;
-        bgrBuffer.copy(tempBuffer, dstOffset, srcOffset, srcOffset + width * 3);
-      }
-    }
-
-    return {
-      shiftPos: pos,
-      rowBytes,
-      data: tempBuffer
-    };
-  };
-};
+export interface EncodedBmp {
+  shiftPos: number;
+  rowBytes: number;
+  data: Buffer;
+}
+
+const writeBmpHeader = (buffer: Buffer, width: number, height: number, rgbSize: number) => {
+  const headerInfoSize = 40;
+  const offset = 54;
+  const fileSize = rgbSize + offset;
+
+  let pos = 0;
+  buffer.write('BM', pos, 2); pos += 2;
+  buffer.writeUInt32LE(fileSize, pos); pos += 4;
+  buffer.writeUInt32LE(0, pos); pos += 4;
+  buffer.writeUInt32LE(offset, pos); pos += 4;
+
+  buffer.writeUInt32LE(headerInfoSize, pos); pos += 4;
+  buffer.writeUInt32LE(width, pos); pos += 4;
+  buffer.writeInt32LE(-height, pos); pos += 4;
+  buffer.writeUInt16LE(1, pos); pos += 2;
+  buffer.writeUInt16LE(24, pos); pos += 2;
+  buffer.writeUInt32LE(0, pos); pos += 4;
+  buffer.writeUInt32LE(rgbSize, pos); pos += 4;
+  buffer.writeUInt32LE(0, pos); pos += 4;
+  buffer.writeUInt32LE(0, pos); pos += 4;
+  buffer.writeUInt32LE(0, pos); pos += 4;
+  buffer.writeUInt32LE(0, pos); pos += 4;
+
+  return offset;
+};
+
+export const createBpmEncoder = (imgData: { width: number; height: number; }) => {
+  const width = imgData.width;
+  const height = imgData.height;
+  const extraBytes = width % 4;
+  const rgbSize = height * (3 * width + extraBytes);
+  const offset = 54;
+
+  return (buffer: Buffer): EncodedBmp => {
+    const tempBuffer = Buffer.alloc(offset + rgbSize);
+    const pos = writeBmpHeader(tempBuffer, width, height, rgbSize);
+
+    let i = 0;
+    const rowBytes = 3 * width + extraBytes;
+
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const p = pos + y * rowBytes + x * 3;
+        i++; // a
+        tempBuffer[p] = buffer[i++]; // b
+        tempBuffer[p + 1] = buffer[i++]; // g
+        tempBuffer[p + 2] = buffer[i++]; // r
+      }
+      if (extraBytes > 0) {
+        const fillOffset = pos + y * rowBytes + width * 3;
+        tempBuffer.fill(0, fillOffset, fillOffset + extraBytes);
+      }
+    }
+
+    return {
+      shiftPos: pos,
+      rowBytes,
+      data: tempBuffer
+    };
+  };
+};
+
+export const createBgrFrameEncoder = (imgData: { width: number; height: number }) => {
+  const width = imgData.width;
+  const height = imgData.height;
+  const extraBytes = width % 4;
+  const rowBytes = 3 * width + extraBytes;
+  const rgbSize = height * rowBytes;
+  const offset = 54;
+
+  const tempBuffer = Buffer.alloc(offset + rgbSize);
+  const pos = writeBmpHeader(tempBuffer, width, height, rgbSize);
+
+  return (bgrBuffer: Buffer): EncodedBmp => {
+    if (extraBytes === 0) {
+      bgrBuffer.copy(tempBuffer, pos, 0, width * height * 3);
+    } else {
+      for (let y = 0; y < height; y++) {
+        const srcOffset = y * width * 3;
+        const dstOffset = pos + y * rowBytes;
+        bgrBuffer.copy(tempBuffer, dstOffset, srcOffset, srcOffset + width * 3);
+      }
+    }
+
+    return {
+      shiftPos: pos,
+      rowBytes,
+      data: tempBuffer
+    };
+  };
+};