VoiceStudio — WhisperX 引擎¶

WhisperX 是 CUDA 和纯 CPU 主机上的默认 ASR 引擎：使用 faster-whisper（CTranslate2）进行转录，并额外执行一次 wav2vec2 强制对齐，将单词边界精确到 ±10–30 ms（Whisper 自身的时间戳为 ±100–300 ms）。这种单词级时间信息正是配音唇形同步所依赖的，因此自动检测会在 CTranslate2 可以使用 GPU 的任何地方优先选择它。

选择它¶

• 在 Model Catalogue 的 ASR 选项卡中，点击 WhisperX 行上的 使用；或
• 使用 OMNIVOICE_ASR_BACKEND=whisperx 固定它（环境变量始终优先于“设置”中的选择；如果两者都未设置，自动检测会按硬件选择）。

擅长领域¶

• 配音 — 强制对齐提供了唇形同步所需的精度级别。
• 批量转录，支持单词级字幕。
• 多说话人场景：它与 pyannote 说话人分离配合使用 — 参见 说话人分离。

平台支持¶

模型选择¶

• ASR_MODEL_WHISPERX — 默认值为 large-v3。接受常见的尺寸别名（tiny … large-v3、distil-large-v3）或完整的 HF 仓库 ID。权重在首次加载时下载 — 参见 downloading-models。
• OMNIVOICE_ALIGN_DEVICE — 强制指定 wav2vec2 对齐器的设备。对齐器支持约 20 种主要语言；其他语言保留 Whisper 原生的单词时间戳，而不会失败。

VRAM 预检与降级¶

将近满的 8 GB 显卡加载 fp16 large-v3 会导致 原生 CUDA 中止——没有 Python 异常，整个后端直接崩溃（#723）。因此，每次加载前，引擎都会根据每种计算类型的预算（float16 5.0 GB、int8_float16 3.5 GB、int8 3.0 GB，更小的模型按比例缩小）检查可用 VRAM，并降级计算类型——或回退到 CPU int8——而不是启动一个会导致进程终止的加载。可通过 OMNIVOICE_ASR_VRAM_PREFLIGHT=0 禁用。

加载时还会运行另外两条回退链：

• 不支持高效 fp16 的 GPU（较老的 Maxwell/Pascal、GTX 16xx）会引发计算类型错误——引擎会依次重试 int8_float16，然后 int8（#551）。
• 真正的 CUDA OOM（内存不足）会在 CPU int8 上重试，因此配音仍能完成（速度较慢，但模型和精度相同）。

注意事项¶

• CUDA 上需要 cuDNN 8。 CTranslate2 链接的是 cuDNN 8；如果缺失，进程会快速失败且没有回溯信息，因此引擎会被提前报告为不可用，选择会回退到 pytorch-whisper，后者使用 torch 自带的 cuDNN 9（#1371）。
• 内核拒绝可执行栈。 CTranslate2 4.4.0 及更早版本附带的库会请求可执行栈，某些 Linux 内核在加载时会拒绝这些库（whisperx 在 Python 3.11 上固定了其中一个版本）。VoiceStudio 会在首次探测引擎时自动清除库文件中的该标志。如果文件是只读的，引擎会被报告为不可用，并附上需要运行一次的 patchelf --clear-execstack <library> 命令（#692）。
• 部分安装的环境（同步中断、防病毒隔离）可能破坏 WhisperX 的深层导入链（whisperx → pyannote → lightning_fabric）。此时引擎会被报告为不可用，并给出修复提示——重新安装，或在源码检出目录中执行 uv sync --reinstall（#1185）。
• 音频通过 VoiceStudio 验证过的 ffmpeg 解码，而不是直接查找 PATH 中的 ffmpeg（#479）。
• 转录有时间限制：每个配音块受 OMNIVOICE_TRANSCRIBE_CHUNK_TIMEOUT_S 限制（默认 120 秒），整个文件受 OMNIVOICE_ASR_TRANSCRIBE_TIMEOUT_S 限制（默认 300 秒）。在慢速硬件上处理超长文件时，请调高这些值。

各引擎间的速度对比见 性能。