Realtime BPM Analyzer

Welcome to Realtime BPM Analyzer, a powerful and easy-to-use TypeScript/JavaScript library for detecting the beats-per-minute (BPM) of an audio or video source in real-time.

• Getting started
  • NextJS
  • Esbuild
• Features
• Usages
  • Player strategy
  • Continuous Analysis strategy
  • Local/Offline strategy
• Roadmap
• Development
• Tests & Coverage
• Credits

Getting started

To install this module to your project, just launch the command below:

npm install realtime-bpm-analyzer

To learn more about how to use the library, you can check out the documentation.

Features

• Dependency-free library that utilizes the Web Audio API to analyze audio or video sources and provide accurate BPM detection.
• Can be used to analyze audio or video nodes, streams as well as files.
• Allows you to compute the BPM while the audio or video is playing.
• Lightweight and easy to use, making it a great option for web-based music production and DJing applications.

Usages

If you encounter issues along the way, remember we have a discord server and a chat !

Player strategy

Mesure or detect the BPM from a web player.

This example shows how to deal with a simple audio node.

1. An AudioNode to analyze. So something like this:

<audio src="./new_order-blue_monday.mp3" id="track"></audio>

2. Create the AudioWorkletProcessor with createRealTimeBpmProcessor, create and pipe the filters to the AudioWorkletNode (realtimeAnalyzerNode).

import { createRealTimeBpmProcessor } from 'realtime-bpm-analyzer';

const realtimeAnalyzerNode = await createRealTimeBpmProcessor(audioContext);

// Set the source with the HTML Audio Node
const track = document.getElementById('track');
const source = audioContext.createMediaElementSource(track);

// Connect nodes together
source.connect(realtimeAnalyzerNode);
source.connect(audioContext.destination);

realtimeAnalyzerNode.port.onmessage = (event) => {
  if (event.data.message === 'BPM') {
    console.log('BPM', event.data.result);
  }
  if (event.data.message === 'BPM_STABLE') {
    console.log('BPM_STABLE', event.data.result);
  }
};

Continuous Analysis strategy

Analyze the BPM of a source continuously. This feature is quite simple and basically get rid of all data inside the analyzer after the stabilizationTime is reached. Why ? Because we store all the "valid peaks" for each thresholds in order to find the best candidates. And we would keep all those data forever, we would have memory leaks.

Note: This approach is NOT recommended if you are using a microphone as source. Except if the microphone gets correct audio source. Typically, if the BPM is never computed using this approach, you probably capture low intensity audio with your microphone (too far from the source, too much noise, directional microphone could be reasons why it's not working).

1. Streams can be played with AudioNode, so the approch is quite similar to the Player strategy.

<audio src="https://ssl1.viastreaming.net:7005/;listen.mp3" id="track"></audio>

Thank you IbizaSonica for the stream.

2. As for the Player strategy, except that we need to turn on the continuousAnalysis flag to periodically delete collected data.

import { createRealTimeBpmProcessor } from 'realtime-bpm-analyzer';

const realtimeAnalyzerNode = await createRealTimeBpmProcessor(audioContext);

// Set the source with the HTML Audio Node
const track = document.getElementById('track');
const source = audioContext.createMediaElementSource(track);

// Connect nodes together
source.connect(realtimeAnalyzerNode);
source.connect(audioContext.destination);

// Enable the continuous feature
realtimeAnalyzerNode.port.postMessage({
  message: 'ASYNC_CONFIGURATION',
  parameters: {
    continuousAnalysis: true,
    stabilizationTime: 20_000, // Default value is 20_000ms after what the library will automatically delete all collected data and restart analysing BPM
  }
})

realtimeAnalyzerNode.port.onmessage = (event) => {
  if (event.data.message === 'BPM') {
    console.log('BPM', event.data.result);
  }
  if (event.data.message === 'BPM_STABLE') {
    console.log('BPM_STABLE', event.data.result);
  }
};

Local/Offline strategy

Analyze the BPM from files located in your desktop, tablet or mobile !

1. Import the library

import * as realtimeBpm from 'realtime-bpm-analyzer';

2. Use an input[type=file] to get the files you want.

<input type="file" accept="wav,mp3" onChange={event => this.onFileChange(event)}/>

3. You can listen the change event like so, and analyze the BPM of the selected files. You don't need to be connected to Internet for this to work.

function onFileChange(event) {
  const audioContext = new AudioContext();
  // Get the first file from the list
  const file = event.target.files[0];
  const reader = new FileReader();
  reader.addEventListener('load', () => {
    // The file is uploaded, now we decode it
    audioContext.decodeAudioData(reader.result, audioBuffer => {
      // The result is passed to the analyzer
      realtimeBpm.analyzeFullBuffer(audioBuffer).then(topCandidates => {
        // Do something with the BPM
        console.log('topCandidates', topCandidates);
      });
    });
  });
  reader.readAsArrayBuffer(file);
};

Roadmap

• Add confidence level of Tempo
• Combine Amplitude Thresholding strategy with others to improve BPM accuracy
• Improve the continous analysis in order to ignore drops and cuts
• Monitore memory usage

Let us know what is your most wanted feature by opening an issue.

Development

The test suite is built on top of karma and is very practical to test new features. Before running tests switch the singleRun property of karma.config.js to leave the browser open after the tests.

npm install
npm run prepare
npm test

Tests & Coverage

To launch the test suite, just launch the command below:

open http://localhost:9876
npm test

Note that tests requires real human gesture to be successfully run!

Credits

This library was inspired by the Tornqvist project, which was also based on Joe Sullivan's algorithm. Thank you to both of them.