Chatterbox TTS - One Click Installer & UI

This project provides a PySide6 desktop interface for Resemble AI's open-source Chatterbox TTS models, along with a Windows-first setup flow that prepares the environment, installs a suitable PyTorch runtime, and launches the app.

Current recommended launcher flow:

• run.bat: launches the app once after running environment setup.
• setup_env.bat: prepares or repairs the local environment and writes installer logs.
• run.sh + setup_env.sh: best-effort shell launcher/setup flow for macOS/Linux, not yet validated to the same level as Windows.

Windows remains the primary maintained path.

Table of Contents

• Features
• Language Support
• Prerequisites
• Installation & Usage
• Manual Installation (Advanced)
• Project Structure
• Troubleshooting
• Important Notes on PyTorch Installation
• Contributing
• Acknowledgements

Screenshot

Check this beautiful UI - Click to expand

(Early Stage of the App UI)

Language Support

Official Model Capabilities (Current UI) - Click to Expand

• The default shipped model entry is the official ResembleAI/chatterbox multilingual backend.
• The current upstream multilingual backend exposes these official language IDs:
  • ar, da, de, el, en, es, fi, fr, he, hi, it, ja, ko, ms, nl, no, pl, pt, ru, sv, sw, tr, zh
• The UI now includes:
  • a backend-aware model selector
  • an explicit language selector for multilingual models
  • editable models.json entries for custom repo testing
  • multilingual_t3_model support in models.json for multilingual entries (v3 by default, v2 for older repos if needed)
• The app also keeps an optional Legacy English compatibility entry for testing the older English-focused loader path.
• Not every Hugging Face repo is compatible. A repo must match the expected checkpoint layout for the selected backend (multilingual or legacy), otherwise the UI will show a compatibility error.

Notes on Bulgarian and Custom Models - Click to Expand

• Bulgarian is not part of the current official multilingual language list exposed by ResembleAI/chatterbox.
• The UI supports custom repos through models.json, but that does not guarantee the repo is usable with the selected backend.
• The included disabled example entries in models.json are there to show users how to add custom multilingual or legacy repos without editing Python code.

Features

Click to expand

• Simple PySide6 Interface:
  • Text input for speech synthesis.
  • Load reference audio files (.wav, .mp3, .flac) for voice cloning.
  • Model repo picker backed by models.json.
  • Explicit language selector for multilingual models.
  • Open models.json and Reload Model List actions.
  • Model Details, Custom Models Help, HF Token..., and Sampling... dialogs for advanced multilingual controls.
  • Per-model notes and language-specific test presets.
  • Adjustable parameters:
    • Exaggeration
    • CFG/Pace
    • Temperature
    • Random Seed (0 for random)
    • Advanced sampling settings: repetition penalty, min-p, and top-p
  • Audio playback controls (Play/Pause/Resume, Stop, Seekable Playhead).
  • Split lower panel with generated file history and an in-app Activity Log.
  • Status updates for model loading, generation, playback and time elapsed.
  • Option to auto-play audio after generation.
• Smart Text Chunking:
  • Utilizes NLTK for sentence tokenization.
  • Long sentences are intelligently split at spaces to avoid cutting words, ensuring better quality for stitched audio.
  • Handles long text inputs by generating and stitching audio chunks.
• Windows Setup Flow (run.bat + setup_env.bat):
  • Uses uv (a fast Python package installer and resolver) for environment setup.
  • Automatically creates a Python virtual environment (.venv).
  • Installs base application dependencies from requirements.lock.txt.
  • Detects your NVIDIA CUDA runtime and installs a suitable PyTorch build separately from the main dependency lock.
  • Writes timestamped installer logs to the logs/ folder.
  • Downloads necessary NLTK resources (punkt for sentence tokenization).
• Output Management:
  • Saves generated audio to a chatterbox_outputs subdirectory.
  • Filenames include timestamps and the actual seed used for generation.

Prerequisites

Click to expand

1. Python: Version 3.11 is the current supported target for the Windows launcher flow.
2. uv: This ultra-fast Python package manager.
   • Installation instructions: https://github.com/astral-sh/uv#installation
3. FFmpeg: Required by Qt Multimedia for playing various audio formats (including the generated .wav files).
   • Download FFmpeg from https://ffmpeg.org/download.html.
   • Extract it and add the bin directory (containing ffmpeg.exe, ffplay.exe, ffprobe.exe) to your system's PATH environment variable.
4. NVIDIA GPU (Optional, for GPU acceleration):
   • If you have an NVIDIA GPU, ensure you have the latest drivers installed. The installer will attempt to detect your CUDA version.
5. Internet Connection: Required for downloading dependencies during the first setup.

Installation & Usage

Click to expand

1. Clone or Download this Repository:

   git clone https://github.com/actepukc/chatterbox-tts-ui
   cd chatterbox-tts-ui

   Or download the ZIP and extract it. (Remove the screenshot or print it as a memory)

2. Run the Launcher:

   • Simply double-click run.bat.

   • This script will:

     • Call setup_env.bat to prepare or repair the environment.
     • Create .venv if needed.
     • Install or refresh base dependencies.
     • Run install_torch.py only when the Torch runtime needs to be installed or repaired.
     • Launch the main.py application once setup succeeds.

   • Important: the first launch can take several minutes.

     • The UI may not appear immediately.
     • The model can still be downloading after the app window appears.
     • Installer decisions and failures are written to logs\installer_YYYYMMDD_HHMMSS.log.
     • Pre-window startup crashes are written to logs\app_startup_YYYYMMDD_HHMMSS.log.

   • Subsequent launches should be much faster, but the launcher still performs quick environment checks before starting the app.

3. Using the Application (main.py):

   • Load Model: The default model attempts to load automatically on startup. Use Load Selected Model to switch or reload.
   • Experimental multilingual models: enable this option to expose the full models.json list instead of only the recommended default entry.
   • Custom repos: use Open models.json, edit the entries you want, then press Reload Model List.
   • Optional HF token: use HF Token... if you want authenticated Hugging Face downloads and higher rate limits.
     • Get one from Hugging Face Settings > Access Tokens.
     • Create a token with Read access.
     • Paste it into the app.
     • It applies to future Hugging Face downloads in the current session, but restarting the app is recommended so startup downloads also use it cleanly.
     • The token is saved locally in app_settings.json, which is ignored by git and should not be shared.
   • Enter Text: Type or paste the text you want to synthesize. Long texts will be automatically chunked and stitched.
   • Reference Audio (Optional): Click "Browse Reference Audio..." to select a .wav, .mp3, or .flac file to clone its voice characteristics.
   • Adjust Parameters: Use the sliders and seed input to fine-tune the output.
     • CFG/Pace: Lower values (e.g., 0.2-0.4) can slow down speech and improve pacing.
     • Exaggeration: Default 0.5 is usually good. Higher values can be more expressive but also faster.
     • Sampling...: Opens advanced multilingual sampling controls for repetition penalty, min-p, and top-p.
   • Generate Audio: Click "Generate Audio". The status bar will show progress if the text is split into multiple chunks.
   • Playback:
     • If "Auto-play" is checked, audio plays automatically.
     • Use the Play/Pause, Stop, and seek slider.
     • Double-click files in the "Generated Files History" to play them.
     • Watch the Activity Log panel for model downloads, warnings, and tracebacks.
   • Generated files are saved in the chatterbox_outputs folder.

Manual Installation (Advanced)

Click to expand

macOS / Linux

• run.sh now mirrors the split launcher/setup pattern used on Windows through setup_env.sh, but it is still best-effort / experimental.
• If you are on macOS or Linux, manual setup is still the safest fallback.
• Apple Silicon / MPS users should install a suitable PyTorch build manually after the base dependencies are installed if the automatic Torch step is not appropriate for their machine. If you prefer not to use the run.bat script or are on a different OS:

1. Ensure Python 3.11 (or compatible) and uv are installed and in your PATH.
2. Ensure FFmpeg is installed and its bin directory is in your PATH.
3. Open a terminal in the project directory.
4. Create and activate a virtual environment:

   uv venv .venv --python 3.11 
   # On Windows:
   .\.venv\Scripts\activate
   # On macOS/Linux:
   source .venv/bin/activate

5. Install dependencies from the lock file:

   uv pip sync requirements.lock.txt

6. Install the correct PyTorch version:

   python install_torch.py

7. Run the application:

   python main.py

Project Structure

Click to expand

• main.py: The main PySide6 application script.
• run.bat: Windows launcher. Runs setup, then starts the app once.
• launch_app.py: Startup wrapper that logs pre-GUI crashes to logs/app_startup_*.log.
• setup_env.bat: Windows environment setup and repair script.
• run.sh: Shell launcher. Runs setup_env.sh, then starts the app.
• setup_env.sh: Best-effort shell environment setup and repair script for macOS/Linux.
• model_backends.py: Backend-aware Chatterbox model loading adapter.
• models.json: Editable model list for official and custom repo entries.
• requirements.in: High-level list of direct Python dependencies.
• requirements.lock.txt: Fully resolved list of all Python dependencies with pinned versions for reproducible environments (generated by uv pip compile).
• install_torch.py: Python script to detect CUDA and install the appropriate PyTorch build.
• logs/: Installer logs written by setup_env.bat.
• chatterbox_outputs/: Directory where generated audio files are saved (created automatically).
• .venv/: Python virtual environment (created automatically by run.bat or manually).

Troubleshooting

Click to expand

• NLTK 'punkt' resource failed to download: Ensure you have an active internet connection during the first run. You can also try manually downloading it:

  # Activate your .venv first
  python -m nltk.downloader punkt
  python -m nltk.downloader punkt_tab

• First launch is slow / the app seems stuck: This is expected on a clean setup. The environment, PyTorch runtime, and model files may still be downloading. Check the Activity Log or the newest file in logs/.
• The app started on CPU but you have an NVIDIA GPU: Close the app and run run.bat again from a console so you can watch the installer output. If it still fails, attach the newest file from logs/installer_*.log.
• The app still fails after a previous broken install: Delete .venv and run run.bat again for a clean rebuild.
• macOS / Linux shell launcher problems: run.sh and setup_env.sh are still best-effort. If they fail on your machine, fall back to the manual install steps and share your platform details if you want to help validate the shell path.
• ChatterboxTTS library not found / model backend import failed: Ensure setup_env.bat completed successfully and inspect the newest installer log.
• The app never opens a window / closes before UI appears: Check the newest logs/app_startup_*.log file. This captures import-time and pre-window startup crashes that would otherwise be hidden by pythonw.exe.
• No audio playback / Media Player Errors: Make sure FFmpeg is correctly installed and its bin directory is in your system's PATH.
• Slow Generation: Generating speech for long texts by stitching multiple chunks will take time. The number of chunks depends on the text length and sentence structure. Experiment with the CFG/Pace and Exaggeration sliders for speech rate.
• Custom repo does not load: Verify that the repo layout matches the selected backend in models.json. Not every Hugging Face repo is a drop-in replacement.
• dicta_onnx not available - Hebrew text processing skipped: This is an optional Hebrew preprocessing warning from the upstream stack. Generation can still work, but Hebrew normalization may be reduced unless the optional dependency is available in the environment.
• Warning: You are sending unauthenticated requests to the HF Hub: Optional. Set a token from HF Token... in the app if you want authenticated downloads and higher rate limits. A Read token is enough.
• Multilingual V3 settings appear ignored: Rebuild the environment after changing dependency sources or deleting .venv. Older installed chatterbox-tts builds can fall back to the package default multilingual loader and ignore explicit V3 T3 selection.

Important Notes on PyTorch Installation & Reproducibility

Click to expand

This project aims for both ease of use and predictable installs. Here's how PyTorch is handled:

1. Dependency Locking (requirements.lock.txt):

   • We use uv and a requirements.lock.txt file to pin the main application dependencies.
   • The Windows setup flow now filters the Torch trio (torch, torchaudio, torchvision) out of the runtime dependency install so they can be managed separately.

2. Hardware-Specific PyTorch Build (install_torch.py):

   • After the base dependencies are installed, setup_env.bat executes python install_torch.py when needed.
   • This specialized script:
     • Detects if you have an NVIDIA GPU and your CUDA version.
     • Installs a PyTorch build suited to your hardware.
     • Verifies that the selected build can actually import and run on the detected device.
     • Falls back when verification fails.

What this means for you:

• Users with NVIDIA GPUs: the installer will attempt to provide a CUDA-accelerated PyTorch automatically.
• Users on CPU-only systems: install_torch.py will install a CPU-only version of PyTorch.
• Users with very new NVIDIA GPUs: the installer may select a newer official CUDA wheel than the upstream chatterbox-tts package pins, because older wheels can lack kernels for the newer GPU architecture.
• macOS / Linux users: the Windows setup flow is currently the maintained path. Manual installation is safer than relying on run.sh for now.

Key takeaway: the main lock file keeps the app dependencies stable, while the installer handles the Torch runtime separately so it can match the user's hardware.

Contributing

Please open an issue or pull request if you want to help improve the app, installer flow, or model compatibility support.

Acknowledgements

• Resemble AI for the open-source Chatterbox TTS model.
• The developers of PySide6, NLTK, PyTorch, and uv.

Contributors ✨

Thanks goes to these wonderful people:

lowkeytea 💻

This project follows the all-contributors specification. Contributions of any kind welcome!