🎙️ 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 git

1-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"`