feat: add exact 26-feature audio extraction pipeline

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

bitcheck-audio-service/app/services/audio_feature_extractor.py

@@ -0,0 +1,166 @@
+import logging
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+FEATURE_NAMES = [
+    "chroma_stft",
+    "rms",
+    "spectral_centroid",
+    "spectral_bandwidth",
+    "rolloff",
+    "zero_crossing_rate",
+    "mfcc1",
+    "mfcc2",
+    "mfcc3",
+    "mfcc4",
+    "mfcc5",
+    "mfcc6",
+    "mfcc7",
+    "mfcc8",
+    "mfcc9",
+    "mfcc10",
+    "mfcc11",
+    "mfcc12",
+    "mfcc13",
+    "mfcc14",
+    "mfcc15",
+    "mfcc16",
+    "mfcc17",
+    "mfcc18",
+    "mfcc19",
+    "mfcc20",
+]
+
+
+@dataclass
+class AudioFeatureResult:
+    checked: bool = True
+    features_found: bool = False
+    feature_count: int = 0
+    feature_names: list = field(default_factory=lambda: FEATURE_NAMES)
+    features: Optional[dict] = None
+    warnings: list = field(default_factory=list)
+    error: str = ""
+
+
+def extract_features(
+    audio_path: str,
+    sr: int = 22050,
+    return_features: bool = False,
+) -> AudioFeatureResult:
+    """Extract the exact 26 features expected by the BitCheck Random Forest model."""
+    warnings: list = []
+
+    # --- Load normalized audio ---
+    try:
+        import librosa
+        y, _sr = librosa.load(audio_path, sr=sr, mono=True)
+    except Exception as e:
+        return AudioFeatureResult(
+            checked=True,
+            features_found=False,
+            error=f"Could not load audio for feature extraction: {e}",
+            warnings=[f"librosa load failed: {e}"],
+        )
+
+    if len(y) < sr * 0.01:
+        warnings.append("Audio is extremely short for reliable feature extraction.")
+
+    # --- Compute features ---
+    sanitized_count = 0
+
+    def _safe_mean(values: np.ndarray, name: str) -> float:
+        nonlocal sanitized_count
+        m = np.nanmean(values)
+        if np.isnan(m) or np.isinf(m):
+            sanitized_count += 1
+            logger.warning("Feature %s was NaN/inf, replacing with 0", name)
+            return 0.0
+        return float(m)
+
+    try:
+        chroma = librosa.feature.chroma_stft(y=y, sr=_sr)
+        chroma_mean = _safe_mean(chroma, "chroma_stft")
+
+        rms = librosa.feature.rms(y=y)
+        rms_mean = _safe_mean(rms, "rms")
+
+        centroid = librosa.feature.spectral_centroid(y=y, sr=_sr)
+        centroid_mean = _safe_mean(centroid, "spectral_centroid")
+
+        bandwidth = librosa.feature.spectral_bandwidth(y=y, sr=_sr)
+        bandwidth_mean = _safe_mean(bandwidth, "spectral_bandwidth")
+
+        rolloff = librosa.feature.spectral_rolloff(y=y, sr=_sr)
+        rolloff_mean = _safe_mean(rolloff, "rolloff")
+
+        zcr = librosa.feature.zero_crossing_rate(y)
+        zcr_mean = _safe_mean(zcr, "zero_crossing_rate")
+
+        mfcc = librosa.feature.mfcc(y=y, sr=_sr, n_mfcc=20)
+    except Exception as e:
+        return AudioFeatureResult(
+            checked=True,
+            features_found=False,
+            error=f"Feature extraction failed: {e}",
+            warnings=[f"Feature computation error: {e}"],
+        )
+
+    mfcc_means = [_safe_mean(mfcc[i], f"mfcc{i+1}") for i in range(20)]
+
+    features = {
+        "chroma_stft": round(chroma_mean, 10),
+        "rms": round(rms_mean, 10),
+        "spectral_centroid": round(centroid_mean, 10),
+        "spectral_bandwidth": round(bandwidth_mean, 10),
+        "rolloff": round(rolloff_mean, 10),
+        "zero_crossing_rate": round(zcr_mean, 10),
+        "mfcc1": round(mfcc_means[0], 10),
+        "mfcc2": round(mfcc_means[1], 10),
+        "mfcc3": round(mfcc_means[2], 10),
+        "mfcc4": round(mfcc_means[3], 10),
+        "mfcc5": round(mfcc_means[4], 10),
+        "mfcc6": round(mfcc_means[5], 10),
+        "mfcc7": round(mfcc_means[6], 10),
+        "mfcc8": round(mfcc_means[7], 10),
+        "mfcc9": round(mfcc_means[8], 10),
+        "mfcc10": round(mfcc_means[9], 10),
+        "mfcc11": round(mfcc_means[10], 10),
+        "mfcc12": round(mfcc_means[11], 10),
+        "mfcc13": round(mfcc_means[12], 10),
+        "mfcc14": round(mfcc_means[13], 10),
+        "mfcc15": round(mfcc_means[14], 10),
+        "mfcc16": round(mfcc_means[15], 10),
+        "mfcc17": round(mfcc_means[16], 10),
+        "mfcc18": round(mfcc_means[17], 10),
+        "mfcc19": round(mfcc_means[18], 10),
+        "mfcc20": round(mfcc_means[19], 10),
+    }
+
+    if sanitized_count > 0:
+        warnings.append(f"{sanitized_count} feature(s) were sanitized (NaN/inf replaced with 0).")
+
+    logger.info(
+        "Extracted %d features, sanitized=%d",
+        len(features), sanitized_count,
+    )
+
+    result = AudioFeatureResult(
+        checked=True,
+        features_found=True,
+        feature_count=len(features),
+        feature_names=FEATURE_NAMES,
+        features=features if return_features else None,
+        warnings=warnings,
+    )
+    return result
+
+
+def features_to_dataframe(features: dict):
+    """Convert a feature dict to a 1-row pandas DataFrame with correct column order."""
+    import pandas as pd
+    return pd.DataFrame([features], columns=FEATURE_NAMES)

bitcheck-audio-service/tests/test_audio_features.py

@@ -0,0 +1,104 @@
+import wave
+import numpy as np
+import pytest
+
+from app.services.audio_feature_extractor import (
+    extract_features,
+    FEATURE_NAMES,
+    features_to_dataframe,
+    AudioFeatureResult,
+)
+
+
+def _make_wav(path: str, duration_ms: int = 2000, sr: int = 22050, amp: float = 0.3):
+    num_samples = int(sr * duration_ms / 1000)
+    t = np.linspace(0, duration_ms / 1000, num_samples, endpoint=False)
+    y = (np.sin(2 * np.pi * 440 * t) * amp).astype(np.float32)
+    y_int = (y * 32767).astype(np.int16)
+    with wave.open(path, "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(sr)
+        wf.writeframes(y_int.tobytes())
+
+
+def _make_silent_wav(path: str, duration_ms: int = 1000, sr: int = 22050):
+    num_samples = int(sr * duration_ms / 1000)
+    with wave.open(path, "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(sr)
+        wf.writeframes(b"\x00" * num_samples * 2)
+
+
+def test_extractor_returns_exactly_26_features(tmp_path):
+    wav_path = tmp_path / "test.wav"
+    _make_wav(str(wav_path))
+    result = extract_features(str(wav_path))
+    assert result.features_found is True
+    assert result.feature_count == 26
+
+
+def test_feature_names_match_expected(tmp_path):
+    wav_path = tmp_path / "test.wav"
+    _make_wav(str(wav_path))
+    result = extract_features(str(wav_path))
+    assert result.feature_names == FEATURE_NAMES
+    assert len(result.feature_names) == 26
+
+
+def test_non_silent_audio_produces_nonzero_features(tmp_path):
+    wav_path = tmp_path / "tone.wav"
+    _make_wav(str(wav_path), amp=0.5)
+    result = extract_features(str(wav_path), return_features=True)
+    assert result.features is not None
+    assert result.features["rms"] > 0.001
+    # Spectral centroid of a 440 Hz tone should be around 440
+    assert result.features["spectral_centroid"] > 100
+
+
+def test_silent_audio_does_not_crash(tmp_path):
+    wav_path = tmp_path / "silent.wav"
+    _make_silent_wav(str(wav_path))
+    result = extract_features(str(wav_path), return_features=True)
+    assert result.features_found is True
+    assert result.feature_count == 26
+    # All features should be finite
+    for name in FEATURE_NAMES:
+        val = result.features[name]
+        assert not np.isnan(val), f"{name} is NaN"
+        assert not np.isinf(val), f"{name} is inf"
+
+
+def test_return_features_false_hides_raw_features(tmp_path):
+    wav_path = tmp_path / "test.wav"
+    _make_wav(str(wav_path))
+    result = extract_features(str(wav_path), return_features=False)
+    assert result.features_found is True
+    assert result.features is None
+
+
+def test_return_features_true_includes_raw_features(tmp_path):
+    wav_path = tmp_path / "test.wav"
+    _make_wav(str(wav_path))
+    result = extract_features(str(wav_path), return_features=True)
+    assert result.features is not None
+    assert len(result.features) == 26
+    for name in FEATURE_NAMES:
+        assert name in result.features
+
+
+def test_corrupt_file_handled(tmp_path):
+    bad_path = tmp_path / "bad.wav"
+    bad_path.write_bytes(b"\x00" * 10)
+    result = extract_features(str(bad_path))
+    assert result.checked is True
+    # Should either find no features or fail gracefully
+    assert isinstance(result, AudioFeatureResult)
+
+
+def test_features_to_dataframe_has_correct_shape():
+    features = {name: 0.0 for name in FEATURE_NAMES}
+    df = features_to_dataframe(features)
+    assert df.shape == (1, 26)
+    assert list(df.columns) == FEATURE_NAMES