voicebox/SETUP.md

voicebox Setup Guide

Quick start guide for setting up the voicebox development environment.

Prerequisites

• Bun - Fast JavaScript runtime and package manager

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

• Python 3.11+ - For backend development

  python --version  # Should be 3.11 or higher
  

• Rust - For Tauri desktop app (installed automatically by Tauri CLI)

  rustc --version  # Check if installed
  

• Node.js 18+ (optional) - Fallback if Bun is not available

Initial Setup

1. Install Dependencies

# Install all workspace dependencies
bun install

This will install dependencies for:

• app/ - Shared React frontend
• tauri/ - Tauri desktop wrapper
• web/ - Web deployment wrapper

2. Setup Backend

cd backend

# Create virtual environment
python -m venv venv

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

# Install Python dependencies
pip install -r requirements.txt

3. Initialize Database

cd backend
python -c "from database import init_db; init_db()"

This creates the SQLite database at data/voicebox.db.

4. Install Qwen3-TTS (Optional)

The Qwen3-TTS models are automatically downloaded from HuggingFace Hub on first use. However, you need to install the qwen_tts package:

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

Note: Models (~2-4GB) will be automatically downloaded on first generation. This may take a few minutes depending on your internet connection.

Development

Start Backend Server

cd backend
source venv/bin/activate  # Activate venv if not already active
uvicorn main:app --reload --port 8000

Backend will be available at http://localhost:8000

Start Tauri Desktop App

# From project root
bun run dev

Or manually:

cd tauri
bun run tauri dev

This will:

1. Start Vite dev server on port 5173
2. Launch Tauri window pointing to localhost:5173
3. Enable hot reload

Start Web App

# From project root
bun run dev:web

Or manually:

cd web
bun run dev

Web app will be available at http://localhost:5174 (or next available port)

Building

Build Python Server Binary

./scripts/build-server.sh

This creates a platform-specific binary in tauri/src-tauri/binaries/

Build Tauri Desktop App

cd tauri
bun run tauri build

Creates platform-specific installers:

• macOS: .app, .dmg
• Windows: .exe, .msi
• Linux: .deb, .AppImage

Build Web App

cd web
bun run build

Output in web/dist/

Generate OpenAPI Client

After starting the backend server:

./scripts/generate-api.sh

This will:

1. Download OpenAPI schema from backend
2. Generate TypeScript client in app/src/lib/api/

Project Structure

voicebox/
├── app/              # Shared React frontend
├── tauri/            # Tauri desktop wrapper
├── web/              # Web deployment wrapper
├── backend/          # Python FastAPI server
├── scripts/          # Build and utility scripts
├── data/             # User data (gitignored)
└── docs/             # Documentation

Troubleshooting

Backend won't start

• Check Python version: python --version (needs 3.11+)
• Ensure virtual environment is activated
• Install dependencies: pip install -r requirements.txt

Tauri build fails

• Ensure Rust is installed: rustc --version
• Install Tauri CLI: bunx @tauri-apps/cli install
• Check tauri/src-tauri/Cargo.toml for correct dependencies

OpenAPI client generation fails

• Ensure backend is running on port 8000
• Check curl http://localhost:8000/openapi.json returns valid JSON
• Install openapi-typescript-codegen: bun add -d openapi-typescript-codegen

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

First-time usage will be slower due to model downloads, but subsequent runs will use cached models.

Next Steps

1. ✅ TTS model loading implemented in backend/tts.py
2. ✅ API routes implemented in backend/main.py
3. Build React components in app/src/components/
4. Connect frontend to backend via generated API client

See README.md for architecture details and docs/ for detailed documentation.