VoxBuddy

Screenshots

VoxBuddy is a local desktop text-to-speech app for macOS on Apple Silicon. It provides a simple GUI for generating speech with MLX-accelerated models, switching between multiple TTS engines, cloning voices from reference audio, recording new voice samples, and exporting finished audio as WAV.

This repository is focused on local inference. Models are downloaded on first use and cached through Hugging Face in ~/.cache/huggingface.

GitHub repository: https://github.com/MateuszPsuja/voxbuddy

Highlights

• Runs locally on Apple Silicon with MLX-backed TTS models
• Switches between three engines from one desktop UI:
  • Chatterbox MLX
  • Chatterbox Turbo MLX
  • Qwen3-TTS MLX
• Supports multilingual generation with model-specific language availability
• Includes 50 built-in voices across American English and British voice sets
• Supports custom voice cloning from imported .wav or .mp3 files
• Includes in-app microphone recording for creating saved custom voices
• Automatically splits long text into chunks and stitches the generated audio back together
• Lets you preview playback, stop playback, and export generated audio as .wav
• Shows generation progress and performance stats after synthesis

Model Overview

• Chatterbox MLX

  • Best for: general-purpose multilingual speech
  • Language support: English, Polish, German, French, Spanish, Italian, Portuguese, Dutch, Russian, Chinese, Japanese, Korean
  • Voice reference: yes
  • Controls: seed, exaggeration, CFG weight, temperature, long-text chunking

• Chatterbox Turbo MLX

  • Best for: faster generation
  • Language support: English only
  • Voice reference: yes
  • Controls: seed only (simplified workflow)

• Qwen3-TTS MLX

  • Best for: voice cloning with instruction prompts
  • Language support: English, Chinese, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian
  • Voice reference: yes
  • Controls: seed, instruction prompt

Requirements

• macOS on Apple Silicon
• Python 3.13 recommended
• A working microphone if you want to record custom voices
• Audio input/output permissions enabled for Terminal or your Python runtime when prompted by macOS

Installation

1. Clone the repository and move into it.

git clone https://github.com/MateuszPsuja/voxbuddy.git
cd voxBuddy

1. Create and activate a virtual environment.

python3.13 -m venv venv
source venv/bin/activate

1. Install dependencies (recommended).

pip install -r requirements.txt

1. Launch the app. The preferred flow is to install dependencies first, then start the UI:

./run_ui.sh

Note: run_ui.sh activates the local venv and performs a small convenience pip install for a few GUI/audio packages. That script redirects pip output to /dev/null by default, so if you encounter installation errors run the pip install -r requirements.txt command above to see full output. The first generation run may take longer because the selected model is downloaded and any required NLTK tokenizer assets are fetched into temp/nltk_data.

How It Works

Basic generation

1. Start the app with ./run_ui.sh
2. Choose a model from the top-right model selector
3. Pick a language if the model supports multiple languages
4. Select a built-in voice or a custom saved voice
5. Paste or type text into the editor
6. Click Generate
7. Use Play to preview the result or Save as WAV to export it

Voice cloning

VoxBuddy supports two ways to create reusable custom voices:

• Load File: import a .wav or .mp3 reference sample
• Record: capture a voice sample directly in the app

Recorded or imported voices are stored locally in asset/custom_voices and appear in the voice dropdown under My Voices.

For best results, use a clean mono speech sample with minimal background noise. The app validates recording quality and rejects clips that are too short, too long, too quiet, or clipped.

Long text handling

For longer input, VoxBuddy automatically switches to chunked generation. The app prepares text chunks itself, generates each chunk in order, and stitches the audio back together. The UI shows:

• word count
• estimated chunk count
• silence duration between chunks

This keeps long passages more manageable and reduces the likelihood of unstable generation on larger inputs.

Notes

• VoxBuddy is designed around MLX, so it is intended for Apple Silicon hardware.
• Models are fetched from Hugging Face on first use and cached locally.
• If you run into Hugging Face rate limits, setting HF_TOKEN in your shell may help.
• run_ui.sh activates the local virtual environment and starts the desktop UI with Python 3.13.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Troubleshooting

• If you see audio device or permission errors on macOS, ensure Terminal (or the app you use to run Python) has Microphone and Input/Output permissions in System Settings → Privacy & Security.
• If model downloads fail or are rate-limited, set HF_TOKEN and retry. Models are cached in ~/.cache/huggingface.
• If ./run_ui.sh fails silently during dependency install, run pip install -r requirements.txt manually to view and fix errors.

GitHub

This project is available on GitHub and can be cloned with:

git clone https://github.com/MateuszPsuja/voxbuddy.git

For visitors landing on the repository page, the key points are:

• this is a local macOS desktop app, not a cloud service
• it targets Apple Silicon and MLX
• it supports multiple TTS engines from one UI
• it includes voice cloning, recording, playback, and WAV export