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、可擴展語音轉文字工具的人的堅實基礎。