trail mix

trail mix is an audio-analysis toolkit written in Rust. It produces tempo, musical key, beat positions, and compact waveform data as JSON.

Cueport uses trail mix for local waveform and audio-analysis features, but the crates are built for any desktop, mobile, server, or research tool that needs local tempo, key, and waveform analysis.

An illustrated mix of nuts, seeds, raisins, and chocolate

Quick start

trail mix requires Rust 1.85 or newer. Run the CLI from the repository root.

cargo run -p trailmix-cli -- song.mp3

The CLI supports MP3, FLAC, AIFF, WAV, AAC-in-MP4, and ALAC-in-MP4 and prints versioned analysis results as JSON. CI tests Linux, macOS, and Windows.

trailmix_codecs::analyze_path() accepts an audio file and handles decoding, mono PCM prep, and analysis.

let analysis = trailmix_codecs::analyze_path(
    "song.mp3",
    trailmix::AnalysisConfig::default(),
)?;
let json = serde_json::to_string(&analysis)?;

When the application already has mono PCM, call the core API directly.

let analysis = trailmix::analyze(audio, trailmix::AnalysisConfig::default());

Design principles

Rust: all analysis is deterministic DSP.
Small binary: all three analyzers fit in < 3 MB.
Portable: runs on ARM, x86, and WASM.
Interpretable: intermediate features available for inspection (chroma vectors, onset envelopes, confidence scores).

Accuracy and next step

BPM, beat-grid, and waveform outputs are the most mature parts of the current implementation. Key estimation has the largest accuracy gap and is the main target for improvement.

The next step is optional model-based or platform-native analysis. The DSP core remains the default for apps that need local, dependency-light analysis.