open-typeless

open-typeless 是什麼？

open-typeless 是以 Trellis 框架打造的 macOS 桌面應用程式，作為展示範例。它提供按住即說的工作流程，從麥克風錄音，使用 Volcano Engine 的 ASR 服務進行串流語音轉文字，並將辨識文字插入目前焦點的文字游標位置。

這個專案適合想在任何 App 中口述輸入而無需切換視窗的使用者。它還包含浮動的玻璃形態風格覆蓋層，顯示目前聆聽狀態及即時轉寫內容，當你按住熱鍵時即可看到。

主要功能

• 按住即說熱鍵：按住右 Option 鍵開始錄音；放開鍵結束錄音並自動插入。
• 即時串流轉寫：使用 Volcano Engine ASR，串流部分結果，讓覆蓋層隨著辨識進度更新。
• 狀態與轉寫浮動覆蓋層：顯示「聆聽中…」狀態及轉寫文字，呈現磨砂玻璃外觀。
• 無需切換視窗的游標插入：自動將辨識文字插入目前游標位置，讓你繼續在使用的 App 中輸入。
• 不搶奪焦點：浮動視窗設計不會中斷使用者在目前應用程式的流程。

如何使用 open-typeless

1. 安裝依賴：執行 pnpm install。
2. 設定環境變數：複製 .env.example 至 .env，填入 Volcano Engine 憑證。
   • VOLCENGINE_APP_ID
   • VOLCENGINE_ACCESS_TOKEN
   • VOLCENGINE_RESOURCE_ID（範例在 repo 中：模型 1.0 用 volc.bigasr.sauc，模型 2.0 用 volc.seedasr.sauc，標記為推薦）
3. 啟動 App：執行 pnpm start。
4. 首次啟動授權 macOS 權限：
   • 麥克風權限（用於錄音）
   • 輔助使用權限（用於全域熱鍵處理及文字插入） 授權後，讓 App 在背景持續執行。
5. 口述輸入：在任何有文字欄位的 App 中，按住右 Option、說話，然後放開。App 會將辨識文字插入游標。

使用情境

• 在任何編輯器口述訊息：按住右 Option 在聊天、郵件編輯器或文件欄位口述；辨識文字會直接出現在游標，無需手動貼上。
• 即時回饋填表：利用浮動覆蓋層監控系統辨識內容，說完放開即提交文字。
• 跨 App 快速筆記：用按住放開鍵快速啟停語音，保持焦點在目前視窗。
• 熱鍵/文字插入問題排除：若熱鍵無反應或文字未插入，請確認 App 已啟用輔助使用權限，且游標位於輸入區域。

常見問題

• 為什麼熱鍵無效？ 確認 App 在系統設定 → 隱私與安全性 → 輔助使用中已啟用輔助使用權限，並加入允許 App 清單。

• 為什麼無法插入文字？ 目標應用程式須支援文字輸入，且游標應在文字輸入區域。也請確認輔助使用權限已正確授權。

• 語音辨識有啟動延遲嗎？ 首次連線 Volcano Engine 服務會建立 WebSocket 連線，可能需1–2 秒；後續使用可能更快。

• 可以變更熱鍵嗎？ Repo 說明熱鍵目前固定為右 Option 鍵，自訂需修改 src/main/services/keyboard/keyboard.service.ts（特別是 triggerKey）。

替代方案

• macOS 內建口述/語音輸入：適合偏好無需設定外部 ASR 憑證的系統級語音轉文字。工作流程不同，因為整合及插入由 macOS 處理。
• 需手動複製貼上的通用語音轉文字工具：提供轉寫但通常需貼到目標 App，本專案則直接游標插入。
• 文字展開及熱鍵口述 App：透過快捷鍵插入文字的工具；有些專注編輯巨集或轉寫流程，而非串流 ASR 搭配磨砂覆蓋層及按住即說。
• 其他開發者導向語音轉文字整合：若自建流程，可用 ASR API 及全域熱鍵/剪貼簿或輔助使用 API；本專案則是現成 App，無需自行實作。