Über Nacht hörte jede Sprachnachricht auf zu transkribieren: PyAV 19 gegen ein einziges Argument in faster-whisper 1.2.1

7:30 auf dem Weg zur Arbeit, du schickst drei Sprachnotizen an deinen Hermes-Bot in Telegram: die drei Todos von heute, eine Schlussfolgerung aus einem Meeting, das du gerade verlassen hast, und ein Wegwerf-Test, ob die Verbindung überhaupt geht. Im Büro öffnest du den Laptop, und alle drei antworten mit derselben Zeile – could not transcribe.
Du hast nichts upgedatet. Keine Config geändert. Gestern lief es. Und das Seltsamste: Textnachrichten sind fein. Nur der Voice-Pfad ist tot.
Fehler, bei denen „nichts geändert“ wurde, sind fast nie Anwendungscode. Es sind Dependencies, die sich bewegt haben, während du nicht hingesehen hast. Dieser hier ist ein Lehrbuchfall.
Das Symptom und der eigentliche Übeltäter
Lokale Transkription ist eine kleine Pipeline: Die Plattform liefert eine Voice-Datei, Hermes reicht sie an die lokale STT-Engine (faster-whisper, laufend auf ctranslate2), und das Audio-Decoding geht über PyAV – Pythons Binding an FFmpeg. Wenn die Transkription scheitert, labelt das Gateway die Nachricht mit [voice message could not be transcribed] und hängt den Pfad an, wenn das Audio auf Platte geschrieben wurde, damit du es später selbst transkribieren kannst.
Der Fehler passiert eine Schicht tiefer, im Decoding. faster-whisper 1.2.1 öffnet die Datei so:
av.open(path, metadata_errors="ignore")
metadata_errors ist der Schalter für „was mache ich bei kaputten Metadaten“. PyAV 19 hat dieses Keyword entfernt. Dieselbe Zeile wirft auf PyAV 19 also sofort:
TypeError: open() got an unexpected keyword argument 'metadata_errors'
Die Exception propagiert, das Transkriptions-Tool meldet Fehlschlag, und das Gateway schreibt „could not be transcribed“. Du siehst drei Wörter; die Wahrheit ist ein TypeError.
Warum es jetzt kaputtging
Weil faster-whisper bei PyAV entspannt ist: Es deklariert av>=11. Diese Constraint heißt „alles ab 11“, also nahm jede Installation, die Dependencies neu auflöst, PyAV 19 bereitwillig – ein ungelockter Resolve wählt heute av==19.0.2.
Das ergibt zwei sehr unterschiedliche Schicksale auf derselben Maschine:
- Gelockter Install:
uv.lockpinntav==18.1.0, die Kombination passt, alles läuft. - Ungelockter Install (das Extra
hermes-agent[stt-whisper]installieren oder ein Virtualenv neu bauen): Der Resolver nimmt 19, und Voice stirbt.
Das erklärt auch das „gestern lief es“: Deine Aktionen waren nicht der Auslöser, ein Dependency-Reinstall war es. Ein Container-Rebuild, ein pip install -U, ein Sprung bei der Python-Version, sogar ein kalter CI-Cache können das auslösen.
Warum ein Upgrade es nicht repariert
Der naheliegende Schritt ist „die Library auf die gefixte Version upgraden“. Das geht hier nicht, aus konkreten Gründen:
- Das neueste
faster-whisperauf PyPI ist weiterhin 1.2.1 – es gibt kein neueres Release zum Installieren. - Upstream hat es tatsächlich gefixt (
SYSTRAN/faster-whisper#1495), aber dieser Fix ist noch in keinem Release.
Zwischen „auf Upstream warten“ und „heute transkribieren können“ bleibt also eine Option: PyAV unter 19 halten.
Der Fix: av auf 18.1.0 pinnen
PR #150984, gemergt am 8. November, macht genau das, und jeder Schritt hat einen Grund:
av>=11,<19wird zuav==18.1.0. Dieses Repo pinnt seine direkten Dependencies per Konvention exakt (steht oben inpyproject.toml), also ein exakter Pin, keine Obergrenze.- Warum 18.1.0: Es erschien am 12. August 2026 – deutlich jenseits der Zwei-Wochen-Altersregel des Repos – und war bereits die gelockte Version. Das führt keinen Fremden ein, sondern schreibt die bekannt gute Paarung in die Constraint.
- Die Platform-Marker entsprechen
faster-whisperexakt:win32-arm64(keinctranslate2-Wheel) unddarwin-x64(keinonnxruntime-Wheel) überspringen den lokalen STT-Pfad ohnehin, plussys_platform != 'android'. uv.lockwurde neu generiert, und der Diff sind nur die vier Zeilen, die die neue Anforderung festhalten – keine geänderten aufgelösten Versionen. Das ist wichtig: Ein Fix sollte nicht stillschweigend irgendetwas anderes upgraden.
Beide Extras sind gepinnt: [voice] (Voice-Eingabe und Wake-Words) und [stt-whisper] (standalone lokale Transkription) ziehen dieselben Pakete, und eines zu vergessen würde Leute durch die andere Tür offen lassen.
Prüfen und selbst reparieren
Bestätige die Diagnose direkt, indem du dir die PyAV-Version ansiehst:
python -c "import av; print(av.__version__)"
Steht da 19.x, sitzt du wahrscheinlich in diesem Loch. Um es genau zu sehen, reproduziere den Call:
python -c "import av; av.open('/path/to/any.wav', metadata_errors='ignore')"
Auf 19 wirft das sofort einen TypeError, wortwörtlich.
Wenn du dein Virtualenv selbst verwaltest statt eines gelockten Hermes-Installs, ist der schnellste Stopgap, es wieder herunterzubringen:
pip install 'av==18.1.0'
Dann starte das Gateway neu (oder welchen Prozess auch immer STT fährt) und schick eine Sprachnotiz. Bei einem offiziellen Install upgrade auf einen Build mit diesem Pin, dann musst du nichts anfassen.
Und wenn du lieber gar kein Modell lokal laufen lassen willst, gibt es einen Pfad, der PyAV nie berührt: Transkription an einen Cloud-Provider geben. Das DashScope-Transkriptions-Plugin deckt dieses Setup ab, und es passt zu Maschinen, die bescheiden sind oder auf denen du keine Modelle pflegen willst.
Drei Dinge, die du behalten solltest
Erstens: „die Lockfile ist okay“ ist nicht „der Install ist okay“. Gelockte Installs gingen hier nie kaputt, ungelockte schon. Wenn irgendetwas in deinem Deployment Dependencies neu auflöst – ein Docker-Build, CI, ein weiteres Paket installieren –, hast du beide Umgebungen, und sie verhalten sich unterschiedlich.
Zweitens: Nur eine direkte Dependency kann eine transitive deckeln. Als faster-whisper av>=11 deklarierte, konnte es nicht ahnen, dass 19 ein Argument löscht; semantische Versionierung bietet begrenzten Schutz gegen „Keyword entfernt“. Wenn Upstream nicht bald releast, ist ein exakter Pin die ehrliche Antwort – er gibt zu: „wir wissen, welche Kombination funktioniert“.
Drittens: Der Fehler wird auf der Ziellinie plattgemacht. Du siehst „could not be transcribed“; der TypeError steht im Log. Bei jedem „dieses ganze Feature funktioniert nicht mehr“ ist der erste Halt die Exception im Log, nicht der Satz auf dem Bildschirm. Wenn du Logs noch nicht gewohnheitsmäßig liest, ist die hermes doctor-Referenz der Seite ein vernünftiger erster Health-Check.
Ein Nebenaspekt: Wenn du ein Voice-Frontend baust – sagen wir, Hermes an einen Lautsprecher zu Hause anschließen –, ist die komplette lokale Pipeline in Hermes mit Home Assistant verbinden beschrieben, und sie reitet auf demselben Dependency-Stack, um den es hier geht.
Status
Dieser Pin (PR #150984) ist auf main, gemergt am 8. November 2026. In v0.23.0 hat pyproject.toml überhaupt keine av-Zeile – PyAV kam damals rein als transitive Dependency von faster-whisper. Also: ältere Version plus gelockter Install ergibt okay; ältere Version plus ungelockter Install ergibt Münzwurf.
Entweder auf einen Build mit dem Pin upgraden oder av von Hand auf 18.1.0 zurückpinnen. Und installiere lokales STT nicht mit einer lockeren av>=11-Constraint – das ist keine Konfigurationsfreiheit, das ist eine Zeitbombe.