前置條件
在開始之前，請確認你的環境符合以下條件：
- Mac 搭載 M 系列晶片（Apple Silicon）
- macOS 14.0 以上
- Python 3.10 以上（原生 arm64 版本，非 Rosetta）
- 已安裝 Homebrew
python -c "import platform; print(platform.processor())"
結果應該是 arm，若顯示 i386 代表你正在使用 Rosetta 模式，需要改用原生 Python。
建立虛擬環境並安裝套件
建議使用虛擬環境避免套件版本衝突。
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install mlx-whisper
這幾行指令的說明：
python3 -m venv .venv：在目前資料夾建立一個名為.venv的虛擬環境source .venv/bin/activate：進入虛擬環境，終端機前會出現(.venv)提示pip install -U pip：把 pip 升級到最新版，避免安裝新套件時出現相容性問題pip install mlx-whisper：安裝主套件
要退出虛擬環境時，輸入 deactivate 即可。
安裝 ffmpeg
mlx-whisper 需要 ffmpeg 處理音訊格式，用 Homebrew 安裝：
brew install ffmpeg準備測試音訊
Mac 內建 say 指令可以直接產生語音測試檔，不需要另外下載：
# 英文測試
say -o test_audio.aiff "Hello, this is a test audio file."
ffmpeg -i test_audio.aiff audio_file.mp3
# 繁體中文測試（使用內建美佳語音）
say -v Meijia -o test_audio.aiff "你好，這是一個測試音訊檔案。"
ffmpeg -i test_audio.aiff audio_file.mp3
登入 Hugging Face
下載模型前需要先登入 Hugging Face，否則會出現 401 或 404 錯誤。
前往 https://huggingface.co/settings/tokens 建立一個 Read 權限的 token，再執行：
python -c "from huggingface_hub import login; login(token='hf_你的token')"
登入成功後 token 會儲存在 ~/.cache/huggingface/token，之後不需要重複登入。
執行語音轉錄
mlx_whisper audio_file.mp3 --model mlx-community/whisper-large-v3-mlx
第一次執行時會自動從 Hugging Face 下載模型，whisper-large-v3-mlx 約 3GB，下載完成後會快取在：
之後再次執行相同模型就不會重複下載。
轉錄完成後，結果會輸出到同名的 .txt 檔案，例如 audio_file.txt。
如果想釋放硬碟空間，可以用以下指令刪除已下載的模型：
rm -rf ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-mlx/
刪除後若再次執行轉錄，會重新從 Hugging Face 下載。若想確認目前快取了哪些模型以及各自佔用的空間，可以執行：
du -sh ~/.cache/huggingface/hub/*/
常見模型選擇
mlx-community 提供多種大小的 Whisper 模型，正確的 repo 名稱格式需要加上 -mlx 後綴：
- tiny：
mlx-community/whisper-tiny-mlx，速度最快，精度較低 - small：
mlx-community/whisper-small-mlx，輕量平衡 - large-v3：
mlx-community/whisper-large-v3-mlx，高精度 - large-v3-turbo：
mlx-community/whisper-large-v3-turbo，速度與精度的最佳平衡，推薦 - distil-large-v3：
mlx-community/distil-whisper-large-v3，蒸餾版，速度快
如果主要轉錄中文，建議使用 large-v3 以上的模型，tiny 對中文的識別準確率偏低。
輸出繁體中文
參考資料-簡繁轉換不再亂碼！開源神組件 OpenCC 安裝與模式切換全攻略
Whisper 轉錄中文時預設輸出簡體，可以用 opencc 做後處理轉換成繁體台灣用語：
pip install opencc-python-reimplemented
轉換指令：
python -c "import opencc; c = opencc.OpenCC('s2twp'); print(c.convert(open('audio_file.txt').read()))" > audio_file_tw.txt
s2twp 模式會將簡體轉為繁體，並同時替換為台灣慣用詞，例如「軟件」→「軟體」、「音讯」→「音訊」。
一行完成轉錄到繁體輸出
把上面兩個步驟串在一起，每次只需要一行指令：
mlx_whisper 你的音訊.mp3 --model mlx-community/whisper-large-v3-mlx && \
python -c "import opencc; c = opencc.OpenCC('s2twp'); print(c.convert(open('你的音訊.txt').read()))" > 你的音訊_tw.txt
把 你的音訊 替換成實際的檔名即可。執行後會產生兩個檔案：簡體原始版本與繁體台灣版本，整個流程完全在本機離線運行，不需要送出任何資料到外部服務。
