Ubuntu BreezyVoice 從零開始完整安裝設定指南

February 25, 2025

Ubuntu BreezyVoice 從零開始完整安裝設定建議 (基於官方文件)

Step 1: 環境準備 (系統更新與基本工具安裝)

開啟 Ubuntu 終端機 (Terminal)：在 Ubuntu 桌面環境中，您可以透過應用程式選單搜尋 “Terminal” 或使用快捷鍵 Ctrl + Alt + T 開啟終端機。
更新系統套件列表與已安裝套件: 保持系統套件最新，有助於避免相容性問題。
```
sudo apt update
sudo apt upgrade -y
```
安裝必要的系統工具: 這些工具包含程式碼下載、編譯以及套件管理所需的基礎工具。
```
sudo apt install -y git curl wget apt-utils
```

Step 2: 安裝 Python 3.10 環境

BreezyVoice 需要 Python 3.10 版本。請確認您的 Ubuntu 環境中已安裝或安裝正確版本的 Python。

1.  **檢查 Python 版本**:  先確認系統中預設的 Python 版本。

    ```bash
    python3 --version
    ```

    如果版本不是 3.10.x，您需要安裝 Python 3.10。

2.  **安裝 Python 3.10 (如果需要)**:  您可以使用 `deadsnakes` PPA 來安裝 Python 3.10。

    ```bash
    sudo add-apt-repository ppa:deadsnakes/ppa
    sudo apt update
    sudo apt install -y python3.10 python3.10-venv  # 同時安裝虛擬環境工具
    ```

3.  **確認 Python 3.10 安裝成功**: 再次檢查版本，確認已安裝 Python 3.10。

    ```bash
    python3.10 --version
    ```

4.  **設定 Python 3.10 為預設 (可選)**:  如果您希望之後直接使用 `python3` 指令就指向 Python 3.10，可以考慮設定預設版本 (請謹慎操作，可能影響其他系統工具)。

    ```bash
    sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
    python3 --version # 再次確認預設 python3 版本
    ```

Step 3: 下載 BreezyVoice 程式碼

Clone GitHub 倉庫: 使用 git clone 指令下載 BreezyVoice 程式碼。

git clone https://github.com/mtkresearch/BreezyVoice.git
cd BreezyVoice

處理 Submodule (如果 Clone 失敗): 如果因為網路問題導致 submodule 下載失敗，請嘗試以下指令，直到成功為止。
```
git submodule update --init --recursive
```

Step 4: 安裝 BreezyVoice 相依性套件

進入 BreezyVoice 專案目錄: 如果您還沒在專案目錄下，請先進入。
```
cd BreezyVoice
```
解除安裝 onnxruntime: 根據文件指示，先解除安裝預設的 onnxruntime。
```
pip3 uninstall onnxruntime
```
安裝相依性套件: 使用 pip3 安裝 requirements.txt 中列出的所有套件。請注意，這裡使用 pip3 指令，確保使用您安裝的 Python 3.10 環境的 pip。
```
pip3 install -r requirements.txt
```
CPU 或 GPU 環境選擇:
- GPU 環境 (建議): requirements.txt 預設安裝 onnxruntime-gpu，這會利用 GPU 加速模型運算，提供更快的推理速度。請確保您的環境已正確安裝 CUDA 和 cuDNN。
- CPU 環境: 如果您沒有 GPU 或想在 CPU 上執行，請先修改 requirements.txt 檔案，將 onnxruntime-gpu 替換為 onnxruntime，然後再執行 pip3 install -r requirements.txt。
安裝 cuDNN (如果需要): 如果您使用 GPU 環境，且遇到 cuDNN 相關錯誤，可能需要手動安裝。文件範例指令如下，請根據您的 CUDA 版本調整。
```
sudo apt-get -y install cudnn9-cuda-11  # 範例指令，CUDA 11 版本
```
請根據您的 CUDA 版本，參考 NVIDIA cuDNN 安裝文件，尋找對應的 Ubuntu 安裝指令。

Step 5: 設定 UTF8 環境變數

BreezyVoice 需要 UTF8 編碼。請設定 PYTHONUTF8 環境變數。

```bash
export PYTHONUTF8=1
```

建議將這行指令加入到您的 `~/.bashrc` 或 `~/.zshrc`  (如果您使用 zsh)  檔案中，讓每次開啟終端機時自動設定。

```bash
echo "export PYTHONUTF8=1" >> ~/.bashrc  # 或 ~/.zshrc
source ~/.bashrc                         # 或 source ~/.zshrc，使設定立即生效
```

Step 6: 執行單句語音合成 (Single Inference)

使用 single_inference.py 腳本進行單句語音合成。

1.  **基本用法範例**:  合成文字 "今天天氣真好"，使用範例音訊 `./data/example.wav` 作為 speaker prompt。

    ```bash
    python3 single_inference.py \
      --content_to_synthesize "今天天氣真好" \
      --speaker_prompt_text_transcription "在密碼學中，加密是將明文資訊改變為難以讀取的密文內容，使之不可讀的方法。" \
      --speaker_prompt_audio_path "./data/example.wav"
    ```

2.  **包含注音符號的文字範例**: 合成文字 "今天天氣真好[:ㄏㄠ3]" ( "好" 字帶有三聲注音)。

    ```bash
    python3 single_inference.py \
      --content_to_synthesize "今天天氣真好[:ㄏㄠ3]" \
      --speaker_prompt_audio_path "./data/example.wav"
    ```

3.  **使用 `run_single_inference.sh` 腳本**:  專案也提供了 `run_single_inference.sh` 腳本，您可以直接執行。

    ```bash
    bash run_single_inference.sh
    ```

**`single_inference.py` 參數說明**:

*   `--content_to_synthesize`:  **必要參數**。指定要合成語音的文字內容。可以包含注音符號 (選用，少量使用)。
    *   純文字範例: `"今天天氣真好"`
    *   帶注音符號範例: `"今天天氣真好[:ㄏㄠ3]"`
*   `--speaker_prompt_audio_path`: **必要參數**。指定 speaker prompt 音訊檔案路徑，用於設定語音風格。可以使用自訂音訊或範例音訊 `./data/tc_speaker.wav`。
    *   範例音訊: `./data/tc_speaker.wav`
*   `--speaker_prompt_text_transcription` (**選用但強烈建議**)。speaker prompt 音訊的文字轉錄稿。提供此資訊有助於提高準確性。若不提供，系統會自動使用 Whisper 進行轉錄。
    *   範例文字 (對應範例音訊): `"在密碼學中，加密是將明文資訊改變為難以讀取的密文內容，使之不可讀的方法。"`
*   `--output_path` (**選用**)。指定輸出 `.wav` 檔案的路徑和名稱。預設路徑為 `results/output.wav`。
    *   預設值: `results/output.wav`
    *   範例: `[your_file_name].wav`
*   `--model_path` (**選用**)。指定使用的預訓練模型路徑。預設值為 `MediaTek-Research/BreezyVoice` (Hugging Face Hub 模型名稱)。
    *   預設值: `MediaTek-Research/BreezyVoice`

Step 7: 執行批次語音合成 (Batch Inference)

使用 batch_inference.py 腳本進行批次語音合成。

1.  **基本用法範例**:  執行批次合成，使用 `./data/batch_files.csv` 作為輸入 CSV 檔案， `./data` 作為 speaker prompt 音訊檔案資料夾， `./results` 作為輸出音訊檔案資料夾。

    ```bash
    python3 batch_inference.py \
      --csv_file ./data/batch_files.csv \
      --speaker_prompt_audio_folder ./data \
      --output_audio_folder ./results
    ```

2.  **使用 `run_batch_inference.sh` 腳本**: 專案也提供了 `run_batch_inference.sh` 腳本，可以直接執行。

    ```bash
    bash run_batch_inference.sh
    ```

**`batch_inference.py` 參數說明**:

*   `--csv_file`: **必要參數**。CSV 檔案路徑，包含批次處理的輸入資料。
    *   範例: `./data/batch_files.csv`
*   `--speaker_prompt_audio_folder`: **必要參數**。speaker prompt 音訊檔案所在的資料夾路徑。
    *   範例: `./data`
*   `--output_audio_folder`: **必要參數**。輸出音訊檔案的儲存資料夾路徑。
    *   範例: `./results`

**CSV 檔案結構 (`batch_files.csv`)**:

CSV 檔案應包含以下欄位 (欄位名稱必須一致):

*   `speaker_prompt_audio_filename`: **必要欄位**。speaker prompt 音訊檔案名稱 (不含副檔名)。系統會從 `--speaker_prompt_audio_folder` 指定的資料夾中尋找對應檔案。
    *   範例: `example`
*   `speaker_prompt_text_transcription`: **選用但強烈建議**。speaker prompt 音訊的文字轉錄稿。
    *   範例: `"在密碼學中，加密是將明文資訊改變為難以讀取的密文內容，使之不可讀的方法。"`
*   `content_to_synthesize`: **必要欄位**。要合成語音的文字內容。
    *   範例: `"今天天氣真好"`
*   `output_audio_filename`: **必要欄位**。輸出音訊檔案名稱 (不含副檔名)。音訊檔案將以 `.wav` 格式儲存到 `--output_audio_folder` 指定的資料夾中。
    *   範例: `output`

Step 8: 引用 (Citation)

如果您覺得 BreezyVoice 對您的研究有幫助，請在您的論文中引用以下文獻：

```
@article{hsu2025breezyvoice,
  title={BreezyVoice: Adapting TTS for Taiwanese Mandarin with Enhanced Polyphone Disambiguation--Challenges and Insights},
  author={Hsu, Chan-Jan and Lin, Yi-Cheng and Lin, Chia-Chun and Chen, Wei-Chih and Chung, Ho Lam and Li, Chen-An and Chen, Yi-Chang and Yu, Chien-Yu and Lee, Ming-Ji and Chen, Chien-Cheng and others},
  journal={arXiv preprint arXiv:2501.17790},
  year={2025}
}
@article{hsu2025breeze,
  title={The Breeze 2 Herd of Models: Traditional Chinese LLMs Based on Llama with Vision-Aware and Function-Calling Capabilities},
  author={Hsu, Chan-Jan and Liu, Chia-Sheng and Chen, Meng-Hsi and Chen, Muxi and Hsu, Po-Chun and Chen, Yi-Chang and Shiu, Da-Shan},
  journal={arXiv preprint arXiv:2501.13921},
  year={2025}
}
@article{du2024cosyvoice,
  title={Cosyvoice: A scalable multilingual zero-shot text-to-speech synthesizer based on supervised semantic tokens},
  author={Du, Zhihao and Chen, Qian and Zhang, Shiliang and Hu, Kai and Lu, Heng and Yang, Yexin and Hu, Hangrui and Zheng, Siqi and Gu, Yue and Ma, Ziyang and others},
  journal={arXiv preprint arXiv:2407.05407},
  year={2024}
}
```

重要提醒:

以 GitHub 文件為準: 本文件是基於您提供的 GitHub 安裝文件整理而成，但 GitHub 上的文件內容可能隨時更新。請務必以 BreezyVoice GitHub 頁面上的最新官方文件為準。
環境相依性: 請仔細檢查 requirements.txt 中的套件版本需求，並確保您的環境符合。
錯誤處理: 如果在安裝或執行過程中遇到任何錯誤，請仔細閱讀錯誤訊息，並嘗試網路搜尋解決方案。
社群支援: 如果遇到無法解決的問題，可以嘗試在 GitHub 專案的 Issue 頁面尋求協助。

Ubuntu BreezyVoice 從零開始完整安裝設定指南

標籤

延伸閱讀