VoiceInk Custom Command：把聽寫的內容交給腳本，而不是直接貼上

作者 · 發佈於

Custom Command（自訂指令）是 VoiceInk 的輸出模式之一。VoiceInk 不貼上文字，而是把聽寫完成的文字交給你寫的 shell 指令，由那個指令決定接下來會發生什麼：附加到筆記、開啟搜尋、呼叫你自己的腳本，或是送到你架設的服務。這是 VoiceInk 處理文字時最有彈性的功能，在你動手搭建之前，有幾項硬性限制值得先知道。

我做了 YapToText，一款不同的 Mac 聽寫 App，所以讀我寫的 VoiceInk 內容時請記得這一點。這裡每一項關於 VoiceInk 的內容，都來自它自己的文件，於 2026 年 10 月 10 日讀取。

在 Mac App Store 下載 YapToText免費下載。不需要帳號，沒有鎖住的功能。需要搭載 Apple 晶片的 Mac 和 macOS 14 或以上版本。 原始碼在 GitHub 上。

用其他語言閱讀： English, العربية, Čeština, Dansk, Deutsch, Ελληνικά, Español, Suomi, Français, עברית, हिन्दी, Magyar, Bahasa Indonesia, Italiano, 日本語, 한국어, Norsk, Nederlands, Polski, Português, Română, Русский, Slovenčina, Svenska, ไทย, Türkçe, Українська, Tiếng Việt, 简体中文

指令會收到什麼

VoiceInk 以兩種方式送出同一份最終文字：標準輸入，以及變數 $VOICEINK_TRANSCRIPT。文字是 UTF-8，文件要求你為變數加上引號，這樣空格、標點和換行才會保留。

  • AI Enhancement（AI 增強）關閉時，指令收到的是原本的逐字稿。這是經過 VoiceInk 格式化和字詞取代之後的逐字稿。
  • AI Enhancement 開啟且運作正常時，指令收到的是增強後的文字。
  • AI Enhancement 被略過或失敗時，指令收到的是最終的原始逐字稿。

指令不會直接拿到音訊、提示、選取的文字、剪貼簿的內容或螢幕上的文字。如果你想讓情境影響結果，文件說要使用提示和 Context Awareness（情境感知），這樣情境就已經包含在最終文字裡了。

它怎麼執行

來自 VoiceInk 的文件 Custom Commands，2026 年 10 月 10 日讀取。

項目行為
Shell/bin/zsh -lc
逾時10 秒，之後 VoiceInk 會停止該指令
權限與 VoiceInk 相同的 macOS 使用者權限
錄音視窗在指令開始之前就會關閉
成功結束代碼為 0。其他任何值都算失敗
輸出標準輸出和錯誤訊息會保留下來供診斷使用，不會貼進 App
找不到指令VoiceInk 會嘗試你的 shell PATH。如果失敗，請使用完整路徑，例如 /opt/homebrew/bin/tool

容易讓人踩到的限制

  • 不會幫你貼上任何東西。如果你還是想讓文字出現在 App 裡，就得由你的指令自己複製或貼上。
  • 只有十秒，而且不能提問。指令無法等待輸入。需要更久的工作，就自己啟動背景處理程序，然後盡快結束。
  • 它不會改變已儲存的逐字稿。指令印出的任何內容都不會寫回去。
  • 沒有 Auto Send。Auto Send 只能搭配 Paste output 使用，不能搭配 Custom Command。
  • 只限即時聽寫。在 Transcribe file 佇列裡的檔案會直接儲存，不會執行輸出指令。
  • 指令不能是空的。指令為空的 Mode 無法儲存。

內建的範本

來自 VoiceInk 的文件 Custom Commands，2026 年 10 月 10 日讀取。

範本作用
Paste and Press Tab（貼上並按 Tab）複製文字、貼上，然後按 Tab 鍵
Lowercase and Paste（轉小寫並貼上）把文字轉成小寫，複製後再貼上
Remove Trailing Period and Paste（移除結尾句號並貼上）貼上之前去掉最後一個句號
Append to Journal（附加到日誌）把文字加到 ~/Documents/VoiceInk/journal.md
Search Web（搜尋網頁）用這段文字開啟網頁搜尋

文件建議從範本開始，再自己修改。下面是它最簡單的兩個範例：複製文字，以及把文字附加到筆記：

printf "%s" "$VOICEINK_TRANSCRIPT" | pbcopy
mkdir -p "$HOME/Documents/VoiceInk"
printf -- "- %s\n" "$VOICEINK_TRANSCRIPT" >> "$HOME/Documents/VoiceInk/notes.md"

確認有沒有成功

VoiceInk 在 Custom Command 執行後，不會顯示成功或失敗的訊息。文件提供了一個 Terminal 指令，可以顯示最近 10 分鐘的傳送記錄，包括指令是成功、失敗，還是執行超過了 10 秒：

/usr/bin/log show --last 10m --style compact \
  --predicate 'subsystem == "com.prakashjoshipax.voiceink" AND category == "TranscriptionDelivery"'

文件提醒，這些記錄可能含有你聽寫的文字。另外，如果你的指令把文字送到網路服務，那個服務就會收到這些文字：VoiceInk 只會執行你設定好的內容。

YapToText 的情況

VoiceInk 的部分來自它的文件，2026 年 10 月 10 日讀取。YapToText 的部分來自它自己的設定。

VoiceInkYapToText
用文字執行 shell 指令可以，用 Custom Command 輸出不行
在游標位置貼上Paste outputPaste，預設值
改成逐字輸入這一頁沒有說明Type character by character
只放進剪貼簿搭配 pbcopy 這類指令Copy to clipboard only
之後按一個鍵Paste and Press Tab 範本每個 App 可以選 Return 或 Command Return
文字落地之前先檢查這一頁沒有說明Review before inserting，預設關閉

如果你想讓聽寫驅動自己的腳本，VoiceInk 的 Custom Command 做得到 YapToText 做不到的事。如果你想讓文字出現在游標位置，並配合周圍的字詞，YapToText 預設就是這樣，不需要任何腳本。VoiceInk Modes 頁面說明了輸出模式在哪裡設定，VoiceInk 與 superwhisper 的比較則把它和另一款以模式為核心的 App 做了對照。

在 Mac App Store 下載 YapToText免費下載。不需要帳號，沒有鎖住的功能。需要搭載 Apple 晶片的 Mac 和 macOS 14 或以上版本。 原始碼在 GitHub 上。

重點整理

  • 它是什麼。這是一種輸出模式，會用最終文字執行你的 shell 指令。
  • 文字從哪裡來。文字會從標準輸入和 $VOICEINK_TRANSCRIPT 送進去。
  • 限制。只有 10 秒，不能輸入，不會自動貼上，也只限即時聽寫。
  • 除錯。App 裡不會顯示任何訊息，請用上面的 Terminal 指令讀取記錄。
  • 從哪裡開始。請從編輯五個範本的其中一個開始。

如果 VoiceInk 改變了 Custom Command 的運作方式，請在 GitHub 上提交 issue，我會更新這個頁面。每一則我都會看。

在 Mac App Store 下載 YapToText免費下載。不需要帳號，沒有鎖住的功能。需要搭載 Apple 晶片的 Mac 和 macOS 14 或以上版本。 原始碼在 GitHub 上。

關於作者。 Ryleigh Newman 從事軟體開發，用手打字有困難，每天都用本站介紹的 YapToText 聽寫。本頁譯自英文。App 的介面和網站的其他頁面是英文的。 進一步瞭解這個專案（英文）。

指南

更多指南（英文）

資料來源

常見問題

VoiceInk 的 Custom Command 是什麼？

它是一種輸出模式。VoiceInk 不貼上文字，而是執行你寫的 shell 指令，並把聽寫的最終文字交給它。

VoiceInk 的 Custom Command 怎麼拿到文字？

文字以 UTF-8 從標準輸入和變數 $VOICEINK_TRANSCRIPT 送進去。為變數加上引號，才能保留空格和換行。

我的 VoiceInk Custom Command 為什麼沒有貼上任何東西？

Custom Command 輸出本身不會貼上。你的指令得自己複製或貼上文字，就像 Paste and Press Tab 範本那樣。

VoiceInk 的 Custom Command 最多可以跑多久？

10 秒。之後 VoiceInk 會停止它。需要更久的工作，請啟動背景處理程序。

YapToText 有像 VoiceInk 那樣的自訂指令嗎？

聽寫之後它不會執行 shell 指令。它會在游標位置貼上或逐字輸入，也可以只複製到剪貼簿，並在文字落地後按 Return。