PrestigePvP/Voicebox 源码：https://github.com/PrestigePvP/Voicebox

VoiceBox

语音转文字工具，捕获语音，通过 Whisper 转录，并用 LLM 格式化输出。按下热键，说话，松开——格式化后的文本会进入剪贴板，并自动粘贴到你正在输入的地方。

工作原理

┌──────────────────────┐ PCM 数据块 ┌──────────────────────────────────┐ 格式化 │ Wails 桌面应用 │ ──WebSocket──▶ │ Cloudflare Worker (Durable Obj) │ ──文本────▶ 剪贴板 → 自动粘贴 │ (Go + React WebView)│ ◀─────────────│ Whisper STT → LLM 格式化器 │ └──────────────────────┘ └──────────────────────────────────┘

1. 按住 Ctrl+Cmd — 捕获焦点上下文，开始录音，屏幕顶部中央显示叠加层
2. 对着麦克风说话（语音电平表显示输入）
3. 松开 Ctrl+Cmd — 音频流传输到云端
4. Whisper 转录，LLM 格式化，结果复制到剪贴板并自动粘贴回原始应用

项目结构

voicebox/ ├── main.go # Wails 入口，应用菜单 ├── app.go # 应用生命周期，热键处理，管道编排 ├── window_darwin.go # macOS 窗口管理（叠加层、设置、Dock 点击） ├── window_other.go # 非 macOS 构建时的桩代码 ├── internal/ │ ├── audio/ # PCM 音频捕获（malgo/miniaudio），RMS 电平 │ ├── pipeline/ # WebSocket 客户端，将音频 + 焦点上下文流传输到 Worker │ ├── accessibility/ # macOS AX API：焦点元素上下文 + 自动粘贴（Cmd+V） │ ├── config/ # TOML 配置加载与保存 │ ├── hotkey/ # 全局热键注册 │ ├── stt/ # STT 提供者接口（桩代码） │ └── formatter/ # LLM 格式化提供者接口（桩代码） ├── frontend/ # React + Tailwind 叠加层 UI（Vite） │ └── src/ │ ├── App.tsx # 路由切换设置模式和叠加模式 │ ├── components/ │ │ ├── settings-form.tsx # 配置编辑器（react-hook-form + zod） │ │ └── title-bar.tsx # 无边框标题栏（带拖动区域） │ └── hooks/ │ ├── use-voicebox.ts # voicebox:state / voicebox:mode / voicebox:level 事件 │ └── use-config.ts # GetConfig / SaveConfig / GetConfigPath 绑定 ├── worker/ # Cloudflare Worker（TypeScript） │ ├── src/ │ │ ├── index.ts # 路由：/ws（WebSocket），/health │ │ ├── session.ts # Durable Object：音频累积 + AI 处理管道 │ │ ├── prompt.ts # 系统提示 + 用户消息构建器 │ │ ├── wav.ts # PCM 转 WAV 包装器 │ │ └── types.ts # 共享类型 │ ├── test/ # Vitest 测试 │ └── wrangler.jsonc # Worker 配置 ├── go.mod └── voicebox.toml # 用户配置（已加入 gitignore）

设置

前提条件

• Go 1.24+
• Node.js + pnpm
• Wails v2（https://wails.io/）CLI
• 一个启用了 Workers AI 访问权限的 Cloudflare 账户
• macOS（自动粘贴需要无障碍权限）

部署 Worker

bash cd worker pnpm install wrangler secret put VOICEBOX_TOKEN # 设置共享密钥 pnpm deploy

配置桌面客户端

首次启动时，VoiceBox 会打开设置窗口。你也可以在 ~/.config/voicebox/voicebox.toml 中手动创建配置：

``toml [provider] mode = “cloud”

[cloud] worker_url = “https://voicebox..workers.dev” token = “your-shared-secret”

[audio] sample_rate = 16000 channels = 1 chunk_size = 4096

[hotkey] record = “ctrl+cmd” ``

配置加载顺序（按优先级）：~/.config/voicebox/voicebox.toml、二进制文件同级目录、./voicebox.toml。

macOS 无障碍权限

自动粘贴需要 macOS 无障碍访问权限。首次使用时，macOS 会提示授予权限，你也可以在 系统设置 → 隐私与安全性 → 无障碍 中手动开启。

构建与运行

bash wails dev # 开发模式，支持热重载 wails build # 生产构建

窗口模式

设置（700×450，居中）：启动时、点击 Dock 图标或通过“录音”菜单打开。在此处编辑配置。 叠加层（160×48，顶部居中，浮动）：录音时显示。显示带语音电平表指示器，处理时显示旋转动画，成功时显示对勾。

WebSocket 协议

客户端连接到 GET /ws?token=。收到 {"type":"ready"} 后，客户端发送 configure 消息（包含音频和焦点上下文），然后流式传输二进制 PCM 数据块：

客户端 服务端 │── 连接 /ws?token=... ──────▶│ │◀── {"type":"ready"} ──────────│ │── {"type":"configure", ...} ──▶│ │── [二进制 PCM 数据块] ─────────▶│ │── [二进制 PCM 数据块] ─────────▶│ │── {"type":"audio_end"} ───────▶│ │◀── {"type":"processing",...} ──│ │◀── {"type":"result",...} ──────│

configure 消息携带音频参数和焦点元素上下文（应用名称、Bundle ID、元素角色、标题、占位符、当前值），LLM 格式化器会根据这些信息调整输出。

云端后端

• STT：@cf/openai/whisper-large-v3-turbo
• 格式化器：@cf/qwen/qwen3-30b-a3b-fp8

本地后端（第二阶段）

• STT：faster-whisper
• 格式化器：Ollama
• 提供者接口位于 internal/stt/ 和 internal/formatter/

音频规格

• 16kHz 采样率，单声道，PCM 有符号 16 位小端序
• 每块约 4096 字节（约 128ms）
• 最长录音：约 25 MiB（约 13 分钟）

开发

``bash

桌面应用

wails dev # 开发服务器（Go + Vite 热重载） wails build # 生产构建 go vet ./… # Go 代码检查 go test ./internal/… # Go 测试

前端

cd frontend && pnpm install && pnpm build

Worker

cd worker pnpm dev # 本地开发服务器 pnpm lint # 类型检查 pnpm format # prettier 格式化 pnpm test # vitest 测试 pnpm deploy # 部署到 Cloudflare ``