tqd-voice
by abm-dungtq
README.md
<div align="center">
# 🎙️ TQD-Voice
### Xưởng giọng nói tiếng Việt chạy **100% trên máy của bạn**
*Local Vietnamese Text-to-Speech Studio — clone giọng chỉ từ **5 giây** audio, tự nhiên, rõ ràng, và **riêng tư tuyệt đối**.*
[](LICENSE)
[](pyproject.toml)
[](AGENTS.md)
[](omnivoice_vi/device.py)
[](#-riêng-tư--đạo-đức)
[](#)
</div>
---
> **TQD-Voice** biến văn bản tiếng Việt thành giọng nói chất lượng cao — ngay trên máy bạn, không gửi dữ liệu lên bất kỳ đám mây nào. Nói được với một trong **10 giọng bản địa** dựng sẵn, hoặc **nhân bản (clone) giọng bất kỳ** chỉ từ một đoạn mẫu 5–10 giây. Có sẵn **giao diện web Studio**, **REST API** và **MCP** để AI agent gọi như một công cụ.
## ✨ Vì sao TQD-Voice?
- 🔒 **Riêng tư tuyệt đối** — chạy loopback-only, không tài khoản, không token, không đám mây. Văn bản và giọng của bạn không rời khỏi máy.
- 🇻🇳 **Chuẩn tiếng Việt** — chuẩn hoá số, ngày tháng, phần trăm, đơn vị, chữ viết tắt và tiêu đề IN HOA; đọc tự nhiên, đúng ngữ điệu ba miền.
- ⚡ **Clone giọng tức thì** — zero-shot, không cần "train" hàng giờ: một đoạn mẫu ngắn là có giọng mới.
- 🎧 **10 giọng sẵn dùng** — Bắc / Trung / Nam, nam & nữ, đã kiểm bản quyền & ghi công.
- 🖥️ **Chạy mọi máy** — tự dò và dùng **NVIDIA CUDA**, **Apple Silicon (MPS)**, hoặc **CPU**.
- 🤖 **Agent tự cài đặt** — kèm `AGENTS.md`: một AI agent (vd Google Antigravity) tự setup đầu-cuối.
## 🚀 Bắt đầu trong 60 giây
```bash
git clone https://github.com/xaotiensinh-abm/tqd-voice.git
cd tqd-voice
```
**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1 # tự dò GPU, cài đúng PyTorch
powershell -ExecutionPolicy Bypass -File scripts\run-windows.ps1 # mở Studio ở trình duyệt
```
**Linux / macOS:**
```bash
bash scripts/setup-linux.sh && bash scripts/run-linux.sh
```
→ Mở **http://127.0.0.1:8765/ui**, gõ văn bản, chọn giọng, nghe ngay.
Toàn bộ quy trình cho AI agent nằm ở **[AGENTS.md](AGENTS.md)**.
## 🎧 Bộ giọng sẵn có
| ID | Tên | Giới tính | Vùng | Phù hợp |
|----|-----|:---------:|:----:|---------|
| `kim-long` | Kim Long | Nam | Trung | thuyết minh, kể chuyện |
| `vinh-nam-narrator` | Vĩnh (nam miền Nam) | Nam | Nam | kể chuyện, thuyết minh, video ngắn |
| `binh-nam-bac` | Bình (nam miền Bắc) | Nam | Bắc | kể chuyện, thuyết minh, video ngắn |
| `tuyen-nam-bac` | Tuyên (nam miền Bắc) | Nam | Bắc | kể chuyện, thuyết minh, video ngắn |
| `khang-nam-trungtinh` | Khang (nam, trung tính) | Nam | Trung tính | thuyết minh, kể chuyện |
| `cdteam-nam` | cdteam (nam) | Nam | Trung tính | kể chuyện, thuyết minh, video ngắn |
| `ly-nu-bac` | Ly (nữ miền Bắc) | Nữ | Bắc | kể chuyện, thuyết minh, video ngắn |
| `ngoc-nu-bac` | Ngọc (nữ miền Bắc) | Nữ | Bắc | kể chuyện, thuyết minh, video ngắn |
| `doan-nu-nam` | Đoan (nữ miền Nam) | Nữ | Nam | chăm sóc KH, video ngắn, kể chuyện |
| `mai-nu-trungtinh` | Mai (nữ, trung tính) | Nữ | Trung tính | thuyết minh, kể chuyện |
> Muốn thêm giọng của riêng bạn? Đưa một đoạn WAV 5–10 giây (được phép sử dụng) và clone — xem [AGENTS.md → Voices](AGENTS.md#voices--shipped-set--adding-new-ones) hoặc [`docs/voice-catalog.md`](docs/voice-catalog.md).
## 🏗️ Kiến trúc
```mermaid
flowchart LR
T["Văn bản tiếng Việt"] --> N["Chuẩn hoá VI<br/>số · ngày · viết tắt · IN HOA"]
N --> R["OmniVoice Runtime<br/>diffusion LM"]
R -->|"CUDA / MPS / CPU"| A["🔊 Audio 24 kHz"]
VC[("Voice Catalog<br/>10 giọng + clone")] --> R
subgraph Clients["Cách dùng"]
UI["🖥️ Studio Web UI"]
API["🌐 REST API"]
MCP["🤖 MCP cho Agent"]
end
UI --> N
API --> N
MCP --> API
```
## 🤖 Dùng trong AI Agent (MCP)
TQD-Voice phát hành một **MCP server** để agent gọi TTS như một công cụ (liệt kê giọng, chuẩn hoá text, ước lượng thời lượng, tổng hợp giọng, hàng đợi long-form). Copy [`.mcp.json.example`](.mcp.json.example) vào cấu hình MCP của agent (vd Antigravity) — chi tiết trong [`docs/mcp-agent-guide.md`](docs/mcp-agent-guide.md).
## 🔬 Điểm kỹ thuật đáng nghiên cứu
- **Diffusion language-model TTS** trên nền [OmniVoice](https://github.com/k2-fsa/OmniVoice) (600+ ngôn ngữ, RTF thấp tới ~0.025).
- **Chuẩn hoá tiếng Việt** riêng: đọc đúng số/ngày/%/đơn vị, mở rộng viết tắt (TTXVN → "thông tấn xã Việt Nam"), và xử lý tiêu đề **IN HOA** thay vì đánh vần từng chữ.
- **Long-form ổn định**: ghim thời lượng theo từng đoạn để tránh giọng nhòe/kéo dài — lời rõ, nhịp tự nhiên.
- **Di động phần cứng**: chọn thiết bị lúc nạp model (`omnivoice_vi/device.py`) — CUDA bất kỳ, Apple MPS, hoặc CPU.
- **Provenance-gated catalog**: mỗi giọng gắn giấy phép, nguồn và trạng thái đồng thuận (`docs/voice-source-ledger.md`).
## 🔐 Riêng tư & Đạo đức
- **Local & loopback-only** — dịch vụ từ chối bind ra địa chỉ công khai; dữ liệu ở lại máy bạn.
- **Đồng thuận là bắt buộc** — chỉ clone giọng bạn được phép. Các giọng dựng sẵn ở giấy phép **Apache-2.0 / CC-BY-NC-4.0**, **phi thương mại**, giữ nguyên ghi công.
- Không dùng cho mạo danh, lừa đảo, hay bất kỳ mục đích trái pháp luật/phi đạo đức nào.
## 🙏 Nền tảng & Ghi công
- Mô hình nền: **[OmniVoice](https://github.com/k2-fsa/OmniVoice)** (k2-fsa) · checkpoint **KhanhTTS-OmniVoice**.
- Giọng mẫu nghiên cứu: **[VieNeu-TTS](https://github.com/pnnbao97/VieNeu-TTS)** (Apache-2.0) và **[viet-tts](https://huggingface.co/dangvansam/viet-tts)** (CC-BY-NC-4.0).
## 📄 License
Mã nguồn theo **[Apache-2.0](LICENSE)**. Giọng mẫu theo giấy phép riêng của từng nguồn (xem `catalog.json` và `docs/voice-source-ledger.md`).
## 👤 Tác giả
**DungTQ** — 0976202028 · dungtq.sales@gmail.com
<div align="center"><sub>Nếu dự án hữu ích, hãy ⭐ để ủng hộ và giúp nhiều người tìm thấy nó.</sub></div>
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessNo issues