---
title: "Development Setup"
description: "Set up your local development environment for Voicebox"
---

## Quick Setup (Recommended)

Get started in two commands:

```bash
# Clone and enter the repository
git clone https://github.com/jamiepine/voicebox.git
cd voicebox

# Setup everything (Python venv, JS deps, dev sidecar)
just setup

# Start development (backend + desktop app)
just dev
```

The `just dev` command automatically starts the Python backend (if not already running) and launches the Tauri desktop app.

## Prerequisites

Ensure you have these installed:

<Cards>
  <Card title="Bun" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="m7.5 4.27 9 5.15"/><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></svg>}>
    [Download Bun](https://bun.sh)
    ```bash
    curl -fsSL https://bun.sh/install | bash
    ```
  </Card>
  <Card title="Python 3.11+" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
    [Download Python](https://python.org)
    ```bash
    python --version
    ```
  </Card>
  <Card title="Rust" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="m6 9 6 6 6-6"/></svg>}>
    [Install Rust](https://rustup.rs)
    ```bash
    rustc --version
    ```
  </Card>
  <Card title="Just" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M4 7V4h3"/><path d="M7 4h14v6h-2V6H7V4Z"/><path d="M4 10v10h16V10H4Z"/></svg>}>
    [Install Just](https://github.com/casey/just)
    ```bash
    brew install just  # macOS
    cargo install just # Linux/Windows
    ```
  </Card>
</Cards>

<Callout type="info">
  Just works on macOS, Linux, and Windows.
</Callout>

## Just Commands

Run `just --list` to see all available commands:

| Command | Description |
|---------|-------------|
| `just setup` | Full setup (Python venv + JS deps) |
| `just dev` | Start backend + desktop app |
| `just dev-web` | Start backend + web app (no Tauri) |
| `just dev-backend` | Start backend only |
| `just dev-frontend` | Start desktop app only (backend must be running) |
| `just build` | Build desktop app for production |
| `just build-web` | Build web app for production |
| `just check` | Run all checks (JS + Python lint + format) |
| `just fix` | Fix lint + format issues |
| `just test` | Run Python tests |
| `just db-init` | Initialize SQLite database |
| `just db-reset` | Reset database (delete + reinit) |
| `just clean` | Clean build artifacts |
| `just clean-all` | Nuclear clean (includes node_modules) |

## Project Structure

<Files>
  <Folder name="voicebox" defaultOpen>
    <Folder name="app">
      <Folder name="src">
        <File name="components/" />
        <File name="lib/" />
        <File name="hooks/" />
      </Folder>
    </Folder>
    <Folder name="backend">
      <File name="app.py" />
      <File name="main.py" />
      <File name="config.py" />
      <File name="models.py" />
      <File name="server.py" />
      <Folder name="routes">
        <File name="..." />
      </Folder>
      <Folder name="services">
        <File name="..." />
      </Folder>
      <Folder name="backends">
        <File name="..." />
      </Folder>
      <Folder name="database">
        <File name="..." />
      </Folder>
      <Folder name="utils">
        <File name="..." />
      </Folder>
    </Folder>
    <Folder name="tauri">
      <Folder name="src-tauri" />
    </Folder>
    <Folder name="web" />
    <Folder name="scripts" />
  </Folder>
</Files>

### Request Flow

HTTP request → **routes/** (validate input) → **services/** (business logic) → **backends/** (TTS/STT inference) → **utils/** (audio processing)

### Key Modules

- **app.py** — FastAPI app factory, CORS, lifecycle events
- **main.py** — Entry point (imports app, runs uvicorn)
- **server.py** — Tauri sidecar launcher, parent-pid watchdog
- **services/generation.py** — Single function handling all generation modes
- **backends/** — TTS/STT engine implementations (MLX, PyTorch, etc.)

## Model Downloads

Models are automatically downloaded from HuggingFace Hub on first use:

- **Whisper** (transcription): Auto-downloads on first transcription
- **Qwen3-TTS** (voice cloning): Auto-downloads on first generation (~2-4GB)

<Callout type="warn">
  First-time usage will be slower due to model downloads, but subsequent runs will use cached models.
</Callout>

## Generate OpenAPI Client

After starting the backend server, generate the TypeScript API client:

```bash
just generate-api
```

This downloads the OpenAPI schema and generates the TypeScript client in `app/src/lib/api/`

## Manual Setup (Advanced)

If you prefer not to use Just, follow these manual steps:

### 1. Install JavaScript Dependencies

```bash
bun install
```

This installs dependencies for:
- `app/` - Shared React frontend
- `tauri/` - Tauri desktop wrapper
- `web/` - Web deployment wrapper

### 2. Set Up Python Backend

```bash
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

# Install Python dependencies
pip install -r requirements.txt

# Apple Silicon: install MLX dependencies
pip install -r requirements-mlx.txt

# Install Qwen3-TTS
pip install git+https://github.com/QwenLM/Qwen3-TTS.git
```

### 3. Start Development

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

In a new terminal, start the desktop app:
```bash
cd tauri
bun run tauri dev
```

## Next Steps

<Cards>
  <Card title="Architecture" href="/development/architecture">
    Understand the system architecture
  </Card>
  <Card title="Contributing" href="/development/contributing">
    Read the contribution guidelines
  </Card>
  <Card title="Building" href="/development/building">
    Learn how to build production releases
  </Card>
  <Card title="API Reference" href="/api-reference">
    Explore the REST API
  </Card>
</Cards>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Backend won't start">
    - Check Python version (must be 3.11+)
    - Ensure virtual environment is activated: `source backend/venv/bin/activate`
    - Verify all dependencies are installed: `pip install -r requirements.txt`
    - Check if port 17493 is available
  </Accordion>

  <Accordion title="Tauri build fails">
    - Ensure Rust is installed: `rustc --version`
    - Clean the build: `cd tauri/src-tauri && cargo clean`
    - Try rebuilding: `just dev`
  </Accordion>

  <Accordion title="OpenAPI client generation fails">
    - Ensure backend is running: `curl http://localhost:17493/openapi.json`
    - Check network connectivity
    - Verify the backend is accessible at localhost:17493
  </Accordion>
</AccordionGroup>

See the full [Troubleshooting Guide](/overview/troubleshooting) for more issues and solutions.
