---
title: 在 macOS 上安裝使用 Whisper.cpp 完整指南
description: 實作 OpenAI Whisper 語音識別模型的 C++ 版本，支援即時麥克風辨識和多語言（含中文）轉錄
tags: whisper, openai, audio-transcription, speech-recognition, cpp, macos
image: https://i.imgur.com/EKlSBgc.png
lang: zh-tw
---
# 在 macOS 上安裝使用 Whisper.cpp 完整指南
:::info
**📄 文件說明**：本文檔詳細介紹如何在 macOS 系統上安裝、編譯和使用 Whisper.cpp 進行即時語音辨識，支援中文（繁體/簡體）。最後更新：2025年5月
:::
[TOC]
## 📚 簡介
[whisper.cpp](https://github.com/ggerganov/whisper.cpp) 是 OpenAI [Whisper](https://openai.com/research/whisper) 語音識別模型的 C/C++ 實作版本，與原版 Python 相比，具有以下優點：
- 🚀 **更快速**：C++ 實作使推理速度提升 4-5 倍
- 💻 **更輕量**：不需要 Python、PyTorch 或大型 ML 框架
- 📱 **更便攜**：可在多種裝置上運行，包括 CPU 和 GPU 支援
### 主要功能
- ✓ 即時麥克風語音辨識
- ✓ 支援多國語言（含繁體/簡體中文）
- ✓ 高精度語音轉錄
- ✓ 低延遲和高效能
- ✓ 語音活動偵測（VAD）整合
- ✓ 時間戳標記（定位詞語時間點）
- ✓ 輸出多種格式（文字、SRT、VTT 字幕）
- ✓ 支援 Apple Silicon 原生加速
## 🛠️ 環境設置
### 系統需求
- macOS 10.15 (Catalina) 或更新版本
- 4GB+ RAM（建議 8GB+）
- 支援 Intel 和 Apple Silicon (M1/M2/M3) 晶片
## 💨 快速安裝方法 (2025年最新)
### 使用 Homebrew 一鍵安裝 (最簡單)
2025年，Whisper.cpp 已正式提供 Homebrew 安裝套件，這是最簡單的安裝方法：
```bash
# 安裝 Whisper.cpp 和依賴的 ffmpeg
brew install whisper-cpp ffmpeg
```
:::tip
**提示**：這種方法適合快速入門，但功能相對有限。若需要最大化效能或啟用進階功能（如 Metal 加速），建議從源碼編譯安裝。
:::
### 檢查安裝版本
安裝後，您可以檢查 Whisper.cpp 的版本：
```bash
whisper-cpp --version
```
目前最新穩定版本為 v1.7.2（截至2025年5月）。
## 🎤 安裝 SDL2 音訊處理函式庫
whisper.cpp 的即時轉錄功能依賴 SDL2 來擷取麥克風音訊。
在終端機中執行以下命令安裝 SDL2：
```bash
brew install sdl2
```
## 📥 從源碼編譯安裝 (進階選項)
### 1. 複製專案
```bash
git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp
# 切換到最新穩定版本（目前為v1.7.2）
git checkout -b v1.7.2 v1.7.2
```
### 2. 啟用 Metal 和 Core ML 加速 (Apple Silicon 專用)
對於 M1/M2/M3 芯片的 Mac，可以啟用 Metal 和 Core ML 加速以獲得最佳效能：
```bash
# 使用 Metal 加速（Apple Silicon 優化）
cmake -B build -DWHISPER_METAL=ON -DWHISPER_SDL2=ON
```
或者也可以啟用 Core ML：
```bash
# 使用 Core ML 加速
cmake -B build -DWHISPER_COREML=ON -DWHISPER_SDL2=ON
```
### 3. 標準編譯（適用於所有 Mac）
如果不需要特殊加速，可以使用標準編譯：
```bash
cmake -B build -DWHISPER_SDL2=ON
cmake --build build --config Release
```
編譯完成後，whisper-stream 可執行檔將位於 `build/bin/` 目錄中。
## 🔎 模型選擇與下載
Whisper 提供多種不同大小和精確度的模型。對於中文語音辨識，建議使用多語言模型，而非僅限英文的 `*.en` 模型。
### 模型對照表 (2025年更新)
| 模型名稱 | 檔案大小 | 記憶體需求 | 相對速度 | 準確度 | 中文支援 | 備註 |
|---------|--------|-----------|---------|-------|---------|------|
| tiny | ~75MB | ~390MB | 最快 | 最低 | ✅ 基本支援 | 適合極度受限的裝置 |
| base | ~142MB | ~500MB | 快 | 較低 | ✅ 支援 | 適合一般對話 |
| small | ~466MB | ~1.0GB | 中等 | 中等 | ✅ 良好支援 | 平衡速度和準確度 |
| medium | ~1.5GB | ~2.6GB | 較慢 | 較高 | ✅ 優良支援 | 適合專業轉錄 |
| large-v3 | ~3.1GB | ~5.0GB | 慢 | 最高 | ✅ 最佳支援 | 最高準確度 |
| large-v3-turbo | ~3.0GB | ~4.8GB | 中等 | 較高 | ✅ 最佳支援 | **新**: 平衡速度與準確度 |
:::warning
**注意**：
- 帶有 `-q5_0` 或 `-q8_0` 後綴的模型是量化版本，犧牲少量準確度來換取更快的速度和更小的檔案大小
- 帶有 `-turbo` 後綴的模型是2024年新增的平衡型模型，提供更好的效能和精確度平衡
:::
### Apple Silicon 專用模型
對於 M1/M2/M3 芯片的 Mac，可以使用專為 Apple Silicon 優化的模型版本：
```bash
# 下載 Apple Silicon 優化版 large-v3 模型
./models/download-ggml-model.sh large-v3-applesilicon
```
### 一般模型下載
使用內建的下載腳本取得所需模型：
```bash
# 下載 base 多語言模型（支援中文，較小）
./models/download-ggml-model.sh base
# 或下載量化版 large-v3 模型（最佳中文支援，速度較快）
./models/download-ggml-model.sh large-v3-q5_0
# 或下載新的 turbo 模型（平衡速度與準確度）
./models/download-ggml-model.sh large-v3-turbo
# 或下載完整 large-v3 模型（最佳準確度，但較慢）
./models/download-ggml-model.sh large-v3
```
:::info
**提示**：下載時請使用模型名稱（如 `large-v3`），而非檔案名稱（如 `ggml-large-v3.bin`）。
:::
## 🎧 音訊格式處理
Whisper.cpp 最佳支援 16kHz、16-bit 單聲道 WAV 格式。如果您的音訊檔案是其他格式，需要先進行轉換。
### 使用 ffmpeg 轉換音訊
```bash
# 將任何音訊檔案轉換為 Whisper 最佳支援格式
ffmpeg -i 輸入檔案.mp3 -ar 16000 -ac 1 -c:a pcm_s16le 輸出檔案.wav
```
### 從影片提取音訊
```bash
# 從影片提取音訊並轉換為適合的格式
ffmpeg -i 影片檔案.mp4 -ar 16000 -ac 1 -c:a pcm_s16le 輸出檔案.wav
```
## 🚀 執行即時語音轉錄
### 中文語音辨識（即時麥克風輸入）
```bash
# Homebrew 安裝版本的執行方式
whisper-cpp \
--model ~/tools/ggml-large-v3-turbo.bin \
--language zh \
--threads 4 \
--step 500 \
--length 5000 \
--vad-thold 0.6 \
--print-colors \
--split-on-word \
--max-len 65
# 或使用源碼編譯版本的執行方式
./build/bin/whisper-stream \
-m models/ggml-large-v3-q5_0.bin \
-l zh \
-t 4 \
--step 500 \
--length 5000 \
--keep 200 \
--vad-thold 0.6 \
--freq-thold 100.0 \
-ps \
-kc \
-f whisper_output.txt
```
### 2025年新增實用參數
| 參數 | 說明 |
|-----|------|
| `--split-on-word` | 在單詞邊界分割文本，避免單詞被截斷 |
| `--print-colors` | 使用彩色輸出，提高可讀性 |
| `--max-len <n>` | 設定每行最大字元數，適合字幕製作 |
| `--no-timestamps` | 關閉時間戳記輸出 |
| `--output-vtt` | 輸出 WebVTT 格式字幕 |
| `--output-srt` | 輸出 SRT 格式字幕 |
### 原有參數說明
| 參數 | 說明 |
|-----|------|
| `-m` | 模型檔案路徑 |
| `-l zh` | 語言設定為中文（支援繁體/簡體） |
| `-t 4` | 使用 4 個執行緒 |
| `--step 500` | 每 500ms 擷取語音進行分析 |
| `--length 5000` | 每輪處理 5 秒音訊 |
| `--keep 200` | 保留前一段 200ms 防止語音被截斷 |
| `--vad-thold 0.6` | 語音活動偵測門檻，0.5~0.8 間調整 |
| `--freq-thold 100.0` | 高通濾波，消除背景低頻雜訊 |
| `-ps` | 顯示特殊 tokens，如 [NOISE] |
| `-kc` | 保留語境，可提升對話連貫性 |
| `-f whisper_output.txt` | 將輸出儲存至文字檔 |
:::tip
**最佳化提示**：若模型辨識結果出現重複詞彙循環，可以：
1. 降低 `--keep` 值至 100ms
2. 不使用 `-kc` 參數
3. 增加 `--step` 間隔時間至 1000ms
4. 考慮使用未量化的完整模型
:::
## 📊 效能參考數據 (2025年)
以下是在不同 Apple 裝置上處理 10 分鐘中文音訊的參考時間：
| 裝置 | 模型 | 處理時間 | 即時因子 |
|------|------|---------|--------|
| MacBook Pro M3 | large-v3-turbo | ~1.5 分鐘 | 6.7x |
| MacBook Pro M2 | large-v3-q5_0 | ~2 分鐘 | 5.0x |
| MacBook Air M1 | medium | ~1.8 分鐘 | 5.5x |
| Mac Mini Intel i5 | small | ~2.5 分鐘 | 4.0x |
*即時因子：處理時間與音訊長度的比率，越高越好*
## 📱 進階應用：集成到 iOS/macOS 應用
Whisper.cpp 2025年版本提供了 XCFramework 支援，方便開發者集成到自己的 iOS 和 macOS 應用中。
### 建立 XCFramework
```bash
# 在 whisper.cpp 目錄下
cd apple
./setup.sh
./build-xcframework.sh
```
這將在 `apple/framework/whisper.xcframework` 生成可直接集成到 Xcode 專案的框架。
### 在 Xcode 專案中使用
1. 將生成的 `whisper.xcframework` 拖曳到您的 Xcode 專案
2. 在 Build Phases > Link Binary With Libraries 中確認框架已加入
3. 在 Swift 或 Objective-C 代碼中引用 Whisper API
```swift
import whisper
// 初始化 Whisper 上下文
let context = whisper_init_from_file("path/to/model.bin")
// 使用 Whisper 進行轉錄
// ...
// 釋放資源
whisper_free(context)
```
## 📝 常用指令範例
### 建立便捷執行腳本
可以創建 `whisper-mic.sh` 腳本，方便日後執行：
```bash
#!/bin/bash
./build/bin/whisper-stream \
-m models/ggml-large-v3-q5_0.bin \
-l zh \
-t 4 \
--step 500 \
--length 5000 \
--keep 200 \
--vad-thold 0.6 \
--freq-thold 100.0 \
-ps \
-kc \
-f whisper_output.txt
```
加上執行權限：
```bash
chmod +x whisper-mic.sh
```
### 處理音訊檔案（非即時）
使用 `whisper-cli` 工具處理預先錄製的音訊檔：
```bash
./build/bin/whisper-cli \
-m models/ggml-large-v3-q5_0.bin \
-f samples/zh.wav \
-l zh \
--output-txt \
--output-srt
```
### 自動檢測語言
```bash
# 自動檢測音訊的語言
./build/bin/whisper-cli \
-m models/ggml-large-v3.bin \
-f samples/audio.wav \
--auto-language
```
## 🔍 常見問題排解
### 1. 辨識結果重複詞彙或句子
**問題**：輸出像 `[_BEG_]回顧一年的房地產[_TT_100][_TT_100]回顧一年的房地產[_TT_200]...` 反覆出現。
**解決方案**：
- 減少 `--keep` 參數值
- 移除 `-kc` 參數
- 增加 `--step` 間隔
- 使用更高質量的模型
### 2. 輸出含有 `[_BEG_]` 和 `[_TT_]` 標記
**說明**：
- `[_BEG_]` 表示新段落開始
- `[_TT_150]` 是時間戳標記（表示 1.5 秒）
這些是內部標記，用於標示轉錄時間點，一般可忽略。
### 3. 不想在終端顯示輸出
```bash
./build/bin/whisper-stream ... > /dev/null
```
這會將所有輸出導向空設備，但仍保留檔案輸出（如有使用 `-f` 參數）。
### 4. Metal 或 Core ML 加速無法使用
**問題**：編譯時啟用了 Metal 或 Core ML，但執行時出現錯誤。
**解決方案**：
- 確保您使用的是 Apple Silicon Mac
- 使用 `xcode-select --install` 確保開發工具齊全
- 嘗試更新至最新的 macOS 版本
## 🌐 網頁版支援 (2025新增)
Whisper.cpp 現在也支援在網頁瀏覽器中運行(透過 WebAssembly)：
1. 在線試用：https://ggml.ai/whisper.cpp/
2. 自行部署：
```bash
cd examples/web
./build.sh
python -m http.server
```
## 📚 參考資源
- [whisper.cpp GitHub 倉庫](https://github.com/ggerganov/whisper.cpp)
- [OpenAI Whisper 模型](https://github.com/openai/whisper)
- [Hugging Face 模型庫](https://huggingface.co/ggerganov/whisper.cpp)
- [Apple Metal 加速指南](https://developer.apple.com/metal/)
- [Core ML 集成文檔](https://developer.apple.com/documentation/coreml)
---
###### tags: `whisper` `openai` `audio-transcription` `speech-recognition` `cpp` `macos`
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet