fix(gateway): set duration on Telegram voice/audio so long clips don'…

[szafranski]

What does this PR do?

Telegram only auto-derives a voice/audio clip's duration from container metadata for
short recordings. Clips longer than ~4:50 are delivered with duration 0 and render as
0:00 in the player. This probes the clip length locally and passes duration
explicitly to sendVoice / sendAudio, so the bubble shows the real time. When the
length can't be determined we omit duration and fall back to Telegram's prior behavior,
so this never regresses the short-clip path.

This extracts and hardens the Telegram-only part of the stale, Piper-bundled PR #7815
(ffprobe-only, predates the current send_voice retry/anchor refactor).

Related Issue

Fixes #36005
Relates to #8508. Supersedes the Telegram portion of #7815.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• plugins/platforms/telegram/adapter.py:
  • Add _probe_voice_duration_seconds() — best-effort length via stdlib wave →
    mutagen → ffprobe (the ffprobe branch is guarded by shutil.which).
  • Add _coerce_duration_seconds() — round to whole positive seconds, else None.
  • send_voice now runs the probe off-thread (asyncio.to_thread) and forwards
    duration to both the .ogg/.opus (send_voice) and .mp3/.m4a (send_audio) paths.
  • No new hard dependency: mutagen is used opportunistically (it isn't a declared
    dep), with wave/ffprobe covering its absence.
• tests/gateway/test_telegram_voice_duration.py: new hermetic test suite (20 tests).

How to Test

1. scripts/run_tests.sh tests/gateway/test_telegram_voice_duration.py → 20 passed (macOS & Linux).
2. End-to-end on Telegram: send a voice/audio reply with audio longer than ~4:50.
3. Before: the bubble shows 0:00. After: it shows the real length. Verified on Linux —
   a 293 s clip now renders as 4:53 (screenshot below).

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(gateway): ...)
• I searched for existing PRs to make sure this isn't a duplicate (found feat(tts): add Piper setup support and fix Telegram voice note metadata #7815 — stale/bundled; this is the focused extract)
• My PR contains only changes related to this fix (no unrelated commits)
• I've run the test suite and all related tests pass (scripts/run_tests.sh tests/gateway/test_telegram_voice_duration.py → 20/20)
• I've added tests for my changes
• I've tested on my platform: macOS 15 (Darwin 25.5) and Linux

Documentation & Housekeeping

• I've updated relevant documentation — N/A (internal helper, no public API/docs change)
• I've updated cli-config.yaml.example if I added/changed config keys — N/A (no config keys)
• I've updated CONTRIBUTING.md / AGENTS.md if I changed architecture — N/A
• I've considered cross-platform impact — shutil.which guards ffprobe; wave is stdlib; mutagen is optional. Validated on macOS + Linux.
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Screenshots / Logs

[alt-glitch]

Competing with #36009 — both fix #36005. This PR (ffprobe→mutagen→wave probe chain with off-thread execution) appears more thorough than #36009 (mutagen+file-size fallback only).

[austinpickett]

Code Review

tl;dr: The implementation is clean and correct. One blocker before merging: the branch needs a rebase onto current main.

---

Stale base

git diff origin/main...pr-36020 --name-only reports 4,203 changed files — this is entirely stale-base pollution. The branch forked off an old commit (10b4cfeac — fix history leakage) that is hundreds of commits behind main. The actual PR commit (34bc595) contains exactly 2 files, 265 lines net-new. Please rebase onto main so CI can run cleanly and reviewers see only the real diff.

---

Implementation review (gateway/platforms/telegram.py, +77 lines)

_coerce_duration_seconds() — correct and tight. Handles float-string inputs (ffprobe returns a string), rejects 0/negative, returns None for anything unusable.

_probe_voice_duration_seconds() — the three-tier fallback chain is well-structured:

1. stdlib wave for .wav — zero external deps, early-exit on success.
2. mutagen — opportunistic; the bare except Exception: pass correctly keeps it optional.
3. ffprobe subprocess guarded by shutil.which — correct 5-second timeout.

All three tiers degrade gracefully to None, which restores pre-PR behavior (Telegram's own metadata, possibly absent). Non-breaking ✓.

send_voice integration — asyncio.to_thread is the right call for the blocking probe before touching the file handle. duration=_duration_secs is passed to both the send_voice (.ogg/.opus) and send_audio (.mp3/.m4a) paths. When _duration_secs is None, python-telegram-bot omits the field from the API request, matching prior behavior. ✓

One minor note: the wave import inside the function is redundant — wave is imported at module level in the test file and is stdlib, but the in-function import is harmless. No action needed.

---

Tests (tests/gateway/test_telegram_voice_duration.py, +188 lines)

Hermetic and thorough:

• 4× parametrized WAV rounding cases using real stdlib wave writes.
• mutagen path exercised via sys.modules injection (no real dep required).
• None-length, 0-length, missing mutagen, and missing ffprobe all return None.
• 8× _coerce_duration_seconds contract cases.
• Async integration tests confirm duration reaches bot.send_voice / bot.send_audio kwargs.
• Graceful-fallback test confirms duration=None when probe fails.

20/20 coverage as claimed. ✓

---

Summary

The fix is correct, targeted, and well-tested. Blocking item: please rebase onto current main — once that's done and CI is green, this is ready to merge.

[austinpickett]

Fix is correct and the rebase landed clean — mergeable: MERGEABLE. Setting duration on Telegram voice/audio so long clips aren't cut off is a real fix. Approving.

[austinpickett]

Almost there — only one failing check is blocking merge: Contributor Attribution Check.

The commit message includes a Co-Authored-By: Claude Opus 4.8 trailer, which is what tripped it. All other checks (tests ×6, lint, typecheck, supply chain, Docker, e2e) are green.

Quick fix — amend the commit to drop that line and force-push:

git commit --amend  # remove the Co-Authored-By: Claude Opus 4.8 line, save
git push --force-with-lease

Once that lands and the attribution check goes green, this is ready to merge.

[szafranski]

Thanks, Should be done: https://github.com/NousResearch/hermes-agent/actions/runs/27344817745 czw., 11 cze 2026 o 13:44 Austin Pickett ***@***.***> napisał(a):

…

*austinpickett* left a comment (NousResearch/hermes-agent#36020) <#36020 (comment)> Almost there — only one failing check is blocking merge: *Contributor Attribution Check*. The commit message includes a Co-Authored-By: Claude Opus 4.8 trailer, which is what tripped it. All other checks (tests ×6, lint, typecheck, supply chain, Docker, e2e) are green. Quick fix — amend the commit to drop that line and force-push: git commit --amend # remove the Co-Authored-By: Claude Opus 4.8 line, save git push --force-with-lease Once that lands and the attribution check goes green, this is ready to merge. — Reply to this email directly, view it on GitHub <#36020?email_source=notifications&email_token=AFUHCAAJT4P4KXJUCODKAN347KLQDA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINRYGAYTMMBQGQZ2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4680160043>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFUHCAGGUASXH5RBXXPFGFT47KLQDAVCNFSNUABGKJSXA33TNF2G64TZHMYTAMRUGU2TIMRWG45US43TOVSTWNBVGU4DKNJTGE3TRILWAI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[austinpickett]

Almost there — the last failing check is Contributor Attribution, and the fix is one line you'll need to add since it maps your email to your GitHub username.

The check found your commit-author email p.fabiszewski@gmail.com (szafranski) isn't yet in AUTHOR_MAP in scripts/release.py. This map is what generates correct release-note attribution, so new contributors add themselves once.

Please add this line to the AUTHOR_MAP dict in scripts/release.py (it starts around line 47; keep it alphabetical-ish with the other gmail.com entries):

    "p.fabiszewski@gmail.com": "szafranski",

If your actual GitHub username differs from szafranski, use that instead — it should be your real login so the release notes link correctly.

Commit + push that to this branch and the attribution check goes green. Everything else (tests, lint, typecheck, the duration fix itself) is already passing — this is the only blocker. Thanks!

[austinpickett]

Attribution check still failing

CI is all green except check-attribution: the contributor email p.fabiszewski@gmail.com is not in the AUTHOR_MAP in scripts/release.py.

This is a maintainer-side fix. Please add:

"p.fabiszewski@gmail.com": "szafranski",

to the AUTHOR_MAP dict in scripts/release.py (around line 47) and push the commit. Once that lands, the check will pass and this PR is merge-ready.

(My APPROVED review from earlier still stands — the fix itself is correct.)

[szafranski]

now ok? :) czw., 11 cze 2026 o 16:55 Austin Pickett ***@***.***> napisał(a):

…

*austinpickett* left a comment (NousResearch/hermes-agent#36020) <#36020 (comment)> Attribution check still failing CI is *all green* except check-attribution: the contributor email ***@***.*** is not in the AUTHOR_MAP in scripts/release.py. This is a maintainer-side fix. Please add: ***@***.***": "szafranski", to the AUTHOR_MAP dict in scripts/release.py (around line 47) and push the commit. Once that lands, the check will pass and this PR is merge-ready. (My APPROVED review from earlier still stands — the fix itself is correct.) — Reply to this email directly, view it on GitHub <#36020?email_source=notifications&email_token=AFUHCAAIMVIQUVLQYMNZR6D47LB57A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINRYGE4DQNJXHA4KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4681885788>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFUHCAAL7AYAEBHA5J4DFML47LB57AVCNFSNUABGKJSXA33TNF2G64TZHMYTAMRUGU2TIMRWG45US43TOVSTWNBVGU4DKNJTGE3TRILWAI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[szafranski]

Sorry for bothering but I just wanted to ask is there anything more I should do?

[szafranski]

Sorry for the repeated attribution-check issue on my side.

I cleaned up the branch history and force-pushed a linear branch on top of current upstream/main. The AI co-author trailer has been removed from the AUTHOR_MAP commit, and the PR diff is now limited to the intended Telegram duration fix, its regression tests, and the AUTHOR_MAP entry.

The new workflow runs are currently waiting for maintainer approval/re-run (action_required).

[szafranski]

@austinpickett please excuse but I wanted to make sure I didn't make some mess here, since I see some "dismissed" info above (image attached). Should I do anything more right now?

[alt-glitch]

This was generated by AI during triage.
Competing with #36009 for the same issue #36005 — both pass explicit duration to send_voice/send_audio. This PR uses a more thorough wave→mutagen→ffprobe probe chain run off-thread; #36009 uses mutagen + file-size fallback. Related, not a duplicate — maintainer to pick.

[teknium1]

Thanks for isolating the duration probe and preserving the adapter's retry/anchor flow. The reported adapter behavior is still present on current main: plugins/platforms/telegram/adapter.py:5861-5869 and :5887-5895 call the Bot API without duration, so this targets a live defect.

Problems

• The fix does not cover the standalone Telegram sender. tools/send_message_tool.py:849-856 routes Telegram sends to _send_telegram, including non-gateway contexts as documented in tests/tools/test_send_message_telegram_proxy.py:3-5. Its voice/audio sends and retry sends at tools/send_message_tool.py:1327-1333 and :1357-1363 still omit duration. Long clips sent through that path retain the reported behavior.

Suggested changes

• Share the probe between the adapter and _send_telegram, then forward the result through both initial and retry send_voice / send_audio calls.
• Add standalone _send_telegram .ogg and .mp3 regression coverage alongside the adapter tests.

Automated hermes-sweeper review.

[teknium1]

Please apply the same duration propagation to the standalone Telegram sender. tools/send_message_tool.py:849-856 routes non-gateway Telegram sends through _send_telegram, whose send_voice/send_audio initial and retry calls at lines 1327-1333 and 1357-1363 still omit duration.

[szafranski]

Addressed: the standalone send_message_tool path now reuses the Telegram duration probe for .ogg sendVoice and .mp3 sendAudio, including the topic retry path. Verified with .venv/bin/python -m pytest tests/gateway/test_telegram_voice_duration.py -q (22 passed) and ruff.

[teknium1]

Merged via #65535 (rebase-merged onto current main, head commit d73a6f5) — all three of your commits were cherry-picked with your authorship preserved in git log. Thanks for the contribution!