项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-10-03 · 当前星标 ★ 1012
使用教程
ℹ 本教程由 AI 依据该项目 README 整理,个别步骤可能需要按你的环境微调。
环境要求
- Python 环境(README 未限定版本,需能创建 .venv 虚拟环境)
- 系统级 PortAudio 音频库
- Docker(仅 Docker 部署方式需要)
- 可访问 PyPI 以安装 whisperflow 及其依赖
安装与启动步骤
-
1安装 PortAudio
这是流式音频依赖。macOS 用 brew install portaudio,Fedora 用 sudo dnf install portaudio-devel;Windows 通常随 PyAudio 自带。
sudo apt-get install portaudio19-dev -
2安装 whisperflow 包
从 PyPI 安装这个包,即可获得流式分块与转写封装接口。
pip install whisperflow -
3获取项目源码
克隆仓库后才能使用其中的 run.sh 脚本,该脚本会统一管理环境与测试。
git clone https://github.com/dimastatz/whisper-flow.git cd whisper-flow -
4一键初始化环境
-local 会创建 .venv、安装 requirements、运行 black、pylint 与全部单元测试。
./run.sh -local -
5Docker 一键部署
脚本会删除旧容器与旧镜像,重新构建镜像并在 8888 端口启动服务。
./run.sh -docker -
6手动运行容器
已有 whisperflow-image 镜像时,用该命令启动容器,并把 8181 端口映射出来。
docker run --name whisperflow-container -p 8181:8181 -d whisperflow-image -
7编写 WebSocket 服务
用 FastAPI 建立 /ws 端点,接收二进制音频块,并在收到 flush 时输出缓冲区里剩余的内容。
from fastapi import FastAPI, WebSocket import whisperflow.streaming as st import whisperflow.transcriber as ts app = FastAPI() @app.websocket("/ws") async def websocket_endpoint(websocket: WebSocket): model = ts.get_model() async def transcribe_async(chunks: list): return await ts.transcribe_pcm_chunks_async(model, chunks) async def send_back_async(data: dict): await websocket.send_json(data) try: await websocket.accept() session = st.TranscribeSession(transcribe_async, send_back_async) while True: message = await websocket.receive() if message["type"] == "websocket.disconnect": break if message.get("bytes") is not None: session.add_chunk(message["bytes"]) elif message.get("text") == '{"type": "flush"}': await session.flush() finally: await session.stop()
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
model | 否 | get_model() 默认加载 tiny.en.pt,换成更大的模型可提高准确率 | tiny.en.pt |
WebSocket 路径 | 是 | 客户端连接地址,README 示例中注册为 /ws | /ws |
容器端口映射 | 否 | 一键脚本说明中为 8888,手动 docker run 示例映射 8181 | 8181:8181 |
flush 消息 | 否 | 收到该文本消息时,立即输出缓冲区中尚未转写的音频 | {"type": "flush"} |
如何确认成功
./run.sh -local 或 -test 全部通过即代码正常;Docker 方式下容器成功启动并监听对应端口即部署成功。
常见问题
Q:Windows 上安装 PortAudio 报错怎么办?
A:README 说明 Windows 下 PortAudio 通常随 PyAudio 的 wheel 一起安装,若仍失败请参考 PyAudio 官方文档排查。
Q:./run.sh -local 中途失败是什么原因?
A:脚本要求 black 格式化通过、pylint 达到 9.9/10、单元测试覆盖率 95%,任一项不达标都会中断,需先修复对应问题。
Q:手动 docker run 提示找不到镜像?
A:需先执行 ./run.sh -docker 构建出 whisperflow-image 镜像,再运行手动容器命令。
Q:服务端口到底用 8888 还是 8181?
A:一键脚本说明容器运行在 8888,手动 docker run 示例映射 8181:8181,以你实际使用的命令与映射为准。
Q:客户端如何得到最后一段文字?
A:向 WebSocket 发送文本消息 {"type": "flush"},服务会调用 session.flush() 输出缓冲区剩余内容。
注意事项
- README 未给出启动 WebSocket 服务的具体命令,示例代码只定义了 FastAPI 应用,需按 FastAPI 常规方式自行运行。
- 流式转写相比整文件批量转写速度更快,但 README 明确提示准确率可能有所下降。
- 首次使用需下载 Whisper 模型文件,请预留磁盘空间并保证依赖下载顺畅。
- run.sh 中的测试环节对代码质量与覆盖率有硬性门槛,本地二次开发时可能需先调整测试。
核心亮点
- 在 Whisper 之上封装流式分块与增量输出,省去自己处理音频切片和结果拼接
- 以 PyPI 包形式发布,Python 项目可快速安装集成,上手成本低
- 面向实时转写场景设计,比直接调用批量 Whisper 更贴近直播、会议等需求
不足之处
- 实时性受 Whisper 推理速度和音频块大小影响,低配设备上延迟可能明显
- 项目星标不足千,生态和长期维护情况有待观察
适用场景
- 会议或通话的实时字幕生成
- 直播、播客的边播边转文字
- 语音助手或客服系统的低延迟语音输入
替代项目
whisper.cpp、faster-whisper
上一篇:faster-whisper
下一篇:TheWhisper
同类项目推荐
SmartSpeaker
开源
用STM32+ESP8266自造一台能联网听话的智能音箱
一个基于云端语音识别的智能控制设备,类似于天猫精灵,小爱同学。采用的芯片为stm32f407,···
google-speech-v2
开源
逆向 Google 语音接口,免费实现语音转文字
:speech_balloon: Reverse Engineering Google's Speech To Text API (v2)
myG2P
开源
把缅甸语文字变音素,让语音识别和合成更准。
Myanmar (Burmese) Language Grapheme to Phoneme (myG2P) Conversion Dictionary for spe···
expo-speech-recognition
开源
Expo 应用一行接入设备端语音转文字
Speech Recognition for React Native Expo projects
voltip
开源
按住说话,松手出字,跨平台语音输入
Push-to-talk voice typing for Windows, macOS, Linux and Android. On-device or cloud ···
no-tipe-releases
开源
开口说话就能往任意应用里打字,本地云端都行
Free desktop dictation for macOS and Windows. Speak messages, emails and notes into ···
opentypeless
开源
按热键说话,任意应用直接出润色文本
Open-source AI voice typing for macOS, Windows, and Linux. Press a hotkey, speak nat···
OBS-captions-plugin
开源
OBS 直播自动生成实时字幕,静音观众也能看懂
Closed Captioning OBS plugin using Google Speech Recognition
willow
开源
本地运行、隐私安全的智能语音助手,替代 Echo 和 Google Home。
Open source, local, and self-hosted Amazon Echo/Google Home competitive Voice Assist···
