fix: verify audio magic bytes before extension-based short-circuit in convert_audio_format

[xiaoyuyu6420]

Problem

When a platform adapter (e.g. NapCat via aiocqhttp / OneBot v11) saves QQ voice messages, the actual audio encoding is AMR (magic bytes #!AMR) but the local file is given a .wav extension. The convert_audio_format() function short-circuits purely on file extension:

if audio_path.lower().endswith(f".{output_format}"):
    return audio_path   # ← skips ffmpeg, returns raw AMR bytes

When output_format is wav, the extension matches and the raw AMR byte stream is returned unchanged. Downstream STT providers (e.g. Whisper-compatible APIs) receive malformed WAV data and reject it with HTTP 400.

Reported in #9594.

Fix

Reuse the existing _get_audio_magic_type() helper (already used by ensure_wav()) to verify the file content actually matches the target format before short-circuiting:

if audio_path.lower().endswith(f".{output_format}"):
    detected = _get_audio_magic_type(audio_path)
    if not detected or detected == output_format:
        return audio_path
    # Extension/content mismatch → proceed with ffmpeg conversion

Three cases:

• Extension matches AND magic bytes confirm the format → short-circuit (preserves the optimization).
• Extension matches BUT magic bytes detect a different format → proceed with ffmpeg conversion (fixes the bug).
• Extension matches BUT format is unrecognised → short-circuit (preserves old behaviour for formats we cannot detect, avoids unnecessary ffmpeg overhead).

Tests

5 new tests added to tests/test_media_utils.py, all passing:

Test	Scenario	Expected
amr_with_wav_extension_does_not_short_circuit	AMR content, .wav ext, target wav	ffmpeg invoked
real_wav_with_wav_extension_short_circuits	WAV content, .wav ext, target wav	no conversion
unknown_content_with_matching_ext_short_circuits	unrecognised content, .wav ext, target wav	no conversion
real_amr_with_amr_extension_short_circuits	AMR content, .amr ext, target amr	no conversion
wav_with_ogg_extension_does_not_short_circuit	WAV content, .ogg ext, target ogg	ffmpeg invoked

Full suite: 55 passed. ruff format / ruff check clean.

Closes #9594.

Summary by Sourcery

Validate audio file magic bytes before short-circuiting format conversion based on file extension to prevent malformed audio from being returned to downstream consumers.

Enhancements:

• Improve convert_audio_format to fall back to ffmpeg when file extension and detected audio format disagree, while preserving the existing optimization when they match or the format is unknown.

Tests:

• Add async tests around convert_audio_format to cover extension vs magic-byte mismatches and confirm correct behavior for AMR, WAV, OGG, and unknown content scenarios.

[sourcery-ai]

Hey - I've left some high level feedback:

• The ffmpeg subprocess mocking logic (including _FakeFFmpegProcess and the fake_exec setup) is duplicated across several tests; consider extracting a reusable helper or fixture to keep the test suite DRY and easier to maintain.
• In _FakeFFmpegProcess, the stderr parameter is accepted but never used; either wire it into communicate() or remove the parameter to avoid confusion about its purpose.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The ffmpeg subprocess mocking logic (including `_FakeFFmpegProcess` and the `fake_exec` setup) is duplicated across several tests; consider extracting a reusable helper or fixture to keep the test suite DRY and easier to maintain.
- In `_FakeFFmpegProcess`, the `stderr` parameter is accepted but never used; either wire it into `communicate()` or remove the parameter to avoid confusion about its purpose.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}