VoxFlow

VoxFlow 是一个面向中文输入场景的本地语音输入工具：监听本地触发，完成录音、转写、文本规范化与输入注入，最终把结果送到当前输入位置。

它不是只验证 ASR 能不能跑通的 demo，而是把触发、录音、推理、后处理、注入、桌面界面、打包分发和发布校验都落到了仓库里，适合继续开发、内测和交付。

当前仓库已经成功完成 Windows / Linux 发布包打包，GitHub Releases 可直接下载对应 zip 产物进行安装和验证。

项目演示视频：https://www.bilibili.com/video/BV1yPGH6AEHN

项目优势

• 本地优先：音频采集、推理、文本纠错和注入都在本机完成，对隐私、延迟和可控性更友好。
• 架构可替换：触发、录音、推理、后处理、注入分层清晰，替换某一层不会把整条链路绑死。
• 多后端可落地：统一 backend 接口已经接通 Faster-Whisper、Whisper ONNX 和 echo/null 验证链路，便于在开发、CPU fallback 和 GPU 发布之间切换。
• CUDA 路线已经跑通：Windows + RTX 2070 SUPER 环境里，CUDA 后端已经完成兼容和打包验证，1 分钟语音大约 1 秒出文本，当前最适合做主力 GPU 发布方案。
• 中文体验完整：默认串联 OpenCC 繁转简、术语词典归一和 FunASR 标点恢复，输出更接近可直接输入的中文文本，而不只是原始 ASR 结果。
• 测试链路友好：Linux 可以用 qpwgraph 做 PipeWire 录音重定向，Windows 可以用 VB-Audio Virtual Cable 做虚拟回采，不必强依赖实体麦克风，也更方便做稳定复现和回归测试。
• 录音反馈直接：主界面会在录音过程中持续显示最新转写，已完成分段还能即时刷到当前焦点；如果焦点暂时不在可输入框上，会等待后再继续注入，更贴近真实输入法体验。
• 交付链路完整：仓库同时具备 Python 入口、CLI、PyInstaller spec、构建验证 workflow 和 release workflow，Windows / Linux 都有明确的发布路径。

面向语音输入法的产品取舍

这个项目不是单纯追求单次转写分数，而是按“真实输入法”来做取舍：用户要的是更快把话变成可提交、可发送、可继续编辑的文本，而不是等待一条最慢但理论最优的 ASR 结果。

• 准确度：默认链路不是只交付原始识别文本，而是继续做 OpenCC 繁转简、术语词典归一和标点恢复，减少中文输入里常见的人名、术语、标点和格式修正成本。
• 易用性：VoxFlow 保留桌面 GUI、托盘、UDP 控制和真实文本注入，快捷键映射可以交给系统或第三方工具处理，避免 Python 进程长期持有全局键盘钩子，让安装、启动和日常使用更稳。
• 响应速度：GUI 和 UDP 服务优先启动，后端模型在后台加载；界面会先告诉用户“后端加载中”“模型预热中”“准备就绪”，录音过程中也会持续刷新最新文本，已完成分段会即时注入当前焦点，而不是把全部反馈都拖到录音结束之后。首次 warmup 默认开启，用一次受控的后台预热换后续首句更低的冷启动延迟。
• 成本：默认模型和后端选择偏向本地可运行与可发布，优先命中可用 GPU，其次回到 CPU int8；这样可以在多数机器上维持可接受的硬件门槛、包体大小和推理成本，而不是把方案绑定到高配显卡或持续云服务费用。
• 可控性：录音由用户显式开始和停止，VAD 负责停止后的静音裁剪，而不是让 VAD 直接决定何时结束整次输入；同时如果当前焦点不在可输入框，注入会等待而不是盲目把文本打到错误位置。这种设计牺牲了一点“全自动感”，换来更稳定的边界和更低的误截断风险。

这套取舍背后的核心思路是：先保证“能顺手输入”，再逐步拉高模型和后处理上限。对输入法来说，稳定、可预期、可恢复，通常比实验室环境里的极限精度更重要。

中文后处理 Before/After 示例

同一段更接近原始 ASR 连续输出的对话文本，在默认 OpenCC + 术语词典 + FunASR 标点恢复链路下，可以得到类似下面的效果：

原始 ASR：
錄音完成你現在方便嗎我想先確認一下另外今天下午要不要去新開的咖啡喝咖啡然後再聊聊昨天看的 movie 和新出的 music album 如果你那邊方便我們三點在地鐵站見

OpenCC + 词典 + FunASR 后：
录音完成。你现在方便吗？我想先确认一下。另外，今天下午要不要去新开的 cafe 喝 coffee，然后再聊聊昨天看的 movie 和新出的 music album。如果你那边方便，我们三点在地铁站见。

这个例子里，OpenCC 会先把“錄”“現”“確”“開”“邊”“鐵”等繁体字转成简体，词典把“新开的咖啡喝咖啡”归一成“新开的 cafe 喝 coffee”，并保留“movie / music album”这类中英混合术语，最后由 FunASR 标点恢复补出问号、逗号和句号。

架构概览

分层说明：

• 触发层：只接收本地 UDP 指令，物理快捷键交给系统或第三方工具映射，避免 Python 进程长期持有全局键盘钩子。
• 录音层：负责录音状态机、音频缓冲和停止后的静音裁剪，当前实现是 sounddevice + Silero-VAD，但保留了可替换录音器抽象。
• 推理层：通过统一 backend 接口接入 Faster-Whisper、provider-aware 的 Whisper ONNX，以及用于链路验证的 echo backend。
• 文本后处理层：转写结果默认先做 OpenCC 繁转简，再进入术语词典归一和 FunASR 标点恢复，确保更贴近中文输入结果。
• 注入层：根据平台能力选择真实输入、剪贴板或日志回退，避免某个桌面环境不可用时整条链路失效。
• 界面与控制层：PyQt6 GUI、托盘和控制器负责状态展示、后台预热、录音调度和生命周期管理。

更完整的架构说明见 docs/VoxFlow-Architecture.md，构建、打包和安装说明见 docs/Build-Packaging-Install.md。

当前已验证的后端结论

• Windows + NVIDIA CUDA：这是当前最稳的 GPU 路线。RTX 2070 SUPER 环境已经完成兼容和打包验证，1 分钟语音大约 1 秒出文本。
• Windows + DirectML：代码路径保留，但在 RTX 2070 SUPER 和当前本机环境里都容易爆显存，实际建议直接回退到 faster-whisper 的 int8 cpu。
• MIGraphX / ROCm：仓库保留相关 provider 路径，但当前没有对应显卡，暂时没有可对外承诺的验证结论。
• Vulkan / WebGPU：相关代码已经写完并可继续实验，但当前速度明显慢于 CUDA，不建议作为现阶段主力发布方案。

快速开始

Windows PowerShell：

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev,qt,audio,clipboard]"
python -m voxflow --gui --backend echo --recorder null

如果要启用 CUDA / ONNX 与默认中文后处理，再补装：

python -m pip install -e ".[onnx,cuda,punctuation]"
python scripts/check_backends.py
python -m voxflow --mini-gui

Windows 发布包无需安装 Python。当前稳定推荐优先下载 voxflow-windows-faster-whisper-int8-cpu-x86_64.zip 或 CUDA 的两个 zip：voxflow-windows-cuda-x86_64.zip 与 voxflow-windows-cuda-runtime-x86_64.zip；使用 CUDA 包时需要把两个 zip 解压到同一目录。如果 release 里仍保留 voxflow-windows-directml-x86_64.zip，更适合作兼容性测试而不是默认安装包。解压后运行 voxflow\voxflow.exe 即可。

Linux：

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev,qt,audio,clipboard]'
python -m voxflow --gui --backend echo --recorder null

如果要启用 ONNX / CUDA 与默认中文后处理，再补装：

python -m pip install -e '.[onnx,cuda,punctuation]'
python scripts/check_backends.py
python -m voxflow --mini-gui

推荐依赖

项目 extras：

• dev：测试和 lint，包含 pytest、ruff。
• qt：桌面 GUI，包含 PyQt6。
• audio：麦克风录音和 VAD 所需依赖，包含 sounddevice、faster-whisper。
• onnx：Whisper ONNX 后端所需依赖，并额外带上 onnxscript 与 imageio-ffmpeg；前者覆盖当前 PyTorch ONNX 导出链路，后者让宿主机缺少系统 ffmpeg 时也能解码常见音频文件。
• vulkan：Vulkan 后端占位 extra，配合自定义的 Vulkan-enabled ONNX Runtime 使用。
• webgpu：WebGPU 后端占位 extra，配合自定义的 WebGPU-enabled ONNX Runtime 使用。
• punctuation：FunASR 标点模型与导出链路，包含 funasr、funasr-onnx、modelscope、huggingface-hub、jieba、torch、torchaudio、onnx、onnxscript。
• clipboard：文本注入，包含 pyperclip、pyautogui。
• packaging：打包桌面程序，包含 pyinstaller。
• release：生成完整发布包的聚合 extra，配合基础依赖覆盖 GUI、录音、Faster-Whisper、FunASR 标点导出、注入和 PyInstaller。

OpenCC 繁转简是核心依赖，默认启用；FunASR 标点在默认配置中启用，发布包会内置标点模型。

GPU Runtime 需要单独按显卡安装：

• NVIDIA CUDA：python -m pip install -e '.[cuda]'
• Windows AMD/通用 GPU：python -m pip install -e '.[directml]'，但当前测试机上 DirectML 容易爆显存，不建议作为默认发布路线
• Linux AMD ROCm：python -m pip install -e '.[rocm]'，当前仓库没有对应显卡做稳定验证
• Linux Vulkan：python -m pip install -e '.[vulkan]'，再安装带 VulkanExecutionProvider 的 ONNX Runtime 构建；当前更适合作实验路径
• Linux WebGPU：python -m pip install -e '.[webgpu]'，再安装自己编出的 onnxruntime_webgpu wheel；当前速度明显慢于 CUDA
• 只跑 CPU：不额外安装 GPU runtime，onnx_auto 会落到 CPUExecutionProvider

cuda extra 会安装 onnxruntime-gpu 以及 ONNX Runtime 在 Windows 上需要的 CUDA 12/cuDNN 9 DLL 包。当前这台机器已经验证 .venv 可命中 CUDAExecutionProvider。

当前硬件和发布目标：

后端选择

默认配置在 config/voxflow.toml：

backend = "auto"
recorder = "sounddevice"
recorder_device = "CABLE Output"
model = "small"
language = "zh"
hf_endpoint = "https://hf-mirror.com"
whisper_device = "cpu"
whisper_compute_type = "int8"
punctuation_backend = "auto"

预导出 FunASR ONNX 标点模型默认先走这里配置的 hf_endpoint；如果该镜像不可用，下载脚本会自动回退到官方 Hugging Face，再决定是否进入 ModelScope 导出回退。

auto 默认按下面顺序选择后端：

CUDA -> faster-whisper(cpu,int8) -> 其他 ONNX provider

其中 onnx_auto 仍会按下面顺序选择其余 provider：

CUDA -> DirectML -> MIGraphX -> ROCm -> Vulkan -> WebGPU -> CPU

从代码路径上看，onnx_auto 仍会继续尝试这些 provider；但从当前已验证结果看，真正推荐的使用顺序更简单：Windows NVIDIA 机器直接用 onnx_cuda，DirectML 遇到显存问题就直接切回 faster_whisper 的 cpu/int8，其余 provider 先按实验路径看待。

DirectML 没有 ONNX Runtime provider 级的硬显存上限参数。Windows AMD/DirectML 建议在配置里使用更保守的 ONNX 设置：

onnx_batch_size = 1
onnx_chunk_length_s = 15
onnx_quantization = "dynamic_int8"

可显式指定后端：

python -m voxflow --backend auto --model medium
python -m voxflow --backend onnx_cuda --model medium
python -m voxflow --backend onnx_directml --model medium
python -m voxflow --backend onnx_vulkan --model medium
python -m voxflow --backend onnx_webgpu --model medium
python -m voxflow --backend faster_whisper --model medium --whisper-device cpu --whisper-compute-type int8
python -m voxflow --backend faster_whisper --model medium --whisper-device cuda --whisper-compute-type float16

Faster-Whisper CUDA 配置也可以写进 config/voxflow.toml：

backend = "faster_whisper"
whisper_device = "cuda"
whisper_compute_type = "float16"

验证命令

检查后端和 ONNX provider：

python scripts/check_backends.py

运行测试和 lint：

python -m pytest -q
python -m ruff check voxflow tests scripts

pytest 已默认把临时目录和 cache 放到仓库内的 .pytest-tmp/，可避开部分 Windows 本机临时目录权限问题。

用本地音频文件测试转写：

python scripts/transcribe_file.py sample.wav --model tiny
python scripts/evaluate_sample.py --audio sample.wav --reference reference.txt --model tiny

启动完整 GUI 或迷你悬浮窗：

python -m voxflow --gui
python -m voxflow --mini-gui

UDP 控制命令：

python scripts/send_udp.py STATUS
python scripts/send_udp.py START_RECORD
python scripts/send_udp.py STOP_RECORD

默认监听 127.0.0.1:9999。

录音测试

如果只是想验证录音、VAD 和转写链路，不一定要直接对着物理麦克风说话，也可以把系统或应用的播放音频临时重定向到 VoxFlow 的录音输入。

Linux / PipeWire：

• 可以使用 qpwgraph 做录音链路重定向，把目标应用的输出，或目标 sink 的 monitor 输出，临时接到 VoxFlow 使用的输入节点。
• 这种方式适合回归录音、分段和转写，不需要额外准备实体麦克风测试环境。

Windows：

• 可以使用 VB-Audio Virtual Cable 做同样的测试。
• 把系统或目标应用的播放设备切到 CABLE Input。
• 把 VoxFlow 的 recorder_device 设为 CABLE Output，这样系统播放音频就会进入 VoxFlow 的录音链路。
• 需要临时覆盖时可以直接运行：

python -m voxflow --gui --recorder-device "CABLE Output"

模型和缓存

常用模型别名：

tiny, base, small, medium, large-v3, turbo

ONNX 后端会优先使用 Hugging Face 上预导出的 Whisper ONNX 仓库，避免首次启动时本地导出 ONNX。首次使用仍需要下载模型权重，medium、large-v3、turbo 会明显大于 tiny/small。

默认模型缓存目录：

• Windows：%LOCALAPPDATA%\VoxFlow\huggingface
• Linux：~/.cache/voxflow/huggingface

可通过配置或环境变量覆盖：

model_cache_dir = "D:/models/voxflow"

set VOXFLOW_MODEL_CACHE_DIR=D:\models\voxflow
set VOXFLOW_HF_ENDPOINT=https://hf-mirror.com

常用配置

当前仓库默认的 ONNX 保守配置：

onnx_batch_size = 1
onnx_chunk_length_s = 15
onnx_quantization = "dynamic_int8"

如果是已经验证过的 CUDA / ROCm 环境，再按实际显存和吞吐把这些值调回 provider 默认值或更激进的设置。

录音和 VAD 参数：

recorder_sample_rate = 16000
recorder_channels = 1
recorder_device = "CABLE Output"
recorder_block_size = 1024
vad_threshold = 0.5
vad_min_speech_ms = 200
vad_min_silence_ms = 800
vad_speech_pad_ms = 200

录音过程中的输出行为：

• 主界面的“最近转写结果”会在录音过程中持续刷新，不必等到手动停止才看到文本。
• 已完成的语音分段会在录音过程中即时注入当前焦点，适合边说边把文本送进目标输入框。
• 如果当前焦点不在可输入控件上，VoxFlow 会等待焦点回到可输入框后再继续注入。
• 手动停止录音时只会补最后还没注入的尾段，避免把前面已经输出过的内容重复打一遍。

如果你在 Windows 上用 VB-Audio Virtual Cable，把系统默认播放设备切到 CABLE Input，再把 VoxFlow 的 recorder_device 设为 CABLE Output 即可从虚拟线缆回采系统声音。也可以临时用命令行覆盖：

python -m voxflow --gui --recorder-device "CABLE Output"

GUI/UDP 会先启动，后端模型在后台加载并预热；界面会显示“后端加载中”“模型预热中”和“准备就绪”。这样做的目的不是把启动耗时藏起来，而是让用户尽早获得可见反馈、先完成界面交互和热键链路建立，再把真正耗时的模型加载放到后台。默认 warmup 会在空闲阶段主动跑一遍后端，降低第一次正式录音时的冷启动抖动；如果当前更关心启动速度、调试效率或短生命周期 smoke test，可以显式跳过预热：

python -m voxflow --mini-gui --no-warmup

指定非默认 GPU：

set VOXFLOW_ONNX_DEVICE_ID=0

默认启用 OpenCC 和 FunASR 标点：

punctuation_backend = "funasr"
punctuation_model = "damo/punc_ct-transformer_zh-cn-common-vocab272727-pytorch"

关闭真实文本注入，仅验证链路：

python -m voxflow --gui --backend echo --recorder null

打包

当前 release workflow 已经可以稳定产出 Linux CPU 包、Windows CPU 包、Windows CUDA 主包与运行时补充包，以及兼容性保留的 DirectML 包，说明这条发布链路已经打包成功并可重复执行。

当前 release workflow 的 Windows CUDA 路线分三步：先装 .[release,onnx,dev]，清掉通用 onnxruntime* 后单独装 .[cuda]；再下载默认 small Faster-Whisper 模型与 FunASR 标点模型；最后在打开 VOXFLOW_INCLUDE_ONNX_BACKENDS=1 和 VOXFLOW_INCLUDE_CUDA_RUNTIME=1 的前提下执行 PyInstaller。

python -m pip install --upgrade pip
python -m pip install -e ".[release,onnx,dev]"
python -m pip uninstall -y onnxruntime onnxruntime-gpu onnxruntime-directml
python -m pip install -e ".[cuda]"
python -m pytest -q
python -m ruff check voxflow tests scripts
python scripts/download_punctuation_model.py
python scripts/download_model.py --model small --output-dir packaging/models/faster-whisper/small
$env:VOXFLOW_INCLUDE_ONNX_BACKENDS='1'
$env:VOXFLOW_INCLUDE_CUDA_RUNTIME='1'
pyinstaller packaging/voxflow.spec --noconfirm --clean

如果要和官方 release artifact 完全一致，还要在打包后先做一次 echo / null 的 UDP 冒烟测试，再把 Windows CUDA 目录拆成 voxflow-windows-cuda-x86_64.zip 与 voxflow-windows-cuda-runtime-x86_64.zip 两个 zip。完整命令见 docs/Build-Packaging-Install.md 和 .github/workflows/release.yml。

release extra 配合基础依赖可覆盖 GUI、录音、Faster-Whisper、FunASR 标点导出、剪贴板注入和 PyInstaller。官方 release workflow 当前默认只预置 small Faster-Whisper 模型和 FunASR 标点模型；如果想把 ONNX 模型和 Silero-VAD 也一起打进目录包，仍需手工执行 python scripts/download_release_assets.py --model small。解压后的 voxflow.exe 在没有 Python 的 Windows 电脑上可直接启动。

GitHub Release 会上传五个 zip：

• voxflow-linux-faster-whisper-int8-cpu-x86_64.zip
• voxflow-windows-faster-whisper-int8-cpu-x86_64.zip
• voxflow-windows-directml-x86_64.zip（兼容性保留，不建议作为当前默认安装包）
• voxflow-windows-cuda-x86_64.zip
• voxflow-windows-cuda-runtime-x86_64.zip（与上面的 CUDA 主包解压到同一目录）

如果只看当前稳定交付，优先关注 CPU 包和 CUDA 包即可。

如果要打明确包含 ONNX 运行链路的包，需要额外安装 .[onnx] 和目标平台 runtime extra，例如 .[directml]、.[cuda] 或 .[rocm]，并把 VOXFLOW_INCLUDE_ONNX_BACKENDS 设为 1。具体平台组合与命令见 docs/Build-Packaging-Install.md。

CPU 包与 DirectML 包保持 VOXFLOW_INCLUDE_CUDA_RUNTIME=0 或不设置即可；只有明确打 CUDA 发布包时才需要把它设为 1，这样 PyInstaller 才会额外带上 CUDA runtime 依赖。

Windows 产物：

.\dist\voxflow\voxflow.exe --gui

Linux 产物：

./dist/voxflow/voxflow --gui

更完整的源码安装、打包和发布说明见 docs/Build-Packaging-Install.md。