Todas las notas de voz dejaron de transcribirse de la noche a la mañana: PyAV 19 contra un argumento de faster-whisper 1.2.1


7:30 de la mañana en el trayecto, mandas tres notas de voz a tu bot de Hermes en Telegram: los tres to-dos de hoy, una conclusión de una reunión de la que acabas de salir y una prueba de usar y tirar para ver si la conexión funciona. En la oficina abres el portátil y las tres responden con la misma frase: no se pudo transcribir.

No actualizaste nada. No cambiaste ninguna configuración. Ayer funcionaba. Y lo más raro: los mensajes de texto van bien. Solo el camino de voz está muerto.

Los fallos en los que «no ha cambiado nada» casi nunca son código de aplicación. Son dependencias que se mueven mientras no miras. Este es un caso de manual.

El síntoma y el culpable real

La transcripción local es un pipeline pequeño: la plataforma entrega un archivo de voz, Hermes se lo pasa al motor STT local (faster-whisper, corriendo sobre ctranslate2) y la decodificación de audio va por PyAV, el binding de Python a FFmpeg. Cuando la transcripción falla, el gateway etiqueta el mensaje [voice message could not be transcribed] y, si el audio se escribió a disco, añade la ruta para que puedas transcribirlo tú más tarde.

El fallo ocurre una capa más abajo, en la decodificación. faster-whisper 1.2.1 abre el archivo así:

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

metadata_errors es el interruptor de «qué hago con los metadatos malos». PyAV 19 eliminó ese keyword. Así que la misma línea sobre PyAV 19 revienta de inmediato:

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

La excepción se propaga, la herramienta de transcripción reporta fallo y el gateway escribe «no se pudo transcribir». Tú ves tres palabras; la verdad es un TypeError.

Por qué se rompió justo ahora

Porque faster-whisper es laxo con PyAV: declara av>=11. Esa restricción significa «cualquier cosa desde la 11 en adelante», así que en cuanto salió PyAV 19, cualquier instalación que volviera a resolver dependencias se lo llevó tan contenta: una resolución sin lock hoy elige av==19.0.2.

Lo que da dos destinos muy distintos en la misma máquina:

  • Instalación con lock: uv.lock fija av==18.1.0, la combinación es buena, todo funciona.
  • Instalación sin lock (instalar el extra hermes-agent[stt-whisper], o reconstruir un virtualenv): el resolver toma la 19 y la voz muere.

Eso explica también el «ayer funcionaba»: el detonante no fue lo que hiciste tú, fue una reinstalación de dependencias. Un rebuild de contenedor, un pip install -U, un salto de versión de Python, incluso una caché de CI en frío pueden hacerlo.

Por qué actualizar no lo arregla

El movimiento natural es «actualizar la librería a la versión arreglada». Aquí no está disponible, por razones concretas:

  • La faster-whisper más nueva en PyPI sigue siendo la 1.2.1: no hay release posterior que instalar.
  • Upstream ya lo arregló (SYSTRAN/faster-whisper#1495), pero ese fix no está en ninguna release todavía.

Así que entre «esperar a upstream» y «poder transcribir hoy» queda una sola opción: mantener PyAV por debajo de la 19.

El fix: fijar av a 18.1.0

El PR #150984, mergeado el 8 de noviembre, hace justo eso, y cada paso tiene su motivo:

  • av>=11,<19 pasa a av==18.1.0. Este repositorio fija en exacto sus dependencias directas por convención (está escrito en la cabecera de pyproject.toml), así que un pin exacto, no un techo.
  • Por qué 18.1.0: salió el 12 de agosto de 2026, muy por encima de la regla de dos semanas de antigüedad del repo, y ya era la versión del lock. No mete un desconocido: escribe en la restricción el emparejamiento que ya se sabía bueno.
  • Los marcadores de plataforma coinciden exactamente con faster-whisper: win32-arm64 (sin wheel de ctranslate2) y darwin-x64 (sin wheel de onnxruntime) ya se saltan la ruta STT local, más sys_platform != 'android'.
  • Se regeneró uv.lock y el diff son solo las cuatro líneas que registran el nuevo requisito: ninguna versión resuelta cambia. Eso importa: un fix no debería actualizar nada más de tapadillo.

Los dos extras están fijados: [voice] (entrada de voz y wake words) y [stt-whisper] (transcripción local suelta) tiran de los mismos paquetes, y dejar uno fuera expondría a la gente por la otra puerta.

Compruébalo y arréglalo en tu máquina

Confirma el diagnóstico mirando la versión de PyAV:

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

Si dice 19.x, lo más probable es que estés en este agujero. Para verlo con precisión, reproduce la llamada:

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

En la 19 lanza TypeError al momento, palabra por palabra.

Si gestionas tu propio virtualenv en vez de una instalación con lock de Hermes, el apaño más rápido es volver a bajarla:

pip install 'av==18.1.0'

Luego reinicia el gateway (o el proceso que haga STT) y manda una nota de voz. En una instalación oficial, actualiza a una build que lleve este pin y no tienes que tocar nada.

Y si prefieres no correr ningún modelo en local, hay un camino que nunca pasa por PyAV: mandar la transcripción a un proveedor en la nube. El plugin de transcripción DashScope cubre esa configuración, y le va bien a máquinas modestas o a esas en las que no quieres mantener modelos.

Tres cosas que merece la pena quedarse

Uno: «el lockfile está bien» no es «la instalación está bien». Las instalaciones con lock no se rompieron aquí; las que no lo tienen, sí. Si algo en tu despliegue resuelve dependencias de nuevo —un build de Docker, CI, instalar un paquete más— tienes dos entornos en las manos y se comportan distinto.

Dos: solo una dependencia directa puede poner techo a una transitiva. Cuando faster-whisper declaró av>=11, no podía anticipar que la 19 borraría un argumento; el versionado semántico protege poco contra «keyword eliminado». Cuando upstream no va a sacar release pronto, un pin exacto es la respuesta honesta: admite «sabemos qué combinación funciona».

Tres: el error se aplana en la meta. Tú ves «no se pudo transcribir»; el TypeError está en el log. Para cualquier problema del tipo «esta funcionalidad entera dejó de funcionar», la primera parada es la excepción del log, no la frase en pantalla. Si todavía no tienes la costumbre de leer logs, la referencia de hermes doctor del sitio es un primer chequeo de salud razonable.

Un aparte: si estás montando un front end de voz —por ejemplo, conectando Hermes a un altavoz en casa— el pipeline local completo está descrito en conectar Hermes con Home Assistant, y va sobre la misma pila de dependencias de la que hablamos aquí.

Estado

Este pin (PR #150984) está en main, mergeado el 8 de noviembre de 2026. En la v0.23.0, pyproject.toml no tiene ninguna línea de av: entonces PyAV entraba solo como dependencia transitiva de faster-whisper. Así que: versión antigua más instalación con lock es igual a bien; versión antigua más instalación sin lock es igual a cara o cruz.

O actualizas a una build con el pin, o fijas av a 18.1.0 a mano. Y no instales STT local con una restricción suelta av>=11: eso no es libertad de configuración, es una bomba de relojería.