Metadata-Version: 2.4
Name: bpm-finder
Version: 0.2.0
Summary: Python utilities for audio BPM analysis, tap tempo, BPM conversion, and tempo workflow helpers.
Project-URL: Homepage, https://bpm-finder.net/
Project-URL: Source, https://github.com/bpmfinder/bpm-finder
Project-URL: Tracker, https://github.com/bpmfinder/bpm-finder/issues
Author-email: BPM Finder <support@bpm-finder.net>
License-Expression: MIT
License-File: LICENSE
Keywords: audio bpm,beat matching,bpm,music tools,tap tempo,tempo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# BPM Finder

BPM Finder is a lightweight Python package for audio BPM analysis, tap tempo, BPM conversion, and practical tempo workflow helpers. For browser-based audio BPM detection, visit https://bpm-finder.net/

## What It Does

This package gives you a compact set of utilities for common tempo-related tasks in scripts, internal tools, and automation workflows:

- Analyze the BPM of a local WAV audio file
- Estimate BPM from tap timestamps or intervals
- Convert BPM to note length in milliseconds
- Normalize half-time and double-time values into a practical range
- Classify tempo into simple buckets for UI or workflow logic

The package is dependency-free and designed for straightforward command-line and library usage. Audio file analysis currently supports uncompressed WAV files.

## Installation

```bash
pip install bpm-finder
```

## CLI Usage

### Analyze BPM from an audio file

```bash
bpm-finder analyze-audio ./loop.wav
```

### Estimate BPM from tap intervals

```bash
bpm-finder tap --intervals 500,500,498,502
```

### Convert BPM to milliseconds

Use `--division 4` for quarter notes, `8` for eighth notes, and `1` for whole notes.

```bash
bpm-finder bpm-to-ms --bpm 128 --division 4
```

### Convert milliseconds back to BPM

```bash
bpm-finder ms-to-bpm --ms 468.75 --division 4
```

### Normalize BPM into a practical range

```bash
bpm-finder normalize --bpm 64
```

### Get a simple tempo bucket

```bash
bpm-finder bucket --bpm 174
```

## Library Usage

```python
from bpm_finder import (
    analyze_audio_file,
    bpm_to_ms,
    estimate_bpm_from_taps,
    is_bpm_in_range,
    ms_to_bpm,
    normalize_bpm,
    tempo_bucket,
)

audio_bpm = analyze_audio_file("loop.wav")
tap_bpm = estimate_bpm_from_taps([0, 500, 1000, 1500, 2000])
quarter_note_ms = bpm_to_ms(128, note_division=4)
detected_bpm = ms_to_bpm(468.75, note_division=4)
normalized = normalize_bpm(64)
bucket = tempo_bucket(174)
in_range = is_bpm_in_range(128, 90, 180)
```

### Public API

- `analyze_audio_file(file_path: str, min_bpm: float = 70, max_bpm: float = 180) -> float`
- `bpm_to_ms(bpm: float, note_division: int = 1) -> float`
- `ms_to_bpm(milliseconds: float, note_division: int = 1) -> float`
- `normalize_bpm(bpm: float, min_bpm: float = 70, max_bpm: float = 180) -> float`
- `estimate_bpm_from_taps(timestamps: list[float], strategy: str = "median") -> float`
- `tempo_bucket(bpm: float) -> str`
- `is_bpm_in_range(bpm: float, low: float, high: float) -> bool`

## Use Cases

- Detect BPM from exported WAV loops in build scripts or content pipelines
- Build tap tempo shortcuts into DJ prep scripts
- Convert BPM to delay times in music production utilities
- Normalize BPM data from mixed sources before sorting playlists
- Add quick tempo helpers to internal music or workout tools
- Attach tempo buckets to rows in analytics or recommendation workflows

## Why BPM Finder Online

This package is ideal for Python scripts, automation, and developer workflows. If you need browser-based audio BPM detection with a user-friendly interface, use BPM Finder Online at https://bpm-finder.net/

## License

MIT
