voicebox/docs/developer/building.mdx

---
title: "Building"
description: "Build Voicebox for production"
---

## Overview

Voicebox uses a multi-step build process to create platform-specific installers.

## Quick Build

```bash
# Build for your current platform (automatically builds server binary first)
make build

# Or manually
bun run build
```

This automatically:
1. Builds the Python server binary (`bun run build:server`)
2. Builds the Tauri app (`cd tauri && bun run tauri build`)

## Build Process

The build process consists of two steps, but `bun run build` handles both automatically:

### 1. Server Binary Build (Automatic)

The Python backend is compiled into a standalone executable using PyInstaller. This happens automatically when you run `bun run build`.

**Platform-specific binaries:**
- macOS (Apple Silicon): `voicebox-server-aarch64-apple-darwin` (includes MLX backend)
- macOS (Intel): `voicebox-server-x86_64-apple-darwin` (PyTorch backend)
- Windows: `voicebox-server-x86_64-pc-windows-msvc.exe` (PyTorch backend)
- Linux: `voicebox-server-x86_64-unknown-linux-gnu` (PyTorch backend)

<Note>
  The build script automatically detects your platform and includes the appropriate backend (MLX for Apple Silicon, PyTorch for others).
</Note>

**Manual build (if needed):**
```bash
bun run build:server
```

### 2. Tauri App Build (Automatic)

The Tauri app build is also handled automatically, which:
1. Builds the React frontend (Vite)
2. Compiles the Rust backend
3. Bundles the server binary as a sidecar
4. Creates platform-specific installers

**Manual build (if needed):**
```bash
cd tauri && bun run tauri build
```

### 3. Output

Installers are created in `tauri/src-tauri/target/release/bundle/`:

**macOS:**
- `dmg/` - Disk image installer
- `macos/` - App bundle

**Windows:**
- `msi/` - MSI installer
- `nsis/` - NSIS installer

**Linux:**
- `deb/` - Debian package
- `appimage/` - AppImage

## Advanced Options

### Building for Specific Platform

```bash
# Build for macOS (Apple Silicon)
bun run tauri build -- --target aarch64-apple-darwin

# Build for macOS (Intel)
bun run tauri build -- --target x86_64-apple-darwin

# Build for Windows
bun run tauri build -- --target x86_64-pc-windows-msvc

# Build for Linux
bun run tauri build -- --target x86_64-unknown-linux-gnu
```

### Using Local Qwen3-TTS

If you're developing Qwen3-TTS locally:

```bash
export QWEN_TTS_PATH=~/path/to/Qwen3-TTS
bun run build:server  # Build server binary only
# or
bun run build  # Build everything
```

This makes PyInstaller use your local version instead of the pip package.

### Debug Build

```bash
cd tauri
bun run tauri build --debug
```

Creates a debug build with symbols and logging.

## Build Configuration

### Tauri Config

Edit `tauri/src-tauri/tauri.conf.json`:

```json
{
  "bundle": {
    "identifier": "com.voicebox.app",
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ]
  }
}
```

### Sidecar Configuration

The Python server is bundled as a sidecar:

```json
{
  "tauri": {
    "bundle": {
      "externalBin": [
        "binaries/voicebox-server"
      ]
    }
  }
}
```

## Code Signing

### macOS

To sign the app for distribution:

```bash
# Set signing identity
export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name"

# Build with signing
bun run tauri build
```

For notarization:

```bash
# Set credentials
export APPLE_ID="[email protected]"
export APPLE_PASSWORD="app-specific-password"

# Build and notarize
bun run tauri build
```

### Windows

For Windows code signing:

```bash
# Set certificate
export WINDOWS_CERTIFICATE_PATH="/path/to/cert.pfx"
export WINDOWS_CERTIFICATE_PASSWORD="password"

# Build with signing
bun run tauri build
```

## Release Process

The full release process is automated:

```bash
# 1. Bump version
bumpversion patch  # or minor/major

# 2. Build all platforms (CI/CD handles this)
git push --tags

# 3. GitHub Actions creates releases
```

See [CONTRIBUTING.md](/development/contributing) for the full release workflow.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server Binary Build Fails">
    **Common issues:**
    - Missing Python dependencies: `pip install -r requirements.txt`
    - PyInstaller not found: `pip install pyinstaller`
    - Qwen3-TTS not installed: `pip install git+https://github.com/QwenLM/Qwen3-TTS.git`

    **Solution:**
    ```bash
    cd backend
    source venv/bin/activate
    pip install -r requirements.txt
    pip install pyinstaller
    ```
  </Accordion>

  <Accordion title="Tauri Build Fails">
    **Common issues:**
    - Rust not installed: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
    - Server binary missing: Usually auto-built, but can run manually: `./scripts/build-server.sh`
    - Node modules outdated: `bun install`

    **Solution:**
    ```bash
    # Clean and rebuild
    cd tauri/src-tauri
    cargo clean
    cd ../..
    bun run build  # Automatically builds server binary first
    ```
  </Accordion>

  <Accordion title="App Won't Launch After Build">
    **Check:**
    - Server binary has execute permissions
    - All dependencies are bundled
    - Check logs in the app's data directory

    **macOS:**
    ```bash
    tail -f ~/Library/Application\ Support/com.voicebox.app/logs/server.log
    ```

    **Windows:**
    ```bash
    type %APPDATA%\com.voicebox.app\logs\server.log
    ```
  </Accordion>
</AccordionGroup>

## CI/CD

GitHub Actions automatically builds releases when tags are pushed:

```yaml
# .github/workflows/release.yml
on:
  push:
    tags:
      - 'v*'
```

See the [repository](https://github.com/jamiepine/voicebox) for the full CI/CD configuration.