@audio/beat-onset 1.0.0

package/band.js

@@ -0,0 +1,87 @@
+/**
+ * Multi-band onset detection.
+ * Splits spectrum into logarithmic frequency bands, computes spectral flux per band, sums.
+ * Better at detecting onsets across different instrument ranges.
+ * @param {Float32Array|Float64Array} data - Audio samples (mono)
+ * @param {Object} [opts]
+ * @param {number} [opts.fs=44100] - Sample rate
+ * @param {number} [opts.frameSize=2048] - STFT frame size
+ * @param {number} [opts.hopSize=512] - STFT hop size
+ * @param {number} [opts.bands=4] - Number of frequency bands (logarithmic spacing)
+ * @param {number} [opts.delta=1.4] - Peak-pick threshold multiplier
+ * @param {number} [opts.windowSize=8] - Peak-pick local mean window (frames)
+ * @returns {Float64Array} Onset times in seconds
+ * @see Klapuri, "Sound Onset Detection by Applying Psychoacoustic Knowledge" (ICASSP 1999)
+ */
+
+import fft from 'fourier-transform'
+import { hann } from 'window-function'
+import { peakPick, validate } from '@audio/beat-core'
+
+export default function bandOnsets(data, opts) {
+  validate(data, opts)
+  let fs = opts?.fs || 44100
+  let frameSize = opts?.frameSize || 2048
+  let hopSize = opts?.hopSize || 512
+  let bands = opts?.bands || 4
+
+  let nFrames = Math.floor((data.length - frameSize) / hopSize) + 1
+  if (nFrames < 2) return new Float64Array(0)
+
+  let win = new Float64Array(frameSize)
+  for (let i = 0; i < frameSize; i++) win[i] = hann(i, frameSize)
+
+  let nBins = frameSize / 2
+  // logarithmic band edges (psychoacoustic spacing per Klapuri 1999)
+  let bandEdges = [0]
+  let maxHz = fs / 2
+  let logMin = Math.log(20), logMax = Math.log(maxHz)
+  for (let b = 1; b <= bands; b++) {
+    let hz = Math.exp(logMin + (logMax - logMin) * b / bands)
+    bandEdges.push(Math.min(nBins, Math.max(bandEdges[b - 1] + 1, Math.round(hz / maxHz * nBins))))
+  }
+  bandEdges[bands] = nBins
+
+  // per-band ODF arrays — separate flux timeseries per band
+  let bandOdfs = Array.from({ length: bands }, () => new Float64Array(nFrames))
+  let prevMag = null
+
+  for (let f = 0; f < nFrames; f++) {
+    let offset = f * hopSize
+    let frame = new Float64Array(frameSize)
+    for (let i = 0; i < frameSize; i++) frame[i] = (data[offset + i] || 0) * win[i]
+    let mag = new Float64Array(fft(frame))
+
+    if (prevMag) {
+      for (let b = 0; b < bands; b++) {
+        let lo = bandEdges[b], hi = bandEdges[b + 1], flux = 0
+        for (let i = lo; i < hi; i++) {
+          let diff = mag[i] - prevMag[i]
+          if (diff > 0) flux += diff
+        }
+        bandOdfs[b][f] = flux
+      }
+    }
+    prevMag = mag
+  }
+
+  // peak-pick each band independently, then merge and deduplicate
+  let minGap = hopSize / fs
+  let all = []
+  for (let b = 0; b < bands; b++) {
+    let hasEnergy = false
+    for (let i = 0; i < nFrames; i++) if (bandOdfs[b][i] > 0) { hasEnergy = true; break }
+    if (!hasEnergy) continue
+    let ons = peakPick(bandOdfs[b], { hopSize, fs, ...opts })
+    for (let t of ons) all.push(t)
+  }
+
+  if (!all.length) return new Float64Array(0)
+
+  all.sort((a, b) => a - b)
+  let deduped = [all[0]]
+  for (let i = 1; i < all.length; i++)
+    if (all[i] - deduped[deduped.length - 1] > minGap) deduped.push(all[i])
+
+  return new Float64Array(deduped)
+}

package/energy.js

@@ -0,0 +1,23 @@
+/**
+ * Energy-based onset detection.
+ * Per-frame RMS → positive first differences → adaptive threshold peak-pick.
+ * Simpler and faster than spectral flux. Best for percussive / strong transient signals.
+ * @param {Float32Array|Float64Array} data - Audio samples (mono)
+ * @param {Object} [opts]
+ * @param {number} [opts.fs=44100] - Sample rate
+ * @param {number} [opts.frameSize=2048] - Frame size
+ * @param {number} [opts.hopSize=512] - Hop size
+ * @param {number} [opts.delta=1.4] - Peak-pick threshold multiplier
+ * @param {number} [opts.windowSize=8] - Peak-pick local mean window (frames)
+ * @returns {Float64Array} Onset times in seconds
+ * @see Klapuri, "Auditory Model Based Beat Tracking" (ICMC 1999)
+ */
+
+import { energyFlux, peakPick, validate } from '@audio/beat-core'
+
+export default function energyOnsets(data, opts) {
+  validate(data, opts)
+  let { odf, hopSize, fs } = energyFlux(data, opts)
+  if (!odf.length) return new Float64Array(0)
+  return peakPick(odf, { hopSize, fs, ...opts })
+}

package/index.js

@@ -0,0 +1,22 @@
+/**
+ * Spectral flux onset detection.
+ * STFT → magnitude → sum positive differences → adaptive threshold peak-pick.
+ * @param {Float32Array|Float64Array} data - Audio samples (mono)
+ * @param {Object} [opts]
+ * @param {number} [opts.fs=44100] - Sample rate
+ * @param {number} [opts.frameSize=2048] - STFT frame size
+ * @param {number} [opts.hopSize=512] - Hop between frames
+ * @param {number} [opts.delta=1.4] - Peak-pick threshold multiplier
+ * @param {number} [opts.windowSize=8] - Peak-pick local mean window (frames)
+ * @returns {Float64Array} Onset times in seconds
+ * @see Dixon, "Onset Detection Revisited" (DAFx 2006)
+ */
+
+import { spectralFlux, peakPick, validate } from '@audio/beat-core'
+
+export default function onsets(data, opts) {
+  validate(data, opts)
+  let { odf, hopSize, fs } = spectralFlux(data, opts)
+  if (!odf.length) return new Float64Array(0)
+  return peakPick(odf, { hopSize, fs, ...opts })
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@audio/beat-onset",
+  "version": "1.0.0",
+  "description": "Spectral flux onset detection",
+  "type": "module",
+  "sideEffects": false,
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json",
+    "./energy": "./energy.js",
+    "./phase": "./phase.js",
+    "./band": "./band.js"
+  },
+  "files": [
+    "index.js",
+    "energy.js",
+    "phase.js",
+    "band.js"
+  ],
+  "dependencies": {
+    "@audio/beat-core": "^1.0.0",
+    "fourier-transform": "^2.2.0",
+    "window-function": "^3.0.0"
+  },
+  "keywords": [
+    "audio",
+    "dsp",
+    "beat",
+    "onset",
+    "onset-detection"
+  ],
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/beat.git",
+    "directory": "packages/beat-onset"
+  },
+  "homepage": "https://github.com/audiojs/beat/tree/main/packages/beat-onset",
+  "bugs": {
+    "url": "https://github.com/audiojs/beat/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/phase.js

@@ -0,0 +1,73 @@
+/**
+ * Complex-domain onset detection (phase deviation).
+ * Measures divergence between predicted and actual STFT phase.
+ * More robust to steady-state signals than spectral flux.
+ * @param {Float32Array|Float64Array} data - Audio samples (mono)
+ * @param {Object} [opts]
+ * @param {number} [opts.fs=44100] - Sample rate
+ * @param {number} [opts.frameSize=2048] - STFT frame size
+ * @param {number} [opts.hopSize=512] - STFT hop size
+ * @param {number} [opts.delta=1.4] - Peak-pick threshold multiplier
+ * @param {number} [opts.windowSize=8] - Peak-pick local mean window (frames)
+ * @returns {Float64Array} Onset times in seconds
+ * @see Bello et al., "A Tutorial on Onset Detection in Music Signals" (TASLP 2005)
+ */
+
+import { cfft } from 'fourier-transform'
+import { hann } from 'window-function'
+import { peakPick, validate } from '@audio/beat-core'
+
+export default function phaseOnsets(data, opts) {
+  validate(data, opts)
+  let fs = opts?.fs || 44100
+  let frameSize = opts?.frameSize || 2048
+  let hopSize = opts?.hopSize || 512
+
+  let nFrames = Math.floor((data.length - frameSize) / hopSize) + 1
+  if (nFrames < 3) return new Float64Array(0)
+
+  let win = new Float64Array(frameSize)
+  for (let i = 0; i < frameSize; i++) win[i] = hann(i, frameSize)
+
+  let odf = new Float64Array(nFrames)
+  let prevPhase = null, prevPrevPhase = null
+
+  for (let f = 0; f < nFrames; f++) {
+    let offset = f * hopSize
+    let re = new Float64Array(frameSize)
+    let im = new Float64Array(frameSize)
+    for (let i = 0; i < frameSize; i++) re[i] = (data[offset + i] || 0) * win[i]
+    cfft(re, im)
+
+    let nBins = frameSize / 2
+    let phase = new Float64Array(nBins)
+    let mag = new Float64Array(nBins)
+    for (let i = 0; i < nBins; i++) {
+      mag[i] = Math.sqrt(re[i] * re[i] + im[i] * im[i])
+      phase[i] = Math.atan2(im[i], re[i])
+    }
+
+    // phase deviation: |actual - predicted|, predicted = 2*prev - prevPrev
+    if (prevPhase && prevPrevPhase) {
+      let deviation = 0
+      for (let i = 0; i < nBins; i++) {
+        let predicted = 2 * prevPhase[i] - prevPrevPhase[i]
+        let diff = phase[i] - predicted
+        // wrap to [-π, π]
+        diff -= Math.round(diff / (2 * Math.PI)) * (2 * Math.PI)
+        deviation += Math.abs(diff) * mag[i]
+      }
+      odf[f] = deviation
+    }
+
+    prevPrevPhase = prevPhase
+    prevPhase = phase
+  }
+
+  // check for silence
+  let hasEnergy = false
+  for (let i = 0; i < odf.length; i++) { if (odf[i] > 0) { hasEnergy = true; break } }
+  if (!hasEnergy) return new Float64Array(0)
+
+  return peakPick(odf, { hopSize, fs, ...opts })
+}