BeetRhythm - Beets Plugin for DeepRhythm Tempo Prediction

A beets plugin that uses DeepRhythm to predict tempo (BPM) for your music library with high accuracy and speed.

Features

• Automatic tempo prediction during music import
• Batch processing for efficient analysis of large collections
• High accuracy using the DeepRhythm CNN model (95.91% accuracy)
• Fast processing with GPU acceleration support
• Flexible configuration with confidence thresholds and device selection
• CLI command for manual processing of specific files or folders

Installation

1. Install the plugin:

poetry install

2. Install DeepRhythm:

pip install deeprhythm

3. Add the plugin to your beets configuration:

plugins:
  - beetrhythm

beetrhythm:
  auto: true              # Automatically predict tempo on import
  write: true             # Write tempo to file tags
  force: false            # Overwrite existing tempo values
  device: auto            # Device for prediction (auto, cpu, cuda, mps)
  batch_size: 128         # Batch size for processing
  workers: 8              # Number of workers for batch processing
  confidence_threshold: 0.0  # Minimum confidence threshold (0.0-1.0)
  disable_batch: false    # Disable batch processing (use for resource-constrained servers)
  write_confidence: false # Always calculate and store confidence scores

Usage

Automatic Mode

When auto: true is set in configuration, the plugin will automatically predict tempo for:

• Albums imported with beet import
• Individual tracks imported as singletons

Manual CLI Command

Use the beet br command to manually process files or folders:

# Process all items in library without tempo
beet br

# Process specific folder
beet br /path/to/music/folder

# Process specific files
beet br /path/to/song1.mp3 /path/to/song2.flac

# Show confidence scores
beet br -c /path/to/music

# Force overwrite existing tempo values
beet br -f /path/to/music

# Use specific device
beet br -d cuda /path/to/music

# Don't write to file tags (database only)
beet br --no-write /path/to/music

Command Options

• -f, --force: Overwrite existing tempo values
• -w, --write: Write tempo to file tags (default: true)
• --no-write: Don't write tempo to file tags
• -c, --confidence: Show confidence scores
• -d, --device: Device for prediction (auto, cpu, cuda, mps)

Configuration Options

Option	Default	Description
auto	true	Automatically predict tempo during import
write	true	Write tempo values to file tags
force	false	Overwrite existing tempo values
device	auto	Device for prediction (auto, cpu, cuda, mps)
batch_size	128	Batch size for processing
workers	8	Number of workers for batch processing
confidence_threshold	0.0	Minimum confidence threshold (0.0-1.0)
disable_batch	false	Disable batch processing (for resource-constrained servers)
write_confidence	false	Always calculate and store confidence scores

Database Fields

The plugin adds the following flexible fields to your beets database:

• bpm: The predicted tempo in beats per minute (float)
• bpm_confidence: The confidence score of the prediction (float, 0.0-1.0)

Note: Confidence scores are only calculated and stored when:

• Using the -c, --confidence CLI flag, OR
• Setting write_confidence: true in configuration

You can query these fields like any other beets field:

# Find songs with tempo between 120-140 BPM
beet list bpm:120..140

# Find songs with high confidence predictions
beet list bpm_confidence:0.9..

# Find songs without tempo predictions
beet list bpm:^$

Performance

The plugin uses batch processing when possible to greatly reduce processing time, especially when processing entire directories.

Requirements

• Python 3.8+
• beets
• deeprhythm
• PyTorch (installed automatically with deeprhythm)

Troubleshooting

DeepRhythm not found

If you get an error about DeepRhythm not being installed:

pip install deeprhythm

GPU not detected

If you have a CUDA-capable GPU but it's not being used:

• Ensure you have the CUDA version of PyTorch installed
• Set device: cuda in your configuration
• Check that your GPU drivers are up to date

Memory issues

If you encounter memory issues with large batches:

• Reduce batch_size in configuration
• Reduce workers count
• Use device: cpu instead of GPU

Hanging or multiprocessing issues

If the plugin hangs or has issues on resource-constrained servers:

• Set disable_batch: true in your configuration
• Set workers: 1 and batch_size: 1
• This will process files individually instead of using batch processing

License

This project is licensed under the same terms as the beets project.

Credits

• DeepRhythm by bleugreen
• beets music library manager