# voicebox: studio AI giọng nói chạy local — hướng dẫn cài đặt và dùng

> Voicebox là studio AI giọng nói local-first, có thể clone giọng, chuyển văn bản thành giọng nói, đọc chính tả và cho agent nói bằng giọng đã chọn. Ứng dụng hỗ trợ macOS, Windows, Linux, Docker cùng nhiều backend GPU; cách cài đơn giản nhất là dùng bản tải sẵn hoặc Docker.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-01 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/voicebox-studio-ai-giong-noi-chay-local

Voicebox là studio AI giọng nói mã nguồn mở chạy local trên máy tính. Repo gom cả hai chiều của giao tiếp bằng giọng nói: tạo âm thanh từ văn bản và chuyển giọng nói thành văn bản. Bạn có thể clone một giọng từ vài giây âm thanh, tạo speech bằng nhiều engine, hoặc đọc chính tả vào ứng dụng đang dùng.

Repo phù hợp với chủ shop muốn làm nội dung bằng giọng riêng, nhân viên văn phòng cần đọc chính tả, nhà phát triển muốn thêm voice output cho agent, và người làm sản phẩm cần API giọng nói chạy tại chỗ. Điểm đáng giá nhất là model, dữ liệu giọng và file thu âm được giữ trên máy theo thiết kế local-first. README cũng cho biết Voicebox miễn phí, mã nguồn mở theo giấy phép MIT và không chèn màn hình chờ, banner hay quảng cáo trong app.

```repo
- repo | jamiepine/voicebox
- kind | Ứng dụng
- desc | Voicebox là studio AI giọng nói mã nguồn mở, hỗ trợ clone giọng, tạo speech, đọc chính tả và kết nối agent ngay trên máy.
- stars | 61k
- lang | Python
- license | MIT
```

## Voicebox làm được gì

### Clone giọng và tạo speech

Bạn có thể tạo voice profile từ file âm thanh hoặc ghi trực tiếp trong app. Sau đó, Voicebox dùng profile này để đọc văn bản bằng giọng tương ứng. Repo hỗ trợ clone zero-shot từ mẫu tham chiếu, nhiều mẫu cho một profile, cũng như nhập và xuất profile để sao lưu hoặc chia sẻ.

Nếu không muốn thu âm mẫu, bạn có thể dùng các giọng dựng sẵn. Kokoro có 50 giọng preset, còn Qwen CustomVoice có 9 giọng preset có thể điều khiển cách đọc bằng mô tả tự nhiên.

### Chọn engine theo nhu cầu

Voicebox tích hợp 8 engine TTS: Qwen3-TTS, Qwen CustomVoice, Qwen VoiceDesign, LuxTTS, Chatterbox Multilingual, Chatterbox Turbo, HumeAI TADA và Kokoro. Mỗi engine có thế mạnh khác nhau.

Qwen3-TTS phù hợp với clone giọng đa ngôn ngữ và hướng dẫn cách đọc như nói chậm hoặc thì thầm. Chatterbox Multilingual có phạm vi 23 ngôn ngữ. LuxTTS nhẹ, dùng khoảng 1 GB VRAM và có thể chạy nhanh trên CPU. Kokoro nhỏ, chỉ 82M model, phù hợp khi cần suy luận CPU nhanh.

Qwen VoiceDesign cho phép mô tả giọng bằng ngôn ngữ tự nhiên thay vì dùng audio mẫu. Đây là lựa chọn tiện khi bạn cần một giọng nhân vật mới cho nội dung hoặc bản thử nghiệm.

### Điều khiển cảm xúc và cách đọc

Chatterbox Turbo hiểu các thẻ như `[laugh]`, `[sigh]`, `[gasp]`, `[whispering]`, `[dramatic]` hoặc `[advertisement]`. Trong ô nhập văn bản, bạn có thể gõ `/` để mở bộ chèn thẻ.

Lưu ý quan trọng là chỉ Chatterbox Turbo diễn giải các thẻ paralinguistic này. Với Qwen3-TTS, LuxTTS, Chatterbox Multilingual và HumeAI TADA, các thẻ có thể được đọc như văn bản bình thường.

### Tạo audio dài và chỉnh hậu kỳ

Văn bản dài được tự động tách theo ranh giới câu. Voicebox tạo từng đoạn rồi crossfade để nối lại thành một file liền mạch. Giới hạn tự động chia đoạn có thể điều chỉnh từ 100 đến 5.000 ký tự, còn độ dài văn bản tối đa là 50.000 ký tự.

Bạn cũng có thể áp dụng 8 hiệu ứng sau khi tạo audio: đổi cao độ, reverb, delay, chorus hoặc flanger, compressor, gain, high-pass filter và low-pass filter. App có 4 preset sẵn gồm Robotic, Radio, Echo Chamber và Deep Voice, đồng thời cho phép tạo preset riêng.

### Làm podcast, hội thoại và truyện

Stories Editor cung cấp timeline nhiều track cho hội thoại, podcast và nội dung kể chuyện. Bạn có thể kéo thả track, cắt hoặc tách audio trực tiếp, phát lại theo playhead đồng bộ và ghim phiên bản cho từng đoạn.

Mỗi lần tạo audio cũng có hệ thống version. Bản gốc luôn được giữ, các bản áp hiệu ứng có nguồn gốc rõ ràng, và bạn có thể tạo take mới bằng seed khác để thử biến thể.

### Đọc chính tả vào ứng dụng

Voicebox dùng Whisper cho speech-to-text. Bạn có thể dùng phím tắt toàn hệ thống với chế độ push-to-talk hoặc toggle, hoặc bấm mic ngay trong các ô nhập của Voicebox.

Trên macOS, bản chép lời có thể được dán vào ô đang focus sau khi Voicebox kiểm tra quyền Accessibility. App có màn hình hướng dẫn cấp quyền Accessibility và Input Monitoring trong lần chạy đầu. Tính năng refinement bằng LLM có thể dọn từ đệm, nói lắp và câu mở đầu thừa trước khi dán.

### Cho agent nói bằng giọng đã chọn

Voicebox có MCP server và REST API. Agent tương thích MCP có thể gọi `voicebox_speak` để nói bằng một voice profile cụ thể. README nêu các client như Claude Code, Cursor, Cline, Windsurf và VS Code có thể kết nối qua HTTP hoặc stdio.

Bạn cũng có thể gọi REST API bằng `POST /speak` từ script, ACP, A2A hoặc ứng dụng riêng. Overlay trên màn hình hiển thị trạng thái như `recording`, `transcribing`, `refining` và `speaking`, giúp bạn biết agent đang làm gì.

### Dùng persona và LLM local

Bạn có thể gắn một persona dạng văn bản vào voice profile. Voicebox có hai chế độ Compose và Speak in character. Compose tạo một câu mới theo nhân vật để bạn chỉnh sửa rồi đọc; Speak in character viết lại nội dung theo persona trước khi đưa sang TTS.

LLM đi kèm là Qwen3 với các lựa chọn 0.6B, 1.7B và 4B. LLM này cũng được dùng cho refinement của dictation và chạy local theo README.

## Cần chuẩn bị gì

Bạn cần một máy tính chạy macOS, Windows hoặc Linux. Voicebox cũng có thể chạy bằng Docker. README cho biết bản tải sẵn hiện có cho macOS Apple Silicon, macOS Intel và Windows; Linux chưa có binary dựng sẵn nên cần xem hướng dẫn build from source được chỉ trong README.

Về phần cứng, app có thể chạy trên CPU ở mọi nền tảng nhưng sẽ chậm hơn. macOS Apple Silicon dùng MLX và Metal. NVIDIA dùng PyTorch CUDA. Linux AMD dùng ROCm, Windows có thể dùng DirectML, còn Intel Arc có backend IPEX/XPU.

Nếu dùng macOS cho dictation toàn hệ thống, bạn cần cấp quyền Accessibility và Input Monitoring khi app yêu cầu. README không nói cần tạo tài khoản hay API key. Vì các model, voice data và capture chạy local, bạn cũng không cần dịch vụ cloud để dùng các chức năng chính theo nội dung đã cung cấp.

Dung lượng model và bộ nhớ GPU phụ thuộc engine. README chỉ nêu rõ LuxTTS dùng khoảng 1 GB VRAM, Kokoro là model 82M, còn các engine và LLM khác có nhiều kích thước. Voicebox có chức năng unload model để giải phóng GPU memory mà không xóa file đã tải.

## Cài đặt từng bước

```steps
- Chọn cách cài | Dùng bản DMG/MSI hoặc chạy Docker
- Chuẩn bị môi trường | Chọn CPU, GPU hoặc backend phù hợp với máy
- Khởi động Voicebox | Mở app đã cài hoặc chạy Docker Compose
- Tạo profile | Thêm audio mẫu hoặc chọn voice preset
- Kiểm tra tích hợp | Tạo speech, dictation hoặc gọi API local
```

### Chọn bản cài phù hợp

Với macOS Apple Silicon, README cung cấp bản DMG riêng. Mac Intel cũng có DMG riêng. Windows có bản MSI. Đây là cách dễ nhất cho người mới vì README không yêu cầu bạn tự cài Python package hay Node package để dùng bản desktop.

README chưa ghi lệnh cài đặt từ source cho Windows hoặc macOS. Nếu dùng Linux, README nói rõ binary dựng sẵn chưa có và trỏ tới hướng dẫn build from source của dự án. Vì vậy, không nên tự đoán lệnh cài Python, Bun hoặc Rust chỉ dựa trên tên các file trong repo.

### Chạy bằng Docker

Nếu đã clone repo về máy, mở terminal tại thư mục gốc của repo rồi chạy:

```bash
docker compose up
```

Lệnh này khởi động cấu hình Docker Compose mặc định được repo cung cấp. Bạn phải chạy nó trong đúng thư mục có file `docker-compose.yml`. Nếu terminal đang ở thư mục khác, hãy chuyển vào thư mục repo trước.

README chỉ nêu lệnh `docker compose up`, chưa cung cấp trong phần tư liệu này URL truy cập, tài khoản mặc định hay biến môi trường bắt buộc. Nếu Docker báo lỗi quyền, thiếu image hoặc không nhận GPU, hãy xem Troubleshooting Guide và các file Docker Compose trong repo thay vì tự thêm cờ hoặc biến chưa được tài liệu xác nhận.

### Nếu cần lấy mã nguồn

Lệnh phổ thông để tải repo là:

```bash
git clone https://github.com/jamiepine/voicebox.git
cd voicebox
```

`git clone` tải mã nguồn về máy. `cd voicebox` đưa terminal vào thư mục dự án. Bước này hữu ích khi bạn muốn chạy Docker Compose, xem cấu hình, hoặc build bản Linux.

Repo có `package.json`, `requirements.txt`, `Dockerfile`, `docker-compose.yml` và thư mục `tauri/`, nhưng README được cung cấp chưa ghi đầy đủ quy trình cài dependency và build from source. Vì vậy, với người mới, hãy ưu tiên DMG, MSI hoặc Docker. Với Linux, mở hướng dẫn Linux install được README chỉ tới để lấy đúng các bước.

### Mở app và cấp quyền cần thiết

Sau khi cài bằng DMG hoặc MSI, mở Voicebox như một ứng dụng desktop thông thường. Khi dùng dictation toàn hệ thống trên macOS, làm theo màn hình hướng dẫn để cấp Accessibility và Input Monitoring.

Nếu chỉ tạo speech từ văn bản hoặc dùng mic trong app, bạn có thể bắt đầu từ giao diện Voicebox. Quyền hệ điều hành nào được yêu cầu ngoài các quyền macOS nói trên chưa được README cung cấp chi tiết.

### Tạo voice profile đầu tiên

Trong app, tạo profile bằng cách nhập một file audio hoặc ghi trực tiếp. Bạn cũng có thể chọn voice preset nếu chưa có mẫu thu âm. Đặt tên và mô tả cho profile để dễ chọn khi tạo speech hoặc gắn với agent.

Nếu muốn clone giọng tốt hơn, dùng nhiều sample cho cùng profile. README cho biết Voicebox hỗ trợ multi-sample, nhưng không đưa ra thời lượng audio tối thiểu hay định dạng file bắt buộc. Không nên tự suy ra các giới hạn này nếu chưa xem tài liệu trong app.

## Kiểm tra đã chạy được chưa

Cách kiểm tra đơn giản nhất là mở app, chọn một engine và tạo một đoạn speech ngắn. Nếu audio được tạo và phát lại được, phần TTS cơ bản đã hoạt động. Với voice profile, kiểm tra xem profile xuất hiện trong danh sách chọn giọng và có thể dùng cho một lần generation.

Nếu dùng Docker hoặc muốn kiểm tra API, README cung cấp ví dụ tạo speech bằng REST API:

```bash
curl -X POST http://127.0.0.1:17493/generate \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "profile_id": "abc123", "language": "en"}'
```

Lệnh này gửi văn bản `Hello world`, profile ID `abc123` và ngôn ngữ `en` tới endpoint local. Bạn cần thay `abc123` bằng profile ID thực tế của mình. Nếu service đang chạy và request hợp lệ, Voicebox sẽ xử lý một lần tạo speech.

Bạn cũng có thể kiểm tra chức năng agent output:

```bash
curl -X POST http://127.0.0.1:17493/speak \
  -H "Content-Type: application/json" \
  -H "X-Voicebox-Client-Id: my-script" \
  -d '{"text": "Deploy complete."}'
```

Nếu agent hoặc script được cấu hình đúng, Voicebox sẽ đọc câu `Deploy complete.` bằng voice profile đã được thiết lập. README không cung cấp response JSON mẫu trong phần tư liệu này, nên không nên dựa vào một mã trạng thái cụ thể để kết luận ngoài việc kiểm tra audio và trạng thái trong app.

## Dùng vào việc thật

### Chủ shop làm lời thoại cho video sản phẩm

Chủ shop có thể tạo một voice profile từ giọng của mình, sau đó nhập lời giới thiệu sản phẩm dài. Voicebox tự chia văn bản theo câu, tạo từng đoạn và crossfade lại. Bạn có thể dùng pitch, compressor hoặc preset Radio để làm giọng dễ nghe hơn rồi chọn phiên bản ưng ý.

Ví dụ nội dung có thể nhập là: “Đây là mẫu bình giữ nhiệt mới của cửa hàng. Sản phẩm giữ nhiệt lâu, dễ vệ sinh và phù hợp mang đi làm.” Nếu cần lời đọc dài cho nhiều sản phẩm, giới hạn 50.000 ký tự và Stories Editor giúp sắp xếp nhiều track.

### Nhân viên văn phòng đọc chính tả biên bản

Nhân viên có thể giữ phím tắt dictation, nói nội dung cuộc họp rồi thả phím. Voicebox dùng Whisper để chép lời. Nếu bật refinement, LLM local có thể dọn từ đệm, nói lắp và các câu mở đầu thừa trước khi chèn vào ô văn bản.

Trên macOS, nội dung có thể được dán vào ô đang focus sau khi cấp quyền Accessibility. Nếu chưa muốn dùng phím tắt toàn hệ thống, bạn có thể bấm mic trong các ô nhập của Voicebox để thử quy trình trong app trước.

### Lập trình viên cho agent thông báo bằng giọng riêng

Một agent MCP-aware có thể gọi:

```ts
await voicebox_speak({
  text: "Deploy complete.",
  profile: "Morgan",
});
```

Agent sẽ nói câu thông báo bằng profile `Morgan`. Bạn có thể gắn các agent khác nhau với profile khác nhau trong phần Settings → MCP, ví dụ để phân biệt agent xử lý code và agent xử lý vận hành chỉ bằng giọng nói.

Nếu client không dùng MCP, gọi endpoint `/speak` từ script:

```bash
curl -X POST http://127.0.0.1:17493/speak \
  -H "Content-Type: application/json" \
  -H "X-Voicebox-Client-Id: my-script" \
  -d '{"text": "Deploy complete."}'
```

### Làm nhân vật tương tác cho game hoặc nội dung kể chuyện

Người làm game có thể mô tả một persona cho voice profile, chẳng hạn nhân vật nói ngắn, bình tĩnh và luôn giải thích theo từng bước. Sau đó dùng Compose để tạo câu thoại mới hoặc bật Speak in character để viết lại nội dung theo persona trước khi đọc.

Với nội dung có cảm xúc, chọn Chatterbox Turbo và thêm thẻ như `[whispering]`, `[dramatic]` hoặc `[laugh]`. Hãy nhớ kiểm tra engine đang chọn, vì các engine khác có thể đọc nguyên thẻ thành tiếng.

> Khi giọng nói chạy local, bạn có thể biến một voice profile thành công cụ làm việc cho cả người dùng lẫn agent.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Docker không khởi động

Kiểm tra bạn đã mở terminal ở đúng thư mục có `docker-compose.yml` và Docker đang chạy. Dùng đúng lệnh README cung cấp là `docker compose up`. Nếu vẫn lỗi, xem Troubleshooting Guide hoặc kiểm tra cấu hình trong file Compose của repo; không tự thêm biến môi trường chưa được tài liệu nói tới.

### GPU không được nhận

Voicebox vẫn có thể chạy CPU nhưng tốc độ chậm hơn. Chọn backend đúng theo máy: CUDA cho NVIDIA, ROCm cho AMD Linux, DirectML cho GPU Windows nói chung, IPEX/XPU cho Intel Arc và MLX/Metal trên Apple Silicon. Các vấn đề cài driver hoặc CUDA cụ thể chưa được README trích dẫn đầy đủ, nên cần xem phần troubleshooting tương ứng.

### Hết bộ nhớ GPU khi đổi model

Voicebox có thể giữ nhiều model trong thư mục model. Hãy dùng chức năng unload model để giải phóng GPU memory mà không xóa bản tải xuống. Nếu cần, chọn model nhỏ hơn; README nêu Kokoro là model 82M và LuxTTS dùng khoảng 1 GB VRAM.

### Thẻ cảm xúc bị đọc thành tiếng

Đây là hành vi dễ nhầm. Chỉ Chatterbox Turbo hiểu thẻ như `[laugh]` hoặc `[sigh]`. Nếu đang dùng Qwen3-TTS, LuxTTS, Chatterbox Multilingual hoặc HumeAI TADA, hãy bỏ thẻ hoặc đổi sang Chatterbox Turbo.

### Dictation không dán được vào ứng dụng

Trên macOS, kiểm tra quyền Accessibility và Input Monitoring. Voicebox có giao diện hướng dẫn cấp quyền trong lần chạy đầu. Nếu chưa muốn xử lý quyền toàn hệ thống, hãy thử nút mic trong ô nhập của Voicebox.

## Có nên dùng không

Voicebox đáng dùng nếu bạn cần một bộ công cụ giọng nói local có cả TTS, STT, clone giọng, hiệu ứng audio, editor nhiều track, API và MCP. Việc hỗ trợ CPU, CUDA, MLX, ROCm, DirectML và Intel Arc giúp repo phù hợp với nhiều loại máy. MIT license, dữ liệu local và khả năng chạy agent bằng voice profile là các điểm mạnh rõ rệt.

Giới hạn là model vẫn cần tải về và tốc độ phụ thuộc phần cứng. CPU chạy được nhưng chậm hơn. Linux chưa có binary dựng sẵn, nên người dùng Linux phải theo hướng build from source. README cũng chưa cho biết chi tiết về cấu hình tối thiểu cho từng engine, thời lượng audio mẫu, định dạng file bắt buộc hay response API đầy đủ.

Bạn nên chọn Voicebox khi ưu tiên quyền riêng tư, muốn kiểm soát voice profile và cần tích hợp agent. Nếu chỉ cần TTS cloud dùng ngay, không muốn quản lý model hoặc không có máy đủ mạnh, một dịch vụ cloud chuyên dụng có thể thuận tiện hơn. Nếu mục tiêu chính là dictation đơn giản, hãy cân nhắc công cụ đọc chính tả nhẹ hơn thay vì cài cả studio nhiều engine.

## Câu hỏi thường gặp

### Voicebox có miễn phí không?

README mô tả Voicebox là công cụ miễn phí, mã nguồn mở và dùng giấy phép MIT. README cũng nói app không có splash screen, banner hay quảng cáo.

### Voicebox có chạy trên Windows không?

Có. README cung cấp bản MSI cho Windows và hỗ trợ PyTorch CUDA, DirectML cho GPU Windows. App cũng có thể chạy CPU nhưng chậm hơn.

### Có cần GPU NVIDIA không?

Không bắt buộc. Voicebox hỗ trợ CPU trên mọi nền tảng, ngoài ra còn có MLX/Metal, CUDA, ROCm, DirectML và IPEX/XPU tùy máy. GPU thường giúp suy luận nhanh hơn.

### Dữ liệu giọng nói có rời khỏi máy không?

README mô tả Voicebox là local-first và nói model, voice data cùng captures không rời khỏi máy. Các chi tiết mạng của từng cấu hình Docker hoặc tích hợp riêng chưa được cung cấp trong tư liệu.

### Có cần API key hoặc tài khoản không?

README được cung cấp không nói cần tạo tài khoản hay API key cho các chức năng chính. Voicebox chạy local theo mô tả của dự án.

### Voicebox khác gì ElevenLabs hoặc WisprFlow?

README mô tả Voicebox là lựa chọn mã nguồn mở local kết hợp hai nhóm chức năng: ElevenLabs thiên về đầu ra giọng nói, còn WisprFlow thiên về đầu vào. Voicebox hỗ trợ cả tạo speech, dictation, clone giọng và agent voice output trong một app.

### Có thể dùng Voicebox cho agent MCP không?

Có. Voicebox có MCP server, tool `voicebox_speak`, REST API `/speak`, cùng HTTP và stdio transport. README nêu các client MCP-aware như Claude Code, Cursor, Cline, Windsurf và VS Code.
