refmatch 0.3.0

AI-powered reference track suggestions for music producers

RefMatch

AI-powered reference track suggestions for music producers.

Stop searching for reference tracks. Drop in your audio, get instant matches based on how it actually sounds — not just metadata.

Why RefMatch?

• Spotify suggests by vibe. RefMatch matches by mix characteristics. Spectral balance, loudness, dynamics, rhythm — the things that matter when you're mixing.
• CLAP neural embeddings understand how your track sounds, not just its frequency stats. Hybrid matching combines perceptual + technical similarity.
• Works offline. No API calls, no cloud. Your audio stays on your machine.
• Open source. The engine is free. Bring your own library or use the built-in seed database.

Install

# Core (DSP matching only)
pip install refmatch

# With neural embeddings (recommended)
pip install refmatch[clap]

# Optional desktop window mode
pip install refmatch[desktop]

Quick Start

# Analyze your track
refmatch analyze my_track.wav

# Find reference tracks
refmatch match my_track.wav

# Match on specific dimensions
refmatch match my_track.wav --dimension low-end
refmatch match my_track.wav --dimension loudness
refmatch match my_track.wav --dimension brightness

# Launch browser UI
refmatch app

# Launch always-on-top desktop window (requires refmatch[desktop])
refmatch app --desktop

How It Works

Two matching engines

DSP Features (43 dimensions) — always available:

• MFCCs (timbral fingerprint)
• Spectral features (centroid, bandwidth, contrast, rolloff)
• Loudness (integrated LUFS, dynamic range)
• Rhythm (tempo detection)
• Harmony (chroma features, key estimation)

CLAP Neural Embeddings (512 dimensions) — with refmatch[clap]:

• Pretrained audio model (laion/clap-htsat-fused)
• Captures perceptual similarity — tracks that sound alike even with different spectral stats
• Segment-based averaging for full-track analysis

Hybrid scoring: 60% CLAP + 40% DSP when both are available. Falls back to DSP-only gracefully.

Dimension-specific matching

Focus on what matters for your mix:

Dimension	What it matches on
low-end	Sub/bass energy, spectral contrast in low bands
loudness	LUFS, dynamic range, RMS energy
brightness	Spectral centroid, rolloff, high-frequency contrast
rhythm	Tempo, transient density
harmony	Chroma features, key similarity

Manage Your Library

# Add tracks (CLAP embeddings extracted automatically)
refmatch library add my_reference.wav
refmatch library add ~/Music/References/ --artist "Various" --genre "Hip-Hop"

# List your library
refmatch library list

# Match against your own library only
refmatch match my_track.wav --library

# Remove a track
refmatch library remove 42

Seed Database

RefMatch ships with 500 CC-licensed tracks across 25 genres from Jamendo. The seed database loads automatically on first use — no setup needed.

Supported Formats

WAV, MP3, FLAC, OGG, AIFF, M4A

For Developers

# Install with dev dependencies
pip install -e ".[dev,clap]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=refmatch --cov-report=term-missing

# Lint
ruff check src/ tests/

Roadmap

• VST3/CLAP plugin for in-DAW matching
• Natural language queries ("find something with heavy sub-bass and airy vocals")
• User feedback loop for personalized ranking
• Segment-based matching (intro/verse/chorus/drop)

License

MIT