ViFastTts — Text-to-Speech tiếng Việt

Tải và dùng trên Windows (không cần build)

Cách nhanh nhất: tải ZIP → giải nén → chạy vifasttts-desktop.exe.

1. Vào Releases v0.3.4 và tải vifasttts-desktop-windows-x64.zip (~92 MB).
2. Chuột phải file ZIP → Extract All (đừng chạy trực tiếp trong file ZIP).
3. Mở thư mục vừa giải nén → chạy vifasttts-desktop.exe.
4. Nếu SmartScreen cảnh báo: More info → Run anyway (bản chưa ký số).
5. Gõ tiếng Việt → bấm Đọc. Model, vocoder, ONNX Runtime và web đã nằm trong gói.

Không cần Python, Node, GPU, tài khoản HuggingFace hay mạng. Cần Windows 10/11 x64; nếu máy thiếu DLL hệ thống, cài VC++ 2015–2022 x64.

Chọn file theo nhu cầu

Tất cả nằm trong release v0.3.4. Hướng dẫn chi tiết + xử lý lỗi: docs/INSTALL.md.

Lưu ý bản build: các thay đổi UI 29/10 (alpha/peak/max, HuggingFace trực tiếp, từ điển mobile, karaoke/SRT/VTT, cách đọc iOS = ai âu ét, Android = an đờ roi), iOS stream local/remote, huỷ tải model Android, catalog/WAV dùng chung và release v0.3.4; tải APK Android 0.3.4 hoặc build từ source; xem docs/UI_PARITY.md và mobile/android/README.md.

Cài Chrome extension (Windows/macOS/Linux)

Extension dùng model bundled nên không cần Python/server để đọc local.

1. Tải vifasttts-extension.zip (~80 MB) từ release v0.3.4.
2. Chuột phải ZIP → Extract All để có một thư mục chứa manifest.json.
3. Chrome: mở chrome://extensions → bật Developer mode → Load unpacked → chọn thư mục vừa giải nén.
4. Edge: mở edge://extensions → bật Developer mode → Load unpacked → chọn cùng thư mục.
5. Ghim icon ViFastTts lên thanh công cụ → bấm icon → nhập text → Đọc.

Lưu ý:

• Hiện extension chưa có trên Chrome Web Store/Edge Add-ons, nên phải Load unpacked; khi store duyệt xong sẽ có link cài trực tiếp.
• Chỉ tải ZIP từ GitHub Release chính thức; đừng tải từ nguồn lạ.
• Local mode đọc bằng model bundled. Tìm/tải model HuggingFace có thể dùng HuggingFace trực tiếp hoặc server /api/models/* (tùy chọn).
• Hướng dẫn nộp store/kiểm tra quyền: docs/EXTENSION_STORE.md.

Tìm model từ HuggingFace: bản nào cần server?

• Desktop dùng vifasttts-model-manager + HuggingFace adapter trực tiếp. Nút Bật server trong desktop chỉ để phục vụ web/extension/điện thoại; nó không cần thiết cho việc tìm model của chính desktop.
• Extension có checkbox HuggingFace trực tiếp trong mục thêm giọng; không cần server. Nếu dùng server, extension gọi /api/models/* để server kiểm hash/catalog tập trung. Model bundled vẫn đọc được khi offline.
• Android/iOS ưu tiên tải trực tiếp HuggingFace khi Server URL để trống (native không bị CORS). Nếu muốn dùng server để kiểm hash/catalog tập trung, nhập http://192.168.1.100:8000 (cùng Wi-Fi/LAN), bật Cho phép LAN trên desktop và mở firewall. Điện thoại không dùng được 127.0.0.1 của máy tính.
• Web khi được server phục vụ dùng API server; bản web tĩnh có thể dùng HuggingFace trực tiếp hoặc nạp bundle thủ công.
• Model browser chỉ hiện file .vfa/.vfts; raw acoustic.onnx là file nội bộ/dev.

Dành cho developer

Phần còn lại của README dành cho build/train/kiến trúc. Nếu chỉ muốn dùng app, bạn có thể dừng ở mục Windows phía trên.

TTS tiếng Việt mã nguồn mở: nhỏ, nhanh, tự train được. Toolkit nghiên cứu + triển khai TTS một giọng, hiểu văn bản tiếng Việt, sinh giọng 24 kHz và xuất ONNX chạy CPU. Mỗi checkpoint là một người nói, một phương ngữ — không cần speaker_id, dialect_id hay audio mẫu.

0. Chạy demo bằng Python (tuỳ chọn, cho developer)

git clone https://github.com/dvchd/ViFastTts.git
cd ViFastTts
./scripts/run_ngochuyen_demo.sh
# Windows PowerShell:
# powershell -ExecutionPolicy Bypass -File .\scripts\run_ngochuyen_demo.ps1
# mở http://127.0.0.1:8090

Script tự tải ONNX FP32 Q-init từ HuggingFace (có kiểm sha256), tạo .venv-demo, cài onnxruntime + fastapi + uvicorn và chạy web demo — không cần torch. Cần Python ≥ 3.11. Người dùng Windows bình thường nên dùng bản desktop ở trên; mục này chỉ dành cho dev/CLI.

• Demo online: https://vifasttts.hoctuthien.com/
• Hugging Face model: https://huggingface.co/dvchd/vifasttts-ngochuyen-small
• Space demo miễn phí: https://huggingface.co/spaces/dvchd/vifasttts-ngochuyen-demo
• Thống kê demo: https://vifasttts.hoctuthien.com/admin
• Góp ý / báo lỗi: form trên web và Space; admin xem tại /admin sau khi đặt ADMIN_PASSWORD (nội dung bị khoá nếu chưa đặt).
• Model/card: docs/NGOC_HUYEN.md
• Model bundles: .vfa/.vfts · base 60k sau Q · 3 mẫu nghe
• App release: v0.3.4

Chọn đúng luồng

A. Người dùng model (không train, không cần torch): chạy script ở trên, mở web, hoặc gọi synthesize-onnx; dùng checkpoint/ONNX có sẵn. Không cần MFA, không cần dữ liệu.

B. Người train model: cài .[dev,audio,train,onnx], chuẩn bị audio + transcript, chạy MFA, cache, train, eval, export. Bắt đầu ở docs/TRAINING_N0.md (N0) hoặc docs/TRAINING.md (tổng quát).

Giấy phép model mẫu: dataset pnnbao-ump/ngochuyen_voice là CC BY-NC 4.0. Model Ngọc Huyền chỉ dùng nghiên cứu/phi thương mại; không dùng giả giọng, lừa đảo hoặc production thương mại. Code repo là MIT.

Đọc nhanh: muốn hiểu kiến trúc → mục 2–3; muốn train lại → docs/TRAINING_N0.md; muốn triển khai → docs/handoff/N0_DEPLOY.md.

1. Dự án làm gì?

Ba khối chính, ghép lại thành một câu TTS hoàn chỉnh:

Văn bản  ──▶  FRONTEND (tiếng Việt)  ──▶  MODEL (mel + thời lượng)  ──▶  VOCODER  ──▶  WAV

Khác biệt cốt lõi: thay vì đưa chuỗi ký tự hay BPE vào model, dự án mô tả mỗi âm tiết bằng 5 thành phần ngôn ngữ học âm đầu + âm đệm + âm chính + âm cuối + thanh điệu (cộng dấu câu/chấm câu — xem mục 7). Nhờ vậy: phát âm ổn định, dấu thanh không bao giờ sai vị trí, và không có "từ lạ" với tiếng Việt chuẩn.

2. Trạng thái hiện tại (số liệu thật)

Model mẫu có sẵn: Ngọc Huyền small 6,1M (research/non-commercial) trong GitHub release; repo không chứa file .pt/.onnx để giữ clone nhẹ — script quickstart tự tải ONNX. Muốn train giọng khác, xem docs/TRAINING.md + docs/TRAINING_N0.md.

Model Ngọc Huyền — số đo chính

Chi tiết + license: docs/NGOC_HUYEN.md.

Vocab Q: từ commit 60b5cf9, onset Q đứng cuối vocab (ID cũ không đổi) cho chữ qu. Checkpoint/ONNX mới mang vocab_version + vocab_hash; artifact cũ không còn được hỗ trợ, không dùng adapter Q→K. Bản đang live là Q-init (Q = K, bit-exact N0 Bắc cũ); fine-tune Q 3k đã train/export nhưng chưa chọn; release nghe thử cũ đã xoá (29/10/2026), artifact base/bundle nằm trên HuggingFace. Xem docs/Q_ONSET.md, CHANGELOG.md, docs/SYLLABLE_GUIDE.md.

3. Luồng hoạt động trong 30 giây

1) CHUẨN BỊ:   WAV + CSV  →  manifest.jsonl  (+ cache feature, kiểm coverage)
2) TRAIN:      manifest   →  acoustic model (dự đoán mel/duration/f0)  → best.pt
                           vocoder riêng (mel → sóng)                 → vocoder.pt
3) SUY LUẬN:   text  →  7 ID/âm tiết  →  mel dự đoán  →  vocoder  →  out.wav
4) XUẤT:       best.pt  →  model.onnx  (chạy bằng ONNX Runtime, fp32/fp16/int8)

Điểm cần nhớ để hiểu code:

• Train dùng thời lượng thật (teacher forcing); suy luận tự dự đoán thời lượng.
• Không sampling — cùng đầu vào cho cùng đầu ra.
• Token không phải tiếng Việt vẫn chạy được (fallback), không bao giờ crash.

Chi tiết đầy đủ (tensor shape, công thức loss, số tham số): docs/MODEL_FLOW.md.

4. Cài đặt

Yêu cầu Python ≥ 3.11.

Chỉ muốn tạo âm thanh ngay (ONNX, không torch):

git clone https://github.com/dvchd/ViFastTts.git
cd ViFastTts
./scripts/run_ngochuyen_demo.sh
# Windows:
# powershell -ExecutionPolicy Bypass -File .\scripts\run_ngochuyen_demo.ps1
# http://127.0.0.1:8090

Phát triển / train / xuất ONNX:

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev,audio,train,onnx]"

Bản tối thiểu (frontend/CLI, không cần torch): pip install -e ..

5. Thử nhanh

# Demo web Ngọc Huyền (tải ONNX lần đầu, chạy local)
./scripts/run_ngochuyen_demo.sh
# Windows PowerShell:
# powershell -ExecutionPolicy Bypass -File .\scripts\run_ngochuyen_demo.ps1
# hoặc macOS/Linux: make demo-ngochuyen

# Xem một câu được tách thành âm tiết và 5 thành phần thế nào
vifasttts parse "Hôm nay trời đẹp."
vifasttts parse-syllable "quốc"
vifasttts check-profile "voan bình" --profile strict   # cảnh báo chính tả/từ vay
vifasttts g2p "quốc" --dialect south                   # phiên âm IPA (phân tích)

# So sánh phiên âm IPA Bắc/Nam (chỉ để phân tích)
python examples/g2p_demo.py

# Lấy dữ liệu từ kênh YouTube của bạn (demo 1 video ngắn, cần: pip install -e ".[youtube]")
vifasttts youtube-fetch "https://www.youtube.com/@codelung/videos" --out data/codelung --demo

# Phiên bản CLI
vifasttts --version

Kiểm chứng toàn bộ pipeline bằng test (tự tạo dữ liệu tí hon, train 2 bước, sinh WAV, xuất ONNX):

pytest

6. Các lệnh chính

# Dữ liệu: metadata.csv có dạng  id|text
vifasttts build-manifest --metadata data/metadata.csv --wav-dir data/wavs --output data/manifest.jsonl
vifasttts validate-manifest --manifest data/manifest.jsonl --wav-dir data/wavs

# Huấn luyện
vifasttts train --config configs/base_24k.yaml \
  --train-manifest data/train.jsonl --val-manifest data/val.jsonl --output runs/base
vifasttts train-vocoder --config configs/base_24k.yaml \
  --manifest data/train.jsonl --output runs/vocoder

# Sinh giọng + xuất ONNX
vifasttts synthesize --config configs/base_24k.yaml \
  --checkpoint runs/base/best.pt --vocoder-checkpoint runs/vocoder/last.pt \
  --text "Xin chào, đây là hệ thống thử nghiệm." --output out.wav
vifasttts export-onnx --config configs/base_24k.yaml \
  --checkpoint runs/base/best.pt --output artifacts/model.onnx --precision fp16
vifasttts export-vocoder-onnx --config configs/base_24k.yaml \
  --checkpoint runs/vocoder/last.pt --output artifacts/vocoder.onnx

# Chạy lại chỉ với ONNX Runtime (không cần PyTorch)
vifasttts synthesize-onnx --acoustic artifacts/model.onnx --vocoder artifacts/vocoder.onnx \
  --text "Xin chào" --output onnx.wav --peak-normalize

# Batch và dịch vụ HTTP
vifasttts synthesize-batch --config configs/base_24k.yaml --checkpoint runs/base/best.pt \
  --input data/cau.txt --output-dir data/wavs_out
vifasttts serve --config configs/base_24k.yaml --checkpoint runs/base/best.pt --port 8000
# → curl -X POST localhost:8000/synthesize -d '{"text":"Xin chào"}' -o out.wav
#   (kèm GET /health, GET /info)

Trên Mac Apple Silicon: training.device: auto (mặc định) chạy acoustic bằng MPS, vocoder bằng CPU (đo thực tế nhanh hơn trên máy nhỏ); số đo và ước lượng thời gian cho Mac mini M6 32GB nằm ở docs/TRAINING_ESTIMATES.md §3.1.

7. Âm tiết tiếng Việt trong dự án (dễ hiểu)

Mỗi âm tiết (một "tiếng") gồm 5 phần + dấu câu. Ví dụ quốc:

quốc = Q + NONE + UÔ + C + SAC: chữ u thuộc nguyên âm đôi uô, không phải âm đệm W; giọng Bắc đọc quốc giống cuốc (cuốc = K + NONE + UÔ + C + SAC), nhưng Q/K là hai token riêng. So sánh quất = Q + W + Â + T + SAC.

Cộng thêm chấm câu và ranh giới từ/câu → mỗi âm tiết là 7 con số đưa vào model. Giải thích từ đầu cho người không chuyên: docs/SYLLABLE_GUIDE.md.

8. Cấu trúc repo

src/vifasttts/
  frontend/   chuẩn hoá text, tách âm tiết, vocab, G2P (phân tích), lexicon/profile, segments, chunking
  data/       manifest, features (mel/f0/vuv/energy/phonation), dataset, cache, subtitles + youtube (tải kênh của bạn)
  models/     acoustic model, conformer, iSTFTNet vocoder, discriminator
  runtime/    chạy ONNX (acoustic + vocoder), iSTFT numpy, postprocess
  train.py    vòng huấn luyện acoustic + vocoder
  infer.py    text → WAV (PyTorch)
  export.py   ONNX (acoustic + vocoder) + quantization
configs/      base_24k.yaml + small_24k.yaml + large_24k.yaml + small_ngochuyen.yaml + ...
tools/        parser_audit, compute_mel_stats, train_chunked, n0_social_card, ...
resources/    brand/ (logo, favicon, OG image, manifest; xem resources/brand/README.md)
deploy/       vifasttts_demo/ (FastAPI ONNX + Dockerfile + static page)
scripts/      fetch_ngochuyen_models.sh · run_ngochuyen_demo.sh · run_A2_fixgap.sh
tests/        2.916 test: parser, normalizer, G2P, model, train/infer/export, ONNX, server
docs/         toàn bộ tài liệu (xem mục 10 + docs/README.md); N0 deploy ở docs/handoff/N0_DEPLOY.md

9. Giới hạn hiện tại & việc còn lại

• Alignment: pipeline N0 dùng MFA thật (6.989/6.989 TextGrid). Với dữ liệu mới, nên chạy MFA/aligner; nếu chưa có, code dùng chia theo trọng số (placeholder), chất lượng thấp hơn.
• Vocoder: bản tham chiếu (GAN nhẹ MPD-lite) + bản nâng cấp MPD đầy đủ 2/3/5/7/11 + MRD + MR-STFT (discriminator: mpd_mrd, chạy khối MPS) — xem docs/archive/plans/REVISION_PLAN_V2.md §10; GTA fine-tune sẽ làm sau.
• ONNX: đã export N0 FP32 (acoustic + Vocos) và runtime CPU; demo dùng ONNX. Chưa gộp vocoder vào một graph duy nhất/INT8 calibration đầy đủ.
• OOV: từ ngoài tiếng Việt đọc bằng fallback — muốn kiểm soát thì bật resolve_oov=True, dùng --overrides file.json hoặc thêm override.
• Một checkpoint = một giọng, một phương ngữ (đúng thiết kế; không có speaker_id/dialect_id nên không đổi giọng lúc chạy). Bộ mã hoá 5 ô dùng chung cho mọi vùng, nên có 15–20 h dữ liệu sạch của một giọng/vùng là train được checkpoint riêng mà không sửa kiến trúc (xem docs/TRAINING_N0.md, docs/SYLLABLE_GUIDE.md). Muốn một model phục vụ nhiều vùng thì phải thêm conditioning vùng/người nói — chưa làm.

Roadmap chi tiết có đánh dấu ✅/⬜: docs/handoff/TRANG_THAI.md.

10. Tài liệu — nên đọc gì trước?

Mục lục đầy đủ + phân loại hiện hành / tham chiếu / lịch sử: docs/README.md.

11. Giấy phép

Code repo: MIT. Dữ liệu giọng nói, lexicon, checkpoint và model mẫu có giấy phép riêng; các công cụ tham chiếu (sea-g2p, MFA, vPhon...) giữ giấy phép gốc — xem docs/LICENSES.md.

Model Ngọc Huyền: dataset pnnbao-ump/ngochuyen_voice là CC BY-NC 4.0; checkpoint/ ONNX/weights chỉ dùng nghiên cứu, phi thương mại, không dùng giả giọng hoặc production thương mại. Dataset lấy từ kênh YouTube của bạn mặc định ghi CC BY 4.0 (ghi nguồn kênh), đổi bằng --license, ví dụ --license "CC0 1.0".