Migration Guide: v5 to v6
Version 6 makes two changes, and this page keeps them apart, so an app that breaks on the upgrade can tell which one broke it:
- Renames. The 5.x events become one reading per analysis step and a state you can read at any time, and the options and fields get engine-neutral names. A missed rename fails loudly: TypeScript stops compiling, and a removed option is refused with a
TypeError. - The default engine. The
tempogramengine replacespeaksas the default. Nothing fails: the tempo comes from another engine, with its own timing.engine: 'peaks'is the one-line way back.
Do part 1 first, with engine: 'peaks' set, and check your app. Then remove that line to move to the new default.
There is no 6.0.0 to install: a failed publish in November 2025 left that number on npm, deprecated, so version 6 starts at 6.1.0.
As before, the library runs on the device, sends no audio anywhere and collects nothing.
Part 1: events, options and fields
Every 5.x name and its v6 form. The sections below show each with before-and-after code.
| 5.x | v6 |
|---|---|
option detector | engine |
tempogramMode: 'extension' | engine: { name: 'tempogram', mode: 'measured' } |
continuousAnalysis and stabilizationTime (ms) | engine: { name: 'peaks', restartAfterSeconds } (seconds) |
muteTimeInIndexes | removed |
analyzeFullBuffer and Node's analyzeChannelData options frequencyValue, qualityValue | engine: { name: 'peaks', lowpass: { frequency, q } } |
getBiquadFilter and Node's applyLowpass settings frequencyValue, qualityValue, type BiquadFilterOptions | { frequency, q } and no other key, type LowpassOption: frequency in Hz above 0 and below half the sample rate (5.x clamped it silently), q the resonance in dB as Web Audio reads a lowpass Q, from -758 to 770 dB |
event bpm | reading |
event bpmStable | statechange with to.status === 'locked' |
event analyzerReset | statechange to listening, reason audio-lost or tempo-changed. Reason pulse-lost is a lost beat, without a start-over |
| none | event kick { contextTime, strength }: each kick drum heard, new in v6 |
event progress { peaks, requiredPeaks } | progress { fraction }, also analyzer.state.progress |
event error { message, error } | error { name, message }; a fatal fault moves to stopped instead |
debug events analyzeChunk, validPeak | debug { engine, data }, with no stable shape |
once(type, listener) | on(type, listener, { once: true }) |
on() returns nothing | on() returns its unsubscribe function, and off() is new |
reset(), silent | statechange with reason reset, then progress 0 |
stop(), said to be restartable | final: statechange to stopped |
Tempo.tempo | Reading.bpm, and Candidate.bpm for the other tempos |
Tempo.count | removed |
Tempo.confidence | Reading.confidence, now the estimated chance the reading is right, or null: unmeasured, outside 90 to 180 BPM or on a custom tempoRange |
BpmCandidates.threshold, Threshold, Peaks | removed |
analyzeFullBuffer and Node's analyzeChannelData return Tempo[] | return a Reading, or null when no tempo was found |
createRealTimeBpmProcessor | removed: use createRealtimeBpmAnalyzer |
new BpmAnalyzer(node) | private: use createRealtimeBpmAnalyzer |
RealTimeBpmAnalyzer (the worklet-side analyzer, deprecated in 5.x) | removed, no replacement |
New, with no 5.x counterpart: analyzer.state, Reading.bpmExact, Reading.audio, Reading.engine and Candidate.relation. They are described at the end of part 1.
The analyzer state
v6 adds analyzer.state, a snapshot of what the analyzer is doing. Its status is one of listening, settling, locked and stopped. Each change of status dispatches a statechange event with from, to and a reason.
analyzer.on('statechange', ({ from, to, reason }) => {
console.log(`${from.status} to ${to.status} (${reason})`);
});
// A listener added late reads the current state: events are never replayed
console.log(analyzer.state.status);Options
detector is now engine
Before (5.x):
const analyzer = await createRealtimeBpmAnalyzer(audioContext, { detector: 'tempogram' });
const tempos = await analyzeFullBuffer(audioBuffer, { detector: 'tempogram' });After (v6):
const analyzer = await createRealtimeBpmAnalyzer(audioContext, { engine: 'tempogram' });
const reading = await analyzeFullBuffer(audioBuffer, { engine: 'tempogram' });The default engine changed too: see part 2.
tempogramMode moved into engine
Its value is renamed too, for what it does rather than who uses it: 'extension' is now 'measured'. It still holds the analyzer to the measured settings and refuses another tempoRange.
Before (5.x):
createRealtimeBpmAnalyzer(audioContext, { detector: 'tempogram', tempogramMode: 'extension' });After (v6):
createRealtimeBpmAnalyzer(audioContext, { engine: { name: 'tempogram', mode: 'measured' } });continuousAnalysis and stabilizationTime are now restartAfterSeconds
The time is now in seconds of audio, not milliseconds.
Before (5.x):
createRealtimeBpmAnalyzer(audioContext, { continuousAnalysis: true, stabilizationTime: 20000 });After (v6):
createRealtimeBpmAnalyzer(audioContext, { engine: { name: 'peaks', restartAfterSeconds: 20 } });Each restart outside listening is a statechange to listening with reason tempo-changed.
muteTimeInIndexes is removed
It has no replacement. Remove it.
Before (5.x):
createRealtimeBpmAnalyzer(audioContext, { muteTimeInIndexes: 10000 });After (v6):
createRealtimeBpmAnalyzer(audioContext);frequencyValue and qualityValue moved into engine
Only whole-buffer analysis takes lowpass settings. Realtime peaks already has a fixed lowpass inside analyzer.input, so connect your source there and add no filter of your own. A realtime engine with a lowpass key is refused with a TypeError that says so.
Before (5.x):
analyzeFullBuffer(audioBuffer, { frequencyValue: 200, qualityValue: 1 });After (v6):
analyzeFullBuffer(audioBuffer, { engine: { name: 'peaks', lowpass: { frequency: 200, q: 1 } } });getBiquadFilter and applyLowpass take the same settings
They take the { frequency, q } of engine.lowpass, and their type is LowpassOption. BiquadFilterOptions is gone: the DOM declares a global type by that name with other fields, which TypeScript would accept in its place.
The settings accept frequency and q and no other key. Any other key throws a TypeError that names it, whatever its value, so a DOM BiquadFilterOptions with Q, detune, type or gain fails at once, and so does a typo, instead of being dropped. Fold a detune into the frequency: frequency × 2^(detune/1200).
q means what it meant in 5.x's qualityValue: the resonance at the cutoff in dB, as Web Audio reads a lowpass Q, not the Audio EQ Cookbook's linear Q. The biquad's α is sin(ω0) / (2 × 10^(q/20)), so 0 dB is a linear Q of 1.
v6 also checks the values, on every path, where 5.x clamped or ignored them without a word:
- Settings that aren't an object.
150,'150'or an array used to give the defaults. They now throw aTypeErrorthat names their type: "The lowpass settings are an object with frequency and q, not a number."nullandundefinedstill mean the defaults. - A setting that isn't a number.
{ frequency: '150' }throws aTypeError, andNaNor an infinity aRangeError. So doesnullfor a single setting, such as{ q: null }, which 5.x read as the default: leave the key out instead. (nullfor the whole settings still means the defaults.) - A cutoff outside the range. 5.x clamped
frequencyto [0, Nyquist] as Web Audio does, so 0 or below gave silence, and half the sample rate or above returned the audio unfiltered. Afrequencythat isn't above 0 and below half the sample rate now throws aRangeErrorthat names the value, the rate and the range: "The lowpass setting frequency 22050 is out of range: at a sample rate of 44100 Hz, it must be above 0 and below 22050 Hz." The default 200 Hz is valid at any rate above 400 Hz. - A
qoutside -758 to 770 dB. That is the range where Web Audio's resonance term 10^(q/20) is a normal, finite 32-bit float: below it Chrome's filter outputs NaN from the first sample, and above it the term overflows. 5.x passed any value on to Web Audio. Aqoutside the range now throws aRangeError: "The lowpass setting q -800 is out of range: it must be from -758 to 770 dB."
Before (5.x):
import { getBiquadFilter, type BiquadFilterOptions } from 'realtime-bpm-analyzer';
const settings: BiquadFilterOptions = { frequencyValue: 150, qualityValue: 1 };
const filter = getBiquadFilter(audioContext, settings);After (v6):
import { getBiquadFilter, type LowpassOption } from 'realtime-bpm-analyzer';
const settings: LowpassOption = { frequency: 150, q: 1 };
const filter = getBiquadFilter(audioContext, settings);A removed option is refused
v6 refuses every option above by its 5.x name with a TypeError that names the replacement, so a missed rename fails at once instead of being ignored. createRealtimeBpmAnalyzer, analyzeFullBuffer and analyzeChannelData are async, so their promise rejects with it; getBiquadFilter and applyLowpass throw it. The lowpass settings do the same, wherever they are passed, and refuse any key other than frequency and q.
The engine object is just as strict. It takes name and the settings of the engine it names, and nothing else:
| Where | name | Its settings |
|---|---|---|
createRealtimeBpmAnalyzer | 'peaks' | restartAfterSeconds |
createRealtimeBpmAnalyzer | 'tempogram' | mode |
analyzeFullBuffer, analyzeChannelData | 'peaks' | lowpass |
Any other key is refused with a TypeError that names it, whatever its value, undefined included: a realtime lowpass, a restartAfterSeconds on the tempogram or in whole-buffer analysis, or a typo such as restartAfterSecond. 5.x had no engine object, so no 5.x call meets this rule: it catches a setting given to an engine or a path that would ignore it, and typos.
The options themselves are strict too. createRealtimeBpmAnalyzer takes engine, tempoRange, processorUrl, liveInput and debug; analyzeFullBuffer and analyzeChannelData take engine and tempoRange; tempoRange takes min and max. Any other key is refused with a TypeError that names it, whatever its value, after the 5.x names above, whose own messages still win. 5.x ignored an unknown key, so a call that passes one, such as a typo or an option the function never read, now rejects. Options that are not an object, null or undefined are refused the same way, naming their type.
Events
bpm is now reading
A reading carries one tempo, bpm, a whole number, and the ranked candidates.
Before (5.x):
analyzer.on('bpm', (data) => {
console.log(data.bpm[0].tempo);
});After (v6):
analyzer.on('reading', (reading) => {
console.log(reading.bpm);
});bpmStable is now statechange to locked
Before (5.x):
analyzer.on('bpmStable', (data) => {
console.log('Stable:', data.bpm[0].tempo);
});After (v6):
analyzer.on('statechange', ({ to }) => {
if (to.status === 'locked') {
console.log('Locked:', to.reading.bpm);
}
});While locked, the tempo can still move without a statechange, so keep showing the latest reading.
analyzerReset is now statechange to listening
The reason says why the analyzer started over: audio-lost or tempo-changed. A statechange to listening with reason pulse-lost means the beat was lost, and the analyzer keeps what it heard.
Before (5.x):
analyzer.on('analyzerReset', () => {
showWaiting();
});After (v6):
analyzer.on('statechange', ({ to }) => {
if (to.status === 'listening') {
showWaiting(to.reason);
}
});progress carries a fraction
Before (5.x):
analyzer.on('progress', ({ peaks, requiredPeaks }) => {
bar.value = peaks / requiredPeaks;
});After (v6):
analyzer.on('progress', ({ fraction }) => {
bar.value = fraction;
});While listening, analyzer.state.progress holds the same value.
error carries a name
The payload is plain data, with no Error object inside. A fatal fault also moves the analyzer to stopped, with the error in state.error.
Before (5.x):
analyzer.on('error', ({ message, error }) => {
console.error(message, error);
});After (v6):
analyzer.on('error', ({ name, message }) => {
console.error(name, message);
});analyzeChunk and validPeak are now debug
With debug: true, every engine sends debug events. Their data has no stable shape.
Before (5.x):
analyzer.on('analyzeChunk', (data) => console.log(data));
analyzer.on('validPeak', (data) => console.log(data));After (v6):
analyzer.on('debug', ({ engine, data }) => console.log(engine, data));Listeners
once() is now an option of on()
Before (5.x):
analyzer.once('bpmStable', handler);After (v6):
analyzer.on('statechange', handler, { once: true });on() returns its unsubscribe function, and off() is new
Before (5.x):
analyzer.on('bpm', handler);
analyzer.removeEventListener('bpm', handler);That 5.x sample never removed anything: on() registered a wrapper around handler, so removeEventListener with handler found no match. In v6 both ways below remove the listener.
After (v6):
const unsubscribe = analyzer.on('reading', handler);
unsubscribe();
// or
analyzer.on('reading', handler);
analyzer.off('reading', handler);on() also takes a signal, which removes the listener when it aborts.
reset() and stop()
reset() now reports itself: a statechange with reason reset, then progress with fraction 0. Once reset() returns, nothing measured before it is ever reported.
stop() is final. It moves the analyzer to stopped, and the analyzer cannot start again. Create a new one instead.
Before (5.x):
analyzer.stop();
// later
analyzer.reset();After (v6):
analyzer.stop();
// later
analyzer = await createRealtimeBpmAnalyzer(audioContext);Whole-buffer results
analyzeFullBuffer and the Node analyzeChannelData return one reading, or null when they find no tempo.
Before (5.x):
const tempos = await analyzeFullBuffer(audioBuffer);
if (tempos.length > 0) {
console.log(tempos[0].tempo, tempos[0].count);
}After (v6):
const reading = await analyzeFullBuffer(audioBuffer);
if (reading !== null) {
console.log(reading.bpm, reading.candidates);
}Tempo.count is removed. BpmCandidates, its threshold, Threshold and Peaks are removed too.
Removed exports
RealTimeBpmAnalyzer and createRealTimeBpmProcessor are removed. Use createRealtimeBpmAnalyzer.
Before (5.x):
import { createRealTimeBpmProcessor } from 'realtime-bpm-analyzer';
const analyzer = await createRealTimeBpmProcessor(audioContext);After (v6):
import { createRealtimeBpmAnalyzer } from 'realtime-bpm-analyzer';
const analyzer = await createRealtimeBpmAnalyzer(audioContext);Removed types
TypeScript code that imports one of these no longer compiles. Each 5.x type and what to use in v6:
| 5.x type | v6 |
|---|---|
Tempo | Candidate for one tempo of a reading, Reading for the reading itself |
BpmCandidates | Reading: its candidates are a Candidate[] |
BpmProgress | Progress |
BpmAnalyzerEventMap | AnalyzerEventMap |
CreateRealtimeBpmAnalyzerOptions | AnalyzerOptions |
RealTimeBpmAnalyzerParameters | AnalyzerOptions |
AnalyzeFullBufferOptions | OfflineOptions |
Detector | EngineName |
TempogramMode | EngineOption: { name: 'tempogram', mode: 'measured' } |
BiquadFilterOptions | LowpassOption: { frequency, q } |
Threshold | None: the peaks engine's threshold is internal. debug: true shows it in DebugInfo |
Peaks | None: internal to the peaks engine. debug: true shows the peaks in DebugInfo |
ProcessorInputEvent | None: the worklet's messages are internal |
ProcessorOutputEvent | None: read AnalyzerEventMap instead |
New in a reading
candidates: each has abpmand arelationto the reading's tempo:top,half,doubleorother.bpmExact: the tempo before rounding, for spacing markers over a long stretch once you know where one beat falls. Showbpm.audio: the stretch the reading was measured on,fromandtoin seconds since the analyzer started or was reset. Realtime,contextTimeis theAudioContext.currentTimeat which the sample attoreached the analyzer. Whole-buffer readings havecontextTime: null.engine: the engine that measured it.
A reading has a tempo, not a beat phase: nothing in it says where a beat falls, so don't start a beat grid at contextTime. Beat positions are planned for a later 6.x minor. What contextTime gives you is the mapping of analysed audio onto the clock AudioContext schedules on: a moment t of the stretch played at contextTime - (audio.to - t).
analyzer.on('reading', ({ bpm, audio }) => {
if (audio.contextTime !== null) {
// When the measured stretch played, on the AudioContext clock
const startedAt = audio.contextTime - (audio.to - audio.from);
highlightMeasured(startedAt, audio.contextTime, bpm);
}
});Unions may grow
A minor release of 6.x can add a value to an exported union: an engine name, a candidate relation, a reason, an error name or an event. Give every switch over one a default branch, so a new value does not break it. status is the one closed union.
analyzer.on('statechange', ({ reason }) => {
switch (reason) {
case 'locked':
showLocked();
break;
case 'pulse-lost':
showWaiting();
break;
default:
break;
}
});Processor file
If you serve the processor file yourself through processorUrl, copy the v6 file again. A 5.x file does not speak to a v6 analyzer, and createRealtimeBpmAnalyzer rejects when it sends no ready in time. Within 6.x, a copy one minor behind still works, and a feature it lacks throws an error saying the processor copy is out of date. Copy the file again on every upgrade to get every feature.
Part 2: the default engine
v6 makes the tempogram engine the default, in realtime and for whole files. It reads the tempo from an onset tempogram, spectral flux across several bands, where peaks reads amplitude peaks in low-passed audio. Both report the same reading, so no code has to change, but what your app sees does:
- Wiring.
analyzer.inputholds no filter for the tempogram, which needs the full band. Connect your source toanalyzer.inputas before. If you putgetBiquadFilter()or a low-pass of your own in front of the analyzer forpeaks, remove it. - Timing. The first reading comes after a 4-second warm-up, and the earliest lock after about 11.5 seconds of audio, where
peaksgives its first reading once it has 16 peaks (about 8 seconds on a steady kick) and locks from 10 seconds. Readings come twice a second instead of about ten times. - Tempo range. The tempogram searches
tempoRangeinstead of folding every tempo into it. From about twiceminup, a tempo can read at half: with the default 90 to 180, a track over about 179 BPM reads half. A wider range does not fix that. See the tempogram engine. - Restarts.
restartAfterSecondsis apeakssetting. The tempogram's memory of past tempos fades with a 16-second half-life, so it follows a tempo change on its own. - Confidence. It is now the estimated chance the reading is right, calibrated on licence-clean dev data from 90 to 180 BPM, and inside that range it means the same under either engine.
null: unmeasured, for a reading outside 90 to 180 BPM and for every reading of an analysis on a customtempoRange, since the calibration ran only on the default range. Type itnumber | null, and drop a customtempoRangeof 90 to 180 or leave it:{ min: 90, max: 180 }is the default and keeps the number. A cut-off you chose for a 5.x score does not carry over. - Locks. On some tracks the tempogram never locks where
peaksdid. Keep showing the latestreadingwhile the analyzer issettling.
The way back: engine: 'peaks'
One line keeps the 5.x engine:
const analyzer = await createRealtimeBpmAnalyzer(audioContext, { engine: 'peaks' });
const reading = await analyzeFullBuffer(audioBuffer, { engine: 'peaks' });The command-line tool takes --engine peaks, and the MCP server's tools take engine: "peaks".
Setting engine also keeps your engine whatever a later default becomes, so name it if your app depends on one engine's timing or range.