README

bpmfinder/bpm-finder is a lightweight PHP library for tap tempo analysis, PCM WAV audio-file BPM estimation, BPM conversion, and practical tempo-range helpers. It is maintained by BPM Finder, the online tool for fast and accurate BPM detection.

Why this package exists

If you are building music tooling, DJ utilities, playlist workflows, or internal tempo features, you often need a few reliable primitives:

• Calculate BPM from user taps
• Estimate BPM from uncompressed WAV audio files
• Convert BPM to milliseconds per beat or bar
• Normalize half-time and double-time readings into a practical range

This package keeps those utilities small, dependency-free, and framework-agnostic.

Installation

composer require bpmfinder/bpm-finder

Usage

Tap tempo from timestamps

<?php

require 'vendor/autoload.php';

use BpmFinder\TempoTools\TapTempoCalculator;

$analysis = TapTempoCalculator::analyzeTimestamps([
    0,
    500,
    1000,
    1500,
    2000,
]);

echo $analysis['bpm']; // 120.0

Tap tempo from intervals

<?php

use BpmFinder\TempoTools\TapTempoCalculator;

$analysis = TapTempoCalculator::analyzeIntervals([500, 502, 498, 500]);

echo $analysis['average_interval_ms']; // 500
echo $analysis['bpm']; // 120.0

BPM and milliseconds conversion

<?php

use BpmFinder\TempoTools\TempoConverter;

$beatMs = TempoConverter::bpmToMillisecondsPerBeat(128);
$barMs = TempoConverter::bpmToMillisecondsPerBar(128, 4);
$bpm = TempoConverter::millisecondsPerBarToBpm(1875, 4);

Analyze a WAV audio file

<?php

use BpmFinder\TempoTools\AudioFileBpmAnalyzer;

$analysis = AudioFileBpmAnalyzer::analyzeFile(__DIR__ . '/loop.wav');

echo $analysis['bpm'];
echo $analysis['confidence'];

analyzeFile() supports uncompressed PCM WAV files in v1.

Normalize into a practical range

<?php

use BpmFinder\TempoTools\TempoRange;

$normalized = TempoRange::normalize(72, 90, 180);   // 144
$doubleTime = TempoRange::doubleTime(87.5);         // 175
$halfTime = TempoRange::halfTime(174);              // 87
$inRange = TempoRange::isWithin(128, 90, 180);      // true

Public API

TapTempoCalculator

• analyzeTimestamps(array $timestampsMs, int $precision = 2): array
• analyzeIntervals(array $intervalsMs, int $precision = 2): array
• bpmFromTimestamps(array $timestampsMs, int $precision = 2): float
• bpmFromIntervals(array $intervalsMs, int $precision = 2): float

AudioFileBpmAnalyzer

• analyzeFile(string $filePath, float $minTempo = 70.0, float $maxTempo = 180.0, int $precision = 2): array
• analyzeSamples(array $samples, int $sampleRate, float $minTempo = 70.0, float $maxTempo = 180.0, int $precision = 2): array

TempoConverter

• bpmToMillisecondsPerBeat(float $bpm, int $precision = 2): float
• bpmToMillisecondsPerBar(float $bpm, int $beatsPerBar = 4, int $precision = 2): float
• millisecondsPerBeatToBpm(float $milliseconds, int $precision = 2): float
• millisecondsPerBarToBpm(float $milliseconds, int $beatsPerBar = 4, int $precision = 2): float

TempoRange

• normalize(float $bpm, float $min = 70.0, float $max = 180.0, int $precision = 2): float
• isWithin(float $bpm, float $min = 70.0, float $max = 180.0): bool
• halfTime(float $bpm, int $precision = 2): float
• doubleTime(float $bpm, int $precision = 2): float

Development

composer install
composer test

Release notes

Current version: 0.1.0

• First public release
• Added PCM WAV audio-file BPM analysis
• Zero runtime dependencies
• Tested with PHPUnit

See CHANGELOG.md for release history.

License

MIT