README.md

---
language:
- vi
license: mit
tags:
- text-to-speech
- tts
- matcha-tts
- vocos
- flow-matching
- speech
- vietnamese
datasets:
- custom
metrics:
- rtf
pipeline_tag: text-to-speech
---

# 🍵 Matcha-TTS & Vocos Tiếng Việt (22,050 Hz)

<p align="center">
  <a href="https://github.com/congkx123789/Matchtts_VI"><img src="https://img.shields.io/badge/GitHub-Matchtts__VI-181717?style=for-the-badge&logo=github" alt="GitHub Repository"></a>
  <a href="https://huggingface.co/Cong123779/Matchtts_VI"><img src="https://img.shields.io/badge/HuggingFace-Model%20Weights-FFD21E?style=for-the-badge&logo=huggingface&logoColor=black" alt="Hugging Face Model"></a>
  <img src="https://img.shields.io/badge/Sample%20Rate-22.05kHz%20PCM--16-blue?style=for-the-badge" alt="Audio Quality">
  <img src="https://img.shields.io/badge/Speed-Up%20to%2080x%20Realtime-brightgreen?style=for-the-badge" alt="Inference Speed">
</p>

Hệ thống tổng hợp giọng nói tiếng Việt tốc độ cao độc lập, kết hợp giữa mô hình **Matcha-TTS** nguyên bản (Conditional Flow Matching + RoPE Encoder) và **Vocos Neural Vocoder**.

- 🔗 **GitHub Repository:** [https://github.com/congkx123789/Matchtts_VI](https://github.com/congkx123789/Matchtts_VI)
- 🤗 **Hugging Face Model Weights:** [https://huggingface.co/Cong123779/Matchtts_VI](https://huggingface.co/Cong123779/Matchtts_VI)

---

## ⚡ Điểm Nổi Bật

- **Tốc độ cực nhanh (Fast Inference):** Đạt từ **30x – 80x Real-time** (chỉ mất ~97ms trên CPU với `steps=1` và ~260ms với `steps=10`).
- **Phát âm chuẩn tiếng Việt:** Tích hợp bộ chuẩn hóa chữ số, ngày tháng, thời gian, đơn vị đo lường và ngữ cảnh đặc thù ([`vietnamese_text_normalizer.py`](https://github.com/congkx123789/Matchtts_VI/blob/main/vietnamese_text_normalizer.py)).
- **Xử lý ký tự đặc biệt & ngoại lai:** Bộ lọc và phiên âm ký tự lạ ([`foreign_symbols_translator.py`](https://github.com/congkx123789/Matchtts_VI/blob/main/foreign_symbols_translator.py)).
- **Âm thanh trung thực:** Tần số lấy mẫu **22,050 Hz (PCM-16)**, âm sắc rõ ràng và tròn vành rõ chữ.
- **Tùy biến ngắt nghỉ:** Hỗ trợ điều chỉnh độ trễ ngắt nghỉ qua file cấu hình hoặc Giao diện Web trực quan.

---

## 📁 Cấu Trúc Dự Án

```text
Matchtts_VI/
├── checkpoints/                        # Thư mục lưu trữ trọng số mô hình (.pt, .ckpt)
│   ├── matcha_epoch10_clean.pt         # Checkpoint Matcha-TTS (CFM)
│   └── vocos_tri_dataset_epoch05.ckpt  # Checkpoint Vocos Vocoder
├── matcha/                             # Kiến trúc mạng cốt lõi Matcha-TTS
├── vocos/                              # Kiến trúc mạng Vocos Neural Vocoder
├── dataset_pipeline.py                 # Pipeline nạp và xử lý tập dữ liệu âm thanh
├── export_clean_tts_manifest.py        # Script xuất manifest dữ liệu huấn luyện
├── foreign_symbols_translator.py       # Xử lý phiên âm ký tự đặc biệt & từ ngoại lai
├── infer.py                            # Script CLI tổng hợp giọng nói (Inference)
├── load_model.py                       # Module nạp trọn bộ mô hình lên GPU/CPU
├── pause_config.json                   # Cấu hình thời gian ngắt nghỉ (dấu phẩy, chấm,...)
├── pause_control_web.py                # Dashboard Web trực quan điều khiển ngắt nghỉ
├── train_full_22050.py                 # Pipeline huấn luyện Matcha-TTS 22.05kHz
├── train_vocos_the_gioi_hoan_my.py     # Script huấn luyện / tinh chỉnh Vocos Vocoder
├── vietnamese_text_normalizer.py       # Bộ chuẩn hóa văn bản tiếng Việt
├── .env.example                        # Mẫu cấu hình Hugging Face token
└── README.md                           # Tài liệu hướng dẫn sử dụng
```

---

## 🛠️ Cài Đặt Môi Trường

Khuyến nghị sử dụng Python 3.10+:

```bash
# 1. Clone repository
git clone https://github.com/congkx123789/Matchtts_VI.git
cd Matchtts_VI

# 2. Cài đặt các thư viện cần thiết
pip install torch torchaudio soundfile omegaconf diffusers numpy scipy huggingface_hub
```

---

## 📥 Tải Checkpoints Từ Hugging Face

Bạn có thể tự động tải toàn bộ trọng số mô hình từ Hugging Face Hub vào thư mục `checkpoints/`:

```python
from huggingface_hub import hf_hub_download
import os

repo_id = "Cong123779/Matchtts_VI"
os.makedirs("checkpoints", exist_ok=True)

# Tải Matcha-TTS checkpoint
hf_hub_download(repo_id=repo_id, filename="checkpoints/matcha_epoch10_clean.pt", local_dir=".")

# Tải Vocos checkpoint
hf_hub_download(repo_id=repo_id, filename="checkpoints/vocos_tri_dataset_epoch05.ckpt", local_dir=".")
```

Hoặc tải nhanh bằng CLI:
```bash
huggingface-cli download Cong123779/Matchtts_VI --local-dir .
```

---

## 🚀 Hướng Dẫn Sử Dụng

### 1. Tổng Hợp Giọng Nói (CLI Inference)

Chạy lệnh tổng hợp âm thanh:

```bash
python3 infer.py --text "Xin chào, đây là giọng đọc tiếng Việt từ mô hình Matcha-TTS." --out "output.wav"
```

#### Bảng tham số:
| Tham số | Ý nghĩa | Mặc định | Gợi ý sử dụng |
|---|---|:---:|---|
| `--text` | Đoạn văn bản tiếng Việt cần đọc | - | Nhập câu bất kỳ |
| `--out` | Đường dẫn file wav đầu ra | `output_demo.wav` | File `.wav` |
| `--steps` | Số bước giải ODE (ODE Solver steps) | `10` | `1` (cực nhanh), `10` (chuẩn), `25` (chất lượng cao) |
| `--temp` | Nhiệt độ lấy mẫu (Temperature) | `0.667` | Khoảng `0.5` - `0.8` |
| `--speed` | Tốc độ đọc | `1.0` | `< 1.0` (chậm hơn), `> 1.0` (nhanh hơn) |

**Ví dụ chạy siêu tốc với 1 step (Real-time > 80x trên CPU):**
```bash
python3 infer.py --text "Matcha-TTS xử lý câu dài cực kỳ nhanh chóng." --steps 1 --out "fast.wav"
```

---

### 2. Giao Diện Web Điều Chỉnh Ngắt Nghỉ (Web UI)

Khởi động giao diện điều khiển ngắt nghỉ âm thanh theo từng dấu câu:

```bash
python3 pause_control_web.py
```
Mở trình duyệt truy cập vào địa chỉ hiển thị trên terminal để tinh chỉnh chi tiết độ dài ngắt nghỉ.

---

### 3. Huấn Luyện & Tinh Chỉnh (Training)

- **Huấn luyện Matcha-TTS (22.05kHz):**
  ```bash
  python3 train_full_22050.py
  ```
- **Huấn luyện Vocos Vocoder:**
  ```bash
  python3 train_vocos_the_gioi_hoan_my.py
  ```

---

## 📜 Giấy Phép & Đóng Góp

- **Mã nguồn:** [MIT License](https://github.com/congkx123789/Matchtts_VI/blob/main/LICENSE)
- **Mô hình pre-trained:** Tự do nghiên cứu và sử dụng phi thương mại / thương mại có ghi nguồn tác giả.
- Mọi đóng góp (pull request, issue) đều được hoan nghênh trên [GitHub Repository](https://github.com/congkx123789/Matchtts_VI)!