Local Development¶

Setting up WakeBuilder for local development and personal use.

Quick Start¶

The fastest way to get started:

# Clone the repository
git clone https://github.com/XableTech/WakeBuilder.git
cd WakeBuilder

# Run the interactive setup
python run.py

Manual Setup¶

For more control over the setup process:

1. Create Virtual Environment¶

uv venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

2. Install Dependencies¶

uv sync

pip install -e .

3. Install PyTorch with CUDA (Optional)¶

For GPU acceleration:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

Replace cu128 with your CUDA version.

4. Download TTS Models¶

python scripts/download_voices.py

This downloads ~5GB of Piper TTS voice models.

5. Start the Server¶

uvicorn src.wakebuilder.backend.main:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser.

Server Options¶

Command Line Options¶

uvicorn src.wakebuilder.backend.main:app \
    --host 0.0.0.0 \
    --port 8000 \
    --reload \
    --log-level info

Using run.py¶

python run.py --run --port 8080

Development Workflow¶

Code Changes¶

With --reload enabled, the server automatically restarts when you modify:

• Python files in src/
• Configuration files

Running Tests¶

# All tests
pytest

# Specific test file
pytest tests/test_training.py

# With coverage
pytest --cov=src/wakebuilder

Code Quality¶

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

Directory Setup¶

WakeBuilder creates these directories on first run:

WakeBuilder/
├── models/
│   ├── default/      # Pre-trained models
│   └── custom/       # Your trained models
├── data/
│   ├── negative/     # UNAC dataset
│   └── cache/        # Pre-processed chunks
├── recordings/       # Temporary recordings
└── tts_voices/       # Piper TTS models

GPU Configuration¶

Checking GPU Availability¶

import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"GPU: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'None'}")

Selecting GPU¶

# Use specific GPU
CUDA_VISIBLE_DEVICES=0 python run.py

# Use CPU only
CUDA_VISIBLE_DEVICES=-1 python run.py

Troubleshooting¶

Server Issues¶

Training Issues¶

Audio Issues¶

Recommended Development Tools¶