TypeError: open() got an unexpected keyword argument ‘metadata_errors’

问题场景

用户在 Windows 上使用 faster-whisper 转写音频，进入 transcribe() 流程后，调用内部 decode_audio() 解码输入音频文件时失败。环境中安装的 PyAV 为 19.0.0。

报错原文

File "...\.venv\Lib\site-packages\faster_whisper\transcribe.py", line 876, in transcribe
    audio = decode_audio(audio, sampling_rate=sampling_rate)

File "...\.venv\Lib\site-packages\faster_whisper\audio.py", line 46, in decode_audio
    with av.open(input_file, mode="r", metadata_errors="ignore") as container:
         ~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

File "...\.venv\Lib\site-packages\av\container\core.py", line 479, in av.container.core.open
    def open(

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

原因分析

faster-whisper 的 decode_audio() 在调用 av.open() 时使用了 metadata_errors="ignore" 参数，但当前安装的 PyAV 19.0.0 版本中 av.open() 不接受该关键字参数，因此抛出 TypeError。这属于 faster-whisper 与 PyAV 版本之间的不兼容，维护者已通过提交修复。

环境排查

• 确认 Python 版本（Issue 中为 3.14.8）。
• 确认操作系统（Issue 中为 Windows）。
• 确认已安装的 PyAV 版本，Issue 中为 av 19.0.0。
• 确认 faster-whisper 的来源与版本，是否已包含修复提交 2ce7f9d7a9fbe315a5804a33bf7224d42e101174。

解决步骤

1. 先确认 PyAV 版本是否为 19.0.0 及更快版本，可查看已安装的 av 包版本。
2. 临时规避：将 PyAV 降级到 19 以下（av < 19），以绕开该参数不被接受的问题。
3. 推荐修复：升级到包含修复提交的 faster-whisper 最新版本，执行：

   python -m pip install --force-reinstall --no-deps git+https://github.com/SYSTRAN/faster-whisper.git

4. 由于使用了 --no-deps，安装后自行确认其它依赖仍然满足，缺少的依赖需手动补齐。

验证方法

在完成升级或降级后，重新运行原本触发报错的 faster-whisper 转写流程，确认音频能够正常被 decode_audio() 解码，且不再出现 TypeError: open() got an unexpected keyword argument 'metadata_errors'。

参考来源

SYSTRAN/faster-whisper #1589

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。