cjpais/Handy

Handy – 离线、隐私优先的语音转文字

是什么 – Handy 是一款免费的开源桌面应用程序，可在任何窗口中即时输入文字，且无需将音频发送到云端。它在 Windows、macOS 和 Linux 上本地运行，使用设备上的神经网络模型（OpenAI 风格的 Whisper 或 CPU 优化的 Parakeet）进行转录。

如何工作

1. 按下可配置的全局快捷键（按住录音或切换模式）。
2. 开始说话 – 音频通过 cpal 捕获，并使用 Silero VAD 进行过滤。
3. 释放快捷键后，音频将输入到所选模型（Whisper Small/Medium/Turbo/Large 或 Parakeet V3）。
4. 生成的文本将自动粘贴到当前聚焦的应用程序中。

所有步骤均在您的设备上完成；无需网络连接。

---

主要特性

• 离线推理 – 支持 Whisper GGML/GGUF 或 Parakeet 模型；有可用 GPU 时使用 GPU 加速。
• 跨平台 – 提供 macOS（Intel 与 Apple Silicon）、Windows x64 和 Linux x64 的原生构建。
• 可扩展性 – 基于 Tauri（Rust 后端，React/TS 前端）构建，开发者可添加插件或新模型。
• 全局快捷键 – rdev 提供系统级快捷键；CLI 标志可控制运行实例（handy --toggle-transcription）。
• 语音活动检测 – Silero VAD 在转录前过滤静音，减少不必要的处理。
• Raycast 集成 – macOS 用户可通过 Raycast 启动器控制 Handy。
• 调试模式与 CLI – 内置调试叠加层、详细日志和众多启动标志，供高级用户使用。

---

架构概览

层	技术	作用
UI	React + TypeScript, Tailwind CSS	设置窗口、叠加层 UI
应用壳	Tauri (Rust)	跨平台打包、系统集成
音频 I/O	cpal	捕获麦克风流
VAD	vad-rs (Silero)	检测语音与静音
快捷键	rdev	全局键盘快捷键
重采样	rubato	将音频转换为模型所需的采样率
Whisper 推理	transcribe-cpp (GGML/GGUF)	GPU 或 CPU 用 Whisper 模型
Parakeet 推理	transcribe-rs	CPU 优化的 Parakeet V3 模型

---

快速上手

1. 安装 – 从 GitHub 发布页面下载二进制文件，或使用包管理器：
   • macOS: brew install --cask handy
   • Windows: winget install cjpais.Handy
2. 运行应用，授予麦克风和辅助功能权限，并在 设置 → 键盘 中设置快捷键。
3. 按下快捷键，说话，松开 – 转录文本将粘贴到光标所在位置。

高级控制 – 使用 CLI 标志可切换录音、隐藏启动、禁用托盘图标等。示例：

handy --start-hidden --no-tray &   # 静默启动
handy --toggle-transcription       # 从自定义快捷键或脚本中切换

---

已知限制与故障排除

• macOS 蓝牙麦克风 – 可能降低播放音量；建议使用内置麦克风或有线麦克风以获得最佳效果。
• fn/Globe 键快捷键 仅在 Apple 键盘上有效，因硬件 HID 限制。
• Whisper 模型在部分 Windows/Linux 配置中崩溃 – 需要社区协助排查。
• Linux Wayland – 需要 wtype 或 dotool 进行文本插入；叠加层可能抢夺焦点，建议禁用（叠加层位置：无）。
• 运行时库 – Linux 上可能需要 libgtk-layer-shell0（或发行版特定包）才能启动应用。

---

扩展 Handy

由于后端为 Rust，前端为标准 Web 栈，贡献者可以：

• 添加新的模型加载器（如其他 GGUF/ONNX 模型）。
• 改进跨平台的全局快捷键处理。
• 构建额外集成（如 VS Code 扩展或浏览器插件）。
• 重构设置存储或添加自定义后处理插件系统。

---

发展路线图（截至 README）

• 将调试日志输出到文件。
• 改进 macOS 快捷键支持（Globe 键，重写全局快捷键处理）。
• 可选的隐私优先分析（用户可选加入）。
• 设置系统清理与 Tauri 命令重构。

---

高级用户快速验证

Handy 使用 Tauri 的更新程序签名对发布文件进行签名。公钥位于 src-tauri/tauri.conf.json 中，可按 README 所示使用 minisign 验证下载文件。

---

总结 – Handy 提供了一种简单、完全离线的语音输入工作流，尊重隐私，在三大主流桌面操作系统上运行，并基于开源语音识别库构建。它是任何需要可 fork、可扩展语音转文字工具的人的坚实基础。