File size: 10,205 Bytes
e305870
 
89fcce4
 
e305870
 
 
 
89fcce4
 
e305870
 
89fcce4
 
e305870
89fcce4
e305870
 
 
89fcce4
e305870
89fcce4
 
e305870
89fcce4
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e305870
89fcce4
 
e305870
 
89fcce4
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
214d1c7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
89fcce4
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e305870
89fcce4
e305870
89fcce4
 
 
e305870
 
 
 
89fcce4
 
 
e305870
 
89fcce4
 
 
 
 
 
 
 
e305870
 
89fcce4
e305870
 
 
89fcce4
e305870
89fcce4
 
 
 
 
 
 
e305870
89fcce4
 
 
 
 
e305870
89fcce4
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
---
license: mit
library_name: pytorch
pipeline_tag: audio-classification
tags:
  - audio
  - music
  - key-detection
  - music-information-retrieval
  - dj
  - constant-q-transform
  - cnn
  - onnx
  - safetensors
model-index:
  - name: drone-v2
    results:
      - task:
          name: Musical key detection
          type: audio-classification
        dataset:
          name: GiantSteps Key with GiantSteps+ expert labels, single-key tracks (457)
          type: giantsteps-plus
        metrics:
          - name: Exact accuracy
            type: accuracy
            value: 87.96
            verified: false
      - task:
          name: Musical key detection
          type: audio-classification
        dataset:
          name: GiantSteps Key, original labels (604)
          type: giantsteps-key
        metrics:
          - name: Exact accuracy
            type: accuracy
            value: 69.87
            verified: false
          - name: MIREX weighted score
            type: other
            value: 75.45
            verified: false
---

# 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](https://github.com/lvndry/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](https://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](https://zenodo.org/records/4153506) 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](https://zenodo.org/records/12759100)), 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](https://docs.astral.sh/uv/):

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

With pip:

```bash
pip install "drone-key @ git+https://github.com/lvndry/drone"
```

```python
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:

```python
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`](https://github.com/lvndry/drone/blob/main/drone/model.py).
Euphoria's [Rust implementation](https://github.com/lvndry/euphoria) 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`](https://github.com/lvndry/drone/blob/main/experiments/studies/frontier-distillation/REPORT.md).
The release evaluation is in
[`experiments/studies/drone-v2-release`](https://github.com/lvndry/drone/blob/main/experiments/studies/drone-v2-release/REPORT.md).

## 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.