fix(audioshake): remux user audio with leading null padding before transcription (#826)

@coderabbitai ignore

## Problem (found by the real Vocal Star E2E)

After #824/#825, the first real Vocal Star job reached transcription but
**AudioShake rejected the asset**: `400 ... "Error fetching or
processing asset"`.

Root cause: the supplied MP3 — and **Vocal Star's entire bulk batch** —
begins with ~731 leading `0x00` bytes before the first ID3/MPEG frame.
`ffmpeg`/`ffprobe` tolerate it (the audio decodes fine), but
AudioShake's asset processing does not.

Consumer jobs never hit this because their audio is re-encoded into
clean stems by the separator before transcription. Tenant /
existing-instrumental jobs upload the user's **raw** file straight to
AudioShake.

## Fix
`AudioUploadOptimizer.prepare_for_upload` now detects leading null
padding on padding-prone compressed formats (`.mp3/.aac/.mp4a` — **not**
container formats like `.mp4/.mov`, which legitimately start with a null
box-size prefix) and **losslessly remuxes** (`ffmpeg -c copy`, no
re-encode) before upload.

## Verified against the real AudioShake API
- padded file → `create_task` **400** ("Error fetching or processing
asset")
- remuxed file (same upload path) → `create_task` **200** ✓

Regression tests added (detection + routing + container-format safety).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 4.8 authored and GitHub committed 2026-06-15 04:12:22 -04:00
1 parent 829ff02bdb
commit c94a5b8754
3 files changed
+120 -2

No files matched your search

+67
View File
@@ -0,0 +1,67 @@
"""
Regression tests for AudioShake leading-padding handling.
Some user-provided audio (e.g. the Vocal Star bulk-batch MP3s) begins with a block of
null bytes before the first ID3/MPEG frame. ffmpeg tolerates it, but AudioShake rejects
the asset with "Error fetching or processing asset" (400 on /tasks). The AudioUploadOptimizer
must detect this and losslessly remux before upload — while leaving clean files and
container formats (.mp4/.mov, which legitimately start with null box-size bytes) untouched.
"""
import os
import tempfile
from unittest.mock import MagicMock, patch
from karaoke_gen.lyrics_transcriber.transcribers.audioshake import AudioUploadOptimizer
def _write(tmp_path, name, head: bytes):
p = os.path.join(tmp_path, name)
with open(p, "wb") as f:
f.write(head + b"\x00" * 2048)
return p
def test_has_leading_padding_detects_null_start(tmp_path):
opt = AudioUploadOptimizer(MagicMock())
padded = _write(str(tmp_path), "padded.mp3", b"\x00\x00\x00\x00")
assert opt._has_leading_padding(padded) is True
def test_has_leading_padding_false_for_id3(tmp_path):
opt = AudioUploadOptimizer(MagicMock())
clean = _write(str(tmp_path), "clean.mp3", b"ID3\x04")
assert opt._has_leading_padding(clean) is False
def test_has_leading_padding_false_for_frame_sync(tmp_path):
opt = AudioUploadOptimizer(MagicMock())
clean = _write(str(tmp_path), "sync.mp3", b"\xff\xfb\xc0\x04")
assert opt._has_leading_padding(clean) is False
def test_padded_mp3_is_remuxed(tmp_path):
opt = AudioUploadOptimizer(MagicMock())
padded = _write(str(tmp_path), "padded.mp3", b"\x00\x00\x00\x00")
with patch.object(opt, "_remux_clean", return_value=("/tmp/clean.mp3", "/tmp/clean.mp3")) as remux:
result = opt.prepare_for_upload(padded)
remux.assert_called_once()
assert result == ("/tmp/clean.mp3", "/tmp/clean.mp3")
def test_clean_mp3_uploaded_directly(tmp_path):
opt = AudioUploadOptimizer(MagicMock())
clean = _write(str(tmp_path), "clean.mp3", b"ID3\x04")
with patch.object(opt, "_remux_clean") as remux:
result = opt.prepare_for_upload(clean)
remux.assert_not_called()
assert result == (clean, None)
def test_container_format_not_remuxed_despite_null_start(tmp_path):
""".mp4/.mov begin with a null box-size prefix — must NOT be treated as padding."""
opt = AudioUploadOptimizer(MagicMock())
mp4 = _write(str(tmp_path), "video.mp4", b"\x00\x00\x00\x20ftyp")
with patch.object(opt, "_remux_clean") as remux:
result = opt.prepare_for_upload(mp4)
remux.assert_not_called()
assert result == (mp4, None)
@@ -29,6 +29,11 @@ AUDIOSHAKE_SUPPORTED = AUDIOSHAKE_SUPPORTED_AUDIO | AUDIOSHAKE_SUPPORTED_VIDEO
# Uncompressed formats that benefit from FLAC conversion (smaller upload)
UNCOMPRESSED_FORMATS = {'.wav', '.aiff', '.aif', '.pcm'}
# Compressed audio formats where leading 0x00 bytes are unambiguous garbage (the real
# audio starts at an ID3 tag or MPEG/ADTS frame sync). Container formats like .mp4/.mov
# legitimately begin with null bytes (box-size prefix) and must NOT be treated this way.
LEADING_PADDING_PRONE = {'.mp3', '.aac', '.mp4a'}
class AudioUploadOptimizer:
"""Optimizes audio files for upload by converting uncompressed formats to FLAC."""
@@ -57,8 +62,14 @@ class AudioUploadOptimizer:
self.logger.info("Stripping metadata from FLAC before upload (audio unchanged)")
return self._strip_metadata(filepath)
# Other AudioShake-supported formats: upload directly
# Other AudioShake-supported formats: upload directly, unless the file has leading
# null-byte padding that AudioShake's asset processing rejects (see below).
if ext in AUDIOSHAKE_SUPPORTED:
if ext in LEADING_PADDING_PRONE and self._has_leading_padding(filepath):
self.logger.info(
f"Leading padding detected in {ext}; remuxing losslessly before upload"
)
return self._remux_clean(filepath, ext)
self.logger.info(f"Uploading AudioShake-supported format ({ext}) directly")
return filepath, None
@@ -91,6 +102,46 @@ class AudioUploadOptimizer:
self.logger.info(f"Stripped metadata from {os.path.basename(filepath)}")
return clean_path, clean_path
def _has_leading_padding(self, filepath: str) -> bool:
"""Return True if the file begins with a null byte (leading padding).
Some user-provided files (notably certain karaoke production exports, e.g. the
Vocal Star bulk batch) carry a block of leading 0x00 bytes before the first ID3
tag / MPEG frame sync. ffmpeg tolerates this, but AudioShake's asset processing
rejects it with "Error fetching or processing asset". Such files must be remuxed
before upload. Only call this for LEADING_PADDING_PRONE formats — container
formats begin with null bytes legitimately.
"""
try:
with open(filepath, "rb") as f:
return f.read(1) == b"\x00"
except OSError:
return False
def _remux_clean(self, filepath: str, ext: str) -> Tuple[str, str]:
"""Losslessly remux audio to strip leading padding that breaks AudioShake.
Uses ffmpeg stream copy (no re-encode, no quality loss); ffmpeg's demuxer skips
the leading garbage and writes only valid frames, so the output starts cleanly.
"""
with tempfile.NamedTemporaryFile(suffix=ext, delete=False) as temp_file:
clean_path = temp_file.name
try:
subprocess.run(
["ffmpeg", "-i", filepath, "-map", "0:a", "-c", "copy", "-map_metadata", "-1", clean_path, "-y"],
check=True,
capture_output=True,
)
except subprocess.CalledProcessError as e:
if os.path.exists(clean_path):
os.unlink(clean_path)
self.logger.error(f"ffmpeg remux failed: {e.stderr.decode()}")
raise
self.logger.info(f"Remuxed {os.path.basename(filepath)} to strip leading padding")
return clean_path, clean_path
def _convert_to_flac(self, filepath: str) -> Tuple[str, str]:
"""Convert audio file to FLAC format."""
ext = os.path.splitext(filepath)[1].lower()
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.183.1"
version = "0.183.2"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"