suaveplan/packages/media/audio/audio-analysis-beat/README.md

@suaveplan/audio-analysis-beat - Universal beat, tempo and onset detection plugin for the @suaveplan/audio-* family. Three selectable algorithms (energy ODF, spectral flux, comb-filter tempo) plus a phase-aligning beat-grid helper, exposed as an AnalysisOp wrapper with batch / streaming / per-block entry points.

Universal beat, tempo, and onset detection plugin for the @suaveplan/audio-* family. Detects BPM, beat locations, and onset times from AudioDocument streams using energy-based and spectral-flux algorithms, with optional comb-filter tempo estimation and beat-grid phase alignment.

Runs identically in Bun, Node.js, Deno, and every browser — zero browser-only APIs, zero Node-only APIs, hand-rolled radix-2 FFT over typed arrays.

Documentation tree

• beat-grid — Beat-grid construction: given a known beat period and a list of detected onsets, find the phase that aligns a regular `…
• comb-tempo — Comb-filter / autocorrelation tempo estimation. Given an onset-detection function (ODF) and the cadence at which it was…
• energy-odf — Energy onset-detection function (ODF) — the cheapest of the three algorithms shipped by `@suaveplan/audio-analysis-beat…
• spectral-flux — Spectral-flux onset detection via a hand-rolled radix-2 real FFT. This module provides the highest-precision ODF in the…
• detector — BeatDetector is the universal tempo / onset / beat-grid analysis op for the @suaveplan/audio-* family. It impl…
  • beat-detector — BeatDetector is the universal tempo / onset / beat-grid analysis op for the @suaveplan/audio-* family. It impl…
• error-codes — Stable error-code registry and concrete SuaveplanError subclass for @suaveplan/audio-analysis-beat. Every fault thr…
  • error-codes — Stable error-code registry and concrete SuaveplanError subclass for @suaveplan/audio-analysis-beat. Every fault thr…

Install

bun add @suaveplan/audio-analysis-beat

Quick start

import { AudioDocument } from "@suaveplan/audio-core";
import { BeatDetector } from "@suaveplan/audio-analysis-beat";

const doc = new AudioDocument({
	sampleRate: 48_000,
	channels: 1,
	sourceLength: pcm.length,
	pages: [{ channelData: [pcm], startSample: 0 }],
});

const result = await new BeatDetector().analyze(doc);
console.log(result.bpm, result.beats.length, result.confidence);

Algorithms

• energy (default) — half-wave-rectified first differences of per-block energies. Cheap, allocation-light, ideal for percussive content.
• spectral-flux — frame-to-frame magnitude-spectrum differences via a hand-rolled radix-2 real FFT. Catches timbral onsets the energy ODF misses.
• comb — comb-filter / autocorrelation tempo estimation over the energy ODF; more robust on syncopated material at the cost of O(range × odf) scan time.

Entry points

• analyze(doc, opts?) — batch scan; returns a single BeatResult.
• analyzeStream(doc, opts?) — async generator yielding refining BeatResult values with monotone confidence.
• analyzeBlock(block, ctx) — synchronous per-block onset state for visualisers and real-time displays.
• asAnalysisOp getter — the underlying audio-core AnalysisOp wrapper.

See per-module .md files for the deep documentation of each algorithm and entry point.