The whole track, one coherent grid.
rbxport’s analysis engine, rbl-analysis, turns decoded audio into BPM, beat timestamps, bar numbers, key, and a three-band waveform. The same audio and settings produce the same result. It is tuned around electronic music in 4/4: four beats per bar, numbered 1–4.
Timing and musical structure do different jobs. Kick attacks place the markers; changes in the arrangement help decide which marker is beat 1. The engine checks the whole track so a clean intro does not hide a later tempo change.
Follow the analysis pipeline.
From decoded audio to a finished beatgrid and key. The main path runs from top to bottom; the branches show where the engine adjusts its plan when the music changes.
Explore the four-stage pipeline
¹ Kick-attack placement requires High precision. ² Internal phrase-start markers are not labeled intro, verse, or chorus detection.
Each decision is explained below: tempo changes, gaps and breakdowns, beat 1, file-start checks, and key rules.
Choose what to analyze.
Choose Analyze Track from a track or player menu. The Analysis Setting dialog applies to the selected batch; changing your selection afterward does not change the queued tracks.
| Setting | What changes |
|---|---|
| BPM / Grid | Updates BPM and beat markers and regenerates waveforms. |
| High precision | Uses attack placement; enabled by default. Without it, placement uses the onset envelope. |
| BPM Range | 70–180 by default; also 98–195, 118–236, and 58–115. |
| KEY | Updates key metadata. Key-only analysis leaves BPM, grids, and waveform files untouched. |
Unchecked results are preserved. Analysis locks prevent changes and a refused track does not stop the rest of the batch. If key detection returns no result, the existing key stays.
Presets and automatic imports
The documented Normal and RBXport presets currently select the same underlying analysis options; they are not two independent engines. Automatic imports use full analysis, high precision, and a 70–180 range. Manual choices belong to that batch rather than overwriting global preferences.
Find the pulse, not just a repeating sound.
The first pass measures onsets—moments when sound energy rises. Sustained notes and fading tails contribute less than a fresh percussive hit. Two measurements work together: how often that pattern repeats, and how strongly it supports each rhythmic rate.
This helps distinguish drum & bass at 174 BPM from half-time 87 BPM. The faster interpretation wins when it carries the rhythm. A broad preference around 132 BPM helps resolve close octave ties; it does not force tracks to that speed.
The tempo calculation
A 1,024-sample spectrum advances by 256 samples. Positive spectral differences form a normalized onset envelope. Candidates are scored using autocorrelation × √Fourier magnitude × a broad tempo prior. The standalone documentation describes a 70–200 search; the app constrains it to your selected BPM range.
Put the marker on the kick’s attack.
BPM gives the spacing between beats. A rough grid estimates their positions, then high-precision analysis looks near each marker for the beginning of a kick. It follows the nearby strong rise rather than the loudest part of the kick’s body.
A weighted timing line is fitted through reliable attacks, then fitted again with outliers removed. Missing kicks do not pull the line away from the steady sections. The grid extends to the start and end of the file.
Precision and whole-number tempos
The attack detector uses the 900–9,000 Hz band, RMS in 1 ms steps, and a ±15 ms search around each prediction. It compares two phases half a beat apart. A steady fitted tempo within 0.1 BPM of a whole number is snapped to that number and re-aligned through the same attacks. Ramps keep their measured per-beat intervals.
Follow tempo changes beat by beat.
The engine checks 16-second windows throughout the track. A different tempo needs repeated, consistent support. It does not treat every fill, isolated impact, or half-level incoming kick as a new settled tempo.
Illustrative intervals: 128 → 136 → 146 → 160 → 174 BPM. Each measured interval gets its own BPM; there is no single jump during the ramp. The final grid resumes after four consecutive intervals match its period within 1% and its phase within 2 ms. Blue, taller markers indicate beat 1; coral markers indicate beats 2–4. Schematics, not track measurements.
Illustrative mid-bar cut: the old grid holds until the first supported new-grid beat. Reliable kick runs are preferred; if none qualifies, transient support helps choose the cut. The yellow dashed line marks the BPM decision, not necessarily a downbeat. Blue, taller markers indicate beat 1; coral markers indicate beats 2–4. Schematics, not track measurements.
Gradual changes: follow the hits toward the next stable section and keep every measured interval, including curved ramps. Abrupt changes: if the walk cannot settle, make a cut where the new grid has reliable support. Beat numbers continue 1–4 across the join.
When kicks and usable clicks disappear, quiet full-band transients can carry the transition. The engine boosts their rises internally by 4× with a 20 ms release. This changes the analysis signal, not your audio. Original hit timestamps are retained; silence and release tails cannot invent beats.
When a new tempo qualifies
At least three windows must agree within 1% of a candidate that differs by more than 2%. Familiar rhythm ratios have a 1% exclusion zone. A walked transition allows up to 5% period drift per beat and rejoins the steady grid after four consecutive intervals agree within 1% in period and 2 ms in phase. The transient fallback is confined to transitions; it does not replace whole-track estimation or settled fitting.
A breakdown is not automatically a new grid.
After two bars without supporting hits, the engine checks how the music returns. If the hits land on the original grid, that grid holds through the breakdown. If they return at the same BPM but shifted in time, each side gets its own alignment and a cut joins them.
A slowdown or speed-up inside that gap is followed only when it leads to a real timing change. If the music comes back on the grid it left, the effect remains a breakdown. This separate gap walker uses its original envelope and thresholds, rather than the newer transition-emphasis fallback.
The first sound is not always beat 1.
A loud off-beat hat, clap, or reverse bass can fool a simple hit detector. rbxport compares the music before and after possible bar positions, looking for drops, breakdowns, and new bass lines. Those repeated changes help identify the downbeat.
It examines eight positions per bar: four beats and their midpoints. Evidence is combined over one-, two-, four-, and eight-bar views. If the winning position lies between the current markers, the grid shifts half a beat.
When the opening tempo segment has at least 32 beats, its own music decides the opening bar position. Later sections cannot simply outvote it. Repetitive audio with little meaningful structural change retains a first-beat fallback.
Handle a kick at the file boundary.
A fitted marker just before zero can leave the first visible marker almost a beat late. If audio starts immediately, a grid beat is close to the boundary, and the downbeat decision agrees, rbxport can anchor beat 1.1 at exactly zero.
If strictly less than 20 ms of the opening beat has been cut away, only that opening marker is added at zero; later markers and BPM values keep their fitted positions. Silence at the start, a clearly later downbeat, or a cut of 20 ms or more does not qualify.
A conditional adjustment, not a universal reset
The first segment and boundary are checked within 15 ms. Audio must already be present at the beginning, with the first millisecond carrying at least 10% of the local first-15-ms peak. An uncut boundary beat can re-anchor the first segment; a clipped opening uses a shortened first interval. Later tempo segments are preserved. This is a boundary heuristic, not independent proof of musical structure.
Build a picture of the notes.
Key detection uses Ángel Faraldo’s edmkey approach with electronic-music key profiles. It gathers spectral peaks, balances their influence, and folds their evidence into twelve pitch classes. Octaves contribute to the same note class.
The pitch profile is compared with major and minor templates at all twelve tonics: 24 candidates. Harmonic weighting, a per-frame gate, and detuning correction help the profile reflect tonal content rather than raw loudness.
Read the paper: Key Estimation in Electronic Dance Music (PDF) — Ángel Faraldo, Emilia Gómez, Sergi Jordà, and Perfecto Herrera, 2016.
From spectrum to key name
The documented front end uses 4,096-sample Hann-windowed frames with no overlap, up to 60 spectral peaks between 25 and 3,500 Hz, whitening, and a harmonic pitch-class profile. Four harmonic contributions have weights 1, 0.6, 0.36, and 0.22. Bins below 0.2 of each frame’s strongest bin are gated out. The averaged profile is compared using Pearson correlation against the edma templates. Results use rekordbox-compatible names such as Fm, Db, and F#m.
A small preference for minor. Not a guarantee.
The documented default applies PreferMinor with a bias of 0.1. It can tip a close major/minor decision, but it does not mean every track is minor or every changed result is correct. Listen to the blend as well as reading the label.
How this relates to the current analysis rules
This example explains the motivation for weighting the mixing sections. It does not establish that the current default automatically changes this track from Am to Dm.
The source also contains experimental BassRoot and BassVote rules, but they are not enabled in the documented default. Their test windows include the first and last 45 seconds, bar starts, and selected parts of beats or phrases. The reviewed docs and default rules do not establish a shipped first-and-last-24-bars fallback.
The test harness compares profiles and rule combinations, recording both improvements and regressions. In the recorded edma run, the minor bias fired on 51 tracks, fixed 44, and broke six. That is why these are measured rules, not guarantees.
Draw the music, without inventing labels.
The detail waveform has 150 columns per second, with low, mid, high, and overall peaks. The 1,200-bucket overview is calculated separately: bass RMS, mid/high energy, and per-band normalization give a more useful envelope than simply shrinking the detail peaks.
Waveform matching is an empirical approximation, not byte-identical rekordbox processing. Calibration used nine reference tracks; it was not a held-out accuracy test. Most measured shapes improved, but one track’s absolute-height error increased. Existing tracks need waveform regeneration to receive the updated output.
Phrase starts versus phrase detection
The downbeat stage can produce internal section-boundary candidates from strong four-bar changes on downbeats. This does not provide labeled intro, verse, chorus, or outro sections. The phrase-label and vocal analyzers are unimplemented stubs; the writer omits those tags instead of inventing results. The app does not offer phrase, vocal, or automatic-cue analysis.
What has actually been measured.
There are three distinct kinds of evidence. A synthetic timing test, a comparison with a hand-checked library, and a real edit loaded into rekordbox answer different questions. Their results should not be combined into one accuracy promise.
Real-track reference baseline
The reference playlist contains 155 tracks in 4/4, spanning 123–178 BPM. These recorded results predate the transient-emphasis fallback and have not been remeasured for that change.
| Measure | Pass condition | Passed |
|---|---|---|
| BPM | Within 0.05 BPM | 155 / 155 |
| Downbeat | Within 25 ms, modulo a bar | 143 / 155 |
| Full grid | 98% of reference beats within 25 ms, same number | 142 / 155 |
| Key | Same key name as the reference | 141 / 155 |
The 99% figure in the engineering docs is a target, not an achieved result across every metric. Key agreement is agreement with the reference label, not proof of the only musically valid answer.
Known disagreements
Eleven older rekordbox 6 grids sit about 25 ms after the kick. Other differences include an early downbeat choice and hand grids that hold a tempo where rbxport follows a slowdown. Documentation reports also differ in their rekordbox-7-only subset counts, so this guide does not use that subset as a headline score.
Saved synthetic grids
Seven two-minute fixtures cover a steady tempo, upward and downward cuts, a mid-bar change, linear ramps, and a curved ramp. The documented saved-grid run matched all 2,103 ticks within 2 ms, with no extra markers, correct numbering, and an exact-zero first marker. Worst error across those cases was 1.938 ms.
Separate regressions cover quiet transitions, release tails, silence, and preserving kick timestamps. The later fallback run records 41 passing unit and integration tests and a clean lint check. Those tests do not refresh existing library grids or replace a new real-track comparison.
Nine real DJ edits
The older multi-tempo baseline passed BPM and key on 9/9 edits, downbeat on 8/9, and the strict full-grid metric on 4/9. Seven of ten tempo changes were within 3 ms. The difficult cuts were hand-placed at an early impact, well before the new kick pattern arrived. The newer fallback has not been shown by a fresh playlist score to fix those misses.
How the validation tools work
The golden harness caches decoded audio and reference grids, then scores candidate analysis without writing to the library. Specialized runs isolate downbeat decisions, key profiles, and bass rules. The multi-tempo rig instead imports copies, writes analysis files, and checks whether the grids survive loading in rekordbox. Its recorded format observations are specific to that rig and version, not a universal compatibility guarantee.
The synthetic fixtures use sample-exact timestamps generated independently of the analyzer. The checker reads persisted grids back from the app and requires a correctly numbered marker within 2 ms of every tick, with no extras. Rebuilding alone does not update saved grids; tracks must be analyzed again.
Use the grid. Check the music.
- The engine assumes 4/4 and is tuned to electronic music; the reference set is not evidence for every genre or meter.
- Ambiguous percussion, long beatless transitions, and creative edits can produce different valid interpretations.
- Whole-number snapping applies only to nearby steady tempos, not every measured interval.
- Key detection supplies a useful label, not a substitute for listening.
- Internal phrase boundaries are not user-facing phrase labels, vocal detection, or stems.
After analysis, check the first downbeat, a later steady section, and any transition. Preview the tracks you intend to blend. If a case looks wrong, use the app’s Report bug action and describe the section and expected behavior.
About this guide.
This guide summarizes the analysis source code in rbx. You can explore the code and implementation details on GitHub ↗.
Figures are explanatory schematics, not captured track measurements. Reported test results come from the project’s recorded benchmarks; no new benchmark was run for this page.