# MockingBird 安裝指南
> 以開源專案 **babysor/MockingBird** 為例，從環境準備、相依安裝、模型放置到啟動 WebUI 的完整流程。

[TOC]

---

## 1. 前置需求（Prerequisites）
- **作業系統**：Windows 10/11（macOS/Linux 亦可，本文以 Windows 為主）
- **Python**：**3.8 ~ 3.10**（建議 3.10；請勾選「Add Python to PATH」）
- **PyTorch**：依 GPU/CUDA 能力選擇（或 **CPU** 版）
- **ffmpeg**：需可由系統 `PATH` 直接呼叫
- **（Windows）C++ Build Tools**：用於原生套件編譯（如 webrtcvad 等）

---

## 2. 安裝 Python（建議 3.10）
1. 下載安裝包（<https://www.python.org/downloads/>），選 **3.10.x** 版本。
2. 安裝時**務必勾選**：**Add Python to PATH**。
3. 確認版本：

   python --version

> **可選（推薦）**：為專案建立獨立虛擬環境

# 在 MockingBird 專案目錄外先建立資料夾
mkdir D:\voice && cd D:\voice

# 建立虛擬環境
python -m venv .venv

# 啟用（PowerShell）
.\.venv\Scripts\Activate.ps1

# 升級 pip
python -m pip install --upgrade pip

---

## 3. 安裝 PyTorch
前往官方引導頁，依 **OS / Package / Python /（CUDA 或 CPU）** 產生指令：
<https://pytorch.org/get-started/locally/>

**常見安裝示例**

- **CPU 版：**

  pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

- **CUDA 版（依你 GPU/CUDA 版本調整）：**

  # 例：CUDA 12.1（示意，實際以官網產生的指令為準）
  pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

> 若無 GPU 或 CUDA 不支援，請安裝 **CPU 版**。


---

## 4. 安裝 ffmpeg
1. 下載：<http://ffmpeg.org/download.html#build-windows>
2. 解壓縮後，將 `bin` 資料夾路徑加入 **系統環境變數 Path**。
- 「控制台 → 系統與安全性 → 系統 → 進階系統設定 → 環境變數 → Path → 新增 ffmpeg\bin」

**驗證**

ffmpeg -version


---

## 5. 下載並進入 MockingBird 專案
- **Zip 下載**：<https://github.com/babysor/MockingBird> → Download ZIP → 解壓縮
- **Git 下載（可選）**：

  git clone https://github.com/babysor/MockingBird.git
  cd MockingBird

> 在專案資料夾內**開啟終端機**（右鍵 → 在此開啟 PowerShell/命令提示字元）。


---

## 6. 安裝相依套件（requirements）

# 已啟用虛擬環境的情況下
python -m pip install --upgrade pip
pip install -r requirements.txt

# Windows 上若 webrtcvad 編譯失敗，可使用 wheels 版
pip install webrtcvad-wheels

---

## 7. 準備模型（Models）
專案執行需要已訓練的模型檔（不同分支/版本路徑略有差異，下列為常見做法）：

- 將 **.pt** 模型檔放入：

  MockingBird-main\data\ckpt\synthesizer

> （部分版本可能還需要 encoder/vocoder 模型，請依專案 README 為準）

- 範例來源（社群提供）：
- **分享两个训练好的 synthesizer 模型**（Issue #289）
<https://github.com/babysor/MockingBird/issues/289>

> 台灣腔模型資源相對較少，如需高擬真度可考慮自行蒐集資料集進行訓練。

---

## 8. 啟動 WebUI
在專案根目錄執行：

python .\web.py
# 或
py .\web.py

啟動後，終端機會輸出可點擊的本機網址（如 `http://127.0.0.1:<port>`）。
點擊進入 **WebUI** 進行資料上傳、訓練與推論。


---

## 9. 常見錯誤與解法（Troubleshooting）

### 9.1 編譯錯誤：找不到 `io.h`（C1083）

programs\python\python39\include\pyconfig.h(59): fatal error C1083: 無法開啟包含檔案: 'io.h': No such file or directory

**原因**：Windows 缺少 C/C++ 編譯工具鏈。
**解法**：
1. 安裝 **Microsoft C++ Build Tools**：
<https://visualstudio.microsoft.com/zh-hant/visual-cpp-build-tools/>
2. 勾選「**使用 C++ 的桌面開發**」（含 MSVC、Windows 10/11 SDK）
3. 重新執行：

   pip install -r requirements.txt


---

### 9.2 Pydantic 相容性（V2 移除 `parse_raw_as`）

PydanticImportError: `pydantic:parse_raw_as` has been removed in V2.

**解法**：將 pydantic 降版至 V1

pip install "pydantic<2"

---

### 9.3 其他常見問題速查
- **`ffmpeg not found`**：確認 `ffmpeg\bin` 已加入 `PATH`，重新開啟終端機再測試。
- **`No module named webrtcvad`**：安裝 `webrtcvad-wheels` 或在裝妥 Build Tools 後重試 `webrtcvad`。
- **CUDA 相依衝突**：改裝 **CPU 版** PyTorch 驗證是否為 CUDA 造成。
- **權限問題**：避免使用系統保護資料夾，將專案放到英文路徑（如 `D:\voice\MockingBird`）。

---

## 10. 安裝流程速查（Cheat Sheet）

# 1) Python & venv
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

# 2) PyTorch（CPU 例）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# 3) ffmpeg：下載後把 bin 加到 PATH

# 4) 下載專案 & 安裝相依
git clone https://github.com/babysor/MockingBird.git
cd MockingBird
pip install -r requirements.txt
pip install webrtcvad-wheels

# 5) 放模型（依 README）
#   MockingBird-main\data\ckpt\synthesizer\*.pt

# 6) 啟動
python .\web.py

---

###### tags: `MockingBird` `TTS` `Voice Cloning` `PyTorch` `Windows`