Files
karaoke-gen/tests
Andrew Beveridge ☄️andClaude Fable 5 527d55ef63 fix: preserve source audio extension for temp downloads (ffmpeg extension-fallback failure) (#1023)
## Summary

Root-cause fix for the 2026-09-17 19:47 ET error-pattern cluster (job
`e026e727`): a paying user's uploaded MP3 had a ~1.2 MB ID3 tag
(embedded cover art from a ytmp3 rip). The backend downloads job audio
to temp files hardcoded as `*.flac` — ffmpeg's content probe is
inconclusive inside the huge tag, so it falls back to the **file
extension**, commits to the flac demuxer, and fails with `Could not find
codec parameters for stream 0 (Audio: flac, 0 channels)`. That single
file broke every consumer of the input audio:

- `GET /api/review/{id}/waveform-data` → 500 ("Decoding failed. ffmpeg
returned error code: 8")
- Review OGG transcode → "Cannot determine format of input 0:0 after
EOF" (fell back to raw FLAC serving)
- Preview video encode → failed on **both** GCE worker and local
fallback ("Invalid data found when processing input")
- Duration probe → `Failed to get audio duration: 'duration'` (KeyError)

**Repro:** the file is a perfectly valid 227 s MP3 — `ffprobe` succeeds
when the copy is named `.mp3` or has no extension, and fails when named
`.flac` (verified on ffmpeg 8.0 locally and 7.0.2-static in prod). The
`majorbrand: dash` metadata is a copied ID3 tag, not a mislabeled MP4.

## Changes

- New `backend/utils/audio_filenames.py` —
`local_audio_filename(gcs_path, stem)` names local copies with the
source object's real (lowercased) extension; unknown/missing extension →
bare name, forcing pure content probing.
- Applied at every site that downloads job audio to a temp file:
- `backend/services/audio_analysis_service.py` (waveform data/image,
analysis, mute-region waveform, stem comparison)
- `backend/services/audio_transcoding_service.py` (review OGG transcode)
- `backend/api/routes/review.py` `_prepare_preview_inputs` (preview
local encode)
- `backend/services/gce_encoding/main.py` (GCE preview + render audio
download)
- `backend/workers/render_video_worker.py`,
`backend/workers/audio_worker.py`, `backend/workers/lyrics_worker.py`
- `docs/TROUBLESHOOTING.md`: new runbook entry for this failure class.
- Version bump 0.229.3 → 0.229.4.

## Testing

- New `tests/unit/test_audio_filenames.py` — 9 tests: helper behavior
(extension preservation, lowercasing, unknown/missing-extension
fallback) + service-level assertions that the transcoding and analysis
services download to source-matching temp names.
- Full `make test` suite passes locally (backend + frontend, 105 suites
/ 1286 frontend tests).

## Impact / rollout

- No data repair needed for job `e026e727` — its stems/lyrics are
intact; the review page starts working once this deploys.
- `gce_encoding/main.py` ships in the wheel; the encoding worker's
per-job wheel version check picks it up (restart `encoding-worker`
service to force immediate pickup).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Bug Fixes**
- Improved audio processing for files with non-FLAC extensions,
including MP3 and OGG files.
- Preview rendering, waveform generation, transcription, and audio
conversion now preserve source file extensions, reducing decoding
failures.
  - Audio conversion fallbacks now use the correct source content type.

- **Documentation**
- Added troubleshooting guidance for waveform and preview failures
related to audio metadata or file extensions.

- **Tests**
- Added coverage for extension handling across audio download and
processing workflows.

- **Release**
  - Updated the application version to 0.229.4.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-17 21:40:36 -04:00
..