dimastatz/whisper-flow

Whisper Flow – 基于 OpenAI Whisper 的实时转录

它能做什么 – Whisper Flow 在一个轻量级的 FastAPI 服务中封装了 OpenAI Whisper 语音转文本模型，该服务通过 WebSocket 接收实时音频流，并以 JSON 格式返回部分和最终的转录结果。它将原本只能处理完整文件的 Whisper 转换为低延迟的流式 ASR 引擎。

它是如何工作的

• 客户端打开 ws://<host>:8181/ws 并以二进制帧的形式发送原始 PCM 音频（16 kHz，单声道，int16）。
• 服务器缓冲传入的数据块，将其分组为 时间窗口（滑动窗口），并对每个片段运行 Whisper。
• 每次推理完成后，会推送一个 JSON 负载：

  {"is_partial": true|false, "data": {"text": "…"}, "time": <ms>}
  

  is_partial 表示转录内容是否可能继续变化；当语音暂停、窗口限制达到或客户端发送 flush/stop 控制帧时，会发出最终结果。
• 提供一个小型 HTTP 端点（GET /ready），用于报告协议版本以及当前可用的 Whisper 模型文件。

核心组件

模块	作用
whisperflow.transcriber	加载 Whisper 模型（默认为 tiny.en.pt），并提供同步（transcribe_pcm_chunks）和异步（transcribe_pcm_chunks_async）辅助函数。
whisperflow.streaming	实现 TranscribeSession，用于管理每个客户端的状态，缓冲音频块，调用转录器，并将 JSON 结果通过 WebSocket 返回。
FastAPI 服务器	暴露 WebSocket 端点、健康检查（/health）以及批量转录 POST 请求（/transcribe_pcm_chunk）。

快速入门

1. 安装 – Python 3.8+，PortAudio（用于 PyAudio），然后运行 ./run.sh -local，该命令会创建虚拟环境，安装 requirements.txt，格式化代码，进行代码检查并运行测试套件。
2. 运行 – ./run.sh -run-server 在端口 8181 上启动服务。通过 http://localhost:8181/health 验证服务状态。
3. 使用 – 可以连接一个流式传输 PCM 音频的 WebSocket 客户端，或者安装该包（pip install whisperflow），并按照 README 示例直接调用库函数。

性能 – 在 Apple M1（16 GB 内存）上使用 LibriSpeech 进行基准测试，平均延迟约为每部分结果 275 ms，词错误率（WER）约为 7 %，满足亚秒级实时目标。

部署选项

• Docker – ./run.sh -docker 构建镜像（whisperflow-image）并运行容器，暴露端口 8181。
• Python 包 – 该库可被导入其他项目，支持自定义 WebSocket 服务器或与现有流水线集成。

路线图 – v1.3 计划通过更广泛的 py‑speech 生态系统暴露该包。

---

所有细节均直接取自仓库的 README。