Enhance audio format conversion with WAV validation and PCM handling

- Introduced functions to validate WAV data chunk readability and convert PCM16LE to WAV format, addressing issues with ffmpeg's pipe output.
- Updated `ensure_wav_bytes` to handle broken WAV data more robustly, ensuring correct WAV headers are generated for non-WAV inputs.
- Enhanced tests to validate new functionality, including handling of invalid WAV data and ensuring proper conversion from PCM to WAV format.
- Improved overall audio processing reliability by implementing ASR-friendly defaults for sample rate and channels.

Author: lapy

backend/audio_format_convert.py

@@ -2,15 +2,22 @@
 
 from __future__ import annotations
 
+import io
 import shutil
+import struct
 import subprocess
+import wave
 from typing import Optional, Tuple
 
 from fastapi import HTTPException
 
 MAX_AUDIO_UPLOAD_BYTES = 60 * 1024 * 1024
 FFMPEG_TIMEOUT_SECONDS = 60
 
+# ASR-friendly defaults when decoding compressed formats.
+ASR_SAMPLE_RATE = 16000
+ASR_CHANNELS = 1
+
 
 class AudioConvertError(Exception):
     """Raised when media cannot be converted to WAV."""
@@ -32,6 +39,39 @@ def ffmpeg_available() -> bool:
     return bool(shutil.which("ffmpeg"))
 
 
+def wav_data_chunk_readable(content: bytes) -> bool:
+    """Return True when the WAV ``data`` chunk size matches available bytes.
+
+    ffmpeg's ``pipe:1`` WAV muxer often writes ``0xFFFFFFFF`` size fields because
+    it cannot seek the stream to patch the header. audio.cpp then fails with
+    ``failed to read WAV data chunk``.
+    """
+    if not is_wav_content(content):
+        return False
+    offset = 12
+    length = len(content)
+    while offset + 8 <= length:
+        chunk_id = content[offset : offset + 4]
+        chunk_size = struct.unpack_from("<I", content, offset + 4)[0]
+        data_start = offset + 8
+        data_end = data_start + chunk_size
+        if chunk_id == b"data":
+            return data_end <= length
+        # Chunks are word-aligned.
+        offset = data_end + (chunk_size % 2)
+    return False
+
+
+def pcm16le_to_wav(pcm: bytes, *, channels: int, sample_rate: int) -> bytes:
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as wf:
+        wf.setnchannels(channels)
+        wf.setsampwidth(2)
+        wf.setframerate(sample_rate)
+        wf.writeframes(pcm)
+    return buf.getvalue()
+
+
 def ensure_wav_bytes(
     content: bytes,
     *,
@@ -40,8 +80,11 @@ def ensure_wav_bytes(
 ) -> Tuple[bytes, str]:
     """Return PCM WAV bytes and a .wav filename.
 
-    Already-WAV payloads are returned unchanged. Other formats are converted
-    with ffmpeg (pcm_s16le). Raises AudioConvertError on failure.
+    Already-WAV payloads with a readable ``data`` chunk are returned unchanged.
+    Other formats (and broken pipe-WAV) are converted with ffmpeg to mono 16 kHz
+    PCM16, then wrapped with a correct RIFF header via the stdlib ``wave``
+    module (avoids ffmpeg stdout size-field bugs). Raises AudioConvertError on
+    failure.
     """
     if not content:
         raise AudioConvertError("Empty audio upload")
@@ -50,16 +93,17 @@ def ensure_wav_bytes(
             f"Audio upload exceeds {MAX_AUDIO_UPLOAD_BYTES // (1024 * 1024)} MB limit",
         )
 
-    if is_wav_content(content):
-        out_name = _wav_filename(filename)
-        return content, out_name
+    if is_wav_content(content) and wav_data_chunk_readable(content):
+        return content, _wav_filename(filename)
 
     if not ffmpeg_available():
         raise AudioConvertError(
             "ffmpeg is not installed; cannot convert non-WAV audio uploads",
             status_code=503,
         )
 
+    # Decode to raw PCM on stdout (size fields are irrelevant for s16le),
+    # then write a seek-correct WAV header ourselves.
     try:
         proc = subprocess.run(
             [
@@ -71,9 +115,13 @@ def ensure_wav_bytes(
                 "-i",
                 "pipe:0",
                 "-f",
-                "wav",
+                "s16le",
                 "-acodec",
                 "pcm_s16le",
+                "-ac",
+                str(ASR_CHANNELS),
+                "-ar",
+                str(ASR_SAMPLE_RATE),
                 "pipe:1",
             ],
             input=content,
@@ -95,10 +143,15 @@ def ensure_wav_bytes(
         name_hint = filename or content_type or "upload"
         raise AudioConvertError(f"Could not convert {name_hint} to WAV: {hint}")
 
-    if not is_wav_content(proc.stdout):
-        raise AudioConvertError("ffmpeg produced output that is not a valid WAV")
+    wav_bytes = pcm16le_to_wav(
+        proc.stdout,
+        channels=ASR_CHANNELS,
+        sample_rate=ASR_SAMPLE_RATE,
+    )
+    if not wav_data_chunk_readable(wav_bytes):
+        raise AudioConvertError("converted WAV failed validation")
 
-    return proc.stdout, _wav_filename(filename)
+    return wav_bytes, _wav_filename(filename)
 
 
 def ensure_wav_bytes_http(

backend/tests/test_audio_format_convert.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import io
+import struct
 import wave
 
 import pytest
@@ -20,12 +21,48 @@ def _minimal_wav(frames: int = 1600, rate: int = 16000) -> bytes:
     return buf.getvalue()
 
 
+def _pipe_style_wav_with_bad_data_size(pcm_bytes: int = 32) -> bytes:
+    """Mimic ffmpeg stdout WAV: valid RIFF/WAVE/fmt, data size 0xFFFFFFFF."""
+    fmt = struct.pack(
+        "<HHIIHH",
+        1,  # PCM
+        1,  # mono
+        16000,
+        32000,
+        2,
+        16,
+    )
+    pcm = b"\x00" * pcm_bytes
+    # RIFF size also often left as 0xFFFFFFFF for pipes.
+    return (
+        b"RIFF"
+        + struct.pack("<I", 0xFFFFFFFF)
+        + b"WAVE"
+        + b"fmt "
+        + struct.pack("<I", 16)
+        + fmt
+        + b"data"
+        + struct.pack("<I", 0xFFFFFFFF)
+        + pcm
+    )
+
+
 def test_is_wav_content_detects_riff_wave():
     assert convert.is_wav_content(_minimal_wav())
     assert not convert.is_wav_content(b"OggS\x00\x00")
     assert not convert.is_wav_content(b"")
 
 
+def test_wav_data_chunk_readable_accepts_honest_wav():
+    assert convert.wav_data_chunk_readable(_minimal_wav())
+
+
+def test_wav_data_chunk_readable_rejects_pipe_size_bug():
+    bad = _pipe_style_wav_with_bad_data_size()
+    assert convert.is_wav_content(bad)
+    assert not convert.wav_data_chunk_readable(bad)
+
+
 def test_ensure_wav_bytes_passthrough_for_wav():
     wav = _minimal_wav()
     out, name = convert.ensure_wav_bytes(wav, filename="clip.ogg")
@@ -39,28 +76,65 @@ def test_ensure_wav_bytes_rejects_empty():
 
 
 def test_ensure_wav_bytes_converts_with_ffmpeg(monkeypatch):
-    wav = _minimal_wav()
+    pcm = b"\x00\x00" * 80
 
     def fake_run(cmd, input=None, capture_output=None, timeout=None, check=None):
         class Result:
             returncode = 0
-            stdout = wav
+            stdout = pcm
             stderr = b""
 
         assert "ffmpeg" in cmd[0]
+        assert "-f" in cmd and "s16le" in cmd
         assert input == b"not-wav-bytes"
         return Result()
 
     monkeypatch.setattr(convert, "ffmpeg_available", lambda: True)
     monkeypatch.setattr(convert.subprocess, "run", fake_run)
 
     out, name = convert.ensure_wav_bytes(b"not-wav-bytes", filename="memo.opus")
-    assert out == wav
     assert name == "memo.wav"
+    assert convert.is_wav_content(out)
+    assert convert.wav_data_chunk_readable(out)
+    with wave.open(io.BytesIO(out), "rb") as wf:
+        assert wf.getnchannels() == 1
+        assert wf.getframerate() == 16000
+        assert wf.getsampwidth() == 2
+        assert wf.readframes(wf.getnframes()) == pcm
+
+
+def test_ensure_wav_bytes_rewrites_broken_pipe_wav(monkeypatch):
+    """Broken ffmpeg-pipe WAV must be re-decoded, not passed through."""
+    bad = _pipe_style_wav_with_bad_data_size()
+    pcm = b"\x01\x00" * 40
+
+    def fake_run(cmd, input=None, capture_output=None, timeout=None, check=None):
+        class Result:
+            returncode = 0
+            stdout = pcm
+            stderr = b""
+
+        assert input == bad
+        return Result()
+
+    monkeypatch.setattr(convert, "ffmpeg_available", lambda: True)
+    monkeypatch.setattr(convert.subprocess, "run", fake_run)
+
+    out, _name = convert.ensure_wav_bytes(bad, filename="pipe.wav")
+    assert convert.wav_data_chunk_readable(out)
+    assert out != bad
 
 
 def test_ensure_wav_bytes_missing_ffmpeg(monkeypatch):
     monkeypatch.setattr(convert, "ffmpeg_available", lambda: False)
     with pytest.raises(convert.AudioConvertError) as exc:
         convert.ensure_wav_bytes(b"OggSfake", filename="a.ogg")
     assert exc.value.status_code == 503
+
+
+def test_pcm16le_to_wav_roundtrip():
+    pcm = b"\x00\x10\xff\x7f"
+    wav = convert.pcm16le_to_wav(pcm, channels=1, sample_rate=16000)
+    assert convert.wav_data_chunk_readable(wav)
+    with wave.open(io.BytesIO(wav), "rb") as wf:
+        assert wf.readframes(2) == pcm