Lumlux Art Lab — BPM & Key Detector
User guide and how to read the results
1. What this is
A single HTML file that runs in your browser. Your audio goes nowhere: the file is decoded, analysed and forgotten locally, and none of it survives closing the page. No server, no account, no storage. Works standalone and inside an iframe.
What it does: find the tempo, lay beats and bar lines over the waveform, estimate the key including how it changes over time, and export all of that.
What it does not do: pronounce verdicts. It is a measuring instrument that shows its own uncertainty, and it is your job to decide whether to trust a reading. The whole interface is built around that — hence the confidence scale, the alternative tempo and the top 3 for key.
2. Getting audio in
Three ways:
- Choose audio file — pick a file.
- Drag and drop — drop the file onto the waveform.
- Record from microphone — capture live. The level meter runs while recording; click again to stop and the recording is analysed immediately.
Clear returns everything to the empty state.
Analysis starts automatically as soon as there is audio. You can always interrupt it with Stop analysis.
Formats
WAV, MP3 and M4A/AAC work everywhere. OGG, FLAC and Opus work in Chrome and Firefox but not in Safari, which refuses them through the Web Audio API. If you get a codec error, that is the browser rather than a bug — convert to WAV or M4A.
If a WAV file is rejected, it is usually an unusual bit depth. Re-export as 16-bit or 32-bit float PCM.
3. The readout plate
Three panels. This is where you spend most of your time.
Tempo
The large number, to two decimals. That precision is not decoration: the difference between 128.00 and 128.04 adds up to twelve seconds of drift over a five-minute track, and you will hear it.
Below it: how many beats were found, or a note that the value is manual.
Alternative appears when there is a serious half- or double-time candidate. This is the honesty button. A track at 87 BPM and a track at 174 BPM have literally the same beat positions — which of the two is “true” is a musical judgement, not a measurement. If the grid feels twice as fast or slow as you expect, click the alternative.
Key
The key with its Camelot code in the box beside it, and the tuning in cents underneath.
A WEAK flag means the tool has a best guess but does not trust it. See §7.
MANUAL means you are looking at your own choice, not a measurement.
Confidence
The stepped bar scale and the word below it describe the tempo, not the key. Key confidence is the separate percentage underneath.
| Word | Range | Meaning |
|---|---|---|
| strong | 70–100% | The grid is almost certainly right. Only check you are not in half or double time. |
| usable | 45–70% | Workable, but play it back with the click on and listen. |
| weak | 0–45% | Do not rely on it. A notice appears with the likely reason. |
The score combines three things with different weights: how sharp the peak in the tempogram is (38%), how evenly spaced the detected beats are (32%), and what fraction of those beats actually land on an audible onset (30%). That last term is what stops loose, breathing performances from scoring well purely because the arithmetic works out.
4. The waveform
Layers
Three toggles:
- Beat grid — thin blue lines on every beat. It hides itself automatically when you zoom out far enough that it would become a solid blue field.
- Downbeats — heavy lines with bar numbers on the first beat of each bar.
- Key track — the coloured strip below the waveform. Blues are major, ambers are minor, and each key gets its own shade. A colour change is a modulation.
Selection
Drag across the waveform to choose a region. Everything outside it dims and the edges turn amber. Analyse selection processes only that part.
This is the most useful tool you have. An intro without drums, a breakdown, an outro drowning in reverb — all poison for tempo detection. Select twenty seconds where the full arrangement is playing and you will almost always get a clean result.
Select whole file puts it back.
A single click without dragging moves the playhead.
The GRID strip
The narrow band across the top of the waveform. Drag inside it to slide the whole grid in time. Useful when the tempo is right but the first beat sits in the wrong place.
Zoom
Zoom in / Zoom out / Fit, or scroll on the waveform. Shift plus scroll pans horizontally. Zoomed in far enough, the waveform is drawn sample by sample so you can see exactly where the transient starts.
5. Playback and verification
Play starts from the playhead. Click on beats toggles the metronome — a higher click on the downbeat, a lower one on the rest.
This is the only real verification that exists. Turn the click on, listen for thirty seconds, and hear whether it drifts. If it drifts, the tempo is slightly off. If it sits consistently beside the hits, the phase is off. If the accented click lands on the wrong beat of the bar, the downbeat is off. All three are corrected separately.
6. Correcting the tempo by hand
Tap tempo
Click Tap or hit the space bar in time. An estimate appears from three taps onward. The tool keeps the last eight taps, discards any interval more than 30% away from the median, and averages the rest — so one fumbled tap does not ruin the reading. Use tapped tempo adopts it.
More than eight taps adds nothing. Three seconds of silence starts a fresh series.
BPM
Type a value, or use the steps: ±1 when you are far off, ±0.1 to get close, ±0.01 to settle it. ×0.5 and ×2 for half and double time.
Grid phase
The buttons shift the grid by 1 or 10 samples. That is not precision for its own sake: at 44.1 kHz one sample is 23 microseconds and ten samples are 0.23 milliseconds — the difference between a grid sitting exactly on the transient and one sitting just past it. The line underneath shows the offset in both milliseconds and samples.
First downbeat at selection start puts the first bar line at the start of your selection. Faster than dragging when you know exactly where bar 1 begins.
Time signature
4/4 by default. Force 3/4 or 6/8 when the tool gets it wrong. This re-runs the analysis, because both the bar lines and the key analysis windows depend on it.
Reset
Reset to detection, or the R key, discards every manual value — tempo, phase, time signature, key, taps — and returns to the measurement.
7. Reading the key
The top 3
Three candidates with their correlation scores. The score is a Pearson correlation between the measured chromagram and a tone profile: 1.0 is perfect, 0 is chance.
Pay attention to the gap between first and second place. Below 0.05 the tool says so explicitly: this is a coin toss, decide by ear.
Three classic confusions exist, and the tool names them when they occur:
- Relative — A minor and C major contain exactly the same notes. Only the centre of gravity differs. Statistics can barely resolve this; you will hear it in two seconds.
- Parallel — C major and C minor, same tonic.
- Fifth — C and G, one accidental apart.
Rules of thumb for the correlation score
| Score | Reading |
|---|---|
| above 0.75 | Strong. Usually simply correct. |
| 0.55 – 0.75 | Reasonable. Check that number two is not the relative key. |
| 0.35 – 0.55 | Weak. Often dense productions or heavy percussion. |
| below 0.35 | No meaningful result. |
WEAK / no clear tonality
Appears when the correlation is low and the chromagram is close to flat. Normal for drum loops, noise and atonal material.
The best guess stays on screen, labelled. That is deliberate: hiding a result is not honesty, it is just less information.
If this fires on music that obviously has a key, you are probably analysing a section without harmony — a drum intro, a breakdown, a percussive outro. Select a passage with chords in it.
Tone profile
Four profiles, all published measurement sets rather than invented numbers:
- Krumhansl-Kessler — the standard, derived from listening experiments on classical material. Good all-rounder.
- Temperley (1999) — revised version, slightly less sensitive to sustained tones.
- Sha’ath — from KeyFinder, tuned for modern productions.
- EDMA — derived from a large collection of dance music. Try this one when the other three give odd answers on house or techno.
Switching re-runs the key stage. If two profiles agree, that is a stronger signal than one high correlation.
Tuning
Deviation from A = 440 Hz, in cents. Anything within ±5 cents is noise. A track sitting consistently at +30 cents was either recorded at a different pitch standard or transposed afterwards — worth knowing before you put it next to other material.
Analysis window and Key segments
The window is normally 8 bars with a hop of 1 bar. Without a usable beat grid the tool falls back to 10 seconds with a hop of 2.5 seconds.
The segment count is the number of contiguous stretches sharing a key after smoothing. One segment means no modulation was found. Fifteen segments across a three-minute track usually does not mean fifteen modulations — it means the chromagram is uncertain.
Override
If you know the key, pick it under Override global key. Everything follows — wheel, mix list, exports, key track — and is marked as manual.
8. The Camelot wheel
Outer ring B is major, inner ring A is minor. Blue is the current key, pale blue the mixable neighbours, amber the energy boost.
Four positions work:
- Same number, other ring — the relative key. The smoothest transition available.
- One step back — one accidental fewer.
- One step forward — one accidental more.
- Two steps forward — the energy boost. A bigger musical jump, but it lifts a set.
Below that, the mixable tempo range at ±6% and ±8%. Watch what that does harmonically. Pitching by roughly 6% is a semitone, so at the edge of that range your key has moved a step and your Camelot number no longer matches what comes out of the speakers. With time-stretching that preserves pitch, this does not apply.
9. Exporting
- Copy summary line — one line to the clipboard:
128.02 BPM — A minor (8A) — tuning +3 cents - Key track (CSV) —
start_sec,end_sec,bar,key,camelot,confidence,manual - Beats & downbeats (CSV) —
index,time_sec,is_downbeat,bar,manual - Beat times (TXT) — bare times to six decimals, downbeats listed separately below
- Full analysis (JSON) — everything: settings, candidates, correlations, segments, beat times
Six decimals is microsecond resolution, comfortably enough to place markers in a DAW without audible drift.
Every manual adjustment is marked manual in every format. Six months from now you will still know whether a value was measured or chosen.
10. Keyboard
| Key | Action |
|---|---|
Space | tap tempo |
Enter | play / pause |
[ ] | shift the grid one sample |
- = | BPM ±0.01 |
H | half tempo |
D | double tempo |
R | back to the detection |
11. When it goes wrong
Tempo half or double ? click the alternative on the readout plate, or use H / D.
Tempo right, grid misplaced ? drag in the GRID strip, or use [ and ].
Bar line on the wrong beat ? use First downbeat at selection start after selecting from exactly bar 1.
Grid slowly drifts away ? the tempo is a fraction off. Go to the end of the track, see how far the click has wandered, and correct in steps of ±0.01.
Weak confidence ? select a passage with clear drums. If that does not help, the track probably has no steady pulse, and tap tempo is the only honest method left.
Key a fifth or a third off ? check the top 3; the right answer is almost always in there. Try a different profile.
Analysis is slow ? a notice appears if the browser blocks background workers. The analysis then runs on the main thread in small blocks: slower, same result.
Fragment shorter than 8 seconds ? a warning appears. Below that threshold there simply is not enough material to base a tempo on; treat the number as indicative.
12. Under the hood
For anyone who wants to know where the numbers come from.
Tempo. The audio is mixed to mono at 11025 Hz. An FFT of 512 with a hop of 128 gives 86.13 frames per second. Each frame’s spectrum is summarised into 40 logarithmically spaced bands and compressed with log(1 + 1000·m); the positive part of the difference between consecutive frames is the onset function. A running mean over ±0.4 seconds is subtracted from it.
An autocorrelation runs over that function across 60 to 200 BPM, weighted by a log-normal preference curve centred on 125 BPM. The highest peak alone is not enough: every local maximum is collected, the three strongest serve as seeds, and each seed is evaluated at the musical ratios 1/3, 1/2, 2/3, 3/4, 1, 4/3, 3/2, 2 and 3 using a pulse train over the onset function. Testing octaves alone was not sufficient — on some tracks that left the tool locked onto a non-metrical neighbour such as 4/3 of the real tempo.
The beats themselves come from a dynamic-programming tracker in the style of Ellis, weighing onset strength against regularity. The final number is a least-squares fit through all detected beats, not the raw peak.
Key. A separate branch at 22050 Hz, FFT of 8192 with a hop of 2048. Harmonic and percussive content are separated with median filters along the time and frequency axes respectively, followed by a soft mask. This happens only in the C2 to C7 band, because outside it nothing contributes to the key and everything costs time.
Spectral peaks are found in the harmonic part using parabolic interpolation. Each peak counts towards its own fundamental and towards the possibility that it is the second, third or fourth harmonic of a lower note, with decreasing weight. The tuning comes from how those peaks deviate from equal temperament, as a circular mean within ±50 cents.
The corrected chromagram is correlated per window against 24 rotated tone profiles. Viterbi smoothing with a switching penalty turns that into a key track that does not flicker. The global key is the energy-weighted most common state in that smoothed track.
Thresholds. The line between “key” and “no clear tonality” was measured rather than chosen: tonal material lands around correlation 0.83 at a spectral flatness of 0.79, while drums and white noise land around 0.39 at 0.99. The rule is correlation above 0.55, or above 0.32 provided flatness stays below 0.97.
13. What you should know before trusting it
Tested with synthetic audio in a test harness: tempo detection across 63 to 174 BPM, half and double time handling, tuning detection, key classification with all four profiles, modulation detection, and the separation between tonal and atonal material.
Not tested in a real browser: the fallback to the main thread under a strict security policy, microphone recording through AudioWorklet, drag and drop, and behaviour inside an iframe. Test those four yourself before putting the tool somewhere permanent.