VoiceFlow

本地语音输入助手 — 按住 F10 说话，松开后自动识别并粘贴到光标位置。无需切换应用，说完即出字。

优先使用本地 vLLM 部署的 Qwen3-ASR 模型；本地服务不可用时自动切换云端 API 兜底，全程无需人工干预。

English

特性

• 双热键模式 — F10 智能粘贴（自动检测终端/普通窗口），F11 强制终端粘贴
• 零启动延迟 — 声卡 Stream 常驻预热 + 200ms pre-roll 环形缓冲，捕获第一个字
• 本地优先，云端兜底 — 本地 vLLM 不可用时毫秒级切换 qwen3-asr-flash，日志标注 backend=local/cloud
• 实时悬浮反馈 — 深色胶囊悬浮于光标上方：录音时显示实时音量条与计时，识别/插入/失败状态一目了然
• 自动粘贴 — 识别结果经剪贴板直接插入光标位置，并自动恢复原剪贴板
• 纯本机音频 — 音频仅在内存与本机回环地址流转，不上传外网（云端兜底除外）

安装

1. 系统依赖

sudo apt install xclip xdotool libportaudio2

2. 启动本地 ASR 服务

vllm serve /path/to/qwen3-asr-1.7B --host 127.0.0.1 --port 8000

3. 安装 VoiceFlow

从源码构建 deb 包并安装（详见 docs/PACKAGING.md）：

bash scripts/build-deb.sh
sudo dpkg -i build/deb-package/voiceflow_0.1.0_amd64.deb
systemctl --user daemon-reload
systemctl --user restart voiceflow.service

如需云端兜底，将 DashScope API Key 注入 systemd 环境变量（详见 docs/CONFIGURATION.md）。

使用

热键	窗口检测	粘贴快捷键	适用场景
F10	自动智能检测	ctrl+v 或 ctrl+shift+v	大多数场景
F11	跳过检测	ctrl+shift+v（强制）	智能检测失败时

聚焦输入框 → 按住 F10 → 说话 → 松开 → 文字自动出现在光标处

录音悬浮窗会实时显示音量条与计时；松开后依次显示"识别中 → 已插入"。单次录音上限 60 秒，达到上限自动转写。

工作原理

systemd user service
  └─ Tauri/Rust 应用（快捷键 / 悬浮窗 / 目标窗口 / 剪贴板粘贴）
      └─ Python sidecar（录音 / ASR 请求 / 窗口类型检测）
          ├─ 本地优先：POST 127.0.0.1:8000/v1/audio/transcriptions（multipart）
          └─ 云端兜底：DashScope qwen3-asr-flash（base64 直传）

Rust 与 Python 之间通过 stdin/stdout JSON Lines 通信（状态、实时音量、结果）。识别错误自动分类并重试，任何阶段失败都不崩溃。

更多细节见 docs/ARCHITECTURE.md（模块实现、状态机、音频传输方式对比、临时文件生命周期）。

配置

运行时行为由 /opt/voiceflow/config.yaml 控制：ASR 端点与模型、云端兜底开关、终端窗口检测规则、录音参数等。完整字段说明与生效情况见 docs/CONFIGURATION.md。

核心片段：

asr:
  endpoint: http://127.0.0.1:8000      # 本地 vLLM
  fallback:                            # 本地不可用时兜底
    enabled: true
    model: qwen3-asr-flash
    api_key_env: DASHSCOPE_API_KEY     # 密钥走环境变量，不写入本文件

开发

# Python sidecar 依赖与测试
uv venv && uv pip install -e ".[dev]"
uv run pytest tests/ -v

# Tauri/React 开发模式
cd voiceflow-ui && pnpm install && pnpm tauri dev

# 构建安装包
bash scripts/build-deb.sh

查看服务日志：

journalctl --user-unit=voiceflow.service -f

FAQ

Q: 本地 ASR 停了怎么办？

自动切换云端兜底。本地服务停止时回环连接立即失败，切换判定开销接近 0，总延迟约等于云端调用。日志中 backend=cloud 表示本次走了云端。

Q: 为什么修改源码后重启服务没生效？

systemd 服务运行的是安装时打包的代码（/opt/voiceflow/），不是开发目录，需要重新打包安装。

Q: 按下快捷键后有延迟？

pre-roll 机制保证按下即捕获，正常无延迟。若有，检查 PRE_ROLL_MS 是否被改动、ASR 服务响应、以及 journalctl 日志。

Q: 支持 Wayland 吗？

不支持。全局热键与模拟粘贴依赖 X11（xdotool/xprop）。

文档

• 架构与实现详解 — 进程模型、模块实现、音频传输方式、临时文件生命周期
• 配置参考 — 完整字段说明、生效情况、云端密钥注入
• 构建与打包指南 — deb 构建、Python 3.12 ABI 注意事项

系统要求

• Ubuntu 桌面（X11，不支持 Wayland）
• 本地 ASR：vLLM 部署的 OpenAI 兼容语音识别模型 + NVIDIA GPU
• 可选云端兜底：DashScope API Key

许可证

MIT