69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
# @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.
|
||
|