Skip to main content
Glama

archi-tts

TTS tiếng Việt (giọng Bắc) chạy hoàn toàn trên máy, dùng để lồng tiếng video, gọi qua MCP.

  • Giọng có sẵn: VieNeu-TTS v3 Turbo, 15 giọng Bắc. Nhanh (~4 phút cho 15 phút audio trên M1 Pro), nhưng không đổi được cảm xúc và đôi khi sai thanh điệu.

  • Giọng clone (chỉ bản full): OmniVoice (bản fine-tune tiếng Việt danhcao/v-omnivoice). Mỗi cảm xúc một clip tham chiếu 3–10s. Chậm hơn (~40 phút cho 15 phút audio) nhưng ít lỗi thanh điệu nhất trong benchmark.

  • Xuất WAV 48 kHz (−16 LUFS), MP3 và SRT vào ~/archi-tts-output/<tên>/.

Kết quả so sánh 4 engine nằm trong bench/ (mở bench/results/index.html qua python3 -m http.server --directory bench).

Cài đặt (Claude Code)

Nói với Claude Code:

Cài plugin archi-tts từ https://github.com/archi-ai-labs/archi-tts

Hoặc gõ tay:

/plugin marketplace add archi-ai-labs/agent-marketplace
/plugin install archi-tts@archi-ai-labs
/plugin enable archi-tts@archi-ai-labs

Hoặc dùng installer của marketplace (đăng ký catalog và bật plugin ở mức user):

curl -fsSL https://archi-ai-labs.github.io/agent-marketplace/install.sh | bash -s -- --plugins archi-tts

Rồi mở phiên mới. Phiên đầu tiên tự cài bản lite ở nền (thư viện Homebrew, môi trường Python, model VieNeu; vài phút, xem ~/.archi-tts/setup.log). Xong thì các tool archi-tts dùng được; nếu chưa thấy, gõ /mcp và kết nối lại archi-tts. Skill /archi-tts:setup để kiểm tra, sửa lỗi, đăng ký Claude Desktop hoặc gỡ cài đặt.

Plugin cài ở trạng thái tắt (defaultEnabled: false), vì nó có hook SessionStart (cài đặt nền) và một MCP server. Bật bằng /plugin enable archi-tts@archi-ai-labs (hoặc claude plugin enable archi-tts@archi-ai-labs). Máy đã cài và bật từ trước không bị ảnh hưởng: giá trị đã ghi trong enabledPlugins luôn được ưu tiên hơn mặc định. Cần Claude Code ≥ v2.1.154; bản cũ hơn bỏ qua trường này và bật plugin ngay khi cài.

Chi phí context luôn bật (đo, không ước đoán): skill setup đóng (disable-model-invocation: true), nên phần mô tả skill nạp sẵn là 0 token (lệnh đo ở mục 6.2 của chuẩn plugin archi-ai-labs). Khi plugin được bật, MCP server thêm 8 tool: định nghĩa tool dài 6.2k ký tự (~1.5k token) cộng 336 ký tự hướng dẫn server.

Dành cho Claude khi được yêu cầu cài plugin này: chạy claude plugin marketplace add archi-ai-labs/agent-marketplace (bỏ qua nếu claude plugin marketplace list đã có archi-ai-labs), rồi claude plugin install archi-tts@archi-ai-labs và claude plugin enable archi-tts@archi-ai-labs. Sau đó chạy bash "$(ls -d ~/.claude/plugins/cache/archi-ai-labs/archi-tts/*/ | tail -1)bin/archi-tts-bootstrap" ở nền để cài ngay mà không phải chờ phiên mới, báo người dùng mở phiên mới hoặc /mcp khi log báo "sẵn sàng". Cần Homebrew; nếu máy chưa có, đưa lệnh cài từ https://brew.sh cho người dùng tự chạy.

Bản lite và bản full

Mặc định cài lite: 15 giọng VieNeu có sẵn, không có giọng clone. Cần giọng clone (cảm xúc theo clip, add_voice) thì nâng lên full. Số đo trên M1 Pro:

Lite (mặc định)

Full

Giọng

15 giọng VieNeu

+ giọng clone OmniVoice, cảm xúc theo clip

Model

0.6 GB

3.9 GB

Môi trường Python

0.64 GB (không có torch)

1.3 GB

Tổng ổ đĩa

~1.3 GB

~5.3 GB

RAM

~1.4 GB

~5 GB lúc nghỉ, ~7.6 GB đỉnh

Lúc cài, cache tải của uv chiếm thêm (2.2 GB với bản full); xoá bằng uv cache clean nếu cần chỗ.

Nâng lên full (hoặc nói với Claude "cài bản full của archi-tts"; skill /archi-tts:setup có lệnh này):

bash "$(ls -d ~/.claude/plugins/cache/archi-ai-labs/archi-tts/*/ | tail -1)bin/archi-tts-bootstrap" --full

Hạ về lite thì dùng --lite: thư viện OmniVoice bị gỡ khỏi môi trường Python, còn model 3.3 GB vẫn nằm trong ~/.cache/huggingface (lệnh xoá được in ra cuối log). Đổi bản xong, kết nối lại server bằng /mcp. Máy đã cài trước khi có hai bản (có sẵn OmniVoice) được giữ là full.

Ở bản lite, list_voices trả "edition": "lite"; gọi giọng clone hay add_voice sẽ báo lỗi kèm lệnh nâng cấp.

Yêu cầu: Mac Apple Silicon, Homebrew; RAM và ổ trống theo bảng trên (full nên có ≥16 GB RAM).

Dữ liệu nằm ở đâu

Thư mục

Nội dung

~/.archi-tts/venv/

Môi trường Python (tự dựng lại khi plugin cập nhật)

~/.archi-tts/edition

lite hoặc full

~/.archi-tts/home/

voices/ + lexicon.yaml của bạn: copy từ bản mặc định ở lần đầu, sau đó plugin không ghi đè

~/.archi-tts/setup.log

Log cài đặt

~/.cache/huggingface/

Model

~/archi-tts-output/

File xuất ra

Related MCP server: FreeTTS

Cài từ repo (Claude Desktop, server HTTP chung)

git clone https://github.com/archi-ai-labs/archi-tts && cd archi-tts
./install.sh            # hỏi lite/full, cài, chạy thử, rồi hỏi đăng ký Claude Code / Claude Desktop / server HTTP chung
./install.sh --full     # cài (hoặc nâng lên) bản full; --lite để hạ về lite
./install.sh --uninstall

Claude Desktop không dùng được plugin của Claude Code, nên đăng ký bằng install.sh (hoặc skill /archi-tts:setup). Cả plugin, install.sh và Claude Desktop đều chạy server qua bin/archi-tts-mcp, dùng chung ~/.archi-tts.

Mỗi client stdio tự khởi động một server riêng, mỗi server giữ ~5 GB RAM sau khi nạp model. Nếu dùng cùng lúc nhiều client (Claude Code + Claude Desktop), nên chạy một server HTTP (./install.sh --http, chạy nền bằng LaunchAgent) rồi trỏ client vào http://127.0.0.1:8766/mcp. Server tự chạy offline khi model đã có trong cache; đặt HF_HUB_OFFLINE=0 nếu cần tải thêm. Đường dẫn ffmpeg/rubberband được tự tìm ở /opt/homebrew/bin, nên client khởi động từ giao diện (không có PATH của Homebrew) vẫn chạy được.

Web thử giọng

Mở http://127.0.0.1:8770. Không cần chạy server riêng: chính server MCP archi-tts (do Claude Code/Claude Desktop tự bật, hoặc archi-tts --http) phục vụ luôn trang này, dùng chung model và hàng đợi với các tool MCP. Đổi cổng bằng --web-port hoặc ARCHI_TTS_WEB_PORT, 0 để tắt. Nếu có nhiều server MCP cùng chạy, chỉ server đầu tiên mở web, các server sau bỏ qua.

Một trang, đi từ trên xuống:

  1. Nhập câu (bấm "Máy sẽ đọc thành gì?" để xem số, ngày, viết tắt được đọc thế nào).

  2. Chọn giọng: đổi giọng là tự phát file mẫu có sẵn (bấm 🔈 để nghe lại), không cần tạo. Mẫu VieNeu nằm ở voices/samples/, tạo lại bằng uv run python scripts/make_samples.py --force; giọng clone phát clip tham chiếu của cảm xúc đang chọn.

  3. Chọn cảm xúc, tốc độ, giọng trầm/cao, âm lượng bằng nút bấm; "Chỉnh chi tiết" có thanh trượt.

  4. Bấm Đọc thử. Mỗi bản nghe thử có nút "+ Thêm vào kịch bản" để ghép nhiều giọng.

  5. Phần Prompt cho Claude tự cập nhật theo lựa chọn (một giọng → speak, kịch bản → synthesize_script), bấm Copy rồi dán vào Claude. Tag sinh ra được kiểm tra parse ngược trong tests/test_web_prompt.py.

Tools

Tool

Việc

list_voices

Danh sách giọng, engine, cảm xúc có clip

speak

Một đoạn ngắn (≤800 ký tự), một giọng → file

synthesize_script

Kịch bản nhiều giọng → job chạy nền, trả job_id

job_status

Tiến độ, ETA, đường dẫn file khi xong

preview_voice

Nghe thử một giọng

check_text

Xem mỗi engine sẽ đọc văn bản thành gì (số, ngày, viết tắt, từ điển)

add_lexicon_entry

Dạy cách đọc một từ, chung hoặc riêng từng engine (ghi vào lexicon.yaml)

add_voice

Thêm giọng clone / clip cảm xúc từ file audio

Kịch bản

[ngoc_huyen] Hôm nay, ngày 15/8/2025, chúng ta tìm hiểu về chip AI.
[mai_anh | speed=1.1] Nó nhanh *gấp đôi* thế hệ trước! [ngắt 0.6s]
[lan | buon] Tiếc là giá lên tới 25 triệu đồng.

[pham_tuyen | pitch=-1 | volume=+2] Vậy có nên mua không?
  • [giọng | cảm_xúc | speed= | pitch= | volume=] ở đầu dòng; dòng không có tag giữ cài đặt dòng trước.

  • Cảm xúc: trung_tinh, vui, buon, tuc_gian. Chỉ áp dụng cho giọng clone (lan ở ví dụ trên là giọng bạn tự thêm, xem dưới).

  • [ngắt 0.8s] khoảng lặng, *từ* nhấn, [cười] [thở dài] âm phi ngôn ngữ (thử nghiệm). Dòng trống = ngắt đoạn.

Thêm giọng clone

Cần bản full. Repo chỉ kèm 15 giọng VieNeu, không kèm giọng clone nào. Thêm giọng của bạn bằng tool add_voice (hoặc nói với Claude "thêm giọng lan từ file ~/clip.wav"): mỗi cảm xúc một clip 3–10 s, giọng sạch, một người nói, kèm lời thoại đúng từng chữ (thiếu lời thoại thì Whisper tự nghe, tải thêm ~1.6 GB). Giọng được ghi vào ~/.archi-tts/home/voices/. Chỉ clone giọng bạn có quyền sử dụng.

Mỗi câu được cache, nên sửa một dòng rồi xuất lại thì chỉ sinh lại dòng đó. Đổi speed/pitch/volume không cần sinh lại (xử lý hậu kỳ).

Các điều khiển hoạt động thế nào (đã đo)

Đo bằng scripts/control_check.py trên cùng một câu, cả hai engine:

Điều khiển

Cách làm

Kết quả đo

Tốc độ

Rubber Band co giãn thời gian, giữ cao độ (cả hai engine; tham số speed của OmniVoice không tỉ lệ nên không dùng)

speed=0.8 → dài ×1.25, 1.25 → ×0.80, cao độ giữ nguyên

Cao độ

Rubber Band, ±6 nửa cung (±2–3 còn tự nhiên)

pitch=±3 → ±2.9–3.3 nửa cung, độ dài giữ nguyên

Âm lượng

Cân mức từng câu về cùng một mức, cộng gain volume, rồi một gain tĩnh cho cả file + limiter chặn đỉnh

-6 → −6.0 dB; +6 → +5.1–5.7 dB (limiter chặn đỉnh)

Cân giọng

Mọi câu được đưa về cùng mức trước khi trộn

VieNeu và OmniVoice lệch 4 dB → lệch 0.1 dB

Loudness file

Gain tĩnh tới −16 LUFS, đỉnh ≤ −1.4 dBFS

−15.8 đến −16.8 LUFS

Ngắt nghỉ

Chèn khoảng lặng chính xác

đúng như ghi

Nhấn từ

Thêm dấu phẩy trước từ để engine ngắt nhẹ rồi nhấn lại

VieNeu: có ngắt rõ (câu dài thêm 0.36 s). OmniVoice: không có tác dụng đo được (+0.06 s); model này bỏ qua dấu câu khi tính nhịp, thử cả ..., —, . đều không ngắt

Cảm xúc

Clip tham chiếu theo cảm xúc (giọng clone). Giọng VieNeu giữ phong cách cố định

Cùng một câu, chỉ đổi clip (hai giọng clone thử nghiệm): giọng nữ vui +2.6 nửa cung, buồn −1.8 nửa cung và chậm hơn 21%, tức giận cao và nhanh; giọng nam ngữ điệu biến thiên mạnh hơn khi vui/buồn (3.8 → 5.0 nửa cung), tức giận nhanh hơn 26%. Nghe mẫu ở ~/archi-tts-output/expressive_check_*

Phụ đề

Mỗi câu một mốc thời gian, chia dòng ≤84 ký tự theo tỉ lệ độ dài

Khớp mốc Whisper trong ~0.1 s

Từ điển phát âm

lexicon.yaml (sửa trực tiếp hoặc dùng tool add_lexicon_entry). Cách đọc được gửi nguyên văn tới engine, không qua bộ chuẩn hóa. Mỗi từ có thể đọc chung cho cả hai engine, hoặc riêng cho từng engine:

AI: ây-ai                                  # cả hai engine
GPU: {vieneu: GPU, omnivoice: gi-pi-iu}    # riêng từng engine

Lý do có hai cách: VieNeu học song ngữ nên đọc GPU, CPU, Pro viết nguyên tốt hơn phiên âm (phiên âm "gi pi iu" bị nghe thành "PU", "prô" thành "Pero"). OmniVoice thì cần phiên âm, và gạch nối giúp đọc liền mạch ("ây ai" bị nghe thành "AAI" 3/4 lần, "ây-ai" đúng 2/2). Với VieNeu, gạch nối tự đổi thành dấu cách.

Với từ điển hiện tại, cả 4 giọng thử (ngoc_huyen, pham_tuyen và hai giọng clone) đều đọc đúng câu "Các ứng dụng AI và GPU, chiếc iPhone 16 Pro giá 25 triệu đồng, CPU cũng nhanh hơn" (kiểm tra bằng Whisper). Dùng check_text để xem trước mỗi engine sẽ đọc thành gì.

Tài nguyên (M1 Pro 16 GB)

  • Model: VieNeu + MOSS codec 0.6 GB, OmniVoice 3.3 GB (chỉ bản full); Whisper 1.6 GB tải thêm khi add_voice không kèm transcript.

  • RAM: bản lite ~1.4 GB. Bản full khi dùng cả hai engine: đỉnh ~7.6 GB (OmniVoice chạy trên GPU qua MPS), ~5 GB lúc nghỉ sau khi đã nạp model.

  • Job 6 phút audio, 5 giọng: sinh trong 7 phút, tốc độ không chậm dần (RTF đầu/cuối: VieNeu 0.28/0.28, OmniVoice 2.68/2.69).

  • Chạy được hoàn toàn offline sau lần tải model đầu tiên (HF_HUB_OFFLINE=1).

Giọng & bản quyền

  • Repo không kèm clip giọng của bên thứ ba. Benchmark trong bench/ clone từ clip giọng tổng hợp Gemini của dataset slexisvn/emotion-tts-vietnamese-sample; các clip đó không kèm theo (tải lại bằng bench/common/pick_refs.py), chỉ giữ file nghe kết quả để so sánh.

  • VieNeu: Apache-2.0. OmniVoice fine-tune: Apache-2.0; bộ mã hóa audio đi kèm theo Boson Higgs Audio 2 Community License.

  • Dùng cho mục đích cá nhân. Chỉ clone giọng khi có quyền sử dụng giọng đó.

Phát triển

uv sync --extra full                  # .venv cho repo (có OmniVoice), dùng voices/ và lexicon.yaml trong repo
uv run --group dev pytest             # unit test
uv run python scripts/mcp_smoke.py    # end-to-end qua MCP stdio (cần model)
ARCHI_TTS_HOME=~/.archi-tts/home uv run python scripts/control_check.py   # các script đo cần giọng clone
ARCHI_TTS_SMOKE_CMD=bin/archi-tts-mcp uv run python scripts/mcp_smoke.py   # qua launcher của plugin

Nhánh và phát hành

  • main: chỉ chứa bản đã phát hành, là thứ người cài plugin nhận được. Không commit thẳng.

  • develop: làm việc hằng ngày ở đây. Push lên develop không chạy CI.

  • Phát hành: tăng version trong .claude-plugin/plugin.json (chỗ duy nhất chứa version) và cập nhật CHANGELOG.md trên develop, mở PR develop → main (CI chạy một lần), merge khi xanh, rồi gắn tag vX.Y.Z trên main (CI kiểm tra tag khớp version).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Vietnamese text-to-speech with voice cloning, 10 built-in voices, text normalization, and long-form queuing, running 100% locally.
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Text to speech in 149 languages: MP3 links from any assistant. Free without an account. 2,253 voices; PRO adds HD voices, WAV, dialogue with a voice per speaker, Script mode timing and transcription.
      7
      44 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local MCP server that turns any text into narration, voice-overs, dialogues, audiobook chapters and per-shot video clips as MP3/WAV files — with emotions, acting modes, inline cues, presets and subtitles — driven by a ChatGPT sign-in rather than an API key. It also exposes tools for inspecting audio (timings, pace, pitch, waveform), transcribing recordings, listing and favouring voices, saving pronunciation presets, and checking sign-in status.
      MIT