Toda mensagem de voz parou de transcrever da noite para o dia: PyAV 19 contra um argumento no faster-whisper 1.2.1


7h30 no trajeto, você manda três áudios para o seu bot Hermes no Telegram: as três tarefas do dia, uma conclusão de uma reunião da qual acabou de sair, e um teste descartável para ver se a conexão funciona. No escritório você abre o notebook e os três respondem com a mesma linha — não foi possível transcrever.

Você não atualizou nada. Não mexeu em config. Ontem funcionava. E a parte mais estranha: mensagens de texto estão normais. Só o caminho de voz está morto.

Falhas em que “nada mudou” quase nunca são código de aplicação. São dependências se movendo enquanto você não olhava. Esta é um caso de manual.

O sintoma e o culpado de verdade

A transcrição local é um pipeline pequeno: a plataforma entrega o arquivo de voz, o Hermes passa para o motor de STT local (faster-whisper, rodando sobre ctranslate2), e a decodificação de áudio vai pelo PyAV — o binding de Python para o FFmpeg. Quando a transcrição falha, o gateway marca a mensagem como [voice message could not be transcribed] e, se o áudio foi gravado em disco, anexa o caminho para você transcrever depois por conta própria.

A falha acontece uma camada abaixo, na decodificação. O faster-whisper 1.2.1 abre o arquivo assim:

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

metadata_errors é o interruptor de “o que fazer com metadado ruim”. O PyAV 19 removeu esse keyword. Então a mesma linha no PyAV 19 estoura na hora:

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

A exceção sobe, a ferramenta de transcrição reporta falha e o gateway escreve “não foi possível transcrever”. Você vê três palavras; a verdade é um TypeError.

Por que quebrou agora

Porque o faster-whisper é relaxado com o PyAV: ele declara av>=11. Essa restrição significa “qualquer coisa de 11 para cima”, então assim que o PyAV 19 saiu, qualquer instalação que re-resolvesse dependências o pegou de bom grado — um resolve sem lock hoje escolhe av==19.0.2.

O que dá dois destinos bem diferentes na mesma máquina:

  • Instalação com lock: o uv.lock fixa av==18.1.0, a combinação está boa, tudo funciona.
  • Instalação sem lock (instalar o extra hermes-agent[stt-whisper] ou reconstruir um virtualenv): o resolver pega a 19, e a voz morre.

Isso também explica o “funcionava ontem”: o gatilho não foi o que você fez, foi uma reinstalação de dependência. Um rebuild de container, um pip install -U, um upgrade de versão do Python, até um cache de CI frio fazem isso.

Por que atualizar não resolve

O movimento natural é “atualiza a biblioteca para a versão corrigida”. Não está disponível aqui, por motivos concretos:

  • O faster-whisper mais novo no PyPI ainda é o 1.2.1 — não existe release mais recente para instalar.
  • O upstream já corrigiu (SYSTRAN/faster-whisper#1495), mas a correção ainda não está em nenhum release.

Então, entre “esperar o upstream” e “conseguir transcrever hoje”, sobra uma opção: segurar o PyAV abaixo da 19.

A correção: fixar av em 18.1.0

O PR #150984, mergeado em 8 de novembro, faz exatamente isso, e cada passo tem motivo:

  • av>=11,<19 vira av==18.1.0. Este repositório fixa suas dependências diretas de forma exata, por convenção (declarada no topo do pyproject.toml), então um pin exato, não um limite superior.
  • Por que 18.1.0: saiu em 12 de agosto de 2026 — bem além da regra de duas semanas de idade do repositório — e já era a versão do lock. Não introduz um desconhecido; escreve na restrição o emparelhamento que se sabe bom.
  • Os platform markers batem com o faster-whisper: win32-arm64 (sem wheel de ctranslate2) e darwin-x64 (sem wheel de onnxruntime) já pulam o caminho de STT local, mais sys_platform != 'android'.
  • O uv.lock foi regerado, e o diff são só as quatro linhas que registram o novo requisito — nenhuma versão resolvida mudou. Isso importa: uma correção não deve atualizar outras coisas de fininho.

Os dois extras estão fixados: [voice] (entrada de voz e wake words) e [stt-whisper] (transcrição local isolada) puxam os mesmos pacotes, e deixar um de fora exporia gente pela outra porta.

Confira e conserte na sua máquina

Confirme o diagnóstico direto olhando a versão do PyAV:

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

Se disser 19.x, provavelmente você está nesse buraco. Para ver com precisão, reproduza a chamada:

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

Na 19 ele levanta TypeError na hora, palavra por palavra.

Se você gerencia o seu próprio virtualenv em vez de uma instalação com lock do Hermes, o contorno mais rápido é voltar a versão:

pip install 'av==18.1.0'

Depois reinicie o gateway (ou o processo que roda o STT) e mande um áudio. Numa instalação oficial, atualize para um build que carregue esse pin e você não precisa mexer em nada.

E se você preferir não rodar modelo nenhum localmente, existe um caminho que nunca toca no PyAV: mandar a transcrição para um provedor de nuvem. O plugin de transcrição DashScope cobre essa configuração, e ele cai bem em máquinas modestas ou que você não quer manter com modelos.

Três coisas que valem guardar

Um: “o lockfile está ok” não é “a instalação está ok”. Instalações com lock nunca quebraram aqui; as sem lock quebraram. Se algo no seu deploy re-resolve dependências — um build Docker, CI, instalar mais um pacote —, você tem os dois ambientes e eles se comportam diferente.

Dois: só uma dependência direta pode limitar uma transitiva. Quando o faster-whisper declarou av>=11, ele não tinha como prever que a 19 apagaria um argumento; versionamento semântico oferece proteção limitada contra “keyword removido”. Quando o upstream não vai lançar tão cedo, um pin exato é a resposta honesta — ele admite “a gente sabe qual combinação funciona”.

Três: o erro é achatado na linha de chegada. Você vê “não foi possível transcrever”; o TypeError está no log. Para qualquer problema de “a feature inteira parou de funcionar”, a primeira parada é a exceção no log, não a frase na tela. Se você ainda não tem o hábito de ler logs, a referência de hermes doctor do site é um primeiro check de saúde razoável.

Um aparte: se você está montando uma frente de voz — digamos, ligando o Hermes numa caixa de som em casa —, o pipeline local completo está descrito em conectando o Hermes ao Home Assistant, e ele anda sobre a mesma pilha de dependências discutida aqui.

Status

Este pin (PR #150984) está na main, mergeado em 8 de novembro de 2026. Na v0.23.0 o pyproject.toml não tem linha de av nenhuma — na época o PyAV entrava puramente como dependência transitiva do faster-whisper. Resumindo: versão antiga com instalação travada dá certo; versão antiga com instalação solta é cara ou coroa.

Ou atualize para um build com o pin, ou fixe o av em 18.1.0 à mão. E não instale STT local com uma restrição frouxa de av>=11 — isso não é liberdade de configuração, isso é uma bomba-relógio.