Vietnamese TTS Studio 🎙️

Free, fully-offline Vietnamese text-to-speech (TTS) and voice cloning with a clean local web UI + CLI. Type Vietnamese text and get a .wav, or give a 3-10s sample to clone any voice - everything runs locally on your own NVIDIA GPU (works on just 4GB VRAM). No internet, no API keys, no cloud, no data ever leaving your machine. Built on the OmniVoice / KhanhTTS models.

Keywords: vietnamese text-to-speech, vietnamese tts, voice cloning, offline tts, local tts, self-hosted, privacy, no API key, OmniVoice, KhanhTTS, FastAPI, audiobook, voice-over.

---

TTS tiếng Việt + nhân bản giọng nói (voice cloning), chạy offline 100% trên GPU local. Nhập văn bản tiếng Việt -> file .wav; hoặc đưa giọng mẫu 3-10 giây -> clone giọng đó. Có giao diện web (khuyên dùng) và CLI.

Đây là công cụ/giao diện sử dụng (consumer app), KHÔNG phải model. Toàn bộ chất lượng giọng nói là công sức của các tác giả model/engine gốc - xem mục Ghi nhận.

✨ Tính năng / Features

• Offline & riêng tư 100% - không internet, không API key, không gửi dữ liệu đi đâu; audio không rời máy bạn.
• Tiếng Việt là trọng tâm - dùng model KhanhTTS (fine-tune OmniVoice trên ~1.500h Việt + Anh, 24kHz).
• Nhân bản giọng (voice cloning) - clone giọng bất kỳ từ mẫu 3-10 giây (tải lên hoặc thu mic ngay trên web).
• Đọc văn bản dài - tự cắt câu, sinh từng đoạn rồi ghép thành một file liền mạch, một giọng duy nhất; chạy được cả trên 4GB VRAM.
• Tốc độ đọc chỉnh được - thanh kéo 0.5x - 2.0x (chậm rãi cho thơ/tình cảm, nhanh gọn cho tin tức).
• Giao diện web sạch (FastAPI) - sáng/tối, side-nav hướng dẫn, lịch sử nghe lại ngay tại dòng, quản lý giọng mẫu (lưu/xóa). Kèm CLI để tự động hóa.

🎯 Dùng để làm gì / Use cases

• Đọc sách nói / audiobook tiếng Việt.
• Lồng tiếng video, YouTube, TikTok, e-learning.
• Đọc thông báo, kịch bản, bản tin tự động.
• Clone giọng cho nhân vật / thương hiệu, hoặc giữ giọng nhất quán cho cả series.
• Bất cứ ai cần TTS tiếng Việt mà không muốn phụ thuộc dịch vụ cloud trả phí / lộ dữ liệu.

Yêu cầu

• Python 3.12 (PyTorch chưa hỗ trợ 3.13/3.14).
• GPU NVIDIA có CUDA (khuyên >= 4GB VRAM). Không có GPU vẫn chạy được bằng CPU (chậm hơn).
• uv để quản lý môi trường Python.

Cài đặt

git clone https://github.com/vuhai2002/vietnamese-tts-studio.git
cd vietnamese-tts-studio

uv venv --python 3.12
# Windows (cache uv ở ổ khác venv): set UV_LINK_MODE=copy
uv pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu128   # đổi cu128 theo CUDA của bạn
uv pip install omnivoice soundfile fastapi "uvicorn[standard]" python-multipart

Lần chạy đầu sẽ tự tải model (~3GB) từ HuggingFace vào thư mục .cache/ ngay trong dự án (không vương ra ngoài, muốn xóa chỉ cần xóa .cache/).

Giao diện web (khuyên dùng)

uv run python web_server.py          # hoặc double-click start-ui.bat (Windows)

Trình duyệt tự mở tại http://127.0.0.1:7860 - chỉ máy này truy cập được, không mở ra mạng. Lần bấm Đọc đầu tiên chờ 30-60 giây tải model; các lần sau gần như tức thì (model giữ trong VRAM).

Giao diện chia 2 phần: side nav hướng dẫn bên trái + màn hình chính bên phải.

Tab "Tạo giọng nói":

• Dán văn bản bất kỳ - một câu hay cả bài đều được. Bài dài tự cắt câu, đọc lần lượt (có thanh tiến độ "đang đọc đoạn 3/12...") rồi ghép thành một file liền mạch.
• Muốn clone giọng: mở khối Giọng mẫu - chọn file có sẵn trong refs/, tải file lên, hoặc thu âm bằng micro. Nên gõ Lời mẫu (đúng câu trong file mẫu) để đỡ tốn VRAM. Bấm Lưu vào refs/ để giữ giọng dùng lần sau, hoặc nút thùng rác để xóa giọng mẫu.
• Tùy chọn nâng cao: thanh kéo tốc độ đọc (0.5x-2.0x), số bước (8-32), hoặc bật Dùng CPU.
• Hết VRAM giữa chừng? Phần đã đọc xong vẫn được lưu (..._partial.wav); bật Dùng CPU hoặc giảm số bước rồi đọc lại.
• Nút Giải phóng VRAM: trả VRAM cho việc khác mà không cần tắt app.

Tab "Lịch sử": xem lại các file đã sinh, bấm play để nghe ngay tại dòng, hoặc xóa.

Dùng CLI

# TTS cơ bản
uv run python run.py --text "Xin chào các bạn, hôm nay trời đẹp quá." --out outputs/test.wav

# Clone giọng từ file mẫu (nên gõ --ref-text đúng lời trong mẫu để đỡ tốn VRAM)
uv run python run.py --text "Câu đọc bằng giọng mẫu." --ref refs/mau.wav \
  --ref-text "lời thoại có trong mau.wav" --out outputs/clone.wav

# Đọc chậm rãi + ép CPU khi hết VRAM
uv run python run.py --text "..." --speed 0.8 --cpu

Tham số run.py: --text --out --ref --ref-text --steps(16) --speed(1.0) --cpu.

Cấu trúc

vietnamese-tts-studio/
├── web_server.py         # Backend FastAPI - phục vụ web + API (giao diện chính)
├── web/                  # Frontend tĩnh (HTML/CSS/JS) + font Be Vietnam Pro
├── run.py                # CLI (terminal)
├── tts_engine.py         # Lõi model dùng chung (load/unload/generate, đặt HF_HOME)
├── text_splitter.py      # Cắt văn bản dài thành câu (tiếng Việt)
├── long_text.py          # Pipeline đọc văn bản dài (ghép đoạn, giữ 1 giọng)
├── history.py            # Đặt tên file output + metadata + lịch sử
├── app.py app_theme.py app_history_tab.py   # Bản giao diện Gradio cũ (tùy chọn)
├── tests/                # Unit test (không cần GPU) + smoke test e2e
├── docs/                 # ADR + changelog
├── refs/                 # (tự tạo) bỏ giọng mẫu vào đây - KHÔNG commit
├── outputs/              # (tự tạo) file .wav sinh ra - KHÔNG commit
└── .cache/  .venv/       # model weights + môi trường - KHÔNG commit

Ghi nhận (Credits)

Dự án này chỉ là lớp giao diện/công cụ. Mọi công sức tạo ra giọng nói thuộc về:

• Model giọng tiếng Việt: kjanh/KhanhTTS-OmniVoice
  • tác giả kjanh (fine-tune ~1.500h tiếng Việt + Anh, output 24kHz, backbone Qwen3-0.6B). License: Apache-2.0.
• Engine / model gốc: k2-fsa/OmniVoice (HuggingFace) - k2-fsa / Xiaomi Corp (tác giả Han Zhu). License: Apache-2.0.
• Font: Be Vietnam Pro (SIL Open Font License).

License

• Code của repo này: MIT (xem file LICENSE) - ai dùng cũng được.
• Model + dữ liệu: theo license của tác giả gốc ở trên (Apache-2.0 cho model/engine).
• Lưu ý thương mại: model card KhanhTTS ghi Apache-2.0 nhưng chưa nói rõ license của dataset train. Nếu dùng giọng sinh ra cho mục đích thương mại, hãy tự xác minh / liên hệ tác giả model trước.