Skip to content

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:

  1. 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.
  2. The default engine. The tempogram engine replaces peaks as 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.xv6
option detectorengine
tempogramMode: 'extension'engine: { name: 'tempogram', mode: 'measured' }
continuousAnalysis and stabilizationTime (ms)engine: { name: 'peaks', restartAfterSeconds } (seconds)
muteTimeInIndexesremoved
analyzeFullBuffer and Node's analyzeChannelData options frequencyValue, qualityValueengine: { 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 bpmreading
event bpmStablestatechange with to.status === 'locked'
event analyzerResetstatechange to listening, reason audio-lost or tempo-changed. Reason pulse-lost is a lost beat, without a start-over
noneevent 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, validPeakdebug { engine, data }, with no stable shape
once(type, listener)on(type, listener, { once: true })
on() returns nothingon() returns its unsubscribe function, and off() is new
reset(), silentstatechange with reason reset, then progress 0
stop(), said to be restartablefinal: statechange to stopped
Tempo.tempoReading.bpm, and Candidate.bpm for the other tempos
Tempo.countremoved
Tempo.confidenceReading.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, Peaksremoved
analyzeFullBuffer and Node's analyzeChannelData return Tempo[]return a Reading, or null when no tempo was found
createRealTimeBpmProcessorremoved: 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.

typescript
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):

typescript
const analyzer = await createRealtimeBpmAnalyzer(audioContext, { detector: 'tempogram' });
const tempos = await analyzeFullBuffer(audioBuffer, { detector: 'tempogram' });

After (v6):

typescript
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):

typescript
createRealtimeBpmAnalyzer(audioContext, { detector: 'tempogram', tempogramMode: 'extension' });

After (v6):

typescript
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):

typescript
createRealtimeBpmAnalyzer(audioContext, { continuousAnalysis: true, stabilizationTime: 20000 });

After (v6):

typescript
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):

typescript
createRealtimeBpmAnalyzer(audioContext, { muteTimeInIndexes: 10000 });

After (v6):

typescript
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):

typescript
analyzeFullBuffer(audioBuffer, { frequencyValue: 200, qualityValue: 1 });

After (v6):

typescript
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 a TypeError that names their type: "The lowpass settings are an object with frequency and q, not a number." null and undefined still mean the defaults.
  • A setting that isn't a number. { frequency: '150' } throws a TypeError, and NaN or an infinity a RangeError. So does null for a single setting, such as { q: null }, which 5.x read as the default: leave the key out instead. (null for the whole settings still means the defaults.)
  • A cutoff outside the range. 5.x clamped frequency to [0, Nyquist] as Web Audio does, so 0 or below gave silence, and half the sample rate or above returned the audio unfiltered. A frequency that isn't above 0 and below half the sample rate now throws a RangeError that 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 q outside -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. A q outside the range now throws a RangeError: "The lowpass setting q -800 is out of range: it must be from -758 to 770 dB."

Before (5.x):

typescript
import { getBiquadFilter, type BiquadFilterOptions } from 'realtime-bpm-analyzer';

const settings: BiquadFilterOptions = { frequencyValue: 150, qualityValue: 1 };
const filter = getBiquadFilter(audioContext, settings);

After (v6):

typescript
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:

WherenameIts 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):

typescript
analyzer.on('bpm', (data) => {
  console.log(data.bpm[0].tempo);
});

After (v6):

typescript
analyzer.on('reading', (reading) => {
  console.log(reading.bpm);
});

bpmStable is now statechange to locked ​

Before (5.x):

typescript
analyzer.on('bpmStable', (data) => {
  console.log('Stable:', data.bpm[0].tempo);
});

After (v6):

typescript
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):

typescript
analyzer.on('analyzerReset', () => {
  showWaiting();
});

After (v6):

typescript
analyzer.on('statechange', ({ to }) => {
  if (to.status === 'listening') {
    showWaiting(to.reason);
  }
});

progress carries a fraction ​

Before (5.x):

typescript
analyzer.on('progress', ({ peaks, requiredPeaks }) => {
  bar.value = peaks / requiredPeaks;
});

After (v6):

typescript
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):

typescript
analyzer.on('error', ({ message, error }) => {
  console.error(message, error);
});

After (v6):

typescript
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):

typescript
analyzer.on('analyzeChunk', (data) => console.log(data));
analyzer.on('validPeak', (data) => console.log(data));

After (v6):

typescript
analyzer.on('debug', ({ engine, data }) => console.log(engine, data));

Listeners ​

once() is now an option of on() ​

Before (5.x):

typescript
analyzer.once('bpmStable', handler);

After (v6):

typescript
analyzer.on('statechange', handler, { once: true });

on() returns its unsubscribe function, and off() is new ​

Before (5.x):

typescript
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):

typescript
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):

typescript
analyzer.stop();
// later
analyzer.reset();

After (v6):

typescript
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):

typescript
const tempos = await analyzeFullBuffer(audioBuffer);
if (tempos.length > 0) {
  console.log(tempos[0].tempo, tempos[0].count);
}

After (v6):

typescript
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):

typescript
import { createRealTimeBpmProcessor } from 'realtime-bpm-analyzer';
const analyzer = await createRealTimeBpmProcessor(audioContext);

After (v6):

typescript
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 typev6
TempoCandidate for one tempo of a reading, Reading for the reading itself
BpmCandidatesReading: its candidates are a Candidate[]
BpmProgressProgress
BpmAnalyzerEventMapAnalyzerEventMap
CreateRealtimeBpmAnalyzerOptionsAnalyzerOptions
RealTimeBpmAnalyzerParametersAnalyzerOptions
AnalyzeFullBufferOptionsOfflineOptions
DetectorEngineName
TempogramModeEngineOption: { name: 'tempogram', mode: 'measured' }
BiquadFilterOptionsLowpassOption: { frequency, q }
ThresholdNone: the peaks engine's threshold is internal. debug: true shows it in DebugInfo
PeaksNone: internal to the peaks engine. debug: true shows the peaks in DebugInfo
ProcessorInputEventNone: the worklet's messages are internal
ProcessorOutputEventNone: read AnalyzerEventMap instead

New in a reading ​

  • candidates: each has a bpm and a relation to the reading's tempo: top, half, double or other.
  • bpmExact: the tempo before rounding, for spacing markers over a long stretch once you know where one beat falls. Show bpm.
  • audio: the stretch the reading was measured on, from and to in seconds since the analyzer started or was reset. Realtime, contextTime is the AudioContext.currentTime at which the sample at to reached the analyzer. Whole-buffer readings have contextTime: 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).

typescript
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.

typescript
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.input holds no filter for the tempogram, which needs the full band. Connect your source to analyzer.input as before. If you put getBiquadFilter() or a low-pass of your own in front of the analyzer for peaks, 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 peaks gives 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 tempoRange instead of folding every tempo into it. From about twice min up, 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. restartAfterSeconds is a peaks setting. 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 custom tempoRange, since the calibration ran only on the default range. Type it number | null, and drop a custom tempoRange of 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 peaks did. Keep showing the latest reading while the analyzer is settling.

The way back: engine: 'peaks' ​

One line keeps the 5.x engine:

typescript
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.