Beat, key and loudness analysis
Every track is analysed once, offline, by TrackAnalyzer.analyze in the ORIXAnalysis module. One pass over the decoded audio produces a constant-tempo beat grid with a downbeat estimate, a musical key with its Camelot code, integrated loudness and sample peak with a suggested gain, a list of transients, and the three-band waveform summary. The module depends only on Accelerate (vDSP, vForce); it contains no machine-learning model and no third-party code.
Sources, all in Packages/ORIXDJCore/Sources/ORIXAnalysis/: TrackAnalyzer.swift, Onset.swift, Tempo.swift, BeatGrid.swift, Key.swift, Loudness.swift, FFT.swift, Waveform.swift, SignalSynth.swift. Tests: Packages/ORIXDJCore/Tests/ORIXAnalysisTests/AccuracyTests.swift and AnalyzerTests.swift (23 tests in 8 suites, all passing in the run of 2026-11-21).
Related documents: waveform.md for the waveform summary and its display, persistence.md for how results are stored, deck-engine.md for how the grid drives sync, quantisation and loops, dsp.md, ../development/testing.md and ../development/performance.md.
Entry point and result
TrackAnalyzer.analyze(left:right:sampleRate:options:progress:isCancelled:) throws -> AnalysisResultThe input is planar 32-bit float audio at the file's own sample rate (no resampling); right may alias left for mono. The call is synchronous and CPU-bound; DJSession runs it on background queues. isCancelled is polled throughout and makes the call throw CancellationError. Input that is empty or has a sample rate below 1000 Hz returns an empty result.
Order of work and the progress values reported: loudness and peak (0.15), mono mix and waveform summary (0.4), onset features (0.7), tempo, grid, downbeat and transients (0.8), key (1.0).
AnalysisResult field |
Meaning |
|---|---|
version |
AnalysisResult.currentVersion, currently 1; a stored result with another version is recomputed |
duration |
seconds |
grid |
BeatGrid(bpm, firstBeatSeconds, downbeatIndex), or nil when no tempo was found |
bpmConfidence, tempoStability, downbeatConfidence |
0...1, defined below |
key |
KeyEstimate(tonic 0...11, mode, confidence), or nil |
integratedLUFS, peakDBFS, suggestedGainDB |
loudness section below |
transients |
onset times in seconds, ascending, at most TrackAnalyzer.maximumTransients = 4096 |
waveform |
WaveformSummary, see waveform.md |
AnalysisOptions has one setting, bpmRange, default 70...180. The application does not use the default: see "Tempo range used by the application".
Beat analysis pipeline
flowchart TD
A["Mono mix: 0.5 * (L + R)"] --> B["STFT: Hann 1024, hop 10 ms"]
B --> C["Log-compressed, half-wave rectified spectral flux: low, mid, high, full"]
B --> D["Log-spaced band spectrum, up to 24 bands, 40 Hz to 12 kHz"]
A --> E["Fine envelope: RMS per 0.5 ms, rise above the previous 20 ms"]
C --> F["Detrend: subtract 1 s moving mean, rectify"]
F --> G["Unbiased normalised autocorrelation by FFT"]
G --> H["Comb scan over the BPM range, 0.25 BPM steps"]
H --> I["Refinement: harmonic sum on the zero-padded envelope spectrum"]
I --> J["Octave choice: half, same, double inside the range"]
C --> J
J --> K["Beat phase: fold kick-weighted flux at the beat period"]
E --> L["Joint micro-alignment of period and phase on attacks"]
K --> L
L --> M["BeatGrid: bpm, firstBeatSeconds"]
D --> N["Downbeat: accent and novelty contrast over 4 phases"]
M --> N
F --> O["Tempo stability: 10 s windows"]
N --> P["AnalysisResult"]
O --> P
M --> P
Onset detection by spectral flux
OnsetAnalyzer.analyze (Onset.swift):
| Parameter | Value |
|---|---|
| Hop | round(sampleRate / 100) samples: 441 at 44.1 kHz, 480 at 48 kHz, so about 100 frames per second |
| FFT size | 1 << round(log2(sampleRate * 0.0232)): 1024 at both 44.1 kHz and 48 kHz (minimum 64) |
| Window | Hann (vDSP_HANN_DENORM), frame centred on frame * hop, zero-padded at the edges |
| Compression | log1p(compression * 4 / size * magnitude) with OnsetAnalyzer.compression = 100 |
| Flux | positive part of the difference with the previous frame, summed over bins |
| Bands | low below 200 Hz, mid 200 to 2500 Hz, high above 2500 Hz, full = sum of the three |
| Nominal latency | size / 4 / sampleRate (5.8 ms at 44.1 kHz), added back when frames are converted to time |
Two more features are computed in the same pass:
- a band spectrum: the mean log magnitude in up to 24 log-spaced bands between 40 Hz and
min(12 kHz, 0.47 * sampleRate)per frame, used for the downbeat; - a fine rise envelope: RMS over blocks of
Int(sampleRate / 2000)samples (22 samples, about 0.5 ms, at 44.1 kHz), then for each block the amount by which it exceeds the maximum of the preceding 20 ms. It marks attacks with sub-millisecond resolution and is used to align beats and transients.
OnsetAnalyzer.detrended subtracts a moving average of ±0.5 s from the full-band flux and half-wave rectifies it. This envelope feeds the tempo estimator, the stability measure and the transient picker.
Transients are local maxima of the detrended envelope above 1.5 * its mean, at least 4 frames apart, limited to the 4096 strongest, each moved to the largest fine-rise value within ±15 ms of its nominal time. transientsMatchTheClicks checks that a 120 BPM click track of 10 s yields exactly 20 transients, each within 3 ms of the true click time.
Tempo by autocorrelation and comb
TempoEstimator.estimate (Tempo.swift). It returns no grid when the track is shorter than 3 s of frames or the envelope is empty.
- Envelope: the detrended flux is smoothed with a 5-tap triangular kernel (50 ms) and made zero-mean.
- Autocorrelation: computed with one forward and one inverse FFT (
RealFFT.autocorrelation) on the zero-padded envelope, then made unbiased (/ (n - lag)) and normalised by lag 0, up to a lag of four beats of the slowest tempo in the range. - Comb score of a candidate tempo: the mean of the autocorrelation at 1, 2, 3 and 4 beat periods (linear interpolation at fractional lags).
- Coarse scan of the range in steps of 0.25 BPM. The range bounds are first clamped (lower bound to 30...300, upper bound to at most 320). If the best comb score is below
minimumSalience = 0.05, no grid is reported. - Refinement: the envelope is zero-padded to
min(2^21, max(2^15, nextPowerOfTwo(16 * n)))points and transformed once; the tempo that maximises the harmonic sum of that spectrum (weights 1, 1, 0.5, 0.5 for the first four harmonics) within ±2.5 % of the coarse value is kept, searched in half-bin steps with parabolic interpolation. This uses the whole track coherently, which is what gives the BPM its precision on constant-tempo material. - Octave choice: among half, same and double tempo that lie inside the range (with a 1.5 % margin), each candidate is scored by how well the drum envelope (low + mid flux, each normalised by its mean) folds at its period. The fastest candidate whose score reaches
octaveThreshold = 0.85of the best is selected.
bpmConfidence is the square root of the comb score at the selected tempo, clamped to 0...1. It measures how periodic the onset envelope is at that tempo and its multiples; it says nothing about whether the metrical level (half or double) is the one a listener would choose.
Constant-tempo grid and first-beat phase
- Phase: a kick-weighted envelope (low 1.0, mid 0.5, high 0.15) is folded modulo the beat period into half-frame bins, smoothed circularly, and the strongest bin (parabolic interpolation) gives the beat phase.
- Micro-alignment (
alignFine): 81 candidate beat periods within a relative spread ofmin(0.003, 0.04 / duration)around the refined period are tried; for each, the fine rise envelope is summed in a ±20 ms window around every predicted beat. The candidate with the sharpest summed peak wins and the grid is shifted onto that peak. The correction is accepted only if the peak is at least 2.5 times the window mean; otherwise the flux-based phase is kept. The final BPM is60 / periodafter this step. - Grid:
BeatGrid.firstBeatSecondsis the anchor reduced modulo one beat, so0 <= firstBeatSeconds < 60 / bpm. Beatkis atfirstBeatSeconds + k * 60 / bpmfor the whole track.BeatGridprovidesbeat(at:),seconds(atBeat:),nearestBeatSeconds(to:)andbarStartSeconds(atOrBefore:)(bars of four beats).
Downbeat
The code does estimate a downbeat. TempoEstimator.downbeat needs at least 8 beats and assumes four beats per bar. For each beat it measures a low-frequency accent (maximum low-band flux within ±2 frames) and a spectral novelty (L1 distance between the mean band spectrum of this beat and of the previous one). For each of the four possible bar phases it computes a contrast statistic of both measures; the phase with the highest sum becomes downbeatIndex (0...3). downbeatConfidence = 1 - exp(-margin / 4), where margin is the lead over the second-best phase.
This is a heuristic. It was measured only on synthetic tracks (below), where the bar start is known. On real music it has not been evaluated, and downbeatConfidence is not a column of real-music-analysis.tsv.
Tempo stability
tempoStability compares local tempo with the global one. The detrended envelope is cut into 10 s windows with 50 % overlap; in each, the autocorrelation is searched within ±8 % of the four-beat lag (two or one beat for short windows) and the deviation of its peak from the expected lag is converted to an agreement max(0, 1 - deviation / 0.04). The result is the mean agreement weighted by window energy. A window that deviates by 4 % or more, or has no clear peak, contributes 0.
driftingTempoHasLowStability asserts: steady 120 BPM clicks above 0.9; clicks accelerating from 90 to 150 BPM over 40 s below 0.4; a random-walk tempo between 90 and 135 BPM below 0.6. The value is a warning that a constant grid will not fit; nothing is done to fit a better one.
Tempo range used by the application
DJSession.analysisOptions in Packages/ORIXDJCore/Sources/ORIXDJEngine/Session.swift sets the range for everything the application analyses:
/// Tempo is reported between 78 and 156 BPM, the convention of DJ software: one octave, so half- and double-time
/// readings of the same track always agree. The deck's ÷2 and ×2 buttons change it per track.
public static let analysisOptions: AnalysisOptions = { var o = AnalysisOptions(); o.bpmRange = 78 ... 156; return o }()The benchmark tool (orix-dj-bench, RealMusic.swift) uses the same options, so real-music-analysis.tsv reflects what the application stores.
Reason for the range: with the default 70...180, an earlier run of the same tool on this music produced double-tempo readings on several tracks between 84 and 90 BPM (values such as 168, 177 and 181 BPM were reported). That earlier output was not kept as a report file. A range wider than one octave contains both metrical levels for such tracks, and the "prefer the fastest acceptable level" rule then picks the upper one. With a range of exactly one octave only one level is available, so the ambiguity cannot arise.
Consequences:
- A tempo outside 78...156 is reported at the octave that falls inside it. A 70 BPM track is stored as 140, a 174 BPM track as 87.
bpmRangeFoldsTheTempoverifies the mechanism (140 BPM clicks read 70 with range60...100, 140 with100...200; 60 BPM clicks read 120 with the default range). - The octave-choice step has almost nothing left to decide, since half and double of a value inside the range fall outside it except within the 1.5 % margin at the edges.
- Tracks near the edges (about 78 or 156 BPM) can land on either side.
- The correction is manual: the comment refers to the deck's ÷2 and ×2 buttons, and
DJSession.setGridstores an edited grid.
The synthetic accuracy table below was produced with the default range, as its header states, not with the application's range.
Key detection
KeyEstimator (Key.swift) computes one global chroma vector for the track and correlates it with key templates.
- Decimation by
max(1, Int(sampleRate / 5000)): factor 8 at 44.1 kHz (5512.5 Hz), 9 at 48 kHz (5333 Hz), with a Hamming-windowed sinc low-pass of12 * factor + 1taps (97 at 44.1 kHz) and cut-off0.45 / factorcycles per input sample (vDSP_desamp). - STFT on the decimated signal: size
1 << round(log2(0.74 * fs)), which is 4096 at both rates (0.74 s at 5512.5 Hz), hopsize / 4= 1024, Hann window. - Peak picking between 55 Hz and 2000 Hz: local maxima above 3 % of the frame's maximum, frequency refined by parabolic interpolation on log magnitudes, converted to pitch and accumulated in a 120-bin histogram (10 cents per bin, one octave folded) with weight
sqrt(magnitude). - Tuning: the offset, in 10-cent steps from -50 to +40 cents, of the 12-tooth comb that captures the most energy. The 12 pitch-class bins are then read around that offset with a
cos^2window of ±40 cents. The offset is available asChroma.tuningCentsbut is not stored in the result. - Templates: the Krumhansl-Kessler probe-tone profiles (
majorProfile,minorProfile; the source cites Krumhansl and Kessler, 1982), each extended by folding in the first six partials of every note (pitch-class offsets 0, 0, 7, 0, 4, 7) with weightsharmonicDecay^(h-1),harmonicDecay = 0.45. A chroma taken from a spectrum contains overtones; the plain profiles do not. - Decision: Pearson correlation of the chroma with the 24 rotated templates; the best one is the key. No key is reported when the best correlation is not positive or the chroma is empty (silence).
Meaning of confidence: min(1, margin / 0.15) * sqrt(bestCorrelation), where margin is the difference between the best and the second-best correlation. It is a measure of how much the winner stands out from the runner-up, not a probability of being right. A value near 0 means two keys fit almost equally well. A high value does not guarantee the key is right (see "...Baby One More Time" below).
Names and Camelot mapping
KeyEstimate.name gives "A minor", shortName "Am". Major tonics use flat names (D♭, E♭, A♭, B♭) except F♯; minor tonics use C♯, F♯, G♯ and E♭, B♭.
camelotNumber takes the tonic of the relative major (minor tonic + 3 semitones) and maps it with (majorTonic * 7 + 7) % 12 + 1; the letter is A for minor and B for major. So C major is 8B, A minor 8A, F♯ major 2B. keyNamesAndCamelot checks all 24 codes against the wheel.
isCompatible(with:) is true for the same Camelot number (same key or relative major/minor) or, within the same mode, numbers that differ by one (a fifth up or down), with wrap-around between 12 and 1. transposed(semitones:) shifts the tonic.
Loudness and peak
Loudness.measure (Loudness.swift) implements integrated loudness after ITU-R BS.1770-4:
- K-weighting as two biquads (high shelf, then high-pass). The coefficients are derived for the actual sample rate from the analogue prototypes of the standard's 48 kHz filters with the bilinear transform, and applied in double precision (
vDSP_biquadD). - Energy is accumulated in 100 ms steps; gating blocks are 400 ms with 75 % overlap.
- Absolute gate at -70 LUFS, then a relative gate 10 LU below the mean of the blocks that passed the absolute gate.
- A mono input (aliased pointers) is measured as dual mono. Input shorter than one gating block is measured ungated.
- Digital silence is reported as
-70LUFS and-120dBFS (silenceLUFS,silencePeakDBFS) so that results remain JSON-encodable.
peakDBFS is the sample peak over both channels (vDSP_maxmgv), not a true-peak measurement: inter-sample peaks are not estimated.
suggestedGainDB = min(targetLUFS - integratedLUFS, -1 - peakDBFS) with AnalysisResult.targetLUFS = -14: the gain that brings the track to -14 LUFS, limited so that the sample peak stays at or below -1 dBFS; 0 for silence. DJSession applies it at load only when Auto DJ is running with autoGain enabled, and the offline mix tool applies it too; both clamp it to -12...+6 dB.
Test (LoudnessTests) |
Tolerance |
|---|---|
| Stereo 1 kHz sine at -20 dBFS, 44.1 and 48 kHz | -20 LUFS ± 0.15; peak -20 dBFS ± 0.05; suggested gain +6 dB ± 0.2 |
| 0 dBFS 997 Hz sine in one channel, 48 kHz | -3.01 LUFS ± 0.1 |
| Same in both channels | 0.0 LUFS ± 0.1; dual mono within 0.01 of stereo; suggested gain below -13.5 dB |
| 10 s of signal followed by 20 s of silence | within 0.1 LU of the signal alone (absolute gate) |
| Half the signal 20 dB quieter | within 0.2 LU of the loud half (relative gate) |
| Half the signal 6 dB quieter | between 1.5 and 3 LU lower |
| Quiet pink noise with one 0.99 sample | suggested gain equals -1 - peakDBFS |
The standard's own conformance audio files were not run.
Accuracy on synthetic signals
AccuracyTests.accuracyReport measures the analyser on signals whose tempo, beat phase, bar phase and key are known exactly, and prints the table below. All signals come from SignalSynth, which is deterministic (a SplitMix64-style generator seeded per track) and contains no samples.
How the signals are made
- Click tracks (
SignalSynth.clickTrack): one click per beat; the click is a 15 ms burst of 1 kHz and 3 kHz cosines with instantaneous attack and a 3 ms decay. - Tracks (
SignalSynth.track) in four styles, peak-normalised to 0.891 (-1 dBFS), real stereo:- drums synthesised from formulas: kick (sine swept from 158 Hz to 48 Hz plus a noise click), snare, clap, closed and open hats, crash, and a soft pulse for the ambient style;
- additive tones (bass, stab, pad, slow pad, pluck, drone) with 3 or 4 harmonics and simple envelopes;
- harmony: a four-bar progression on scale degrees 1, 6, 4, 5 of the major or natural minor scale of the requested tonic (I-vi-IV-V, or i-VI-iv-v), bass on chord roots;
- bar structure by phrases of 4 bars (8 when the track has 32 bars or more): intro, main, breakdown without drums, drop, and an outro when there are at least five phrases;
houseandtechnohave a kick on every beat;breakbeathas kicks on sixteenth steps 0 and 10 and snares on beats 2 and 4;ambienthas slow pads, a drone and a soft pulse, with no pulse in the intro and breakdown.
- Test set: 40 s per signal at 44.1 kHz. Tempo rows: the ten tempi 70, 87.5, 100, 120, 124, 128, 133.3, 140, 150 and 174 BPM, each as a click track and in the four styles (50 signals), with a first-beat offset of
0.031 + 0.0173 * is and varying keys. Key rows: all 24 keys in three styles (house at 124, breakbeat at 133.3, ambient at 100 BPM), 72 signals.
Classification rules of the test
- Tempo:
correctwhen the ratio to the truth is within 1 %;doublewithin 0.02 of 2;halfwithin 0.005 of 0.5; otherwiseother;nonewhen no grid is returned. - BPM error: absolute error over the
correctrows. - Phase error: distance in milliseconds between the true beat nearest the middle of the track and the nearest grid beat, over
correctanddoublerows. Measuring at the middle charges a small tempo error to the phase, as it would be heard. - Downbeat: counted on
correcttrack rows; right when the estimated bar start is within half a beat of the true one. - Key:
exact;relative(other mode, same Camelot number);fifth(same mode, tonic 5 or 7 semitones away);parallel(same tonic, other mode);other;none.
Measured table
Output of the test run of 2026-11-21 (debug build), reproduced verbatim:
=== ORIX-ANALYSIS-ACCURACY ===
Synthetic audio only (SignalSynth), 40 s per track, 44.1 kHz, bpmRange 70...180.
Tempi: 70.0, 87.5, 100.0, 120.0, 124.0, 128.0, 133.3, 140.0, 150.0, 174.0
TEMPO / BEAT PHASE / DOWNBEAT (BPM error over tempo-correct tracks = within 1 %; phase over correct + double-time)
group n correct double half other nogrid bpmErr mean bpmErr max phase mean ms phase max ms downbeat conf stab dbConf
click 10 10 0 0 0 0 0.000 0.001 0.068 0.113 - 0.98 0.99 0.03
house 10 9 1 0 0 0 0.001 0.002 0.949 1.001 9/9 0.93 0.99 0.62
techno 10 10 0 0 0 0 0.001 0.001 1.023 1.089 10/10 0.92 0.80 0.76
breakbeat 10 9 0 1 0 0 0.001 0.002 0.951 1.024 9/9 0.88 0.99 0.81
ambient 10 8 2 0 0 0 0.002 0.003 7.201 16.340 8/8 0.75 0.98 0.92
all tracks 40 36 3 1 0 0 0.001 0.003 2.572 16.340 36/36 0.87 0.94 0.78
Octave error rate on tracks: 4/40 = 10.0 %
Per-track detail (estimated BPM; * = not within 1 % of the truth)
bpm click house techno breakbeat ambient
70.0 70.00 70.00 70.00 70.00 140.00*
87.5 87.50 175.00* 87.50 87.50 174.83*
100.0 100.00 100.00 100.00 100.00 100.00
120.0 120.00 120.00 120.00 120.00 120.00
124.0 124.00 124.00 124.00 124.00 124.00
128.0 128.00 128.00 128.00 128.00 128.00
133.3 133.30 133.30 133.30 133.30 133.30
140.0 140.00 140.00 140.00 70.00* 140.00
150.0 150.00 150.00 150.00 150.00 150.00
174.0 174.00 174.00 174.00 174.00 174.00
KEY (24 keys per style)
style exact relative fifth parallel other none mean conf
house 23 1 0 0 0 0 0.78
breakbeat 24 0 0 0 0 0 0.86
ambient 24 0 0 0 0 0 0.92
all 71 1 0 0 0 0 0.85
Key errors: house D♭->B♭m
=== END ===Reading the table:
- Every error is an octave error (4 of 40 tracks); there is no unrelated tempo and no missing grid. In the four cases both metrical levels lie inside
70...180: 70 and 87.5 BPM read at double, 140 BPM breakbeat read at half. With the application's78...156range these particular confusions cannot occur, but 70 and 174 BPM would be stored as 140 and 87 by design. - On tempo-correct tracks the BPM error is at most 0.003 BPM, for 40 s signals with a perfectly constant tempo.
- Beat phase is within about 1 ms on the three styles with drums. The ambient style, whose pulse has a 4 ms attack and whose pads have slow attacks, is at 7.2 ms mean and 16.3 ms worst case.
- The downbeat was right on all 36 tempo-correct tracks. These tracks have a clear bar structure (crash on phrase starts, chord changes on bar lines), which is what the heuristic looks for.
- The click rows have a mean downbeat confidence of 0.03: identical clicks carry no bar information.
- The mean stability of the techno rows is 0.80, lower than the other styles although the tempo is exactly constant; the reason was not investigated.
- Key: 71 of 72 exact, one relative-minor confusion.
Regression floors
The test fails if any of these is violated; they are looser than the measured values:
| Assertion | Floor |
|---|---|
| Click tracks | all correct, BPM error below 0.02, phase error below 2 ms |
| Tracks | at least 32 of 40 correct; none other or none; BPM error below 0.03 on correct ones |
| Phase on styles with drums | mean below 3 ms |
| Downbeat | at least 80 % of evaluated tracks |
| Key | at least 64 of 72 exact |
Other analysis tests: otherSampleRatesSwingAndMono (a 126 BPM house track with 25 % swing at 48 kHz and 22.05 kHz, stereo and mono: BPM within 0.05, first beat within 6 ms, key exact); steadySineAndNoiseHaveNoConfidentTempo (a steady sine gives no grid; white and pink noise give no grid or a confidence below 0.4); silenceGivesNoGrid; veryShortInputsDoNotCrash (0 to 40 000 samples: no grid, no crash); cancellationThrows; progressIsMonotonicAndEndsAtOne; resultRoundTripsThroughJSON.
Synthetic results are an upper bound. These signals have exact tempo, clean attacks, diatonic harmony with a clear tonic, and no vocals. They show that the implementation does what it is designed to do; they do not predict accuracy on recorded music.
Comparison on real music
docs/reports/real-music-analysis.tsv holds the analysis of 60 commercial tracks from the owner's library (four artists: Britney Spears, Dr. Dre, Dua Lipa, Lady Gaga), produced by orix-dj-bench with the application's options. All 60 files decoded and analysed (0 failed).
About the reference values. The reference tempi and keys below are values commonly published for these songs, recalled from public listings. They were not independently verified by us: nobody tapped the tempi or checked the keys by ear or against a score, and such listings are usually rounded to whole BPM. The comparison therefore measures agreement with commonly published values, not accuracy against ground truth. Only tracks for which a reference was at hand are compared: 20 of 60 for tempo, 11 of 60 for key. The selection was not random.
Tempo
| Track | Published BPM | Measured BPM | Difference | Relation | BPM confidence | Stability |
|---|---|---|---|---|---|---|
| Lady Gaga - Bad Romance | 119 | 119.00 | 0.00 | within ±1 | 0.88 | 0.98 |
| Lady Gaga - Just Dance | 119 | 119.00 | 0.00 | within ±1 | 0.88 | 0.98 |
| Lady Gaga - Poker Face | 119 | 119.00 | 0.00 | within ±1 | 0.77 | 0.98 |
| Lady Gaga - Telephone | 122 | 122.00 | 0.00 | within ±1 | 0.76 | 0.98 |
| Lady Gaga - Alejandro | 99 | 99.00 | 0.00 | within ±1 | 0.83 | 0.97 |
| Lady Gaga - Paparazzi | 115 | 115.00 | 0.00 | within ±1 | 0.64 | 0.98 |
| Lady Gaga - LoveGame | 105 | 105.00 | 0.00 | within ±1 | 0.76 | 0.97 |
| Dua Lipa - Don't Start Now | 124 | 124.00 | 0.00 | within ±1 | 0.83 | 0.99 |
| Dua Lipa - Levitating | 103 | 103.00 | 0.00 | within ±1 | 0.81 | 0.99 |
| Dua Lipa - Physical | 147 | 147.00 | 0.00 | within ±1 | 0.84 | 0.98 |
| Dua Lipa - Hallucinate | 122 | 122.00 | 0.00 | within ±1 | 0.83 | 0.98 |
| Dua Lipa - Break My Heart | 113 | 113.00 | 0.00 | within ±1 | 0.79 | 0.96 |
| Dua Lipa - Love Again | 116 | 116.02 | +0.02 | within ±1 | 0.87 | 0.97 |
| Dua Lipa - Future Nostalgia | 116 | 115.00 | -1.00 | within ±1 (at the limit) | 0.81 | 0.98 |
| Dua Lipa - Pretty Please | 106 | 107.00 | +1.00 | within ±1 (at the limit) | 0.84 | 0.98 |
| Britney Spears - ...Baby One More Time | 93 | 92.98 | -0.02 | within ±1 | 0.91 | 0.99 |
| Britney Spears - Sometimes | 96 | 96.01 | +0.01 | within ±1 | 0.89 | 1.00 |
| Dr. Dre - Still D.R.E. | 93 | 93.43 | +0.43 | within ±1 | 0.89 | 0.99 |
| Dr. Dre - The Next Episode | 95 | 95.38 | +0.38 | within ±1 | 0.89 | 0.98 |
| Dr. Dre - Forgot About Dre | 134 | 133.87 | -0.13 | within ±1 | 0.76 | 0.98 |
Agreement over the 20 tracks:
| Category | Definition | Count |
|---|---|---|
| Exact | measured within ±1 BPM of the published value | 20 |
| Octave | measured within ±1 BPM of double or half the published value | 0 |
| Other | anything else | 0 |
Notes:
- 18 of the 20 are within 0.5 BPM. The two others, "Future Nostalgia" and "Pretty Please", differ by exactly 1.00 BPM at the two decimals printed, which is on the boundary of the ±1 criterion. For these two either the published value or the measurement is off by one; we did not determine which.
- "Levitating" appears twice in the report: the plain version (compared above) and "Levitating (feat. DaBaby)". The second also reads 103.00 BPM (confidence 0.76, stability 0.98). It is not counted, so that the song is not counted twice.
- All 20 published values lie inside 78...156, so this comparison cannot expose the folding described above. In the full report, three Britney Spears and Lady Gaga tracks read 142.00, 150.00 and 145.34 BPM ("E-Mail My Heart", "From the Bottom of My Broken Heart", "Speechless"); if their musical tempo is below 78 BPM, these are the double-time values the range imposes. No reference was at hand for them and this was not verified.
- "Forgot About Dre" is listed at 134 BPM; the same pulse counted at half speed is 67, which the range excludes.
Key
Pitch classes are numbered C = 0 ... B = 11. Categories, the same as in the synthetic test:
- exact: same tonic and mode;
- relative: other mode, same key signature (minor tonic 3 semitones below the major tonic; same Camelot number);
- fifth: same mode, measured tonic 7 semitones (dominant) or 5 semitones (subdominant) above the reference; adjacent Camelot number;
- parallel: same tonic, other mode;
- other: anything else.
| Track | Published key | Measured key | Measured Camelot | Relation | Key confidence |
|---|---|---|---|---|---|
| Dua Lipa - Don't Start Now | B minor | B minor | 10A | exact | 0.79 |
| Dua Lipa - Levitating | B minor | B minor | 10A | exact | 0.29 |
| Dua Lipa - Physical | A minor | A minor | 8A | exact | 0.41 |
| Dua Lipa - Break My Heart | E minor | E minor | 9A | exact | 0.52 |
| Dua Lipa - Love Again | F♯ minor | F♯ minor | 11A | exact | 0.92 |
| Lady Gaga - Telephone | F minor | F minor | 4A | exact | 0.27 |
| Lady Gaga - Bad Romance | A minor (9) | E minor (4) | 9A | fifth (dominant, +7) | 0.40 |
| Lady Gaga - Poker Face | G♯ minor (8) | B major (11) | 1B | relative major | 0.22 |
| Lady Gaga - Just Dance | C♯ minor (1) | E major (4) | 12B | relative major | 0.21 |
| Lady Gaga - Alejandro | B minor (11) | F♯ minor (6) | 11A | fifth (dominant, +7) | 0.16 |
| Britney Spears - ...Baby One More Time | C minor (0) | G minor (7) | 6A | fifth (dominant, +7) | 0.89 |
Agreement over the 11 tracks:
| Category | Count |
|---|---|
| Exact | 6 |
| Relative major/minor | 2 |
| Fifth-related (all three on the dominant) | 3 |
| Parallel | 0 |
| Other | 0 |
Notes:
- 6 of 11 agree exactly. The 5 disagreements are all with a key that
isCompatible(with:)treats as compatible with the published one (same or adjacent Camelot code). For harmonic mixing such an error costs less than an unrelated key would, but the displayed key name differs from the published one. - Confidence does not separate agreement from disagreement here. The exact matches have confidences from 0.27 to 0.92; "...Baby One More Time" disagrees with the published key at 0.89. The sample is far too small to calibrate anything.
- "Levitating (feat. DaBaby)" also reads B minor (confidence 0.22); not counted.
- Eleven tracks by three artists are not a benchmark. No evaluation on an annotated key dataset has been done.
Other observations in the report
- Low key confidence is common. Over the 60 tracks the median key confidence is 0.29; 12 tracks are below 0.10 and 26 below 0.25; 19 are at or above 0.5. Ten are at or below 0.05, for example "E-Mail My Heart" (0.00), "Bar One" (0.01), "Hallucinate" (0.01), "(You Drive Me) Crazy" (0.02), "Housewife" (0.02). For these the best and second-best templates fit almost equally well. The library stores the confidence (
key_confidence) next to the key. - Short interludes. The two tracks with the lowest tempo confidence are short items: "Lolo (Intro)" (41 s; 110.68 BPM, confidence 0.27, stability 0.34) and "The Car Bomb" (61 s; 100.38 BPM, confidence 0.23, stability 0.06). A grid is still reported for them, because the comb score exceeds the
minimumSaliencefloor of 0.05; it should not be trusted. "Pause 4 Porno" (93 s) has stability 0.90 and reads 79.99 BPM, at the lower edge of the range. - Across the report the median tempo confidence is 0.82 and the median stability 0.98; only the two items above and "Boys Will Be Boys" (0.49) have a tempo confidence below 0.5.
- Loudness. Integrated loudness ranges from -14.2 to -5.9 LUFS (median about -8.4) and sample peaks from -1.3 to 0.0 dBFS. With these values the suggested-gain formula gives a negative gain for all 60 tracks.
Analysis speed
| Measurement | Result | Source |
|---|---|---|
| 60 real tracks, 12 449 s of audio | analysed in 32.0 s, 389 times real time (analysis only; the decode_s column adds up to a further 29.2 s); per track 0.05 s to 1.98 s |
footer and columns of docs/reports/real-music-analysis.tsv |
| 5-minute 44.1 kHz stereo synthetic track, release build | 0.294 s; BPM 126.000 (truth 126), first beat 0.0812 s (truth 0.0800), key G minor (truth G minor), -13.7 LUFS | docs/reports/engine-benchmark.txt, Apple M5 Max |
Same length, debug build, fiveMinuteTrackTiming |
0.747 s, best of 3; BPM 126.0002, first beat 0.0811 s, downbeat 0, key G minor, -14.95 LUFS, stability 0.99, 1974 transients | test output of 2026-11-21 |
The benchmark and the test use the same track specification except for the seed (5 and 11), so their loudness values differ. The test asserts less than 3.0 s in release builds only. Analysis is single-threaded per track, and the application analyses one track at a time on a utility-priority queue (DJSession.analyzePending). In the real-music run, per-track analysis times vary by a factor of more than ten for tracks of similar length; the cause was not investigated.
Memory: the analyser works on the fully decoded track and allocates one mono copy plus one scratch buffer of the same length for the waveform filters. Peak memory was not measured.
Limitations
- Constant tempo only. The grid is one BPM and one phase for the whole track. There are no variable-tempo grids, no tempo maps and no per-beat positions. Live drummers, rubato, tempo changes and tracks that drift will not stay on the grid;
tempoStabilityreports the problem and nothing corrects it. - Octave ambiguity is resolved by convention. With the application's
78...156range, slow and fast tracks are stored at the octave inside the range. The user corrects this per track. - Downbeat is a heuristic that assumes 4/4 and a constant bar phase. Other metres, pick-up bars and tracks that drop or add beats are not handled. It was validated only on synthetic tracks.
- A grid is reported for weakly rhythmic material whenever the comb score exceeds 0.05. The analyser does not withhold a low-confidence grid; callers have
bpmConfidenceandtempoStabilityto judge it. - One global key per track. Modulations are averaged into one chroma vector. Only major and natural-minor templates exist; modal, atonal and percussion-only material still receives a key unless the chroma is empty.
- Key confidence is a margin, not a probability, and is low for a large share of real tracks (see above).
- Spelling is fixed by pitch class: G♯ minor is never shown as A♭ minor.
- Sample peak, not true peak. The -1 dBFS ceiling of the suggested gain does not account for inter-sample peaks.
- Loudness is integrated only. No short-term or momentary loudness and no loudness range are computed.
- Evaluation is thin. Accuracy claims rest on synthetic signals with exact ground truth, plus agreement with commonly published, unverified values for 20 tempi and 11 keys from four artists. No annotated dataset, no other genres, and no listening verification of beat phase or downbeats on real music.
- Two automated mixes rendered offline by
orix-dj-bench mixre-analyse at 124.00 BPM and 119.00 BPM with stability 0.98. That is consistent with the two decks having stayed aligned, but nobody has listened to those files yet.