trail mix

trail mix is an audio-analysis toolkit written in Rust. It accepts an audio file or mono PCM and returns 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

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

Accuracy and next step

trail mix uses lightweight DSP. It runs locally, remains small, and works across targets. BPM, beat, and waveform analysis are useful now. Key estimation needs the most improvement.

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