在 macOS 上安裝使用 Whisper.cpp 完整指南

📄 文件說明：本文檔詳細介紹如何在 macOS 系統上安裝、編譯和使用 Whisper.cpp 進行即時語音辨識，支援中文（繁體/簡體）。最後更新：2025年5月

## 📚 簡介

whisper.cpp 是 OpenAI 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 安裝套件，這是最簡單的安裝方法：

# 安裝 Whisper.cpp 和依賴的 ffmpeg
brew install whisper-cpp ffmpeg

:::tip 提示：這種方法適合快速入門，但功能相對有限。若需要最大化效能或啟用進階功能（如 Metal 加速），建議從源碼編譯安裝。 :::

檢查安裝版本

安裝後，您可以檢查 Whisper.cpp 的版本：

whisper-cpp --version

目前最新穩定版本為 v1.7.2（截至2025年5月）。

🎤 安裝 SDL2 音訊處理函式庫

whisper.cpp 的即時轉錄功能依賴 SDL2 來擷取麥克風音訊。

在終端機中執行以下命令安裝 SDL2：

brew install sdl2

📥 從源碼編譯安裝 (進階選項)

1. 複製專案

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 加速以獲得最佳效能：

# 使用 Metal 加速（Apple Silicon 優化）
cmake -B build -DWHISPER_METAL=ON -DWHISPER_SDL2=ON

或者也可以啟用 Core ML：

# 使用 Core ML 加速
cmake -B build -DWHISPER_COREML=ON -DWHISPER_SDL2=ON

3. 標準編譯（適用於所有 Mac）

如果不需要特殊加速，可以使用標準編譯：

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	中等	較高	✅ 最佳支援	新: 平衡速度與準確度

注意：

帶有 -q5_0 或 -q8_0 後綴的模型是量化版本，犧牲少量準確度來換取更快的速度和更小的檔案大小
帶有 -turbo 後綴的模型是2024年新增的平衡型模型，提供更好的效能和精確度平衡

### Apple Silicon 專用模型

對於 M1/M2/M3 芯片的 Mac，可以使用專為 Apple Silicon 優化的模型版本：

# 下載 Apple Silicon 優化版 large-v3 模型
./models/download-ggml-model.sh large-v3-applesilicon

一般模型下載

使用內建的下載腳本取得所需模型：

# 下載 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

提示：下載時請使用模型名稱（如 large-v3），而非檔案名稱（如 ggml-large-v3.bin）。

## 🎧 音訊格式處理

Whisper.cpp 最佳支援 16kHz、16-bit 單聲道 WAV 格式。如果您的音訊檔案是其他格式，需要先進行轉換。

使用 ffmpeg 轉換音訊

# 將任何音訊檔案轉換為 Whisper 最佳支援格式
ffmpeg -i 輸入檔案.mp3 -ar 16000 -ac 1 -c:a pcm_s16le 輸出檔案.wav

從影片提取音訊

# 從影片提取音訊並轉換為適合的格式
ffmpeg -i 影片檔案.mp4 -ar 16000 -ac 1 -c:a pcm_s16le 輸出檔案.wav

🚀 執行即時語音轉錄

中文語音辨識（即時麥克風輸入）

# Homebrew 安裝版本的執行方式
whisper-cpp \
  --model <sub>/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.50.8 間調整
`--freq-thold 100.0`	高通濾波，消除背景低頻雜訊
`-ps`	顯示特殊 tokens，如 [NOISE]
`-kc`	保留語境，可提升對話連貫性
`-f whisper_output.txt`	將輸出儲存至文字檔

:::tip 最佳化提示：若模型辨識結果出現重複詞彙循環，可以：

降低 --keep 值至 100ms
不使用 -kc 參數
增加 --step 間隔時間至 1000ms
考慮使用未量化的完整模型 :::

📊 效能參考數據 (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

# 在 whisper.cpp 目錄下
cd apple
./setup.sh
./build-xcframework.sh

這將在 apple/framework/whisper.xcframework 生成可直接集成到 Xcode 專案的框架。

在 Xcode 專案中使用

將生成的 whisper.xcframework 拖曳到您的 Xcode 專案
在 Build Phases > Link Binary With Libraries 中確認框架已加入
在 Swift 或 Objective-C 代碼中引用 Whisper API

import whisper

// 初始化 Whisper 上下文
let context = whisper_init_from_file("path/to/model.bin")

// 使用 Whisper 進行轉錄
// ...

// 釋放資源
whisper_free(context)

📝 常用指令範例

建立便捷執行腳本

可以創建 whisper-mic.sh 腳本，方便日後執行：

#!/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

加上執行權限：

chmod +x whisper-mic.sh

處理音訊檔案（非即時）

使用 whisper-cli 工具處理預先錄製的音訊檔：

./build/bin/whisper-cli \
  -m models/ggml-large-v3-q5_0.bin \
  -f samples/zh.wav \
  -l zh \
  --output-txt \
  --output-srt

自動檢測語言

# 自動檢測音訊的語言
./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. 不想在終端顯示輸出

./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)：

在線試用：https://ggml.ai/whisper.cpp/

自行部署：

cd examples/web
./build.sh
python -m http.server

📚 參考資源

tags: `whisper` `openai` `audio-transcription` `speech-recognition` `cpp` `macos`

本文最初發布於 HackMD @BASHCAT。