isRock.VoiceInput 1.2.0

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.2.0
voiceinput

從原始碼打包與本機安裝

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

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

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

設定 Azure 連線

執行 voiceinput -h 或 voiceinput --help 可顯示環境變數設定方法並結束，不會進入主選單、檢查麥克風或開始監聽。從原始碼執行時使用 dotnet run -- --help。

安裝後，在 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：程式優先讀取環境變數，但即使缺少 endpoint 或 key，也會進入主選單，不會在啟動時要求輸入。主選單以亮黃色文字、深紅色背景凸顯「缺少 endpoint 和 key」（僅缺少其中一項時會指出該項），並暫停聽寫，直到連線設定有效。

選項 5 可輸入同一個支援 MAI-Transcribe-2 的 Speech 資源 endpoint 和 key。新的一組設定會覆蓋本次執行使用的連線，並更新目前程序的 AZURE_SPEECH_ENDPOINT／AZURE_SPEECH_KEY 環境變數，不會修改父 PowerShell、Windows 使用者或系統層級環境變數，也不永久保存；下次啟動仍讀取當時的環境變數。輸入無效時會保留原本的連線。若原本因缺少連線而停用聽寫，成功設定後會自動開始監聽；原本手動暫停則維持暫停。

程式內輸入金鑰時不顯示字元；上方的 PowerShell Read-Host 會顯示輸入內容。請勿把金鑰寫進原始碼或提交版控；若金鑰曾公開分享，請到 Azure 入口網站重新產生。

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

選單與聽寫

執行 voiceinput 後，程式會清除主控台畫面、顯示有外框的選單。若環境變數中的 endpoint 和 key 有效，立即開始監聽，不需再按「開始」；缺少或無效時仍可使用選單設定連線。主控台可最小化，但程序必須保持執行。預設快捷鍵是 Ctrl+Shift+Space。

主選單與子選單皆支援 上下方向鍵切換選項，目前選項以反白顯示，按 Enter 執行；到達首尾時會循環切換。選單選擇模式中按 Esc 會清除已輸入的數字並反白選取該選單的 0 項目，不會立即執行；再按 Enter 才返回或結束。也保留輸入選項數字後按 Enter 的操作，輸入有效數字時會同步反白對應選項。子選單顯示在同一個外框選單區，選擇 0 返回上一層；主選單的 0 仍是結束程式。返回主選單後保留目前選項，詞彙、路徑或連線設定的文字輸入仍使用原本方式。重新導向輸入時仍使用原本的數字文字輸入方式。變更設定時監聽會短暫暫停，完成後自動恢復；若原本是手動暫停，修改設定後仍保持暫停。選單外框的「最近」區域提供四行，自動換行顯示最近轉寫；超出時提示按 4 查看全文。

變更快捷鍵時，請讓主控台保持焦點並直接按下組合鍵。設定使用全域低階鍵盤 hook，在按鍵送到終端機前擷取並攔截主鍵，因此可設定 Windows Terminal 原本會攔截的 Ctrl+Shift+Space，不會開啟終端機下拉選單。程式會顯示偵測到的快捷鍵，等待主鍵與修飾鍵放開後儲存；不支援的組合會提示重新按鍵。切換到其他視窗時不擷取新組合鍵。此功能需要互動式主控台，不支援以管線或重新導向的文字輸入設定快捷鍵；Windows 安全組合鍵（例如 Ctrl+Alt+Delete）仍無法攔截。

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

控制模式（Ctrl+Shift+Z）

除了可自訂的聽寫快捷鍵外，程式會監聽 Ctrl+Shift+Z 作為控制模式熱鍵；此功能預設開啟，可用選項 8 切換開關，狀態保存在設定檔並顯示於選單上方的快捷鍵列。按住時螢幕浮層顯示「控制模式」（與「聽取中」相同的呈現方式）並開始錄音；放開後浮層顯示「識別中」並轉寫成文字。轉寫結果不會貼上，而是帶入 copilot -p "<辨識文字>" --yolo，在另一個新的 PowerShell 視窗背景執行，不佔用儀表板主控台。期間狀態列顯示洋紅色「執行命令中」，浮層短暫顯示「執行命令中」；新視窗執行完畢會等待按 Enter 關閉，關閉後狀態列顯示「已完成」。監聽在命令執行期間持續進行，可繼續使用兩組熱鍵。兩組熱鍵共用同一個忙碌狀態，同一時間只會有一組進行錄音或轉寫；請避免把聽寫快捷鍵也設為 Ctrl+Shift+Z。需已安裝 GitHub Copilot CLI。關閉控制模式後，Ctrl+Shift+Z 不再被攔截，會照常傳給前景程式。

錄音停止後，在辨識／等待貼上的過程可按 Esc 取消本次聽寫，不會停止背景監聽。會取消本機 HTTP 請求並跳過尚未執行的貼上或複製；雲端可能已收到音訊，取消不保證停止伺服器處理。若尚未寫入剪貼簿，保持當時的內容不動；「貼上後還原」模式即使在貼上階段取消，仍會完成還原（其他程式已修改剪貼簿時則不覆蓋其新內容）。已送出的貼上無法撤銷。「貼上並保留」與「僅複製」模式若已寫入文字，仍按原設定保留。這段期間 Esc 優先用於取消聽寫；其他時間在選單中仍是跳到 0 項目。

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

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

剪貼簿模式

自動貼上前會等待 Ctrl、Shift、Alt 與快捷鍵主鍵全部放開，最長約五秒。若逾時仍判定有按鍵按住，會顯示「辨識完成，但未自動貼上」及被判定按住的鍵名；辨識結果仍保留，可按 4 查看全文，此情況不會更新剪貼簿。

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

「貼上後還原」會優先在覆蓋前把 Unicode 文字讀成獨立的字串備份，還原後檢查文字是否一致。含有文字的剪貼簿會以純文字還原，不保留同時附帶的 HTML、RTF 或其他富文字格式。非文字資料則逐一讀取格式並建立獨立備份，支援字串、位元組陣列、檔案路徑陣列、可定位串流及圖片；無法讀取或不支援的格式會明確報錯並取消貼上，不會覆蓋原內容。備份期間若剪貼簿變更，也會取消貼上。備份只存在記憶體中，不會寫入磁碟。

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

編輯辨識提示詞彙

主選單選項 6 可查看、新增、修改、刪除詞彙，也可清空清單或還原預設的中英文軟體開發詞彙。每個詞彙可包含空白，例如 ASP.NET Core；不接受空白詞彙。選擇「儲存並返回」才會保存並套用修改，「取消並返回」則保留原本清單。空清單可儲存，表示不提供自訂詞彙提示。

詞彙編輯子選單的 7／8 可切換詞彙顯示頁，每頁四個詞彙；新增／修改／刪除的文字提示中輸入 0 可返回詞彙編輯選單，不套用該次操作。編輯選單的 0 則放棄全部未儲存修改並返回主選單。

詞彙存於 %LOCALAPPDATA%\MaiTranscript\phrases.json，採用與 Isolated Storage 類似的使用者專屬本機儲存方式，沿用現有設定資料夾，更新工具版本後仍保留。首次執行或檔案不存在時會寫入預設清單；之後啟動皆讀取已儲存的清單。儲存失敗會顯示錯誤並保留編輯內容，不會套用未儲存的修改；檔案內容損壞時會明確報錯，不會自動覆蓋。可修正 JSON 字串陣列，或刪除該檔案讓下次啟動重新建立預設值。

編輯期間會暫停監聽，返回後恢復原本的監聽／暫停狀態。詞彙會送至 Azure 作為 phraseList.phrases，請勿加入密碼、金鑰等敏感資料。

主選單選項 7 可選擇匯入或匯出，再輸入 JSON 檔案路徑（支援相對路徑及加上雙引號的路徑；空白取消）。匯出時若未輸入副檔名，會自動使用 .json，例如 my-phrases 會匯出為 my-phrases.json；已有副檔名則保留。檔案格式與本機詞彙檔一致，為 JSON 字串陣列，例如：

[
  "程式碼",
  "ASP.NET Core",
  "Azure"
]

匯入會先驗證內容，在確認子選單選擇 1 後取代整份目前清單，保存到本機詞彙儲存體，立即供後續聽寫使用。允許空陣列 []，但不接受 null、空白詞彙或非字串項目；檔案不存在或格式錯誤會顯示錯誤，不會建立預設詞彙或修改現有清單。匯出的是目前已套用的清單，不會修改本機設定；目標檔案已存在時需在確認子選單選擇 1 才覆寫（仍接受 y）。確認選單預設選取 0 取消，避免直接按 Enter 誤覆寫；0 返回匯入／匯出選單。檔案路徑輸入 0 或空白也會返回匯入／匯出選單；操作後可繼續匯出，選擇 0 返回主選單。匯出及本機儲存使用 UTF-8，中文字直接顯示，方便閱讀；舊檔案中的 \uXXXX Unicode 跳脫格式仍可正常匯入。匯入／匯出期間暫停監聽，返回後恢復原本狀態。

辨識方式與參考

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

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