文档
WhisperX（手动安装）

WhisperX（手动安装）

VideoLingo 默认的本地语音识别是 Qwen3-ASR + Qwen3-ForcedAligner，见使用文档。WhisperX 仍然是一个本地后端（whisper.backend: whisperx，中文仍强制使用 Belle 模型），但不是安装器里的选项。setup_env.py 和 installer.py 都不会安装它，也不会询问要不要安装，也没有对应开关。本页是唯一的安装说明：额外依赖需要你自己安装。

以下情况可以考虑改用 WhisperX：想和 Qwen 的结果做对比；希望中文使用带标点增强的 Belle Whisper 模型；已有基于 WhisperX 的使用习惯。

支持范围

平台能否与默认环境共存说明
Windows / Linux可以在 VideoLingo 环境中追加安装，见下文。依赖解析已用 uv pip compile 验证（Python 3.13），Windows CPU 已实跑识别、pyannote 语音检测和对齐，无需系统 FFmpeg 或可用的 TorchCodec；Linux 推理未实跑
Apple Silicon Mac不可以默认的 MLX 后端需要 huggingface-hub>=1，WhisperX 3.8.6 需要 huggingface-hub<1。请另建一个独立环境使用 WhisperX，不要装进默认环境

安装

下面的命令由你自己执行。安装器不会代为执行，之后也不会把 WhisperX 装回去。

在 Windows 或 Linux 上完成安装后，从 VideoLingo 文件夹运行下面的命令。它使用项目的 .venv；如果使用 --shared，请把 .venv 换成共享环境的路径。不要在 Apple Silicon 的默认环境里执行；Mac 的独立环境见下文。

uv pip install --python .venv "whisperx>=3.8.6,<3.9" "ctranslate2>=4.5,<5" "pyannote-audio>=4.0.4,<5" "torchcodec>=0.7,<0.8"

这 4 个包的版本约束与 3.0.4 版本中 requirements.txt 的约束相同。WhisperX 3.8 需要 Torch/torchaudio 2.8、torchvision 0.23 和 Transformers 4，与默认环境一致，因此不需要改动已装的 PyTorch。

启用本地 WhisperX 后，运行 uv run start.py --check，检查 VideoLingo 实际使用的环境，并验证 FFmpeg 解码和 pyannote 内存波形路径，不要求 TorchCodec 文件解码器可用。Windows/Linux 上重跑安装器不会卸载自行添加的 WhisperX；Apple Silicon 默认环境会移除与 MLX 不兼容的 WhisperX 依赖，详见下文。

启用

在侧栏选择「语音识别运行环境：本地」→「本地识别后端：WhisperX（手动安装）」，或在 config.yaml 中设置：

whisper:
  runtime: 'local'
  backend: 'whisperx'
  model: 'large-v3'   # 仅 WhisperX 使用。large-v3-turbo 会被改写成 large-v3
  language: 'en'
  • whisper.model 只接受 large-v3。名字里含 turbo（包括 large-v3-turbo）会在加载前改成 large-v3，因为这条管线里 turbo 会循环复读。缓存键同样按 large-v3 计算。
  • 识别语言设为 zh 时，WhisperX 路径会强制使用 Huan69/Belle-whisper-large-v3-zh-punct-fasterwhisper，忽略 whisper.model。
  • 自动检测到中文但识别语言不是 zh 时，WhisperX 路径会报错，要求明确选择中文。
  • 识别结果缓存的键包含后端，WhisperX 和 Qwen 的结果不会互相复用。

GPU 运行库（CUDA 12 cuBLAS / cuDNN 9）

默认的 Qwen 路径只需要 PyTorch 自带的 CUDA 运行库。WhisperX 使用 CTranslate2（faster-whisper），GPU 运行时还需要进程能找到 CUDA 12 cuBLAS 和 cuDNN 9。依据为 faster-whisper GPU 要求 (opens in a new tab)和 CTranslate2 4.5 的 cuDNN 9 变更 (opens in a new tab)。

  • Windows 缺少这些库时，可从 NVIDIA 的 CUDA 12.8 Update 1 归档 (opens in a new tab)取得 CUDA 12 库，从 NVIDIA (opens in a new tab)选择 用于 CUDA 12 的 cuDNN 9。将实际 DLL 所在目录加入 PATH 后重开终端，不能把 PyTorch 包版本直接替换进示例 cuDNN 路径。
  • Linux 按上述 faster-whisper 文档，在启动 Python 前通过 LD_LIBRARY_PATH 暴露已安装的 cuBLAS/cuDNN 库。Docker 镜像基于 cudnn-runtime，已包含这些运行库。

FFmpeg：无需手动安装

VideoLingo 的 WhisperX 复用安装器自动提供的 FFmpeg 命令行程序。它先用 whisperx.audio.load_audio 解码，再把 NumPy 音频传给识别和对齐；WhisperX 传给 pyannote 的也是内存中的 waveform 和 sample_rate。pyannote 官方支持这条路径，即使 TorchCodec 加载失败也可以使用。因此本项目的 WhisperX 流程不需要额外下载共享库版 FFmpeg，也不需要配置 PATH。

Windows 本机已验证：WhisperX 3.8.6、pyannote-audio 4.0.7、TorchCodec 0.7.0，清空系统 PATH，只启用自动提供的 FFmpeg 8.0.1，并确认 TorchCodec 导入失败。实际调用本项目 WhisperX 后端，使用 tiny.en、CPU、pyannote 语音检测和逐词对齐，成功处理 15.05 秒英文音频并输出 35 个词。本次没有验证 large/Belle 模型及 Linux/macOS 推理。

TorchCodec 仍随可选依赖安装，以满足 pyannote 的 Python 包依赖。只有自行扩展代码、让 TorchCodec 或 pyannote 直接读取文件名时，才需要兼容的 FFmpeg 共享库（TorchCodec 0.7 支持 FFmpeg 4–7）；自动提供的静态程序不包含这些库。Windows 的 VIDEOLINGO_FFMPEG_DLL_DIR 可选覆盖仍保留给这类自定义用法。参见 pyannote 音频输入实现 (opens in a new tab)。

Apple Silicon：另建环境

在 Apple Silicon 上，默认依赖会安装 mlx-audio（要求 Transformers 5、huggingface-hub>=1），而 WhisperX 3.8.6 要求 huggingface-hub<1，两者不能装在同一个环境里。uv 只有选中预发布版 whisperx 3.8.7rc1 才能解出依赖，该组合未经验证，不建议使用。

如需在 Mac 上使用 WhisperX，请为它另建一个独立的虚拟环境，不要在默认环境里执行上面的安装命令。本仓库不提供这个独立环境的安装脚本，相关组合也没有经过验证。如果默认环境里已经装了 whisperx（例如从旧版本升级），重跑 installer.py 时会先卸载 WhisperX 整套依赖（whisperx、torchcodec、faster-whisper、ctranslate2、pyannote-*）（仍被其他已装包依赖的会保留），并且不会再装回去。在这套依赖卸掉之前，installer.py --check 会把两者共存判为错误。

常见报错

  1. local_files_only=True：所选 Whisper 本地模型或缓存不完整。检查模型目录及 config.json、model.bin、tokenizer.json，离线查找不能下载缺失权重，ping 成功也不能证明模型可用。
  2. cublas64_12.dll not found：进程找不到 CUDA 12 cuBLAS。按上面的 GPU 运行库 核对实际启动环境、Torch CUDA 包和库搜索路径，仅更新驱动不提供这个 DLL。
  3. Whisper 模型加载时无报错直接段错误 (Segfault)：ctranslate2 版本与 cuDNN 版本不匹配。确保 ctranslate2>=4.5.0（支持 cuDNN 9，PyTorch 2.6+ 自带 cuDNN 9）。
  4. RuntimeError: Weights only load failed：PyTorch ≥2.6 更改了 torch.load 的默认行为。已在 whisperX_local.py 中通过猴补丁修复，如果遇到此问题说明代码未正确更新。
  5. Streamlit 中 WhisperX 转录卡住不动（CPU/GPU 均空闲）：librosa.load() 在 Streamlit 的非主线程中死锁。已用 whisperx.audio.load_audio()（基于 ffmpeg 子进程）替换。如果遇到此问题说明代码未正确更新。
  6. TorchCodec could not load 警告：单独出现这条警告不影响本项目 WhisperX 流程，因为传给 pyannote 的是已解码的波形。运行 uv run start.py --check 验证这条音频路径。自行扩展代码让 pyannote 直接读取文件名时，才需要上述共享库解码器。
  7. WhisperX is not installed：whisper.backend 已设为 whisperx，但没有安装该包。识别会在准备音频之前停止。请按上面的步骤自行安装，或把 whisper.backend 改回 qwen。安装器不会替你安装 WhisperX。
使用文档技术文档