# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
bun add @suaveplan/audio-analysis-beat
```

## Quick start

```ts
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.