# NousResearch/hermes-agent · TTS audio format and voice bubble delivery issues

## Open now

- 2 issues, 2 PRs open on GitHub.
- #62079: \[Bug\]: Telegram MEDIA document upload failures fall through to generic attachment warning without retry/recovery
- #64137: \[Bug\]: send_document (Telegram) has no flood-control retry, silently degrades to text apology
- PR #57184: fix(tts): transcode openai voice output to opus
- PR #64145: fix(telegram): retry native media sends on flood control instead of giving up

These issues and fixes concern TTS output being delivered in wrong audio formats (MP3 instead of OGG/Opus) across Telegram, Matrix, Feishu, and DingTalk, causing broken voice bubbles or silent fallbacks. Related work involves transcoding pipelines, flood-control gaps, and notification delivery for voice replies.

## TL;DR

- 39 member(s): 2 open issue(s), 12 closed issue(s), 2 open PR(s), 3 merged PR(s), 20 PR(s) closed without merging.
- A fix was merged to main in PR #28504. Verify it addresses your case.
- **Recommended:** read PR #28504 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-73508`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.05`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Open related issues

- #62079: \[Bug\]: Telegram MEDIA document upload failures fall through to generic attachment warning without retry/recovery
- #64137: \[Bug\]: send_document (Telegram) has no flood-control retry, silently degrades to text apology

## Closed / duplicate issues

- #4248: \[Bug\]: Telegram send_voice falls back to text "🔊 Audio: /path" instead of sending voice bubble
- #7564: \[Bug\]\[DingTalk\] Media upload failure silently degrades to placeholder text
- #14841: Matrix voice replies sent as mp3 instead of ogg/opus — render as broken attachments
- #26355: Telegram: TTS voice bubbles not delivered despite valid OGG Opus +
- #27970: \[Bug\]: Telegram auto voice replies can fall back to MP3 attachments and silent final notifications
- #36685: Telegram gateway auto-replies force MP3 for Opus-capable TTS providers
- #45557: minimax TTS on Feishu sends mp3 as file attachment instead of voice bubble
- #54589: \[Bug\]: OpenAI-compatible TTS backends without opus support fail on voice bubbles (_generate_openai_tts hardcodes response_format="opus" for .ogg)
- #57049: Base platform adapter's auto-TTS voice reply defaults to .mp3 on Telegram (no native voice bubble) — session-platform detection unavailable in that code path
- #57213: \[Bug\]: xAI TTS also writes MP3 bytes into .ogg voice files — Telegram voice bubbles broken (same class as #57048/#54589, xai provider not covered by existing fixes)
- #58715: \[Bug\]: Matrix TTS voice replies sent as non-Opus audio — Element X voice bubble renders but won't play
- #60556: \[Bug\]: Telegram streaming + \[\[audio_as_voice\]\] causes TTS to render as plain audio attachment, not voice bubble

## Prior & competing PRs

- **#28504: fix(gateway): mark final voice reply as notify-worthy so Telegram delivers it audibly**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `gateway/run.py`, `tests/gateway/test_send_voice_reply_notify.py`, `tests/gateway/test_voice_command.py`
- **#60580: fix(gateway/streaming): deliver \[\[audio_as_voice\]\] via send_voice during streaming**. closed without merge · fix tier `suggested`
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `f58902818d9302fcdd4b30cc29cf2b9bc5f9f5f4`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#73072: fix(tts): class-level .ogg container repair + multi-platform Opus voice detection**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `tests/tools/test_tts_container_repair.py`, `tools/tts_tool.py`
- **#73508: fix(gateway): platform-aware auto-TTS voice delivery (opus platforms, streamed/global gap, captions)**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `gateway/platforms/base.py`, `gateway/run.py`, `plugins/platforms/feishu/adapter.py`, `plugins/platforms/matrix/adapter.py`, `plugins/platforms/telegram/adapter.py`, `tests/gateway/test_auto_voice_reply_format.py`, `tests/gateway/test_base_auto_tts_output_format.py`, `tests/gateway/test_matrix_voice.py`, `tests/gateway/test_telegram_voice_caption_markdown.py`, `tests/gateway/test_voice_command.py`, `tests/tools/test_tts_opus_routing.py`, `tools/tts_tool.py`
- **#14900: fix: send voice replies as Opus/OGG on Matrix**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`
- **#20182: fix(gateway): use OGG for Telegram auto TTS**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#41644`
- **#28107: fix(gateway): mark final voice reply as notify-worthy so Telegram delivers it audibly**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#28504`
- **#36686: fix(tts): preserve Telegram Opus output for native providers**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `f440a44753`, `#73508`, `#62040`, `#73508`
- **#45555: fix(tts): include feishu in want_opus platforms**. closed without merge
  - maintainer direction: category `silent_close`; implication `active`
- **#45637: fix(tts): include feishu in want_opus guard for native voice delivery**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#45555`
- **#45712: fix(tts): extend opus conversion to Feishu for voice bubbles (#45557)**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#45555`, `#45557`, `#45555`, `#45637`
- **#45761: fix(tts): include feishu in want_opus platforms**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `f440a44753`, `#73508`, `#62040`, `#73508`
- **#54597: fix(tools): transcode to OGG/Opus for OpenAI-compatible TTS backends without opus (#54589)**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#54589`, `#37337`, `#54488`
- **#55278: fix(tts): synthesize mp3 then transcode to opus for .ogg targets**. closed without merge
  - maintainer direction: category `wontfix_bydesign`; implication `wontfix`; refs `#54597`
- **#56777: fix(tts): transcode OpenAI-compatible speech to Opus for .ogg targets (#54589)**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#54589`, `#54597`, `#55278`
- **#56873: fix(tts): transcode OpenAI-compatible TTS to OGG/Opus when backend lacks opus**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#73072`
- **#57071: fix(gateway): pass explicit .ogg output_path for Telegram auto-TTS**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `f440a44753`, `#73508`, `#62040`, `#73508`
- **#57084: fix(gateway): request OGG for Telegram auto TTS**. closed without merge
  - maintainer direction: category `stale_abandoned`; implication `active`
- **#57184: fix(tts): transcode openai voice output to opus**. open
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `70db671fac`, `fae29c841`, `045a9b463e`, `#73470`, `#73482`, `#73482`
  - files: `tests/tools/test_tts_opus_routing.py`, `tools/tts_tool.py`
- **#57222: fix(tts): transcode xAI ogg requests to Opus**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#73072`
- **#57250: fix(tts): transcode xai ogg output paths**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#57222`
- **#57518: fix(tts): transcode xAI TTS output to Opus when .ogg requested (#57213)**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#57222`, `#57222`, `#57250`, `#57222`
- **#58716: fix(gateway): use OGG/Opus for Matrix voice replies**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#14900`, `#14900`
- **#64145: fix(telegram): retry native media sends on flood control instead of giving up**. open
  - maintainer direction: category `partial_fix`; implication `needs_llm`; refs `40ce9604723a`, `#64145`, `#64137`, `#64145`, `#64145`, `#374151`, `#64137`, `#64145`
  - files: `plugins/platforms/telegram/adapter.py`, `tests/gateway/test_telegram_documents.py`
- **#68063: fix: Matrix voice as Ogg/Opus — direct TTS path + non-blocking metadata (completes #54488)**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `f440a44753`, `#73508`

## Fix status

- Merged to main in PR #28504 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-07-28`.
- Subsystem: `agent`