127 lines
5.3 KiB
Python
127 lines
5.3 KiB
Python
"""
|
||
Audio feature analysis service — BPM and musical key.
|
||
|
||
Uses librosa for all audio processing. To keep latency low the analysis
|
||
window is capped at MAX_ANALYSIS_SECONDS (90 s by default). Results are
|
||
returned as a plain dict and are designed to be cached in project.json under
|
||
the ``audio_features`` key.
|
||
|
||
Key-finding algorithm:
|
||
Krumhansl-Schmuckler (1990) — compare the mean chromagram of the excerpt
|
||
against the major and minor key profiles for all 12 pitch classes and pick
|
||
the best-correlating one. Confidence is the normalised Pearson r value in
|
||
[0, 1], where 1 means a perfect match.
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
import logging
|
||
from pathlib import Path
|
||
|
||
import librosa
|
||
import numpy as np
|
||
|
||
log = logging.getLogger(__name__)
|
||
|
||
# ─── Constants ─────────────────────────────────────────────────────────────────
|
||
|
||
MAX_ANALYSIS_SECONDS: float = 90.0
|
||
SAMPLE_RATE: int = 22_050 # librosa default; good balance of speed vs quality
|
||
|
||
# Krumhansl-Schmuckler key profiles (Krumhansl 1990, Table 2)
|
||
_KS_MAJOR = np.array([6.35, 2.23, 3.48, 2.33, 4.38, 4.09,
|
||
2.52, 5.19, 2.39, 3.66, 2.29, 2.88])
|
||
_KS_MINOR = np.array([6.33, 2.68, 3.52, 5.38, 2.60, 3.53,
|
||
2.54, 4.75, 3.98, 2.69, 3.34, 3.17])
|
||
|
||
# MIDI pitch-class → note name (enharmonic equivalents use sharps)
|
||
_NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
|
||
|
||
# ─── Internal helpers ──────────────────────────────────────────────────────────
|
||
|
||
def _ks_key(chroma_mean: np.ndarray) -> tuple[str, str, float]:
|
||
"""
|
||
Krumhansl-Schmuckler key-finding.
|
||
|
||
Returns (note_name, mode, confidence) where confidence ∈ [0, 1].
|
||
"""
|
||
best_pitch = 0
|
||
best_mode = "major"
|
||
best_r = -2.0
|
||
|
||
for pitch in range(12):
|
||
rotated = np.roll(chroma_mean, -pitch)
|
||
r_major = float(np.corrcoef(rotated, _KS_MAJOR)[0, 1])
|
||
r_minor = float(np.corrcoef(rotated, _KS_MINOR)[0, 1])
|
||
if r_major > best_r:
|
||
best_r, best_pitch, best_mode = r_major, pitch, "major"
|
||
if r_minor > best_r:
|
||
best_r, best_pitch, best_mode = r_minor, pitch, "minor"
|
||
|
||
# Normalise raw Pearson r ∈ [-1, 1] to confidence ∈ [0, 1]
|
||
confidence = (best_r + 1.0) / 2.0
|
||
return _NOTE_NAMES[best_pitch], best_mode, round(confidence, 4)
|
||
|
||
|
||
# ─── Public API ────────────────────────────────────────────────────────────────
|
||
|
||
def analyze_audio_features(
|
||
source_path: Path | str,
|
||
max_duration: float = MAX_ANALYSIS_SECONDS,
|
||
) -> dict:
|
||
"""
|
||
Analyze BPM and musical key for an audio file.
|
||
|
||
Returns a dict:
|
||
{
|
||
"bpm": 128.0, # float, rounded to 1 dp
|
||
"key": "F# minor", # human-readable
|
||
"key_note": "F#", # pitch class
|
||
"key_mode": "minor", # "major" | "minor"
|
||
"key_confidence": 0.87 # 0–1 float
|
||
"analysis_duration_seconds": 87.4
|
||
}
|
||
Returns an empty dict on failure so callers can treat it as non-fatal.
|
||
"""
|
||
source_path = Path(source_path)
|
||
if not source_path.exists():
|
||
log.warning("audio_analysis: file not found: %s", source_path)
|
||
return {}
|
||
|
||
try:
|
||
log.debug("audio_analysis: loading %s (max %.0f s)", source_path.name, max_duration)
|
||
y, sr = librosa.load(str(source_path), sr=SAMPLE_RATE, mono=True, duration=max_duration)
|
||
|
||
actual_duration = round(float(len(y)) / sr, 2)
|
||
|
||
# ── BPM ──────────────────────────────────────────────────────────────
|
||
# Use onset strength envelope + beat tracker for robustness on pop/RnB.
|
||
onset_env = librosa.onset.onset_strength(y=y, sr=sr)
|
||
# beat_track returns (tempo_array, beat_frames)
|
||
tempo_arr, _ = librosa.beat.beat_track(onset_envelope=onset_env, sr=sr)
|
||
# librosa ≥0.10 returns a scalar ndarray; earlier versions return float
|
||
bpm = float(np.atleast_1d(tempo_arr)[0])
|
||
bpm = round(bpm, 1)
|
||
|
||
# ── Key ───────────────────────────────────────────────────────────────
|
||
# CQT-based chromagram for better pitch accuracy than STFT chroma.
|
||
chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
|
||
chroma_mean = np.mean(chroma, axis=1) # shape (12,)
|
||
note, mode, confidence = _ks_key(chroma_mean)
|
||
key_str = f"{note} {mode}"
|
||
|
||
result = {
|
||
"bpm": bpm,
|
||
"key": key_str,
|
||
"key_note": note,
|
||
"key_mode": mode,
|
||
"key_confidence": confidence,
|
||
"analysis_duration_seconds": actual_duration,
|
||
}
|
||
log.info("audio_analysis: %s → BPM=%.1f key=%s (conf=%.2f)",
|
||
source_path.name, bpm, key_str, confidence)
|
||
return result
|
||
|
||
except Exception as exc:
|
||
log.warning("audio_analysis: failed for %s — %s", source_path, exc)
|
||
return {}
|