Every voice message stopped transcribing overnight: PyAV 19 versus one argument in faster-whisper 1.2.1

7:30 on the commute, you send three voice notes to your Hermes bot on Telegram: today’s three todos, one conclusion from a meeting you just left, and a throwaway test of whether the connection works. At the office you open your laptop and all three answer with the same line — could not transcribe.
You upgraded nothing. You changed no config. It worked yesterday. And the strangest part: text messages are fine. Only the voice path is dead.
Failures where “nothing changed” are almost never application code. They are dependencies moving while you were not looking. This one is a textbook case.
The symptom and the actual culprit
Local transcription is a small pipeline: the platform delivers a voice file, Hermes hands it to the local STT engine (faster-whisper, running on ctranslate2), and audio decoding goes through PyAV — Python’s binding to FFmpeg. When transcription fails, the gateway labels the message [voice message could not be transcribed], and if the audio was written to disk it appends the path so you can transcribe it yourself later.
The failure happens one layer down, in decoding. faster-whisper 1.2.1 opens the file like this:
av.open(path, metadata_errors="ignore")
metadata_errors is the “what do I do about bad metadata” switch. PyAV 19 removed that keyword. So the same line on PyAV 19 raises immediately:
TypeError: open() got an unexpected keyword argument 'metadata_errors'
The exception propagates, the transcription tool reports failure, and the gateway writes “could not be transcribed”. You see three words; the truth is a TypeError.
Why it broke now
Because faster-whisper is relaxed about PyAV: it declares av>=11. That constraint means “anything from 11 up”, so once PyAV 19 shipped, any install that re-resolved dependencies happily took it — an unlocked resolve today picks av==19.0.2.
Which gives two very different fates on the same machine:
- Locked install:
uv.lockpinsav==18.1.0, the combination is good, everything works. - Unlocked install (installing the
hermes-agent[stt-whisper]extra, or rebuilding a virtualenv): the resolver takes 19, and voice dies.
That also explains “it worked yesterday”: your actions were not the trigger, a dependency reinstall was. A container rebuild, a pip install -U, a Python version bump, even a cold CI cache can do it.
Why upgrading cannot fix it
The natural move is “upgrade the library to the fixed version”. That is not available here, for concrete reasons:
- The newest
faster-whisperon PyPI is still 1.2.1 — there is no newer release to install. - Upstream has actually fixed it (
SYSTRAN/faster-whisper#1495), but that fix is not in any release yet.
So between “wait for upstream” and “be able to transcribe today”, one option is left: hold PyAV below 19.
The fix: pin av to 18.1.0
PR #150984, merged on November 8, does exactly that, and each step has a reason:
av>=11,<19becomesav==18.1.0. This repository exact-pins its direct dependencies by convention (stated at the top ofpyproject.toml), so an exact pin, not an upper bound.- Why 18.1.0: it shipped on August 12, 2026 — well past the repo’s two-week age rule — and it was already the locked version. This does not introduce a stranger; it writes the known-good pairing into the constraint.
- Platform markers match
faster-whisperexactly:win32-arm64(noctranslate2wheel) anddarwin-x64(noonnxruntimewheel) already skip the local STT path, plussys_platform != 'android'. uv.lockwas regenerated, and the diff is only the four lines recording the new requirement — no resolved version changes. That matters: a fix should not quietly upgrade anything else.
Both extras are pinned: [voice] (voice input and wake words) and [stt-whisper] (standalone local transcription) pull the same packages, and missing one would leave people exposed through the other door.
Check it and fix it on your own machine
Confirm the diagnosis directly by looking at PyAV’s version:
python -c "import av; print(av.__version__)"
If it says 19.x, you are probably in this hole. To see it precisely, reproduce the call:
python -c "import av; av.open('/path/to/any.wav', metadata_errors='ignore')"
On 19 it raises TypeError right away, word for word.
If you manage your own virtualenv rather than a Hermes locked install, the quickest stopgap is to bring it back down:
pip install 'av==18.1.0'
Then restart the gateway (or whatever process runs STT) and send a voice note. On an official install, upgrade to a build that carries this pin and you do not have to touch anything.
And if you would rather not run a model locally at all, there is a path that never touches PyAV: send transcription to a cloud provider. The DashScope transcription plugin covers that setup, and it suits machines that are modest or that you do not want to maintain models on.
Three things worth keeping
One: “the lockfile is fine” is not “the install is fine”. Locked installs never broke here; unlocked ones did. If anything in your deployment re-resolves dependencies — a Docker build, CI, installing one more package — you own both environments, and they behave differently.
Two: only a direct dependency can cap a transitive one. When faster-whisper declared av>=11, it could not have anticipated that 19 would delete an argument; semantic versioning offers limited protection against “keyword removed”. When upstream is not going to release soon, an exact pin is the honest answer — it admits “we know which combination works”.
Three: the error gets flattened at the finish line. You see “could not be transcribed”; the TypeError sits in the log. For any “this whole feature stopped working” problem, the first stop is the exception in the log, not the sentence on screen. If you do not habitually read logs yet, the site’s hermes doctor reference is a reasonable first health check.
One aside: if you are building a voice front end — say, wiring Hermes into a speaker at home — the full local pipeline is described in connecting Hermes to Home Assistant, and it rides on the same dependency stack discussed here.
Status
This pin (PR #150984) is on main, merged November 8, 2026. In v0.23.0, pyproject.toml has no av line at all — PyAV came in purely as a transitive dependency of faster-whisper back then. So: older version plus a locked install equals fine; older version plus an unlocked install equals a coin flip.
Either upgrade to a build with the pin, or pin av back to 18.1.0 by hand. And do not install local STT with a loose av>=11 constraint — that is not configuration freedom, that is a time bomb.