Voicebox is a local-first open-source AI voice workbench that integrates voice cloning, text-to-speech, Whisper speech recognition, global dictation, REST API, and MCP Server into a single desktop application.
It supports Windows CUDA, macOS MLX, Linux, AMD ROCm, Intel Arc, and Docker. Windows users can install MSI directly without having to set up a Python project first. Models, reference audio, and generated results are saved locally by default, suitable for scenarios where you do not want to upload sound samples to third-party services.
Quick Answer
The easiest way on Windows is to download MSI from Voicebox Releases. After the first run, install only one TTS engine suitable for VRAM, first convert normal text to speech, then add reference audio for voice cloning. When you need to let Claude Code, Cursor, or other Agents speak, enable the service in Voicebox’s MCP settings and configure the client according to the address generated by the interface.
Don’t download all models at the same time. Qwen3-TTS, Chatterbox, TADA, and Whisper will take up disk and VRAM respectively, and having too many models can make initial troubleshooting difficult.
What can Voicebox do?
The current project combines the two voice links of input and output:
- Create sound configurations using a few seconds of reference audio;
- Generate voice through engines such as Qwen3-TTS, Chatterbox, Kokoro;
- Use Whisper to convert microphones or audio files into text;
- Use global shortcuts to dictate in other apps;
- Enable AI Agents to invoke voice via REST API or MCP;
- Combine multi-role dialogues, podcasts, or narration in the Stories editor;
- Add effects such as reverb, pitch change, and compression to the generated results.
The project README currently lists 7 TTS engines and 23 languages, but each engine supports different languages, memory requirements, and performance. Therefore, “application support for 23 languages” cannot be understood as supporting all languages for every model.
Windows installation steps
1. Check the graphics card and driver
NVIDIA users run first:
|
|
If the command does not exist or driver information cannot be displayed, first repair the graphics card driver. Successful installation of Voicebox does not necessarily mean CUDA inference is available.
Without NVIDIA graphics cards, you can also try other backends supported by the CPU or project, but generation speed and available models will be affected.
2. Download MSI
Download the latest Windows installer from the official Release page:
|
|
After installation, launch from the Start menu. If Windows SmartScreen prompts an unknown publisher, first verify the download link, release file name, and project repository; do not look for so-called green versions from third-party cloud drives.
3. Only one model was downloaded for testing
The first test can be selected by hardware:
| Scenario | Recommended starting point |
|---|---|
| CPU or VRAM is very small | Kokoro or LuxTTS |
| Requires Chinese, multilingual, and voice cloning | Qwen3-TTS 0.6B |
| Emphasize expression control | Qwen3-TTS 1.7B or Qwen CustomVoice |
| Need More Language Coverage | Chatterbox Multilingual |
The specific available model is based on the current model management page of the application. After downloading the model, first enter a short piece of text to generate the default voice, confirm the backend is normal, then create the sound configuration.
Create Voice Clone Configuration
Reference audio directly affects the results. Recommendations:
- Use single-person recordings without background music or reverberation;
- Maintain natural speaking speed and stable volume;
- Cut out prolonged silence and obvious noise;
- Only use voices you have authorized;
- Test with short sentences first; don’t generate long articles directly.
Upload or record reference audio in Voice Profile, select an engine that supports zero-shot cloning, and then enter test text. Different engines have different requirements for reference audio length and transcription accuracy. If one engine performs poorly, you can switch engines for comparison instead of just increasing the volume.
Use Whisper for Dictation and Transcription
Voicebox’s voice input uses Whisper, and you can choose sizes such as Base, Small, Medium, Large, or Turbo. Usually:
- Small models download quickly and use up low usage, suitable for everyday dictation;
- Large models are heavier, suitable for accents, noise, or complex content;
- Turbo is suitable for tasks where you want to increase speed while maintaining good quality.
Global dictation requires system microphone permissions. If you see “Can record but cannot paste” appears, check microphone permissions, Voicebox shortcut key conflicts, and whether the target app allows automatic input.
Integrate the MCP Agent
Voicebox has a built-in MCP Server that allows MCP-supported clients to call voicebox.speak. The recommended process is:
- Complete one manual voice generation in Voicebox;
- Open Settings → MCP;
- Enable MCP and copy the connection information provided by the interface;
- Add the service in Claude Code, Cursor, Cline, or other MCP clients;
- Have the Agent speak only one short sentence to confirm the connection and sound configuration;
- Then bind different Voice Profiles to different Agents.
The project provides both HTTP and stdio transmission methods. Do not rely on old tutorials for handwritten ports and binary paths; prioritize using the configuration generated by the current version settings page.
Agent vocals are suitable for completion notifications, approval issues, and short status prompts. Do not let it read the full log aloud, as this will occupy the generation queue and it is difficult to locate technical errors from the voice.
Running Docker
The Docker entry point provided by the project README is:
|
|
Docker is more suitable for Linux servers or users who want to isolate dependencies. If you need a GPU on Windows, make sure Docker Desktop, WSL2, NVIDIA drivers, and container GPU support are all normal. Desktop dictation and global shortcuts are better suited for the native MSI version.
The official docker-compose.yml defaults to CPU builds and does not automatically use NVIDIA GPUs. It restricts services to local loopback addresses:
|
|
Therefore, the Docker version of health check should access the host’s 17600, not the 17493 commonly used in desktop versions:
|
|
The Compose file also defines three types of persistent data:
| Data | Default Position | Function |
|---|---|---|
| Generate Audio | ./output |
Convenient for directly reading results from the host |
voicebox-data |
Docker named volume | Saves profile, database, and application data |
huggingface-cache |
Docker named volume | Avoid re-downloading the model after rebuilding |
Do not add -v when stopping the container:
|
|
docker compose down -v will also delete named volumes, which may cause both the model cache and application data to disappear.
Understanding Why the First Generation Is Slow
The official troubleshooting documentation states that the first generation may take 2–5 minutes because the application needs to download and initialize the model. The model size varies greatly between engines: Kokoro is about 350 MB, while TADA 3B can reach about 8 GB.
During the first test, observe in the following order:
- Does Settings → Models display download progress;
- Whether the network can access Hugging Face;
- After the model download is complete, whether the GPU or CPU has started working;
- Check if the second generation is noticeably faster.
If the first time is slow and the second time is normal, it’s not a fault. Only if the download progress remains unchanged for a long time, there are errors in the logs, or if the download restarts every time you start up should you check the network and cache directory.
For low bandwidth or just want to confirm successful installation, the official recommendation is to first use Kokoro or LuxTTS, both with download volumes of about 300–350 MB, then decide whether to install larger cloning models.
View Service Status and Logs
The desktop app backend defaults to 17493. If a red status appears or a Failed to connect to server message appears in the lower left corner, first check the port:
|
|
If another process is returned, record the PID:
|
|
After confirming that the process can be stopped, close it normally. Do not directly kill unknown system processes just because they see port occupancy.
Windows Service Log is located at:
|
|
PowerShell allows real-time viewing of the tail:
|
|
Logs can distinguish at least four types of issues: service failure to start, model download failure, CUDA/memory errors, and audio or database errors.
flash-attn is not installed Should it be repaired?
Windows logs may recur:
|
|
Official documentation clearly states that this can usually be ignored. Windows does not have stable official flash-attn support; Voicebox uses PyTorch’s built-in SDPA, and voice can still be generated normally. Do not treat this warning as a service start failure, nor do you recommend installing a mismatched community wheel to clear logs.
Only consider when Linux, CUDA, and PyTorch versions are fully compatible and performance is indeed constrained:
|
|
Compilation may take more than twenty minutes, and failure does not affect continued use of the default backend.
How to choose between VRAM and CPU modes
The official troubleshooting document uses more than 6GB of VRAM as a practical threshold for GPU generation. Different engines will still have variations, so the actual model and text length should be used as the standard.
When CUDA out of memory appears, handle them in the following order:
- Close the game, video editor, and browser tabs that occupy WebGL;
- Uninstall the currently unused model in Voicebox;
- Restart the app and clear up the VRAM that has been occupied but not freed;
- Switch to a smaller model;
- Split long texts;
- Finally, switch to Settings → Generation → Use CPU instead of GPU.
CPU mode uses system memory, and the official estimate is that it may be 5–10 times slower than the GPU. It’s suitable for verifying functions or low-frequency generation, and not for hiding memory issues to continue batch tasks.
How should sound quality be compared?
Don’t judge the model based on generating just one sentence. Prepare a set of fixed test texts:
|
|
Each Voice Profile uses the same set of text, the same output format, and similar parameters. The official recommendation is to use clear recordings of 10–30 seconds for reference audio, and you can add multiple segments of samples from the same speaker. When the tone is similar but the tone is stiff, check whether the reference sample itself is too monotonous, rather than just increasing the sample length.
Model Caching and Data Backup
The application provides model directory migration and profile import and export. Before upgrading, cleaning disk, or reinstalling, prioritize exporting important profiles from the application and recording the model directory.
The official documentation provides a recovery method for directly deleting the database, but this will cause loss of Voice Profiles and generation history, so it cannot be used as the first step in ordinary troubleshooting. When encountering an SQLite lock, first close all Voicebox instances and back up the data, then process the lock files based on the logs.
If the model version is abnormal, do not delete the entire Hugging Face cache directly. First, delete the specific model in Settings → Models; Manual cleaning should be limited to a clear model directory and ensure the application is closed.
Do not expose ports directly for remote access
The Voicebox backend provides health checkups:
|
|
This only verifies whether the service is reachable and does not mean it is suitable for direct exposure to the public network. For remote use, at least the following are required:
- Firewalls only allow trusted sources;
- Access via VPN, SSH tunnel, or authenticated reverse proxy;
- Model management, profile, and generation interfaces are not disclosed;
- Check whether the MCP client writes the tool address into the synchronized configuration;
- Regularly review your visit logs.
If the Agent is only being called on the same computer, the 127.0.0.1 should continue to bind without opening the LAN port.
Common Problem Troubleshooting
Model download is stuck
First, check disk space and network, then check if Hugging Face Hub is accessible. When deactivating, cleaning, and migrating the Voicebox model page, prioritize using built-in features and do not delete the entire data directory directly.
When manual verification is needed, you can install the Hugging Face CLI and try model download separately:
|
|
When the CLI also cannot download, the problem usually lies in the network, proxy, disk, or Hugging Face access, rather than the Voicebox interface.
CUDA is available but lacks VRAM during generation
Close other GPU-intensive programs, uninstall unused models, switch to smaller engines or version 0.6B, and shorten the amount of text generated per time. Although long text can be automatically chunked, it still increases task time and cache usage.
Unnatural Chinese pronunciation
Confirm that the current engine clearly supports Chinese, and try to match the reference audio language with the generated text as much as possible. Even if the English-specific model can read Chinese characters, it does not mean the Chinese quality is qualified.
MCP is configured but the agent has no sound
First, manually generate the voice within the Voicebox, then check whether the MCP client has found the voicebox.speak, whether the Voice Profile name exists, and whether the Voicebox is still running. Separate the “Tool Not Connected” and “Voice Generation Failure” for investigation.
Privacy and Voice Authorization
Local operation reduces the risk of uploading voice samples but does not automatically resolve authorization issues. Do not clone others’ voices for impersonation, fraud, or unauthorized public content. When publicly publishing generated audio, it is best to clearly indicate the synthesis source and properly protect the reference audio and exported Voice Profile.
References
- Voicebox GitHub repository
- [Voicebox Latest Version] (https://github.com/jamiepine/voicebox/releases/latest)
- Voicebox Official Documentation