fix(tts): preserve Telegram Opus output for native providers

[alauer]

Summary

Fixes #36685.

Telegram gateway auto-replies pass an explicit .mp3 temporary output path into text_to_speech_tool(). That path bypassed the existing Telegram-aware default .ogg selection and forced Opus-capable providers such as ElevenLabs down their MP3 output path.

Changes

• add a built-in provider capability check for Opus OGG output paths;
• rewrite Telegram gateway-style explicit .mp3 destinations to .ogg for Opus-capable providers;
• request native Opus from MiniMax t2a_v2 when the output path ends in .ogg;
• keep legacy MiniMax endpoints and MP3-only providers on their existing MP3 plus ffmpeg conversion path;
• document MiniMax t2a_v2 native Opus behavior;
• add regression coverage for gateway-style explicit .mp3 paths with ElevenLabs and MiniMax.

Validation

pytest -q -o addopts='' tests/tools/test_tts_speed.py
22 passed

python -m py_compile tools/tts_tool.py tests/tools/test_tts_speed.py
git diff --check

-o addopts='' is used because the shared local venv does not include the latest upstream pytest-timeout plugin required by the repository default test options.

[mxnstrexgl]

🤖 Automated PR Review

Security Scan

• ✓ No hardcoded secrets, injection sinks, unsafe deserialization, or dependency red flags found by this automated scan.

Code Quality

• ✓ No blocking code-quality issues found by this automated scan.

Summary

Status: APPROVE — security findings: 0, quality suggestions: 0.

Automated review; raw diff content intentionally omitted.

[tonydwb]

Code Review Summary

Verdict: Approved

✅ Looks Good

• Clean refactor: Extracts Opus-output detection into _supports_opus_output() helper, reducing duplicated inline checks
• Adds MiniMax support: MiniMax t2a_v2 API users now get native Opus/OGG output for Telegram voice bubbles
• Correct mapping: Gateway temp paths (/tmp/*.mp3) are rewritten to .ogg when the platform is Telegram and the provider supports Opus
• Good test coverage: Tests for OGG suffix, explicit MP3 rewrite, and MiniMax t2a_v2 detection
• Documentation updated: TTS docs reflect the changes

---

Reviewed by Hermes Agent

[teknium1]

Thanks for the focused MiniMax native-Opus work. The remaining MiniMax change is useful: current main’s tools/tts_tool.py:1368-1373 still hardcodes audio_setting.format to "mp3", while the live Telegram auto-reply path now supplies an .ogg destination (gateway/run.py:13153-13163).

Problems

• The new tests at tests/tools/test_tts_speed.py:217 and :250 describe gateway-supplied .mp3 paths, but current main changed that gateway contract in ae82eed2b194a5708bfecbc153637e434fc15ddb; tests/gateway/test_auto_voice_reply_format.py:17-43 already verifies the live path requests and delivers .ogg.

Suggested changes

• Re-scope the MiniMax regression test to the current gateway .ogg route and assert its t2a_v2 request uses audio_setting.format == "opus". That directly protects the remaining defect without preserving the obsolete gateway premise.

Automated hermes-sweeper review.

[teknium1]

Current GatewayRunner._send_voice_reply() already supplies .ogg for Telegram (gateway/run.py:13155, introduced by ae82eed2b). Please re-scope this regression to the live OGG gateway path and assert the MiniMax request payload selects format: "opus"; this test currently exercises an obsolete gateway contract.

[teknium1]

The root cause here (gateway auto-TTS choosing MP3 vs Ogg/Opus via the cleared HERMES_SESSION_PLATFORM contextvar, so opus platforms got audio attachments instead of native voice bubbles) was fixed class-wide in #73508: platform-awareness now comes from the caller via build_auto_tts_output_path(platform) keyed off OPUS_VOICE_PLATFORMS (based on @giladbau's #62040), with the central container repair guaranteeing real Ogg/Opus bytes.

(Landed via #73508, merge f440a44753.) Closing.