# How to Build Voicebox from Source: Complete Setup Guide

> Build Voicebox from source with this complete setup guide. Learn to install dependencies and compile the backend and desktop app using simple commands.

- Repository: [Jamie Pine/voicebox](https://github.com/jamiepine/voicebox)
- Tags: how-to-guide
- Published: 2026-04-14

---

**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:

```bash
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:

```bash
just build

```

For Windows with CUDA GPU acceleration:

```bash
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:

```bash
./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:

```bash
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`](https://github.com/jamiepine/voicebox/blob/main/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`](https://github.com/jamiepine/voicebox/blob/main/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:

```bash
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`](https://github.com/jamiepine/voicebox/blob/main/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`](https://github.com/jamiepine/voicebox/blob/main/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.