Realtime BPM Analyzer

A powerful TypeScript library for detecting beats-per-minute (BPM) in real-time.

📚 Documentation • 🎯 Examples • 🚀 Getting Started

Features

• Zero dependencies - Uses native Web Audio API
• Real-time analysis - Analyze audio/video as it plays
• Multiple sources - Works with files, streams, microphone, or any audio/video node
• Typed events - Full TypeScript support with autocomplete
• Client-side only - 100% privacy-focused, no data collection
• Supports MP3, FLAC, WAV formats

Installation

npm install realtime-bpm-analyzer

Quick Example

import { createRealtimeBpmAnalyzer } from 'realtime-bpm-analyzer';
// Create analyzer
const analyzer = await createRealtimeBpmAnalyzer(audioContext);
// Connect your audio source
audioSource.connect(analyzer.node);
// Listen for BPM detection
analyzer.on('bpm', (data) => {
  console.log('BPM detected:', data.bpm[0].tempo);
});

Strict CSP and browser extensions

The worklet loads from a blob: URL by default. Pages whose Content Security Policy blocks blob: scripts, and Manifest V3 extensions, serve the published processor file (realtime-bpm-analyzer/processor, i.e. dist/realtime-bpm-processor.js) from their own origin and pass its URL:

const analyzer = await createRealtimeBpmAnalyzer(audioContext, {
  processorUrl: chrome.runtime.getURL('realtime-bpm-processor.js'), // or '/realtime-bpm-processor.js'
});

See the strict CSP guide for Vite and extension setups.

Node.js

realtime-bpm-analyzer/node analyses decoded PCM samples without Web Audio, in Node.js, Bun or Deno, with no added dependency. It returns the same candidates as analyzeFullBuffer for the same samples. Decoding is up to you (a WAV reader, ffmpeg, ...):

import {analyzeChannelData} from 'realtime-bpm-analyzer/node';
const tempos = await analyzeChannelData(channelData, 44100); // Float32Array of one channel
console.log(tempos[0]?.tempo);

See the Node.js guide.

Command line

A separate package, realtime-bpm-analyzer-cli, detects the BPM of audio files from a terminal, so this library stays dependency-free:

npx realtime-bpm-analyzer-cli song.mp3        # 128 BPM (confidence 0.46) and the top candidates
npx realtime-bpm-analyzer-cli --json ./music  # every audio file of a folder, as JSON

See the command-line guide.

AI assistants (MCP)

realtime-bpm-analyzer-mcp is a local MCP server, so Claude Desktop, Claude Code or any MCP client can detect the BPM of files on your disk. It runs on your machine over stdio: the audio never leaves it.

claude mcp add bpm -- npx -y realtime-bpm-analyzer-mcp   # Claude Code

See the MCP guide for Claude Desktop and the two tools, analyze_file and analyze_folder.

Documentation

📖 Full Documentation - Complete guides, API reference, and tutorials

Key sections:

• Quick Start Guide - Get up and running
• API Reference - Complete API documentation
• Examples - Live demos and code samples
• Migration to v5 - Upgrading from v4.x

Use Cases

• Audio Players - Display BPM while playing tracks
• Live Streams - Continuous BPM detection from radio/streaming
• File Analysis - Offline BPM detection from uploaded files
• Microphone Input - Real-time analysis from live audio
• DJ Applications - Beat matching and tempo detection

Running Examples Locally

# Install dependencies
npm install
Run a specific example
npm run dev --workspace=examples/01-vanilla-basic
Available examples:
- 01-vanilla-basic, 02-vanilla-streaming, 03-vanilla-microphone
- 04-react-basic, 05-react-streaming, 06-react-microphone  
- 07-vue-basic, 08-vue-streaming, 09-vue-microphone

Privacy & Security

• 100% client-side processing
• No data collection or transmission
• No audio recording - real-time analysis only
• Open source - fully auditable code

Contributing

Contributions are welcome! See contributing.md for guidelines.

License

Apache-2.0 License - See licence.md for details.

For commercial licensing inquiries, contact: [email protected]

Sponsors

If your product depends on this library, consider sponsoring its maintenance via GitHub Sponsors.

Credits

Inspired by Tornqvist's bpm-detective and Joe Sullivan's algorithm.