🎙️ Mac 嘴砲輸入法 (VoiceType4TW) — 學生版完整安裝手冊
🎙️ Mac 嘴砲輸入法 (VoiceType4TW) — 學生版完整安裝手冊
適用對象：拿到新 Mac 電腦的學生，零基礎也能跟著做。
最終成果：按一下右 Shift → 講話 → 再按一下 → 文字自動出現在游標位置。
費用：完全免費。語音辨識在你自己的電腦上跑，不上傳任何資料。
📋 事前準備清單
在開始之前，請確認以下三件事：
- [ ] 你的 Mac 是 Apple Silicon (M1/M2/M3/M4) 晶片
- [ ] macOS 版本 14.0 (Sonoma) 以上
- [ ] 電腦已連上 Wi-Fi
第一步：安裝基礎工具 (約 5 分鐘)
打開 Mac 的 「終端機」 (Launchpad → 搜尋 Terminal)，依序貼上以下指令：
1-1. 安裝 Homebrew (Mac 的套件管理員)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安裝完成後，終端機會顯示兩行
Next steps，請把那兩行也貼上去執行。
1-2. 安裝 Python 與 Git
brew install python git1-3. 安裝 uv (Python 虛擬環境加速器)
curl -LsSf https://astral.sh/uv/install.sh | sh裝完後關掉終端機再重開一次。
第二步：下載專案並建立環境 (約 3 分鐘)
# 進入你的專案資料夾 (沒有就自動建一個)
mkdir -p ~/Projects && cd ~/Projects
# 從 GitHub 下載嘴砲輸入法
git clone https://github.com/jfamily4tw/voicetype4tw-mac.git
# 進入專案目錄
cd voicetype4tw-mac
# 建立 Python 虛擬環境並安裝依賴
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
# 🔑 安裝兩個關鍵套件 (原版沒有，但我們需要)
uv pip install pynput pyperclip第三步：換心手術 — 修改核心貼上程式 (約 1 分鐘)
原版用 AppleScript 貼上文字，但 macOS 的安全機制會直接擋掉。我們換成更可靠的方式。
用任何文字編輯器打開 output/injector.py，刪掉全部內容，貼上以下程式碼：
import pyperclip
import time
from pynput.keyboard import Key, Controller, KeyCode
class TextInjector:
"""
將文字寫入剪貼簿，並透過 pynput 模擬 Cmd+V 自動貼上
"""
def __init__(self):
self.keyboard = Controller()
def inject(self, text: str) -> None:
if not text:
return
pyperclip.copy(text)
time.sleep(0.05)
self._paste()
def select_back(self, char_count: int) -> None:
if char_count <= 0:
return
with self.keyboard.pressed(Key.shift_l):
for _ in range(char_count):
self.keyboard.press(Key.left)
self.keyboard.release(Key.left)
time.sleep(0.01)
def _paste(self) -> None:
with self.keyboard.pressed(Key.cmd):
self.keyboard.press('v')
self.keyboard.release('v')存檔關閉。
第四步：打通 macOS 安全權限 (最關鍵！約 2 分鐘)
⚠️ 這一步如果沒做，按快捷鍵會完全沒反應！
4-1. 輔助使用 (Accessibility)
- 打開 系統設定 → 隱私權與安全性 → 輔助使用
- 點擊左下角的 🔒 鎖頭 解鎖
- 點擊
+號 - 在跳出的選檔視窗中，按
⌘ + ⇧ + G(前往路徑) - 貼上以下路徑，把
你的使用者名稱換掉：/Users/你的使用者名稱/Projects/voicetype4tw-mac/.venv/bin/python - 按 Enter → 選擇
python→ 打開 → 確認有打勾 ✅
4-2. 輸入監聽 (Input Monitoring)
- 回到 隱私權與安全性 → 輸入監聽
- 重複上面 4-1 的步驟 3~6，把同一個
python加進去並打勾
4-3. 麥克風 (Microphone)
- 回到 隱私權與安全性 → 麥克風
- 確認「終端機 (Terminal)」已經有權限（通常第一次錄音時系統會自動彈出詢問）
🔴 授權完成後，必須完全關閉終端機 (
⌘+Q) 再重新打開！ 權限才會真正生效。
第五步：最佳化設定 (約 30 秒)
用文字編輯器打開專案根目錄的 config.json，刪掉全部內容，貼上：
{
"hotkey": "shift_r",
"trigger_mode": "toggle",
"stt_engine": "local_whisper",
"whisper_model": "large-v3-turbo",
"llm_enabled": false,
"language": "zh",
"hotkey_toggle": "shift_r",
"hotkey_ptt": ""
}這組設定的意思是：
- 快捷鍵綁定在右邊的 Shift 鍵
- 按一下開始錄音，再按一下送出（Toggle 模式）
- 使用本地 Whisper 引擎，不需要任何 API Key
- 關閉 Ollama 潤飾（避免崩潰，且速度更快）
第六步：建立桌面啟動捷徑 (一勞永逸)
在終端機貼上以下三行：
cat > ~/Desktop/啟動嘴砲輸入法.command << 'EOF'
#!/bin/bash
cd ~/Projects/voicetype4tw-mac
source .venv/bin/activate
python main.py
EOF
chmod +x ~/Desktop/啟動嘴砲輸入法.command🎉 完成！ 以後只要雙擊桌面的「啟動嘴砲輸入法.command」，把彈出的黑窗縮到最小，就可以隨時按右 Shift 開始語音輸入了！
🧪 驗證是否成功
- 雙擊桌面的
啟動嘴砲輸入法.command - 打開任何 App（備忘錄、Google Docs、LINE 都行）
- 將游標點在輸入框裡
- 按一下右 Shift → 對著麥克風說話 → 再按一下右 Shift
- 等幾秒鐘，文字就會自動出現在游標位置！
💡 第一次使用時，Whisper 模型 (~1.5GB) 會自動下載，請耐心等候約 3-5 分鐘。
❓ 常見問題
| 問題 | 解法 |
|---|---|
| 按右 Shift 完全沒反應 | 回去檢查第四步的權限設定，確認有加入且有打勾 |
| 程式啟動後馬上崩潰 | 確認 config.json 中 llm_enabled 是 false |
| 錄音後沒有文字出現 | 確認麥克風權限已開啟，且終端機有重新啟動過 |
| 貼上位置不對 | 確認游標已經點在你想輸入的地方再按快捷鍵 |
| 辨識出來是簡體中文 | 確認 config.json 中 language 是 "zh" |
最後更新：2026-03-01 | 作者：數位人生教練 蔡教練
🚀 準備好迎接你的 AI 數位轉型了嗎？
知識只是起點，落地才是關鍵。如果您也想為企業或個人打造專屬的 AI 數位分身與自動化工作流，擺脫繁瑣的重複勞動，專注於最具價值的高階戰略？
我是數位教練蔡正信，擁有豐富的系統建構與企業陪跑經驗。在 AI 飛速發展的今天，讓我協助你將這些技術化為你最強大的「虛擬合夥人」。
漫遊數位 ‧ 大腦算力注能
我持續探索，與您共享 AI 時代的實戰洞察
如果這篇文章或工具為您帶來了啟發，歡迎請我喝杯咖啡。您的支持將 100% 轉化為大阿爪的 API 算力與技術研發基金，讓我們一同在數位時代漫遊！
☕NT$100一杯咖啡 (注能 6 天)🍱NT$300一頓午餐 (注能 18 天)⚡NT$500一週能量 (注能 1 個月)💖NT$1000無限進化 (終極注能)