### Voicebox Quick Start Setup

Source: https://github.com/jamiepine/voicebox/blob/main/README.md

Clone the repository, set up the Python virtual environment, and install dependencies.

```bash
git clone https://github.com/jamiepine/voicebox.git
cd voicebox

just setup   # creates Python venv, installs all deps
just dev     # starts backend + desktop app
```

--------------------------------

### Clone and Setup Voicebox

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Clone the repository and run the setup command to install all dependencies and configure the development environment.

```bash
git clone https://github.com/jamiepine/voicebox.git
cd voicebox
just setup
just dev
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/README.md

Use these commands from the `docs/` directory to install dependencies and start the local development server for the documentation.

```bash
bun install
bun run dev
```

--------------------------------

### Clone Repository and Setup Development Environment

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Clones the Voicebox repository and sets up the development environment using the 'just' command. This includes creating a virtual environment and installing Python and JavaScript dependencies.

```bash
git clone https://github.com/YOUR_USERNAME/voicebox.git
cd voicebox

just setup   # creates venv, installs Python + JS deps
```

--------------------------------

### Run Development Server

Source: https://github.com/jamiepine/voicebox/blob/main/docs/README.md

Use this command to start the Next.js development server for the fumadocs-ui-template project. Ensure you have Bun installed.

```bash
bun run dev
```

--------------------------------

### Run Just Setup Commands

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Execute specific setup tasks using Just. `just setup` performs a full setup, while `just setup-python` and `just setup-js` handle Python dependencies and JavaScript dependencies separately.

```bash
just setup
```

```bash
just setup-python
```

```bash
just setup-js
```

--------------------------------

### Run Just Development Commands

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Start the development server and application. `just dev` starts the backend and Tauri app, `just dev-web` starts the backend and web app, `just dev-backend` starts only the backend, and `just dev-frontend` starts only the Tauri app. `just kill` stops all development processes.

```bash
just dev
```

```bash
just dev-web
```

```bash
just dev-backend
```

```bash
just dev-frontend
```

```bash
just kill
```

--------------------------------

### Start Development Server and Desktop App

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Starts the backend and desktop application simultaneously for development. If a backend is already running, it will only start the frontend.

```bash
just dev     # starts backend + desktop app
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/jamiepine/voicebox/blob/main/landing/README.md

Navigate to the landing directory and run this command to install project dependencies using Bun.

```bash
cd landing
bun install
```

--------------------------------

### RunPod Deployment Notes

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/remote-mode.mdx

Guide for deploying Voicebox on RunPod. Deploy a pod with CUDA support, install the Voicebox backend, and expose the necessary port.

```bash
# Deploy a pod with CUDA support
# Install Voicebox backend
# Expose port 17493
```

--------------------------------

### Install WebP and FFmpeg

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Installs the `webp` and `ffmpeg` command-line tools, which are required for the asset conversion script.

```bash
brew install webp ffmpeg
```

--------------------------------

### Install Voicebox Backend Dependencies

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/remote-mode.mdx

Clone the Voicebox repository and install necessary Python dependencies for the backend. Use `--no-deps` for specific packages with incompatible transitive pins and install Qwen3-TTS from source.

```bash
git clone https://github.com/jamiepine/voicebox.git
cd voicebox/backend
pip install -r requirements.txt
pip install --no-deps chatterbox-tts
pip install --no-deps hume-tada
pip install git+https://github.com/QwenLM/Qwen3-TTS.git
```

--------------------------------

### Install Just (macOS/Linux/Windows)

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Install the Just command runner. Use Homebrew for macOS, or Cargo for Linux/Windows.

```bash
brew install just  # macOS
```

```bash
cargo install just # Linux/Windows
```

--------------------------------

### Docker Compose for Voicebox

Source: https://github.com/jamiepine/voicebox/blob/main/README.md

Use this command to start Voicebox using Docker Compose. Ensure Docker is installed and configured.

```bash
docker compose up
```

--------------------------------

### Start Production Server with Bun

Source: https://github.com/jamiepine/voicebox/blob/main/landing/README.md

Run the production build of the application using Bun.

```bash
bun run start
```

--------------------------------

### Start Development Server

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Starts the FastAPI backend server with hot-reloading enabled on port 17493. Ensure the virtual environment is activated.

```bash
cd backend
source venv/bin/activate
uvicorn main:app --reload --port 17493
```

--------------------------------

### AWS EC2 Deployment Notes

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/remote-mode.mdx

Instructions for deploying Voicebox on AWS EC2. Launch a GPU instance, install dependencies, and start the server with the appropriate host setting.

```bash
# Launch a GPU instance (e.g., g4dn.xlarge)
# Install dependencies
# Start server with --host 0.0.0.0
```

--------------------------------

### Install Model Package

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/tts-engines.mdx

Installs a model package using pip. It first attempts a standard installation and then shows how to install with specific dependency versions or without dependencies if conflicts arise.

```bash
pip install model-package
```

```bash
pip install model-package torch==2.10 transformers==4.57.3 numpy>=1.26
```

```bash
pip install --no-deps model-package
```

--------------------------------

### Reinstall Backend Dependencies

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/troubleshooting.mdx

Reinstall all backend dependencies using the 'just setup' command or manually via pip. This is a common solution for import errors or module not found issues when starting the backend in dev mode.

```bash
just setup
```

```bash
cd backend
pip install -r requirements.txt
pip install --no-deps chatterbox-tts
pip install --no-deps hume-tada
pip install git+https://github.com/QwenLM/Qwen3-TTS.git
```

--------------------------------

### Install Dependencies

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/building.mdx

Ensure all project dependencies are installed before building. This command should be run within an activated Python virtual environment.

```bash
pip install -r requirements.txt
```

--------------------------------

### Development Build Commands

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/architecture.mdx

Use these commands to start the backend and Tauri app for development. Ensure the backend is running if only starting the frontend.

```bash
just dev              # Starts backend + Tauri app
just dev-web          # Starts backend + web app (no Tauri)
just dev-backend      # Backend only
just dev-frontend     # Tauri app only (backend must be running)
```

--------------------------------

### Install flash-attn on Windows using Community Wheels

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/troubleshooting.mdx

Install flash-attn on Windows by downloading a prebuilt wheel that matches your CUDA, PyTorch, and Python versions. This is an alternative to official builds.

```bash
pip install https://github.com/kingbri1/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu128torch2.8.0cxx11abiFALSE-cp312-cp312-win_amd64.whl
```

--------------------------------

### Run Just Build Commands

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Build the application artifacts. `just build` creates a CPU server binary and Tauri installer. `just build-local` on Windows builds CPU, CUDA server binaries, and Tauri installer. Other commands build specific components like server binaries or the Tauri app.

```bash
just build
```

```bash
just build-local
```

```bash
just build-server
```

```bash
just build-server-cuda
```

```bash
just build-tauri
```

```bash
just build-web
```

--------------------------------

### Install Bun

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Installs Bun, a fast JavaScript runtime and package manager, using a curl command.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Install PyInstaller

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/building.mdx

PyInstaller is required for packaging the application. Install it using pip.

```bash
pip install pyinstaller
```

--------------------------------

### Install JavaScript Dependencies

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Installs dependencies for the React frontend, Tauri desktop wrapper, and web deployment wrapper using Bun.

```bash
bun install
```

--------------------------------

### Install Python Backend Dependencies

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Installs necessary Python packages, including specific versions for MLX, Chatterbox-TTS, HumeAI TADA, and Qwen3-TTS. Also installs development tools like PyInstaller and linters.

```bash
pip install -r requirements.txt
pip install -r requirements-mlx.txt
pip install --no-deps chatterbox-tts
pip install --no-deps hume-tada
pip install git+https://github.com/QwenLM/Qwen3-TTS.git
pip install pyinstaller ruff pytest pytest-asyncio
```

--------------------------------

### Install Normal PyPI Packages

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/tts-engines.mdx

For standard Python packages, add them to the `backend/requirements.txt` file with their version specifiers.

```bash
some-model-package>=1.0.0
```

--------------------------------

### Python Docstring: Google Style Example

Source: https://github.com/jamiepine/voicebox/blob/main/backend/STYLE_GUIDE.md

Provides an example of a function documented using the Google style, including sections for arguments, return values, and raised exceptions.

```python
def combine_voice_prompts(
    profile_dir: Path,
    *,
    target_sr: int = 24000,
) -> tuple[np.ndarray, int]:
    """Load and concatenate all voice prompt files for a profile.

    Reads .wav/.mp3/.flac files from the profile directory, resamples to
    the target sample rate, normalizes, and concatenates into a single array.

    Args:
        profile_dir: Path to the voice profile directory containing audio files.
        target_sr: Target sample rate for the output. Defaults to 24000.

    Returns:
        Tuple of (concatenated audio array, sample rate).

    Raises:
        FileNotFoundError: If profile_dir does not exist.
        ValueError: If no valid audio files are found.
    """
```

--------------------------------

### Install flash-attn on Linux

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/troubleshooting.mdx

Install the flash-attn library on Linux using pip. This is an optional step for faster inference and requires a matching CUDA toolkit.

```bash
pip install flash-attn --no-build-isolation
```

--------------------------------

### Install Voicebox on macOS (Intel)

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/installation.mdx

Extract the downloaded archive and move the Voicebox application to the Applications directory. This is for Intel-based Macs.

```bash
# Extract the archive
tar -xzf voicebox_x64.app.tar.gz

# Move to Applications
mv Voicebox.app /Applications/
```

--------------------------------

### Set Up Python Backend - Virtual Environment

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Creates and activates a Python virtual environment for the backend. Use the appropriate command for your operating system.

```bash
python -m venv venv
source venv/bin/activate
```

```bash
venv\Scripts\activate
```

--------------------------------

### List Profiles with Voicebox API

Source: https://github.com/jamiepine/voicebox/blob/main/backend/README.md

Example using curl to send a GET request to the /profiles endpoint to retrieve a list of available voice profiles.

```bash
# List profiles
curl http://localhost:17493/profiles
```

--------------------------------

### Dockerfile for Voicebox with AMD ROCm Support (Experimental)

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/DOCKER_DEPLOYMENT.md

A Dockerfile for experimental AMD GPU support using ROCm. It starts from a ROCm base image and installs Python, dependencies, and the application.

```dockerfile
FROM rocm/dev-ubuntu-22.04:6.0

# Install Python
RUN apt-get update && apt-get install -y \
    python3.11 python3-pip git ffmpeg && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

```

--------------------------------

### Vast.ai Deployment Notes

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/remote-mode.mdx

Steps for deploying Voicebox on Vast.ai. Rent a GPU instance, SSH into it, clone the repository, and start the server.

```bash
# Rent a GPU instance
# SSH in and clone repo
# Start server
```

--------------------------------

### Build Project with Bun

Source: https://github.com/jamiepine/voicebox/blob/main/landing/README.md

Use this command to build the project for production using Bun.

```bash
bun run build
```

--------------------------------

### Check Rust Installation

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Checks if Rust is installed on the system. Rust is required for the Tauri desktop app and is typically installed automatically by the Tauri CLI.

```bash
rustc --version  # Check if installed
```

--------------------------------

### Build and Run Voicebox from Source

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/DOCKER_DEPLOYMENT.md

Commands to build a Docker image from the basic Dockerfile and then run it, mapping a local data directory.

```bash
docker build -t voicebox .
docker run -p 8000:8000 -v $(pwd)/data:/app/data voicebox
```

--------------------------------

### Production Build Commands

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/architecture.mdx

Commands for building production-ready binaries and installers. Includes options for CPU and CUDA binaries, and local builds.

```bash
just build            # CPU server binary + Tauri installer
just build-local      # CPU + CUDA binaries + Tauri installer (Windows)
just build-server     # Server binary only
just build-tauri      # Tauri app only
```

--------------------------------

### Add Profile Sample

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/voice-profiles.mdx

Validates and copies an audio sample to the profile directory, then creates a database record. Ensure audio is valid before calling.

```python
async def add_profile_sample(
    profile_id: str,
    audio_path: str,
    reference_text: str,
    db: Session,
) -> ProfileSampleResponse:
    # 1. Validate audio (duration, format, quality)
    is_valid, error_msg = validate_reference_audio(audio_path)
    if not is_valid:
        raise ValueError(f"Invalid reference audio: {error_msg}")
    
    # 2. Copy to profile directory
    sample_id = str(uuid.uuid4())
    dest_path = profile_dir / f"{sample_id}.wav"
    audio, sr = load_audio(audio_path)
    save_audio(audio, str(dest_path), sr)
    
    # 3. Create database record
    db_sample = DBProfileSample(
        id=sample_id,
        profile_id=profile_id,
        audio_path=str(dest_path),
        reference_text=reference_text,
    )
    db.add(db_sample)
    db.commit()
```

--------------------------------

### Good Instruct Prompts for Qwen Engines

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/tts-generation.mdx

Examples of natural-language delivery controls for engines that support instruct mode. Other engines will ignore this field.

```text
# Good instruct prompts:
"warm and conversational, slight smile"
"whisper, intimate and close"
"authoritative, broadcast quality"
```

--------------------------------

### Verify CUDA Installation

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/troubleshooting.mdx

Check if the NVIDIA CUDA toolkit is installed and recognized by the system. This command should display information about your GPU.

```bash
nvidia-smi
```

--------------------------------

### Configure Voicebox with Environment Variables

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/DOCKER_DEPLOYMENT.md

Example command to run Voicebox with various environment variables set to configure TTS and Whisper modes, API keys, GPU memory usage, and logging level.

```bash
docker run -e TTS_MODE=local \
           -e WHISPER_MODE=openai-api \
           -e OPENAI_API_KEY=sk-...
           -e GPU_MEMORY_FRACTION=0.8 \
           -e LOG_LEVEL=info \
           -p 8000:8000 voicebox
```

--------------------------------

### Get Story Details API

Source: https://context7.com/jamiepine/voicebox/llms.txt

Retrieve a specific story, including all its items, by sending a GET request to /stories/{story_id}.

```bash
# Get story with all items
curl http://127.0.0.1:17493/stories/story-abc123
```

--------------------------------

### Start Tauri Development App

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Launches the Tauri desktop application in development mode. This should be run in a separate terminal after the backend has started.

```bash
cd tauri
bun run tauri dev
```

--------------------------------

### Build and Deploy Voicebox to Google Cloud Run (CPU-only)

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/DOCKER_DEPLOYMENT.md

Builds a Docker image for Voicebox, pushes it to Google Container Registry, and deploys it to Cloud Run. Configured for CPU and memory limits.

```bash
# Build and push
docker build -t gcr.io/your-project/voicebox .
docker push gcr.io/your-project/voicebox

# Deploy to Cloud Run
gcloud run deploy voicebox \
  --image gcr.io/your-project/voicebox \
  --platform managed \
  --region us-central1 \
  --memory 4Gi \
  --cpu 2 \
  --port 8000
```

--------------------------------

### Install Voicebox MCP Server via Stdio Shim

Source: https://github.com/jamiepine/voicebox/blob/main/backend/mcp_server/README.md

Use this configuration as a fallback when the client does not support HTTP MCP. The `voicebox-mcp` binary must be available.

```json
{
  "mcpServers": {
    "voicebox": {
      "command": "/Applications/Voicebox.app/Contents/MacOS/voicebox-mcp",
      "env": { "VOICEBOX_CLIENT_ID": "claude-code" }
    }
  }
}
```

--------------------------------

### Voicebox Local Build Commands

Source: https://github.com/jamiepine/voicebox/blob/main/README.md

Commands to build the CPU server binary and Tauri app, with a specific option for Windows with CUDA support.

```bash
just build          # Build CPU server binary + Tauri app
just build-local    # (Windows) Build CPU + CUDA server binaries + Tauri app
```

--------------------------------

### Using Custom Package Indexes

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/tts-engines.mdx

When using custom package indexes, such as for C extensions, use `--find-links` to point to the index URL and then list the package.

```text
# Custom package indexes (C extensions with platform-specific wheels)
--find-links https://k2-fsa.github.io/icefall/piper_phonemize.html
piper-phonemize>=1.2.0
```

--------------------------------

### Install Docker and NVIDIA Docker on Amazon Linux 2

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/DOCKER_DEPLOYMENT.md

Installs Docker and the NVIDIA Container Toolkit on Amazon Linux 2. Ensure your instance has GPU support.

```bash
# Amazon Linux 2
yum install -y docker
systemctl start docker
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
systemctl restart docker
```

--------------------------------

### Run Just Database Commands

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Manage the SQLite database. `just db-init` initializes the database, and `just db-reset` deletes and reinitializes it.

```bash
just db-init
```

```bash
just db-reset
```

--------------------------------

### Install PyTorch Nightly for Bleeding-Edge GPUs

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/overview/gpu-acceleration.mdx

Install the PyTorch nightly build with force-reinstall for bleeding-edge GPUs that are newer than current Blackwell architectures. This ensures broader architecture support until stable PyTorch versions catch up.

```bash
pip install torch --index-url https://download.pytorch.org/whl/nightly/cu128 --force-reinstall
```

--------------------------------

### List Available Just Commands

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Display all available commands in the Justfile.

```bash
just --list
```

--------------------------------

### GET /

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/api-reference/general/root__get.mdx

Root endpoint of the Voicebox API.

```APIDOC
## GET /

### Description
Root endpoint.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **message** (string) - A welcome message or status indicator.
```

--------------------------------

### Building Tauri Desktop App

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/building.mdx

Navigate to the `tauri` directory and run `bun run tauri build` to compile the Tauri desktop application. This command triggers Vite to build the frontend, Rust to compile the Tauri wrapper, and bundles the server sidecar binary.

```bash
cd tauri
bun run tauri build
```

--------------------------------

### Install Pinned Dependencies with --no-deps

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/tts-engines.mdx

When a model package has conflicting pinned dependencies (e.g., older torch/numpy), use `pip install --no-deps` and manually list sub-dependencies. This pattern is used for packages like `chatterbox-tts`.

```bash
# In justfile / CI setup:
pip install --no-deps chatterbox-tts
```

--------------------------------

### Building CUDA-Enabled Server Binary

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/building.mdx

To build the CUDA-enabled server binary, navigate to the `backend` directory and execute `build_binary.py` with the `--cuda` flag. This process results in a larger binary compared to the CPU-only version.

```bash
cd backend
python build_binary.py --cuda
```

--------------------------------

### Install and Use bumpversion for Version Management

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Install the bumpversion tool using pip. Use commands like 'bumpversion patch', 'bumpversion minor', or 'bumpversion major' to update version numbers, create commits, and generate tags.

```bash
# Install bumpversion (if not already installed)
pip install bumpversion

# Bump patch version (0.1.0 -> 0.1.1)
bumpversion patch

# Or bump minor version (0.1.0 -> 0.2.0)
bumpversion minor

# Or bump major version (0.1.0 -> 1.0.0)
bumpversion major
```

--------------------------------

### Check Rust Version

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/setup.mdx

Verify that the Rust compiler is installed.

```bash
rustc --version
```

--------------------------------

### Get Aggregate Statistics

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/history.mdx

Retrieves aggregate statistics for generations.

```APIDOC
## GET /history/stats

### Description
Get aggregate statistics.

### Method
GET

### Endpoint
/history/stats
```

--------------------------------

### FastAPI App Initialization

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/MCP_SERVER.md

Migrated app.py to use lifespan for initialization and mounts the FastMCP server at the /mcp endpoint.

```python
app.py
```

--------------------------------

### GET /history/stats

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/api-reference/history/get_stats_history_stats_get.mdx

Retrieves generation statistics for the Voicebox service.

```APIDOC
## GET /history/stats

### Description
Get generation statistics.

### Method
GET

### Endpoint
/history/stats
```

--------------------------------

### Build Shim Binary with Python Script

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/MCP_SERVER.md

Use this Python script to build the stdio shim binary for the Voicebox MCP. Ensure the correct target triple is specified for cross-platform compatibility.

```python
python backend/build_binary.py --shim
```

--------------------------------

### GET /audio/{generation_id}

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/api-reference/generation/get_audio_audio__generation_id__get.mdx

Serve generated audio file.

```APIDOC
## GET /audio/{generation_id}

### Description
Serve generated audio file.

### Method
GET

### Endpoint
/audio/{generation_id}

### Parameters
#### Path Parameters
- **generation_id** (string) - Required - The ID of the audio generation to retrieve.
```

--------------------------------

### Build Voicebox Server with Local Qwen3-TTS Development Version

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Builds the Voicebox server, using a local development version of the Qwen3-TTS library by setting the QWEN_TTS_PATH environment variable. This is useful when actively modifying the Qwen3-TTS library.

```bash
export QWEN_TTS_PATH=~/path/to/your/Qwen3-TTS
just build-server
```

--------------------------------

### Check Python Version

Source: https://github.com/jamiepine/voicebox/blob/main/CONTRIBUTING.md

Verifies that Python 3.11 or higher is installed.

```bash
python --version  # Should be 3.11 or higher
```

--------------------------------

### Deploy Voicebox on DigitalOcean GPU Droplet

Source: https://github.com/jamiepine/voicebox/blob/main/docs/plans/DOCKER_DEPLOYMENT.md

Creates a GPU Droplet on DigitalOcean and deploys Voicebox. Installs Docker and runs the container, exposing port 80.

```bash
# Create droplet via CLI
doctl compute droplet create voicebox \
  --size gpu-h100x1-80gb \
  --image ubuntu-22-04-x64 \
  --region nyc3

# SSH and deploy
ssh root@<droplet-ip>
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
docker run --gpus all -d -p 80:8000 voicebox:cuda
```

--------------------------------

### Get Specific Capture

Source: https://context7.com/jamiepine/voicebox/llms.txt

Fetches details for a specific capture by its ID.

```bash
curl http://127.0.0.1:17493/captures/capture-abc123
```

--------------------------------

### Build Commands for Voicebox

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/building.mdx

Use these `just` commands to build the Voicebox project. `build` compiles both the server and Tauri app, `build-server` targets only the Python server binary, and `build-tauri` focuses on the Tauri desktop application.

```bash
just build          # Build everything (server + Tauri)
just build-server   # Build Python server binary only
just build-tauri    # Build Tauri app only
```

--------------------------------

### Get Generation by ID

Source: https://github.com/jamiepine/voicebox/blob/main/docs/content/docs/developer/history.mdx

Retrieves a specific generation by its unique ID.

```APIDOC
## GET /history/{id}

### Description
Get generation by ID.

### Method
GET

### Endpoint
/history/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the generation.
```