feat: chromagram extractor — chroma CQT mean, L1-normalized

app/services/chromagram.py

@@ -0,0 +1,10 @@
+import numpy as np
+import librosa
+
+
+def extract_chroma_mean(y: np.ndarray, sr: int, hop_length: int = 512) -> np.ndarray:
+    """Extract mean chroma CQT vector (12,) for an audio chunk, L1-normalized."""
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr, hop_length=hop_length)
+    mean = chroma.mean(axis=1)
+    total = mean.sum()
+    return mean / total if total > 0 else mean

tests/test_chromagram.py

@@ -0,0 +1,21 @@
+import numpy as np
+from app.services.chromagram import extract_chroma_mean
+
+def sine(freq, duration=2.0, sr=22050):
+    t = np.linspace(0, duration, int(sr * duration))
+    return np.sin(2 * np.pi * freq * t).astype(np.float32)
+
+def test_output_shape():
+    assert extract_chroma_mean(sine(440.0), sr=22050).shape == (12,)
+
+def test_output_is_normalized():
+    chroma = extract_chroma_mean(sine(440.0), sr=22050)
+    assert abs(chroma.sum() - 1.0) < 0.05
+
+def test_output_non_negative():
+    assert (extract_chroma_mean(sine(440.0), sr=22050) >= 0).all()
+
+def test_a440_peak_at_index_9():
+    # A = pitch class 9 (C=0 … A=9)
+    chroma = extract_chroma_mean(sine(440.0, duration=4.0), sr=22050)
+    assert np.argmax(chroma) == 9