How to Build Voicebox from Source: Complete Setup Guide

Building Voicebox from source requires running just setup to install Python, Node, and Rust dependencies, followed by just build to compile the FastAPI backend and Tauri desktop application.

Voicebox is a local-first voice synthesis studio developed by Jamie Pine that combines a Tauri-based desktop UI with a Python FastAPI backend. Building it from source allows you to customize TTS engines like Qwen3-TTS, LuxTTS, and Chatterbox while keeping all voice data private on your machine.

Prerequisites

Before building Voicebox, ensure you have the following installed:

• Rust toolchain for the Tauri desktop framework
• Python 3.x for the FastAPI backend
• Bun or Node.js for the React frontend
• Just (command runner) to orchestrate the build process

Voicebox uses a Justfile located at the repository root to manage all setup and build tasks, eliminating the need to run individual commands manually.

Setting Up the Development Environment

The justfile at the repository root automates environment creation. The core command handles Python virtual environments, JavaScript dependencies, and Rust toolchain verification.

Run the setup command:

just setup

This command is defined at lines 25-27 of the justfile【/cache/repos/github.com/jamiepine/voicebox/main/justfile#L25-L27】. It executes setup-python and setup-js targets in sequence.

Python Virtual Environment

The setup process automatically creates a Python virtual environment if one does not exist. The justfile checks for the venv at lines 94-100 and prompts you to run just setup if dependencies are missing【/cache/repos/github.com/jamiepine/voicebox/main/justfile#L94-L100】.

The backend uses SQLite for persistence and PyTorch-based models for transcription and synthesis.

JavaScript and Bun Dependencies

The setup-js target installs Node dependencies using bun install and prepares the Tauri side-car by running bun run setup:dev at lines 410-411 of the justfile【/cache/repos/github.com/jamiepine/voicebox/main/justfile#L410-L411】.

This installs the Vite, React, and Tailwind CSS packages required for the frontend SPA that runs inside the Tauri window.

Building Voicebox from Source

Once dependencies are installed, compile the production binaries using build targets defined in the justfile.

For a standard CPU build:

just build

For Windows with CUDA GPU acceleration:

just build-local

These commands are documented at lines 276-277 of the README【/cache/repos/github.com/jamiepine/voicebox/main/README.md#L276-L277】.

The just build command compiles the FastAPI server into a standalone executable using PyInstaller and bundles the Tauri desktop application. The just build-local variant includes CUDA-enabled PyTorch binaries for GPU acceleration on Windows.

CPU vs GPU Builds

• just build: Creates CPU-only binaries suitable for any platform (macOS, Windows, Linux). The FastAPI backend runs as a side-car process to the Tauri UI.
• just build-local: Specifically for Windows systems with NVIDIA GPUs. Bundles CUDA libraries for accelerated inference with TTS engines like Qwen3-TTS and LuxTTS.

Running the Application

After compilation completes, you can launch Voicebox in two modes: as a desktop application or as a standalone API server.

Desktop Mode

Run the compiled Tauri application:

./target/release/voicebox

The path varies by platform:

• macOS: target/release/voicebox or target/release/bundle/macos/Voicebox.app
• Windows: target/release/voicebox.exe
• Linux: target/release/voicebox

The desktop UI communicates with the FastAPI backend over HTTP at http://localhost:17493 by default.

API-Only Mode

To run just the backend server without the desktop UI:

python -m backend.main --host 0.0.0.0 --port 17493

The FastAPI application is created by the create_app() function in backend/app.py at lines 69-82【/cache/repos/github.com/jamiepine/voicebox/main/backend/app.py#L69-L82】. This factory function configures CORS, mounts the frontend static files (if present), registers API routers from backend/routes/__init__.py, and attaches startup/shutdown lifecycle events.

Testing the API

Verify your build by generating speech via the REST API. The server exposes endpoints for voice synthesis, profile management, and model listing.

Generate speech using curl:

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

This example appears at lines 203-210 of the README【/cache/repos/github.com/jamiepine/voicebox/main/README.md#L203-L210】.

Key endpoints include:

• GET /profiles – List available voice profiles
• POST /profiles – Create new voice profiles
• GET /models – List loaded TTS models (Qwen3-TTS, LuxTTS, Chatterbox, HumeAI TADA)

Interactive API documentation is available at http://localhost:17493/docs when the server is running.

Summary

• Building Voicebox from source requires the just command runner, Rust, Python, and Bun/Node.js installed on your system.
• Run just setup to create the Python virtual environment and install JavaScript dependencies (as defined in justfile lines 25-27).
• Execute just build for CPU-only binaries or just build-local for Windows CUDA support.
• The FastAPI backend in backend/app.py (lines 69-82) handles TTS orchestration and serves the React frontend.
• Launch the desktop app from ./target/release/voicebox or run the backend directly via python -m backend.main.

Frequently Asked Questions

Do I need a GPU to build and run Voicebox?

No. Voicebox supports CPU-only inference, though a CUDA-capable NVIDIA GPU significantly improves performance for real-time voice cloning. Use just build for CPU-only mode or just build-local on Windows to include GPU acceleration.

What is the purpose of the justfile in Voicebox?

The justfile serves as the build orchestration layer for the entire project. It automates Python virtual environment creation (lines 94-100), JavaScript dependency installation (lines 410-411), and the compilation of both the FastAPI backend and Tauri desktop application.

How does the Tauri UI communicate with the Python backend?

The Tauri desktop application runs the FastAPI server as a side-car process. The React frontend (built with Vite and served from web/src/main.tsx) communicates via HTTP requests to localhost:17493, where the Python backend handles TTS generation, audio processing via Pedalboard, and SQLite persistence.

Can I run Voicebox as a server without the desktop UI?

Yes. After building from source, run python -m backend.main --host 0.0.0.0 --port 17493 to start only the FastAPI server. This mode is useful for deploying Voicebox in Docker containers or running it on headless servers while accessing the web interface from another machine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}