whisper-flow

边说话边出字幕,把 Whisper 变成实时转写引擎

开源 🏷️完全免费 🔧 仅开源项目,无在线服务,需自行部署 语音识别 🍴 复刻 139 🐛 待处理 1 👀 关注 8
访问官网 ↗ GitHub ↗
GitHub 星标 ★ 1012
维护状态 活跃
是否开源 开源
定价模式 🏷️完全免费 开源免费,基于OpenAI Whisper模型

项目预览

whisper-flow 项目界面预览图
图片来源:GitHub 官方仓库名片

项目数据

分类语音识别
开发团队dimastatz
定价模式🏷️完全免费
价格说明开源免费,基于OpenAI Whisper模型
访问状态🔧 仅开源项目,无在线服务,需自行部署
是否开源是
开源协议MIT
主要语言Python
技术栈/模型pypi-package,python,speech-to-text,transcription,whisper
GitHub 星标★ 1012
上线时间2024-06-03 00:00:00
代码更新2026-11-15
仓库体积74.2 MB
本站数据更新2026-11-17
维护状态活跃
收录时间2026-10-03
浏览次数4

项目介绍

Whisper-Flow 是一个基于 OpenAI Whisper 模型的实时语音转写框架,专门解决传统 Whisper 只能整文件批量转写、无法边说话边出文字的问题。它把连续音频切成小块流式送入模型,并增量输出转写结果,让开发者能在通话、直播、会议等场景中获得近乎实时的字幕。项目用 Python 实现并发布到 PyPI,核心能力包括音频分块调度、流式推理封装和增量文本拼接,屏蔽了手动切音频、反复调用模型、处理上下文衔接等繁琐细节。对于想快速搭建实时字幕或语音助手原型的团队,它提供了比直接调用 Whisper 更贴近流式场景的抽象层,降低了从批量转写到实时转写的改造门槛。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整

数据来源:GitHub API 逐日快照 · 收录于 2026-10-03 · 当前星标 ★ 1012

使用教程

ℹ 本教程由 AI 依据该项目 README 整理,个别步骤可能需要按你的环境微调。

难度:进阶 约 20 分钟 部署方式:库/依赖 7 步

环境要求

  • Python 环境(README 未限定版本,需能创建 .venv 虚拟环境)
  • 系统级 PortAudio 音频库
  • Docker(仅 Docker 部署方式需要)
  • 可访问 PyPI 以安装 whisperflow 及其依赖

安装与启动步骤

  1. 1安装 PortAudio

    这是流式音频依赖。macOS 用 brew install portaudio,Fedora 用 sudo dnf install portaudio-devel;Windows 通常随 PyAudio 自带。

    sudo apt-get install portaudio19-dev
  2. 2安装 whisperflow 包

    从 PyPI 安装这个包,即可获得流式分块与转写封装接口。

    pip install whisperflow
  3. 3获取项目源码

    克隆仓库后才能使用其中的 run.sh 脚本,该脚本会统一管理环境与测试。

    git clone https://github.com/dimastatz/whisper-flow.git
    cd whisper-flow
  4. 4一键初始化环境

    -local 会创建 .venv、安装 requirements、运行 black、pylint 与全部单元测试。

    ./run.sh -local
  5. 5Docker 一键部署

    脚本会删除旧容器与旧镜像,重新构建镜像并在 8888 端口启动服务。

    ./run.sh -docker
  6. 6手动运行容器

    已有 whisperflow-image 镜像时,用该命令启动容器,并把 8181 端口映射出来。

    docker run --name whisperflow-container -p 8181:8181 -d whisperflow-image
  7. 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 示例映射 81818181: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,···

★ 313 2026-10-03
google-speech-v2 开源

逆向 Google 语音接口,免费实现语音转文字

:speech_balloon: Reverse Engineering Google's Speech To Text API (v2)

★ 468 2026-08-09
myG2P 开源

把缅甸语文字变音素,让语音识别和合成更准。

Myanmar (Burmese) Language Grapheme to Phoneme (myG2P) Conversion Dictionary for spe···

★ 65 2026-08-09
voltip 开源

按住说话,松手出字,跨平台语音输入

Push-to-talk voice typing for Windows, macOS, Linux and Android. On-device or cloud ···

★ 111 2026-11-17
no-tipe-releases 开源

开口说话就能往任意应用里打字,本地云端都行

Free desktop dictation for macOS and Windows. Speak messages, emails and notes into ···

★ 520 2026-10-19
opentypeless 开源

按热键说话,任意应用直接出润色文本

Open-source AI voice typing for macOS, Windows, and Linux. Press a hotkey, speak nat···

★ 687 2026-09-28
OBS-captions-plugin 开源

OBS 直播自动生成实时字幕,静音观众也能看懂

Closed Captioning OBS plugin using Google Speech Recognition

★ 1349 2026-10-01
willow 开源

本地运行、隐私安全的智能语音助手,替代 Echo 和 Google Home。

Open source, local, and self-hosted Amazon Echo/Google Home competitive Voice Assist···

★ 3140 2026-08-10