<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.

</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

git clone https://github.com/xaotiensinh-abm/tqd-voice.git
cd tqd-voice

Windows (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 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.

🎧 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 hoặc docs/voice-catalog.md.

🏗️ Kiến trúc

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 vào cấu hình MCP của agent (vd Antigravity) — chi tiết trong docs/mcp-agent-guide.md.

🔬 Điểm kỹ thuật đáng nghiên cứu

• Diffusion language-model TTS trên nền 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 (k2-fsa) · checkpoint KhanhTTS-OmniVoice.
• Giọng mẫu nghiên cứu: VieNeu-TTS (Apache-2.0) và viet-tts (CC-BY-NC-4.0).

📄 License

Mã nguồn theo Apache-2.0. 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">_{Nếu dự án hữu ích, hãy ⭐ để ủng hộ và giúp nhiều người tìm thấy nó.}</div>