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 content against its detected format before skipping conversion based on the file extension.

Bug Fixes:

• Prevent audio files whose extensions do not match their detected magic-byte format from bypassing conversion and reaching downstream consumers with invalid data.

Enhancements:

• Preserve conversion short-circuiting for matching, detectable formats and missing files while covering extension/content mismatch scenarios with focused tests.

Tests:

• Add coverage for matching formats, mismatched extensions, AMR/WAV detection, unknown content, and missing audio files.

[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.}

[xiaoyuyu6420]

Addressed both Sourcery notes:

• Unused stderr param — removed in b5e2b31.
• Duplicated ffmpeg mocking — b5e2b31 extracted _patch_ffmpeg for the invoked-ffmpeg path and dropped stderr; ac7b2d6 finishes the job by collapsing the three duplicated "never-called" fake_exec stubs into a shared _patch_ffmpeg_not_called(monkeypatch, reason) helper (per-scenario reason strings preserved).

Verified: pytest tests/test_media_utils.py -k convert_audio_format — 5 passed; full file — 54 passed, 1 pre-existing Windows-only failure in test_file_uri_to_path_* (unrelated to this change, fails on upstream baseline too); ruff check clean.

[sourcery-ai]

Sourcery assessment

Approved.

[xiaoyuyu6420]

Friendly ping @Soulter — rebased onto current master. The core fix for #9594 was already merged in #9612; this PR now provides test coverage for the magic-byte verification logic. Sourcery approved. CI awaits fork-PR approval.

[xiaoyuyu6420]

Closing this PR — the core fix for #9594 was already merged in #9612, which also includes 3 regression tests covering the critical scenarios (AMR-as-WAV transcoding, misnamed target format, and missing-path handling). The additional positive/edge-case tests in this PR add marginal value and arent worth the review time.

The PR served its purpose as a learning exercise and helped me understand the media pipeline. Thanks to anyone who looked.