ghcr.io/collabora/whisperlive-gpu:latest

WhisperLive

OpenAI Whisper的近实时实现。

本项目是一个实时转录应用程序，它使用OpenAI Whisper模型将语音输入转换为文本输出。可用于转录麦克风的实时音频输入和预先录制的音频文件。

• Installation
• Getting Started
• Running the Server
• Running the Client
• Advanced Features
• Word-Level Timestamps
• Custom Vocabulary / Hotwords
• Speaker Diarization
• Batch Inference
• Raw PCM Input
• Streaming Client (Manual Audio Chunking)
• Browser Extensions
• Whisper Live Server in Docker
• Troubleshooting
• Future Work
• Blog Posts
• Contact
• Citations

Installation

• 安装PortAudio（通过PyAudio进行麦克风输入所需的系统依赖）

bash scripts/setup.sh

在Debian/Ubuntu上，这会安装portaudio19-dev；在Fedora上安装portaudio-devel；在macOS上使用Homebrew安装portaudio。

• 安装3.12虚拟环境（在Fedora上执行sudo dnf install -y python3.12 python3.12-pip）

python3.12 -m venv whisper_env
source whisper_env/bin/activate

• 通过pip安装whisper-live

pip install whisper-live

OpenAI REST接口

服务器

python3 run_server.py --port 9090 --backend faster_whisper --max_clients 4 --max_connection_time 600 --enable_rest --cors-origins="http://localhost:8080,http://127.0.0.1:8080"

客户端

python3 client_openai.py $AUDIO_FILE

为TensorRT后端设置NVIDIA/TensorRT-LLM

• 请按照https://github.com/collabora/WhisperLive/blob/main/TensorRT_whisper.md设置https://github.com/NVIDIA/TensorRT-LLM并构建Whisper-TensorRT引擎。

Getting Started

服务器支持3种后端：faster_whisper、tensorrt和openvino。如果运行tensorrt后端，请遵循https://github.com/collabora/WhisperLive/blob/main/TensorRT_whisper.md。

Running the Server

• https://github.com/SYSTRAN/faster-whisper后端

python3 run_server.py --port 9090 \
--backend faster_whisper \
--max_clients 4 \
--max_connection_time 600

# 使用自定义模型和cache_dir运行，以保存自动转换的ctranslate2模型
python3 run_server.py --port 9090 \
--backend faster_whisper \
--max_clients 4 \
--max_connection_time 600 \
-fw "/path/to/custom/faster/whisper/model" \
-c ~/.cache/whisper-live/

• TensorRT后端。目前，我们建议仅通过Docker设置使用TensorRT。请遵循https://github.com/collabora/WhisperLive/blob/main/TensorRT_whisper.md，其工作正常。确保在使用TensorRT后端运行服务器之前构建TensorRT引擎。

# 运行仅支持英语的模型
python3 run_server.py -p 9090 \
-b tensorrt \
-trt /home/TensorRT-LLM/examples/whisper/whisper_small_en \
--max_clients 4 \
--max_connection_time 600

# 运行多语言模型
python3 run_server.py -p 9090 \
-b tensorrt \
-trt /home/TensorRT-LLM/examples/whisper/whisper_small \
-m \
--max_clients 4 \
--max_connection_time 600

[!NOTE] TensorRT后端默认使用C++会话。如果遇到问题（例如重复的CrossAttentionMask警告或崩溃），添加--trt_py_session标志以使用Python会话。

• 使用--max_clients选项限制服务器允许的客户端数量。默认为4。
• 使用--max_connection_time选项限制客户端的连接时间（以秒为单位）。默认为600。
• WhisperLive现在支持https://github.com/openvinotoolkit/openvino后端，可在Intel CPU、iGPU和dGPU上高效推理。目前，我们测试了https://huggingface.co/OpenVINO?search_models=whisper。

[!IMPORTANT] 推荐使用Docker：在Docker中运行带OpenVINO的WhisperLive会自动启用GPU支持（iGPU/dGPU），无需额外的主机设置。 [!NOTE] 原生（非Docker）使用：如果倾向于在Docker外运行，请确保系统上已安装并正确配置Intel驱动程序和OpenVINO运行时。参考https://docs.openvino.ai/2025/get-started/install-openvino.html?PACKAGE=OPENVINO_BASE&VERSION=v_2025_0_0&OP_SYSTEM=LINUX&DISTRIBUTION=PIP#的文档。

python3 run_server.py -p 9090 -b openvino

为faster_whisper后端设置AMD ROCm

• 请按照https://github.com/collabora/WhisperLive/blob/main/ROCm_whisper.md设置AMD ROCm GPU支持，使用CTranslate2 ROCm wheel。

控制OpenMP线程数

要控制OpenMP使用的线程数，可设置OMP_NUM_THREADS环境变量。这有助于管理CPU资源并确保性能一致。如果未指定，OMP_NUM_THREADS默认设置为1。可使用--omp_num_threads参数更改：

python3 run_server.py --port 9090 \
--backend faster_whisper \
--omp_num_threads 4

单模型模式

默认情况下，运行服务器时不指定模型，服务器会为每个客户端连接实例化一个新的whisper模型。这样做的优点是服务器可以根据客户端请求的模型大小使用不同的模型尺寸。但另一方面，这也意味着客户端连接时需要等待模型加载，并且（V）RAM使用量会增加。

当使用-trt指定自定义TensorRT模型或使用-fw指定自定义faster_whisper模型时，服务器会仅实例化一次自定义模型，然后在所有客户端连接中重用它。

如果不希望这样，设置--no_single_model。

Running the Client

使用以下命令运行客户端：

python3 run_client.py --files

默认连接到运行在9090端口的本地服务器。使用--server和--port标志可配置不同的服务器和端口。上述命令将转录通过--files标志提供的音频文件。

以下是 run_client.py 脚本中实现的客户端实例详情：

• lang：输入音频的语言，仅在使用多语言模型时适用。
• translate：若设为 True，则从任意语言翻译为 en（英语）。
• model：Whisper 模型大小。
• use_vad：是否在服务器端使用 Voice Activity Detection（语音活动检测）。
• save_output_recording：设为 True 可在实时转录期间将麦克风输入保存为 .wav 文件。此选项有助于录制会话供后续回放或分析。默认为 False。
• output_recording_filename：若 save_output_recording 设为 True，指定麦克风输入保存的 .wav 文件路径。
• mute_audio_playback：转录音频文件时是否静音播放。默认为 False。
• enable_translation：在服务器端启动翻译线程（从任意语言到任意语言）。
• target_language：服务器翻译线程的目标翻译语言。

from whisper_live.client import TranscriptionClient
client = TranscriptionClient(
"localhost",
9090,
lang="en",
translate=False,
model="small", # 也支持 hf_model => `Systran/faster-whisper-small`
use_vad=False,
save_output_recording=True, # 仅用于麦克风输入，默认 False
output_recording_filename="./output_recording.wav", # 仅用于麦克风输入
mute_audio_playback=False, # 仅用于文件输入，默认 False
enable_translation=True,
target_language="hi",
initial_prompt=None, # 为模型添加上下文，例如 'Jane Doe context'
)

它连接到运行在 localhost:9090 的服务器。使用多语言模型时，转录语言将被自动检测。你也可以使用 language 选项指定转录的目标语言，在本例中为英语（"en"）。如果希望从源语言翻译为英语，translate 选项应设为 True；如果希望用源语言转录，则设为 False。

• 转录音频文件：

client("tests/jfk.wav")

• 从麦克风转录：

client()

• 从 RTSP 流转录：

client(rtsp_url="rtsp://admin:admin@192.168.0.1/rtsp")

• 从 HLS 流转录：

client(hls_url="http://as-hls-ww-live.akamaized.net/pool_904/live/ww/bbc_1xtra/bbc_1xtra.isml/bbc_1xtra-audio%3d96000.norewind.m3u8")

高级特性

单词级时间戳

在转录片段中启用逐词时间和置信度分数：

client = TranscriptionClient(
"localhost", 9090,
word_timestamps=True,
)

启用后，WebSocket 响应中的每个片段包含 words 数组：

{
"segments": [{
"start": "0.000", "end": "2.500", "text": "Hello world",
"words": [
{"word": "Hello", "start": "0.000", "end": "0.800", "probability": 0.95},
{"word": " world", "start": "0.900", "end": "2.500", "probability": 0.88}
]
}]
}

自定义词汇表/热词

增强特定术语（产品名称、首字母缩写词、领域术语）的识别：

client = TranscriptionClient(
"localhost", 9090,
hotwords="WhisperLive,TensorRT,OpenVINO",
)

hotwords 参数是直接传递给 faster-whisper 关键词增强功能的逗号分隔字符串。REST API 中也可通过 hotwords 表单字段使用。

说话人分离

使用 pyannote.audio 嵌入进行实时说话人识别（可选依赖）：

pip install pyannote.audio

client = TranscriptionClient(
"localhost", 9090,
enable_diarization=True,
max_speakers=4,
)

启用后，已完成的片段包含 speaker 字段：

{"start": "0.000", "end": "2.500", "text": "Hello", "speaker": "SPEAKER_00", "completed": true}

分离功能使用说话人嵌入的在线余弦相似度聚类。若未安装 pyannote.audio，服务器会记录警告并继续运行（不启用分离功能）。

OpenAI 兼容的 REST 端点还接受 known_speaker_names 和上传的 known_speaker_references 多部分字段。当提供说话人字段且 response_format="verbose_json" 时，片段包含 speaker 字段。

批量推理

将多个客户端会话批量处理为单次 GPU 调用以提高吞吐量：

python3 run_server.py --port 9090 --backend faster_whisper \
--batch_inference --batch_max_size 8 --batch_window_ms 50

原始 PCM 输入

接受客户端的原始 PCM int16 音频（对嵌入式设备有用）：

python3 run_server.py --port 9090 --backend faster_whisper --raw_pcm_input

音频会自动归一化到 float32 范围 [-1.0, 1.0]。客户端也可在初始 WebSocket 选项中将 audio_format 设置为 float32（默认）、int16 或 uint8。

流式客户端（从任意源手动流式传输音频）

StreamingTranscriptionClient 允许你从任意源（实时麦克风捕获循环、网络流、音频管道等）推送原始 PCM 音频字节，并在检测到语音时通过回调接收转录文本。与 TranscriptionClient 不同，它不内部管理音频捕获；你可以控制音频的馈送时机和方式。

从音频文件读取并流式传输块的可运行示例位于 examples/manual_audio_chunking.py：

python examples/manual_audio_chunking.py --file assets/jfk.flac

使用示例：

from whisper_live.client import StreamingTranscriptionClient

client = StreamingTranscriptionClient(
"localhost", 9090,
lang="en",
model="small",
on_session_started=lambda: print("Server ready"),
on_partial_transcript=lambda text, segs: print(f"… {text}", end="\r"),
on_committed_transcript=lambda text, segs: print(f"✓ {text}"),
on_error=lambda e: print(f"Error: {e}"),
on_close=lambda: print("Closed"),
)

with client:
for chunk in my_audio_source: # 任意节奏、任意块大小
client.send(chunk, pcm_format="int16")

音频必须为 单声道、16 kHz PCM。支持以下两种格式：

可使用 send_array() 发送 NumPy 数组：

import numpy as np
samples = np.frombuffer(raw_bytes, dtype=np.int16)
client.send_array(samples)

回调函数

浏览器扩展

• 按照https://github.com/collabora/WhisperLive?tab=readme-ov-file#running-the-server所示，使用您所需的后端运行服务器。
• 通过我们的 Chrome 或 Firefox 扩展直接从浏览器转录音频。参考 https://github.com/collabora/whisper-live/tree/main/Audio-Transcription-Chrome#readme 和 https://github.com/collabora/WhisperLive/blob/main/TensorRT_whisper.md。

iOS 客户端

通过我们的原生 iOS 客户端在 iOS 上使用 WhisperLive。 有关设置和使用说明，请参考 https://github.com/collabora/WhisperLive/tree/main/Audio-Transcription-iOS 和 https://github.com/collabora/WhisperLive/blob/main/Audio-Transcription-iOS/README.md。

Docker 中的 Whisper Live 服务器

• GPU
  • Faster-Whisper

docker run -it --gpus all -p 9090:9090 ghcr.io/collabora/whisperlive-gpu:latest

• TensorRT。有关设置和更多 tensorrt 后端配置，请参考 https://github.com/collabora/WhisperLive/blob/main/TensorRT_whisper.md。

docker build . -f docker/Dockerfile.tensorrt -t whisperlive-tensorrt
  docker run -p 9090:9090 --runtime=nvidia --gpus all --entrypoint /bin/bash -it whisperlive-tensorrt

  # 构建 small.en 引擎
  bash build_whisper_tensorrt.sh /app/TensorRT-LLM-examples small.en # float16
  bash build_whisper_tensorrt.sh /app/TensorRT-LLM-examples small.en int8 # int8 仅权重量化
  bash build_whisper_tensorrt.sh /app/TensorRT-LLM-examples small.en int4 # int4 仅权重量化

  # 使用 small.en 运行服务器（选择一个引擎）
  python3 run_server.py --port 9090 \
  --backend tensorrt \
  --trt_model_path "/app/TensorRT-LLM-examples/whisper/whisper_small_en_float16"
  # 或 int8 / int4：
  # --trt_model_path "/app/TensorRT-LLM-examples/whisper/whisper_small_en_int8"
  # --trt_model_path "/app/TensorRT-LLM-examples/whisper/whisper_small_en_int4"

• OpenVINO

docker run -it --device=/dev/dri -p 9090:9090 ghcr.io/collabora/whisperlive-openvino

• AMD ROCm（通过 CTranslate2 ROCm wheel 在 AMD GPU 上运行 faster-whisper）

docker build -f docker/Dockerfile.rocm -t whisperlive-rocm .
  docker run --rm -it --device=/dev/kfd --device=/dev/dri \
  --group-add "$(getent group video | cut -d: -f3)" \
  --group-add "$(getent group render | cut -d: -f3)" \
  -p 9090:9090 whisperlive-rocm

• CPU
  • Faster-whisper

docker run -it -p 9090:9090 ghcr.io/collabora/whisperlive-cpu:latest

故障排除

macOS OpenMP 运行时冲突

在 macOS 上，尤其是 Intel Mac，faster_whisper/ctranslate2 可能与其他 Python 包加载的 OpenMP 运行时发生冲突。如果服务器因 OpenMP 运行时重复错误而中止，请使用 KMP_DUPLICATE_LIB_OK=TRUE 运行服务器：

KMP_DUPLICATE_LIB_OK=TRUE python3 run_server.py --port 9090 \
--backend faster_whisper \
--max_clients 4 \
--max_connection_time 600 \
--no_single_model

此解决方法适用于本地开发和测试。对于生产部署，建议使用仅加载一个 OpenMP 运行时的干净环境。

未来工作

• 在转录基础上添加其他语言的翻译功能。

博客文章

• 使用 WhisperLive 变革语音技术
• WhisperFusion：与 AI 聊天机器人的超低延迟对话（由 WhisperLive 提供支持）
• 打破语言障碍 2.0：迈向完全可靠、可生产的印地语 ASR（用于 WhisperLive 的印地语功能）

联系方式

我们可为开源和专有 AI 项目提供帮助。您可以通过 Collabora 网站或 *** 及 *** 与我们联系。

引用

@article{Whisper
title = {Robust Speech Recognition via Large-Scale Weak Supervision},
url = {https://arxiv.org/abs/2212.04356},
author = {Radford, Alec and Kim, Jong Wook and Xu, Tao and Brockman, Greg and McLeavey, Christine and Sutskever, Ilya},
publisher = {arXiv},
year = {2022},
}

@misc{Silero VAD,
author = {Silero Team},
title = {Silero VAD: pre-trained enterprise-grade Voice Activity Detector (VAD), Number Detector and Language Classifier},
year = {2021},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/snakers4/silero-vad}},
email = {hello@silero.ai}
}