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

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

:::warning
**注意**：
- 帶有 `-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

:::info
**提示**：下載時請使用模型名稱（如 `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 ~/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

# 在 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

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

1. 在線試用：https://ggml.ai/whisper.cpp/
2. 自行部署：

   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`