English | 中文
VoiceX 是一个跨平台桌面语音输入工具。整体处理链路为：录音、实时反馈、识别、按需纠正或翻译、把文本送进当前应用、保存并同步历史记录。它和当下流行的语音输入工具在核心流程上类似，但也有一些自身的特点，以及对功能边界的取舍。
- 跨平台 — 同时支持 macOS 和 Windows，使用平台原生热键捕获、托盘图标和文本注入。
- 多 ASR 后端 — 在十一种云端和本地语音识别引擎间自由切换，兼顾准确率、延迟、语种覆盖和隐私。
- 一键多用 — 单个全局热键驱动三种交互模式：轻点启动免提听写、长按进入按住说话、双击触发翻译。
- 实时 HUD 浮层 — 轻量置顶窗口，实时显示转写文本、录音模式、倒计时和处理状态；在 macOS 多桌面场景下也会跟随当前活跃 Space 显示，不打断当前工作流。
- LLM 后处理 — 可选将 ASR 输出交给大模型做纠错、翻译或润色，支持自定义 prompt 模板和词典上下文注入。
- 智能文本注入 — 识别结果通过剪贴板粘贴（自动备份/恢复原内容）或模拟键入送入当前应用，无缝衔接。
- 历史记录与统计 — 每次听写保留完整元数据（时长、设备、ASR/LLM 模型、原文 vs. 纠正文本），按日期浏览，并支持录音回放与重新转录。
- 跨设备同步 — 自建同步服务器，在多台设备间保持历史一致。
VoiceX 通过一个可配置的全局热键映射三种不同意图：
| 手势 | 模式 | 行为 |
|---|---|---|
| 轻点（按下即松） | 免提听写 | 持续录音直到静音超时或最大时长，无需一直按住。 |
| 长按（按住不放） | 按住说话 | 按住期间录音，松开即结束。 |
| 双击 | 翻译 | 与免提听写相同，但结果通过 LLM 翻译为英文（需开启）。 |
长按阈值和双击窗口均可调。录音期间按 Escape 可随时取消并丢弃。
| 提供商 | 类型 | 说明 |
|---|---|---|
| 火山引擎（豆包语音） | 云端流式 (WebSocket) | 中文优化；支持热词增强、ITN、标点、DDC |
| Google Cloud Speech-to-Text V2 | 云端流式 (gRPC) | 多语种，Phrase Boost，可配置端点检测 |
| Fun-ASR Realtime | 云端流式 (WebSocket) | DashScope；fun-asr-realtime / fun-asr-flash-8k-realtime；适合低延迟实时出字 |
| 通义千问（DashScope ASR） | 云端流式 / 批量文件识别 | 阿里云；支持 Realtime、Batch 和 Realtime + 录后 Batch 精修；batch 路径当前受 5 分钟短音频接口限制 |
| Gemini Audio Transcription | 云端批量文件识别 | gemini-3.1-flash-lite-preview；录音结束后上传整段音频；支持自动 / 中文 / English / 中英混合提示 |
| Gemini Live Realtime | 云端流式 (WebSocket) | gemini-3.1-flash-live-preview；基于输入音频转写的实时识别，可附带语言提示 |
| Cohere Audio Transcription | 云端批量文件识别 | cohere-transcribe-03-2026；整段音频上传识别，需显式指定 ISO-639-1 语言码 |
| Soniox Realtime | 云端流式 (WebSocket) | stt-rt-v4；基于 token 的流式识别，支持热词和语言提示 |
| OpenAI ASR | 云端批量 / 流式 (WebSocket) | gpt-4o-transcribe；双模式——批量文件上传或实时 WebSocket 流式识别（含 VAD） |
| ElevenLabs Speech-to-Text | 云端流式 / 批量文件识别 | scribe_v2_realtime / scribe_v2；支持实时识别、整段批量转录，以及录音结束后的 batch refine |
| Coli | 本地离线 | 基于 SenseVoice / Whisper，需通过 npm 单独安装 |
目前推荐豆包、通义千问、ElevenLabs、Soniox 和 Coli，但每个人的体验可能会有差异，发音习惯、用词和使用领域都会影响最终效果。
提示： 云端 ASR 服务需要到对应平台申请 API Key。Coli 需要事先通过 npm 全局安装（
npm i -g @marswave/coli），详见 Coli 文档。
VoiceX 可选将 ASR 输出交给 LLM 做纠错或翻译。支持的提供商：
| 提供商 | 默认模型 |
|---|---|
| 火山引擎（豆包） | doubao-seed-2-0-mini-260215 |
| OpenAI（或兼容接口） | gpt-4o-mini |
| 通义千问（DashScope） | qwen3.5-flash |
| 自定义 | 任何 OpenAI 兼容端点 |
提示： 每个 LLM 提供商都需要到对应平台申请 API Key，在 设置 → LLM 中配置即可。
能力：
- ASR 纠错 — 结合词典上下文和可自定义 prompt 修正识别错误。
- 翻译 — 将听写内容翻译为英文，由双击手势触发。
- Prompt 模板 — 完全自定义纠错和翻译 prompt，支持
{{DICTIONARY}}占位符注入热词。
- 维护纯文本词表（每行一个），同时作为 ASR 热词和 LLM prompt 上下文注入。
- 关键词替换规则 — 定义自定义查找替换规则（精确、包含或正则），对识别结果做后处理。
- 在线热词同步 — 可选与火山引擎热词平台双向同步（需配置 AK/SK）。
- 智能标点清理 — 短句自动去除末尾标点（阈值可配置）。
- 关键词替换 — 正则/精确/包含替换规则，在文本注入前执行。
- 全量历史按日期分组，每条记录支持录音回放、复制和详情查看。
- 原始 ASR 输出与 LLM 纠正结果的并排对比。
- 可对任意历史录音重新转录，切换不同 ASR 后端并按需叠加 LLM 纠错，方便做同音频对比。
- 批量识别失败时，会在本机历史中保留失败记录和录音，方便后续重新转录，不必整段重说。
- 可配置文本和录音的保留策略（7 / 30 / 180 / 365 天或永久保留）。
- 概览仪表盘：总时长、字符数、AI 纠正次数、平均听写速度——按设备汇总。
- 主界面、HUD 浮层、托盘菜单和默认 prompt 模板都完整覆盖
zh-CN与en-US。 - 支持系统 / 中文 / English 三档界面切换；选择
system时会自动跟随系统语言。 - 设置、历史、诊断信息和 provider 说明都做了双语处理，整体体验保持一致。
记忆会是 AI 时代的长期主题。如果你在多台电脑上都使用语音输入，那么把输入历史集中管理，会更方便未来沉淀为可检索、可复用的记忆。VoiceX 支持轻量自建同步服务器（sync-server/），跨设备保持文本历史一致。录音文件仅保存在本地。部署同步服务需要一台可被各终端访问的服务器，但资源占用不高。
- Token + 共享密钥认证。
- 实时同步状态（已连接 / 连接中 / 重连中 / 配置缺失）。
- 详见 sync-server/README.md。
| 层 | 技术 |
|---|---|
| 前端 | Vue 3 · TypeScript · Naive UI · Vite |
| 桌面壳 | Tauri 2 (Rust) |
| 音频采集 | cpal · Opus (OggOpus) · 16 kHz 单声道 |
| 同步服务端 | Rust · Axum · SQLite |
- Node.js (LTS)
- pnpm
- Rust (stable)
- Tauri 2 系统依赖：参考 Tauri Prerequisites
# 安装 JS 依赖
pnpm install
# 启动 Web 开发环境
pnpm dev
# 启动桌面开发环境（含 Tauri）
pnpm tauri dev
# 构建生产版本
pnpm build
pnpm tauri buildVoiceX 需要以下三项 macOS 权限才能正常工作——全局热键捕获依赖辅助功能和输入监控，录音依赖麦克风权限：
| 权限 | 用途 |
|---|---|
| 辅助功能 (Accessibility) | 拦截全局热键事件，向其他应用注入文本 |
| 输入监控 (Input Monitoring) | 在系统范围内捕获键盘事件以检测热键 |
| 麦克风 (Microphone) | 录音用于语音识别 |
首次启动时系统会弹出授权提示，在 系统设置 → 隐私与安全性 中授予即可。
如果不进行代码签名，macOS 会将每次编译的新版本视为不同应用，导致每次重新编译后都需要重新授予上述三项权限。通过本地自签名证书签名构建产物，macOS 能跨编译识别应用身份，权限授予持续有效。
# 一次性操作：在钥匙串中创建本地代码签名身份
pnpm mac:setup-signing
# 构建、签名并安装到 /Applications
pnpm mac:build-localmac:setup-signing 生成名为 "VoiceX Local Code Signing" 的自签名证书并导入到登录钥匙串（只需执行一次）。mac:build-local 构建 Release 版本，用该证书签名，然后安装到 /Applications 并移除隔离标记。
仅用于本地开发构建。CI/CD 或分发构建应使用正式的 Apple 开发者证书。
Windows 上本地开发不需要代码签名，直接用 PowerShell 构建即可：
.\scripts\Build-VoiceX.ps1src/ # Vue 3 前端
components/ # 共享 UI 组件
views/ # 路由页面 (Overview, History, Dictionary, Settings, About)
stores/ # Pinia 状态管理
hud/ # 轻量 HUD 覆盖层
src-tauri/ # Tauri (Rust) 桌面壳
src/ # Tauri commands & 核心逻辑
proto/ # gRPC proto 定义 (Google Cloud Speech)
vendor/ # Vendored 依赖 (audiopus_sys, rdev)
sync-server/ # 自建历史同步服务端
tools/llm-bench/ # LLM 纠正能力基准测试
scripts/ # 构建与签名辅助脚本
本项目基于 MIT License 开源。
项目包含的第三方组件的许可信息详见 THIRD_PARTY_LICENSES。