Toutes les notes vocales ont cessé d'être transcrites du jour au lendemain : PyAV 19 contre un argument dans faster-whisper 1.2.1


7 h 30 dans les transports : vous envoyez trois notes vocales à votre bot Hermes sur Telegram — les trois tâches du jour, une conclusion d’une réunion que vous venez de quitter, et un test jetable pour savoir si la connexion marche. Au bureau, vous ouvrez le portable et les trois répondent la même chose — could not transcribe.

Vous n’avez rien mis à jour. Vous n’avez changé aucune config. Ça marchait hier. Et le plus étrange : les messages texte passent très bien. Seul le chemin vocal est mort.

Les pannes où rien n’a changé ne viennent presque jamais du code applicatif. Elles viennent de dépendances qui bougent pendant que vous regardez ailleurs. Celle-ci est un cas d’école.

Le symptôme et le vrai coupable

La transcription locale est un petit pipeline : la plateforme livre un fichier vocal, Hermes le passe au moteur STT local (faster-whisper, qui tourne sur ctranslate2), et le décodage audio passe par PyAV — le binding Python vers FFmpeg. Quand la transcription échoue, le gateway étiquette le message [voice message could not be transcribed], et si l’audio a été écrit sur disque il ajoute le chemin pour que vous puissiez le transcrire vous-même plus tard.

La panne se produit une couche plus bas, dans le décodage. faster-whisper 1.2.1 ouvre le fichier comme ceci :

av.open(path, metadata_errors="ignore")

metadata_errors est l’interrupteur qui règle le sort des métadonnées abîmées. PyAV 19 a supprimé ce mot-clé. La même ligne sur PyAV 19 lève donc immédiatement :

TypeError: open() got an unexpected keyword argument 'metadata_errors'

L’exception remonte, l’outil de transcription signale un échec, et le gateway écrit could not be transcribed. Vous voyez trois mots ; la vérité est un TypeError.

Pourquoi ça casse maintenant

Parce que faster-whisper est indulgent avec PyAV : il déclare av>=11. Cette contrainte revient à accepter n’importe quelle version à partir de 11, donc dès que PyAV 19 est sorti, toute installation qui re-résout ses dépendances l’a pris sans broncher — une résolution non verrouillée aujourd’hui choisit av==19.0.2.

D’où deux sorts très différents sur la même machine :

  • Installation verrouillée : uv.lock épingle av==18.1.0, la combinaison est bonne, tout fonctionne.
  • Installation non verrouillée (installer l’extra hermes-agent[stt-whisper], ou reconstruire un virtualenv) : le résolveur prend 19, et la voix meurt.

Ça explique aussi le fait que ça marchait la veille : ce ne sont pas vos actions qui ont déclenché, c’est une réinstallation de dépendance. Un rebuild de conteneur, un pip install -U, un changement de version de Python, même un cache CI froid peuvent le faire.

Pourquoi mettre à jour ne peut pas le corriger

Le réflexe naturel est de passer la bibliothèque à la version corrigée. Ce n’est pas disponible ici, pour des raisons concrètes :

  • Le plus récent faster-whisper sur PyPI est toujours 1.2.1 — il n’y a pas de release plus récente à installer.
  • L’amont a bien corrigé (SYSTRAN/faster-whisper#1495), mais ce correctif n’est encore dans aucune release.

Donc entre attendre l’amont et pouvoir transcrire aujourd’hui, il reste une option : maintenir PyAV sous 19.

Le correctif : épingler av en 18.1.0

La PR #150984, fusionnée le 8 novembre, fait exactement ça, et chaque étape a sa raison :

  • av>=11,<19 devient av==18.1.0. Ce dépôt épingle exactement ses dépendances directes par convention (c’est écrit en haut de pyproject.toml), donc une épingle exacte, pas une borne haute.
  • Pourquoi 18.1.0 : sortie le 12 août 2026 — bien au-delà de la règle des deux semaines du dépôt — et elle était déjà la version verrouillée. Ça n’introduit pas un inconnu ; ça inscrit dans la contrainte la paire qu’on sait bonne.
  • Les marqueurs de plateforme collent exactement à faster-whisper : win32-arm64 (pas de wheel ctranslate2) et darwin-x64 (pas de wheel onnxruntime) sautent déjà le chemin STT local, plus sys_platform != 'android'.
  • uv.lock a été régénéré, et le diff ne contient que les quatre lignes qui enregistrent la nouvelle exigence — aucune version résolue ne change. Ça compte : un correctif ne doit pas mettre à jour autre chose en douce.

Les deux extras sont épinglés : [voice] (entrée vocale et mots d’activation) et [stt-whisper] (transcription locale autonome) tirent les mêmes paquets, et en oublier un laisserait des gens exposés par l’autre porte.

Vérifier et réparer sur votre machine

Confirmez le diagnostic directement en regardant la version de PyAV :

python -c "import av; print(av.__version__)"

Si ça affiche 19.x, vous êtes probablement dans ce trou. Pour en avoir le cœur net, reproduisez l’appel :

python -c "import av; av.open('/path/to/any.wav', metadata_errors='ignore')"

Sur 19, ça lève un TypeError tout de suite, mot pour mot.

Si vous gérez votre propre virtualenv plutôt qu’une installation verrouillée de Hermes, le stopgap le plus rapide est de le redescendre :

pip install 'av==18.1.0'

Puis redémarrez le gateway (ou le processus qui fait le STT) et envoyez une note vocale. Sur une installation officielle, passez à un build qui porte cette épingle et vous n’avez rien à toucher.

Et si vous préférez ne pas faire tourner de modèle en local du tout, il existe un chemin qui ne touche jamais PyAV : envoyer la transcription à un fournisseur cloud. Le plugin de transcription DashScope couvre cette installation, et il convient aux machines modestes ou à celles sur lesquelles vous ne voulez pas maintenir de modèles.

Trois choses à retenir

Un : un lockfile sain ne veut pas dire une installation saine. Les installations verrouillées n’ont jamais cassé ici ; les non verrouillées, si. Si quelque chose dans votre déploiement re-résout les dépendances — un build Docker, la CI, l’installation d’un paquet de plus — vous avez deux environnements, et ils se comportent différemment.

Deux : seule une dépendance directe peut plafonner une transitive. Quand faster-whisper déclarait av>=11, il ne pouvait pas anticiper que 19 supprimerait un argument ; le versionnage sémantique protège mal contre un mot-clé retiré. Quand l’amont ne va pas sortir de sitôt, une épingle exacte est la réponse honnête — elle admet qu’on sait quelle combinaison fonctionne.

Trois : l’erreur est aplatie à la ligne d’arrivée. Vous voyez could not be transcribed ; le TypeError est dans le log. Pour tout problème du type toute cette fonctionnalité s’est arrêtée, le premier réflexe est l’exception dans le log, pas la phrase à l’écran. Si vous n’avez pas encore l’habitude de lire les logs, la référence hermes doctor du site est un premier bilan de santé raisonnable.

Une parenthèse : si vous construisez un front vocal — par exemple brancher Hermes sur une enceinte à la maison — le pipeline local complet est décrit dans connecter Hermes à Home Assistant, et il repose sur la même pile de dépendances dont on parle ici.

État des lieux

Cette épingle (PR #150984) est sur main, fusionnée le 8 novembre 2026. Dans la v0.23.0, pyproject.toml n’a aucune ligne av — PyAV arrivait alors purement comme dépendance transitive de faster-whisper. Donc : ancienne version plus installation verrouillée égale tout va bien ; ancienne version plus installation non verrouillée égale pile ou face.

Soit vous passez à un build qui contient l’épingle, soit vous réépinglez av en 18.1.0 à la main. Et n’installez pas de STT local avec une contrainte lâche av>=11 — ce n’est pas de la liberté de configuration, c’est une bombe à retardement.