audio_features.py

Version: 1.0.1 (2026-09-28). Used by AudioProcessor.py 1.1.0 and later.

This module takes signal measurements from audio that AudioProcessor has already decoded (mono float32, 48 kHz). It uses numpy only and loads no model.

Function	Returns	Method
estimate_bpm(x)	(bpm, confidence)	Autocorrelation of a spectral-flux onset envelope, for both the kick band (<250 Hz) and the full band, keeping the clearer. Uses a mild prior around 122 BPM and folds into 70–180
estimate_key(x)	(key, confidence)	Chroma (12 kHz copy, 8192-point FFT, median over time so kicks don't dominate), correlated with the Krumhansl–Kessler major and minor profiles
level_db(x)	dBFS	RMS level
file_loudness(path)	(LUFS, LRA)	ffmpeg ebur128 filter over the whole file
find_changes(windows)	[start s]	Flags a window where at least two of these change: tempo (by 3 BPM or more), key, or tag overlap (below 34%). Since v1.0.1 a change must also be at least 120 s after the last one kept, so a DJ blend spanning several windows counts once
summarise(...)	item summary	median and range of BPM, main key, mean level, LUFS/LRA, changes

Self-test

python3 audio_features.py --selftest runs these checks on synthetic audio:

• 11 tempos between 86 and 174 BPM
• 5 keys
• 3 tempos buried in heavy noise
• white noise, which must return no BPM

It prints PASS or FAIL.

Limits

• Half or double tempo: some material reads at half or double the real tempo. Fast drum & bass can show as about 87.
• Beatless material: returns no BPM rather than a guess.
• Key on percussive or atonal passages: often returns no key.
• Track changes: approximate, not a cue sheet.