---
# System prepended metadata

title: "\U0001F399️ macOS 免費影片轉文字教學（Whisper.cpp + ffmpeg）"
tags: [Side Project, AI]

---

本教學示範如何在 **macOS** 使用 **Whisper.cpp** 將影片離線轉成文字，全程免費、支援中文。

---

## 🧩 一、安裝 Homebrew

打開終端機（Terminal）並輸入：

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

完成後測試：

```bash
brew -v
```

若顯示版本號，表示安裝成功。

---

## 🧠 二、安裝必要工具

```bash
brew install cmake ffmpeg git
```

* `cmake`：編譯工具
* `ffmpeg`：影音轉檔工具
* `git`：下載 Whisper.cpp 原始碼

---

## 🦜 三、下載 Whisper.cpp

```bash
cd ~
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp
```

---

## 🧱 四、編譯 Whisper.cpp

```bash
make
```

完成後會產生執行檔於：

```
~/whisper.cpp/build/bin/
```

---

## 🧰 五、下載模型（建議 large-v3）

```bash
bash ./models/download-ggml-model.sh large-v3
```

完成後模型會儲存在：

```
~/whisper.cpp/models/ggml-large-v3.bin
```

---

## 🎞️ 六、影片轉音訊（必要步驟）

Whisper 無法直接讀取 `.mp4`，請用 ffmpeg 轉成 `.wav`：

```bash
ffmpeg -i ~/Downloads/voice_92964.mp4 -ar 16000 -ac 1 ~/Downloads/voice_92964.wav
```

說明：

* `-ar 16000`：16kHz 取樣率
* `-ac 1`：單聲道音訊


---

## 🗣️ 七、轉錄語音成文字

```bash
cd ~/whisper.cpp/build/bin
./whisper-cli -m ~/whisper.cpp/models/ggml-large-v3.bin -f ~/Downloads/voice_92964.wav -l zh > ~/Downloads/voice_92964.txt
```

說明：

* `-m` 指定模型
* `-f` 指定音訊檔
* `-l zh` 指中文模式（可改 `auto` 自動語言偵測）
* `> ~/Downloads/voice_92964.txt` 將輸出文字儲存為檔案

執行後：

* 文字會同時顯示在終端機
* 並儲存到 `~/Downloads/voice_92964.txt`


---

## ⚙️ 八、（可選）GPU 加速（Apple M1/M2/M3）

Whisper.cpp 會自動偵測 Metal GPU，無需額外設定。若想確認：

```bash
./whisper-cli -m ~/whisper.cpp/models/ggml-large-v3.bin -f ~/Downloads/voice_92964.wav -l zh --print-gpu
```

---

## ✅ 成功結果

終端機會顯示類似以下輸出：

```
[00:00.000 --> 00:05.000] 你好，這是測試語音。
[00:05.000 --> 00:10.000] Whisper 成功把影片轉成文字。
```

同時產生：

```
voice_92964.wav.txt
```

---

## 🧹 九、常見錯誤排除

| 問題                                 | 解決方式                   |
| ---------------------------------- | ---------------------- |
| `command not found: whisper-cpp`   | 使用從 Git 編譯版本           |
| `invalid model data (bad magic)`   | 下載新版模型 `large-v3`      |
| `failed to read audio data as wav` | 先用 ffmpeg 轉成 `.wav`    |
| 欲重編譯                               | 刪除 `build/` 後重跑 `make` |

---

## 📘 參考連結

* [Whisper.cpp 官方 GitHub](https://github.com/ggerganov/whisper.cpp)
* [HuggingFace 模型列表](https://huggingface.co/ggerganov/whisper.cpp/tree/main)
* [FFmpeg 官方網站](https://ffmpeg.org/)

---
