API reference

Every public class, method, and event in @codexo/exojs. Generated from source.

C

classBeatDetector

@codexo/exojs-audio-fx / audio / stable

Real-time tempo + beat tracker. Splits work between the audio-rendering thread (an AudioWorklet that runs onset detection, tempogram analysis, and parallel 3/4 and 4/4 posterior estimation) and the main thread (this class - receives beats, fires Signals, handles configuration and source routing). Accepts a wide range of BeatDetectorSources - a bus, an individual Voice, a raw MediaStream, or any AudioNode - and exposes a Signal for each notable event: - BeatDetector.onBeat - every detected beat - BeatDetector.onDownbeat - first beat of each bar - BeatDetector.onBarStart - bar boundary - BeatDetector.onTempoChange - when the tracked BPM changes - BeatDetector.onBeatPredicted - look-ahead schedule notice Early beats arrive with low latency tagged `status: 'provisional'` (after a short `minSettlingMs` warm-up, default 400 ms) for snappy visual reactivity, then promote to `status: 'locked'` once the tempo grid is trustworthy - a single BeatDetector.onBeat signal carries both via BeatInfo.status. Set `emitProvisionalBeats: false` to receive only locked beats. Time-signature detection (3/4 vs 4/4) is on by default; lock to 4/4 by setting `enableTimeSignatureDetection: false`.

26
props
2
methods
5
events
Import
import { BeatDetector } from '@codexo/exojs-audio-fx'

Real-time tempo + beat tracker. Splits work between the audio-rendering thread (an AudioWorklet that runs onset detection, tempogram analysis, and parallel 3/4 and 4/4 posterior estimation) and the main thread (this class - receives beats, fires Signals, handles configuration and source routing).

Accepts a wide range of BeatDetectorSources - a bus, an individual Voice, a raw MediaStream, or any AudioNode - and exposes a Signal for each notable event: - BeatDetector.onBeat - every detected beat - BeatDetector.onDownbeat - first beat of each bar - BeatDetector.onBarStart - bar boundary - BeatDetector.onTempoChange - when the tracked BPM changes - BeatDetector.onBeatPredicted - look-ahead schedule notice

Early beats arrive with low latency tagged `status: 'provisional'` (after a short `minSettlingMs` warm-up, default 400 ms) for snappy visual reactivity, then promote to `status: 'locked'` once the tempo grid is trustworthy - a single BeatDetector.onBeat signal carries both via BeatInfo.status. Set `emitProvisionalBeats: false` to receive only locked beats. Time-signature detection (3/4 vs 4/4) is on by default; lock to 4/4 by setting `enableTimeSignatureDetection: false`.

Constructors1
new(options?: BeatDetectorOptions): BeatDetector
Methods2
destroy(): void
subdivisionPhase(division: number): number
Phase 0..1 within a subdivision of the current beat. division is the number of subdivisions per beat: 2 for 8th notes, 4 for 16th notes, 3 for triplets. Use to drive sub-beat-resolution effects: const sixteenth = clock.subdivisionPhase(4); if (sixteenth < 0.05) flash();
Properties26
barPulseHalfLife: number
Half-life for the barPulse envelope. Mutable; default 0.3.
justBeatWindow: number
Time window for justBeat. Mutable; default 0.03 (30ms).
pulseHalfLife: number
Half-life in seconds for the pulse envelope. Mutable; default 0.15. Smaller values give a snappier pulse, larger values a longer afterglow.
analysisLatency: number
Seconds between analysisTime and the moment the main thread received that state, measured rather than assumed. Covers the analysis hop and the worklet-to-main-thread delivery together, and is quantised to the context's render-quantum boundary, so treat it as a budget figure rather than an exact age. It says nothing about the output path: what a listener hears lags the analysed audio by the output latency on top, which AudioOutputClock reports.
analysisTime: number
The AudioContext.currentTime of the newest sample the current state describes. 0 until the first state message arrives. Every timestamp this detector reports - this one, BeatInfo.audioTime, nextBeatTime, lookahead - is on the audio context's clock, so AudioOutputClock converts them to the performance.now() timeline without further correction.
bandEnergy: BandEnergy
barLength: number
barPosition: number
barPulse: number
Like pulse but resets on downbeats and decays per barPulseHalfLife. Useful for emphasizing the first beat of each bar (e.g. brighter flash on "1" vs "2,3,4").
beatPhase: number
confidence: number
gridStability: number
justBeat: boolean
True for the visual frame(s) within justBeatWindow seconds of a beat onset. Use for one-shot triggers (strobe flash, particle burst, sample retrigger). Default window 30ms covers a typical 60fps frame.
lookahead: readonly UpcomingBeat[]
nextBeatTime: number
nextDownbeatTime: number
onsetStrength: number
phaseConfidence: number
How well recent onsets support the beat grid's phase, 0 to 1, or 0 before the grid locks. Distinct from confidence, which reports how sure the detector is of the tempo. A metronomic loop at a wrong-by-an-octave tempo reads high confidence and high phase confidence; a rubato passage at a known tempo reads high confidence and low phase confidence. Gate anything that must land exactly on the beat - a scored hit, a quantised trigger - on this rather than on confidence.
pulse: number
0..1 envelope, peaks at 1.0 the moment a beat fires and halves every pulseHalfLife seconds. Drives "pulse on the beat" visuals with a single multiplication: sprite.scale = 1 + clock.pulse * 0.3.
ready: Promise<void>
rms: number
secondsSinceLastBeat: number
Seconds elapsed since the most recent beat, derived from beatPhase and tempo. Returns 0 when the detector hasn't locked yet.
source: BeatDetectorSource
tempo: number
tempoCandidates: readonly TempoCandidate[]
timeSignature: TimeSignature
Events5
onBarStart: SignalLightweight typed event emitter. Each `Signal` represents one named notification channel (e.g. `onResize`, `onFrame`). Listeners are added with Signal.add or S…<[BarInfo]>
onBeat: SignalLightweight typed event emitter. Each `Signal` represents one named notification channel (e.g. `onResize`, `onFrame`). Listeners are added with Signal.add or S…<[BeatInfo]>
onBeatPredicted: SignalLightweight typed event emitter. Each `Signal` represents one named notification channel (e.g. `onResize`, `onFrame`). Listeners are added with Signal.add or S…<[UpcomingBeat]>
onDownbeat: SignalLightweight typed event emitter. Each `Signal` represents one named notification channel (e.g. `onResize`, `onFrame`). Listeners are added with Signal.add or S…<[BeatInfo]>
onTempoChange: SignalLightweight typed event emitter. Each `Signal` represents one named notification channel (e.g. `onResize`, `onFrame`). Listeners are added with Signal.add or S…<[number, number]>
Source
packages/exojs-audio-fx/src/BeatDetector.ts