Files
stemengine_old/backend/services/audio_analysis_service.py

127 lines
5.3 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""
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 {}