SPB Git

Repository Public

analysis.md 35.1 KB

# 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

swift
TrackAnalyzer.analyze(left:right:sampleRate:options:progress:isCancelled:) throws -> AnalysisResult

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

  1. Envelope: the detrended flux is smoothed with a 5-tap triangular kernel (50 ms) and made zero-mean.
  2. 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.
  3. Comb score of a candidate tempo: the mean of the autocorrelation at 1, 2, 3 and 4 beat periods (linear interpolation at fractional lags).
  4. 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.
  5. 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.
  6. 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.85 of 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 of min(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 is 60 / period after this step.
  • Grid: BeatGrid.firstBeatSeconds is the anchor reduced modulo one beat, so 0 <= firstBeatSeconds < 60 / bpm. Beat k is at firstBeatSeconds + k * 60 / bpm for the whole track. BeatGrid provides beat(at:), seconds(atBeat:), nearestBeatSeconds(to:) and barStartSeconds(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:

swift
/// 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. bpmRangeFoldsTheTempo verifies the mechanism (140 BPM clicks read 70 with range 60...100, 140 with 100...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.setGrid stores 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.

  1. 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 of 12 * factor + 1 taps (97 at 44.1 kHz) and cut-off 0.45 / factor cycles per input sample (vDSP_desamp).
  2. 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), hop size / 4 = 1024, Hann window.
  3. 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).
  4. 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^2 window of ±40 cents. The offset is available as Chroma.tuningCents but is not stored in the result.
  5. 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 weights harmonicDecay^(h-1), harmonicDecay = 0.45. A chroma taken from a spectrum contains overtones; the plain profiles do not.
  6. 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 -70 LUFS and -120 dBFS (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;
    • house and techno have a kick on every beat; breakbeat has kicks on sixteenth steps 0 and 10 and snares on beats 2 and 4; ambient has 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 * i s 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: correct when the ratio to the truth is within 1 %; double within 0.02 of 2; half within 0.005 of 0.5; otherwise other; none when no grid is returned.
  • BPM error: absolute error over the correct rows.
  • Phase error: distance in milliseconds between the true beat nearest the middle of the track and the nearest grid beat, over correct and double rows. Measuring at the middle charges a small tempo error to the phase, as it would be heard.
  • Downbeat: counted on correct track 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:

text
=== 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's 78...156 range 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 minimumSalience floor 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; tempoStability reports the problem and nothing corrects it.
  • Octave ambiguity is resolved by convention. With the application's 78...156 range, 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 bpmConfidence and tempoStability to 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 mix re-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.
Files main
Menu

Theme