isRock.VoiceInput 1.1.2

isRock.VoiceInput — MAI-Transcribe-2 全域語音聽寫

這是 Windows 上的 .NET 8 主控台程式，使用 MAI-Transcribe-2（Microsoft 官方文件） 辨識麥克風語音。啟動後會自動監聽全域快捷鍵：切換到記事本、Word 或瀏覽器，按住快捷鍵說話，放開後才上傳音訊轉寫。結果經 OpenCC 轉為臺灣繁體，可自動貼上或保留於剪貼簿。這不是即時串流辨識。

執行前準備

• 安裝 .NET 8 SDK，並在 Windows 開放此程式的麥克風存取權限。
• 準備支援 MAI-Transcribe-2 的 Microsoft Foundry Speech 資源，確認所在區域支援此模型。金鑰和 HTTPS 端點必須來自同一個資源，例如 https://your-resource.cognitiveservices.azure.com/；不要使用其他資源的金鑰、Speech SDK 即時語音端點或模型部署 URL。程式在 API 請求中選擇 MAI-Transcribe-2，沒有另外一組模型專用的金鑰或端點。
• 準備網路連線；錄音完成後，音訊會上傳到你的 Azure 資源。

安裝與啟動

套件 ID 與程式碼 namespace 為 isRock.VoiceInput，安裝後的指令為 voiceinput。僅支援 Windows，執行時需要 .NET 8 Windows Desktop Runtime（安裝 .NET 8 SDK 已包含）。仍是主控台工具，僅在聽寫時顯示狀態浮層，沒有一般表單操作視窗。

使用已發布的套件

套件發布到 NuGet.org 後，使用者可透過以下指令安裝；本專案的打包作業不會自動發布套件：

dotnet tool install --global isRock.VoiceInput --version 1.1.2
voiceinput

從原始碼打包與本機安裝

在專案目錄執行以下指令，會將套件產生至 .\artifacts\packages，再從該資料夾安裝：

dotnet pack -c Release -o .\artifacts\packages
dotnet tool install --global isRock.VoiceInput --version 1.1.2 --add-source .\artifacts\packages

若安裝後找不到 voiceinput 指令，請確認 %USERPROFILE%\.dotnet\tools 在 PATH 中，並重新開啟 PowerShell。

設定 Azure 連線

安裝後，在 PowerShell 設定目前視窗的環境變數並啟動：

$env:AZURE_SPEECH_KEY = Read-Host "MAI-Transcribe-2 Speech resource key"
$env:AZURE_SPEECH_ENDPOINT = Read-Host "Same Speech resource endpoint (https://...)"
voiceinput

也可以直接執行 voiceinput：缺少環境變數時，程式會在啟動階段提示輸入。程式內輸入金鑰時不顯示字元；上方的 PowerShell Read-Host 會顯示輸入內容。程式內輸入的值只供本次執行，不會寫入檔案；非互動執行時則必須先設定兩個環境變數。請勿把金鑰寫進原始碼或提交版控；若金鑰曾公開分享，請到 Azure 入口網站重新產生。

開發時仍可在專案目錄使用 dotnet run，操作方式相同。移除全域工具可執行 dotnet tool uninstall --global isRock.VoiceInput；移除工具不會刪除個人設定檔。

選單與聽寫

執行 voiceinput 並完成必要的金鑰與端點輸入後，程式會清除主控台畫面、顯示有外框的選單，並立即開始監聽，不需再按「開始」。主控台可最小化，但程序必須保持執行。預設快捷鍵是 Ctrl+Shift+Space。

在主控台輸入選項數字後按 Enter。變更設定時監聽會短暫暫停，完成後自動恢復；若原本是手動暫停，修改設定後仍保持暫停。選單外框固定顯示最近轉寫的摘要；選項 4 可查看全文。

到其他程式的文字輸入位置按住快捷鍵說話；放開其中任一按鍵就停止錄音。狀態列會即時顯示綠色「監聽中」、紅色「錄音中」、黃色「轉寫中」、青色「已完成」，以及暫停或錯誤狀態。雲端轉寫期間不能開始下一次錄音。

錄音成功開始時會播放一聲低音提示；放開快捷鍵、停止錄音時會播放兩聲低音提示（300 Hz）。提示音在背景依序播放，不會阻塞鍵盤監聽；暫停監聽或轉寫忙碌時按快捷鍵不會播放錄音提示。若使用喇叭，開始提示音可能被麥克風收錄，建議使用耳機。

錄音時，目標視窗所在螢幕正中央會顯示「聽取中…」；上傳辨識時改為「識別中…」。浮層採黑底、灰色大字及亮灰矩形外框，整體透明度 30%（不透明度 70%）。完成、失敗、取消或結束監聽後，浮層會自動清除。浮層置頂、可點擊穿透且不搶焦點，不會切走原本的文字輸入位置；錯誤細節仍顯示在主控台。

剪貼簿模式

自動貼上只會在錄音時的視窗仍在前景且目標不是主控台時執行；否則可用選項 4 查看結果，但不會改動剪貼簿。還原模式下若其他程式在貼上期間改動剪貼簿，程式會跳過還原，以免覆蓋較新的內容；特殊剪貼簿格式或延遲讀取剪貼簿的程式，可能無法完整還原或貼上。管理員權限視窗、密碼欄位或特殊編輯器也可能拒絕模擬貼上。快捷鍵若與輸入法或其他程式衝突，可改用選項 1。

快捷鍵及剪貼簿模式保存在 %LOCALAPPDATA%\MaiTranscript\settings.json，重新啟動仍生效；金鑰、端點與轉寫文字不會存入此設定檔。設定檔損壞時可檢查內容或刪除檔案，恢復首次執行的預設值。程式保持主控台啟動與選單操作，Windows Forms 僅用於剪貼簿和不搶焦點的狀態浮層，沒有一般表單操作視窗。

辨識方式與參考

程式以預設麥克風錄製 16 kHz／16-bit／單聲道 WAV，呼叫 Transcriptions - Transcribe（API 版本 2025-10-15）。請求中的 enhancedMode.model 固定為 MAI-Transcribe-2、transcribeStyle 為 clean；未指定 locales，保留中英混合語音的自動語言辨識。

MAI-Transcribe-2 不支援自由格式提示詞；Program.cs 的 phraseList.phrases 是繁體中文軟體開發詞彙與英文技術術語的辨識提示，可自行加入專案專有名詞。模型語言表將 zh 列為簡體中文，因此程式收到結果後使用 OpenCC 的 s2twp 規則轉成臺灣正體與常用詞彙；文字轉換不能修正語音辨識錯誤，多義詞仍可能需要校對。