drone-v2: musical key detection on a CPU

drone-v2 tells you the musical key of a song: one of 24 keys, the 12 tonics (C, C#, D ... B) each in major or minor. It is a 109,128-parameter convolutional network that reads a constant-Q spectrogram of the whole track and runs in about 60 ms on one CPU core for a two-minute track. It was built for DJ software (Euphoria) and works anywhere you can run PyTorch, ONNX Runtime, or a few hundred lines of native code.

Output One of 24 keys, with a softmax score for each
Size 109,128 parameters; 0.44 MB of float32 weights
Speed About 0.3 s per two-minute track on one core of an Apple M5, of which 57 ms is the network
Source github.com/lvndry/drone (MIT)
Previous version drone-v1, still in this repository

How accurate is it?

All detectors below were run on the same 604 GiantSteps previews (two-minute excerpts of electronic dance music) and scored against the same labels. Exact means the predicted key equals the reference key.

Detector Original GiantSteps labels (604) Expert labels (571) Expert labels, single-key tracks (457)
libkeyfinder 2.2.8 60.4% 69.9% 76.2%
madmom KEY_CNN 67.9% 77.4% 83.4%
drone-v1 68.5% 77.4% 83.4%
drone-v2 69.9% 80.7% 88.0%

Why three columns? The original GiantSteps labels agree with the GiantSteps+ expert re-annotation on only 82% of tracks, so part of every detector's "error" on the original labels is label error. The single-key column keeps only tracks the experts marked with one key throughout, the cleanest reference available.

On the expert single-key tracks, drone-v2 is ahead of libkeyfinder by 11.8 points (paired 95% interval 8.1 to 15.5) and of drone-v1 by 4.6 points (2.0 to 7.4). On the half of those tracks never used for any development decision, the gaps are 12.4 and 6.2 points.

Outside dance music, on 500 tracks of mixed genres from the Free Music Archive (FMAKv2), drone-v2 scores 75.0% exact against drone-v1's 65.4%: 72.4% and 77.6% on the two 250-track panels, a gain of 9 to 10 points on each.

For DJs: exact or a fifth away

A key a fifth away (a neighbouring number on the Camelot wheel, same letter) still mixes; the relative key, the parallel key or anything else does not. Counted that way, drone-v2 gives a usable key on 90.6% of the expert single-key tracks, against 85.6% for libkeyfinder (+5.0 points, 95% interval 2.0 to 8.3), and on 75.8% against 71.9% with the original GiantSteps labels. The gap is smaller than on exact keys because many of libkeyfinder's misses were already a fifth away.

On 309 afro house tracks from a DJ library, drone-v2 (through Euphoria) and rekordbox 7 named the same key for 89.3% of tracks and keys within a fifth for 95.5%; where Euphoria rated its key high confidence (two tracks in three), 99.0% were within a fifth of rekordbox's. That is agreement between two detectors, not accuracy against a reference.

What these numbers do not say

  • Not compared with Mixed In Key. Published Mixed In Key results (85 to 89% exact) come from other tracks, labels and scoring, so they are not comparable with this table.
  • GiantSteps is not a blind test for this model family. It was used while developing Drone, though never to train it. The 604 previews share no track with the training set.
  • On the original GiantSteps labels, a larger published model (KeyMyna, 22M parameters) reports 72.0% exact, above drone-v2's 69.9%.
  • Previews, not full mixes. GiantSteps tracks are two-minute excerpts and most training audio is 30-second clips or previews. Full-length tracks work (the network averages over time), but accuracy on 6 to 10 minute club tracks has not been measured separately.
  • One key per track. A track that changes key gets the key the network hears most.
  • The scores are not probabilities. The softmax output ranks keys; a score of 0.8 does not mean the key is right 80% of the time.

Use it

Python

In a project managed by uv:

uv add "drone-key @ git+https://github.com/lvndry/drone"

With pip:

pip install "drone-key @ git+https://github.com/lvndry/drone"
from drone import Predictor

predictor = Predictor()  # loads drone-v2; reuse it for many files
tonic, mode, score = predictor.predict("track.mp3")
print(tonic, mode)  # e.g. "A minor"

ffmpeg must be installed: the package decodes audio with it. From a shell: python -m drone track.mp3.

Any language, with ONNX

drone-v2.onnx takes the spectrogram and returns 24 logits. You compute the spectrogram yourself; this is the exact recipe, checked against the Python package on 20 of 20 test tracks:

import librosa
import numpy as np
import onnxruntime as ort

TONICS = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]

samples, _ = librosa.load("track.mp3", sr=22050, mono=True)
lowest = librosa.note_to_hz("C1") * 2 ** (-4 / 12)  # four semitones below C1
transform = librosa.cqt(
    samples, sr=22050, hop_length=4096, fmin=lowest, n_bins=208, bins_per_octave=24
)
spectrogram = np.log1p(np.abs(transform))
features = spectrogram[8:200].astype(np.float32)[None]  # (1, 192, frames)

session = ort.InferenceSession("drone-v2.onnx")
logits = session.run(["logits"], {"features": features})[0][0]
key_class = int(logits.argmax())
print(TONICS[key_class // 2], "minor" if key_class % 2 else "major")

The contract, for a native port

Step Specification
Audio Mono (average the channels), 22,050 Hz
Spectrogram Constant-Q transform as in librosa.cqt 1.0: 208 bins, 24 per octave, lowest bin four semitones below C1 (25.9565 Hz), hop 4,096 samples, default Hann window and filter scale
Values log1p of the magnitude, float32
Network input Rows 8 to 199 of the spectrogram, shape (batch, 192, frames), at least 8 frames (about 1.5 s)
Output 24 logits. Class k is tonic TONICS[k // 2], minor when k is odd: 0 is C major, 1 C minor, 2 C# major ... 23 B minor

drone-v2.safetensors holds every weight and BatchNorm statistic in float32 under its PyTorch name, for hosts without PyTorch or ONNX Runtime. The architecture is three blocks of two 3x3 convolutions (16, 32, 64 channels), each convolution followed by BatchNorm and ELU, each block ending in 2x2 max pooling; then an average over time only, which keeps the 24 frequency rows, and one linear layer from 64 x 24 features to 24 keys. See drone/model.py. Euphoria's Rust implementation is a complete example.

Files

File For
drone-v2.pt The Python package and PyTorch. Includes training provenance in its metadata
drone-v2.onnx ONNX Runtime in any language. Opset 18, dynamic batch and length; matches PyTorch within 2e-5
drone-v2.json The ONNX file's contracts (features, labels, input layout)
drone-v2.safetensors Native implementations
drone-v1.* The previous release, unchanged

How it was trained

  • Data: 6,263 labelled tracks: 4,988 from FMAKv2 (Free Music Archive tracks of many genres with key labels) and 1,275 Beatport dance-music previews from GiantSteps-MTG-Key. The training set shares no track ID with the 604 GiantSteps Key previews.
  • Distillation: three networks first trained on the labels alone were averaged into a "teacher". drone-v2 learned half from the human labels and half from the teacher's softer predictions, and also from the teacher's predictions on 24,827 unlabelled 30-second clips (FMA medium).
  • Pitch shifting: every training excerpt was shifted by up to 12 semitones either way, with its key label moved to match, so the network learns every key from every song.
  • Recipe: AdamW (learning rate 1e-3, weight decay 1e-4), cosine schedule, 120 epochs, batch 32, 60-second crops. Seed 42; the checkpoint from epoch 88 was chosen on a held-back 10% of the training data.

The full study, including 13 experiments and everything that did not work (larger networks, more unlabelled audio, other spectrogram views, label cleaning), is in experiments/studies/frontier-distillation. The release evaluation is in experiments/studies/drone-v2-release.

License

The weights and code are MIT-licensed. The training audio and labels keep their own terms: Free Music Archive audio under each track's Creative Commons licence, FMAKv2 labels under CC BY 4.0, GiantSteps+ annotations under CC BY-SA 4.0, and GiantSteps-MTG-Key, whose publisher states no licence. The K10 architecture follows the MIT-licensed MIREX 2026 submission.

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. ๐Ÿ™‹ Ask for provider support

Evaluation results

  • Exact accuracy on GiantSteps Key with GiantSteps+ expert labels, single-key tracks (457)
    self-reported
    87.960
  • Exact accuracy on GiantSteps Key, original labels (604)
    self-reported
    69.870
  • MIREX weighted score on GiantSteps Key, original labels (604)
    self-reported
    75.450