BitCheck Dev Claude Opus 4.7 commited on
Commit ·
3739d3d
1
Parent(s): 349d719
feat: add audio preprocessing and normalization
Browse filesCo-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
bitcheck-audio-service/app/services/audio_preprocessor.py
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
import logging
|
| 2 |
+
import subprocess
|
| 3 |
+
import uuid
|
| 4 |
+
from dataclasses import dataclass, field
|
| 5 |
+
from pathlib import Path
|
| 6 |
+
from typing import Optional
|
| 7 |
+
|
| 8 |
+
import numpy as np
|
| 9 |
+
|
| 10 |
+
from app.config import TARGET_SAMPLE_RATE, MAX_AUDIO_DURATION_SECONDS, OUTPUT_DIR
|
| 11 |
+
|
| 12 |
+
logger = logging.getLogger(__name__)
|
| 13 |
+
|
| 14 |
+
|
| 15 |
+
@dataclass
|
| 16 |
+
class AudioPreprocessResult:
|
| 17 |
+
checked: bool = True
|
| 18 |
+
status: str = ""
|
| 19 |
+
target_sample_rate: int = TARGET_SAMPLE_RATE
|
| 20 |
+
mono: bool = True
|
| 21 |
+
duration_used_seconds: float = 0.0
|
| 22 |
+
normalized_audio_path: str = ""
|
| 23 |
+
rms_energy: float = 0.0
|
| 24 |
+
warnings: list = field(default_factory=list)
|
| 25 |
+
error: str = ""
|
| 26 |
+
|
| 27 |
+
|
| 28 |
+
def preprocess_audio(
|
| 29 |
+
filepath: str,
|
| 30 |
+
max_duration: float = MAX_AUDIO_DURATION_SECONDS,
|
| 31 |
+
target_sr: int = TARGET_SAMPLE_RATE,
|
| 32 |
+
is_video: bool = False,
|
| 33 |
+
output_dir: Optional[Path] = None,
|
| 34 |
+
) -> AudioPreprocessResult:
|
| 35 |
+
"""Normalize audio to mono WAV at target sample rate, truncated to max duration."""
|
| 36 |
+
warnings: list = []
|
| 37 |
+
out_dir = output_dir or OUTPUT_DIR
|
| 38 |
+
out_dir.mkdir(parents=True, exist_ok=True)
|
| 39 |
+
|
| 40 |
+
# --- Resolve input path for video files via ffmpeg ---
|
| 41 |
+
load_path = filepath
|
| 42 |
+
|
| 43 |
+
if is_video:
|
| 44 |
+
extracted = _extract_audio_with_ffmpeg(filepath, out_dir)
|
| 45 |
+
if extracted is None:
|
| 46 |
+
return AudioPreprocessResult(
|
| 47 |
+
checked=True,
|
| 48 |
+
status="failed",
|
| 49 |
+
error="Could not extract audio from video file.",
|
| 50 |
+
warnings=["ffmpeg audio extraction failed."],
|
| 51 |
+
)
|
| 52 |
+
load_path = extracted
|
| 53 |
+
warnings.append("Audio extracted from video container.")
|
| 54 |
+
|
| 55 |
+
# --- Load with librosa ---
|
| 56 |
+
try:
|
| 57 |
+
import librosa
|
| 58 |
+
y, sr = librosa.load(
|
| 59 |
+
load_path,
|
| 60 |
+
sr=target_sr,
|
| 61 |
+
mono=True,
|
| 62 |
+
duration=max_duration,
|
| 63 |
+
)
|
| 64 |
+
except Exception:
|
| 65 |
+
# Fallback: try converting to WAV with ffmpeg first, then load
|
| 66 |
+
converted = _convert_to_wav_ffmpeg(filepath, out_dir)
|
| 67 |
+
if converted is None:
|
| 68 |
+
return AudioPreprocessResult(
|
| 69 |
+
checked=True,
|
| 70 |
+
status="failed",
|
| 71 |
+
error="Could not load or convert audio file.",
|
| 72 |
+
warnings=["librosa load failed and ffmpeg conversion also failed."],
|
| 73 |
+
)
|
| 74 |
+
try:
|
| 75 |
+
import librosa
|
| 76 |
+
y, sr = librosa.load(
|
| 77 |
+
converted,
|
| 78 |
+
sr=target_sr,
|
| 79 |
+
mono=True,
|
| 80 |
+
duration=max_duration,
|
| 81 |
+
)
|
| 82 |
+
warnings.append("Audio required ffmpeg conversion before loading.")
|
| 83 |
+
except Exception:
|
| 84 |
+
return AudioPreprocessResult(
|
| 85 |
+
checked=True,
|
| 86 |
+
status="failed",
|
| 87 |
+
error="Could not load audio even after conversion.",
|
| 88 |
+
warnings=["All loading methods failed."],
|
| 89 |
+
)
|
| 90 |
+
|
| 91 |
+
duration_used = len(y) / sr if sr > 0 else 0.0
|
| 92 |
+
|
| 93 |
+
if duration_used < 0.05:
|
| 94 |
+
warnings.append("Audio is extremely short after preprocessing.")
|
| 95 |
+
|
| 96 |
+
# --- Compute RMS energy ---
|
| 97 |
+
rms = float(np.sqrt(np.mean(y ** 2))) if len(y) > 0 else 0.0
|
| 98 |
+
|
| 99 |
+
if rms < 1e-6:
|
| 100 |
+
warnings.append("Audio appears to be silent or nearly silent after preprocessing.")
|
| 101 |
+
|
| 102 |
+
# --- Save normalized WAV ---
|
| 103 |
+
output_name = f"{uuid.uuid4().hex}_normalized.wav"
|
| 104 |
+
output_path = out_dir / output_name
|
| 105 |
+
|
| 106 |
+
try:
|
| 107 |
+
import soundfile as sf
|
| 108 |
+
sf.write(str(output_path), y, target_sr, subtype="PCM_16")
|
| 109 |
+
except Exception:
|
| 110 |
+
return AudioPreprocessResult(
|
| 111 |
+
checked=True,
|
| 112 |
+
status="failed",
|
| 113 |
+
error="Could not write normalized WAV file.",
|
| 114 |
+
warnings=warnings + ["WAV write failed."],
|
| 115 |
+
)
|
| 116 |
+
|
| 117 |
+
logger.info(
|
| 118 |
+
"Preprocessed: path=%s duration=%.2fs sr=%d rms=%.6f",
|
| 119 |
+
output_name, duration_used, target_sr, rms,
|
| 120 |
+
)
|
| 121 |
+
|
| 122 |
+
return AudioPreprocessResult(
|
| 123 |
+
checked=True,
|
| 124 |
+
status="normalized",
|
| 125 |
+
target_sample_rate=target_sr,
|
| 126 |
+
mono=True,
|
| 127 |
+
duration_used_seconds=round(duration_used, 4),
|
| 128 |
+
normalized_audio_path=str(output_path),
|
| 129 |
+
rms_energy=round(rms, 6),
|
| 130 |
+
warnings=warnings,
|
| 131 |
+
)
|
| 132 |
+
|
| 133 |
+
|
| 134 |
+
def _extract_audio_with_ffmpeg(filepath: str, out_dir: Path) -> Optional[str]:
|
| 135 |
+
"""Extract audio track from video using ffmpeg. Returns path or None."""
|
| 136 |
+
import shutil
|
| 137 |
+
if not shutil.which("ffmpeg"):
|
| 138 |
+
logger.warning("ffmpeg not available for video audio extraction")
|
| 139 |
+
return None
|
| 140 |
+
output_name = f"{uuid.uuid4().hex}_extracted.wav"
|
| 141 |
+
output_path = out_dir / output_name
|
| 142 |
+
try:
|
| 143 |
+
subprocess.run(
|
| 144 |
+
[
|
| 145 |
+
"ffmpeg",
|
| 146 |
+
"-y",
|
| 147 |
+
"-i", filepath,
|
| 148 |
+
"-vn",
|
| 149 |
+
"-acodec", "pcm_s16le",
|
| 150 |
+
"-ar", "16000",
|
| 151 |
+
"-ac", "1",
|
| 152 |
+
str(output_path),
|
| 153 |
+
],
|
| 154 |
+
capture_output=True,
|
| 155 |
+
timeout=60,
|
| 156 |
+
check=True,
|
| 157 |
+
)
|
| 158 |
+
if output_path.exists() and output_path.stat().st_size > 44:
|
| 159 |
+
return str(output_path)
|
| 160 |
+
return None
|
| 161 |
+
except Exception as e:
|
| 162 |
+
logger.warning("ffmpeg audio extraction failed: %s", e)
|
| 163 |
+
return None
|
| 164 |
+
|
| 165 |
+
|
| 166 |
+
def _convert_to_wav_ffmpeg(filepath: str, out_dir: Path) -> Optional[str]:
|
| 167 |
+
"""Convert any audio file to WAV using ffmpeg. Returns path or None."""
|
| 168 |
+
import shutil
|
| 169 |
+
if not shutil.which("ffmpeg"):
|
| 170 |
+
return None
|
| 171 |
+
output_name = f"{uuid.uuid4().hex}_converted.wav"
|
| 172 |
+
output_path = out_dir / output_name
|
| 173 |
+
try:
|
| 174 |
+
subprocess.run(
|
| 175 |
+
[
|
| 176 |
+
"ffmpeg",
|
| 177 |
+
"-y",
|
| 178 |
+
"-i", filepath,
|
| 179 |
+
"-acodec", "pcm_s16le",
|
| 180 |
+
str(output_path),
|
| 181 |
+
],
|
| 182 |
+
capture_output=True,
|
| 183 |
+
timeout=60,
|
| 184 |
+
check=True,
|
| 185 |
+
)
|
| 186 |
+
if output_path.exists() and output_path.stat().st_size > 44:
|
| 187 |
+
return str(output_path)
|
| 188 |
+
return None
|
| 189 |
+
except Exception as e:
|
| 190 |
+
logger.warning("ffmpeg conversion failed: %s", e)
|
| 191 |
+
return None
|
bitcheck-audio-service/tests/test_audio_preprocessor.py
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
import io
|
| 2 |
+
import wave
|
| 3 |
+
|
| 4 |
+
import numpy as np
|
| 5 |
+
|
| 6 |
+
from app.services.audio_preprocessor import preprocess_audio, AudioPreprocessResult
|
| 7 |
+
|
| 8 |
+
|
| 9 |
+
def _make_wav_file(path: str, duration_ms: int = 2000, sample_rate: int = 44100, channels: int = 2):
|
| 10 |
+
num_samples = int(sample_rate * duration_ms / 1000)
|
| 11 |
+
with wave.open(path, "wb") as wf:
|
| 12 |
+
wf.setnchannels(channels)
|
| 13 |
+
wf.setsampwidth(2)
|
| 14 |
+
wf.setframerate(sample_rate)
|
| 15 |
+
# Generate a 440 Hz sine tone to be non-silent
|
| 16 |
+
t = np.linspace(0, duration_ms / 1000, num_samples, endpoint=False)
|
| 17 |
+
tone = (np.sin(2 * np.pi * 440 * t) * 0.3 * 32767).astype(np.int16)
|
| 18 |
+
wf.writeframes(tone.tobytes())
|
| 19 |
+
|
| 20 |
+
|
| 21 |
+
def _make_silent_wav(path: str, duration_ms: int = 1000, sample_rate: int = 22050):
|
| 22 |
+
num_samples = int(sample_rate * duration_ms / 1000)
|
| 23 |
+
with wave.open(path, "wb") as wf:
|
| 24 |
+
wf.setnchannels(1)
|
| 25 |
+
wf.setsampwidth(2)
|
| 26 |
+
wf.setframerate(sample_rate)
|
| 27 |
+
wf.writeframes(b"\x00" * num_samples * 2)
|
| 28 |
+
|
| 29 |
+
|
| 30 |
+
def test_can_normalize_sine_wav(tmp_path):
|
| 31 |
+
wav_path = tmp_path / "sine.wav"
|
| 32 |
+
_make_wav_file(str(wav_path), duration_ms=2000, sample_rate=44100, channels=2)
|
| 33 |
+
result = preprocess_audio(str(wav_path), output_dir=tmp_path)
|
| 34 |
+
assert result.checked is True
|
| 35 |
+
assert result.status == "normalized"
|
| 36 |
+
assert result.target_sample_rate == 22050
|
| 37 |
+
assert result.mono is True
|
| 38 |
+
assert result.duration_used_seconds > 0
|
| 39 |
+
assert result.normalized_audio_path
|
| 40 |
+
assert result.rms_energy > 0
|
| 41 |
+
|
| 42 |
+
|
| 43 |
+
def test_silent_audio_does_not_crash(tmp_path):
|
| 44 |
+
wav_path = tmp_path / "silent.wav"
|
| 45 |
+
_make_silent_wav(str(wav_path), duration_ms=1000)
|
| 46 |
+
result = preprocess_audio(str(wav_path), output_dir=tmp_path)
|
| 47 |
+
assert result.checked is True
|
| 48 |
+
assert result.status == "normalized"
|
| 49 |
+
assert any("silent" in w.lower() for w in result.warnings)
|
| 50 |
+
|
| 51 |
+
|
| 52 |
+
def test_output_path_is_relative_to_output_dir(tmp_path):
|
| 53 |
+
wav_path = tmp_path / "tone.wav"
|
| 54 |
+
_make_wav_file(str(wav_path))
|
| 55 |
+
out_dir = tmp_path / "outputs"
|
| 56 |
+
result = preprocess_audio(str(wav_path), output_dir=out_dir)
|
| 57 |
+
assert result.status == "normalized"
|
| 58 |
+
assert str(out_dir) in result.normalized_audio_path
|
| 59 |
+
assert result.normalized_audio_path.endswith("_normalized.wav")
|
| 60 |
+
|
| 61 |
+
|
| 62 |
+
def test_duration_truncation_works(tmp_path):
|
| 63 |
+
wav_path = tmp_path / "long.wav"
|
| 64 |
+
_make_wav_file(str(wav_path), duration_ms=5000, sample_rate=22050)
|
| 65 |
+
result = preprocess_audio(str(wav_path), max_duration=1.0, output_dir=tmp_path)
|
| 66 |
+
assert result.status == "normalized"
|
| 67 |
+
# Should be ~1 second, not 5
|
| 68 |
+
assert result.duration_used_seconds <= 1.1
|
| 69 |
+
|
| 70 |
+
|
| 71 |
+
def test_corrupt_file_returns_failed(tmp_path):
|
| 72 |
+
bad_path = tmp_path / "bad.wav"
|
| 73 |
+
bad_path.write_bytes(b"\x00\x00\x00\x00\x00")
|
| 74 |
+
result = preprocess_audio(str(bad_path), output_dir=tmp_path)
|
| 75 |
+
assert result.checked is True
|
| 76 |
+
# Should fail gracefully
|
| 77 |
+
assert result.status == "failed" or result.status == "normalized"
|
| 78 |
+
|
| 79 |
+
|
| 80 |
+
def test_result_is_audio_preprocess_result(tmp_path):
|
| 81 |
+
wav_path = tmp_path / "t.wav"
|
| 82 |
+
_make_silent_wav(str(wav_path))
|
| 83 |
+
result = preprocess_audio(str(wav_path), output_dir=tmp_path)
|
| 84 |
+
assert isinstance(result, AudioPreprocessResult)
|
| 85 |
+
assert result.checked is True
|