isolate shutdown unload calls so one failure doesn't block the other

fix startup db session leak on error (rollback + close in finally)
suppress E402 for app.py (AMD env vars must precede torch import)
2026-09-27 06:05:14 -07:00 · 2026-03-16 03:50:28 -07:00 · 2026-03-16 03:49:21 -07:00 · 2026-03-16 03:47:56 -07:00 · 2026-03-16 03:46:58 -07:00 · 2026-03-16 03:44:33 -07:00
97 changed files with 6735 additions and 9409 deletions
@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.2.4
+current_version = 0.2.3
 commit = True
 tag = True
 tag_name = v{new_version}
@@ -49,6 +49,7 @@ logs/
 # Generated files
 app/openapi.json
 tauri/src-tauri/binaries/*
+tauri/src-tauri/gen/Assets.car

 # Temporary
 tmp/
@@ -66,14 +66,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OpenAPI client generator script now documents the local backend port and avoids an unused loop variable warning

 ### Added
- **Makefile** - Comprehensive development workflow automation with commands for setup, development, building, testing, and code quality checks
-  - Includes Python version detection and compatibility warnings
-  - Self-documenting help system with `make help`
-  - Colored output for better readability
-  - Supports parallel development server execution
+- **justfile** - Comprehensive development workflow automation with commands for setup, development, building, testing, and code quality checks
+  - Cross-platform support (macOS, Linux, Windows)
+  - Python version detection and compatibility warnings
+  - Self-documenting help system with `just --list`

 ### Changed
- **README** - Added Makefile reference and updated Quick Start with Makefile-based setup instructions alongside manual setup
+- **README** - Updated Quick Start with justfile-based setup instructions
+
+### Removed
+- **Makefile** - Replaced by justfile (cross-platform, simpler syntax)

 ---

@@ -1,250 +0,0 @@
-# Voicebox Makefile
-# Unix-only (macOS/Linux). Windows users should use WSL.
-
-SHELL := /bin/bash
-.DEFAULT_GOAL := help
-
-# Directories
-BACKEND_DIR := backend
-TAURI_DIR := tauri
-WEB_DIR := web
-APP_DIR := app
-
-# Python (prefer 3.12, fallback to 3.13, then python3)
-PYTHON := $(shell command -v python3.12 2>/dev/null || command -v python3.13 2>/dev/null || echo python3)
-VENV := $(CURDIR)/$(BACKEND_DIR)/venv
-VENV_BIN := $(VENV)/bin
-PIP := $(VENV_BIN)/pip
-PYTHON_VENV := $(VENV_BIN)/python
-
-# Colors for output
-BLUE := \033[0;34m
-GREEN := \033[0;32m
-YELLOW := \033[0;33m
-NC := \033[0m # No Color
-
-.PHONY: help
-help: ## Show this help message
-	@echo -e "$(BLUE)Voicebox$(NC) - Development Commands"
-	@echo ""
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
-		awk 'BEGIN {FS = ":.*?## "}; {printf "  $(GREEN)%-20s$(NC) %s\n", $$1, $$2}'
-
-# =============================================================================
-# SETUP
-# =============================================================================
-
-.PHONY: setup setup-js setup-python setup-rust
-
-setup: setup-js setup-python ## Full project setup (all dependencies)
-	@echo -e "$(GREEN)✓ Setup complete!$(NC)"
-	@echo -e "  Run $(YELLOW)make dev$(NC) to start development servers"
-
-setup-js: ## Install JavaScript dependencies (bun)
-	@echo -e "$(BLUE)Installing JavaScript dependencies...$(NC)"
-	bun install
-
-setup-python: $(VENV)/bin/activate ## Set up Python virtual environment and dependencies
-	@echo -e "$(BLUE)Installing Python dependencies...$(NC)"
-	$(PIP) install --upgrade pip
-	$(PIP) install -r $(BACKEND_DIR)/requirements.txt
-	$(PIP) install --no-deps chatterbox-tts
-	@if [ "$$(uname -m)" = "arm64" ] && [ "$$(uname)" = "Darwin" ]; then \
-		echo -e "$(BLUE)Detected Apple Silicon - installing MLX dependencies...$(NC)"; \
-		$(PIP) install -r $(BACKEND_DIR)/requirements-mlx.txt; \
-		echo -e "$(GREEN)✓ MLX backend enabled (native Metal acceleration)$(NC)"; \
-	fi
-	$(PIP) install git+https://github.com/QwenLM/Qwen3-TTS.git
-	@echo -e "$(GREEN)✓ Python environment ready$(NC)"
-
-$(VENV)/bin/activate:
-	@echo -e "$(BLUE)Creating Python virtual environment...$(NC)"
-	@PY_MINOR=$$($(PYTHON) -c "import sys; print(sys.version_info[1])"); \
-	if [ "$$PY_MINOR" -gt 13 ]; then \
-		echo -e "$(YELLOW)Warning: Python 3.$$PY_MINOR detected. ML packages may not be compatible.$(NC)"; \
-		echo -e "$(YELLOW)Recommended: Use Python 3.12 or 3.13 (brew install [email protected])$(NC)"; \
-	fi
-	$(PYTHON) -m venv $(VENV)
-
-setup-rust: ## Install Rust toolchain (if not present)
-	@command -v rustc >/dev/null 2>&1 || curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
-# =============================================================================
-# DEVELOPMENT
-# =============================================================================
-
-.PHONY: dev dev-backend dev-frontend dev-web kill-dev
-
-dev: ## Start backend + desktop app (parallel)
-	@echo -e "$(BLUE)Starting development servers...$(NC)"
-	@echo -e "$(YELLOW)Note: If Tauri fails, run 'make build-server' first or use separate terminals$(NC)"
-	@trap 'kill 0' EXIT; \
-		$(MAKE) dev-backend & \
-		sleep 2 && if [ "$$(uname)" = "Linux" ] && lspci 2>/dev/null | grep -qi nvidia; then \
-			WEBKIT_DISABLE_DMABUF_RENDERER=1 $(MAKE) dev-frontend; \
-		else \
-			$(MAKE) dev-frontend; \
-		fi & \
-		wait
-
-dev-backend: ## Start FastAPI backend server
-	@echo -e "$(BLUE)Starting backend server on http://localhost:17493$(NC)"
-	$(VENV_BIN)/uvicorn backend.main:app --reload --port 17493
-
-dev-frontend: ## Start Tauri desktop app
-	@echo -e "$(BLUE)Starting Tauri desktop app...$(NC)"
-	bun run dev
-
-dev-web: ## Start backend + web app (parallel)
-	@echo -e "$(BLUE)Starting web development servers...$(NC)"
-	@trap 'kill 0' EXIT; \
-		$(MAKE) dev-backend & \
-		sleep 2 && cd $(WEB_DIR) && bun run dev & \
-		wait
-
-kill-dev: ## Kill all development processes
-	@echo -e "$(YELLOW)Killing development processes...$(NC)"
-	-pkill -f "uvicorn main:app" 2>/dev/null || true
-	-pkill -f "vite" 2>/dev/null || true
-	@echo -e "$(GREEN)✓ Processes killed$(NC)"
-
-# =============================================================================
-# BUILD
-# =============================================================================
-
-.PHONY: build build-server build-tauri build-web
-
-build: build-server build-tauri ## Build everything (server binary + desktop app)
-	@echo -e "$(GREEN)✓ Build complete!$(NC)"
-
-build-server: ## Build Python server binary
-	@echo -e "$(BLUE)Building server binary...$(NC)"
-	PATH="$(VENV_BIN):$$PATH" ./scripts/build-server.sh
-
-build-tauri: ## Build Tauri desktop app
-	@echo -e "$(BLUE)Building Tauri desktop app...$(NC)"
-	cd $(TAURI_DIR) && bun run tauri build
-
-build-web: ## Build web app
-	@echo -e "$(BLUE)Building web app...$(NC)"
-	cd $(WEB_DIR) && bun run build
-	@echo -e "$(GREEN)✓ Web build output in $(WEB_DIR)/dist/$(NC)"
-
-# =============================================================================
-# DATABASE & API
-# =============================================================================
-
-.PHONY: db-init db-reset generate-api
-
-db-init: $(VENV)/bin/activate ## Initialize SQLite database
-	@echo -e "$(BLUE)Initializing database...$(NC)"
-	cd $(BACKEND_DIR) && $(PYTHON_VENV) -c "from database import init_db; init_db()"
-	@echo -e "$(GREEN)✓ Database created at $(BACKEND_DIR)/data/voicebox.db$(NC)"
-
-db-reset: ## Reset database (delete and reinitialize)
-	@echo -e "$(YELLOW)Resetting database...$(NC)"
-	rm -f $(BACKEND_DIR)/data/voicebox.db
-	$(MAKE) db-init
-
-generate-api: ## Generate TypeScript API client from OpenAPI schema
-	@echo -e "$(BLUE)Generating API client...$(NC)"
-	@echo -e "$(YELLOW)Note: Backend must be running (make dev-backend)$(NC)"
-	./scripts/generate-api.sh
-	@echo -e "$(GREEN)✓ API client generated in $(APP_DIR)/src/lib/api/$(NC)"
-
-# =============================================================================
-# CODE QUALITY
-# =============================================================================
-
-.PHONY: lint format typecheck check
-
-lint: ## Run linter (Biome)
-	@echo -e "$(BLUE)Linting...$(NC)"
-	bun run lint
-
-format: ## Format code (Biome)
-	@echo -e "$(BLUE)Formatting...$(NC)"
-	bun run format
-
-typecheck: ## Run TypeScript type checking
-	@echo -e "$(BLUE)Type checking...$(NC)"
-	bun run tsc --noEmit
-
-check: ## Run all checks (Biome lint + format + type check)
-	@echo -e "$(BLUE)Running all checks...$(NC)"
-	bun run check
-	@echo -e "$(GREEN)✓ All checks passed$(NC)"
-
-# =============================================================================
-# TESTING
-# =============================================================================
-
-.PHONY: test test-backend test-frontend
-
-test: test-backend test-frontend ## Run all tests
-	@echo -e "$(GREEN)✓ All tests passed$(NC)"
-
-test-backend: ## Run Python backend tests (requires pytest)
-	@echo -e "$(BLUE)Running backend tests...$(NC)"
-	@if [ -f "$(VENV_BIN)/pytest" ]; then \
-		cd $(BACKEND_DIR) && $(VENV_BIN)/pytest -v; \
-	else \
-		echo -e "$(YELLOW)pytest not installed. Run: $(PIP) install pytest$(NC)"; \
-		exit 1; \
-	fi
-
-test-frontend: ## Run frontend tests (requires test script in package.json)
-	@echo -e "$(BLUE)Running frontend tests...$(NC)"
-	@if bun run test --help >/dev/null 2>&1; then \
-		bun run test; \
-	else \
-		echo -e "$(YELLOW)No test script configured$(NC)"; \
-		exit 1; \
-	fi
-
-# =============================================================================
-# LOGS & DEBUGGING
-# =============================================================================
-
-.PHONY: logs docs
-
-logs: ## Tail backend logs
-	@echo -e "$(BLUE)Tailing logs (Ctrl+C to stop)...$(NC)"
-	tail -f $(BACKEND_DIR)/logs/*.log 2>/dev/null || echo "No log files found"
-
-docs: ## Open API documentation (backend must be running)
-	@echo -e "$(BLUE)Opening API docs...$(NC)"
-	open http://localhost:17493/docs 2>/dev/null || xdg-open http://localhost:17493/docs
-
-# =============================================================================
-# CLEAN
-# =============================================================================
-
-.PHONY: clean clean-python clean-build clean-all
-
-clean: ## Clean build artifacts
-	@echo -e "$(BLUE)Cleaning build artifacts...$(NC)"
-	rm -rf $(TAURI_DIR)/src-tauri/target/release
-	rm -rf $(WEB_DIR)/dist
-	rm -rf $(APP_DIR)/dist
-	@echo -e "$(GREEN)✓ Build artifacts cleaned$(NC)"
-
-clean-python: ## Clean Python cache and virtual environment
-	@echo -e "$(BLUE)Cleaning Python files...$(NC)"
-	rm -rf $(VENV)
-	find $(BACKEND_DIR) -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
-	find $(BACKEND_DIR) -type f -name "*.pyc" -delete 2>/dev/null || true
-	@echo -e "$(GREEN)✓ Python environment cleaned$(NC)"
-
-clean-build: ## Clean Rust/Tauri build cache
-	@echo -e "$(BLUE)Cleaning Rust build cache...$(NC)"
-	cd $(TAURI_DIR)/src-tauri && cargo clean
-	@echo -e "$(GREEN)✓ Rust cache cleaned$(NC)"
-
-clean-all: clean clean-python clean-build ## Nuclear clean (everything)
-	@echo -e "$(BLUE)Cleaning node_modules...$(NC)"
-	rm -rf node_modules
-	rm -rf $(APP_DIR)/node_modules
-	rm -rf $(TAURI_DIR)/node_modules
-	rm -rf $(WEB_DIR)/node_modules
-	@echo -e "$(GREEN)✓ Full clean complete$(NC)"
@@ -31,7 +31,7 @@ Two-part fix:

 ## Testing
 To test this fix:
-1. Build Voicebox from source: `make build`
+1. Build Voicebox from source: `just build`
 2. Disconnect from internet
 3. Try generating speech
 4. Should work without network requests
@@ -40,13 +40,13 @@ To test this fix:

 ```bash
 # Install dependencies
-pip install -r requirements.txt
+just setup

 # Build the app
-make build
+just build

 # Or build just the server
-make build-server
+just build-server
 ```

 ## Notes
@@ -6,7 +6,7 @@

 <p align="center">
  <strong>The open-source voice synthesis studio.</strong><br/>
-  Clone voices. Generate speech. Build voice-powered apps.<br/>
+  Clone voices. Generate speech. Apply effects. Build voice-powered apps.<br/>
  All running locally on your machine.
 </p>

@@ -59,96 +59,147 @@

 ## What is Voicebox?

-Voicebox is a **local-first voice cloning studio** with DAW-like features for professional voice synthesis. Think of it as a **local, free and open-source alternative to ElevenLabs** — download models, clone voices, and generate speech entirely on your machine.
-
-Unlike cloud services that lock your voice data behind subscriptions, Voicebox gives you:
+Voicebox is a **local-first voice cloning studio** — a free and open-source alternative to ElevenLabs. Clone voices from a few seconds of audio, generate speech in 23 languages across 4 TTS engines, apply post-processing effects, and compose multi-voice projects with a timeline editor.

 - **Complete privacy** — models and voice data stay on your machine
- **Professional tools** — multi-track timeline editor, audio trimming, conversation mixing
- **Model flexibility** — currently powered by Qwen3-TTS, with support for XTTS, Bark, and other models coming soon
- **API-first** — use the desktop app or integrate voice synthesis into your own projects
+- **4 TTS engines** — Qwen3-TTS, LuxTTS, Chatterbox Multilingual, and Chatterbox Turbo
+- **23 languages** — from English to Arabic, Japanese, Hindi, Swahili, and more
+- **Post-processing effects** — pitch shift, reverb, delay, chorus, compression, and filters
+- **Expressive speech** — paralinguistic tags like `[laugh]`, `[sigh]`, `[gasp]` via Chatterbox Turbo
+- **Unlimited length** — auto-chunking with crossfade for scripts, articles, and chapters
+- **Stories editor** — multi-track timeline for conversations, podcasts, and narratives
+- **API-first** — REST API for integrating voice synthesis into your own projects
 - **Native performance** — built with Tauri (Rust), not Electron
- **Super fast on Mac** — MLX backend with native Metal acceleration for 4-5x faster inference on Apple Silicon
-
-Download a voice model, clone any voice from a few seconds of audio, and compose multi-voice projects with studio-grade editing tools. No Python install required, no cloud dependency, no limits.
+- **Runs everywhere** — macOS (MLX/Metal), Windows (CUDA), Linux, AMD ROCm, Intel Arc, Docker

 ---

 ## Download

-Voicebox is available now for macOS and Windows.
-
 | Platform | Download |
 |----------|----------|
-| macOS (Apple Silicon) | [Voicebox_aarch64.app.tar.gz](https://github.com/jamiepine/voicebox/releases/latest/download/Voicebox_aarch64.app.tar.gz) |
-| macOS (Intel) | [Voicebox_x64.app.tar.gz](https://github.com/jamiepine/voicebox/releases/latest/download/Voicebox_x64.app.tar.gz) |
-| Windows (MSI) | [Latest Windows MSI](https://github.com/jamiepine/voicebox/releases/latest) |
-| Windows (Setup) | [Latest Windows Setup](https://github.com/jamiepine/voicebox/releases/latest) |
+| macOS (Apple Silicon) | [Download DMG](https://voicebox.sh/download/mac-arm) |
+| macOS (Intel) | [Download DMG](https://voicebox.sh/download/mac-intel) |
+| Windows | [Download MSI](https://voicebox.sh/download/windows) |
+| Docker | `docker compose up` |

-> **Linux** — Pre-built binaries are not yet available. Linux users can compile from source, see [Development](#development) below.
+> **[View all binaries →](https://github.com/jamiepine/voicebox/releases/latest)**
+
+> **Linux** — Pre-built binaries are not yet available. See [voicebox.sh/linux-install](https://voicebox.sh/linux-install) for build-from-source instructions.

 ---

 ## Features

-### Voice Cloning with Qwen3-TTS
+### Multi-Engine Voice Cloning

-Powered by Alibaba's **Qwen3-TTS** — a breakthrough model that achieves near-perfect voice cloning from just a few seconds of audio.
+Four TTS engines with different strengths, switchable per-generation:

- **Instant cloning** — Upload a sample, get a voice profile
- **High fidelity** — Natural prosody, emotion, and cadence
- **Multi-language** — English, Chinese, and more coming
- **Lightning fast on Mac** — MLX backend leverages Apple Silicon's Neural Engine for super-fast generation
+| Engine | Languages | Strengths |
+|--------|-----------|-----------|
+| **Qwen3-TTS** (0.6B / 1.7B) | 10 | High-quality multilingual cloning, delivery instructions ("speak slowly", "whisper") |
+| **LuxTTS** | English | Lightweight (~1GB VRAM), 48kHz output, 150x realtime on CPU |
+| **Chatterbox Multilingual** | 23 | Broadest language coverage — Arabic, Danish, Finnish, Greek, Hebrew, Hindi, Malay, Norwegian, Polish, Swahili, Swedish, Turkish and more |
+| **Chatterbox Turbo** | English | Fast 350M model with paralinguistic emotion/sound tags |
+
+### Emotions & Paralinguistic Tags
+
+Type `/` in the text input to insert expressive tags that the model synthesizes inline with speech (Chatterbox Turbo):
+
+`[laugh]` `[chuckle]` `[gasp]` `[cough]` `[sigh]` `[groan]` `[sniff]` `[shush]` `[clear throat]`
+
+### Post-Processing Effects
+
+8 audio effects powered by Spotify's `pedalboard` library. Apply after generation, preview in real time, build reusable presets.
+
+| Effect | Description |
+|--------|-------------|
+| Pitch Shift | Up or down by up to 12 semitones |
+| Reverb | Configurable room size, damping, wet/dry mix |
+| Delay | Echo with adjustable time, feedback, and mix |
+| Chorus / Flanger | Modulated delay for metallic or lush textures |
+| Compressor | Dynamic range compression |
+| Gain | Volume adjustment (-40 to +40 dB) |
+| High-Pass Filter | Remove low frequencies |
+| Low-Pass Filter | Remove high frequencies |
+
+Ships with 4 built-in presets (Robotic, Radio, Echo Chamber, Deep Voice) and supports custom presets. Effects can be assigned per-profile as defaults.
+
+### Unlimited Generation Length
+
+Text is automatically split at sentence boundaries and each chunk is generated independently, then crossfaded together. Works with all engines.
+
+- Configurable auto-chunking limit (100–5,000 chars)
+- Crossfade slider (0–200ms) for smooth transitions
+- Max text length: 50,000 characters
+- Smart splitting respects abbreviations, CJK punctuation, and `[tags]`
+
+### Generation Versions
+
+Every generation supports multiple versions with provenance tracking:
+
+- **Original** — clean TTS output, always preserved
+- **Effects versions** — apply different effects chains from any source version
+- **Takes** — regenerate with a new seed for variation
+- **Source tracking** — each version records its lineage
+- **Favorites** — star generations for quick access
+
+### Async Generation Queue
+
+Generation is non-blocking. Submit and immediately start typing the next one.
+
+- Serial execution queue prevents GPU contention
+- Real-time SSE status streaming
+- Failed generations can be retried
+- Stale generations from crashes auto-recover on startup

 ### Voice Profile Management

- **Create profiles** from audio files or record directly in-app
- **Import/Export** profiles to share or back up
- **Multi-sample support** — combine multiple samples for higher quality cloning
- **Organize** with descriptions and language tags
-
-### Speech Generation
-
- **Text-to-speech** with any cloned voice
- **Batch generation** for long-form content
- **Smart caching** — regenerate instantly with voice prompt caching
+- Create profiles from audio files or record directly in-app
+- Import/export profiles to share or back up
+- Multi-sample support for higher quality cloning
+- Per-profile default effects chains
+- Organize with descriptions and language tags

 ### Stories Editor

-Create multi-voice narratives, podcasts, and conversations with a timeline-based editor.
+Multi-voice timeline editor for conversations, podcasts, and narratives.

- **Multi-track composition** — arrange multiple voice tracks in a single project
- **Inline audio editing** — trim and split clips directly in the timeline
- **Auto-playback** — preview stories with synchronized playhead
- **Voice mixing** — build conversations with multiple participants
+- Multi-track composition with drag-and-drop
+- Inline audio trimming and splitting
+- Auto-playback with synchronized playhead
+- Version pinning per track clip

 ### Recording & Transcription

- **In-app recording** with waveform visualization
- **System audio capture** — record desktop audio on macOS and Windows
- **Automatic transcription** powered by Whisper
- **Export recordings** in multiple formats
+- In-app recording with waveform visualization
+- System audio capture (macOS and Windows)
+- Automatic transcription powered by Whisper (including Whisper Turbo)
+- Export recordings in multiple formats

-### Generation History
+### Model Management

- **Full history** of all generated audio
- **Search & filter** by voice, text, or date
- **Re-generate** any past generation with one click
+- Per-model unload to free GPU memory without deleting downloads
+- Custom models directory via `VOICEBOX_MODELS_DIR`
+- Model folder migration with progress tracking
+- Download cancel/clear UI

-### Flexible Deployment
+### GPU Support

- **Local mode** — Everything runs on your machine
- **Remote mode** — Connect to a GPU server on your network
- **One-click server** — Turn any machine into a Voicebox server
+| Platform | Backend | Notes |
+|----------|---------|-------|
+| macOS (Apple Silicon) | MLX (Metal) | 4-5x faster via Neural Engine |
+| Windows / Linux (NVIDIA) | PyTorch (CUDA) | Auto-downloads CUDA binary from within the app |
+| Linux (AMD) | PyTorch (ROCm) | Auto-configures HSA_OVERRIDE_GFX_VERSION |
+| Windows (any GPU) | DirectML | Universal Windows GPU support |
+| Intel Arc | IPEX/XPU | Intel discrete GPU acceleration |
+| Any | CPU | Works everywhere, just slower |

 ---

 ## API

-Voicebox exposes a full REST API, so you can integrate voice synthesis into your own apps.
-
-For the current local app and development workflow, the backend is typically available at `http://localhost:17493`.
-If you launch the backend manually with a different host or port, use that address instead.
+Voicebox exposes a full REST API for integrating voice synthesis into your own apps.

 ```bash
 # Generate speech
@@ -165,15 +216,9 @@ curl -X POST http://localhost:17493/profiles \
  -d '{"name": "My Voice", "language": "en"}'
 ```

-**Use cases:**
+**Use cases:** game dialogue, podcast production, accessibility tools, voice assistants, content automation.

- Game dialogue systems
- Podcast/video production pipelines
- Accessibility tools
- Voice assistants
- Content creation automation
-
-Full API documentation is available at `http://localhost:17493/docs` in the default local workflow, or at `/docs` on whatever server address you configured.
+Full API documentation available at `http://localhost:17493/docs`.

 ---

@@ -185,42 +230,24 @@ Full API documentation is available at `http://localhost:17493/docs` in the defa
 | Frontend | React, TypeScript, Tailwind CSS |
 | State | Zustand, React Query |
 | Backend | FastAPI (Python) |
-| Voice Model | Qwen3-TTS (PyTorch or MLX) |
-| Transcription | Whisper (PyTorch or MLX) |
-| Inference Engine | MLX (Apple Silicon) / PyTorch (Windows/Linux/Intel) |
+| TTS Engines | Qwen3-TTS, LuxTTS, Chatterbox, Chatterbox Turbo |
+| Effects | Pedalboard (Spotify) |
+| Transcription | Whisper / Whisper Turbo (PyTorch or MLX) |
+| Inference | MLX (Apple Silicon) / PyTorch (CUDA/ROCm/XPU/CPU) |
 | Database | SQLite |
 | Audio | WaveSurfer.js, librosa |

-**Why this stack?**
-
- **Tauri over Electron** — 10x smaller bundle, native performance, lower memory
- **FastAPI** — Async Python with automatic OpenAPI schema generation
- **Type-safe end-to-end** — Generated TypeScript client from OpenAPI spec
-
 ---

 ## Roadmap

-Voicebox is the beginning of something bigger. Here's what's coming:
-
-### Coming Soon
-
 | Feature | Description |
 |---------|-------------|
-| **Real-time Synthesis** | Stream audio as it generates, word by word |
-| **Conversation Mode** | Multi-speaker dialogues with automatic turn-taking |
-| **Voice Effects** | Pitch shift, reverb, M3GAN-style effects |
-| **Timeline Editor** | Audio studio with word-level precision editing |
+| **Real-time Streaming** | Stream audio as it generates, word by word |
+| **Voice Design** | Create new voices from text descriptions |
 | **More Models** | XTTS, Bark, and other open-source voice models |
-
-### Future Vision
-
- **Voice Design** — Create new voices from text descriptions
- **Project System** — Save and load complex multi-voice sessions
- **Plugin Architecture** — Extend with custom models and effects
- **Mobile Companion** — Control Voicebox from your phone
-
-Voicebox aims to be the **one-stop shop for everything voice** — cloning, synthesis, editing, effects, and beyond.
+| **Plugin Architecture** | Extend with custom models and effects |
+| **Mobile Companion** | Control Voicebox from your phone |

 ---

@@ -242,14 +269,6 @@ Install [just](https://github.com/casey/just): `brew install just` or `cargo ins

 **Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.11+](https://python.org), [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/), and [Xcode](https://developer.apple.com/xcode/) on macOS.

-### Platform Notes
-
-| Platform | GPU Backend | Notes |
-|----------|-------------|-------|
-| macOS (Apple Silicon) | MLX (Metal) | 4-5x faster inference via Neural Engine |
-| Windows (NVIDIA) | PyTorch (CUDA) | `just setup` auto-installs CUDA PyTorch |
-| Windows/Linux (no NVIDIA) | PyTorch (CPU) | Works but slower |
-
 ### Building Locally

 ```bash
@@ -257,8 +276,6 @@ just build          # Build CPU server binary + Tauri app
 just build-local    # (Windows) Build CPU + CUDA server binaries + Tauri app
 ```

-`just build-local` produces a production-ready installer with the CUDA binary pre-placed for GPU switching.
-
 ### Project Structure

 ```
@@ -1,6 +1,6 @@
 {
  "name": "@voicebox/app",
-  "version": "0.2.4",
+  "version": "0.2.3",
  "private": true,
  "type": "module",
  "scripts": {
@@ -0,0 +1,103 @@
+import type { UseFormReturn } from 'react-hook-form';
+import { FormControl } from '@/components/ui/form';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { getLanguageOptionsForEngine } from '@/lib/constants/languages';
+import type { GenerationFormValues } from '@/lib/hooks/useGenerationForm';
+
+/**
+ * Engine/model options and their display metadata.
+ * Adding a new engine means adding one entry here.
+ */
+const ENGINE_OPTIONS = [
+  { value: 'qwen:1.7B', label: 'Qwen3-TTS 1.7B' },
+  { value: 'qwen:0.6B', label: 'Qwen3-TTS 0.6B' },
+  { value: 'luxtts', label: 'LuxTTS' },
+  { value: 'chatterbox', label: 'Chatterbox' },
+  { value: 'chatterbox_turbo', label: 'Chatterbox Turbo' },
+] as const;
+
+const ENGINE_DESCRIPTIONS: Record<string, string> = {
+  qwen: 'Multi-language, two sizes',
+  luxtts: 'Fast, English-focused',
+  chatterbox: '23 languages, incl. Hebrew',
+  chatterbox_turbo: 'English, [laugh] [cough] tags',
+};
+
+/** Engines that only support English and should force language to 'en' on select. */
+const ENGLISH_ONLY_ENGINES = new Set(['luxtts', 'chatterbox_turbo']);
+
+function getSelectValue(engine: string, modelSize?: string): string {
+  if (engine === 'qwen') return `qwen:${modelSize || '1.7B'}`;
+  return engine;
+}
+
+function handleEngineChange(form: UseFormReturn<GenerationFormValues>, value: string) {
+  if (value.startsWith('qwen:')) {
+    const [, modelSize] = value.split(':');
+    form.setValue('engine', 'qwen');
+    form.setValue('modelSize', modelSize as '1.7B' | '0.6B');
+    // Validate language is supported by Qwen
+    const currentLang = form.getValues('language');
+    const available = getLanguageOptionsForEngine('qwen');
+    if (!available.some((l) => l.value === currentLang)) {
+      form.setValue('language', available[0]?.value ?? 'en');
+    }
+  } else {
+    form.setValue('engine', value as GenerationFormValues['engine']);
+    form.setValue('modelSize', undefined as unknown as '1.7B' | '0.6B');
+    if (ENGLISH_ONLY_ENGINES.has(value)) {
+      form.setValue('language', 'en');
+    } else {
+      // If current language isn't supported by the new engine, reset to first available
+      const currentLang = form.getValues('language');
+      const available = getLanguageOptionsForEngine(value);
+      if (!available.some((l) => l.value === currentLang)) {
+        form.setValue('language', available[0]?.value ?? 'en');
+      }
+    }
+  }
+}
+
+interface EngineModelSelectorProps {
+  form: UseFormReturn<GenerationFormValues>;
+  compact?: boolean;
+}
+
+export function EngineModelSelector({ form, compact }: EngineModelSelectorProps) {
+  const engine = form.watch('engine') || 'qwen';
+  const modelSize = form.watch('modelSize');
+  const selectValue = getSelectValue(engine, modelSize);
+
+  const itemClass = compact ? 'text-xs text-muted-foreground' : undefined;
+  const triggerClass = compact
+    ? 'h-8 text-xs bg-card border-border rounded-full hover:bg-background/50 transition-all'
+    : undefined;
+
+  return (
+    <Select value={selectValue} onValueChange={(v) => handleEngineChange(form, v)}>
+      <FormControl>
+        <SelectTrigger className={triggerClass}>
+          <SelectValue />
+        </SelectTrigger>
+      </FormControl>
+      <SelectContent>
+        {ENGINE_OPTIONS.map((opt) => (
+          <SelectItem key={opt.value} value={opt.value} className={itemClass}>
+            {opt.label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
+/** Returns a human-readable description for the currently selected engine. */
+export function getEngineDescription(engine: string): string {
+  return ENGINE_DESCRIPTIONS[engine] ?? '';
+}
@@ -1,8 +1,8 @@
+import { useQuery } from '@tanstack/react-query';
 import { useMatchRoute } from '@tanstack/react-router';
 import { AnimatePresence, motion } from 'framer-motion';
-import { Loader2, SlidersHorizontal, Sparkles } from 'lucide-react';
+import { Loader2, Sparkles } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
-import { EffectsChainEditor } from '@/components/Effects/EffectsChainEditor';
 import { Button } from '@/components/ui/button';
 import { Form, FormControl, FormField, FormItem, FormMessage } from '@/components/ui/form';
 import {
@@ -13,7 +13,7 @@ import {
  SelectValue,
 } from '@/components/ui/select';
 import { Textarea } from '@/components/ui/textarea';
-import type { EffectConfig } from '@/lib/api/types';
+import { apiClient } from '@/lib/api/client';
 import { getLanguageOptionsForEngine, type LanguageCode } from '@/lib/constants/languages';
 import { useGenerationForm } from '@/lib/hooks/useGenerationForm';
 import { useProfile, useProfiles } from '@/lib/hooks/useProfiles';
@@ -22,6 +22,7 @@ import { cn } from '@/lib/utils/cn';
 import { useGenerationStore } from '@/stores/generationStore';
 import { useStoryStore } from '@/stores/storyStore';
 import { useUIStore } from '@/stores/uiStore';
+import { EngineModelSelector } from './EngineModelSelector';
 import { ParalinguisticInput } from './ParalinguisticInput';

 interface FloatingGenerateBoxProps {
@@ -38,8 +39,7 @@ export function FloatingGenerateBox({
  const { data: selectedProfile } = useProfile(selectedProfileId || '');
  const { data: profiles } = useProfiles();
  const [isExpanded, setIsExpanded] = useState(false);
-  const [isInstructMode, setIsInstructMode] = useState(false);
-  const [effectsChain, setEffectsChain] = useState<EffectConfig[]>([]);
+  const [selectedPresetId, setSelectedPresetId] = useState<string | null>(null);
  const containerRef = useRef<HTMLDivElement>(null);
  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
  const matchRoute = useMatchRoute();
@@ -49,18 +49,28 @@ export function FloatingGenerateBox({
  const { data: currentStory } = useStory(selectedStoryId);
  const addPendingStoryAdd = useGenerationStore((s) => s.addPendingStoryAdd);

+  // Fetch effect presets for the dropdown
+  const { data: effectPresets } = useQuery({
+    queryKey: ['effectPresets'],
+    queryFn: () => apiClient.listEffectPresets(),
+  });
+
  // Calculate if track editor is visible (on stories route with items)
  const hasTrackEditor = isStoriesRoute && currentStory && currentStory.items.length > 0;

  const { form, handleSubmit, isPending } = useGenerationForm({
    onSuccess: async (generationId) => {
      setIsExpanded(false);
-      // Defer the story add until TTS completes — useGenerationProgress handles it
+      // Defer the story add until TTS completes -- useGenerationProgress handles it
      if (isStoriesRoute && selectedStoryId && generationId) {
        addPendingStoryAdd(generationId, selectedStoryId);
      }
    },
-    getEffectsChain: () => (effectsChain.length > 0 ? effectsChain : undefined),
+    getEffectsChain: () => {
+      if (!selectedPresetId || !effectPresets) return undefined;
+      const preset = effectPresets.find((p) => p.id === selectedPresetId);
+      return preset?.effects_chain;
+    },
  });

  // Click away handler to collapse the box
@@ -188,111 +198,57 @@ export function FloatingGenerateBox({
        <Form {...form}>
          <form onSubmit={form.handleSubmit(onSubmit)}>
            <div className="flex gap-2">
-              <motion.div
-                className={cn('flex-1', isExpanded && 'mr-12')}
-                transition={{ duration: 0.3, ease: 'easeOut' }}
-              >
-                {/* Text field - hidden when in instruct mode */}
-                <div style={{ display: isInstructMode ? 'none' : 'block' }}>
-                  <FormField
-                    control={form.control}
-                    name="text"
-                    render={({ field }) => (
-                      <FormItem>
-                        <FormControl>
-                          <motion.div
-                            animate={{
-                              height: isExpanded ? 'auto' : '32px',
-                            }}
-                            transition={{ duration: 0.15, ease: 'easeOut' }}
-                            style={{ overflow: 'hidden' }}
-                          >
-                            {form.watch('engine') === 'chatterbox_turbo' ? (
-                              <ParalinguisticInput
-                                value={field.value}
-                                onChange={field.onChange}
-                                placeholder={
-                                  isStoriesRoute && currentStory
-                                    ? `Generate speech for "${currentStory.name}"... (type / for effects)`
-                                    : selectedProfile
-                                      ? `Type / for effects like [laugh], [sigh]...`
-                                      : 'Select a voice profile above...'
-                                }
-                                className="px-3 py-2 resize-none bg-transparent border-none focus-visible:ring-0 focus-visible:ring-offset-0 focus:outline-none focus:ring-0 outline-none ring-0 rounded-2xl text-sm w-full"
-                                style={{
-                                  minHeight: isExpanded ? '100px' : '32px',
-                                  maxHeight: '300px',
-                                  overflowY: 'auto',
-                                }}
-                                disabled={!selectedProfileId}
-                                onClick={() => setIsExpanded(true)}
-                                onFocus={() => setIsExpanded(true)}
-                              />
-                            ) : (
-                              <Textarea
-                                {...field}
-                                ref={(node: HTMLTextAreaElement | null) => {
-                                  // Store ref for auto-resize (only for active field)
-                                  if (!isInstructMode) {
-                                    textareaRef.current = node;
-                                  }
-                                  // Forward ref to react-hook-form
-                                  if (typeof field.ref === 'function') {
-                                    field.ref(node);
-                                  }
-                                }}
-                                placeholder={
-                                  isStoriesRoute && currentStory
-                                    ? `Generate speech for "${currentStory.name}"...`
-                                    : selectedProfile
-                                      ? `Generate speech using ${selectedProfile.name}...`
-                                      : 'Select a voice profile above...'
-                                }
-                                className="resize-none bg-transparent border-none focus-visible:ring-0 focus-visible:ring-offset-0 focus:outline-none focus:ring-0 outline-none ring-0 rounded-2xl text-sm placeholder:text-muted-foreground/60 w-full"
-                                style={{
-                                  minHeight: isExpanded ? '100px' : '32px',
-                                  maxHeight: '300px',
-                                }}
-                                disabled={!selectedProfileId}
-                                onClick={() => setIsExpanded(true)}
-                                onFocus={() => setIsExpanded(true)}
-                              />
-                            )}
-                          </motion.div>
-                        </FormControl>
-                        <FormMessage className="text-xs" />
-                      </FormItem>
-                    )}
-                  />
-                </div>
-                {/* Instruct field - hidden when in text mode */}
-                <div style={{ display: isInstructMode ? 'block' : 'none' }}>
-                  <FormField
-                    control={form.control}
-                    name="instruct"
-                    render={({ field }) => (
-                      <FormItem>
-                        <FormControl>
-                          <motion.div
-                            animate={{
-                              height: isExpanded ? 'auto' : '32px',
-                            }}
-                            transition={{ duration: 0.15, ease: 'easeOut' }}
-                            style={{ overflow: 'hidden' }}
-                          >
+              <motion.div className="flex-1" transition={{ duration: 0.3, ease: 'easeOut' }}>
+                <FormField
+                  control={form.control}
+                  name="text"
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormControl>
+                        <motion.div
+                          animate={{
+                            height: isExpanded ? 'auto' : '32px',
+                          }}
+                          transition={{ duration: 0.15, ease: 'easeOut' }}
+                          style={{ overflow: 'hidden' }}
+                        >
+                          {form.watch('engine') === 'chatterbox_turbo' ? (
+                            <ParalinguisticInput
+                              value={field.value}
+                              onChange={field.onChange}
+                              placeholder={
+                                isStoriesRoute && currentStory
+                                  ? `Generate speech for "${currentStory.name}"... (type / for effects)`
+                                  : selectedProfile
+                                    ? `Type / for effects like [laugh], [sigh]...`
+                                    : 'Select a voice profile above...'
+                              }
+                              className="px-3 py-2 resize-none bg-transparent border-none focus-visible:ring-0 focus-visible:ring-offset-0 focus:outline-none focus:ring-0 outline-none ring-0 rounded-2xl text-sm w-full"
+                              style={{
+                                minHeight: isExpanded ? '100px' : '32px',
+                                maxHeight: '300px',
+                                overflowY: 'auto',
+                              }}
+                              disabled={!selectedProfileId}
+                              onClick={() => setIsExpanded(true)}
+                              onFocus={() => setIsExpanded(true)}
+                            />
+                          ) : (
                            <Textarea
                              {...field}
                              ref={(node: HTMLTextAreaElement | null) => {
-                                // Store ref for auto-resize (only for active field)
-                                if (isInstructMode) {
-                                  textareaRef.current = node;
-                                }
-                                // Forward ref to react-hook-form
+                                textareaRef.current = node;
                                if (typeof field.ref === 'function') {
                                  field.ref(node);
                                }
                              }}
-                              placeholder="e.g. very happy and excited"
+                              placeholder={
+                                isStoriesRoute && currentStory
+                                  ? `Generate speech for "${currentStory.name}"...`
+                                  : selectedProfile
+                                    ? `Generate speech using ${selectedProfile.name}...`
+                                    : 'Select a voice profile above...'
+                              }
                              className="resize-none bg-transparent border-none focus-visible:ring-0 focus-visible:ring-offset-0 focus:outline-none focus:ring-0 outline-none ring-0 rounded-2xl text-sm placeholder:text-muted-foreground/60 w-full"
                              style={{
                                minHeight: isExpanded ? '100px' : '32px',
@@ -302,13 +258,13 @@ export function FloatingGenerateBox({
                              onClick={() => setIsExpanded(true)}
                              onFocus={() => setIsExpanded(true)}
                            />
-                          </motion.div>
-                        </FormControl>
-                        <FormMessage className="text-xs" />
-                      </FormItem>
-                    )}
-                  />
-                </div>
+                          )}
+                        </motion.div>
+                      </FormControl>
+                      <FormMessage className="text-xs" />
+                    </FormItem>
+                  )}
+                />
              </motion.div>

              <div className="relative shrink-0">
@@ -340,62 +296,9 @@ export function FloatingGenerateBox({
                        : 'Generate speech'}
                  </span>
                </div>
-                <AnimatePresence>
-                  {isExpanded && form.watch('engine') === 'qwen' && (
-                    <motion.div
-                      initial={{ opacity: 0, scale: 0.8 }}
-                      animate={{ opacity: 1, scale: 1 }}
-                      exit={{ opacity: 0, scale: 0.8 }}
-                      transition={{ duration: 0.2 }}
-                      className="absolute top-0 right-[calc(100%+0.5rem)]"
-                    >
-                      <div className="group relative">
-                        <Button
-                          type="button"
-                          variant="ghost"
-                          size="icon"
-                          onClick={() => setIsInstructMode(!isInstructMode)}
-                          className={cn(
-                            'h-10 w-10 rounded-full transition-all duration-200',
-                            isInstructMode
-                              ? 'bg-accent text-accent-foreground border border-accent hover:bg-accent/90'
-                              : effectsChain.length > 0
-                                ? 'bg-accent/50 text-accent-foreground border border-accent/50 hover:bg-accent/70'
-                                : 'bg-card border border-border hover:bg-background/50',
-                          )}
-                          aria-label={
-                            isInstructMode ? 'Fine tune instructions, on' : 'Fine tune instructions'
-                          }
-                        >
-                          <SlidersHorizontal className="h-4 w-4" />
-                        </Button>
-                        <span className="pointer-events-none absolute bottom-full left-1/2 -translate-x-1/2 mb-2 whitespace-nowrap rounded-md bg-popover px-3 py-1.5 text-xs text-popover-foreground border border-border opacity-0 transition-opacity group-hover:opacity-100 z-[9999]">
-                          Fine tune instructions & effects
-                        </span>
-                      </div>
-                    </motion.div>
-                  )}
-                </AnimatePresence>
              </div>
            </div>

-            {/* Effects chain editor panel - shown alongside instruct */}
-            <AnimatePresence>
-              {isExpanded && isInstructMode && (
-                <motion.div
-                  initial={{ height: 0, opacity: 0 }}
-                  animate={{ height: 'auto', opacity: 1 }}
-                  exit={{ height: 0, opacity: 0 }}
-                  transition={{ duration: 0.2 }}
-                  className="overflow-hidden mt-2"
-                >
-                  <div className="border-t border-border/50 pt-2 pb-1">
-                    <EffectsChainEditor value={effectsChain} onChange={setEffectsChain} compact />
-                  </div>
-                </motion.div>
-              )}
-            </AnimatePresence>
-
            <AnimatePresence>
              <motion.div
                initial={{ height: 0, opacity: 0 }}
@@ -454,57 +357,29 @@ export function FloatingGenerateBox({
                    }}
                  />

+                  <FormItem className="flex-1 space-y-0">
+                    <EngineModelSelector form={form} compact />
+                  </FormItem>
+
                  <FormItem className="flex-1 space-y-0">
                    <Select
-                      value={
-                        form.watch('engine') === 'luxtts'
-                          ? 'luxtts'
-                          : form.watch('engine') === 'chatterbox'
-                            ? 'chatterbox'
-                            : form.watch('engine') === 'chatterbox_turbo'
-                              ? 'chatterbox_turbo'
-                              : `qwen:${form.watch('modelSize') || '1.7B'}`
+                      value={selectedPresetId || 'none'}
+                      onValueChange={(value) =>
+                        setSelectedPresetId(value === 'none' ? null : value)
                      }
-                      onValueChange={(value) => {
-                        if (value === 'luxtts') {
-                          form.setValue('engine', 'luxtts');
-                          form.setValue('language', 'en');
-                        } else if (value === 'chatterbox') {
-                          form.setValue('engine', 'chatterbox');
-                        } else if (value === 'chatterbox_turbo') {
-                          form.setValue('engine', 'chatterbox_turbo');
-                          form.setValue('language', 'en');
-                        } else {
-                          const [, modelSize] = value.split(':');
-                          form.setValue('engine', 'qwen');
-                          form.setValue('modelSize', modelSize as '1.7B' | '0.6B');
-                        }
-                      }}
                    >
-                      <FormControl>
-                        <SelectTrigger className="h-8 text-xs bg-card border-border rounded-full hover:bg-background/50 transition-all">
-                          <SelectValue />
-                        </SelectTrigger>
-                      </FormControl>
+                      <SelectTrigger className="h-8 text-xs bg-card border-border rounded-full hover:bg-background/50 transition-all">
+                        <SelectValue placeholder="No effects" />
+                      </SelectTrigger>
                      <SelectContent>
-                        <SelectItem value="qwen:1.7B" className="text-xs text-muted-foreground">
-                          Qwen3-TTS 1.7B
-                        </SelectItem>
-                        <SelectItem value="qwen:0.6B" className="text-xs text-muted-foreground">
-                          Qwen3-TTS 0.6B
-                        </SelectItem>
-                        <SelectItem value="luxtts" className="text-xs text-muted-foreground">
-                          LuxTTS
-                        </SelectItem>
-                        <SelectItem value="chatterbox" className="text-xs text-muted-foreground">
-                          Chatterbox
-                        </SelectItem>
-                        <SelectItem
-                          value="chatterbox_turbo"
-                          className="text-xs text-muted-foreground"
-                        >
-                          Chatterbox Turbo
+                        <SelectItem value="none" className="text-xs">
+                          No effects
                        </SelectItem>
+                        {effectPresets?.map((preset) => (
+                          <SelectItem key={preset.id} value={preset.id} className="text-xs">
+                            {preset.name}
+                          </SelectItem>
+                        ))}
                      </SelectContent>
                    </Select>
                  </FormItem>
@@ -23,6 +23,7 @@ import { getLanguageOptionsForEngine } from '@/lib/constants/languages';
 import { useGenerationForm } from '@/lib/hooks/useGenerationForm';
 import { useProfile } from '@/lib/hooks/useProfiles';
 import { useUIStore } from '@/stores/uiStore';
+import { EngineModelSelector, getEngineDescription } from './EngineModelSelector';
 import { ParalinguisticInput } from './ParalinguisticInput';

 export function GenerationForm() {
@@ -117,53 +118,9 @@ export function GenerationForm() {
            <div className="grid gap-4 md:grid-cols-3">
              <FormItem>
                <FormLabel>Model</FormLabel>
-                <Select
-                  value={
-                    form.watch('engine') === 'luxtts'
-                      ? 'luxtts'
-                      : form.watch('engine') === 'chatterbox'
-                        ? 'chatterbox'
-                        : form.watch('engine') === 'chatterbox_turbo'
-                          ? 'chatterbox_turbo'
-                          : `qwen:${form.watch('modelSize') || '1.7B'}`
-                  }
-                  onValueChange={(value) => {
-                    if (value === 'luxtts') {
-                      form.setValue('engine', 'luxtts');
-                      form.setValue('language', 'en');
-                    } else if (value === 'chatterbox') {
-                      form.setValue('engine', 'chatterbox');
-                    } else if (value === 'chatterbox_turbo') {
-                      form.setValue('engine', 'chatterbox_turbo');
-                      form.setValue('language', 'en');
-                    } else {
-                      const [, modelSize] = value.split(':');
-                      form.setValue('engine', 'qwen');
-                      form.setValue('modelSize', modelSize as '1.7B' | '0.6B');
-                    }
-                  }}
-                >
-                  <FormControl>
-                    <SelectTrigger>
-                      <SelectValue />
-                    </SelectTrigger>
-                  </FormControl>
-                  <SelectContent>
-                    <SelectItem value="qwen:1.7B">Qwen3-TTS 1.7B</SelectItem>
-                    <SelectItem value="qwen:0.6B">Qwen3-TTS 0.6B</SelectItem>
-                    <SelectItem value="luxtts">LuxTTS</SelectItem>
-                    <SelectItem value="chatterbox">Chatterbox</SelectItem>
-                    <SelectItem value="chatterbox_turbo">Chatterbox Turbo</SelectItem>
-                  </SelectContent>
-                </Select>
+                <EngineModelSelector form={form} />
                <FormDescription>
-                  {form.watch('engine') === 'luxtts'
-                    ? 'Fast, English-focused'
-                    : form.watch('engine') === 'chatterbox'
-                      ? '23 languages, incl. Hebrew'
-                      : form.watch('engine') === 'chatterbox_turbo'
-                        ? 'English, [laugh] [cough] tags'
-                        : 'Multi-language, two sizes'}
+                  {getEngineDescription(form.watch('engine') || 'qwen')}
                </FormDescription>
              </FormItem>

@@ -394,7 +394,8 @@ export function HistoryTable() {
          >
            {history.map((gen) => {
              const isCurrentlyPlaying = currentAudioId === gen.id && isPlaying;
-              const isGenerating = gen.status === 'generating';
+              const isInProgress = gen.status === 'loading_model' || gen.status === 'generating';
+              const isGenerating = isInProgress;
              const isFailed = gen.status === 'failed';
              const isPlayable = !isGenerating && !isFailed;
              const hasVersions = gen.versions && gen.versions.length > 1;
@@ -472,8 +473,10 @@ export function HistoryTable() {
                        ) : null}
                      </div>
                      <div className="text-xs text-muted-foreground">
-                        {isGenerating ? (
-                          <span className="text-accent">Generating...</span>
+                        {isInProgress ? (
+                          <span className="text-accent">
+                            {gen.status === 'loading_model' ? 'Loading model...' : 'Generating...'}
+                          </span>
                        ) : (
                          formatDate(gen.created_at)
                        )}
@@ -1,7 +1,10 @@
 import { Link, useMatchRoute } from '@tanstack/react-router';
 import { AudioLines, Box, Mic, Server, Speaker, Volume2, Wand2 } from 'lucide-react';
+import { useEffect, useState } from 'react';
 import voiceboxLogo from '@/assets/voicebox-logo.png';
 import { cn } from '@/lib/utils/cn';
+import { usePlatform } from '@/platform/PlatformContext';
+import type { UpdateStatus } from '@/platform/types';
 import { usePlayerStore } from '@/stores/playerStore';
 import { version } from '../../package.json';

@@ -22,6 +25,10 @@ const tabs = [
 export function Sidebar({ isMacOS }: SidebarProps) {
  const matchRoute = useMatchRoute();
  const isPlayerOpen = !!usePlayerStore((s) => s.audioUrl);
+  const platform = usePlatform();
+
+  const [updateStatus, setUpdateStatus] = useState<UpdateStatus>(platform.updater.getStatus());
+  useEffect(() => platform.updater.subscribe(setUpdateStatus), [platform.updater]);

  return (
    <div
@@ -85,10 +92,18 @@ export function Sidebar({ isMacOS }: SidebarProps) {

      {/* Version */}
      <div
-        className="mt-auto text-[10px] text-muted-foreground/50 transition-all duration-300"
+        className="mt-auto flex flex-col items-center gap-1.5 transition-all duration-300"
        style={{ paddingBottom: isPlayerOpen ? '7rem' : undefined }}
      >
-        v{version}
+        <span className="text-[10px] text-muted-foreground/50">v{version}</span>
+        {updateStatus.available && (
+          <Link
+            to="/server"
+            className="text-[9px] font-semibold tracking-wide uppercase px-2 py-0.5 rounded-full bg-accent/15 text-accent hover:bg-accent/25 transition-colors"
+          >
+            Update
+          </Link>
+        )}
      </div>
    </div>
  );
@@ -16,7 +16,7 @@ const SelectTrigger = React.forwardRef<
  <SelectPrimitive.Trigger
    ref={ref}
    className={cn(
-      'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
+      'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:bg-muted/50 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
      className,
    )}
    {...props}
@@ -73,7 +73,7 @@ export interface GenerationResponse {
  instruct?: string;
  engine?: string;
  model_size?: string;
-  status: 'generating' | 'completed' | 'failed';
+  status: 'loading_model' | 'generating' | 'completed' | 'failed';
  error?: string;
  is_favorited?: boolean;
  created_at: string;
@@ -8,7 +8,7 @@ import { useServerStore } from '@/stores/serverStore';

 interface GenerationStatusEvent {
  id: string;
-  status: 'generating' | 'completed' | 'failed' | 'not_found';
+  status: 'loading_model' | 'generating' | 'completed' | 'failed' | 'not_found';
  duration?: number;
  error?: string;
 }
@@ -1,462 +1,135 @@
-# voicebox Backend
+# Voicebox Backend

-Production-quality FastAPI backend for Qwen3-TTS voice cloning.
+FastAPI server powering voice cloning, speech generation, and audio processing. Runs locally as a Tauri sidecar or standalone via `python -m backend.main`.

-## Features
+## Running

- ✅ **Voice Profile Management** - Create, update, delete voice profiles with multi-sample support
- ✅ **Voice Cloning** - Generate speech using voice profiles with caching
- ✅ **Generation History** - Full history tracking with search and filtering
- ✅ **Transcription** - Whisper-based audio transcription
- ✅ **Multi-Sample Profiles** - Combine multiple reference samples for better quality
- ✅ **Voice Prompt Caching** - Dual memory + disk caching for fast generation
- ✅ **Audio Validation** - Automatic validation of reference audio quality
- ✅ **Model Management** - Lazy loading and VRAM management
+```bash
+# Via justfile (recommended)
+just dev:server
+
+# Standalone
+python -m backend.main --host 127.0.0.1 --port 17493
+
+# With custom data directory
+python -m backend.main --data-dir /path/to/data
+```
+
+The server auto-initializes the SQLite database on first startup. Models are downloaded from HuggingFace on first use.

 ## Architecture

 ```
 backend/
-├── main.py              # FastAPI app with all routes
-├── models.py            # Pydantic request/response models
-├── platform_detect.py   # Platform detection for backend selection
-├── tts.py              # TTS backend abstraction (delegates to MLX or PyTorch)
-├── transcribe.py       # STT backend abstraction (delegates to MLX or PyTorch)
-├── backends/           # Backend implementations
-│   ├── __init__.py     # Backend factory and protocols
-│   ├── mlx_backend.py  # MLX backend (Apple Silicon)
-│   └── pytorch_backend.py  # PyTorch backend (Windows/Linux/Intel)
-├── profiles.py         # Voice profile CRUD
-├── history.py          # Generation history
-├── studio.py           # Audio editing (TODO)
-├── database.py         # SQLite ORM
-└── utils/
-    ├── audio.py        # Audio processing utilities
-    ├── cache.py        # Voice prompt caching
-    └── validation.py   # Input validation
+  app.py                  # FastAPI app factory, CORS, lifecycle events
+  main.py                 # Entry point (imports app, runs uvicorn)
+  config.py               # Data directory paths and configuration
+  models.py               # Pydantic request/response schemas
+  server.py               # Tauri sidecar launcher, parent-pid watchdog
+
+  routes/                 # Thin HTTP handlers — validation, delegation, response formatting
+  services/               # Business logic, CRUD, orchestration
+  backends/               # TTS/STT engine implementations (MLX, PyTorch, etc.)
+  database/               # ORM models, session management, migrations, seed data
+  utils/                  # Shared utilities (audio, effects, caching, progress tracking)
 ```

-### Backend Selection
-
-Voicebox automatically selects the best backend based on platform:
-
- **Apple Silicon (M1/M2/M3)**: Uses MLX backend with native Metal acceleration (4-5x faster)
- **Windows/Linux/Intel Mac**: Uses PyTorch backend (CUDA GPU if available, CPU fallback)
-
-The backend is detected at runtime via `platform_detect.py`. Both backends implement the same interface, so the API remains consistent across platforms.
-
-## API Endpoints
-
-### Health & Info
-
-#### `GET /`
-Root endpoint with version info.
-
-#### `GET /health`
-Health check with model status.
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "model_loaded": true,
-  "gpu_available": true,
-  "gpu_type": "Metal (Apple Silicon via MLX)",
-  "backend_type": "mlx",
-  "vram_used_mb": null
-}
-```
-
-**Backend Types:**
- `"mlx"` - MLX backend (Apple Silicon with Metal acceleration)
- `"pytorch"` - PyTorch backend (Windows/Linux/Intel Mac)
-
-### Voice Profiles
-
-**Note:** The database is automatically initialized when the server starts. No manual setup required.
-
-#### `POST /profiles`
-Create a new voice profile.
-
-**Request:**
-```json
-{
-  "name": "My Voice",
-  "description": "Optional description",
-  "language": "en"
-}
-```
-
-**Response:**
-```json
-{
-  "id": "uuid",
-  "name": "My Voice",
-  "description": "Optional description",
-  "language": "en",
-  "created_at": "2024-01-01T00:00:00Z",
-  "updated_at": "2024-01-01T00:00:00Z"
-}
-```
-
-#### `GET /profiles`
-List all voice profiles.
-
-#### `GET /profiles/{profile_id}`
-Get a specific profile.
-
-#### `PUT /profiles/{profile_id}`
-Update a profile.
-
-#### `DELETE /profiles/{profile_id}`
-Delete a profile and all associated samples.
-
-#### `POST /profiles/{profile_id}/samples`
-Add a sample to a profile.
-
-**Form Data:**
- `file`: Audio file (WAV, MP3, etc.)
- `reference_text`: Transcript of the audio
-
-**Response:**
-```json
-{
-  "id": "sample-uuid",
-  "profile_id": "profile-uuid",
-  "audio_path": "/path/to/sample.wav",
-  "reference_text": "This is my voice"
-}
-```
-
-#### `GET /profiles/{profile_id}/samples`
-List all samples for a profile.
-
-#### `DELETE /profiles/samples/{sample_id}`
-Delete a specific sample.
-
-### Generation
-
-#### `POST /generate`
-Generate speech from text using a voice profile.
-
-**Request:**
-```json
-{
-  "profile_id": "uuid",
-  "text": "Hello, this is a test.",
-  "language": "en",
-  "seed": 42
-}
-```
-
-**Response:**
-```json
-{
-  "id": "generation-uuid",
-  "profile_id": "profile-uuid",
-  "text": "Hello, this is a test.",
-  "language": "en",
-  "audio_path": "/path/to/audio.wav",
-  "duration": 2.5,
-  "seed": 42,
-  "created_at": "2024-01-01T00:00:00Z"
-}
-```
-
-### History
-
-#### `GET /history`
-List generation history with optional filters.
-
-**Query Parameters:**
- `profile_id` (optional): Filter by profile
- `search` (optional): Search in text content
- `limit` (default: 50): Results per page
- `offset` (default: 0): Pagination offset
-
-#### `GET /history/{generation_id}`
-Get a specific generation.
-
-#### `DELETE /history/{generation_id}`
-Delete a generation.
-
-#### `GET /history/stats`
-Get generation statistics.
-
-**Response:**
-```json
-{
-  "total_generations": 100,
-  "total_duration_seconds": 250.5,
-  "generations_by_profile": {
-    "profile-uuid-1": 50,
-    "profile-uuid-2": 50
-  }
-}
-```
-
-### Audio Files
-
-#### `GET /audio/{generation_id}`
-Download generated audio file.
-
-Returns WAV file with appropriate headers.
-
-### Transcription
-
-#### `POST /transcribe`
-Transcribe audio file to text.
-
-**Form Data:**
- `file`: Audio file
- `language` (optional): Language hint (en or zh)
-
-**Response:**
-```json
-{
-  "text": "Transcribed text here",
-  "duration": 5.5
-}
-```
-
-### Model Management
-
-#### `POST /models/load`
-Manually load TTS model.
-
-**Query Parameters:**
- `model_size`: Model size (1.7B or 0.6B)
-
-#### `POST /models/unload`
-Unload TTS model to free memory.
-
-## Database Schema
-
-### profiles
- `id`: UUID primary key
- `name`: Profile name (unique)
- `description`: Optional description
- `language`: Language code (en/zh)
- `created_at`: Creation timestamp
- `updated_at`: Last update timestamp
-
-### profile_samples
- `id`: UUID primary key
- `profile_id`: Foreign key to profiles
- `audio_path`: Path to audio file
- `reference_text`: Transcript
-
-### generations
- `id`: UUID primary key
- `profile_id`: Foreign key to profiles
- `text`: Generated text
- `language`: Language code
- `audio_path`: Path to audio file
- `duration`: Duration in seconds
- `seed`: Random seed (optional)
- `created_at`: Creation timestamp
-
-### projects
- `id`: UUID primary key
- `name`: Project name
- `data`: JSON data
- `created_at`: Creation timestamp
- `updated_at`: Last update timestamp
-
-## File Structure
+### Request flow

 ```
-data/
-├── profiles/
-│   └── {profile_id}/
-│       ├── {sample_id}.wav
-│       └── ...
-├── generations/
-│   └── {generation_id}.wav
-├── cache/
-│   └── {hash}.prompt
-├── projects/
-│   └── {project_id}.json
-└── voicebox.db
+HTTP request
+  -> routes/        (validate input, parse params)
+  -> services/      (business logic, database queries, orchestration)
+  -> backends/      (TTS/STT inference)
+  -> utils/         (audio processing, effects, caching)
 ```

-## Setup
+Route handlers are intentionally thin. They validate input, delegate to a service function, and format the response. All business logic lives in `services/`.

-### 1. Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-**Note:** On Apple Silicon, also install MLX dependencies for faster inference:
-```bash
-pip install -r requirements-mlx.txt
-```
-
-### 2. Download Models (Automatic)
-
-The Qwen3-TTS models are automatically downloaded from HuggingFace Hub on first use, similar to how Whisper models work.
-
-**No manual download required!** The models will be cached locally after the first download.
-
-Available models:
- **1.7B** (recommended): `Qwen/Qwen3-TTS-12Hz-1.7B-Base` (~4GB)
- **0.6B** (faster): `Qwen/Qwen3-TTS-12Hz-0.6B-Base` (~2GB)
-
-**Note:** The first generation will take longer as the model downloads. Subsequent generations will use the cached model.
-
-#### Manual Download (Optional)
-
-If you prefer to download models manually or have limited internet during runtime:
-
-```bash
-# Install huggingface-cli
-pip install huggingface_hub
-
-# Download 1.7B model
-huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base
-
-# Or use Python
-python -c "from huggingface_hub import snapshot_download; snapshot_download('Qwen/Qwen3-TTS-12Hz-1.7B-Base')"
-```
-
-Models are cached in `~/.cache/huggingface/hub/` by default.
-
-### 4. Run Server
-
-```bash
-# Development (local only)
-python -m backend.main
-
-# Production (allow remote access)
-python -m backend.main --host 0.0.0.0 --port 8000
-```
-
-## Usage Examples
-
-The desktop app, web client, and current development workflow use `http://localhost:17493` by default.
-If you launch the backend manually with a different host or port, substitute that address in the examples below.
-
-### Creating a Voice Profile
-
-```bash
-# 1. Create profile
-curl -X POST http://localhost:17493/profiles \
-  -H "Content-Type: application/json" \
-  -d '{"name": "My Voice", "language": "en"}'
-
-# Response: {"id": "abc-123", ...}
-
-# 2. Add sample
-curl -X POST http://localhost:17493/profiles/abc-123/samples \
-  -F "[email protected]" \
-  -F "reference_text=This is my voice sample"
-```
-
-### Generating Speech
+### Key modules
+
+**services/generation.py** -- Single `run_generation()` function that handles all three generation modes (generate, retry, regenerate). Manages model loading, voice prompt creation, chunked inference, normalization, effects, and version persistence.
+
+**services/task_queue.py** -- Serial generation queue. Ensures only one GPU inference runs at a time. Background tasks are tracked to prevent garbage collection.
+
+**backends/__init__.py** -- Protocol definitions (`TTSBackend`, `STTBackend`), model config registry, and factory functions. Adding a new engine means implementing the protocol and registering a config entry.
+
+**backends/base.py** -- Shared utilities used across all engine implementations: HuggingFace cache checks, device detection, voice prompt combination, progress tracking.
+
+**database/** -- SQLAlchemy ORM models with a re-exporting `__init__.py` for backward compatibility. Migrations run automatically on startup.
+
+### Backend selection
+
+The server detects the best inference backend at startup:
+
+| Platform | Backend | Acceleration |
+|----------|---------|-------------|
+| macOS (Apple Silicon) | MLX | Metal / Neural Engine |
+| Windows / Linux (NVIDIA) | PyTorch | CUDA |
+| Linux (AMD) | PyTorch | ROCm |
+| Intel Arc | PyTorch | IPEX / XPU |
+| Windows (any GPU) | PyTorch | DirectML |
+| Any | PyTorch | CPU fallback |
+
+Detection is handled by `utils/platform_detect.py`. Both backends implement the same `TTSBackend` protocol, so the API layer is engine-agnostic.
+
+## API
+
+90 endpoints organized by domain. Full interactive documentation available at `http://localhost:17493/docs` when the server is running.
+
+| Domain | Prefix | Description |
+|--------|--------|-------------|
+| Health | `/`, `/health` | Server status, GPU info, filesystem checks |
+| Profiles | `/profiles` | Voice profile CRUD, samples, avatars, import/export |
+| Channels | `/channels` | Audio channel management and voice assignment |
+| Generation | `/generate` | TTS generation, retry, regenerate, status SSE |
+| History | `/history` | Generation history, search, favorites, export |
+| Transcription | `/transcribe` | Whisper-based audio-to-text |
+| Stories | `/stories` | Multi-track timeline editor, audio export |
+| Effects | `/effects` | Effect presets, preview, version management |
+| Audio | `/audio`, `/samples` | Audio file serving |
+| Models | `/models` | Load, unload, download, migrate, status |
+| Tasks | `/tasks`, `/cache` | Active task tracking, cache management |
+| CUDA | `/backend/cuda-*` | CUDA binary download and management |
+
+### Quick examples

 ```bash
+# Generate speech
 curl -X POST http://localhost:17493/generate \
  -H "Content-Type: application/json" \
-  -d '{
-    "profile_id": "abc-123",
-    "text": "Hello, this is a test.",
-    "language": "en",
-    "seed": 42
-  }'
+  -d '{"text": "Hello world", "profile_id": "...", "language": "en"}'

-# Response: {"id": "gen-456", "audio_path": "/path/to/audio.wav", ...}
+# List profiles
+curl http://localhost:17493/profiles

-# Download audio
-curl http://localhost:17493/audio/gen-456 -o output.wav
+# Stream generation status (SSE)
+curl http://localhost:17493/generate/{id}/status
 ```

-### Transcribing Audio
+## Data directory
+
+```
+{data_dir}/
+  voicebox.db             # SQLite database
+  profiles/{id}/          # Voice samples per profile
+  generations/            # Generated audio files
+  cache/                  # Voice prompt cache (memory + disk)
+  backends/               # Downloaded CUDA binary (if applicable)
+```
+
+Default location is the OS-specific app data directory. Override with `--data-dir` or the `VOICEBOX_DATA_DIR` environment variable.
+
+## Code quality
+
+Linting and formatting are enforced by [ruff](https://docs.astral.sh/ruff/), configured in `pyproject.toml`. See `STYLE_GUIDE.md` for conventions.

 ```bash
-curl -X POST http://localhost:17493/transcribe \
-  -F "[email protected]" \
-  -F "language=en"
-
-# Response: {"text": "Transcribed text", "duration": 5.5}
+just check-python       # lint + format check
+just fix-python         # auto-fix lint issues + reformat
+just test               # run pytest
 ```

-## Advanced Features
+## Dependencies

-### Multi-Sample Profiles
-
-Add multiple samples to a profile for better quality:
-
-```bash
-# Add first sample
-curl -X POST http://localhost:17493/profiles/abc-123/samples \
-  -F "[email protected]" \
-  -F "reference_text=First sample"
-
-# Add second sample
-curl -X POST http://localhost:17493/profiles/abc-123/samples \
-  -F "[email protected]" \
-  -F "reference_text=Second sample"
-
-# Generation will automatically combine all samples
-```
-
-### Voice Prompt Caching
-
-Voice prompts are automatically cached for faster generation:
- First generation: ~5-10 seconds (creates prompt)
- Subsequent generations: ~1-2 seconds (uses cached prompt)
-
-Cache is stored in `data/cache/` and persists across server restarts.
-
-### VRAM Management
-
-Models are lazy-loaded and can be manually unloaded:
-
-```bash
-# Unload TTS model
-curl -X POST http://localhost:17493/models/unload
-
-# Load specific model size
-curl -X POST "http://localhost:17493/models/load?model_size=0.6B"
-```
-
-## Error Handling
-
-All endpoints return proper HTTP status codes:
-
- `200 OK`: Success
- `400 Bad Request`: Invalid input
- `404 Not Found`: Resource not found
- `500 Internal Server Error`: Server error
-
-Error responses include details:
-
-```json
-{
-  "detail": "Profile not found"
-}
-```
-
-## Performance Tips
-
-1. **Use multi-sample profiles** - Better quality than single sample
-2. **Let caching work** - Voice prompts are cached automatically
-3. **Use 0.6B model on CPU** - Faster than 1.7B with acceptable quality
-4. **Use 1.7B model on GPU** - Best quality, still fast
-5. **Unload Whisper after transcription** - Frees VRAM for TTS
-
-## TODO
-
- [ ] WebSocket support for generation progress
- [ ] Batch generation endpoint
- [ ] Audio effects (M3GAN, etc.)
- [ ] Voice design (text-to-voice)
- [ ] Audio studio timeline features
- [ ] Project management
- [ ] Authentication & rate limiting
- [ ] Export/import profiles
-
-## License
-
-See main project LICENSE.
+Runtime dependencies are in `requirements.txt`. macOS-only MLX dependencies are in `requirements-mlx.txt`. Dev tools (ruff, pytest) are installed automatically by `just setup-python`.
@@ -0,0 +1,404 @@
+# Python Style Guide
+
+Target: **Python 3.12+** | Formatter/Linter: **Ruff** | Config: `backend/pyproject.toml`
+
+This guide codifies the conventions used across the backend, and prescribes the target style for code written during the refactor (Phases 3-6). Existing code should be migrated incrementally -- don't reformat entire files in unrelated PRs.
+
+---
+
+## Formatting
+
+Enforced by `ruff format` (Black-compatible).
+
+- **Line length**: 120 characters.
+- **Indent**: 4 spaces. No tabs.
+- **Trailing commas**: Required on multi-line function signatures, arguments, collections.
+- **Quotes**: Double quotes (`"`) for strings. Single quotes are acceptable in f-string expressions and dict keys inside f-strings where avoiding escapes improves readability.
+
+Run: `ruff format backend/`
+
+---
+
+## Imports
+
+Enforced by ruff's `isort` rules (rule set `I`).
+
+**Grouping** -- three blocks separated by a blank line:
+
+```python
+import asyncio                          # 1. stdlib
+from pathlib import Path
+
+import numpy as np                      # 2. third-party
+from fastapi import APIRouter, HTTPException
+from sqlalchemy.orm import Session
+
+from backend.config import get_data_dir  # 3. local (absolute)
+from .database import get_db            #    or relative
+```
+
+**Rules:**
+- Within the `backend` package, use **relative imports** for sibling/child modules: `from .database import get_db`, `from ..utils.audio import load_audio`.
+- Absolute imports are fine for top-level references from entry points (`main.py`, `server.py`).
+- Never use wildcard imports (`from module import *`).
+- One import per line for `from X import Y` when there are 4+ names; below that, comma-separated is fine.
+- **Lazy imports** are acceptable for heavy dependencies (torch, transformers, mlx) inside functions to reduce startup time. Add a comment: `# lazy: heavy import`.
+
+---
+
+## Type Annotations
+
+Python 3.12 means we use **built-in generics and union syntax natively**. No `from __future__ import annotations`, no `typing.List`/`typing.Dict`.
+
+```python
+# Yes
+def process(items: list[str], config: dict[str, int] | None = None) -> tuple[int, str]: ...
+
+# No
+from typing import List, Dict, Optional, Tuple
+def process(items: List[str], config: Optional[Dict[str, int]] = None) -> Tuple[int, str]: ...
+```
+
+**What to annotate:**
+- All public function signatures (parameters + return type).
+- Private functions: parameters at minimum; return type encouraged.
+- Module-level variables: only when the type isn't obvious from the assignment.
+- Route handlers: parameters are annotated via FastAPI's dependency injection. Add explicit `-> SomeResponse` return types when the route doesn't use `response_model`.
+
+**Imports from `typing` that are still needed** (no built-in equivalent):
+`Literal`, `TypeAlias`, `Protocol`, `runtime_checkable`, `Callable`, `Any`, `ClassVar`, `TypeVar`, `overload`, `TYPE_CHECKING`.
+
+Use `collections.abc` for abstract types: `Sequence`, `Mapping`, `Iterable`, `Iterator`, `Generator`.
+
+---
+
+## Naming
+
+| Thing | Convention | Example |
+|-------|-----------|---------|
+| Module | `snake_case` | `task_queue.py` |
+| Class | `PascalCase` | `ProgressManager` |
+| Function / method | `snake_case` | `create_profile` |
+| Variable | `snake_case` | `sample_rate` |
+| Constant | `UPPER_SNAKE_CASE` | `DEFAULT_SAMPLE_RATE` |
+| Private | `_leading_underscore` | `_generation_queue` |
+| Type alias | `PascalCase` | `EffectChain = list[dict[str, Any]]` |
+
+**Specific conventions:**
+- Database ORM models imported with `DB` prefix alias: `from .database import VoiceProfile as DBVoiceProfile`.
+- Pydantic models use descriptive suffixes: `VoiceProfileCreate`, `VoiceProfileResponse`, `GenerationRequest`.
+- Backend classes use engine-name prefix: `MLXTTSBackend`, `PyTorchSTTBackend`.
+
+---
+
+## Docstrings
+
+**Google style**. Required on all public functions, classes, and modules.
+
+```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.
+    """
+```
+
+**Short form** is fine for simple functions:
+
+```python
+def get_db_path() -> Path:
+    """Get the path to the SQLite database file."""
+```
+
+**When to skip**: Private helpers under ~5 lines where the name and signature make intent obvious.
+
+**Module docstrings**: A single sentence at the top of every file describing its purpose.
+
+```python
+"""Voice profile CRUD operations."""
+```
+
+---
+
+## Comments
+
+Comments explain **why**, not **what**. If the code needs a comment to explain what it does, the code should be rewritten to be clearer. The exceptions are non-obvious performance choices, external constraints, and concurrency/race-condition reasoning -- those always deserve a comment.
+
+### No section dividers
+
+Do not use ASCII dividers to create visual sections in files:
+
+```python
+# No -- any of these:
+# ============================================
+# GENERATION ENDPOINTS
+# ============================================
+
+# ---------------------------------------------------------------------------
+# Device detection
+# ---------------------------------------------------------------------------
+
+# --- Load model --------------------------------------------------
+```
+
+If a file needs section dividers to be navigable, the file is too long. Split it into modules. Within a function, if you need labeled sections to follow the logic, extract those sections into named functions.
+
+### Inline comments
+
+Inline comments (end-of-line) are fine when they add information the code can't express:
+
+```python
+# Yes -- explains a non-obvious constraint or gives context:
+audio, sr = load_audio(path, sr=24000)  # Qwen expects 24kHz mono
+_generation_queue: asyncio.Queue = None  # type: ignore  # initialized at startup
+"tauri://localhost",         # Tauri webview (macOS)
+
+# No -- restates the code:
+# Check if profile name already exists
+existing = db.query(DBVoiceProfile).filter_by(name=data.name).first()
+
+# Delete from database
+db.delete(sample)
+
+# Update fields
+profile.name = data.name
+```
+
+Delete comments that narrate what the next line of code obviously does. If the function name, variable name, or method call already communicates intent, the comment is noise.
+
+### Block comments
+
+Use block comments for **why** explanations -- constraints, workarounds, non-obvious decisions:
+
+```python
+# PyInstaller + multiprocessing: child processes re-execute the frozen binary
+# with internal arguments. freeze_support() handles this and exits early.
+multiprocessing.freeze_support()
+
+# Mark any stale "generating" records as failed -- these are leftovers
+# from a previous process that was killed mid-generation.
+db.query(Generation).filter_by(status="generating").update({"status": "failed"})
+```
+
+Keep block comments tight. Two to three lines is normal. If you need a paragraph, it probably belongs in the docstring or a design doc.
+
+### Linter/type-checker suppression
+
+Always add a reason after `noqa` and `type: ignore`:
+
+```python
+import intel_extension_for_pytorch  # noqa: F401 -- side-effect import enables XPU
+_queue: asyncio.Queue = None  # type: ignore[assignment]  # initialized at startup
+```
+
+Bare `# noqa` or `# type: ignore` with no explanation are not allowed.
+
+### TODO / FIXME
+
+Use sparingly. Every `TODO` must include a brief description of what needs doing. Don't use them as a substitute for tracking work properly:
+
+```python
+# TODO: replace with async SQLAlchemy once CRUD modules are migrated (Phase 5)
+result = await asyncio.to_thread(profiles.get_profile, profile_id, db)
+```
+
+Never commit `HACK`, `XXX`, or `FIXME` -- fix the problem or file an issue.
+
+### Commented-out code
+
+Delete it. That's what git is for. If you need to document that something was intentionally removed, a short tombstone comment is acceptable:
+
+```python
+# Removed config.json-only check -- too lenient, doesn't confirm weights exist.
+```
+
+---
+
+## Error Handling
+
+The refactor is standardizing on a **two-layer pattern**:
+
+### 1. Domain layer -- raise plain exceptions
+
+CRUD modules and services raise `ValueError`, `FileNotFoundError`, or (post-refactor) custom exceptions defined in `backend/errors.py`:
+
+```python
+# backend/errors.py  (to be created in Phase 4)
+class NotFoundError(Exception):
+    """Raised when a requested resource does not exist."""
+
+class ConflictError(Exception):
+    """Raised on uniqueness constraint violations."""
+```
+
+```python
+# In a service or CRUD module:
+raise NotFoundError(f"Profile {profile_id} not found")
+```
+
+### 2. Route layer -- translate to HTTPException
+
+Route handlers catch domain exceptions and convert:
+
+```python
+@router.post("/profiles")
+async def create_profile(data: VoiceProfileCreate, db: Session = Depends(get_db)):
+    try:
+        return await profiles.create_profile(data, db)
+    except ConflictError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+```
+
+**Background tasks** catch `Exception` broadly, log with `logger.exception()`, and update the task status to `"failed"`.
+
+**Never**: silently swallow exceptions, use bare `except:`, or catch `BaseException`.
+
+---
+
+## Async
+
+### Rules for the refactor
+
+1. **Don't declare `async def` unless the function awaits something.** Several service modules still declare `async def` without awaiting -- these should be migrated to sync functions with `asyncio.to_thread()` at the route layer, or to real async SQLAlchemy.
+2. **CPU-bound work** (audio processing, numpy operations) goes through `asyncio.to_thread()`:
+   ```python
+   audio, sr = await asyncio.to_thread(load_audio, source_path)
+   ```
+3. **GPU-bound TTS inference** is serialized through the generation queue (`services/task_queue.py`). Never call a backend's `generate()` directly from a route handler.
+4. **Fire-and-forget tasks**: use `asyncio.create_task()` and track the task reference to prevent garbage collection:
+   ```python
+   task = asyncio.create_task(some_coro())
+   _background_tasks.add(task)
+   task.add_done_callback(_background_tasks.discard)
+   ```
+
+---
+
+## Logging
+
+Use the `logging` module. Not `print()`.
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.info("Loading model %s on %s", model_name, device)
+logger.warning("Cache miss for %s, downloading", repo_id)
+logger.exception("Generation %s failed")  # logs traceback automatically
+```
+
+**Rules:**
+- Use `%s`-style placeholders in log calls (not f-strings). This avoids formatting the string if the log level is filtered out.
+- Use `logger.exception()` inside `except` blocks -- it captures the traceback.
+- Logger name should be `__name__` (yields `backend.utils.audio`, etc.).
+- Existing `print()` calls should be migrated to logging as files are touched during the refactor.
+
+---
+
+## Constants
+
+- Define at **module level** in the file where they're primarily used.
+- Use `UPPER_SNAKE_CASE`.
+- Shared/cross-cutting constants (sample rates, file size limits, CORS origins) go in `backend/config.py` after Phase 6 consolidation.
+- Magic numbers in function bodies should be extracted to named constants:
+  ```python
+  # No
+  if len(audio) > 24000 * 60 * 10:
+
+  # Yes
+  MAX_AUDIO_DURATION_SAMPLES = SAMPLE_RATE * 60 * 10
+  if len(audio) > MAX_AUDIO_DURATION_SAMPLES:
+  ```
+
+---
+
+## Function Signatures
+
+- **Keyword-only arguments** (after `*`) for functions with 3+ parameters, especially when several share the same type:
+  ```python
+  def is_model_cached(
+      hf_repo: str,
+      *,
+      weight_extensions: tuple[str, ...] = (".safetensors", ".bin"),
+      required_files: list[str] | None = None,
+  ) -> bool:
+  ```
+- Parameters on **separate lines** when the signature exceeds ~100 characters or has 3+ params.
+- **Trailing comma** after the last parameter in multi-line signatures.
+- Default values inline with the parameter.
+
+---
+
+## String Formatting
+
+- **f-strings** for runtime string construction.
+- **`%s`-style** for `logging` calls (lazy evaluation).
+- **`.format()`**: avoid; f-strings are preferred.
+
+---
+
+## Testing
+
+Framework: **pytest** with `pytest-asyncio`.
+
+- Test files: `test_<module>.py` in `backend/tests/`.
+- Use `conftest.py` for shared fixtures (db sessions, test client, mock backends).
+- Group related tests in classes: `class TestProfileCRUD:`.
+- Use `@pytest.mark.asyncio` for async tests.
+- Use `@pytest.mark.parametrize` to reduce repetition.
+- Manual integration scripts stay in `tests/` but are clearly marked (filename prefix `manual_` or documented in `tests/README.md`).
+
+---
+
+## Project Layout
+
+```
+backend/
+  app.py              # FastAPI app factory, CORS, lifecycle events
+  main.py             # Entry point (imports app, runs uvicorn)
+  config.py           # Data directory paths
+  models.py           # Pydantic request/response schemas
+  server.py           # Tauri sidecar launcher, parent-pid watchdog
+  routes/             # Thin HTTP handlers (validation, delegation, response formatting)
+  services/           # Business logic, CRUD, orchestration
+  backends/           # TTS/STT engine implementations
+  database/           # ORM models, session management, migrations, seeds
+  utils/              # Shared utilities (audio, effects, caching, progress)
+  tests/              # pytest suite
+```
+
+---
+
+## Ruff Adoption
+
+`pyproject.toml` configures ruff for linting and formatting. Run:
+
+```bash
+# Lint (check)
+ruff check backend/
+
+# Lint (auto-fix)
+ruff check backend/ --fix
+
+# Format
+ruff format backend/
+```
+
+Introduce ruff fixes file-by-file as you touch them. Don't run `--fix` across the entire codebase in one shot -- that creates unreviewable diffs.
@@ -1,3 +1,3 @@
 # Backend package

-__version__ = "0.2.4"
+__version__ = "0.2.3"
@@ -0,0 +1,215 @@
+"""FastAPI application factory, middleware, and lifecycle events."""
+
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+
+
+class ColoredFormatter(logging.Formatter):
+    """Custom formatter to add colors matching uvicorn's style."""
+
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+    }
+    RESET = "\033[0m"
+
+    def format(self, record):
+        log_color = self.COLORS.get(record.levelname, self.RESET)
+        record.levelname = f"{log_color}{record.levelname}{self.RESET}"
+        return super().format(record)
+
+
+# Configure logging to match uvicorn's format with colors
+handler = logging.StreamHandler(sys.stderr)
+handler.setFormatter(ColoredFormatter("%(levelname)s:     %(message)s"))
+logging.basicConfig(
+    level=logging.INFO,
+    handlers=[handler],
+)
+
+logger = logging.getLogger(__name__)
+
+# AMD GPU environment variables must be set before torch import
+if not os.environ.get("HSA_OVERRIDE_GFX_VERSION"):
+    os.environ["HSA_OVERRIDE_GFX_VERSION"] = "10.3.0"
+if not os.environ.get("MIOPEN_LOG_LEVEL"):
+    os.environ["MIOPEN_LOG_LEVEL"] = "4"
+
+import torch
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from urllib.parse import quote
+
+from . import __version__, config, database
+from .services import tts, transcribe
+from .database import get_db
+from .utils.platform_detect import get_backend_type
+from .utils.progress import get_progress_manager
+from .services.task_queue import create_background_task, init_queue
+from .routes import register_routers
+
+
+def safe_content_disposition(disposition_type: str, filename: str) -> str:
+    """Build a Content-Disposition header safe for non-ASCII filenames.
+
+    Uses RFC 5987 ``filename*`` parameter so browsers can decode UTF-8
+    filenames while the ``filename`` fallback stays ASCII-only.
+    """
+    ascii_name = "".join(c for c in filename if c.isascii() and (c.isalnum() or c in " -_.")).strip() or "download"
+    utf8_name = quote(filename, safe="")
+    return f"{disposition_type}; filename=\"{ascii_name}\"; filename*=UTF-8''{utf8_name}"
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    application = FastAPI(
+        title="voicebox API",
+        description="Production-quality Qwen3-TTS voice cloning API",
+        version=__version__,
+    )
+
+    _configure_cors(application)
+    register_routers(application)
+    _register_lifecycle(application)
+
+    return application
+
+
+def _configure_cors(application: FastAPI) -> None:
+    """Set up CORS middleware with local-first defaults."""
+    default_origins = [
+        "http://localhost:5173",  # Vite dev server
+        "http://127.0.0.1:5173",
+        "http://localhost:17493",
+        "http://127.0.0.1:17493",
+        "tauri://localhost",  # Tauri webview (macOS)
+        "https://tauri.localhost",  # Tauri webview (Windows/Linux)
+        "http://tauri.localhost",  # Tauri webview (Windows, some builds)
+    ]
+    env_origins = os.environ.get("VOICEBOX_CORS_ORIGINS", "")
+    all_origins = default_origins + [o.strip() for o in env_origins.split(",") if o.strip()]
+
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=all_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+def _get_gpu_status() -> str:
+    """Return a human-readable string describing GPU availability."""
+    backend_type = get_backend_type()
+    if torch.cuda.is_available():
+        device_name = torch.cuda.get_device_name(0)
+        is_rocm = hasattr(torch.version, "hip") and torch.version.hip is not None
+        if is_rocm:
+            return f"ROCm ({device_name})"
+        return f"CUDA ({device_name})"
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "MPS (Apple Silicon)"
+    elif backend_type == "mlx":
+        return "Metal (Apple Silicon via MLX)"
+    return "None (CPU only)"
+
+
+def _register_lifecycle(application: FastAPI) -> None:
+    """Attach startup and shutdown event handlers."""
+
+    @application.on_event("startup")
+    async def startup_event():
+        import platform
+        import sys
+
+        logger.info("Voicebox v%s starting up", __version__)
+        logger.info(
+            "Python %s on %s %s (%s)",
+            sys.version.split()[0],
+            platform.system(),
+            platform.release(),
+            platform.machine(),
+        )
+
+        database.init_db()
+
+        from .database.session import _db_path
+
+        logger.info("Database: %s", _db_path)
+        logger.info("Data directory: %s", config.get_data_dir())
+
+        init_queue()
+
+        # Mark stale "generating" records as failed -- leftovers from a killed process
+        from sqlalchemy import text as sa_text
+
+        db = next(get_db())
+        try:
+            result = db.execute(
+                sa_text(
+                    "UPDATE generations SET status = 'failed', "
+                    "error = 'Server was shut down during generation' "
+                    "WHERE status IN ('generating', 'loading_model')"
+                )
+            )
+            if result.rowcount > 0:
+                logger.info("Marked %d stale generation(s) as failed", result.rowcount)
+
+            from .database import VoiceProfile as DBVoiceProfile, Generation as DBGeneration
+
+            profile_count = db.query(DBVoiceProfile).count()
+            generation_count = db.query(DBGeneration).count()
+            logger.info("Profiles: %d, Generations: %d", profile_count, generation_count)
+
+            db.commit()
+        except Exception as e:
+            db.rollback()
+            logger.warning("Could not clean up stale generations: %s", e)
+        finally:
+            db.close()
+
+        backend_type = get_backend_type()
+        logger.info("Backend: %s", backend_type.upper())
+        logger.info("GPU: %s", _get_gpu_status())
+
+        from .services.cuda import check_and_update_cuda_binary
+
+        create_background_task(check_and_update_cuda_binary())
+
+        try:
+            progress_manager = get_progress_manager()
+            progress_manager._set_main_loop(asyncio.get_running_loop())
+        except Exception as e:
+            logger.warning("Could not initialize progress manager event loop: %s", e)
+
+        try:
+            from huggingface_hub import constants as hf_constants
+
+            cache_dir = Path(hf_constants.HF_HUB_CACHE)
+            cache_dir.mkdir(parents=True, exist_ok=True)
+            logger.info("Model cache: %s", cache_dir)
+        except Exception as e:
+            logger.warning("Could not create HuggingFace cache directory: %s", e)
+
+        logger.info("Ready")
+
+    @application.on_event("shutdown")
+    async def shutdown_event():
+        logger.info("Voicebox server shutting down...")
+        try:
+            tts.unload_tts_model()
+        except Exception:
+            logger.exception("Failed to unload TTS model")
+        try:
+            transcribe.unload_whisper_model()
+        except Exception:
+            logger.exception("Failed to unload Whisper model")
+
+
+app = create_app()
@@ -1,25 +1,66 @@
 """
 Backend abstraction layer for TTS and STT.

-Provides a unified interface for MLX and PyTorch backends.
+Provides a unified interface for MLX and PyTorch backends,
+and a model config registry that eliminates per-engine dispatch maps.
 """

 import threading
+from dataclasses import dataclass, field
 from typing import Protocol, Optional, Tuple, List
 from typing_extensions import runtime_checkable
 import numpy as np

-from ..platform_detect import get_backend_type
+from ..utils.platform_detect import get_backend_type
+
+LANGUAGE_CODE_TO_NAME = {
+    "zh": "chinese",
+    "en": "english",
+    "ja": "japanese",
+    "ko": "korean",
+    "de": "german",
+    "fr": "french",
+    "ru": "russian",
+    "pt": "portuguese",
+    "es": "spanish",
+    "it": "italian",
+}
+
+WHISPER_HF_REPOS = {
+    "base": "openai/whisper-base",
+    "small": "openai/whisper-small",
+    "medium": "openai/whisper-medium",
+    "large": "openai/whisper-large-v3",
+    "turbo": "openai/whisper-large-v3-turbo",
+}
+
+
+@dataclass
+class ModelConfig:
+    """Declarative config for a downloadable model variant."""
+
+    model_name: str  # e.g. "luxtts", "chatterbox-tts"
+    display_name: str  # e.g. "LuxTTS (Fast, CPU-friendly)"
+    engine: str  # e.g. "luxtts", "chatterbox"
+    hf_repo_id: str  # e.g. "YatharthS/LuxTTS"
+    model_size: str = "default"
+    size_mb: int = 0
+    needs_trim: bool = False
+    supports_instruct: bool = False
+    languages: list[str] = field(default_factory=lambda: ["en"])


@runtime_checkable
 class TTSBackend(Protocol):
    """Protocol for TTS backend implementations."""
-    
+
+    # Each backend class should define MODEL_CONFIGS as a class variable:
+    # MODEL_CONFIGS: list[ModelConfig]
+
    async def load_model(self, model_size: str) -> None:
        """Load TTS model."""
        ...
-    
+
    async def create_voice_prompt(
        self,
        audio_path: str,
@@ -28,12 +69,12 @@ class TTSBackend(Protocol):
    ) -> Tuple[dict, bool]:
        """
        Create voice prompt from reference audio.
-        
+
        Returns:
            Tuple of (voice_prompt_dict, was_cached)
        """
        ...
-    
+
    async def combine_voice_prompts(
        self,
        audio_paths: List[str],
@@ -41,12 +82,12 @@ class TTSBackend(Protocol):
    ) -> Tuple[np.ndarray, str]:
        """
        Combine multiple voice prompts.
-        
+
        Returns:
            Tuple of (combined_audio_array, combined_text)
        """
        ...
-    
+
    async def generate(
        self,
        text: str,
@@ -57,24 +98,24 @@ class TTSBackend(Protocol):
    ) -> Tuple[np.ndarray, int]:
        """
        Generate audio from text.
-        
+
        Returns:
            Tuple of (audio_array, sample_rate)
        """
        ...
-    
+
    def unload_model(self) -> None:
        """Unload model to free memory."""
        ...
-    
+
    def is_loaded(self) -> bool:
        """Check if model is loaded."""
        ...
-    
+
    def _get_model_path(self, model_size: str) -> str:
        """
        Get model path for a given size.
-        
+
        Returns:
            Model path or HuggingFace Hub ID
        """
@@ -84,11 +125,11 @@ class TTSBackend(Protocol):
@runtime_checkable
 class STTBackend(Protocol):
    """Protocol for STT (Speech-to-Text) backend implementations."""
-    
+
    async def load_model(self, model_size: str) -> None:
        """Load STT model."""
        ...
-    
+
    async def transcribe(
        self,
        audio_path: str,
@@ -96,16 +137,16 @@ class STTBackend(Protocol):
    ) -> str:
        """
        Transcribe audio to text.
-        
+
        Returns:
            Transcribed text
        """
        ...
-    
+
    def unload_model(self) -> None:
        """Unload model to free memory."""
        ...
-    
+
    def is_loaded(self) -> bool:
        """Check if model is loaded."""
        ...
@@ -117,7 +158,8 @@ _tts_backends: dict[str, TTSBackend] = {}
 _tts_backends_lock = threading.Lock()
 _stt_backend: Optional[STTBackend] = None

-# Supported TTS engines
+# Supported TTS engines — keyed by engine name, value is the backend class import path.
+# The factory function uses this for the if/elif chain; the model configs live on the backend classes.
 TTS_ENGINES = {
    "qwen": "Qwen TTS",
    "luxtts": "LuxTTS",
@@ -126,10 +168,277 @@ TTS_ENGINES = {
 }


+def _get_qwen_model_configs() -> list[ModelConfig]:
+    """Return Qwen model configs with backend-aware HF repo IDs."""
+    backend_type = get_backend_type()
+    if backend_type == "mlx":
+        repo_1_7b = "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16"
+        repo_0_6b = "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16"  # 0.6B not available in MLX, falls back
+    else:
+        repo_1_7b = "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
+        repo_0_6b = "Qwen/Qwen3-TTS-12Hz-0.6B-Base"
+
+    return [
+        ModelConfig(
+            model_name="qwen-tts-1.7B",
+            display_name="Qwen TTS 1.7B",
+            engine="qwen",
+            hf_repo_id=repo_1_7b,
+            model_size="1.7B",
+            size_mb=3500,
+            supports_instruct=False,  # Base model drops instruct silently
+            languages=["zh", "en", "ja", "ko", "de", "fr", "ru", "pt", "es", "it"],
+        ),
+        ModelConfig(
+            model_name="qwen-tts-0.6B",
+            display_name="Qwen TTS 0.6B",
+            engine="qwen",
+            hf_repo_id=repo_0_6b,
+            model_size="0.6B",
+            size_mb=1200,
+            supports_instruct=False,
+            languages=["zh", "en", "ja", "ko", "de", "fr", "ru", "pt", "es", "it"],
+        ),
+    ]
+
+
+def _get_non_qwen_tts_configs() -> list[ModelConfig]:
+    """Return model configs for non-Qwen TTS engines.
+
+    These are static — no backend-type branching needed.
+    """
+    return [
+        ModelConfig(
+            model_name="luxtts",
+            display_name="LuxTTS (Fast, CPU-friendly)",
+            engine="luxtts",
+            hf_repo_id="YatharthS/LuxTTS",
+            size_mb=300,
+            languages=["en"],
+        ),
+        ModelConfig(
+            model_name="chatterbox-tts",
+            display_name="Chatterbox TTS (Multilingual)",
+            engine="chatterbox",
+            hf_repo_id="ResembleAI/chatterbox",
+            size_mb=3200,
+            needs_trim=True,
+            languages=[
+                "zh",
+                "en",
+                "ja",
+                "ko",
+                "de",
+                "fr",
+                "ru",
+                "pt",
+                "es",
+                "it",
+                "he",
+                "ar",
+                "da",
+                "el",
+                "fi",
+                "hi",
+                "ms",
+                "nl",
+                "no",
+                "pl",
+                "sv",
+                "sw",
+                "tr",
+            ],
+        ),
+        ModelConfig(
+            model_name="chatterbox-turbo",
+            display_name="Chatterbox Turbo (English, Tags)",
+            engine="chatterbox_turbo",
+            hf_repo_id="ResembleAI/chatterbox-turbo",
+            size_mb=1500,
+            needs_trim=True,
+            languages=["en"],
+        ),
+    ]
+
+
+def _get_whisper_configs() -> list[ModelConfig]:
+    """Return Whisper STT model configs."""
+    return [
+        ModelConfig(
+            model_name="whisper-base",
+            display_name="Whisper Base",
+            engine="whisper",
+            hf_repo_id="openai/whisper-base",
+            model_size="base",
+        ),
+        ModelConfig(
+            model_name="whisper-small",
+            display_name="Whisper Small",
+            engine="whisper",
+            hf_repo_id="openai/whisper-small",
+            model_size="small",
+        ),
+        ModelConfig(
+            model_name="whisper-medium",
+            display_name="Whisper Medium",
+            engine="whisper",
+            hf_repo_id="openai/whisper-medium",
+            model_size="medium",
+        ),
+        ModelConfig(
+            model_name="whisper-large",
+            display_name="Whisper Large",
+            engine="whisper",
+            hf_repo_id="openai/whisper-large-v3",
+            model_size="large",
+        ),
+        ModelConfig(
+            model_name="whisper-turbo",
+            display_name="Whisper Turbo",
+            engine="whisper",
+            hf_repo_id="openai/whisper-large-v3-turbo",
+            model_size="turbo",
+        ),
+    ]
+
+
+def get_all_model_configs() -> list[ModelConfig]:
+    """Return the full list of model configs (TTS + STT)."""
+    return _get_qwen_model_configs() + _get_non_qwen_tts_configs() + _get_whisper_configs()
+
+
+def get_tts_model_configs() -> list[ModelConfig]:
+    """Return only TTS model configs."""
+    return _get_qwen_model_configs() + _get_non_qwen_tts_configs()
+
+
+# Lookup helpers — these replace the if/elif chains in main.py
+
+
+def get_model_config(model_name: str) -> Optional[ModelConfig]:
+    """Look up a model config by model_name."""
+    for cfg in get_all_model_configs():
+        if cfg.model_name == model_name:
+            return cfg
+    return None
+
+
+def engine_needs_trim(engine: str) -> bool:
+    """Whether this engine's output should be run through trim_tts_output."""
+    for cfg in get_tts_model_configs():
+        if cfg.engine == engine:
+            return cfg.needs_trim
+    return False
+
+
+def engine_has_model_sizes(engine: str) -> bool:
+    """Whether this engine supports multiple model sizes (only Qwen currently)."""
+    configs = [c for c in get_tts_model_configs() if c.engine == engine]
+    return len(configs) > 1
+
+
+async def load_engine_model(engine: str, model_size: str = "default") -> None:
+    """Load a model for the given engine, handling the Qwen model_size special case."""
+    backend = get_tts_backend_for_engine(engine)
+    if engine == "qwen":
+        await backend.load_model_async(model_size)
+    else:
+        await backend.load_model()
+
+
+async def ensure_model_cached_or_raise(engine: str, model_size: str = "default") -> None:
+    """Check if a model is cached, raise HTTPException if not. Used by streaming endpoint."""
+    from fastapi import HTTPException
+
+    backend = get_tts_backend_for_engine(engine)
+    cfg = None
+    for c in get_tts_model_configs():
+        if c.engine == engine and c.model_size == model_size:
+            cfg = c
+            break
+
+    if engine == "qwen":
+        if not backend._is_model_cached(model_size):
+            raise HTTPException(
+                status_code=400,
+                detail=f"Model {model_size} is not downloaded yet. Use /generate to trigger a download.",
+            )
+    else:
+        if not backend._is_model_cached():
+            display = cfg.display_name if cfg else engine
+            raise HTTPException(
+                status_code=400,
+                detail=f"{display} model is not downloaded yet. Use /generate to trigger a download.",
+            )
+
+
+def unload_model_by_config(config: ModelConfig) -> bool:
+    """Unload a model given its config. Returns True if it was loaded, False otherwise."""
+    from . import get_tts_backend_for_engine
+    from ..services import tts, transcribe
+
+    if config.engine == "whisper":
+        whisper_model = transcribe.get_whisper_model()
+        if whisper_model.is_loaded() and whisper_model.model_size == config.model_size:
+            transcribe.unload_whisper_model()
+            return True
+        return False
+
+    if config.engine == "qwen":
+        tts_model = tts.get_tts_model()
+        loaded_size = getattr(tts_model, "_current_model_size", None) or getattr(tts_model, "model_size", None)
+        if tts_model.is_loaded() and loaded_size == config.model_size:
+            tts.unload_tts_model()
+            return True
+        return False
+
+    # All other TTS engines
+    backend = get_tts_backend_for_engine(config.engine)
+    if backend.is_loaded():
+        backend.unload_model()
+        return True
+    return False
+
+
+def check_model_loaded(config: ModelConfig) -> bool:
+    """Check if a model is currently loaded."""
+    from . import get_tts_backend_for_engine
+    from ..services import tts, transcribe
+
+    try:
+        if config.engine == "whisper":
+            whisper_model = transcribe.get_whisper_model()
+            return whisper_model.is_loaded() and getattr(whisper_model, "model_size", None) == config.model_size
+
+        if config.engine == "qwen":
+            tts_model = tts.get_tts_model()
+            loaded_size = getattr(tts_model, "_current_model_size", None) or getattr(tts_model, "model_size", None)
+            return tts_model.is_loaded() and loaded_size == config.model_size
+
+        backend = get_tts_backend_for_engine(config.engine)
+        return backend.is_loaded()
+    except Exception:
+        return False
+
+
+def get_model_load_func(config: ModelConfig):
+    """Return a callable that loads/downloads the model."""
+    from . import get_tts_backend_for_engine
+    from ..services import tts, transcribe
+
+    if config.engine == "whisper":
+        return lambda: transcribe.get_whisper_model().load_model(config.model_size)
+
+    if config.engine == "qwen":
+        return lambda: tts.get_tts_model().load_model(config.model_size)
+
+    return lambda: get_tts_backend_for_engine(config.engine).load_model()
+
+
 def get_tts_backend() -> TTSBackend:
    """
    Get or create the default (Qwen) TTS backend instance based on platform.
-    
+
    Returns:
        TTS backend instance (MLX or PyTorch)
    """
@@ -139,45 +448,50 @@ def get_tts_backend() -> TTSBackend:
 def get_tts_backend_for_engine(engine: str) -> TTSBackend:
    """
    Get or create a TTS backend for the given engine.
-    
+
    Args:
-        engine: Engine name ("qwen" or "luxtts")
-    
+        engine: Engine name (e.g. "qwen", "luxtts", "chatterbox", "chatterbox_turbo")
+
    Returns:
        TTS backend instance
    """
    global _tts_backends
-    
+
    # Fast path: check without lock
    if engine in _tts_backends:
        return _tts_backends[engine]
-    
+
    # Slow path: create with lock to avoid duplicate instantiation
    with _tts_backends_lock:
        # Double-check after acquiring lock
        if engine in _tts_backends:
            return _tts_backends[engine]
-        
+
        if engine == "qwen":
            backend_type = get_backend_type()
            if backend_type == "mlx":
                from .mlx_backend import MLXTTSBackend
+
                backend = MLXTTSBackend()
            else:
                from .pytorch_backend import PyTorchTTSBackend
+
                backend = PyTorchTTSBackend()
        elif engine == "luxtts":
            from .luxtts_backend import LuxTTSBackend
+
            backend = LuxTTSBackend()
        elif engine == "chatterbox":
            from .chatterbox_backend import ChatterboxTTSBackend
+
            backend = ChatterboxTTSBackend()
        elif engine == "chatterbox_turbo":
            from .chatterbox_turbo_backend import ChatterboxTurboTTSBackend
+
            backend = ChatterboxTurboTTSBackend()
        else:
            raise ValueError(f"Unknown TTS engine: {engine}. Supported: {list(TTS_ENGINES.keys())}")
-        
+
        _tts_backends[engine] = backend
        return backend

@@ -185,22 +499,24 @@ def get_tts_backend_for_engine(engine: str) -> TTSBackend:
 def get_stt_backend() -> STTBackend:
    """
    Get or create STT backend instance based on platform.
-    
+
    Returns:
        STT backend instance (MLX or PyTorch)
    """
    global _stt_backend
-    
+
    if _stt_backend is None:
        backend_type = get_backend_type()
-        
+
        if backend_type == "mlx":
            from .mlx_backend import MLXSTTBackend
+
            _stt_backend = MLXSTTBackend()
        else:
            from .pytorch_backend import PyTorchSTTBackend
+
            _stt_backend = PyTorchSTTBackend()
-    
+
    return _stt_backend


@@ -0,0 +1,258 @@
+"""
+Shared utilities for TTS/STT backend implementations.
+
+Eliminates duplication of cache checking, device detection,
+voice prompt combination, and model loading progress tracking.
+"""
+
+import logging
+import platform
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Callable, List, Optional, Tuple
+
+import numpy as np
+
+from ..utils.audio import normalize_audio, load_audio
+from ..utils.progress import get_progress_manager
+from ..utils.hf_progress import HFProgressTracker, create_hf_progress_callback
+from ..utils.tasks import get_task_manager
+
+logger = logging.getLogger(__name__)
+
+
+def is_model_cached(
+    hf_repo: str,
+    *,
+    weight_extensions: tuple[str, ...] = (".safetensors", ".bin"),
+    required_files: Optional[list[str]] = None,
+) -> bool:
+    """
+    Check if a HuggingFace model is fully cached locally.
+
+    Args:
+        hf_repo: HuggingFace repo ID (e.g. "Qwen/Qwen3-TTS-12Hz-1.7B-Base")
+        weight_extensions: File extensions that count as model weights.
+        required_files: If set, check that these specific filenames exist
+                        in snapshots instead of checking by extension.
+
+    Returns:
+        True if model is fully cached, False if missing or incomplete.
+    """
+    try:
+        from huggingface_hub import constants as hf_constants
+
+        repo_cache = Path(hf_constants.HF_HUB_CACHE) / ("models--" + hf_repo.replace("/", "--"))
+
+        if not repo_cache.exists():
+            return False
+
+        # Incomplete blobs mean a download is still in progress
+        blobs_dir = repo_cache / "blobs"
+        if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
+            logger.debug(f"Found .incomplete files for {hf_repo}")
+            return False
+
+        snapshots_dir = repo_cache / "snapshots"
+        if not snapshots_dir.exists():
+            return False
+
+        if required_files:
+            # Check that every required filename exists somewhere in snapshots
+            for fname in required_files:
+                if not any(snapshots_dir.rglob(fname)):
+                    return False
+            return True
+
+        # Check that at least one weight file exists
+        for ext in weight_extensions:
+            if any(snapshots_dir.rglob(f"*{ext}")):
+                return True
+
+        logger.debug(f"No model weights found for {hf_repo}")
+        return False
+
+    except Exception as e:
+        logger.warning(f"Error checking cache for {hf_repo}: {e}")
+        return False
+
+
+def get_torch_device(
+    *,
+    allow_xpu: bool = False,
+    allow_directml: bool = False,
+    allow_mps: bool = False,
+    force_cpu_on_mac: bool = False,
+) -> str:
+    """
+    Detect the best available torch device.
+
+    Args:
+        allow_xpu: Check for Intel XPU (IPEX) support.
+        allow_directml: Check for DirectML (Windows) support.
+        allow_mps: Allow MPS (Apple Silicon). If False, MPS falls back to CPU.
+        force_cpu_on_mac: Force CPU on macOS regardless of GPU availability.
+    """
+    if force_cpu_on_mac and platform.system() == "Darwin":
+        return "cpu"
+
+    import torch
+
+    if torch.cuda.is_available():
+        return "cuda"
+
+    if allow_xpu:
+        try:
+            import intel_extension_for_pytorch  # noqa: F401
+
+            if hasattr(torch, "xpu") and torch.xpu.is_available():
+                return "xpu"
+        except ImportError:
+            pass
+
+    if allow_directml:
+        try:
+            import torch_directml
+
+            if torch_directml.device_count() > 0:
+                return torch_directml.device(0)
+        except ImportError:
+            pass
+
+    if allow_mps:
+        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            return "mps"
+
+    return "cpu"
+
+
+async def combine_voice_prompts(
+    audio_paths: List[str],
+    reference_texts: List[str],
+    *,
+    sample_rate: Optional[int] = None,
+) -> Tuple[np.ndarray, str]:
+    """
+    Combine multiple reference audio samples into one.
+
+    Loads each audio file, normalizes, concatenates, and joins texts.
+
+    Args:
+        audio_paths: Paths to reference audio files.
+        reference_texts: Corresponding transcripts.
+        sample_rate: If set, resample audio to this rate during loading.
+    """
+    combined_audio = []
+
+    for path in audio_paths:
+        kwargs = {"sample_rate": sample_rate} if sample_rate else {}
+        audio, _sr = load_audio(path, **kwargs)
+        audio = normalize_audio(audio)
+        combined_audio.append(audio)
+
+    mixed = np.concatenate(combined_audio)
+    mixed = normalize_audio(mixed)
+    combined_text = " ".join(reference_texts)
+
+    return mixed, combined_text
+
+
+@contextmanager
+def model_load_progress(
+    model_name: str,
+    is_cached: bool,
+    filter_non_downloads: Optional[bool] = None,
+):
+    """
+    Context manager for model loading with HF download progress tracking.
+
+    Handles the tqdm patching, progress_manager/task_manager lifecycle,
+    and error reporting that every backend duplicates.
+
+    Args:
+        model_name: Progress tracking key (e.g. "qwen-tts-1.7B", "whisper-base").
+        is_cached: Whether the model is already downloaded.
+        filter_non_downloads: Whether to filter non-download tqdm bars.
+                              Defaults to `is_cached`.
+
+    Yields:
+        The tracker context (already entered). The caller loads the model
+        inside the `with` block. The tqdm patch is torn down on exit.
+
+    Usage:
+        with model_load_progress("qwen-tts-1.7B", is_cached) as ctx:
+            self.model = SomeModel.from_pretrained(...)
+    """
+    if filter_non_downloads is None:
+        filter_non_downloads = is_cached
+
+    progress_manager = get_progress_manager()
+    task_manager = get_task_manager()
+
+    progress_callback = create_hf_progress_callback(model_name, progress_manager)
+    tracker = HFProgressTracker(progress_callback, filter_non_downloads=filter_non_downloads)
+
+    tracker_context = tracker.patch_download()
+    tracker_context.__enter__()
+
+    if not is_cached:
+        task_manager.start_download(model_name)
+        progress_manager.update_progress(
+            model_name=model_name,
+            current=0,
+            total=0,
+            filename="Connecting to HuggingFace...",
+            status="downloading",
+        )
+
+    try:
+        yield tracker_context
+    except Exception as e:
+        # Report error to both managers
+        progress_manager.mark_error(model_name, str(e))
+        task_manager.error_download(model_name, str(e))
+        raise
+    else:
+        # Only mark complete if we were tracking a download
+        if not is_cached:
+            progress_manager.mark_complete(model_name)
+            task_manager.complete_download(model_name)
+    finally:
+        tracker_context.__exit__(None, None, None)
+
+
+def patch_chatterbox_f32(model) -> None:
+    """
+    Patch float64 -> float32 dtype mismatches in upstream chatterbox.
+
+    librosa.load returns float64 numpy arrays. Multiple upstream code paths
+    convert these to torch tensors via torch.from_numpy() without casting,
+    then matmul against float32 model weights. This patches the two known
+    entry points:
+
+    1. S3Tokenizer.log_mel_spectrogram — audio tensor hits _mel_filters (f32)
+    2. VoiceEncoder.forward — float64 mel spectrograms hit LSTM weights (f32)
+    """
+    import types
+
+    # Patch S3Tokenizer
+    _tokzr = model.s3gen.tokenizer
+    _orig_log_mel = _tokzr.log_mel_spectrogram.__func__
+
+    def _f32_log_mel(self_tokzr, audio, padding=0):
+        import torch as _torch
+
+        if _torch.is_tensor(audio):
+            audio = audio.float()
+        return _orig_log_mel(self_tokzr, audio, padding)
+
+    _tokzr.log_mel_spectrogram = types.MethodType(_f32_log_mel, _tokzr)
+
+    # Patch VoiceEncoder
+    _ve = model.ve
+    _orig_ve_forward = _ve.forward.__func__
+
+    def _f32_ve_forward(self_ve, mels):
+        return _orig_ve_forward(self_ve, mels.float())
+
+    _ve.forward = types.MethodType(_f32_ve_forward, _ve)
@@ -8,7 +8,6 @@ on macOS due to known MPS tensor issues.

 import asyncio
 import logging
-import platform
 import threading
 from pathlib import Path
 from typing import ClassVar, List, Optional, Tuple
@@ -16,9 +15,13 @@ from typing import ClassVar, List, Optional, Tuple
 import numpy as np

 from . import TTSBackend
-from ..utils.audio import normalize_audio, load_audio
-from ..utils.progress import get_progress_manager
-from ..utils.tasks import get_task_manager
+from .base import (
+    is_model_cached,
+    get_torch_device,
+    combine_voice_prompts as _combine_voice_prompts,
+    model_load_progress,
+    patch_chatterbox_f32,
+)

 logger = logging.getLogger(__name__)

@@ -45,17 +48,7 @@ class ChatterboxTTSBackend:
        self._model_load_lock = asyncio.Lock()

    def _get_device(self) -> str:
-        """Get the best available device. Forces CPU on macOS (MPS issue)."""
-        if platform.system() == "Darwin":
-            return "cpu"
-        try:
-            import torch
-
-            if torch.cuda.is_available():
-                return "cuda"
-        except ImportError:
-            pass
-        return "cpu"
+        return get_torch_device(force_cpu_on_mac=True)

    def is_loaded(self) -> bool:
        return self.model is not None
@@ -64,33 +57,7 @@ class ChatterboxTTSBackend:
        return CHATTERBOX_HF_REPO

    def _is_model_cached(self, model_size: str = "default") -> bool:
-        """Check if the Chatterbox multilingual model is cached locally."""
-        try:
-            from huggingface_hub import constants as hf_constants
-
-            repo_cache = Path(hf_constants.HF_HUB_CACHE) / (
-                "models--" + CHATTERBOX_HF_REPO.replace("/", "--")
-            )
-
-            if not repo_cache.exists():
-                return False
-
-            blobs_dir = repo_cache / "blobs"
-            if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
-                return False
-
-            # Check for multilingual weight files
-            snapshots_dir = repo_cache / "snapshots"
-            if snapshots_dir.exists():
-                for fname in _MTL_WEIGHT_FILES:
-                    if not any(snapshots_dir.rglob(fname)):
-                        return False
-                return True
-
-            return False
-        except Exception as e:
-            logger.warning(f"Error checking Chatterbox cache: {e}")
-            return False
+        return is_model_cached(CHATTERBOX_HF_REPO, required_files=_MTL_WEIGHT_FILES)

    async def load_model(self, model_size: str = "default") -> None:
        """Load the Chatterbox multilingual model."""
@@ -103,132 +70,45 @@ class ChatterboxTTSBackend:

    def _load_model_sync(self):
        """Synchronous model loading."""
-        from ..utils.hf_progress import HFProgressTracker, create_hf_progress_callback
-
-        progress_manager = get_progress_manager()
-        task_manager = get_task_manager()
        model_name = "chatterbox-tts"
-
        is_cached = self._is_model_cached()

-        # Set up HF progress tracking (intercepts tqdm for file-level progress)
-        progress_callback = create_hf_progress_callback(model_name, progress_manager)
-        tracker = HFProgressTracker(progress_callback, filter_non_downloads=is_cached)
-        tracker_context = tracker.patch_download()
-        tracker_context.__enter__()
-
-        if not is_cached:
-            task_manager.start_download(model_name)
-            progress_manager.update_progress(
-                model_name=model_name,
-                current=0,
-                total=0,
-                filename="Connecting to HuggingFace...",
-                status="downloading",
-            )
-
-        try:
+        with model_load_progress(model_name, is_cached):
            device = self._get_device()
            self._device = device
-
            logger.info(f"Loading Chatterbox Multilingual TTS on {device}...")

            import torch
            from chatterbox.mtl_tts import ChatterboxMultilingualTTS

-            # Load into a local variable first, apply all patches, then
-            # assign to self.model.  This avoids leaving a half-initialised
-            # model on self.model if any patch step raises an exception.
-            #
-            # Monkey-patch torch.load for CPU loading. The model's .pt files
-            # were saved on CUDA; from_pretrained() doesn't pass map_location
-            # so loading on CPU fails without this.
-            try:
-                if device == "cpu":
-                    _orig_torch_load = torch.load
+            if device == "cpu":
+                _orig_torch_load = torch.load

-                    def _patched_load(*args, **kwargs):
-                        kwargs.setdefault("map_location", "cpu")
-                        return _orig_torch_load(*args, **kwargs)
+                def _patched_load(*args, **kwargs):
+                    kwargs.setdefault("map_location", "cpu")
+                    return _orig_torch_load(*args, **kwargs)

-                    with ChatterboxTTSBackend._load_lock:
-                        torch.load = _patched_load
-                        try:
-                            model = ChatterboxMultilingualTTS.from_pretrained(
-                                device=device,
-                            )
-                        finally:
-                            torch.load = _orig_torch_load
-                else:
-                    model = ChatterboxMultilingualTTS.from_pretrained(
-                        device=device,
-                    )
-            finally:
-                tracker_context.__exit__(None, None, None)
+                with ChatterboxTTSBackend._load_lock:
+                    torch.load = _patched_load
+                    try:
+                        model = ChatterboxMultilingualTTS.from_pretrained(device=device)
+                    finally:
+                        torch.load = _orig_torch_load
+            else:
+                model = ChatterboxMultilingualTTS.from_pretrained(device=device)

-            # Fix: transformers >= 4.36 defaults LlamaModel to sdpa attention
-            # which doesn't support output_attentions=True (needed by
-            # Chatterbox's AlignmentStreamAnalyzer). Force eager attention.
+            # Fix sdpa attention for output_attentions support
            t3_tfmr = model.t3.tfmr
-            if hasattr(t3_tfmr, "config") and hasattr(
-                t3_tfmr.config, "_attn_implementation"
-            ):
+            if hasattr(t3_tfmr, "config") and hasattr(t3_tfmr.config, "_attn_implementation"):
                t3_tfmr.config._attn_implementation = "eager"
                for layer in getattr(t3_tfmr, "layers", []):
                    if hasattr(layer, "self_attn"):
                        layer.self_attn._attn_implementation = "eager"

-            if not is_cached:
-                progress_manager.mark_complete(model_name)
-                task_manager.complete_download(model_name)
-
-            # Patch float64 → float32 dtype mismatches in upstream chatterbox.
-            # librosa.load returns float64 numpy; multiple upstream code paths
-            # convert it to a torch tensor via torch.from_numpy() without
-            # casting, then matmul it against float32 model weights.
-            import types
-
-            # Patch S3Tokenizer (used by s3gen.tokenizer)
-            _tokzr = model.s3gen.tokenizer
-            _orig_log_mel = _tokzr.log_mel_spectrogram.__func__
-
-            def _f32_log_mel(self_tokzr, audio, padding=0):
-                import torch as _torch
-                if _torch.is_tensor(audio):
-                    audio = audio.float()
-                return _orig_log_mel(self_tokzr, audio, padding)
-
-            _tokzr.log_mel_spectrogram = types.MethodType(_f32_log_mel, _tokzr)
-
-            # Patch VoiceEncoder
-            _ve = model.ve
-            _orig_ve_forward = _ve.forward.__func__
-
-            def _f32_ve_forward(self_ve, mels):
-                return _orig_ve_forward(self_ve, mels.float())
-
-            _ve.forward = types.MethodType(_f32_ve_forward, _ve)
-
-            # All patches applied successfully — publish the model
+            patch_chatterbox_f32(model)
            self.model = model

-            logger.info("Chatterbox Multilingual TTS loaded successfully")
-
-        except ImportError as e:
-            logger.error(
-                "chatterbox-tts package not found. "
-                "Install with: pip install chatterbox-tts"
-            )
-            if not is_cached:
-                progress_manager.mark_error(model_name, str(e))
-                task_manager.error_download(model_name, str(e))
-            raise
-        except Exception as e:
-            logger.error(f"Failed to load Chatterbox: {e}")
-            if not is_cached:
-                progress_manager.mark_error(model_name, str(e))
-                task_manager.error_download(model_name, str(e))
-            raise
+        logger.info("Chatterbox Multilingual TTS loaded successfully")

    def unload_model(self) -> None:
        """Unload model to free memory."""
@@ -267,17 +147,7 @@ class ChatterboxTTSBackend:
        audio_paths: List[str],
        reference_texts: List[str],
    ) -> Tuple[np.ndarray, str]:
-        """Combine multiple reference samples."""
-        combined_audio = []
-        for path in audio_paths:
-            audio, _sr = load_audio(path)
-            audio = normalize_audio(audio)
-            combined_audio.append(audio)
-
-        mixed = np.concatenate(combined_audio)
-        mixed = normalize_audio(mixed)
-        combined_text = " ".join(reference_texts)
-        return mixed, combined_text
+        return await _combine_voice_prompts(audio_paths, reference_texts)

    # Per-language generation defaults. Lower temp + higher cfg = clearer speech.
    _LANG_DEFAULTS: ClassVar[dict] = {
@@ -8,7 +8,6 @@ Forces CPU on macOS due to known MPS tensor issues.

 import asyncio
 import logging
-import platform
 import threading
 from pathlib import Path
 from typing import ClassVar, List, Optional, Tuple
@@ -16,9 +15,13 @@ from typing import ClassVar, List, Optional, Tuple
 import numpy as np

 from . import TTSBackend
-from ..utils.audio import normalize_audio, load_audio
-from ..utils.progress import get_progress_manager
-from ..utils.tasks import get_task_manager
+from .base import (
+    is_model_cached,
+    get_torch_device,
+    combine_voice_prompts as _combine_voice_prompts,
+    model_load_progress,
+    patch_chatterbox_f32,
+)

 logger = logging.getLogger(__name__)

@@ -45,17 +48,7 @@ class ChatterboxTurboTTSBackend:
        self._model_load_lock = asyncio.Lock()

    def _get_device(self) -> str:
-        """Get the best available device. Forces CPU on macOS (MPS issue)."""
-        if platform.system() == "Darwin":
-            return "cpu"
-        try:
-            import torch
-
-            if torch.cuda.is_available():
-                return "cuda"
-        except ImportError:
-            pass
-        return "cpu"
+        return get_torch_device(force_cpu_on_mac=True)

    def is_loaded(self) -> bool:
        return self.model is not None
@@ -64,33 +57,7 @@ class ChatterboxTurboTTSBackend:
        return CHATTERBOX_TURBO_HF_REPO

    def _is_model_cached(self, model_size: str = "default") -> bool:
-        """Check if the Chatterbox Turbo model is cached locally."""
-        try:
-            from huggingface_hub import constants as hf_constants
-
-            repo_cache = Path(hf_constants.HF_HUB_CACHE) / (
-                "models--" + CHATTERBOX_TURBO_HF_REPO.replace("/", "--")
-            )
-
-            if not repo_cache.exists():
-                return False
-
-            blobs_dir = repo_cache / "blobs"
-            if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
-                return False
-
-            # Check for turbo weight files
-            snapshots_dir = repo_cache / "snapshots"
-            if snapshots_dir.exists():
-                for fname in _TURBO_WEIGHT_FILES:
-                    if not any(snapshots_dir.rglob(fname)):
-                        return False
-                return True
-
-            return False
-        except Exception as e:
-            logger.warning(f"Error checking Chatterbox Turbo cache: {e}")
-            return False
+        return is_model_cached(CHATTERBOX_TURBO_HF_REPO, required_files=_TURBO_WEIGHT_FILES)

    async def load_model(self, model_size: str = "default") -> None:
        """Load the Chatterbox Turbo model."""
@@ -103,59 +70,24 @@ class ChatterboxTurboTTSBackend:

    def _load_model_sync(self):
        """Synchronous model loading."""
-        from ..utils.hf_progress import HFProgressTracker, create_hf_progress_callback
-
-        progress_manager = get_progress_manager()
-        task_manager = get_task_manager()
        model_name = "chatterbox-turbo"
-
        is_cached = self._is_model_cached()

-        # Set up HF progress tracking (intercepts tqdm for file-level progress)
-        progress_callback = create_hf_progress_callback(model_name, progress_manager)
-        tracker = HFProgressTracker(progress_callback, filter_non_downloads=is_cached)
-        tracker_context = tracker.patch_download()
-        tracker_context.__enter__()
-
-        if not is_cached:
-            task_manager.start_download(model_name)
-            progress_manager.update_progress(
-                model_name=model_name,
-                current=0,
-                total=0,
-                filename="Connecting to HuggingFace...",
-                status="downloading",
-            )
-
-        try:
+        with model_load_progress(model_name, is_cached):
            device = self._get_device()
            self._device = device
-
            logger.info(f"Loading Chatterbox Turbo TTS on {device}...")

            import torch
            from huggingface_hub import snapshot_download
            from chatterbox.tts_turbo import ChatterboxTurboTTS

-            # Download model files ourselves so we can pass token=None
-            # (upstream from_pretrained passes token=True which requires
-            # a stored HF token even though the repo is public).
-            try:
-                local_path = snapshot_download(
-                    repo_id=CHATTERBOX_TURBO_HF_REPO,
-                    token=None,
-                    allow_patterns=[
-                        "*.safetensors", "*.json", "*.txt", "*.pt", "*.model",
-                    ],
-                )
-            finally:
-                tracker_context.__exit__(None, None, None)
+            local_path = snapshot_download(
+                repo_id=CHATTERBOX_TURBO_HF_REPO,
+                token=None,
+                allow_patterns=["*.safetensors", "*.json", "*.txt", "*.pt", "*.model"],
+            )

-            # Monkey-patch torch.load for CPU loading. The model's .pt files
-            # were saved on CUDA; from_local() doesn't pass map_location
-            # so loading on CPU fails without this.
-            # Load into a local var, apply patches, then publish to
-            # self.model so a failed patch doesn't leave us half-initialised.
            if device == "cpu":
                _orig_torch_load = torch.load

@@ -166,73 +98,16 @@ class ChatterboxTurboTTSBackend:
                with ChatterboxTurboTTSBackend._load_lock:
                    torch.load = _patched_load
                    try:
-                        model = ChatterboxTurboTTS.from_local(
-                            local_path, device,
-                        )
+                        model = ChatterboxTurboTTS.from_local(local_path, device)
                    finally:
                        torch.load = _orig_torch_load
            else:
-                model = ChatterboxTurboTTS.from_local(
-                    local_path, device,
-                )
+                model = ChatterboxTurboTTS.from_local(local_path, device)

-            if not is_cached:
-                progress_manager.mark_complete(model_name)
-                task_manager.complete_download(model_name)
-
-            # Patch float64 → float32 dtype mismatches in upstream chatterbox.
-            # librosa.load returns float64 numpy; multiple upstream code paths
-            # convert it to a torch tensor via torch.from_numpy() without
-            # casting, then matmul it against float32 model weights.
-            # We patch the two known entry points:
-            #
-            # 1. S3Tokenizer.log_mel_spectrogram — the audio tensor from
-            #    librosa hits _mel_filters (float32) in a matmul.
-            # 2. VoiceEncoder.forward — float64 mel spectrograms hit the
-            #    float32 LSTM weights.
-            import types
-
-            # Patch S3Tokenizer (used by s3gen.tokenizer)
-            _tokzr = model.s3gen.tokenizer
-            _orig_log_mel = _tokzr.log_mel_spectrogram.__func__
-
-            def _f32_log_mel(self_tokzr, audio, padding=0):
-                import torch as _torch
-                if _torch.is_tensor(audio):
-                    audio = audio.float()
-                return _orig_log_mel(self_tokzr, audio, padding)
-
-            _tokzr.log_mel_spectrogram = types.MethodType(_f32_log_mel, _tokzr)
-
-            # Patch VoiceEncoder
-            _ve = model.ve
-            _orig_ve_forward = _ve.forward.__func__
-
-            def _f32_ve_forward(self_ve, mels):
-                return _orig_ve_forward(self_ve, mels.float())
-
-            _ve.forward = types.MethodType(_f32_ve_forward, _ve)
-
-            # Only publish after all patches succeed
+            patch_chatterbox_f32(model)
            self.model = model

-            logger.info("Chatterbox Turbo TTS loaded successfully")
-
-        except ImportError as e:
-            logger.error(
-                "chatterbox-tts package not found. "
-                "Install with: pip install chatterbox-tts"
-            )
-            if not is_cached:
-                progress_manager.mark_error(model_name, str(e))
-                task_manager.error_download(model_name, str(e))
-            raise
-        except Exception as e:
-            logger.error(f"Failed to load Chatterbox Turbo: {e}")
-            if not is_cached:
-                progress_manager.mark_error(model_name, str(e))
-                task_manager.error_download(model_name, str(e))
-            raise
+        logger.info("Chatterbox Turbo TTS loaded successfully")

    def unload_model(self) -> None:
        """Unload model to free memory."""
@@ -270,17 +145,7 @@ class ChatterboxTurboTTSBackend:
        audio_paths: List[str],
        reference_texts: List[str],
    ) -> Tuple[np.ndarray, str]:
-        """Combine multiple reference samples."""
-        combined_audio = []
-        for path in audio_paths:
-            audio, _sr = load_audio(path)
-            audio = normalize_audio(audio)
-            combined_audio.append(audio)
-
-        mixed = np.concatenate(combined_audio)
-        mixed = normalize_audio(mixed)
-        combined_text = " ".join(reference_texts)
-        return mixed, combined_text
+        return await _combine_voice_prompts(audio_paths, reference_texts)

    async def generate(
        self,
@@ -7,16 +7,13 @@ Wraps the LuxTTS (ZipVoice) model for zero-shot voice cloning.

 import asyncio
 import logging
-from pathlib import Path
-from typing import List, Optional, Tuple
+from typing import Optional, Tuple

 import numpy as np

 from . import TTSBackend
-from ..utils.audio import normalize_audio, load_audio
+from .base import is_model_cached, get_torch_device, combine_voice_prompts as _combine_voice_prompts, model_load_progress
 from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt
-from ..utils.progress import get_progress_manager
-from ..utils.tasks import get_task_manager

 logger = logging.getLogger(__name__)

@@ -33,14 +30,7 @@ class LuxTTSBackend:
        self._device = None

    def _get_device(self) -> str:
-        """Get the best available device."""
-        import torch
-
-        if torch.cuda.is_available():
-            return "cuda"
-        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
-            return "mps"
-        return "cpu"
+        return get_torch_device(allow_mps=True)

    def is_loaded(self) -> bool:
        return self.model is not None
@@ -55,35 +45,10 @@ class LuxTTSBackend:
        return LUXTTS_HF_REPO

    def _is_model_cached(self, model_size: str = "default") -> bool:
-        """Check if LuxTTS model weights are cached locally."""
-        try:
-            from huggingface_hub import constants as hf_constants
-
-            repo_cache = (
-                Path(hf_constants.HF_HUB_CACHE)
-                / ("models--" + LUXTTS_HF_REPO.replace("/", "--"))
-            )
-
-            if not repo_cache.exists():
-                return False
-
-            blobs_dir = repo_cache / "blobs"
-            if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
-                return False
-
-            snapshots_dir = repo_cache / "snapshots"
-            if snapshots_dir.exists():
-                has_weights = any(snapshots_dir.rglob("*.pt")) or any(
-                    snapshots_dir.rglob("*.safetensors")
-                ) or any(snapshots_dir.rglob("*.onnx")) or any(
-                    snapshots_dir.rglob("*.bin")
-                )
-                return has_weights
-
-            return False
-        except Exception as e:
-            logger.warning(f"Error checking LuxTTS cache: {e}")
-            return False
+        return is_model_cached(
+            LUXTTS_HF_REPO,
+            weight_extensions=(".pt", ".safetensors", ".onnx", ".bin"),
+        )

    async def load_model(self, model_size: str = "default") -> None:
        """Load the LuxTTS model."""
@@ -93,67 +58,25 @@ class LuxTTSBackend:
        await asyncio.to_thread(self._load_model_sync)

    def _load_model_sync(self):
-        """Synchronous model loading."""
-        from ..utils.hf_progress import HFProgressTracker, create_hf_progress_callback
-
-        progress_manager = get_progress_manager()
-        task_manager = get_task_manager()
        model_name = "luxtts"
-
        is_cached = self._is_model_cached()

-        # Set up HF progress tracking (intercepts tqdm for file-level progress)
-        progress_callback = create_hf_progress_callback(model_name, progress_manager)
-        tracker = HFProgressTracker(progress_callback, filter_non_downloads=is_cached)
-        tracker_context = tracker.patch_download()
-        tracker_context.__enter__()
-
-        if not is_cached:
-            task_manager.start_download(model_name)
-            progress_manager.update_progress(
-                model_name=model_name,
-                current=0,
-                total=0,
-                filename="Connecting to HuggingFace...",
-                status="downloading",
-            )
-
-        try:
+        with model_load_progress(model_name, is_cached):
            from zipvoice.luxvoice import LuxTTS

            device = self.device
            logger.info(f"Loading LuxTTS on {device}...")

-            # LuxTTS constructor downloads model and loads everything
-            try:
-                if device == "cpu":
-                    import os
-                    threads = os.cpu_count() or 4
-                    self.model = LuxTTS(
-                        model_path=LUXTTS_HF_REPO,
-                        device="cpu",
-                        threads=min(threads, 8),
-                    )
-                else:
-                    self.model = LuxTTS(
-                        model_path=LUXTTS_HF_REPO,
-                        device=device,
-                    )
-            finally:
-                tracker_context.__exit__(None, None, None)
+            if device == "cpu":
+                import os
+                threads = os.cpu_count() or 4
+                self.model = LuxTTS(
+                    model_path=LUXTTS_HF_REPO, device="cpu", threads=min(threads, 8),
+                )
+            else:
+                self.model = LuxTTS(model_path=LUXTTS_HF_REPO, device=device)

-            if not is_cached:
-                progress_manager.mark_complete(model_name)
-                task_manager.complete_download(model_name)
-
-            logger.info("LuxTTS loaded successfully")
-
-        except Exception as e:
-            logger.error(f"Failed to load LuxTTS: {e}")
-            if not is_cached:
-                progress_manager.mark_error(model_name, str(e))
-                task_manager.error_download(model_name, str(e))
-            raise
+        logger.info("LuxTTS loaded successfully")

    def unload_model(self) -> None:
        """Unload model to free memory."""
@@ -204,28 +127,8 @@ class LuxTTSBackend:

        return encoded, False

-    async def combine_voice_prompts(
-        self,
-        audio_paths: List[str],
-        reference_texts: List[str],
-    ) -> Tuple[np.ndarray, str]:
-        """
-        Combine multiple reference samples.
-
-        LuxTTS doesn't have native multi-prompt support, so we concatenate
-        the audio and let encode_prompt handle the combined clip.
-        """
-        combined_audio = []
-        for path in audio_paths:
-            audio, _sr = load_audio(path, sample_rate=24000)
-            audio = normalize_audio(audio)
-            combined_audio.append(audio)
-
-        mixed = np.concatenate(combined_audio)
-        mixed = normalize_audio(mixed)
-        combined_text = " ".join(reference_texts)
-
-        return mixed, combined_text
+    async def combine_voice_prompts(self, audio_paths, reference_texts):
+        return await _combine_voice_prompts(audio_paths, reference_texts, sample_rate=24000)

    async def generate(
        self,
@@ -4,49 +4,44 @@ MLX backend implementation for TTS and STT using mlx-audio.

 from typing import Optional, List, Tuple
 import asyncio
+import logging
 import numpy as np
 import os
 from pathlib import Path

+logger = logging.getLogger(__name__)
+
 # PATCH: Import and apply offline patch BEFORE any huggingface_hub usage
 # This prevents mlx_audio from making network requests when models are cached
 from ..utils.hf_offline_patch import patch_huggingface_hub_offline, ensure_original_qwen_config_cached
+
 patch_huggingface_hub_offline()
 ensure_original_qwen_config_cached()

-from . import TTSBackend, STTBackend
+from . import TTSBackend, STTBackend, LANGUAGE_CODE_TO_NAME, WHISPER_HF_REPOS
+from .base import is_model_cached, combine_voice_prompts as _combine_voice_prompts, model_load_progress
 from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt
-from ..utils.audio import normalize_audio, load_audio
-from ..utils.progress import get_progress_manager
-from ..utils.hf_progress import HFProgressTracker, create_hf_progress_callback
-from ..utils.tasks import get_task_manager
-
-LANGUAGE_CODE_TO_NAME = {
-    "zh": "chinese", "en": "english", "ja": "japanese", "ko": "korean",
-    "de": "german", "fr": "french", "ru": "russian", "pt": "portuguese",
-    "es": "spanish", "it": "italian",
-}


 class MLXTTSBackend:
    """MLX-based TTS backend using mlx-audio."""
-    
+
    def __init__(self, model_size: str = "1.7B"):
        self.model = None
        self.model_size = model_size
        self._current_model_size = None
-    
+
    def is_loaded(self) -> bool:
        """Check if model is loaded."""
        return self.model is not None
-    
+
    def _get_model_path(self, model_size: str) -> str:
        """
        Get the MLX model path.
-        
+
        Args:
            model_size: Model size (1.7B or 0.6B)
-            
+
        Returns:
            HuggingFace Hub model ID for MLX
        """
@@ -56,187 +51,90 @@ class MLXTTSBackend:
            # 0.6B not yet converted to MLX format
            "0.6B": "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16",  # Fallback to 1.7B
        }
-        
+
        if model_size not in mlx_model_map:
            raise ValueError(f"Unknown model size: {model_size}")
-        
+
        hf_model_id = mlx_model_map[model_size]
-        print(f"Will download MLX model from HuggingFace Hub: {hf_model_id}")
-        
+        logger.info("Will download MLX model from HuggingFace Hub: %s", hf_model_id)
+
        return hf_model_id
-    
+
    def _is_model_cached(self, model_size: str) -> bool:
-        """
-        Check if the model is already cached locally AND fully downloaded.
-        
-        Args:
-            model_size: Model size to check
-            
-        Returns:
-            True if model is fully cached, False if missing or incomplete
-        """
-        try:
-            from huggingface_hub import constants as hf_constants
-            model_path = self._get_model_path(model_size)
-            repo_cache = Path(hf_constants.HF_HUB_CACHE) / ("models--" + model_path.replace("/", "--"))
-            
-            if not repo_cache.exists():
-                return False
-            
-            # Check for .incomplete files - if any exist, download is still in progress
-            blobs_dir = repo_cache / "blobs"
-            if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
-                print(f"[_is_model_cached] Found .incomplete files for {model_size}, treating as not cached")
-                return False
-            
-            # Check that actual model weight files exist in snapshots
-            snapshots_dir = repo_cache / "snapshots"
-            if snapshots_dir.exists():
-                has_weights = (
-                    any(snapshots_dir.rglob("*.safetensors")) or
-                    any(snapshots_dir.rglob("*.bin")) or
-                    any(snapshots_dir.rglob("*.npz"))
-                )
-                if not has_weights:
-                    print(f"[_is_model_cached] No model weights found for {model_size}, treating as not cached")
-                    return False
-            
-            return True
-        except Exception as e:
-            print(f"[_is_model_cached] Error checking cache for {model_size}: {e}")
-            return False
-    
+        return is_model_cached(
+            self._get_model_path(model_size),
+            weight_extensions=(".safetensors", ".bin", ".npz"),
+        )
+
    async def load_model_async(self, model_size: Optional[str] = None):
        """
        Lazy load the MLX TTS model.
-        
+
        Args:
            model_size: Model size to load (1.7B or 0.6B)
        """
        if model_size is None:
            model_size = self.model_size
-            
+
        # If already loaded with correct size, return
        if self.model is not None and self._current_model_size == model_size:
            return
-        
+
        # Unload existing model if different size requested
        if self.model is not None and self._current_model_size != model_size:
            self.unload_model()
-        
+
        # Run blocking load in thread pool
        await asyncio.to_thread(self._load_model_sync, model_size)
-    
+
    # Alias for compatibility
    load_model = load_model_async
-    
+
    def _load_model_sync(self, model_size: str):
        """Synchronous model loading."""
+        model_path = self._get_model_path(model_size)
+        model_name = f"qwen-tts-{model_size}"
+        is_cached = self._is_model_cached(model_size)
+
+        # Force offline mode when cached to avoid network requests
+        original_hf_hub_offline = os.environ.get("HF_HUB_OFFLINE")
+        if is_cached:
+            os.environ["HF_HUB_OFFLINE"] = "1"
+            logger.info("[PATCH] Model %s is cached, forcing HF_HUB_OFFLINE=1 to avoid network requests", model_size)
+
        try:
-            # Get model path BEFORE importing mlx_audio
-            model_path = self._get_model_path(model_size)
-            
-            # Set up progress tracking
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            model_name = f"qwen-tts-{model_size}"
-            
-            # Check if model is already cached
-            is_cached = self._is_model_cached(model_size)
-            
-            # Set up progress callback
-            # If cached: filter out non-download progress
-            # If not cached: report all progress (we're actually downloading)
-            progress_callback = create_hf_progress_callback(model_name, progress_manager)
-            tracker = HFProgressTracker(progress_callback, filter_non_downloads=is_cached)
-            
-            print(f"Loading MLX TTS model {model_size}...")
-            
-            # Only track download progress if model is NOT cached
-            if not is_cached:
-                # Start tracking download task
-                task_manager.start_download(model_name)
-                
-                # Initialize progress state so SSE endpoint has initial data to send
-                # This provides immediate feedback while HuggingFace fetches metadata
-                progress_manager.update_progress(
-                    model_name=model_name,
-                    current=0,
-                    total=0,  # Will be updated once actual total is known
-                    filename="Connecting to HuggingFace...",
-                    status="downloading",
-                )
-            
-            # IMPORTANT: Patch tqdm BEFORE importing mlx_audio
-            # Otherwise mlx_audio caches reference to original tqdm
-            tracker_context = tracker.patch_download()
-            tracker_context.__enter__()
-            
-            # PATCH: Force offline mode when model is already cached
-            # This prevents crashes when HuggingFace is unreachable
-            original_hf_hub_offline = os.environ.get("HF_HUB_OFFLINE")
-            if is_cached:
-                os.environ["HF_HUB_OFFLINE"] = "1"
-                print(f"[PATCH] Model {model_size} is cached, forcing HF_HUB_OFFLINE=1 to avoid network requests")
-            
-            # Import mlx_audio AFTER patching tqdm
-            from mlx_audio.tts import load
-            
-            # Load MLX model (downloads automatically)
-            try:
-                self.model = load(model_path)
-            except Exception as load_error:
-                # If offline mode failed, try with network enabled as fallback
-                if is_cached and "offline" in str(load_error).lower():
-                    print(f"[PATCH] Offline load failed, trying with network: {load_error}")
-                    os.environ.pop("HF_HUB_OFFLINE", None)
+            with model_load_progress(model_name, is_cached):
+                from mlx_audio.tts import load
+
+                logger.info("Loading MLX TTS model %s...", model_size)
+
+                try:
                    self.model = load(model_path)
-                else:
-                    raise
-            finally:
-                # Exit the patch context
-                tracker_context.__exit__(None, None, None)
-                # Restore original HF_HUB_OFFLINE setting
-                if original_hf_hub_offline is not None:
-                    os.environ["HF_HUB_OFFLINE"] = original_hf_hub_offline
-                else:
-                    os.environ.pop("HF_HUB_OFFLINE", None)
-            
-            # Only mark download as complete if we were tracking it
-            if not is_cached:
-                progress_manager.mark_complete(model_name)
-                task_manager.complete_download(model_name)
-            
-            self._current_model_size = model_size
-            self.model_size = model_size
-            
-            print(f"MLX TTS model {model_size} loaded successfully")
-            
-        except ImportError as e:
-            print(f"Error: mlx_audio package not found. Install with: pip install mlx-audio")
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            model_name = f"qwen-tts-{model_size}"
-            progress_manager.mark_error(model_name, str(e))
-            task_manager.error_download(model_name, str(e))
-            raise
-        except Exception as e:
-            print(f"Error loading MLX TTS model: {e}")
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            model_name = f"qwen-tts-{model_size}"
-            progress_manager.mark_error(model_name, str(e))
-            task_manager.error_download(model_name, str(e))
-            raise
-    
+                except Exception as load_error:
+                    if is_cached and "offline" in str(load_error).lower():
+                        logger.warning("[PATCH] Offline load failed, trying with network: %s", load_error)
+                        os.environ.pop("HF_HUB_OFFLINE", None)
+                        self.model = load(model_path)
+                    else:
+                        raise
+        finally:
+            if original_hf_hub_offline is not None:
+                os.environ["HF_HUB_OFFLINE"] = original_hf_hub_offline
+            else:
+                os.environ.pop("HF_HUB_OFFLINE", None)
+
+        self._current_model_size = model_size
+        self.model_size = model_size
+        logger.info("MLX TTS model %s loaded successfully", model_size)
+
    def unload_model(self):
        """Unload the model to free memory."""
        if self.model is not None:
            del self.model
            self.model = None
            self._current_model_size = None
-            print("MLX TTS model unloaded")
-    
+            logger.info("MLX TTS model unloaded")
+
    async def create_voice_prompt(
        self,
        audio_path: str,
@@ -245,20 +143,20 @@ class MLXTTSBackend:
    ) -> Tuple[dict, bool]:
        """
        Create voice prompt from reference audio.
-        
+
        MLX backend stores voice prompt as a dict with audio path and text.
        The actual voice prompt processing happens during generation.
-        
+
        Args:
            audio_path: Path to reference audio file
            reference_text: Transcript of reference audio
            use_cache: Whether to use cached prompt if available
-            
+
        Returns:
            Tuple of (voice_prompt_dict, was_cached)
        """
        await self.load_model_async(None)
-        
+
        # Check cache if enabled
        if use_cache:
            cache_key = get_cache_key(audio_path, reference_text)
@@ -272,53 +170,25 @@ class MLXTTSBackend:
                        return cached_prompt, True
                    else:
                        # Cached file no longer exists, invalidate cache
-                        print(f"Cached audio file not found: {cached_audio_path}, regenerating prompt")
-        
+                        logger.warning("Cached audio file not found: %s, regenerating prompt", cached_audio_path)
+
        # MLX voice prompt format - store audio path and text
        # The model will process this during generation
        voice_prompt_items = {
            "ref_audio": str(audio_path),
            "ref_text": reference_text,
        }
-        
+
        # Cache if enabled
        if use_cache:
            cache_key = get_cache_key(audio_path, reference_text)
            cache_voice_prompt(cache_key, voice_prompt_items)
-        
+
        return voice_prompt_items, False
-    
-    async def combine_voice_prompts(
-        self,
-        audio_paths: List[str],
-        reference_texts: List[str],
-    ) -> Tuple[np.ndarray, str]:
-        """
-        Combine multiple reference samples for better quality.
-        
-        Args:
-            audio_paths: List of audio file paths
-            reference_texts: List of reference texts
-            
-        Returns:
-            Tuple of (combined_audio, combined_text)
-        """
-        combined_audio = []
-        
-        for audio_path in audio_paths:
-            audio, sr = load_audio(audio_path)
-            audio = normalize_audio(audio)
-            combined_audio.append(audio)
-        
-        # Concatenate audio
-        mixed = np.concatenate(combined_audio)
-        mixed = normalize_audio(mixed)
-        
-        # Combine texts
-        combined_text = " ".join(reference_texts)
-        
-        return mixed, combined_text
-    
+
+    async def combine_voice_prompts(self, audio_paths, reference_texts):
+        return await _combine_voice_prompts(audio_paths, reference_texts)
+
    async def generate(
        self,
        text: str,
@@ -342,7 +212,7 @@ class MLXTTSBackend:
        """
        await self.load_model_async(None)

-        print(f"Generating audio for text: {text}")
+        logger.info("Generating audio for text: %s", text)

        def _generate_sync():
            """Run synchronous generation in thread pool."""
@@ -354,20 +224,21 @@ class MLXTTSBackend:
            # Set seed if provided (MLX uses numpy random)
            if seed is not None:
                import mlx.core as mx
+
                np.random.seed(seed)
                mx.random.seed(seed)
-            
+
            # Extract voice prompt info
            ref_audio = voice_prompt.get("ref_audio") or voice_prompt.get("ref_audio_path")
            ref_text = voice_prompt.get("ref_text", "")
-            
+
            # Validate that the audio file exists
            if ref_audio and not Path(ref_audio).exists():
-                print(f"Warning: Audio file not found: {ref_audio}")
-                print("This may be due to a cached voice prompt referencing a deleted temp file.")
-                print("Regenerating without voice prompt.")
+                logger.warning("Audio file not found: %s", ref_audio)
+                logger.warning("This may be due to a cached voice prompt referencing a deleted temp file.")
+                logger.warning("Regenerating without voice prompt.")
                ref_audio = None
-            
+
            # Check if model supports voice cloning via generate method
            # MLX API may support ref_audio parameter directly
            try:
@@ -375,6 +246,7 @@ class MLXTTSBackend:
                if ref_audio:
                    # Check if generate accepts ref_audio parameter
                    import inspect
+
                    sig = inspect.signature(self.model.generate)
                    if "ref_audio" in sig.parameters:
                        # Generate with voice cloning
@@ -393,18 +265,18 @@ class MLXTTSBackend:
                        sample_rate = result.sample_rate
            except Exception as e:
                # If voice cloning fails, try without it
-                print(f"Warning: Voice cloning failed, generating without voice prompt: {e}")
+                logger.warning("Voice cloning failed, generating without voice prompt: %s", e)
                for result in self.model.generate(text, lang_code=lang):
                    audio_chunks.append(np.array(result.audio))
                    sample_rate = result.sample_rate
-            
+
            # Concatenate all chunks
            if audio_chunks:
                audio = np.concatenate([np.asarray(chunk, dtype=np.float32) for chunk in audio_chunks])
            else:
                # Fallback: empty audio
                audio = np.array([], dtype=np.float32)
-            
+
            return audio, sample_rate

        # Run blocking inference in thread pool
@@ -413,167 +285,62 @@ class MLXTTSBackend:
        return audio, sample_rate


-WHISPER_HF_REPOS = {
-    "base": "openai/whisper-base",
-    "small": "openai/whisper-small",
-    "medium": "openai/whisper-medium",
-    "large": "openai/whisper-large-v3",
-}
-
-
 class MLXSTTBackend:
    """MLX-based STT backend using mlx-audio Whisper."""

    def __init__(self, model_size: str = "base"):
        self.model = None
        self.model_size = model_size
-    
+
    def is_loaded(self) -> bool:
        """Check if model is loaded."""
        return self.model is not None
-    
+
    def _is_model_cached(self, model_size: str) -> bool:
-        """
-        Check if the Whisper model is already cached locally AND fully downloaded.
-        
-        Args:
-            model_size: Model size to check
-            
-        Returns:
-            True if model is fully cached, False if missing or incomplete
-        """
-        try:
-            from huggingface_hub import constants as hf_constants
-            hf_repo = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
-            repo_cache = Path(hf_constants.HF_HUB_CACHE) / ("models--" + hf_repo.replace("/", "--"))
-            
-            if not repo_cache.exists():
-                return False
-            
-            # Check for .incomplete files - if any exist, download is still in progress
-            blobs_dir = repo_cache / "blobs"
-            if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
-                print(f"[_is_model_cached] Found .incomplete files for whisper-{model_size}, treating as not cached")
-                return False
-            
-            # Check that actual model weight files exist in snapshots
-            snapshots_dir = repo_cache / "snapshots"
-            if snapshots_dir.exists():
-                has_weights = (
-                    any(snapshots_dir.rglob("*.safetensors")) or
-                    any(snapshots_dir.rglob("*.bin")) or
-                    any(snapshots_dir.rglob("*.npz"))
-                )
-                if not has_weights:
-                    print(f"[_is_model_cached] No model weights found for whisper-{model_size}, treating as not cached")
-                    return False
-            
-            return True
-        except Exception as e:
-            print(f"[_is_model_cached] Error checking cache for whisper-{model_size}: {e}")
-            return False
-    
+        hf_repo = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
+        return is_model_cached(hf_repo, weight_extensions=(".safetensors", ".bin", ".npz"))
+
    async def load_model_async(self, model_size: Optional[str] = None):
        """
        Lazy load the MLX Whisper model.
-        
+
        Args:
            model_size: Model size (tiny, base, small, medium, large)
        """
        if model_size is None:
            model_size = self.model_size
-        
+
        if self.model is not None and self.model_size == model_size:
            return
-        
+
        # Run blocking load in thread pool
        await asyncio.to_thread(self._load_model_sync, model_size)
-    
+
    # Alias for compatibility
    load_model = load_model_async
-    
+
    def _load_model_sync(self, model_size: str):
        """Synchronous model loading."""
-        try:
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            progress_model_name = f"whisper-{model_size}"
+        progress_model_name = f"whisper-{model_size}"
+        is_cached = self._is_model_cached(model_size)

-            # Check if model is already cached
-            is_cached = self._is_model_cached(model_size)
-
-            # Set up progress callback and tracker
-            # If cached: filter out non-download progress
-            # If not cached: report all progress (we're actually downloading)
-            progress_callback = create_hf_progress_callback(progress_model_name, progress_manager)
-            tracker = HFProgressTracker(progress_callback, filter_non_downloads=is_cached)
-
-            # Patch tqdm BEFORE importing mlx_audio
-            tracker_context = tracker.patch_download()
-            tracker_context.__enter__()
-
-            # Import mlx_audio
+        with model_load_progress(progress_model_name, is_cached):
            from mlx_audio.stt import load

-            # MLX Whisper uses the standard OpenAI models
            model_name = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
+            logger.info("Loading MLX Whisper model %s...", model_size)
+            self.model = load(model_name)

-            print(f"Loading MLX Whisper model {model_size}...")
+        self.model_size = model_size
+        logger.info("MLX Whisper model %s loaded successfully", model_size)

-            # Only track download progress if model is NOT cached
-            if not is_cached:
-                # Start tracking download task
-                task_manager.start_download(progress_model_name)
-                
-                # Initialize progress state so SSE endpoint has initial data to send
-                progress_manager.update_progress(
-                    model_name=progress_model_name,
-                    current=0,
-                    total=0,
-                    filename="Connecting to HuggingFace...",
-                    status="downloading",
-                )
-
-            # Load the model (tqdm is patched, but filters out non-download progress)
-            try:
-                self.model = load(model_name)
-            finally:
-                # Exit the patch context
-                tracker_context.__exit__(None, None, None)
-            
-            # Only mark download as complete if we were tracking it
-            if not is_cached:
-                progress_manager.mark_complete(progress_model_name)
-                task_manager.complete_download(progress_model_name)
-            
-            self.model_size = model_size
-            
-            print(f"MLX Whisper model {model_size} loaded successfully")
-            
-        except ImportError as e:
-            print(f"Error: mlx_audio package not found. Install with: pip install mlx-audio")
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            progress_model_name = f"whisper-{model_size}"
-            progress_manager.mark_error(progress_model_name, str(e))
-            task_manager.error_download(progress_model_name, str(e))
-            raise
-        except Exception as e:
-            print(f"Error loading MLX Whisper model: {e}")
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            progress_model_name = f"whisper-{model_size}"
-            progress_manager.mark_error(progress_model_name, str(e))
-            task_manager.error_download(progress_model_name, str(e))
-            raise
-    
    def unload_model(self):
        """Unload the model to free memory."""
        if self.model is not None:
            del self.model
            self.model = None
-            print("MLX Whisper model unloaded")
-    
+            logger.info("MLX Whisper model unloaded")
+
    async def transcribe(
        self,
        audio_path: str,
@@ -4,67 +4,47 @@ PyTorch backend implementation for TTS and STT.

 from typing import Optional, List, Tuple
 import asyncio
+import logging
 import torch
 import numpy as np
-from pathlib import Path

-from . import TTSBackend, STTBackend
+logger = logging.getLogger(__name__)
+
+from . import TTSBackend, STTBackend, LANGUAGE_CODE_TO_NAME, WHISPER_HF_REPOS
+from .base import (
+    is_model_cached,
+    get_torch_device,
+    combine_voice_prompts as _combine_voice_prompts,
+    model_load_progress,
+)
 from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt
-from ..utils.audio import normalize_audio, load_audio
-from ..utils.progress import get_progress_manager
-from ..utils.hf_progress import HFProgressTracker, create_hf_progress_callback
-from ..utils.tasks import get_task_manager
-
-LANGUAGE_CODE_TO_NAME = {
-    "zh": "chinese", "en": "english", "ja": "japanese", "ko": "korean",
-    "de": "german", "fr": "french", "ru": "russian", "pt": "portuguese",
-    "es": "spanish", "it": "italian",
-}
+from ..utils.audio import load_audio


 class PyTorchTTSBackend:
    """PyTorch-based TTS backend using Qwen3-TTS."""
-    
+
    def __init__(self, model_size: str = "1.7B"):
        self.model = None
        self.model_size = model_size
        self.device = self._get_device()
        self._current_model_size = None
-    
+
    def _get_device(self) -> str:
        """Get the best available device."""
-        if torch.cuda.is_available():
-            return "cuda"
-        # Intel Arc / Intel Xe GPU via intel-extension-for-pytorch (IPEX)
-        try:
-            import intel_extension_for_pytorch  # noqa: F401
-            if hasattr(torch, 'xpu') and torch.xpu.is_available():
-                return "xpu"
-        except ImportError:
-            pass
-        # Any GPU on Windows via DirectML (torch-directml)
-        try:
-            import torch_directml
-            if torch_directml.device_count() > 0:
-                return torch_directml.device(0)
-        except ImportError:
-            pass
-        # MPS (Apple Silicon) — kept for completeness but MLX backend is preferred
-        if hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
-            return "cpu"  # MPS disabled for stability; MLX backend handles Apple Silicon
-        return "cpu"
-    
+        return get_torch_device(allow_xpu=True, allow_directml=True)
+
    def is_loaded(self) -> bool:
        """Check if model is loaded."""
        return self.model is not None
-    
+
    def _get_model_path(self, model_size: str) -> str:
        """
        Get the HuggingFace Hub model ID.
-        
+
        Args:
            model_size: Model size (1.7B or 0.6B)
-            
+
        Returns:
            HuggingFace Hub model ID
        """
@@ -72,179 +52,79 @@ class PyTorchTTSBackend:
            "1.7B": "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
            "0.6B": "Qwen/Qwen3-TTS-12Hz-0.6B-Base",
        }
-        
+
        if model_size not in hf_model_map:
            raise ValueError(f"Unknown model size: {model_size}")
-        
+
        return hf_model_map[model_size]
-    
+
    def _is_model_cached(self, model_size: str) -> bool:
-        """
-        Check if the model is already cached locally AND fully downloaded.
-        
-        Args:
-            model_size: Model size to check
-            
-        Returns:
-            True if model is fully cached, False if missing or incomplete
-        """
-        try:
-            from huggingface_hub import constants as hf_constants
-            model_path = self._get_model_path(model_size)
-            repo_cache = Path(hf_constants.HF_HUB_CACHE) / ("models--" + model_path.replace("/", "--"))
-            
-            if not repo_cache.exists():
-                return False
-            
-            # Check for .incomplete files - if any exist, download is still in progress
-            blobs_dir = repo_cache / "blobs"
-            if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
-                print(f"[_is_model_cached] Found .incomplete files for {model_size}, treating as not cached")
-                return False
-            
-            # Check that actual model weight files exist in snapshots
-            snapshots_dir = repo_cache / "snapshots"
-            if snapshots_dir.exists():
-                has_weights = (
-                    any(snapshots_dir.rglob("*.safetensors")) or
-                    any(snapshots_dir.rglob("*.bin"))
-                )
-                if not has_weights:
-                    print(f"[_is_model_cached] No model weights found for {model_size}, treating as not cached")
-                    return False
-            
-            return True
-        except Exception as e:
-            print(f"[_is_model_cached] Error checking cache for {model_size}: {e}")
-            return False
-    
+        return is_model_cached(self._get_model_path(model_size))
+
    async def load_model_async(self, model_size: Optional[str] = None):
        """
        Lazy load the TTS model with automatic downloading from HuggingFace Hub.
-        
+
        Args:
            model_size: Model size to load (1.7B or 0.6B)
        """
        if model_size is None:
            model_size = self.model_size
-            
+
        # If already loaded with correct size, return
        if self.model is not None and self._current_model_size == model_size:
            return
-        
+
        # Unload existing model if different size requested
        if self.model is not None and self._current_model_size != model_size:
            self.unload_model()
-        
+
        # Run blocking load in thread pool
        await asyncio.to_thread(self._load_model_sync, model_size)
-    
+
    # Alias for compatibility
    load_model = load_model_async
-    
+
    def _load_model_sync(self, model_size: str):
        """Synchronous model loading."""
-        try:
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            model_name = f"qwen-tts-{model_size}"
+        model_name = f"qwen-tts-{model_size}"
+        is_cached = self._is_model_cached(model_size)

-            # Check if model is already cached
-            is_cached = self._is_model_cached(model_size)
-
-            # Set up progress callback and tracker
-            # If cached: filter out non-download progress (like "Segment 1/1" during generation)
-            # If not cached: report all progress (we're actually downloading)
-            progress_callback = create_hf_progress_callback(model_name, progress_manager)
-            tracker = HFProgressTracker(progress_callback, filter_non_downloads=is_cached)
-
-            # Patch tqdm BEFORE importing qwen_tts
-            tracker_context = tracker.patch_download()
-            tracker_context.__enter__()
-
-            # Import qwen_tts
+        with model_load_progress(model_name, is_cached):
            from qwen_tts import Qwen3TTSModel

-            # Get model path (local or HuggingFace Hub ID)
            model_path = self._get_model_path(model_size)
+            logger.info("Loading TTS model %s on %s...", model_size, self.device)

-            print(f"Loading TTS model {model_size} on {self.device}...")
-
-            # Only track download progress if model is NOT cached
-            if not is_cached:
-                # Start tracking download task
-                task_manager.start_download(model_name)
-
-                # Initialize progress state so SSE endpoint has initial data to send
-                progress_manager.update_progress(
-                    model_name=model_name,
-                    current=0,
-                    total=0,  # Will be updated once actual total is known
-                    filename="Connecting to HuggingFace...",
-                    status="downloading",
+            if self.device == "cpu":
+                self.model = Qwen3TTSModel.from_pretrained(
+                    model_path,
+                    torch_dtype=torch.float32,
+                    low_cpu_mem_usage=False,
+                )
+            else:
+                self.model = Qwen3TTSModel.from_pretrained(
+                    model_path,
+                    device_map=self.device,
+                    torch_dtype=torch.bfloat16,
                )

-            # Load the model (tqdm is patched, but filters out non-download progress)
-            try:
-                # Don't pass device_map on CPU: accelerate's meta-tensor mechanism
-                # causes "Cannot copy out of meta tensor" when moving to CPU.
-                # Instead load directly then call .to(device) if needed.
-                if self.device == "cpu":
-                    self.model = Qwen3TTSModel.from_pretrained(
-                        model_path,
-                        torch_dtype=torch.float32,
-                        low_cpu_mem_usage=False,
-                    )
-                else:
-                    self.model = Qwen3TTSModel.from_pretrained(
-                        model_path,
-                        device_map=self.device,
-                        torch_dtype=torch.bfloat16,
-                    )
-            finally:
-                # Exit the patch context
-                tracker_context.__exit__(None, None, None)
-            
-            # Only mark download as complete if we were tracking it
-            if not is_cached:
-                progress_manager.mark_complete(model_name)
-                task_manager.complete_download(model_name)
-            
-            self._current_model_size = model_size
-            self.model_size = model_size
-            
-            print(f"TTS model {model_size} loaded successfully")
-            
-        except ImportError as e:
-            print(f"Error: qwen_tts package not found. Install with: pip install git+https://github.com/QwenLM/Qwen3-TTS.git")
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            model_name = f"qwen-tts-{model_size}"
-            progress_manager.mark_error(model_name, str(e))
-            task_manager.error_download(model_name, str(e))
-            raise
-        except Exception as e:
-            print(f"Error loading TTS model: {e}")
-            print(f"Tip: The model will be automatically downloaded from HuggingFace Hub on first use.")
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            model_name = f"qwen-tts-{model_size}"
-            progress_manager.mark_error(model_name, str(e))
-            task_manager.error_download(model_name, str(e))
-            raise
-    
+        self._current_model_size = model_size
+        self.model_size = model_size
+        logger.info("TTS model %s loaded successfully", model_size)
+
    def unload_model(self):
        """Unload the model to free memory."""
        if self.model is not None:
            del self.model
            self.model = None
            self._current_model_size = None
-            
+
            if torch.cuda.is_available():
                torch.cuda.empty_cache()
-            
-            print("TTS model unloaded")
-    
+
+            logger.info("TTS model unloaded")
+
    async def create_voice_prompt(
        self,
        audio_path: str,
@@ -253,17 +133,17 @@ class PyTorchTTSBackend:
    ) -> Tuple[dict, bool]:
        """
        Create voice prompt from reference audio.
-        
+
        Args:
            audio_path: Path to reference audio file
            reference_text: Transcript of reference audio
            use_cache: Whether to use cached prompt if available
-            
+
        Returns:
            Tuple of (voice_prompt_dict, was_cached)
        """
        await self.load_model_async(None)
-        
+
        # Check cache if enabled
        if use_cache:
            cache_key = get_cache_key(audio_path, reference_text)
@@ -279,7 +159,7 @@ class PyTorchTTSBackend:
                    # Legacy cache format - convert to dict
                    # This shouldn't happen in practice, but handle it
                    return {"prompt": cached_prompt}, True
-        
+
        def _create_prompt_sync():
            """Run synchronous voice prompt creation in thread pool."""
            return self.model.create_voice_clone_prompt(
@@ -287,48 +167,24 @@ class PyTorchTTSBackend:
                ref_text=reference_text,
                x_vector_only_mode=False,
            )
-        
+
        # Run blocking operation in thread pool
        voice_prompt_items = await asyncio.to_thread(_create_prompt_sync)
-        
+
        # Cache if enabled
        if use_cache:
            cache_key = get_cache_key(audio_path, reference_text)
            cache_voice_prompt(cache_key, voice_prompt_items)
-        
+
        return voice_prompt_items, False
-    
+
    async def combine_voice_prompts(
        self,
        audio_paths: List[str],
        reference_texts: List[str],
    ) -> Tuple[np.ndarray, str]:
-        """
-        Combine multiple reference samples for better quality.
-        
-        Args:
-            audio_paths: List of audio file paths
-            reference_texts: List of reference texts
-            
-        Returns:
-            Tuple of (combined_audio, combined_text)
-        """
-        combined_audio = []
-        
-        for audio_path in audio_paths:
-            audio, sr = load_audio(audio_path)
-            audio = normalize_audio(audio)
-            combined_audio.append(audio)
-        
-        # Concatenate audio
-        mixed = np.concatenate(combined_audio)
-        mixed = normalize_audio(mixed)
-        
-        # Combine texts
-        combined_text = " ".join(reference_texts)
-        
-        return mixed, combined_text
-    
+        return await _combine_voice_prompts(audio_paths, reference_texts)
+
    async def generate(
        self,
        text: str,
@@ -376,15 +232,6 @@ class PyTorchTTSBackend:
        return audio, sample_rate


-WHISPER_HF_REPOS = {
-    "base": "openai/whisper-base",
-    "small": "openai/whisper-small",
-    "medium": "openai/whisper-medium",
-    "large": "openai/whisper-large-v3",
-    "turbo": "openai/whisper-large-v3-turbo",
-}
-
-
 class PyTorchSTTBackend:
    """PyTorch-based STT backend using Whisper."""

@@ -393,72 +240,18 @@ class PyTorchSTTBackend:
        self.processor = None
        self.model_size = model_size
        self.device = self._get_device()
-    
+
    def _get_device(self) -> str:
        """Get the best available device."""
-        if torch.cuda.is_available():
-            return "cuda"
-        # Intel Arc / Intel Xe GPU via intel-extension-for-pytorch (IPEX)
-        try:
-            import intel_extension_for_pytorch  # noqa: F401
-            if hasattr(torch, 'xpu') and torch.xpu.is_available():
-                return "xpu"
-        except ImportError:
-            pass
-        # Any GPU on Windows via DirectML (torch-directml)
-        try:
-            import torch_directml
-            if torch_directml.device_count() > 0:
-                return torch_directml.device(0)
-        except ImportError:
-            pass
-        if hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
-            return "cpu"  # MPS disabled for stability
-        return "cpu"
-    
+        return get_torch_device(allow_xpu=True, allow_directml=True)
+
    def is_loaded(self) -> bool:
        """Check if model is loaded."""
        return self.model is not None
-    
+
    def _is_model_cached(self, model_size: str) -> bool:
-        """
-        Check if the Whisper model is already cached locally AND fully downloaded.
-        
-        Args:
-            model_size: Model size to check
-            
-        Returns:
-            True if model is fully cached, False if missing or incomplete
-        """
-        try:
-            from huggingface_hub import constants as hf_constants
-            hf_repo = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
-            repo_cache = Path(hf_constants.HF_HUB_CACHE) / ("models--" + hf_repo.replace("/", "--"))
-
-            if not repo_cache.exists():
-                return False
-
-            # Check for .incomplete files - if any exist, download is still in progress
-            blobs_dir = repo_cache / "blobs"
-            if blobs_dir.exists() and any(blobs_dir.glob("*.incomplete")):
-                print(f"[_is_model_cached] Found .incomplete files for whisper-{model_size}, treating as not cached")
-                return False
-
-            # Check that actual model weight files exist in snapshots
-            snapshots_dir = repo_cache / "snapshots"
-            if snapshots_dir.exists():
-                has_weights = (
-                    any(snapshots_dir.rglob("*.safetensors")) or
-                    any(snapshots_dir.rglob("*.bin"))
-                )
-                if not has_weights:
-                    print(f"[_is_model_cached] No model weights found for whisper-{model_size}, treating as not cached")
-                    return False
-
-            return True
-        except Exception as e:
-            print(f"[_is_model_cached] Error checking cache for whisper-{model_size}: {e}")
-            return False
+        hf_repo = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
+        return is_model_cached(hf_repo)

    async def load_model_async(self, model_size: Optional[str] = None):
        """
@@ -467,95 +260,35 @@ class PyTorchSTTBackend:
        Args:
            model_size: Model size (tiny, base, small, medium, large)
        """
-        print(f"[DEBUG] load_model_async called with size: {model_size}")
        if model_size is None:
            model_size = self.model_size

-        print(f"[DEBUG] Model already loaded? {self.model is not None}, current size: {self.model_size}, requested: {model_size}")
        if self.model is not None and self.model_size == model_size:
-            print(f"[DEBUG] Early return - model already loaded")
            return

-        print(f"[DEBUG] Calling asyncio.to_thread for _load_model_sync")
-        # Run blocking load in thread pool
        await asyncio.to_thread(self._load_model_sync, model_size)
-        print(f"[DEBUG] asyncio.to_thread completed")
-    
+
    # Alias for compatibility
    load_model = load_model_async
-    
+
    def _load_model_sync(self, model_size: str):
        """Synchronous model loading."""
-        print(f"[DEBUG] _load_model_sync called for Whisper {model_size}")
-        try:
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            progress_model_name = f"whisper-{model_size}"
+        progress_model_name = f"whisper-{model_size}"
+        is_cached = self._is_model_cached(model_size)

-            # Check if model is already cached
-            is_cached = self._is_model_cached(model_size)
-
-            # Set up progress callback and tracker
-            # If cached: filter out non-download progress
-            # If not cached: report all progress (we're actually downloading)
-            progress_callback = create_hf_progress_callback(progress_model_name, progress_manager)
-            tracker = HFProgressTracker(progress_callback, filter_non_downloads=is_cached)
-
-            # Patch tqdm BEFORE importing transformers
-            print("[DEBUG] Starting tqdm patch BEFORE transformers import")
-            tracker_context = tracker.patch_download()
-            tracker_context.__enter__()
-            print("[DEBUG] tqdm patched, now importing transformers")
-
-            # Import transformers
+        with model_load_progress(progress_model_name, is_cached):
            from transformers import WhisperProcessor, WhisperForConditionalGeneration

            model_name = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
-            print(f"[DEBUG] Model name: {model_name}")
+            logger.info("Loading Whisper model %s on %s...", model_size, self.device)

-            print(f"Loading Whisper model {model_size} on {self.device}...")
+            self.processor = WhisperProcessor.from_pretrained(model_name)
+            self.model = WhisperForConditionalGeneration.from_pretrained(model_name)

-            # Only track download progress if model is NOT cached
-            if not is_cached:
-                # Start tracking download task
-                task_manager.start_download(progress_model_name)
+        self.model.to(self.device)
+        self.model_size = model_size
+        logger.info("Whisper model %s loaded successfully", model_size)

-                # Initialize progress state so SSE endpoint has initial data to send
-                progress_manager.update_progress(
-                    model_name=progress_model_name,
-                    current=0,
-                    total=0,  # Will be updated once actual total is known
-                    filename="Connecting to HuggingFace...",
-                    status="downloading",
-                )
-
-            # Load models (tqdm is patched, but filters out non-download progress)
-            try:
-                self.processor = WhisperProcessor.from_pretrained(model_name)
-                self.model = WhisperForConditionalGeneration.from_pretrained(model_name)
-            finally:
-                # Exit the patch context
-                tracker_context.__exit__(None, None, None)
-            
-            # Only mark download as complete if we were tracking it
-            if not is_cached:
-                progress_manager.mark_complete(progress_model_name)
-                task_manager.complete_download(progress_model_name)
-            
-            self.model.to(self.device)
-            self.model_size = model_size
-            
-            print(f"Whisper model {model_size} loaded successfully")
-            
-        except Exception as e:
-            print(f"Error loading Whisper model: {e}")
-            progress_manager = get_progress_manager()
-            task_manager = get_task_manager()
-            progress_model_name = f"whisper-{model_size}"
-            progress_manager.mark_error(progress_model_name, str(e))
-            task_manager.error_download(progress_model_name, str(e))
-            raise
-    
    def unload_model(self):
        """Unload the model to free memory."""
        if self.model is not None:
@@ -563,12 +296,12 @@ class PyTorchSTTBackend:
            del self.processor
            self.model = None
            self.processor = None
-            
+
            if torch.cuda.is_available():
                torch.cuda.empty_cache()
-            
-            print("Whisper model unloaded")
-    
+
+            logger.info("Whisper model unloaded")
+
    async def transcribe(
        self,
        audio_path: str,
@@ -576,21 +309,21 @@ class PyTorchSTTBackend:
    ) -> str:
        """
        Transcribe audio to text.
-        
+
        Args:
            audio_path: Path to audio file
            language: Optional language hint (en or zh)
-            
+
        Returns:
            Transcribed text
        """
        await self.load_model_async(None)
-        
+
        def _transcribe_sync():
            """Run synchronous transcription in thread pool."""
            # Load audio
            audio, sr = load_audio(audio_path, sample_rate=16000)
-            
+
            # Process audio
            inputs = self.processor(
                audio,
@@ -598,7 +331,7 @@ class PyTorchSTTBackend:
                return_tensors="pt",
            )
            inputs = inputs.to(self.device)
-            
+
            # Generate transcription
            # If language is provided, force it; otherwise let Whisper auto-detect
            generate_kwargs = {}
@@ -608,20 +341,20 @@ class PyTorchSTTBackend:
                    task="transcribe",
                )
                generate_kwargs["forced_decoder_ids"] = forced_decoder_ids
-            
+
            with torch.no_grad():
                predicted_ids = self.model.generate(
                    inputs["input_features"],
                    **generate_kwargs,
                )
-            
+
            # Decode
            transcription = self.processor.batch_decode(
                predicted_ids,
                skip_special_tokens=True,
            )[0]
-            
+
            return transcription.strip()
-        
+
        # Run blocking transcription in thread pool
        return await asyncio.to_thread(_transcribe_sync)
@@ -8,11 +8,14 @@ Usage:

 import PyInstaller.__main__
 import argparse
+import logging
 import os
 import platform
 import sys
 from pathlib import Path

+logger = logging.getLogger(__name__)
+

 def is_apple_silicon():
    """Check if running on Apple Silicon."""
@@ -28,134 +31,246 @@ def build_server(cuda=False):
    """
    backend_dir = Path(__file__).parent

-    binary_name = 'voicebox-server-cuda' if cuda else 'voicebox-server'
+    binary_name = "voicebox-server-cuda" if cuda else "voicebox-server"

    # PyInstaller arguments
    args = [
-        'server.py',  # Use server.py as entry point instead of main.py
-        '--onefile',
-        '--noconsole',  # No visible console window on Windows
-        '--name', binary_name,
+        "server.py",  # Use server.py as entry point instead of main.py
+        "--onefile",
+        "--name",
+        binary_name,
    ]

+    # Hide console window on Windows only. On macOS/Linux the sidecar needs
+    # stdout/stderr for Tauri to capture logs.
+    if platform.system() == "Windows":
+        args.append("--noconsole")
+
    # Add local qwen_tts path if specified (for editable installs)
-    qwen_tts_path = os.getenv('QWEN_TTS_PATH')
+    qwen_tts_path = os.getenv("QWEN_TTS_PATH")
    if qwen_tts_path and Path(qwen_tts_path).exists():
-        args.extend(['--paths', str(qwen_tts_path)])
-        print(f"Using local qwen_tts source from: {qwen_tts_path}")
+        args.extend(["--paths", str(qwen_tts_path)])
+        logger.info("Using local qwen_tts source from: %s", qwen_tts_path)

    # Add common hidden imports
-    args.extend([
-        '--hidden-import', 'backend',
-        '--hidden-import', 'backend.main',
-        '--hidden-import', 'backend.config',
-        '--hidden-import', 'backend.database',
-        '--hidden-import', 'backend.models',
-        '--hidden-import', 'backend.profiles',
-        '--hidden-import', 'backend.history',
-        '--hidden-import', 'backend.tts',
-        '--hidden-import', 'backend.transcribe',
-        '--hidden-import', 'backend.platform_detect',
-        '--hidden-import', 'backend.backends',
-        '--hidden-import', 'backend.backends.pytorch_backend',
-        '--hidden-import', 'backend.utils.audio',
-        '--hidden-import', 'backend.utils.cache',
-        '--hidden-import', 'backend.utils.progress',
-        '--hidden-import', 'backend.utils.hf_progress',
-        '--hidden-import', 'backend.utils.validation',
-        '--hidden-import', 'backend.cuda_download',
-        '--hidden-import', 'backend.effects',
-        '--hidden-import', 'backend.utils.effects',
-        '--hidden-import', 'backend.versions',
-        '--hidden-import', 'pedalboard',
-        '--hidden-import', 'chatterbox',
-        '--hidden-import', 'chatterbox.tts_turbo',
-        '--hidden-import', 'chatterbox.mtl_tts',
-        '--hidden-import', 'backend.backends.chatterbox_backend',
-        '--hidden-import', 'backend.backends.chatterbox_turbo_backend',
-        '--hidden-import', 'backend.backends.luxtts_backend',
-        '--hidden-import', 'zipvoice',
-        '--hidden-import', 'zipvoice.luxvoice',
-        '--collect-all', 'zipvoice',
-        '--hidden-import', 'torch',
-        '--hidden-import', 'transformers',
-        '--hidden-import', 'fastapi',
-        '--hidden-import', 'uvicorn',
-        '--hidden-import', 'sqlalchemy',
-        '--hidden-import', 'librosa',
-        '--hidden-import', 'soundfile',
-        '--hidden-import', 'qwen_tts',
-        '--hidden-import', 'qwen_tts.inference',
-        '--hidden-import', 'qwen_tts.inference.qwen3_tts_model',
-        '--hidden-import', 'qwen_tts.inference.qwen3_tts_tokenizer',
-        '--hidden-import', 'qwen_tts.core',
-        '--hidden-import', 'qwen_tts.cli',
-        '--copy-metadata', 'qwen-tts',
-        '--collect-submodules', 'qwen_tts',
-        '--collect-data', 'qwen_tts',
-        # Fix for pkg_resources and jaraco namespace packages
-        '--hidden-import', 'pkg_resources.extern',
-        '--collect-submodules', 'jaraco',
-    ])
+    args.extend(
+        [
+            "--hidden-import",
+            "backend",
+            "--hidden-import",
+            "backend.main",
+            "--hidden-import",
+            "backend.config",
+            "--hidden-import",
+            "backend.database",
+            "--hidden-import",
+            "backend.models",
+            "--hidden-import",
+            "backend.services.profiles",
+            "--hidden-import",
+            "backend.services.history",
+            "--hidden-import",
+            "backend.services.tts",
+            "--hidden-import",
+            "backend.services.transcribe",
+            "--hidden-import",
+            "backend.utils.platform_detect",
+            "--hidden-import",
+            "backend.backends",
+            "--hidden-import",
+            "backend.backends.pytorch_backend",
+            "--hidden-import",
+            "backend.utils.audio",
+            "--hidden-import",
+            "backend.utils.cache",
+            "--hidden-import",
+            "backend.utils.progress",
+            "--hidden-import",
+            "backend.utils.hf_progress",
+            "--hidden-import",
+            "backend.services.cuda",
+            "--hidden-import",
+            "backend.services.effects",
+            "--hidden-import",
+            "backend.utils.effects",
+            "--hidden-import",
+            "backend.services.versions",
+            "--hidden-import",
+            "pedalboard",
+            "--hidden-import",
+            "chatterbox",
+            "--hidden-import",
+            "chatterbox.tts_turbo",
+            "--hidden-import",
+            "chatterbox.mtl_tts",
+            "--hidden-import",
+            "backend.backends.chatterbox_backend",
+            "--hidden-import",
+            "backend.backends.chatterbox_turbo_backend",
+            "--hidden-import",
+            "backend.backends.luxtts_backend",
+            "--hidden-import",
+            "zipvoice",
+            "--hidden-import",
+            "zipvoice.luxvoice",
+            "--collect-all",
+            "zipvoice",
+            "--collect-all",
+            "linacodec",
+            "--hidden-import",
+            "torch",
+            "--hidden-import",
+            "transformers",
+            "--hidden-import",
+            "fastapi",
+            "--hidden-import",
+            "uvicorn",
+            "--hidden-import",
+            "sqlalchemy",
+            "--hidden-import",
+            "librosa",
+            "--hidden-import",
+            "soundfile",
+            "--hidden-import",
+            "qwen_tts",
+            "--hidden-import",
+            "qwen_tts.inference",
+            "--hidden-import",
+            "qwen_tts.inference.qwen3_tts_model",
+            "--hidden-import",
+            "qwen_tts.inference.qwen3_tts_tokenizer",
+            "--hidden-import",
+            "qwen_tts.core",
+            "--hidden-import",
+            "qwen_tts.cli",
+            "--copy-metadata",
+            "qwen-tts",
+            "--copy-metadata",
+            "requests",
+            "--copy-metadata",
+            "transformers",
+            "--copy-metadata",
+            "huggingface-hub",
+            "--copy-metadata",
+            "tokenizers",
+            "--copy-metadata",
+            "safetensors",
+            "--copy-metadata",
+            "tqdm",
+            "--hidden-import",
+            "requests",
+            "--collect-submodules",
+            "qwen_tts",
+            "--collect-data",
+            "qwen_tts",
+            # Fix for pkg_resources and jaraco namespace packages
+            "--hidden-import",
+            "pkg_resources.extern",
+            "--collect-submodules",
+            "jaraco",
+            # inflect uses typeguard @typechecked which calls inspect.getsource()
+            # at import time — needs .py source files, not just .pyc bytecode
+            "--collect-all",
+            "inflect",
+            # perth ships pretrained watermark model files (hparams.yaml, .pth.tar)
+            # in perth/perth_net/pretrained/ — needed by chatterbox at runtime
+            "--collect-all",
+            "perth",
+            # piper_phonemize ships espeak-ng-data/ (phoneme tables, language dicts)
+            # needed by LuxTTS for text-to-phoneme conversion
+            "--collect-all",
+            "piper_phonemize",
+        ]
+    )

    # Add CUDA-specific hidden imports
    if cuda:
-        print("Building with CUDA support")
-        args.extend([
-            '--hidden-import', 'torch.cuda',
-            '--hidden-import', 'torch.backends.cudnn',
-        ])
+        logger.info("Building with CUDA support")
+        args.extend(
+            [
+                "--hidden-import",
+                "torch.cuda",
+                "--hidden-import",
+                "torch.backends.cudnn",
+            ]
+        )
    else:
        # Exclude NVIDIA CUDA packages from CPU-only builds to keep binary small.
        # When building from a venv with CUDA torch installed, PyInstaller would
        # bundle ~3GB of NVIDIA shared libraries. We exclude both the Python
        # modules and the binary DLLs.
        nvidia_packages = [
-            'nvidia', 'nvidia.cublas', 'nvidia.cuda_cupti', 'nvidia.cuda_nvrtc',
-            'nvidia.cuda_runtime', 'nvidia.cudnn', 'nvidia.cufft', 'nvidia.curand',
-            'nvidia.cusolver', 'nvidia.cusparse', 'nvidia.nccl', 'nvidia.nvjitlink',
-            'nvidia.nvtx',
+            "nvidia",
+            "nvidia.cublas",
+            "nvidia.cuda_cupti",
+            "nvidia.cuda_nvrtc",
+            "nvidia.cuda_runtime",
+            "nvidia.cudnn",
+            "nvidia.cufft",
+            "nvidia.curand",
+            "nvidia.cusolver",
+            "nvidia.cusparse",
+            "nvidia.nccl",
+            "nvidia.nvjitlink",
+            "nvidia.nvtx",
        ]
        for pkg in nvidia_packages:
-            args.extend(['--exclude-module', pkg])
+            args.extend(["--exclude-module", pkg])

    # Add MLX-specific imports if building on Apple Silicon (never for CUDA builds)
    if is_apple_silicon() and not cuda:
-        print("Building for Apple Silicon - including MLX dependencies")
-        args.extend([
-            '--hidden-import', 'backend.backends.mlx_backend',
-            '--hidden-import', 'mlx',
-            '--hidden-import', 'mlx.core',
-            '--hidden-import', 'mlx.nn',
-            '--hidden-import', 'mlx_audio',
-            '--hidden-import', 'mlx_audio.tts',
-            '--hidden-import', 'mlx_audio.stt',
-            '--collect-submodules', 'mlx',
-            '--collect-submodules', 'mlx_audio',
-            # Use --collect-all so PyInstaller bundles both data files AND
-            # native shared libraries (.dylib, .metallib) for MLX.
-            # Previously only --collect-data was used, which caused MLX to
-            # raise OSError at runtime inside the bundled binary because
-            # the Metal shader libraries were missing.
-            '--collect-all', 'mlx',
-            '--collect-all', 'mlx_audio',
-        ])
+        logger.info("Building for Apple Silicon - including MLX dependencies")
+        args.extend(
+            [
+                "--hidden-import",
+                "backend.backends.mlx_backend",
+                "--hidden-import",
+                "mlx",
+                "--hidden-import",
+                "mlx.core",
+                "--hidden-import",
+                "mlx.nn",
+                "--hidden-import",
+                "mlx_audio",
+                "--hidden-import",
+                "mlx_audio.tts",
+                "--hidden-import",
+                "mlx_audio.stt",
+                "--collect-submodules",
+                "mlx",
+                "--collect-submodules",
+                "mlx_audio",
+                # Use --collect-all so PyInstaller bundles both data files AND
+                # native shared libraries (.dylib, .metallib) for MLX.
+                # Previously only --collect-data was used, which caused MLX to
+                # raise OSError at runtime inside the bundled binary because
+                # the Metal shader libraries were missing.
+                "--collect-all",
+                "mlx",
+                "--collect-all",
+                "mlx_audio",
+            ]
+        )
    elif not cuda:
-        print("Building for non-Apple Silicon platform - PyTorch only")
+        logger.info("Building for non-Apple Silicon platform - PyTorch only")

-    dist_dir = str(backend_dir / 'dist')
-    build_dir = str(backend_dir / 'build')
+    dist_dir = str(backend_dir / "dist")
+    build_dir = str(backend_dir / "build")

-    args.extend([
-        '--distpath', dist_dir,
-        '--workpath', build_dir,
-        '--noconfirm',
-        '--clean',
-    ])
+    args.extend(
+        [
+            "--distpath",
+            dist_dir,
+            "--workpath",
+            build_dir,
+            "--noconfirm",
+            "--clean",
+        ]
+    )

    # Change to backend directory
    os.chdir(backend_dir)
-    
+
    # For CPU builds on Windows, ensure we're using CPU-only torch.
    # If CUDA torch is installed (local dev), swap to CPU torch before building,
    # then restore CUDA torch after. This prevents PyInstaller from bundling
@@ -163,17 +278,28 @@ def build_server(cuda=False):
    restore_cuda = False
    if not cuda and platform.system() == "Windows":
        import subprocess
+
        result = subprocess.run(
-            [sys.executable, "-c", "import torch; print(torch.version.cuda or '')"],
-            capture_output=True, text=True
+            [sys.executable, "-c", "import torch; print(torch.version.cuda or '')"], capture_output=True, text=True
        )
        has_cuda_torch = bool(result.stdout.strip())
        if has_cuda_torch:
-            print("CUDA torch detected — installing CPU torch for CPU build...")
+            logger.info("CUDA torch detected — installing CPU torch for CPU build...")
            subprocess.run(
-                [sys.executable, "-m", "pip", "install", "torch", "torchvision", "torchaudio",
-                 "--index-url", "https://download.pytorch.org/whl/cpu", "--force-reinstall", "-q"],
-                check=True
+                [
+                    sys.executable,
+                    "-m",
+                    "pip",
+                    "install",
+                    "torch",
+                    "torchvision",
+                    "torchaudio",
+                    "--index-url",
+                    "https://download.pytorch.org/whl/cpu",
+                    "--force-reinstall",
+                    "-q",
+                ],
+                check=True,
            )
            restore_cuda = True

@@ -183,57 +309,34 @@ def build_server(cuda=False):
    finally:
        # Restore CUDA torch if we swapped it out (even on build failure)
        if restore_cuda:
-            print("Restoring CUDA torch...")
+            logger.info("Restoring CUDA torch...")
            import subprocess
+
            subprocess.run(
-                [sys.executable, "-m", "pip", "install", "torch", "torchvision", "torchaudio",
-                 "--index-url", "https://download.pytorch.org/whl/cu126", "--force-reinstall", "-q"],
-                check=True
+                [
+                    sys.executable,
+                    "-m",
+                    "pip",
+                    "install",
+                    "torch",
+                    "torchvision",
+                    "torchaudio",
+                    "--index-url",
+                    "https://download.pytorch.org/whl/cu126",
+                    "--force-reinstall",
+                    "-q",
+                ],
+                check=True,
            )
-    
-    print(f"Binary built in {backend_dir / 'dist' / binary_name}")
+
+    logger.info("Binary built in %s", backend_dir / "dist" / binary_name)


-def _get_cuda_dll_excludes():
-    """Get list of CUDA DLL filenames to exclude from CPU builds.
-    
-    When building locally with CUDA torch installed, PyInstaller bundles ~3GB of
-    CUDA DLLs from torch/lib/. Returns a list of DLL filenames to exclude.
-    """
-    try:
-        import torch
-        torch_lib = Path(torch.__file__).parent / 'lib'
-    except ImportError:
-        return []
-    
-    cuda_prefixes = (
-        'torch_cuda', 'cublas', 'cublasLt', 'cudnn', 'cusparse', 'cufft',
-        'cusolver', 'cusolverMg', 'curand', 'nvrtc', 'nvJitLink', 'nccl',
-        'nvperf', 'nvrtc-builtins',
-    )
-    
-    exclude_dlls = []
-    if torch_lib.exists():
-        for f in torch_lib.iterdir():
-            if f.suffix == '.dll' and any(f.name.startswith(p) for p in cuda_prefixes):
-                exclude_dlls.append(f.name)
-    
-    if exclude_dlls:
-        total_mb = sum(
-            (torch_lib / dll).stat().st_size 
-            for dll in exclude_dlls 
-            if (torch_lib / dll).exists()
-        ) / 1024 / 1024
-        print(f"CPU build: will exclude {len(exclude_dlls)} CUDA DLLs ({total_mb:.0f} MB)")
-    
-    return exclude_dlls
-
-
-if __name__ == '__main__':
+if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Build voicebox-server binary")
    parser.add_argument(
-        '--cuda',
-        action='store_true',
+        "--cuda",
+        action="store_true",
        help="Build CUDA-enabled binary (voicebox-server-cuda)",
    )
    cli_args = parser.parse_args()
@@ -4,20 +4,24 @@ Configuration module for voicebox backend.
 Handles data directory configuration for production bundling.
 """

+import logging
 import os
 from pathlib import Path

+logger = logging.getLogger(__name__)
+
 # Allow users to override the HuggingFace model download directory.
 # Set VOICEBOX_MODELS_DIR to an absolute path before starting the server.
 # This sets HF_HUB_CACHE so all huggingface_hub downloads go to that path.
 _custom_models_dir = os.environ.get("VOICEBOX_MODELS_DIR")
 if _custom_models_dir:
    os.environ["HF_HUB_CACHE"] = _custom_models_dir
-    print(f"[config] Model download path set to: {_custom_models_dir}")
+    logger.info("Model download path set to: %s", _custom_models_dir)

 # Default data directory (used in development)
 _data_dir = Path("data")

+
 def set_data_dir(path: str | Path):
    """
    Set the data directory path.
@@ -28,7 +32,8 @@ def set_data_dir(path: str | Path):
    global _data_dir
    _data_dir = Path(path)
    _data_dir.mkdir(parents=True, exist_ok=True)
-    print(f"Data directory set to: {_data_dir.absolute()}")
+    logger.info("Data directory set to: %s", _data_dir.absolute())
+

 def get_data_dir() -> Path:
    """
@@ -39,28 +44,33 @@ def get_data_dir() -> Path:
    """
    return _data_dir

+
 def get_db_path() -> Path:
    """Get database file path."""
    return _data_dir / "voicebox.db"

+
 def get_profiles_dir() -> Path:
    """Get profiles directory path."""
    path = _data_dir / "profiles"
    path.mkdir(parents=True, exist_ok=True)
    return path

+
 def get_generations_dir() -> Path:
    """Get generations directory path."""
    path = _data_dir / "generations"
    path.mkdir(parents=True, exist_ok=True)
    return path

+
 def get_cache_dir() -> Path:
    """Get cache directory path."""
    path = _data_dir / "cache"
    path.mkdir(parents=True, exist_ok=True)
    return path

+
 def get_models_dir() -> Path:
    """Get models directory path."""
    path = _data_dir / "models"
@@ -1,487 +0,0 @@
-"""
-SQLite database ORM using SQLAlchemy.
-"""
-
-from sqlalchemy import create_engine, Column, String, Integer, Float, DateTime, Text, ForeignKey, Boolean
-from sqlalchemy.ext.declarative import declarative_base
-from sqlalchemy.orm import sessionmaker, Session
-from datetime import datetime
-import uuid
-from pathlib import Path
-
-from . import config
-
-Base = declarative_base()
-
-
-class VoiceProfile(Base):
-    """Voice profile database model."""
-    __tablename__ = "profiles"
-
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, unique=True, nullable=False)
-    description = Column(Text)
-    language = Column(String, default="en")
-    avatar_path = Column(String, nullable=True)
-    effects_chain = Column(Text, nullable=True)  # JSON-serialized default effects chain
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-
-class ProfileSample(Base):
-    """Voice profile sample database model."""
-    __tablename__ = "profile_samples"
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    profile_id = Column(String, ForeignKey("profiles.id"), nullable=False)
-    audio_path = Column(String, nullable=False)
-    reference_text = Column(Text, nullable=False)
-
-
-class Generation(Base):
-    """Generation history database model."""
-    __tablename__ = "generations"
-
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    profile_id = Column(String, ForeignKey("profiles.id"), nullable=False)
-    text = Column(Text, nullable=False)
-    language = Column(String, default="en")
-    audio_path = Column(String, nullable=True)
-    duration = Column(Float, nullable=True)
-    seed = Column(Integer)
-    instruct = Column(Text)
-    engine = Column(String, default="qwen")
-    model_size = Column(String, nullable=True)
-    status = Column(String, default="completed")  # generating, completed, failed
-    error = Column(Text, nullable=True)
-    is_favorited = Column(Boolean, default=False)
-    created_at = Column(DateTime, default=datetime.utcnow)
-
-
-class Story(Base):
-    """Story database model."""
-    __tablename__ = "stories"
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    description = Column(Text)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-
-class StoryItem(Base):
-    """Story item database model (links generations to stories)."""
-    __tablename__ = "story_items"
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    story_id = Column(String, ForeignKey("stories.id"), nullable=False)
-    generation_id = Column(String, ForeignKey("generations.id"), nullable=False)
-    version_id = Column(String, ForeignKey("generation_versions.id"), nullable=True)  # Pin to specific version, null = use generation default
-    start_time_ms = Column(Integer, nullable=False, default=0)  # Milliseconds from story start
-    track = Column(Integer, nullable=False, default=0)  # Track number (0 = main track)
-    trim_start_ms = Column(Integer, nullable=False, default=0)  # Milliseconds trimmed from start
-    trim_end_ms = Column(Integer, nullable=False, default=0)  # Milliseconds trimmed from end
-    created_at = Column(DateTime, default=datetime.utcnow)
-
-
-class Project(Base):
-    """Audio studio project database model."""
-    __tablename__ = "projects"
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    data = Column(Text)  # JSON string
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-
-class GenerationVersion(Base):
-    """A version of a generation's audio (clean, processed, alternate takes)."""
-    __tablename__ = "generation_versions"
-
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    generation_id = Column(String, ForeignKey("generations.id"), nullable=False)
-    label = Column(String, nullable=False)  # "clean", "processed", or user-defined
-    audio_path = Column(String, nullable=False)
-    effects_chain = Column(Text, nullable=True)  # JSON-serialized effects config, null for clean
-    source_version_id = Column(String, ForeignKey("generation_versions.id"), nullable=True)  # Which version was used as input
-    is_default = Column(Boolean, default=False)
-    created_at = Column(DateTime, default=datetime.utcnow)
-
-
-class EffectPreset(Base):
-    """Saved effect chain preset."""
-    __tablename__ = "effect_presets"
-
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, unique=True, nullable=False)
-    description = Column(Text, nullable=True)
-    effects_chain = Column(Text, nullable=False)  # JSON-serialized effects config
-    is_builtin = Column(Boolean, default=False)
-    sort_order = Column(Integer, default=100)
-    created_at = Column(DateTime, default=datetime.utcnow)
-
-
-class AudioChannel(Base):
-    """Audio channel (bus) database model."""
-    __tablename__ = "audio_channels"
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    is_default = Column(Boolean, default=False)
-    created_at = Column(DateTime, default=datetime.utcnow)
-
-
-class ChannelDeviceMapping(Base):
-    """Mapping between channels and OS audio devices."""
-    __tablename__ = "channel_device_mappings"
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    channel_id = Column(String, ForeignKey("audio_channels.id"), nullable=False)
-    device_id = Column(String, nullable=False)  # OS device identifier
-
-
-class ProfileChannelMapping(Base):
-    """Mapping between voice profiles and audio channels (many-to-many)."""
-    __tablename__ = "profile_channel_mappings"
-    
-    profile_id = Column(String, ForeignKey("profiles.id"), primary_key=True)
-    channel_id = Column(String, ForeignKey("audio_channels.id"), primary_key=True)
-
-
-# Database setup will be initialized in init_db()
-engine = None
-SessionLocal = None
-_db_path = None
-
-
-def init_db():
-    """Initialize database tables."""
-    global engine, SessionLocal, _db_path
-
-    _db_path = config.get_db_path()
-    _db_path.parent.mkdir(parents=True, exist_ok=True)
-
-    engine = create_engine(
-        f"sqlite:///{_db_path}",
-        connect_args={"check_same_thread": False},
-    )
-
-    SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
-    
-    # Run migrations before creating tables
-    _run_migrations(engine)
-    
-    Base.metadata.create_all(bind=engine)
-    
-    # Create default channel if it doesn't exist
-    db = SessionLocal()
-    try:
-        default_channel = db.query(AudioChannel).filter(AudioChannel.is_default == True).first()
-        if not default_channel:
-            default_channel = AudioChannel(
-                id=str(uuid.uuid4()),
-                name="Default",
-                is_default=True
-            )
-            db.add(default_channel)
-            
-            # Assign all existing profiles to default channel
-            profiles = db.query(VoiceProfile).all()
-            for profile in profiles:
-                mapping = ProfileChannelMapping(
-                    profile_id=profile.id,
-                    channel_id=default_channel.id
-                )
-                db.add(mapping)
-            
-            db.commit()
-    finally:
-        db.close()
-
-    # Backfill: create "clean" GenerationVersion entries for existing generations
-    _backfill_generation_versions()
-
-    # Seed built-in effect presets
-    _seed_builtin_presets()
-
-
-def _run_migrations(engine):
-    """Run database migrations."""
-    from sqlalchemy import inspect, text
-    
-    inspector = inspect(engine)
-    
-    # Check if story_items table exists
-    if 'story_items' not in inspector.get_table_names():
-        return  # Table doesn't exist yet, will be created fresh
-    
-    # Get columns in story_items table
-    columns = {col['name'] for col in inspector.get_columns('story_items')}
-    
-    # Migration: Remove position column and ensure start_time_ms exists
-    # SQLite doesn't support DROP COLUMN easily, so we recreate the table
-    if 'position' in columns:
-        print("Migrating story_items: removing position column, using start_time_ms")
-        
-        with engine.connect() as conn:
-            # Check if start_time_ms already exists
-            has_start_time = 'start_time_ms' in columns
-            
-            if not has_start_time:
-                # First, add the new column temporarily
-                conn.execute(text("ALTER TABLE story_items ADD COLUMN start_time_ms INTEGER DEFAULT 0"))
-                
-                # Calculate timecodes from position ordering
-                result = conn.execute(text("""
-                    SELECT si.id, si.story_id, si.position, g.duration
-                    FROM story_items si
-                    JOIN generations g ON si.generation_id = g.id
-                    ORDER BY si.story_id, si.position
-                """))
-                
-                rows = result.fetchall()
-                
-                current_story_id = None
-                current_time_ms = 0
-                
-                for row in rows:
-                    item_id, story_id, position, duration = row
-                    
-                    if story_id != current_story_id:
-                        current_story_id = story_id
-                        current_time_ms = 0
-                    
-                    conn.execute(
-                        text("UPDATE story_items SET start_time_ms = :time WHERE id = :id"),
-                        {"time": current_time_ms, "id": item_id}
-                    )
-                    
-                    current_time_ms += int(duration * 1000) + 200
-                
-                conn.commit()
-            
-            # Now recreate the table without the position column
-            # 1. Create new table
-            conn.execute(text("""
-                CREATE TABLE story_items_new (
-                    id VARCHAR PRIMARY KEY,
-                    story_id VARCHAR NOT NULL,
-                    generation_id VARCHAR NOT NULL,
-                    start_time_ms INTEGER NOT NULL DEFAULT 0,
-                    created_at DATETIME,
-                    FOREIGN KEY (story_id) REFERENCES stories(id),
-                    FOREIGN KEY (generation_id) REFERENCES generations(id)
-                )
-            """))
-            
-            # 2. Copy data
-            conn.execute(text("""
-                INSERT INTO story_items_new (id, story_id, generation_id, start_time_ms, created_at)
-                SELECT id, story_id, generation_id, start_time_ms, created_at FROM story_items
-            """))
-            
-            # 3. Drop old table
-            conn.execute(text("DROP TABLE story_items"))
-            
-            # 4. Rename new table
-            conn.execute(text("ALTER TABLE story_items_new RENAME TO story_items"))
-            
-            conn.commit()
-            print("Migrated story_items table to use start_time_ms (removed position column)")
-    
-    # Migration: Add track column if it doesn't exist
-    # Re-check columns after potential position migration
-    columns = {col['name'] for col in inspector.get_columns('story_items')}
-    if 'track' not in columns:
-        print("Migrating story_items: adding track column")
-        with engine.connect() as conn:
-            conn.execute(text("ALTER TABLE story_items ADD COLUMN track INTEGER NOT NULL DEFAULT 0"))
-            conn.commit()
-            print("Added track column to story_items")
-    
-    # Migration: Add trim columns if they don't exist
-    # Re-check columns after potential track migration
-    columns = {col['name'] for col in inspector.get_columns('story_items')}
-    if 'trim_start_ms' not in columns:
-        print("Migrating story_items: adding trim_start_ms column")
-        with engine.connect() as conn:
-            conn.execute(text("ALTER TABLE story_items ADD COLUMN trim_start_ms INTEGER NOT NULL DEFAULT 0"))
-            conn.commit()
-            print("Added trim_start_ms column to story_items")
-    
-    columns = {col['name'] for col in inspector.get_columns('story_items')}
-    if 'trim_end_ms' not in columns:
-        print("Migrating story_items: adding trim_end_ms column")
-        with engine.connect() as conn:
-            conn.execute(text("ALTER TABLE story_items ADD COLUMN trim_end_ms INTEGER NOT NULL DEFAULT 0"))
-            conn.commit()
-            print("Added trim_end_ms column to story_items")
-
-    # Migration: Add avatar_path to profiles table
-    if 'profiles' in inspector.get_table_names():
-        columns = {col['name'] for col in inspector.get_columns('profiles')}
-        if 'avatar_path' not in columns:
-            print("Migrating profiles: adding avatar_path column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE profiles ADD COLUMN avatar_path VARCHAR"))
-                conn.commit()
-                print("Added avatar_path column to profiles")
-
-    # Migration: Add status and error columns to generations table
-    if 'generations' in inspector.get_table_names():
-        columns = {col['name'] for col in inspector.get_columns('generations')}
-        if 'status' not in columns:
-            print("Migrating generations: adding status column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE generations ADD COLUMN status VARCHAR DEFAULT 'completed'"))
-                conn.commit()
-                print("Added status column to generations")
-        if 'error' not in columns:
-            print("Migrating generations: adding error column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE generations ADD COLUMN error TEXT"))
-                conn.commit()
-                print("Added error column to generations")
-        if 'engine' not in columns:
-            print("Migrating generations: adding engine column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE generations ADD COLUMN engine VARCHAR DEFAULT 'qwen'"))
-                conn.commit()
-                print("Added engine column to generations")
-        # Re-read columns after engine migration (variable name shadows outer `engine`)
-        columns = {col['name'] for col in inspector.get_columns('generations')}
-        if 'model_size' not in columns:
-            print("Migrating generations: adding model_size column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE generations ADD COLUMN model_size VARCHAR"))
-                conn.commit()
-                print("Added model_size column to generations")
-
-    # Migration: Add effects_chain to profiles table
-    if 'profiles' in inspector.get_table_names():
-        columns = {col['name'] for col in inspector.get_columns('profiles')}
-        if 'effects_chain' not in columns:
-            print("Migrating profiles: adding effects_chain column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE profiles ADD COLUMN effects_chain TEXT"))
-                conn.commit()
-                print("Added effects_chain column to profiles")
-
-    # Migration: Add sort_order to effect_presets table
-    if 'effect_presets' in inspector.get_table_names():
-        columns = {col['name'] for col in inspector.get_columns('effect_presets')}
-        if 'sort_order' not in columns:
-            print("Migrating effect_presets: adding sort_order column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE effect_presets ADD COLUMN sort_order INTEGER DEFAULT 100"))
-                conn.commit()
-                print("Added sort_order column to effect_presets")
-
-    # Migration: Add version_id column to story_items table
-    if 'story_items' in inspector.get_table_names():
-        columns = {col['name'] for col in inspector.get_columns('story_items')}
-        if 'version_id' not in columns:
-            print("Migrating story_items: adding version_id column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE story_items ADD COLUMN version_id VARCHAR"))
-                conn.commit()
-                print("Added version_id column to story_items")
-
-    # Migration: Add source_version_id to generation_versions table
-    if 'generation_versions' in inspector.get_table_names():
-        columns = {col['name'] for col in inspector.get_columns('generation_versions')}
-        if 'source_version_id' not in columns:
-            print("Migrating generation_versions: adding source_version_id column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE generation_versions ADD COLUMN source_version_id VARCHAR"))
-                conn.commit()
-                print("Added source_version_id column to generation_versions")
-
-    if 'generations' in inspector.get_table_names():
-        columns = {col['name'] for col in inspector.get_columns('generations')}
-        if 'is_favorited' not in columns:
-            print("Migrating generations: adding is_favorited column")
-            with engine.connect() as conn:
-                conn.execute(text("ALTER TABLE generations ADD COLUMN is_favorited BOOLEAN DEFAULT 0"))
-                conn.commit()
-                print("Added is_favorited column to generations")
-
-    # Migration: Create generation_versions for existing generations
-    # (populate after tables are created, handled in init_db)
-
-
-def _backfill_generation_versions():
-    """Create 'clean' version entries for existing generations that don't have any."""
-    db = SessionLocal()
-    try:
-        from pathlib import Path as _Path
-
-        # Find generations that have no version entries
-        existing_version_gen_ids = {
-            row[0] for row in db.query(GenerationVersion.generation_id).all()
-        }
-        generations = db.query(Generation).filter(
-            Generation.status == "completed",
-            Generation.audio_path.isnot(None),
-            Generation.audio_path != "",
-        ).all()
-
-        count = 0
-        for gen in generations:
-            if gen.id in existing_version_gen_ids:
-                continue
-            if not _Path(gen.audio_path).exists():
-                continue
-            version = GenerationVersion(
-                id=str(uuid.uuid4()),
-                generation_id=gen.id,
-                label="clean",
-                audio_path=gen.audio_path,
-                effects_chain=None,
-                is_default=True,
-            )
-            db.add(version)
-            count += 1
-
-        if count > 0:
-            db.commit()
-            print(f"Backfilled {count} generation version entries")
-    finally:
-        db.close()
-
-
-def _seed_builtin_presets():
-    """Ensure built-in effect presets exist in the database."""
-    import json
-    from .utils.effects import BUILTIN_PRESETS
-
-    db = SessionLocal()
-    try:
-        for idx, (key, preset_data) in enumerate(BUILTIN_PRESETS.items()):
-            sort_order = preset_data.get("sort_order", idx)
-            existing = db.query(EffectPreset).filter_by(name=preset_data["name"]).first()
-            if not existing:
-                preset = EffectPreset(
-                    id=str(uuid.uuid4()),
-                    name=preset_data["name"],
-                    description=preset_data.get("description"),
-                    effects_chain=json.dumps(preset_data["effects_chain"]),
-                    is_builtin=True,
-                    sort_order=sort_order,
-                )
-                db.add(preset)
-            elif existing.sort_order != sort_order:
-                existing.sort_order = sort_order
-        db.commit()
-    finally:
-        db.close()
-
-
-def get_db():
-    """Get database session (generator for dependency injection)."""
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
@@ -0,0 +1,44 @@
+"""Database package — ORM models, session management, and migrations.
+
+Re-exports all public symbols so that ``from .database import get_db``
+and ``from .database import Generation as DBGeneration`` continue to work
+without changing any importers.
+"""
+
+from .models import (
+    Base,
+    AudioChannel,
+    ChannelDeviceMapping,
+    EffectPreset,
+    Generation,
+    GenerationVersion,
+    ProfileChannelMapping,
+    ProfileSample,
+    Project,
+    Story,
+    StoryItem,
+    VoiceProfile,
+)
+from .session import engine, SessionLocal, _db_path, init_db, get_db
+
+__all__ = [
+    # Models
+    "Base",
+    "AudioChannel",
+    "ChannelDeviceMapping",
+    "EffectPreset",
+    "Generation",
+    "GenerationVersion",
+    "ProfileChannelMapping",
+    "ProfileSample",
+    "Project",
+    "Story",
+    "StoryItem",
+    "VoiceProfile",
+    # Session
+    "engine",
+    "SessionLocal",
+    "_db_path",
+    "init_db",
+    "get_db",
+]
@@ -0,0 +1,170 @@
+"""Column-level migrations for the voicebox SQLite database.
+
+Why not Alembic?  voicebox is a single-user desktop app shipping as a
+PyInstaller binary.  Every user has exactly one SQLite file.  Alembic's
+strengths -- migration tracking across environments, rollback, team
+coordination -- don't apply here and would add bundling complexity
+(alembic.ini, env.py, versions/ directory all need to survive
+PyInstaller).  The column-existence checks below are idempotent, run in
+<50 ms on startup, and have worked reliably across 12 schema changes.
+If the project ever moves to a server-based deployment or Postgres, this
+decision should be revisited.
+
+Adding a new migration:
+    1. Append a new ``_migrate_*`` helper at the bottom of this file.
+    2. Call it from ``run_migrations()`` in the appropriate spot.
+    3. The helper should check column/table existence before acting
+       (idempotent) and print a short message when it does real work.
+"""
+
+import logging
+
+from sqlalchemy import inspect, text
+
+logger = logging.getLogger(__name__)
+
+
+def run_migrations(engine) -> None:
+    """Run all schema migrations.  Safe to call on every startup."""
+    inspector = inspect(engine)
+    tables = set(inspector.get_table_names())
+
+    _migrate_story_items(engine, inspector, tables)
+    _migrate_profiles(engine, inspector, tables)
+    _migrate_generations(engine, inspector, tables)
+    _migrate_effect_presets(engine, inspector, tables)
+    _migrate_generation_versions(engine, inspector, tables)
+
+
+# -- helpers ---------------------------------------------------------------
+
+def _get_columns(inspector, table: str) -> set[str]:
+    return {col["name"] for col in inspector.get_columns(table)}
+
+
+def _add_column(engine, table: str, column_sql: str, label: str) -> None:
+    """Add a column if it doesn't already exist."""
+    with engine.connect() as conn:
+        conn.execute(text(f"ALTER TABLE {table} ADD COLUMN {column_sql}"))
+        conn.commit()
+    logger.info("Added %s column to %s", label, table)
+
+
+# -- per-table migrations --------------------------------------------------
+
+def _migrate_story_items(engine, inspector, tables: set[str]) -> None:
+    if "story_items" not in tables:
+        return
+
+    columns = _get_columns(inspector, "story_items")
+
+    # Replace position-based ordering with absolute timecodes
+    if "position" in columns:
+        logger.info("Migrating story_items: removing position column, using start_time_ms")
+        with engine.connect() as conn:
+            if "start_time_ms" not in columns:
+                conn.execute(text(
+                    "ALTER TABLE story_items ADD COLUMN start_time_ms INTEGER DEFAULT 0"
+                ))
+                result = conn.execute(text("""
+                    SELECT si.id, si.story_id, si.position, g.duration
+                    FROM story_items si
+                    JOIN generations g ON si.generation_id = g.id
+                    ORDER BY si.story_id, si.position
+                """))
+                current_story_id = None
+                current_time_ms = 0
+                for item_id, story_id, _position, duration in result.fetchall():
+                    if story_id != current_story_id:
+                        current_story_id = story_id
+                        current_time_ms = 0
+                    conn.execute(
+                        text("UPDATE story_items SET start_time_ms = :time WHERE id = :id"),
+                        {"time": current_time_ms, "id": item_id},
+                    )
+                    current_time_ms += int((duration or 0) * 1000) + 200
+                conn.commit()
+
+            # Recreate table without the position column (SQLite lacks DROP COLUMN)
+            conn.execute(text("""
+                CREATE TABLE story_items_new (
+                    id VARCHAR PRIMARY KEY,
+                    story_id VARCHAR NOT NULL,
+                    generation_id VARCHAR NOT NULL,
+                    start_time_ms INTEGER NOT NULL DEFAULT 0,
+                    track INTEGER NOT NULL DEFAULT 0,
+                    trim_start_ms INTEGER NOT NULL DEFAULT 0,
+                    trim_end_ms INTEGER NOT NULL DEFAULT 0,
+                    version_id VARCHAR,
+                    created_at DATETIME,
+                    FOREIGN KEY (story_id) REFERENCES stories(id),
+                    FOREIGN KEY (generation_id) REFERENCES generations(id)
+                )
+            """))
+            conn.execute(text("""
+                INSERT INTO story_items_new (id, story_id, generation_id, start_time_ms, track, trim_start_ms, trim_end_ms, version_id, created_at)
+                SELECT id, story_id, generation_id, start_time_ms,
+                    COALESCE(track, 0), COALESCE(trim_start_ms, 0), COALESCE(trim_end_ms, 0), version_id, created_at
+                FROM story_items
+            """))
+            conn.execute(text("DROP TABLE story_items"))
+            conn.execute(text("ALTER TABLE story_items_new RENAME TO story_items"))
+            conn.commit()
+
+        # Re-read after table recreation
+        columns = _get_columns(inspector, "story_items")
+
+    if "track" not in columns:
+        _add_column(engine, "story_items", "track INTEGER NOT NULL DEFAULT 0", "track")
+    # Re-read so subsequent checks see new columns
+    columns = _get_columns(inspector, "story_items")
+    if "trim_start_ms" not in columns:
+        _add_column(engine, "story_items", "trim_start_ms INTEGER NOT NULL DEFAULT 0", "trim_start_ms")
+    if "trim_end_ms" not in columns:
+        _add_column(engine, "story_items", "trim_end_ms INTEGER NOT NULL DEFAULT 0", "trim_end_ms")
+    if "version_id" not in columns:
+        _add_column(engine, "story_items", "version_id VARCHAR", "version_id")
+
+
+def _migrate_profiles(engine, inspector, tables: set[str]) -> None:
+    if "profiles" not in tables:
+        return
+    columns = _get_columns(inspector, "profiles")
+    if "avatar_path" not in columns:
+        _add_column(engine, "profiles", "avatar_path VARCHAR", "avatar_path")
+    if "effects_chain" not in columns:
+        _add_column(engine, "profiles", "effects_chain TEXT", "effects_chain")
+
+
+def _migrate_generations(engine, inspector, tables: set[str]) -> None:
+    if "generations" not in tables:
+        return
+    columns = _get_columns(inspector, "generations")
+    if "status" not in columns:
+        _add_column(engine, "generations", "status VARCHAR DEFAULT 'completed'", "status")
+    if "error" not in columns:
+        _add_column(engine, "generations", "error TEXT", "error")
+    if "engine" not in columns:
+        _add_column(engine, "generations", "engine VARCHAR DEFAULT 'qwen'", "engine")
+    # Re-read after engine column (variable name shadows outer scope in old code)
+    columns = _get_columns(inspector, "generations")
+    if "model_size" not in columns:
+        _add_column(engine, "generations", "model_size VARCHAR", "model_size")
+    if "is_favorited" not in columns:
+        _add_column(engine, "generations", "is_favorited BOOLEAN DEFAULT 0", "is_favorited")
+
+
+def _migrate_effect_presets(engine, inspector, tables: set[str]) -> None:
+    if "effect_presets" not in tables:
+        return
+    columns = _get_columns(inspector, "effect_presets")
+    if "sort_order" not in columns:
+        _add_column(engine, "effect_presets", "sort_order INTEGER DEFAULT 100", "sort_order")
+
+
+def _migrate_generation_versions(engine, inspector, tables: set[str]) -> None:
+    if "generation_versions" not in tables:
+        return
+    columns = _get_columns(inspector, "generation_versions")
+    if "source_version_id" not in columns:
+        _add_column(engine, "generation_versions", "source_version_id VARCHAR", "source_version_id")
@@ -0,0 +1,155 @@
+"""ORM model definitions for the voicebox SQLite database."""
+
+from datetime import datetime
+import uuid
+
+from sqlalchemy import Column, String, Integer, Float, DateTime, Text, ForeignKey, Boolean
+from sqlalchemy.ext.declarative import declarative_base
+
+Base = declarative_base()
+
+
+class VoiceProfile(Base):
+    """Voice profile."""
+
+    __tablename__ = "profiles"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String, unique=True, nullable=False)
+    description = Column(Text)
+    language = Column(String, default="en")
+    avatar_path = Column(String, nullable=True)
+    effects_chain = Column(Text, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+
+class ProfileSample(Base):
+    """Audio sample attached to a voice profile."""
+
+    __tablename__ = "profile_samples"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    profile_id = Column(String, ForeignKey("profiles.id"), nullable=False)
+    audio_path = Column(String, nullable=False)
+    reference_text = Column(Text, nullable=False)
+
+
+class Generation(Base):
+    """A single TTS generation."""
+
+    __tablename__ = "generations"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    profile_id = Column(String, ForeignKey("profiles.id"), nullable=False)
+    text = Column(Text, nullable=False)
+    language = Column(String, default="en")
+    audio_path = Column(String, nullable=True)
+    duration = Column(Float, nullable=True)
+    seed = Column(Integer)
+    instruct = Column(Text)
+    engine = Column(String, default="qwen")
+    model_size = Column(String, nullable=True)
+    status = Column(String, default="completed")
+    error = Column(Text, nullable=True)
+    is_favorited = Column(Boolean, default=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class Story(Base):
+    """A story that sequences multiple generations."""
+
+    __tablename__ = "stories"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String, nullable=False)
+    description = Column(Text)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+
+class StoryItem(Base):
+    """Links a generation to a story at a specific timecode."""
+
+    __tablename__ = "story_items"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    story_id = Column(String, ForeignKey("stories.id"), nullable=False)
+    generation_id = Column(String, ForeignKey("generations.id"), nullable=False)
+    version_id = Column(String, ForeignKey("generation_versions.id"), nullable=True)
+    start_time_ms = Column(Integer, nullable=False, default=0)
+    track = Column(Integer, nullable=False, default=0)
+    trim_start_ms = Column(Integer, nullable=False, default=0)
+    trim_end_ms = Column(Integer, nullable=False, default=0)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class Project(Base):
+    """Audio studio project (JSON blob)."""
+
+    __tablename__ = "projects"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String, nullable=False)
+    data = Column(Text)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+
+class GenerationVersion(Base):
+    """A version of a generation's audio (original, processed, alternate takes)."""
+
+    __tablename__ = "generation_versions"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    generation_id = Column(String, ForeignKey("generations.id"), nullable=False)
+    label = Column(String, nullable=False)
+    audio_path = Column(String, nullable=False)
+    effects_chain = Column(Text, nullable=True)
+    source_version_id = Column(String, ForeignKey("generation_versions.id"), nullable=True)
+    is_default = Column(Boolean, default=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class EffectPreset(Base):
+    """Saved effect chain preset."""
+
+    __tablename__ = "effect_presets"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String, unique=True, nullable=False)
+    description = Column(Text, nullable=True)
+    effects_chain = Column(Text, nullable=False)
+    is_builtin = Column(Boolean, default=False)
+    sort_order = Column(Integer, default=100)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class AudioChannel(Base):
+    """Audio output channel (bus)."""
+
+    __tablename__ = "audio_channels"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String, nullable=False)
+    is_default = Column(Boolean, default=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class ChannelDeviceMapping(Base):
+    """Mapping between a channel and an OS audio device."""
+
+    __tablename__ = "channel_device_mappings"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    channel_id = Column(String, ForeignKey("audio_channels.id"), nullable=False)
+    device_id = Column(String, nullable=False)
+
+
+class ProfileChannelMapping(Base):
+    """Many-to-many mapping between voice profiles and audio channels."""
+
+    __tablename__ = "profile_channel_mappings"
+
+    profile_id = Column(String, ForeignKey("profiles.id"), primary_key=True)
+    channel_id = Column(String, ForeignKey("audio_channels.id"), primary_key=True)
@@ -0,0 +1,71 @@
+"""Post-migration data seeding and backfills."""
+
+import json
+import logging
+import uuid
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def backfill_generation_versions(SessionLocal, Generation, GenerationVersion) -> None:
+    """Create 'clean' version entries for generations that predate the versions feature."""
+    db = SessionLocal()
+    try:
+        existing_version_gen_ids = {
+            row[0] for row in db.query(GenerationVersion.generation_id).all()
+        }
+        generations = db.query(Generation).filter(
+            Generation.status == "completed",
+            Generation.audio_path.isnot(None),
+            Generation.audio_path != "",
+        ).all()
+
+        count = 0
+        for gen in generations:
+            if gen.id in existing_version_gen_ids:
+                continue
+            if not Path(gen.audio_path).exists():
+                continue
+            version = GenerationVersion(
+                id=str(uuid.uuid4()),
+                generation_id=gen.id,
+                label="clean",
+                audio_path=gen.audio_path,
+                effects_chain=None,
+                is_default=True,
+            )
+            db.add(version)
+            count += 1
+
+        if count > 0:
+            db.commit()
+            logger.info("Backfilled %d generation version entries", count)
+    finally:
+        db.close()
+
+
+def seed_builtin_presets(SessionLocal, EffectPreset) -> None:
+    """Ensure built-in effect presets exist in the database."""
+    from ..utils.effects import BUILTIN_PRESETS
+
+    db = SessionLocal()
+    try:
+        for idx, (_key, preset_data) in enumerate(BUILTIN_PRESETS.items()):
+            sort_order = preset_data.get("sort_order", idx)
+            existing = db.query(EffectPreset).filter_by(name=preset_data["name"]).first()
+            if not existing:
+                preset = EffectPreset(
+                    id=str(uuid.uuid4()),
+                    name=preset_data["name"],
+                    description=preset_data.get("description"),
+                    effects_chain=json.dumps(preset_data["effects_chain"]),
+                    is_builtin=True,
+                    sort_order=sort_order,
+                )
+                db.add(preset)
+            elif existing.sort_order != sort_order:
+                existing.sort_order = sort_order
+        db.commit()
+    finally:
+        db.close()
@@ -0,0 +1,78 @@
+"""Engine creation, initialization, and session management."""
+
+import logging
+import uuid
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from .. import config
+from .models import (
+    Base,
+    AudioChannel,
+    EffectPreset,
+    Generation,
+    GenerationVersion,
+    ProfileChannelMapping,
+    VoiceProfile,
+)
+from .migrations import run_migrations
+from .seed import backfill_generation_versions, seed_builtin_presets
+
+logger = logging.getLogger(__name__)
+
+# Initialized by init_db()
+engine = None
+SessionLocal = None
+_db_path = None
+
+
+def init_db() -> None:
+    """Initialize the database engine, run migrations, create tables, and seed data."""
+    global engine, SessionLocal, _db_path
+
+    _db_path = config.get_db_path()
+    _db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    engine = create_engine(
+        f"sqlite:///{_db_path}",
+        connect_args={"check_same_thread": False},
+    )
+
+    SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+    run_migrations(engine)
+    Base.metadata.create_all(bind=engine)
+
+    # Create default audio channel if it doesn't exist
+    db = SessionLocal()
+    try:
+        default_channel = db.query(AudioChannel).filter(AudioChannel.is_default == True).first()
+        if not default_channel:
+            default_channel = AudioChannel(
+                id=str(uuid.uuid4()),
+                name="Default",
+                is_default=True,
+            )
+            db.add(default_channel)
+
+            for profile in db.query(VoiceProfile).all():
+                db.add(ProfileChannelMapping(
+                    profile_id=profile.id,
+                    channel_id=default_channel.id,
+                ))
+            db.commit()
+    finally:
+        db.close()
+
+    backfill_generation_versions(SessionLocal, Generation, GenerationVersion)
+    seed_builtin_presets(SessionLocal, EffectPreset)
+
+
+def get_db():
+    """Yield a database session (FastAPI dependency)."""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
@@ -1,221 +0,0 @@
-"""
-Example usage of the voicebox backend API.
-
-This script demonstrates how to:
-1. Create a voice profile
-2. Add samples to the profile
-3. Generate speech
-4. List history
-"""
-
-import requests
-import time
-from pathlib import Path
-
-# API base URL
-BASE_URL = "http://localhost:8000"
-
-
-def check_health():
-    """Check if the server is running."""
-    response = requests.get(f"{BASE_URL}/health")
-    data = response.json()
-    print(f"Server status: {data['status']}")
-    print(f"Model loaded: {data['model_loaded']}")
-    print(f"GPU available: {data['gpu_available']}")
-    print()
-    return data
-
-
-def create_profile(name: str, description: str = None, language: str = "en"):
-    """Create a new voice profile."""
-    response = requests.post(
-        f"{BASE_URL}/profiles",
-        json={
-            "name": name,
-            "description": description,
-            "language": language,
-        },
-    )
-    response.raise_for_status()
-    profile = response.json()
-    print(f"Created profile: {profile['name']} (ID: {profile['id']})")
-    return profile
-
-
-def add_sample(profile_id: str, audio_file: str, reference_text: str):
-    """Add a sample to a voice profile."""
-    with open(audio_file, "rb") as f:
-        files = {"file": f}
-        data = {"reference_text": reference_text}
-        response = requests.post(
-            f"{BASE_URL}/profiles/{profile_id}/samples",
-            files=files,
-            data=data,
-        )
-    response.raise_for_status()
-    sample = response.json()
-    print(f"Added sample: {sample['id']}")
-    return sample
-
-
-def generate_speech(profile_id: str, text: str, language: str = "en", seed: int = None):
-    """Generate speech using a voice profile."""
-    print(f"Generating speech: '{text[:50]}...'")
-    start_time = time.time()
-    
-    response = requests.post(
-        f"{BASE_URL}/generate",
-        json={
-            "profile_id": profile_id,
-            "text": text,
-            "language": language,
-            "seed": seed,
-        },
-    )
-    response.raise_for_status()
-    generation = response.json()
-    
-    elapsed = time.time() - start_time
-    print(f"Generated in {elapsed:.2f}s (duration: {generation['duration']:.2f}s)")
-    print(f"Generation ID: {generation['id']}")
-    return generation
-
-
-def download_audio(generation_id: str, output_file: str):
-    """Download generated audio."""
-    response = requests.get(f"{BASE_URL}/audio/{generation_id}")
-    response.raise_for_status()
-    
-    with open(output_file, "wb") as f:
-        f.write(response.content)
-    
-    print(f"Saved audio to: {output_file}")
-
-
-def list_profiles():
-    """List all voice profiles."""
-    response = requests.get(f"{BASE_URL}/profiles")
-    response.raise_for_status()
-    profiles = response.json()
-    
-    print(f"Found {len(profiles)} profiles:")
-    for profile in profiles:
-        print(f"  - {profile['name']} (ID: {profile['id']})")
-    
-    return profiles
-
-
-def list_history(profile_id: str = None, limit: int = 10):
-    """List generation history."""
-    params = {"limit": limit}
-    if profile_id:
-        params["profile_id"] = profile_id
-    
-    response = requests.get(f"{BASE_URL}/history", params=params)
-    response.raise_for_status()
-    history = response.json()
-    
-    print(f"Found {len(history)} generations:")
-    for gen in history:
-        print(f"  - {gen['text'][:50]}... ({gen['duration']:.2f}s)")
-    
-    return history
-
-
-def transcribe_audio(audio_file: str, language: str = None):
-    """Transcribe audio file."""
-    print(f"Transcribing: {audio_file}")
-    
-    with open(audio_file, "rb") as f:
-        files = {"file": f}
-        data = {}
-        if language:
-            data["language"] = language
-        
-        response = requests.post(
-            f"{BASE_URL}/transcribe",
-            files=files,
-            data=data,
-        )
-    
-    response.raise_for_status()
-    result = response.json()
-    
-    print(f"Transcription: {result['text']}")
-    print(f"Duration: {result['duration']:.2f}s")
-    return result
-
-
-def main():
-    """Run example workflow."""
-    print("=" * 60)
-    print("voicebox Backend API Example")
-    print("=" * 60)
-    print()
-    
-    # 1. Check health
-    print("1. Checking server health...")
-    check_health()
-    
-    # 2. Create a profile
-    print("2. Creating voice profile...")
-    profile = create_profile(
-        name="Example Voice",
-        description="A test voice profile",
-        language="en",
-    )
-    profile_id = profile["id"]
-    print()
-    
-    # 3. Add samples (you'll need actual audio files)
-    print("3. Adding samples...")
-    print("   (Skipping - add your own audio files here)")
-    # Uncomment and add your audio file:
-    # sample = add_sample(
-    #     profile_id,
-    #     "path/to/your/sample.wav",
-    #     "This is the transcript of the audio",
-    # )
-    print()
-    
-    # 4. Generate speech (requires samples to be added first)
-    print("4. Generating speech...")
-    print("   (Skipping - add samples first)")
-    # Uncomment after adding samples:
-    # generation = generate_speech(
-    #     profile_id,
-    #     "Hello, this is a test of the voice cloning system.",
-    #     language="en",
-    #     seed=42,
-    # )
-    # 
-    # # 5. Download audio
-    # print("\n5. Downloading audio...")
-    # download_audio(generation["id"], "output.wav")
-    print()
-    
-    # 6. List profiles
-    print("6. Listing all profiles...")
-    list_profiles()
-    print()
-    
-    # 7. List history
-    print("7. Listing generation history...")
-    list_history(limit=5)
-    print()
-    
-    # 8. Transcribe audio (you'll need an audio file)
-    print("8. Transcribing audio...")
-    print("   (Skipping - add your own audio file here)")
-    # Uncomment and add your audio file:
-    # transcribe_audio("path/to/audio.wav", language="en")
-    print()
-    
-    print("=" * 60)
-    print("Example complete!")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()
@@ -1,48 +0,0 @@
-"""
-Database migration script to add instruct column to generations table.
-
-Run this once to update existing databases:
-    python -m backend.migrate_add_instruct
-"""
-
-import sqlite3
-import os
-from pathlib import Path
-
-
-def migrate():
-    """Add instruct column to generations table if it doesn't exist."""
-    # Get data directory
-    data_dir = os.environ.get("VOICEBOX_DATA_DIR")
-    if data_dir:
-        db_path = Path(data_dir) / "voicebox.db"
-    else:
-        db_path = Path.cwd() / "data" / "voicebox.db"
-
-    if not db_path.exists():
-        print(f"Database not found at {db_path}, skipping migration")
-        return
-
-    conn = sqlite3.connect(db_path)
-    cursor = conn.cursor()
-
-    # Check if instruct column already exists
-    cursor.execute("PRAGMA table_info(generations)")
-    columns = [row[1] for row in cursor.fetchall()]
-
-    if 'instruct' in columns:
-        print("instruct column already exists, skipping migration")
-        conn.close()
-        return
-
-    # Add instruct column
-    print("Adding instruct column to generations table...")
-    cursor.execute("ALTER TABLE generations ADD COLUMN instruct TEXT")
-    conn.commit()
-    conn.close()
-
-    print("Migration complete!")
-
-
-if __name__ == "__main__":
-    migrate()
@@ -9,13 +9,17 @@ from datetime import datetime

 class VoiceProfileCreate(BaseModel):
    """Request model for creating a voice profile."""
+
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = Field(None, max_length=500)
-    language: str = Field(default="en", pattern="^(zh|en|ja|ko|de|fr|ru|pt|es|it|he|ar|da|el|fi|hi|ms|nl|no|pl|sv|sw|tr)$")
+    language: str = Field(
+        default="en", pattern="^(zh|en|ja|ko|de|fr|ru|pt|es|it|he|ar|da|el|fi|hi|ms|nl|no|pl|sv|sw|tr)$"
+    )


 class VoiceProfileResponse(BaseModel):
    """Response model for voice profile."""
+
    id: str
    name: str
    description: Optional[str]
@@ -33,16 +37,19 @@ class VoiceProfileResponse(BaseModel):

 class ProfileSampleCreate(BaseModel):
    """Request model for adding a sample to a profile."""
+
    reference_text: str = Field(..., min_length=1, max_length=1000)


 class ProfileSampleUpdate(BaseModel):
    """Request model for updating a profile sample."""
+
    reference_text: str = Field(..., min_length=1, max_length=1000)


 class ProfileSampleResponse(BaseModel):
    """Response model for profile sample."""
+
    id: str
    profile_id: str
    audio_path: str
@@ -54,21 +61,29 @@ class ProfileSampleResponse(BaseModel):

 class GenerationRequest(BaseModel):
    """Request model for voice generation."""
+
    profile_id: str
    text: str = Field(..., min_length=1, max_length=50000)
-    language: str = Field(default="en", pattern="^(zh|en|ja|ko|de|fr|ru|pt|es|it|he)$")
+    language: str = Field(default="en", pattern="^(zh|en|ja|ko|de|fr|ru|pt|es|it|he|ar|da|el|fi|hi|ms|nl|no|pl|sv|sw|tr)$")
    seed: Optional[int] = Field(None, ge=0)
    model_size: Optional[str] = Field(default="1.7B", pattern="^(1\\.7B|0\\.6B)$")
    instruct: Optional[str] = Field(None, max_length=500)
    engine: Optional[str] = Field(default="qwen", pattern="^(qwen|luxtts|chatterbox|chatterbox_turbo)$")
-    max_chunk_chars: int = Field(default=800, ge=100, le=5000, description="Max characters per chunk for long text splitting")
-    crossfade_ms: int = Field(default=50, ge=0, le=500, description="Crossfade duration in ms between chunks (0 for hard cut)")
+    max_chunk_chars: int = Field(
+        default=800, ge=100, le=5000, description="Max characters per chunk for long text splitting"
+    )
+    crossfade_ms: int = Field(
+        default=50, ge=0, le=500, description="Crossfade duration in ms between chunks (0 for hard cut)"
+    )
    normalize: bool = Field(default=True, description="Normalize output audio volume")
-    effects_chain: Optional[List["EffectConfig"]] = Field(None, description="Effects chain to apply after generation (overrides profile default)")
+    effects_chain: Optional[List["EffectConfig"]] = Field(
+        None, description="Effects chain to apply after generation (overrides profile default)"
+    )


 class GenerationResponse(BaseModel):
    """Response model for voice generation."""
+
    id: str
    profile_id: str
    text: str
@@ -92,6 +107,7 @@ class GenerationResponse(BaseModel):

 class HistoryQuery(BaseModel):
    """Query model for generation history."""
+
    profile_id: Optional[str] = None
    search: Optional[str] = None
    limit: int = Field(default=50, ge=1, le=100)
@@ -100,6 +116,7 @@ class HistoryQuery(BaseModel):

 class HistoryResponse(BaseModel):
    """Response model for history entry (includes profile name)."""
+
    id: str
    profile_id: str
    profile_name: str
@@ -124,23 +141,27 @@ class HistoryResponse(BaseModel):

 class HistoryListResponse(BaseModel):
    """Response model for history list."""
+
    items: List[HistoryResponse]
    total: int


 class TranscriptionRequest(BaseModel):
    """Request model for audio transcription."""
+
    language: Optional[str] = Field(None, pattern="^(en|zh)$")


 class TranscriptionResponse(BaseModel):
    """Response model for transcription."""
+
    text: str
    duration: float


 class HealthResponse(BaseModel):
    """Response model for health check."""
+
    status: str
    model_loaded: bool
    model_downloaded: Optional[bool] = None  # Whether model is cached/downloaded
@@ -154,6 +175,7 @@ class HealthResponse(BaseModel):

 class DirectoryCheck(BaseModel):
    """Health status for a single directory."""
+
    path: str
    exists: bool
    writable: bool
@@ -162,6 +184,7 @@ class DirectoryCheck(BaseModel):

 class FilesystemHealthResponse(BaseModel):
    """Response model for filesystem health check."""
+
    healthy: bool
    disk_free_mb: Optional[float] = None
    disk_total_mb: Optional[float] = None
@@ -170,6 +193,7 @@ class FilesystemHealthResponse(BaseModel):

 class ModelStatus(BaseModel):
    """Response model for model status."""
+
    model_name: str
    display_name: str
    hf_repo_id: Optional[str] = None  # HuggingFace repository ID
@@ -181,33 +205,38 @@ class ModelStatus(BaseModel):

 class ModelStatusListResponse(BaseModel):
    """Response model for model status list."""
+
    models: List[ModelStatus]


 class ModelDownloadRequest(BaseModel):
    """Request model for triggering model download."""
+
    model_name: str


 class ModelMigrateRequest(BaseModel):
    """Request model for migrating models to a new directory."""
+
    destination: str


 class ActiveDownloadTask(BaseModel):
    """Response model for active download task."""
+
    model_name: str
    status: str
    started_at: datetime
    error: Optional[str] = None
    progress: Optional[float] = None  # 0-100 percentage
-    current: Optional[int] = None     # bytes downloaded
-    total: Optional[int] = None       # total bytes
-    filename: Optional[str] = None    # current file being downloaded
+    current: Optional[int] = None  # bytes downloaded
+    total: Optional[int] = None  # total bytes
+    filename: Optional[str] = None  # current file being downloaded


 class ActiveGenerationTask(BaseModel):
    """Response model for active generation task."""
+
    task_id: str
    profile_id: str
    text_preview: str
@@ -216,24 +245,28 @@ class ActiveGenerationTask(BaseModel):

 class ActiveTasksResponse(BaseModel):
    """Response model for active tasks."""
+
    downloads: List[ActiveDownloadTask]
    generations: List[ActiveGenerationTask]


 class AudioChannelCreate(BaseModel):
    """Request model for creating an audio channel."""
+
    name: str = Field(..., min_length=1, max_length=100)
    device_ids: List[str] = Field(default_factory=list)


 class AudioChannelUpdate(BaseModel):
    """Request model for updating an audio channel."""
+
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    device_ids: Optional[List[str]] = None


 class AudioChannelResponse(BaseModel):
    """Response model for audio channel."""
+
    id: str
    name: str
    is_default: bool
@@ -246,22 +279,26 @@ class AudioChannelResponse(BaseModel):

 class ChannelVoiceAssignment(BaseModel):
    """Request model for assigning voices to a channel."""
+
    profile_ids: List[str]


 class ProfileChannelAssignment(BaseModel):
    """Request model for assigning channels to a profile."""
+
    channel_ids: List[str]


 class StoryCreate(BaseModel):
    """Request model for creating a story."""
+
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = Field(None, max_length=500)


 class StoryResponse(BaseModel):
    """Response model for story (list view)."""
+
    id: str
    name: str
    description: Optional[str]
@@ -275,6 +312,7 @@ class StoryResponse(BaseModel):

 class StoryItemDetail(BaseModel):
    """Detail model for story item with generation info."""
+
    id: str
    story_id: str
    generation_id: str
@@ -304,6 +342,7 @@ class StoryItemDetail(BaseModel):

 class StoryDetailResponse(BaseModel):
    """Response model for story with items."""
+
    id: str
    name: str
    description: Optional[str]
@@ -317,6 +356,7 @@ class StoryDetailResponse(BaseModel):

 class StoryItemCreate(BaseModel):
    """Request model for adding a generation to a story."""
+
    generation_id: str
    start_time_ms: Optional[int] = None  # If not provided, will be calculated automatically
    track: Optional[int] = 0  # Track number (0 = main track)
@@ -324,48 +364,52 @@ class StoryItemCreate(BaseModel):

 class StoryItemUpdateTime(BaseModel):
    """Request model for updating a story item's timecode."""
+
    generation_id: str
    start_time_ms: int = Field(..., ge=0)


 class StoryItemBatchUpdate(BaseModel):
    """Request model for batch updating story item timecodes."""
+
    updates: List[StoryItemUpdateTime]


 class StoryItemReorder(BaseModel):
    """Request model for reordering story items."""
+
    generation_ids: List[str] = Field(..., min_length=1)


 class StoryItemMove(BaseModel):
    """Request model for moving a story item (position and/or track)."""
+
    start_time_ms: int = Field(..., ge=0)
    track: int = 0


 class StoryItemTrim(BaseModel):
    """Request model for trimming a story item."""
+
    trim_start_ms: int = Field(..., ge=0)
    trim_end_ms: int = Field(..., ge=0)


 class StoryItemSplit(BaseModel):
    """Request model for splitting a story item."""
+
    split_time_ms: int = Field(..., ge=0)  # Time within the clip to split at (relative to clip start)


 class StoryItemVersionUpdate(BaseModel):
    """Request model for setting a story item's pinned version."""
+
    version_id: Optional[str] = None  # null = use generation default


-# ============================================
-# Effects & Versions
-# ============================================
-
 class EffectConfig(BaseModel):
    """A single effect in an effects chain."""
+
    type: str
    enabled: bool = True
    params: dict = Field(default_factory=dict)
@@ -373,11 +417,13 @@ class EffectConfig(BaseModel):

 class EffectsChain(BaseModel):
    """An ordered list of effects to apply."""
+
    effects: List[EffectConfig] = Field(default_factory=list)


 class EffectPresetCreate(BaseModel):
    """Request model for creating an effect preset."""
+
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = Field(None, max_length=500)
    effects_chain: List[EffectConfig]
@@ -385,6 +431,7 @@ class EffectPresetCreate(BaseModel):

 class EffectPresetUpdate(BaseModel):
    """Request model for updating an effect preset."""
+
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    description: Optional[str] = None
    effects_chain: Optional[List[EffectConfig]] = None
@@ -392,6 +439,7 @@ class EffectPresetUpdate(BaseModel):

 class EffectPresetResponse(BaseModel):
    """Response model for effect preset."""
+
    id: str
    name: str
    description: Optional[str] = None
@@ -405,6 +453,7 @@ class EffectPresetResponse(BaseModel):

 class GenerationVersionResponse(BaseModel):
    """Response model for a generation version."""
+
    id: str
    generation_id: str
    label: str
@@ -420,19 +469,24 @@ class GenerationVersionResponse(BaseModel):

 class ApplyEffectsRequest(BaseModel):
    """Request to apply effects to an existing generation."""
+
    effects_chain: List[EffectConfig]
-    source_version_id: Optional[str] = Field(None, description="Version to use as source audio (defaults to clean/original)")
+    source_version_id: Optional[str] = Field(
+        None, description="Version to use as source audio (defaults to clean/original)"
+    )
    label: Optional[str] = Field(None, max_length=100, description="Label for this version (auto-generated if omitted)")
    set_as_default: bool = Field(default=True, description="Set this version as the default")


 class ProfileEffectsUpdate(BaseModel):
    """Request to update the default effects chain on a profile."""
+
    effects_chain: Optional[List[EffectConfig]] = Field(None, description="Effects chain (null to remove)")


 class AvailableEffectParam(BaseModel):
    """Description of a single effect parameter."""
+
    default: float
    min: float
    max: float
@@ -442,6 +496,7 @@ class AvailableEffectParam(BaseModel):

 class AvailableEffect(BaseModel):
    """Description of an available effect type."""
+
    type: str
    label: str
    description: str
@@ -450,4 +505,5 @@ class AvailableEffect(BaseModel):

 class AvailableEffectsResponse(BaseModel):
    """Response listing all available effect types."""
+
    effects: List[AvailableEffect]
@@ -0,0 +1,83 @@
+[project]
+name = "voicebox-backend"
+version = "0.2.3"
+requires-python = ">=3.12"
+
+# ---------------------------------------------------------------------------
+# Ruff – linter + formatter
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["."]
+
+# Files/dirs to skip entirely.
+extend-exclude = [
+    "voicebox-server.spec",
+    "build_binary.py",
+]
+
+[tool.ruff.lint]
+select = [
+    "F",     # pyflakes
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade (modernize syntax for 3.12)
+    "B",     # flake8-bugbear
+    "A",     # flake8-builtins (shadowing built-in names)
+    "SIM",   # flake8-simplify
+    "T20",   # flake8-print (flag print() calls)
+    "RET",   # flake8-return
+    "PIE",   # misc lints
+    "PT",    # flake8-pytest-style
+    "RUF",   # ruff-specific rules
+    "ERA",   # commented-out code detection
+    "FIX",   # flag TODO/FIXME/HACK/XXX for review
+]
+
+ignore = [
+    # Allow print() in existing code -- remove items from this list as files
+    # are migrated to logging during the refactor.
+    "T201",   # print() found
+
+    # These conflict with the formatter or are too noisy during migration:
+    "E501",   # line too long (formatter handles this)
+    "RET504", # unnecessary assignment before return
+    "SIM108", # use ternary operator (sometimes less readable)
+    "B008",   # function call in default argument (FastAPI Depends() pattern)
+    "UP007",  # use X | Y for union (auto-fixed by UP, but noisy on big diffs)
+]
+
+# Per-file rule overrides.
+[tool.ruff.lint.per-file-ignores]
+# Tests can use assert, print, and magic values freely.
+"tests/**" = ["S101", "T201", "PLR2004", "ERA001"]
+# __init__.py re-exports are expected to have unused imports.
+"**/__init__.py" = ["F401"]
+# Entry points and scripts legitimately use print.
+"server.py" = ["T201"]
+"main.py" = ["T201"]
+# AMD GPU env vars must be set before torch import.
+"app.py" = ["E402"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["backend"]
+# Group "from backend.*" imports into the first-party section.
+force-single-line = false
+combine-as-imports = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+# ---------------------------------------------------------------------------
+# pytest
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
@@ -0,0 +1,32 @@
+"""Route registration for the voicebox API."""
+
+from fastapi import FastAPI
+
+
+def register_routers(app: FastAPI) -> None:
+    """Include all domain routers on the application."""
+    from .health import router as health_router
+    from .profiles import router as profiles_router
+    from .channels import router as channels_router
+    from .generations import router as generations_router
+    from .history import router as history_router
+    from .transcription import router as transcription_router
+    from .stories import router as stories_router
+    from .effects import router as effects_router
+    from .audio import router as audio_router
+    from .models import router as models_router
+    from .tasks import router as tasks_router
+    from .cuda import router as cuda_router
+
+    app.include_router(health_router)
+    app.include_router(profiles_router)
+    app.include_router(channels_router)
+    app.include_router(generations_router)
+    app.include_router(history_router)
+    app.include_router(transcription_router)
+    app.include_router(stories_router)
+    app.include_router(effects_router)
+    app.include_router(audio_router)
+    app.include_router(models_router)
+    app.include_router(tasks_router)
+    app.include_router(cuda_router)
@@ -0,0 +1,71 @@
+"""Audio file serving endpoints."""
+
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import FileResponse
+from sqlalchemy.orm import Session
+
+from .. import models
+from ..services import history
+from ..database import get_db
+
+router = APIRouter()
+
+
+@router.get("/audio/version/{version_id}")
+async def get_version_audio(version_id: str, db: Session = Depends(get_db)):
+    """Serve audio for a specific version."""
+    from ..services import versions as versions_mod
+
+    version = versions_mod.get_version(version_id, db)
+    if not version:
+        raise HTTPException(status_code=404, detail="Version not found")
+
+    audio_path = Path(version.audio_path)
+    if not audio_path.exists():
+        raise HTTPException(status_code=404, detail="Audio file not found")
+
+    return FileResponse(
+        audio_path,
+        media_type="audio/wav",
+        filename=f"generation_{version.generation_id}_{version.label}.wav",
+    )
+
+
+@router.get("/audio/{generation_id}")
+async def get_audio(generation_id: str, db: Session = Depends(get_db)):
+    """Serve generated audio file (serves the default version)."""
+    generation = await history.get_generation(generation_id, db)
+    if not generation:
+        raise HTTPException(status_code=404, detail="Generation not found")
+
+    audio_path = Path(generation.audio_path)
+    if not audio_path.exists():
+        raise HTTPException(status_code=404, detail="Audio file not found")
+
+    return FileResponse(
+        audio_path,
+        media_type="audio/wav",
+        filename=f"generation_{generation_id}.wav",
+    )
+
+
+@router.get("/samples/{sample_id}")
+async def get_sample_audio(sample_id: str, db: Session = Depends(get_db)):
+    """Serve profile sample audio file."""
+    from ..database import ProfileSample as DBProfileSample
+
+    sample = db.query(DBProfileSample).filter_by(id=sample_id).first()
+    if not sample:
+        raise HTTPException(status_code=404, detail="Sample not found")
+
+    audio_path = Path(sample.audio_path)
+    if not audio_path.exists():
+        raise HTTPException(status_code=404, detail="Audio file not found")
+
+    return FileResponse(
+        audio_path,
+        media_type="audio/wav",
+        filename=f"sample_{sample_id}.wav",
+    )
@@ -0,0 +1,98 @@
+"""Audio channel endpoints."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+
+from .. import models
+from ..services import channels
+from ..database import get_db
+
+router = APIRouter()
+
+
+@router.get("/channels", response_model=list[models.AudioChannelResponse])
+async def list_channels(db: Session = Depends(get_db)):
+    """List all audio channels."""
+    return await channels.list_channels(db)
+
+
+@router.post("/channels", response_model=models.AudioChannelResponse)
+async def create_channel(
+    data: models.AudioChannelCreate,
+    db: Session = Depends(get_db),
+):
+    """Create a new audio channel."""
+    try:
+        return await channels.create_channel(data, db)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/channels/{channel_id}", response_model=models.AudioChannelResponse)
+async def get_channel(
+    channel_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get an audio channel by ID."""
+    channel = await channels.get_channel(channel_id, db)
+    if not channel:
+        raise HTTPException(status_code=404, detail="Channel not found")
+    return channel
+
+
+@router.put("/channels/{channel_id}", response_model=models.AudioChannelResponse)
+async def update_channel(
+    channel_id: str,
+    data: models.AudioChannelUpdate,
+    db: Session = Depends(get_db),
+):
+    """Update an audio channel."""
+    try:
+        channel = await channels.update_channel(channel_id, data, db)
+        if not channel:
+            raise HTTPException(status_code=404, detail="Channel not found")
+        return channel
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/channels/{channel_id}")
+async def delete_channel(
+    channel_id: str,
+    db: Session = Depends(get_db),
+):
+    """Delete an audio channel."""
+    try:
+        success = await channels.delete_channel(channel_id, db)
+        if not success:
+            raise HTTPException(status_code=404, detail="Channel not found")
+        return {"message": "Channel deleted successfully"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/channels/{channel_id}/voices")
+async def get_channel_voices(
+    channel_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get list of profile IDs assigned to a channel."""
+    try:
+        profile_ids = await channels.get_channel_voices(channel_id, db)
+        return {"profile_ids": profile_ids}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/channels/{channel_id}/voices")
+async def set_channel_voices(
+    channel_id: str,
+    data: models.ChannelVoiceAssignment,
+    db: Session = Depends(get_db),
+):
+    """Set which voices are assigned to a channel."""
+    try:
+        await channels.set_channel_voices(channel_id, data, db)
+        return {"message": "Channel voices updated successfully"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
@@ -0,0 +1,82 @@
+"""CUDA backend management endpoints."""
+
+import logging
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from ..services.task_queue import create_background_task
+from ..utils.progress import get_progress_manager
+
+router = APIRouter()
+
+logger = logging.getLogger(__name__)
+
+
+@router.get("/backend/cuda-status")
+async def get_cuda_status():
+    """Get CUDA backend download/availability status."""
+    from ..services import cuda
+
+    return cuda.get_cuda_status()
+
+
+@router.post("/backend/download-cuda")
+async def download_cuda_backend():
+    """Download the CUDA backend binary."""
+    from ..services import cuda
+
+    if cuda.get_cuda_binary_path() is not None:
+        raise HTTPException(status_code=409, detail="CUDA backend already downloaded")
+
+    progress_manager = get_progress_manager()
+    existing = progress_manager.get_progress(cuda.PROGRESS_KEY)
+    if existing and existing.get("status") == "downloading":
+        raise HTTPException(status_code=409, detail="CUDA backend download already in progress")
+
+    async def _download():
+        try:
+            await cuda.download_cuda_binary()
+        except Exception as e:
+            logger.error("CUDA download failed: %s", e)
+
+    create_background_task(_download())
+    return {"message": "CUDA backend download started", "progress_key": "cuda-backend"}
+
+
+@router.delete("/backend/cuda")
+async def delete_cuda_backend():
+    """Delete the downloaded CUDA backend binary."""
+    from ..services import cuda
+
+    if cuda.is_cuda_active():
+        raise HTTPException(
+            status_code=409,
+            detail="Cannot delete CUDA backend while it is active. Switch to CPU first.",
+        )
+
+    deleted = await cuda.delete_cuda_binary()
+    if not deleted:
+        raise HTTPException(status_code=404, detail="No CUDA backend found to delete")
+
+    return {"message": "CUDA backend deleted"}
+
+
+@router.get("/backend/cuda-progress")
+async def get_cuda_download_progress():
+    """Get CUDA backend download progress via Server-Sent Events."""
+    progress_manager = get_progress_manager()
+
+    async def event_generator():
+        async for event in progress_manager.subscribe("cuda-backend"):
+            yield event
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
@@ -0,0 +1,261 @@
+"""Effects presets and generation version endpoints."""
+
+import asyncio
+import io
+import uuid
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from sqlalchemy.orm import Session
+
+from .. import config, models
+from ..services import history
+from ..database import Generation as DBGeneration, get_db
+
+router = APIRouter()
+
+
+@router.post("/effects/preview/{generation_id}")
+async def preview_effects(
+    generation_id: str,
+    data: models.ApplyEffectsRequest,
+    db: Session = Depends(get_db),
+):
+    """Apply effects to a generation's clean audio and stream back without saving."""
+    gen = db.query(DBGeneration).filter_by(id=generation_id).first()
+    if not gen:
+        raise HTTPException(status_code=404, detail="Generation not found")
+    if (gen.status or "completed") != "completed":
+        raise HTTPException(status_code=400, detail="Generation is not completed")
+
+    from ..services import versions as versions_mod
+    from ..utils.effects import apply_effects, validate_effects_chain
+    from ..utils.audio import load_audio
+
+    chain_dicts = [e.model_dump() for e in data.effects_chain]
+    error = validate_effects_chain(chain_dicts)
+    if error:
+        raise HTTPException(status_code=400, detail=error)
+
+    all_versions = versions_mod.list_versions(generation_id, db)
+    clean_version = next((v for v in all_versions if v.effects_chain is None), None)
+    source_path = clean_version.audio_path if clean_version else gen.audio_path
+    if not source_path or not Path(source_path).exists():
+        raise HTTPException(status_code=404, detail="Source audio file not found")
+
+    audio, sample_rate = await asyncio.to_thread(load_audio, source_path)
+    processed = await asyncio.to_thread(apply_effects, audio, sample_rate, chain_dicts)
+
+    import soundfile as sf
+
+    buf = io.BytesIO()
+    await asyncio.to_thread(lambda: sf.write(buf, processed, sample_rate, format="WAV"))
+    buf.seek(0)
+
+    return StreamingResponse(
+        buf,
+        media_type="audio/wav",
+        headers={
+            "Content-Disposition": f'inline; filename="preview_{generation_id}.wav"',
+            "Cache-Control": "no-cache, no-store",
+        },
+    )
+
+
+@router.get("/effects/available", response_model=models.AvailableEffectsResponse)
+async def get_available_effects():
+    """List all available effect types with parameter definitions."""
+    from ..utils.effects import get_available_effects as _get_effects
+
+    return models.AvailableEffectsResponse(effects=[models.AvailableEffect(**e) for e in _get_effects()])
+
+
+@router.get("/effects/presets", response_model=list[models.EffectPresetResponse])
+async def list_effect_presets(db: Session = Depends(get_db)):
+    """List all effect presets (built-in + user-created)."""
+    from ..services import effects as effects_mod
+
+    return effects_mod.list_presets(db)
+
+
+@router.get("/effects/presets/{preset_id}", response_model=models.EffectPresetResponse)
+async def get_effect_preset(preset_id: str, db: Session = Depends(get_db)):
+    """Get a specific effect preset."""
+    from ..services import effects as effects_mod
+
+    preset = effects_mod.get_preset(preset_id, db)
+    if not preset:
+        raise HTTPException(status_code=404, detail="Preset not found")
+    return preset
+
+
+@router.post("/effects/presets", response_model=models.EffectPresetResponse)
+async def create_effect_preset(
+    data: models.EffectPresetCreate,
+    db: Session = Depends(get_db),
+):
+    """Create a new effect preset."""
+    from ..services import effects as effects_mod
+
+    try:
+        return effects_mod.create_preset(data, db)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/effects/presets/{preset_id}", response_model=models.EffectPresetResponse)
+async def update_effect_preset(
+    preset_id: str,
+    data: models.EffectPresetUpdate,
+    db: Session = Depends(get_db),
+):
+    """Update an effect preset."""
+    from ..services import effects as effects_mod
+
+    try:
+        result = effects_mod.update_preset(preset_id, data, db)
+        if not result:
+            raise HTTPException(status_code=404, detail="Preset not found")
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/effects/presets/{preset_id}")
+async def delete_effect_preset(preset_id: str, db: Session = Depends(get_db)):
+    """Delete a user effect preset."""
+    from ..services import effects as effects_mod
+
+    try:
+        if not effects_mod.delete_preset(preset_id, db):
+            raise HTTPException(status_code=404, detail="Preset not found")
+        return {"status": "deleted"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get(
+    "/generations/{generation_id}/versions",
+    response_model=list[models.GenerationVersionResponse],
+)
+async def list_generation_versions(
+    generation_id: str,
+    db: Session = Depends(get_db),
+):
+    """List all versions for a generation."""
+    gen = await history.get_generation(generation_id, db)
+    if not gen:
+        raise HTTPException(status_code=404, detail="Generation not found")
+
+    from ..services import versions as versions_mod
+
+    return versions_mod.list_versions(generation_id, db)
+
+
+@router.post(
+    "/generations/{generation_id}/versions/apply-effects",
+    response_model=models.GenerationVersionResponse,
+)
+async def apply_effects_to_generation(
+    generation_id: str,
+    data: models.ApplyEffectsRequest,
+    db: Session = Depends(get_db),
+):
+    """Apply an effects chain to an existing generation, creating a new version."""
+    gen = db.query(DBGeneration).filter_by(id=generation_id).first()
+    if not gen:
+        raise HTTPException(status_code=404, detail="Generation not found")
+    if (gen.status or "completed") != "completed":
+        raise HTTPException(status_code=400, detail="Generation is not completed")
+
+    from ..services import versions as versions_mod
+    from ..utils.effects import apply_effects, validate_effects_chain
+    from ..utils.audio import load_audio, save_audio
+
+    chain_dicts = [e.model_dump() for e in data.effects_chain]
+    error = validate_effects_chain(chain_dicts)
+    if error:
+        raise HTTPException(status_code=400, detail=error)
+
+    all_versions = versions_mod.list_versions(generation_id, db)
+    source_version_id = data.source_version_id
+    if source_version_id:
+        source_version = next((v for v in all_versions if v.id == source_version_id), None)
+        if not source_version:
+            raise HTTPException(status_code=404, detail="Source version not found")
+        source_path = source_version.audio_path
+    else:
+        clean_version = next((v for v in all_versions if v.effects_chain is None), None)
+        if not clean_version:
+            source_path = gen.audio_path
+        else:
+            source_path = clean_version.audio_path
+            source_version_id = clean_version.id
+
+    if not source_path or not Path(source_path).exists():
+        raise HTTPException(status_code=404, detail="Source audio file not found")
+
+    audio, sample_rate = await asyncio.to_thread(load_audio, source_path)
+    processed_audio = await asyncio.to_thread(apply_effects, audio, sample_rate, chain_dicts)
+
+    version_id = str(uuid.uuid4())
+    processed_path = config.get_generations_dir() / f"{generation_id}_{version_id[:8]}.wav"
+    await asyncio.to_thread(save_audio, processed_audio, str(processed_path), sample_rate)
+
+    label = data.label or f"version-{len(all_versions) + 1}"
+
+    version = versions_mod.create_version(
+        generation_id=generation_id,
+        label=label,
+        audio_path=str(processed_path),
+        db=db,
+        effects_chain=chain_dicts,
+        is_default=data.set_as_default,
+        source_version_id=source_version_id,
+    )
+
+    return version
+
+
+@router.put(
+    "/generations/{generation_id}/versions/{version_id}/set-default",
+    response_model=models.GenerationVersionResponse,
+)
+async def set_default_version(
+    generation_id: str,
+    version_id: str,
+    db: Session = Depends(get_db),
+):
+    """Set a specific version as the default for a generation."""
+    from ..services import versions as versions_mod
+
+    version = versions_mod.get_version(version_id, db)
+    if not version or version.generation_id != generation_id:
+        raise HTTPException(status_code=404, detail="Version not found")
+
+    result = versions_mod.set_default_version(version_id, db)
+    if not result:
+        raise HTTPException(status_code=404, detail="Version not found")
+    return result
+
+
+@router.delete("/generations/{generation_id}/versions/{version_id}")
+async def delete_generation_version(
+    generation_id: str,
+    version_id: str,
+    db: Session = Depends(get_db),
+):
+    """Delete a version. Cannot delete the last remaining version."""
+    from ..services import versions as versions_mod
+
+    version = versions_mod.get_version(version_id, db)
+    if not version or version.generation_id != generation_id:
+        raise HTTPException(status_code=404, detail="Version not found")
+
+    if not versions_mod.delete_version(version_id, db):
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot delete the last remaining version",
+        )
+    return {"status": "deleted"}
@@ -0,0 +1,276 @@
+"""TTS generation endpoints."""
+
+import asyncio
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from sqlalchemy.orm import Session
+
+from .. import models
+from ..services import history, profiles, tts
+from ..database import Generation as DBGeneration, VoiceProfile as DBVoiceProfile, get_db
+from ..services.generation import run_generation
+from ..services.task_queue import enqueue_generation
+from ..utils.tasks import get_task_manager
+
+router = APIRouter()
+
+
+@router.post("/generate", response_model=models.GenerationResponse)
+async def generate_speech(
+    data: models.GenerationRequest,
+    db: Session = Depends(get_db),
+):
+    """Generate speech from text using a voice profile."""
+    task_manager = get_task_manager()
+    generation_id = str(uuid.uuid4())
+
+    profile = await profiles.get_profile(data.profile_id, db)
+    if not profile:
+        raise HTTPException(status_code=404, detail="Profile not found")
+
+    from ..backends import engine_has_model_sizes
+
+    engine = data.engine or "qwen"
+    model_size = (data.model_size or "1.7B") if engine_has_model_sizes(engine) else None
+
+    generation = await history.create_generation(
+        profile_id=data.profile_id,
+        text=data.text,
+        language=data.language,
+        audio_path="",
+        duration=0,
+        seed=data.seed,
+        db=db,
+        instruct=data.instruct,
+        generation_id=generation_id,
+        status="generating",
+        engine=engine,
+        model_size=model_size if engine_has_model_sizes(engine) else None,
+    )
+
+    task_manager.start_generation(
+        task_id=generation_id,
+        profile_id=data.profile_id,
+        text=data.text,
+    )
+
+    effects_chain_config = None
+    if data.effects_chain is not None:
+        effects_chain_config = [e.model_dump() for e in data.effects_chain]
+    else:
+        import json as _json
+
+        profile_obj = db.query(DBVoiceProfile).filter_by(id=data.profile_id).first()
+        if profile_obj and profile_obj.effects_chain:
+            try:
+                effects_chain_config = _json.loads(profile_obj.effects_chain)
+            except Exception:
+                pass
+
+    enqueue_generation(
+        run_generation(
+            generation_id=generation_id,
+            profile_id=data.profile_id,
+            text=data.text,
+            language=data.language,
+            engine=engine,
+            model_size=model_size,
+            seed=data.seed,
+            normalize=data.normalize,
+            effects_chain=effects_chain_config,
+            instruct=data.instruct,
+            mode="generate",
+            max_chunk_chars=data.max_chunk_chars,
+            crossfade_ms=data.crossfade_ms,
+        )
+    )
+
+    return generation
+
+
+@router.post("/generate/{generation_id}/retry", response_model=models.GenerationResponse)
+async def retry_generation(generation_id: str, db: Session = Depends(get_db)):
+    """Retry a failed generation using the same parameters."""
+    gen = db.query(DBGeneration).filter_by(id=generation_id).first()
+    if not gen:
+        raise HTTPException(status_code=404, detail="Generation not found")
+
+    if (gen.status or "completed") != "failed":
+        raise HTTPException(status_code=400, detail="Only failed generations can be retried")
+
+    gen.status = "generating"
+    gen.error = None
+    gen.audio_path = ""
+    gen.duration = 0
+    db.commit()
+    db.refresh(gen)
+
+    task_manager = get_task_manager()
+    task_manager.start_generation(
+        task_id=generation_id,
+        profile_id=gen.profile_id,
+        text=gen.text,
+    )
+
+    enqueue_generation(
+        run_generation(
+            generation_id=generation_id,
+            profile_id=gen.profile_id,
+            text=gen.text,
+            language=gen.language,
+            engine=gen.engine or "qwen",
+            model_size=gen.model_size or "1.7B",
+            seed=gen.seed,
+            instruct=gen.instruct,
+            mode="retry",
+        )
+    )
+
+    return models.GenerationResponse.model_validate(gen)
+
+
+@router.post(
+    "/generate/{generation_id}/regenerate",
+    response_model=models.GenerationResponse,
+)
+async def regenerate_generation(generation_id: str, db: Session = Depends(get_db)):
+    """Re-run TTS with the same parameters and save the result as a new version."""
+    gen = db.query(DBGeneration).filter_by(id=generation_id).first()
+    if not gen:
+        raise HTTPException(status_code=404, detail="Generation not found")
+    if (gen.status or "completed") != "completed":
+        raise HTTPException(status_code=400, detail="Generation must be completed to regenerate")
+
+    gen.status = "generating"
+    gen.error = None
+    db.commit()
+    db.refresh(gen)
+
+    task_manager = get_task_manager()
+    task_manager.start_generation(
+        task_id=generation_id,
+        profile_id=gen.profile_id,
+        text=gen.text,
+    )
+
+    version_id = str(uuid.uuid4())
+
+    enqueue_generation(
+        run_generation(
+            generation_id=generation_id,
+            profile_id=gen.profile_id,
+            text=gen.text,
+            language=gen.language,
+            engine=gen.engine or "qwen",
+            model_size=gen.model_size or "1.7B",
+            seed=gen.seed,
+            instruct=gen.instruct,
+            mode="regenerate",
+            version_id=version_id,
+        )
+    )
+
+    return models.GenerationResponse.model_validate(gen)
+
+
+@router.get("/generate/{generation_id}/status")
+async def get_generation_status(generation_id: str, db: Session = Depends(get_db)):
+    """SSE endpoint that streams generation status updates."""
+    import json
+
+    async def event_stream():
+        while True:
+            db.expire_all()
+            gen = db.query(DBGeneration).filter_by(id=generation_id).first()
+            if not gen:
+                yield f"data: {json.dumps({'status': 'not_found', 'id': generation_id})}\n\n"
+                return
+
+            payload = {
+                "id": gen.id,
+                "status": gen.status or "completed",
+                "duration": gen.duration,
+                "error": gen.error,
+            }
+            yield f"data: {json.dumps(payload)}\n\n"
+
+            if (gen.status or "completed") in ("completed", "failed"):
+                return
+
+            await asyncio.sleep(1)
+
+    return StreamingResponse(
+        event_stream(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.post("/generate/stream")
+async def stream_speech(
+    data: models.GenerationRequest,
+    db: Session = Depends(get_db),
+):
+    """Generate speech and stream the WAV audio directly without saving to disk."""
+    from ..backends import get_tts_backend_for_engine, ensure_model_cached_or_raise, load_engine_model, engine_needs_trim
+
+    profile = await profiles.get_profile(data.profile_id, db)
+    if not profile:
+        raise HTTPException(status_code=404, detail="Profile not found")
+
+    engine = data.engine or "qwen"
+    tts_model = get_tts_backend_for_engine(engine)
+    model_size = data.model_size or "1.7B"
+
+    await ensure_model_cached_or_raise(engine, model_size)
+    await load_engine_model(engine, model_size)
+
+    voice_prompt = await profiles.create_voice_prompt_for_profile(
+        data.profile_id,
+        db,
+        engine=engine,
+    )
+
+    from ..utils.chunked_tts import generate_chunked
+
+    trim_fn = None
+    if engine_needs_trim(engine):
+        from ..utils.audio import trim_tts_output
+
+        trim_fn = trim_tts_output
+
+    audio, sample_rate = await generate_chunked(
+        tts_model,
+        data.text,
+        voice_prompt,
+        language=data.language,
+        seed=data.seed,
+        instruct=data.instruct,
+        max_chunk_chars=data.max_chunk_chars,
+        crossfade_ms=data.crossfade_ms,
+        trim_fn=trim_fn,
+    )
+
+    if data.normalize:
+        from ..utils.audio import normalize_audio
+
+        audio = normalize_audio(audio)
+
+    wav_bytes = tts.audio_to_wav_bytes(audio, sample_rate)
+
+    async def _wav_stream():
+        chunk_size = 64 * 1024
+        for i in range(0, len(wav_bytes), chunk_size):
+            yield wav_bytes[i : i + chunk_size]
+
+    return StreamingResponse(
+        _wav_stream(),
+        media_type="audio/wav",
+        headers={"Content-Disposition": 'attachment; filename="speech.wav"'},
+    )
@@ -0,0 +1,225 @@
+"""Health and infrastructure endpoints."""
+
+import asyncio
+import os
+import signal
+
+import torch
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from .. import config, models
+from ..services import tts
+from ..database import get_db
+from ..utils.platform_detect import get_backend_type
+
+router = APIRouter()
+
+
+@router.get("/")
+async def root():
+    """Root endpoint."""
+    from .. import __version__
+
+    return {"message": "voicebox API", "version": __version__}
+
+
+@router.post("/shutdown")
+async def shutdown():
+    """Gracefully shutdown the server."""
+
+    async def shutdown_async():
+        await asyncio.sleep(0.1)
+        os.kill(os.getpid(), signal.SIGTERM)
+
+    asyncio.create_task(shutdown_async())
+    return {"message": "Shutting down..."}
+
+
+@router.post("/watchdog/disable")
+async def watchdog_disable():
+    """Disable the parent process watchdog so the server keeps running."""
+    from backend.server import disable_watchdog
+
+    disable_watchdog()
+    return {"message": "Watchdog disabled"}
+
+
+@router.get("/health", response_model=models.HealthResponse)
+async def health():
+    """Health check endpoint."""
+    from huggingface_hub import constants as hf_constants
+    from pathlib import Path
+
+    tts_model = tts.get_tts_model()
+    backend_type = get_backend_type()
+
+    has_cuda = torch.cuda.is_available()
+    has_mps = hasattr(torch.backends, "mps") and torch.backends.mps.is_available()
+
+    has_xpu = False
+    xpu_name = None
+    try:
+        import intel_extension_for_pytorch as ipex  # noqa: F401 -- side-effect import enables XPU
+
+        if hasattr(torch, "xpu") and torch.xpu.is_available():
+            has_xpu = True
+            try:
+                xpu_name = torch.xpu.get_device_name(0)
+            except Exception:
+                xpu_name = "Intel GPU"
+    except ImportError:
+        pass
+
+    has_directml = False
+    directml_name = None
+    try:
+        import torch_directml
+
+        if torch_directml.device_count() > 0:
+            has_directml = True
+            try:
+                directml_name = torch_directml.device_name(0)
+            except Exception:
+                directml_name = "DirectML GPU"
+    except ImportError:
+        pass
+
+    gpu_available = has_cuda or has_mps or has_xpu or has_directml or backend_type == "mlx"
+
+    gpu_type = None
+    if has_cuda:
+        gpu_type = f"CUDA ({torch.cuda.get_device_name(0)})"
+    elif has_mps:
+        gpu_type = "MPS (Apple Silicon)"
+    elif backend_type == "mlx":
+        gpu_type = "Metal (Apple Silicon via MLX)"
+    elif has_xpu:
+        gpu_type = f"XPU ({xpu_name})"
+    elif has_directml:
+        gpu_type = f"DirectML ({directml_name})"
+
+    vram_used = None
+    if has_cuda:
+        vram_used = torch.cuda.memory_allocated() / 1024 / 1024
+
+    model_loaded = False
+    model_size = None
+    try:
+        if tts_model.is_loaded():
+            model_loaded = True
+            model_size = getattr(tts_model, "_current_model_size", None)
+            if not model_size:
+                model_size = getattr(tts_model, "model_size", None)
+    except Exception:
+        model_loaded = False
+        model_size = None
+
+    model_downloaded = None
+    try:
+        from ..backends import get_model_config
+
+        default_config = get_model_config("qwen-tts-1.7B")
+        default_model_id = default_config.hf_repo_id if default_config else "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
+
+        try:
+            from huggingface_hub import scan_cache_dir
+
+            cache_info = scan_cache_dir()
+            for repo in cache_info.repos:
+                if repo.repo_id == default_model_id:
+                    model_downloaded = True
+                    break
+        except (ImportError, Exception):
+            cache_dir = hf_constants.HF_HUB_CACHE
+            repo_cache = Path(cache_dir) / ("models--" + default_model_id.replace("/", "--"))
+            if repo_cache.exists():
+                has_model_files = (
+                    any(repo_cache.rglob("*.bin"))
+                    or any(repo_cache.rglob("*.safetensors"))
+                    or any(repo_cache.rglob("*.pt"))
+                    or any(repo_cache.rglob("*.pth"))
+                    or any(repo_cache.rglob("*.npz"))
+                )
+                model_downloaded = has_model_files
+    except Exception:
+        pass
+
+    return models.HealthResponse(
+        status="healthy",
+        model_loaded=model_loaded,
+        model_downloaded=model_downloaded,
+        model_size=model_size,
+        gpu_available=gpu_available,
+        gpu_type=gpu_type,
+        vram_used_mb=vram_used,
+        backend_type=backend_type,
+        backend_variant=os.environ.get("VOICEBOX_BACKEND_VARIANT", "cuda" if torch.cuda.is_available() else "cpu"),
+    )
+
+
+@router.get("/health/filesystem", response_model=models.FilesystemHealthResponse)
+async def filesystem_health():
+    """Check filesystem health: directory existence, write permissions, and disk space."""
+    import shutil
+
+    dirs_to_check = {
+        "generations": config.get_generations_dir(),
+        "profiles": config.get_profiles_dir(),
+        "data": config.get_data_dir(),
+    }
+
+    checks: list[models.DirectoryCheck] = []
+    all_ok = True
+
+    for _label, dir_path in dirs_to_check.items():
+        exists = dir_path.exists()
+        writable = False
+        error = None
+        if exists:
+            probe = dir_path / ".voicebox_probe"
+            try:
+                probe.write_text("ok")
+                probe.unlink()
+                writable = True
+            except PermissionError:
+                error = "Permission denied"
+            except OSError as e:
+                error = str(e)
+            finally:
+                try:
+                    probe.unlink(missing_ok=True)
+                except Exception:
+                    pass
+        else:
+            error = "Directory does not exist"
+
+        if not exists or not writable:
+            all_ok = False
+
+        checks.append(
+            models.DirectoryCheck(
+                path=str(dir_path),
+                exists=exists,
+                writable=writable,
+                error=error,
+            )
+        )
+
+    disk_free_mb = None
+    disk_total_mb = None
+    try:
+        usage = shutil.disk_usage(str(config.get_data_dir()))
+        disk_free_mb = round(usage.free / (1024 * 1024), 1)
+        disk_total_mb = round(usage.total / (1024 * 1024), 1)
+        if disk_free_mb < 500:
+            all_ok = False
+    except OSError:
+        all_ok = False
+
+    return models.FilesystemHealthResponse(
+        healthy=all_ok,
+        disk_free_mb=disk_free_mb,
+        disk_total_mb=disk_total_mb,
+        directories=checks,
+    )
@@ -0,0 +1,178 @@
+"""Generation history endpoints."""
+
+import io
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
+from fastapi.responses import FileResponse, StreamingResponse
+from sqlalchemy.orm import Session
+
+from .. import models
+from ..services import export_import, history
+from ..app import safe_content_disposition
+from ..database import Generation as DBGeneration, VoiceProfile as DBVoiceProfile, get_db
+
+router = APIRouter()
+
+
+@router.get("/history", response_model=models.HistoryListResponse)
+async def list_history(
+    profile_id: str | None = None,
+    search: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    db: Session = Depends(get_db),
+):
+    """List generation history with optional filters."""
+    query = models.HistoryQuery(
+        profile_id=profile_id,
+        search=search,
+        limit=limit,
+        offset=offset,
+    )
+    return await history.list_generations(query, db)
+
+
+@router.get("/history/stats")
+async def get_stats(db: Session = Depends(get_db)):
+    """Get generation statistics."""
+    return await history.get_generation_stats(db)
+
+
+@router.post("/history/import")
+async def import_generation(
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+):
+    """Import a generation from a ZIP archive."""
+    MAX_FILE_SIZE = 50 * 1024 * 1024
+
+    content = await file.read()
+
+    if len(content) > MAX_FILE_SIZE:
+        raise HTTPException(
+            status_code=400, detail=f"File too large. Maximum size is {MAX_FILE_SIZE / (1024 * 1024)}MB"
+        )
+
+    try:
+        result = await export_import.import_generation_from_zip(content, db)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/history/{generation_id}", response_model=models.HistoryResponse)
+async def get_generation(
+    generation_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get a generation by ID."""
+    result = (
+        db.query(DBGeneration, DBVoiceProfile.name.label("profile_name"))
+        .join(DBVoiceProfile, DBGeneration.profile_id == DBVoiceProfile.id)
+        .filter(DBGeneration.id == generation_id)
+        .first()
+    )
+
+    if not result:
+        raise HTTPException(status_code=404, detail="Generation not found")
+
+    gen, profile_name = result
+    return models.HistoryResponse(
+        id=gen.id,
+        profile_id=gen.profile_id,
+        profile_name=profile_name,
+        text=gen.text,
+        language=gen.language,
+        audio_path=gen.audio_path,
+        duration=gen.duration,
+        seed=gen.seed,
+        instruct=gen.instruct,
+        created_at=gen.created_at,
+    )
+
+
+@router.post("/history/{generation_id}/favorite")
+async def toggle_favorite(
+    generation_id: str,
+    db: Session = Depends(get_db),
+):
+    """Toggle the favorite status of a generation."""
+    gen = db.query(DBGeneration).filter_by(id=generation_id).first()
+    if not gen:
+        raise HTTPException(status_code=404, detail="Generation not found")
+    gen.is_favorited = not gen.is_favorited
+    db.commit()
+    return {"is_favorited": gen.is_favorited}
+
+
+@router.delete("/history/{generation_id}")
+async def delete_generation(
+    generation_id: str,
+    db: Session = Depends(get_db),
+):
+    """Delete a generation."""
+    success = await history.delete_generation(generation_id, db)
+    if not success:
+        raise HTTPException(status_code=404, detail="Generation not found")
+    return {"message": "Generation deleted successfully"}
+
+
+@router.get("/history/{generation_id}/export")
+async def export_generation(
+    generation_id: str,
+    db: Session = Depends(get_db),
+):
+    """Export a generation as a ZIP archive."""
+    generation = db.query(DBGeneration).filter_by(id=generation_id).first()
+    if not generation:
+        raise HTTPException(status_code=404, detail="Generation not found")
+
+    try:
+        zip_bytes = export_import.export_generation_to_zip(generation_id, db)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+    safe_text = "".join(c for c in generation.text[:30] if c.isalnum() or c in (" ", "-", "_")).strip()
+    if not safe_text:
+        safe_text = "generation"
+    filename = f"generation-{safe_text}.voicebox.zip"
+
+    return StreamingResponse(
+        io.BytesIO(zip_bytes),
+        media_type="application/zip",
+        headers={"Content-Disposition": safe_content_disposition("attachment", filename)},
+    )
+
+
+@router.get("/history/{generation_id}/export-audio")
+async def export_generation_audio(
+    generation_id: str,
+    db: Session = Depends(get_db),
+):
+    """Export only the audio file from a generation."""
+    generation = db.query(DBGeneration).filter_by(id=generation_id).first()
+    if not generation:
+        raise HTTPException(status_code=404, detail="Generation not found")
+
+    if not generation.audio_path:
+        raise HTTPException(status_code=404, detail="Generation has no audio file")
+
+    audio_path = Path(generation.audio_path)
+    if not audio_path.is_file():
+        raise HTTPException(status_code=404, detail="Audio file not found")
+
+    safe_text = "".join(c for c in generation.text[:30] if c.isalnum() or c in (" ", "-", "_")).strip()
+    if not safe_text:
+        safe_text = "generation"
+    filename = f"{safe_text}.wav"
+
+    return FileResponse(
+        audio_path,
+        media_type="audio/wav",
+        headers={"Content-Disposition": safe_content_disposition("attachment", filename)},
+    )
@@ -0,0 +1,474 @@
+"""Model management endpoints."""
+
+import asyncio
+import shutil
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from sqlalchemy.orm import Session
+
+from .. import models
+from ..utils.platform_detect import get_backend_type
+from ..services.task_queue import create_background_task
+from ..utils.progress import get_progress_manager
+from ..utils.tasks import get_task_manager
+
+router = APIRouter()
+
+
+def _get_dir_size(path: Path) -> int:
+    """Get total size of a directory in bytes."""
+    total = 0
+    for f in path.rglob("*"):
+        if f.is_file():
+            total += f.stat().st_size
+    return total
+
+
+def _copy_with_progress(src: Path, dst: Path, progress_manager, copied_so_far: int, total_bytes: int) -> int:
+    """Copy a directory tree with byte-level progress tracking."""
+    dst.mkdir(parents=True, exist_ok=True)
+    for item in src.iterdir():
+        dest_item = dst / item.name
+        if item.is_dir():
+            copied_so_far = _copy_with_progress(item, dest_item, progress_manager, copied_so_far, total_bytes)
+        else:
+            size = item.stat().st_size
+            shutil.copy2(str(item), str(dest_item))
+            copied_so_far += size
+            progress_manager.update_progress(
+                "migration",
+                copied_so_far,
+                total_bytes,
+                filename=item.name,
+                status="downloading",
+            )
+    return copied_so_far
+
+
+@router.post("/models/load")
+async def load_model(model_size: str = "1.7B"):
+    """Manually load TTS model."""
+    from ..services import tts
+
+    try:
+        tts_model = tts.get_tts_model()
+        await tts_model.load_model_async(model_size)
+        return {"message": f"Model {model_size} loaded successfully"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/models/unload")
+async def unload_model():
+    """Unload the default Qwen TTS model to free memory."""
+    from ..services import tts
+
+    try:
+        tts.unload_tts_model()
+        return {"message": "Model unloaded successfully"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/models/{model_name}/unload")
+async def unload_model_by_name(model_name: str):
+    """Unload a specific model from memory without deleting it from disk."""
+    from ..backends import get_model_config, unload_model_by_config
+
+    config = get_model_config(model_name)
+    if not config:
+        raise HTTPException(status_code=400, detail=f"Unknown model: {model_name}")
+
+    try:
+        was_loaded = unload_model_by_config(config)
+        if not was_loaded:
+            return {"message": f"Model {model_name} is not loaded"}
+        return {"message": f"Model {model_name} unloaded successfully"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.get("/models/progress/{model_name}")
+async def get_model_progress(model_name: str):
+    """Get model download progress via Server-Sent Events."""
+    progress_manager = get_progress_manager()
+
+    async def event_generator():
+        async for event in progress_manager.subscribe(model_name):
+            yield event
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.get("/models/cache-dir")
+async def get_models_cache_dir():
+    """Get the path to the HuggingFace model cache directory."""
+    from huggingface_hub import constants as hf_constants
+
+    return {"path": str(Path(hf_constants.HF_HUB_CACHE))}
+
+
+@router.post("/models/migrate")
+async def migrate_models(request: models.ModelMigrateRequest):
+    """Move all downloaded models to a new directory with byte-level progress via SSE."""
+    from huggingface_hub import constants as hf_constants
+
+    source = Path(hf_constants.HF_HUB_CACHE)
+    destination = Path(request.destination)
+
+    if not source.exists():
+        raise HTTPException(status_code=404, detail="Current model cache directory not found")
+
+    if source.resolve() == destination.resolve():
+        raise HTTPException(status_code=400, detail="Source and destination are the same directory")
+
+    if destination.resolve().is_relative_to(source.resolve()):
+        raise HTTPException(status_code=400, detail="Destination cannot be inside the current cache directory")
+
+    model_dirs = [d for d in source.iterdir() if d.name.startswith("models--") and d.is_dir()]
+    if not model_dirs:
+        return {"moved": 0, "errors": [], "source": str(source), "destination": str(destination)}
+
+    destination.mkdir(parents=True, exist_ok=True)
+
+    progress_manager = get_progress_manager()
+
+    same_fs = False
+    try:
+        same_fs = source.stat().st_dev == destination.stat().st_dev
+    except OSError:
+        pass
+
+    async def migrate_background():
+        moved = 0
+        errors = []
+        try:
+            if same_fs:
+                total = len(model_dirs)
+                for i, item in enumerate(model_dirs):
+                    dest_item = destination / item.name
+                    try:
+                        if dest_item.exists():
+                            shutil.rmtree(dest_item)
+                        shutil.move(str(item), str(dest_item))
+                        moved += 1
+                        progress_manager.update_progress(
+                            "migration",
+                            i + 1,
+                            total,
+                            filename=item.name,
+                            status="downloading",
+                        )
+                    except Exception as e:
+                        errors.append(f"{item.name}: {str(e)}")
+            else:
+                total_bytes = sum(_get_dir_size(d) for d in model_dirs)
+                progress_manager.update_progress(
+                    "migration", 0, total_bytes, filename="Calculating...", status="downloading"
+                )
+
+                copied = 0
+                for item in model_dirs:
+                    dest_item = destination / item.name
+                    try:
+                        if dest_item.exists():
+                            shutil.rmtree(dest_item)
+                        copied = await asyncio.to_thread(
+                            _copy_with_progress, item, dest_item, progress_manager, copied, total_bytes
+                        )
+                        await asyncio.to_thread(shutil.rmtree, str(item))
+                        moved += 1
+                    except Exception as e:
+                        errors.append(f"{item.name}: {str(e)}")
+
+            progress_manager.update_progress("migration", 1, 1, status="complete")
+            progress_manager.mark_complete("migration")
+        except Exception as e:
+            progress_manager.update_progress("migration", 0, 0, status="error")
+            progress_manager.mark_error("migration", str(e))
+
+    create_background_task(migrate_background())
+
+    return {"source": str(source), "destination": str(destination)}
+
+
+@router.get("/models/migrate/progress")
+async def get_migration_progress():
+    """Get model migration progress via Server-Sent Events."""
+    progress_manager = get_progress_manager()
+
+    async def event_generator():
+        async for event in progress_manager.subscribe("migration"):
+            yield event
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.get("/models/status", response_model=models.ModelStatusListResponse)
+async def get_model_status():
+    """Get status of all available models."""
+    from huggingface_hub import constants as hf_constants
+
+    backend_type = get_backend_type()
+    task_manager = get_task_manager()
+
+    active_download_names = {task.model_name for task in task_manager.get_active_downloads()}
+
+    try:
+        from huggingface_hub import scan_cache_dir
+
+        use_scan_cache = True
+    except ImportError:
+        use_scan_cache = False
+
+    from ..backends import get_all_model_configs, check_model_loaded
+
+    registry_configs = get_all_model_configs()
+    model_configs = [
+        {
+            "model_name": cfg.model_name,
+            "display_name": cfg.display_name,
+            "hf_repo_id": cfg.hf_repo_id,
+            "model_size": cfg.model_size,
+            "check_loaded": lambda c=cfg: check_model_loaded(c),
+        }
+        for cfg in registry_configs
+    ]
+
+    model_to_repo = {cfg["model_name"]: cfg["hf_repo_id"] for cfg in model_configs}
+    active_download_repos = {model_to_repo.get(name) for name in active_download_names if name in model_to_repo}
+
+    cache_info = None
+    if use_scan_cache:
+        try:
+            cache_info = scan_cache_dir()
+        except Exception:
+            pass
+
+    statuses = []
+
+    for config in model_configs:
+        try:
+            downloaded = False
+            size_mb = None
+            loaded = False
+
+            if cache_info:
+                repo_id = config["hf_repo_id"]
+                for repo in cache_info.repos:
+                    if repo.repo_id == repo_id:
+                        has_model_weights = False
+                        for rev in repo.revisions:
+                            for f in rev.files:
+                                fname = f.file_name.lower()
+                                if fname.endswith((".safetensors", ".bin", ".pt", ".pth", ".npz")):
+                                    has_model_weights = True
+                                    break
+                            if has_model_weights:
+                                break
+
+                        has_incomplete = False
+                        try:
+                            cache_dir = hf_constants.HF_HUB_CACHE
+                            blobs_dir = Path(cache_dir) / ("models--" + repo_id.replace("/", "--")) / "blobs"
+                            if blobs_dir.exists():
+                                has_incomplete = any(blobs_dir.glob("*.incomplete"))
+                        except Exception:
+                            pass
+
+                        if has_model_weights and not has_incomplete:
+                            downloaded = True
+                            try:
+                                total_size = sum(revision.size_on_disk for revision in repo.revisions)
+                                size_mb = total_size / (1024 * 1024)
+                            except Exception:
+                                pass
+                        break
+
+            if not downloaded:
+                try:
+                    cache_dir = hf_constants.HF_HUB_CACHE
+                    repo_cache = Path(cache_dir) / ("models--" + config["hf_repo_id"].replace("/", "--"))
+
+                    if repo_cache.exists():
+                        blobs_dir = repo_cache / "blobs"
+                        has_incomplete = blobs_dir.exists() and any(blobs_dir.glob("*.incomplete"))
+
+                        if not has_incomplete:
+                            snapshots_dir = repo_cache / "snapshots"
+                            has_model_files = False
+                            if snapshots_dir.exists():
+                                has_model_files = (
+                                    any(snapshots_dir.rglob("*.bin"))
+                                    or any(snapshots_dir.rglob("*.safetensors"))
+                                    or any(snapshots_dir.rglob("*.pt"))
+                                    or any(snapshots_dir.rglob("*.pth"))
+                                    or any(snapshots_dir.rglob("*.npz"))
+                                )
+
+                            if has_model_files:
+                                downloaded = True
+                                try:
+                                    total_size = sum(
+                                        f.stat().st_size
+                                        for f in repo_cache.rglob("*")
+                                        if f.is_file() and not f.name.endswith(".incomplete")
+                                    )
+                                    size_mb = total_size / (1024 * 1024)
+                                except Exception:
+                                    pass
+                except Exception:
+                    pass
+
+            try:
+                loaded = config["check_loaded"]()
+            except Exception:
+                loaded = False
+
+            is_downloading = config["hf_repo_id"] in active_download_repos
+
+            if is_downloading:
+                downloaded = False
+                size_mb = None
+
+            statuses.append(
+                models.ModelStatus(
+                    model_name=config["model_name"],
+                    display_name=config["display_name"],
+                    hf_repo_id=config["hf_repo_id"],
+                    downloaded=downloaded,
+                    downloading=is_downloading,
+                    size_mb=size_mb,
+                    loaded=loaded,
+                )
+            )
+        except Exception:
+            try:
+                loaded = config["check_loaded"]()
+            except Exception:
+                loaded = False
+
+            is_downloading = config["hf_repo_id"] in active_download_repos
+
+            statuses.append(
+                models.ModelStatus(
+                    model_name=config["model_name"],
+                    display_name=config["display_name"],
+                    hf_repo_id=config["hf_repo_id"],
+                    downloaded=False,
+                    downloading=is_downloading,
+                    size_mb=None,
+                    loaded=loaded,
+                )
+            )
+
+    return models.ModelStatusListResponse(models=statuses)
+
+
+@router.post("/models/download")
+async def trigger_model_download(request: models.ModelDownloadRequest):
+    """Trigger download of a specific model."""
+    from ..backends import get_model_config, get_model_load_func
+
+    task_manager = get_task_manager()
+    progress_manager = get_progress_manager()
+
+    config = get_model_config(request.model_name)
+    if not config:
+        raise HTTPException(status_code=400, detail=f"Unknown model: {request.model_name}")
+
+    load_func = get_model_load_func(config)
+
+    async def download_in_background():
+        try:
+            result = load_func()
+            if asyncio.iscoroutine(result):
+                await result
+            task_manager.complete_download(request.model_name)
+        except Exception as e:
+            task_manager.error_download(request.model_name, str(e))
+
+    task_manager.start_download(request.model_name)
+
+    progress_manager.update_progress(
+        model_name=request.model_name,
+        current=0,
+        total=0,
+        filename="Connecting to HuggingFace...",
+        status="downloading",
+    )
+
+    create_background_task(download_in_background())
+
+    return {"message": f"Model {request.model_name} download started"}
+
+
+@router.post("/models/download/cancel")
+async def cancel_model_download(request: models.ModelDownloadRequest):
+    """Cancel or dismiss an errored/stale download task."""
+    task_manager = get_task_manager()
+    progress_manager = get_progress_manager()
+
+    removed = task_manager.cancel_download(request.model_name)
+
+    progress_removed = False
+    with progress_manager._lock:
+        if request.model_name in progress_manager._progress:
+            del progress_manager._progress[request.model_name]
+            progress_removed = True
+
+    if removed or progress_removed:
+        return {"message": f"Download task for {request.model_name} cancelled"}
+    return {"message": f"No active task found for {request.model_name}"}
+
+
+@router.delete("/models/{model_name}")
+async def delete_model(model_name: str):
+    """Delete a downloaded model from the HuggingFace cache."""
+    from huggingface_hub import constants as hf_constants
+    from ..backends import get_model_config, unload_model_by_config
+
+    config = get_model_config(model_name)
+    if not config:
+        raise HTTPException(status_code=400, detail=f"Unknown model: {model_name}")
+
+    hf_repo_id = config.hf_repo_id
+
+    try:
+        unload_model_by_config(config)
+
+        cache_dir = hf_constants.HF_HUB_CACHE
+        repo_cache_dir = Path(cache_dir) / ("models--" + hf_repo_id.replace("/", "--"))
+
+        if not repo_cache_dir.exists():
+            raise HTTPException(status_code=404, detail=f"Model {model_name} not found in cache")
+
+        try:
+            shutil.rmtree(repo_cache_dir)
+        except OSError as e:
+            raise HTTPException(status_code=500, detail=f"Failed to delete model cache directory: {str(e)}")
+
+        return {"message": f"Model {model_name} deleted successfully"}
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to delete model: {str(e)}")
@@ -0,0 +1,309 @@
+"""Voice profile endpoints."""
+
+import io
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse, StreamingResponse
+from sqlalchemy.orm import Session
+
+from .. import config, models
+from ..app import safe_content_disposition
+from ..database import VoiceProfile as DBVoiceProfile, get_db
+from ..services import channels, export_import, profiles
+from ..services.profiles import _profile_to_response
+
+router = APIRouter()
+
+
+@router.post("/profiles", response_model=models.VoiceProfileResponse)
+async def create_profile(
+    data: models.VoiceProfileCreate,
+    db: Session = Depends(get_db),
+):
+    """Create a new voice profile."""
+    try:
+        return await profiles.create_profile(data, db)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/profiles", response_model=list[models.VoiceProfileResponse])
+async def list_profiles(db: Session = Depends(get_db)):
+    """List all voice profiles."""
+    return await profiles.list_profiles(db)
+
+
+@router.post("/profiles/import", response_model=models.VoiceProfileResponse)
+async def import_profile(
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+):
+    """Import a voice profile from a ZIP archive."""
+    MAX_FILE_SIZE = 100 * 1024 * 1024
+
+    content = await file.read()
+
+    if len(content) > MAX_FILE_SIZE:
+        raise HTTPException(
+            status_code=400, detail=f"File too large. Maximum size is {MAX_FILE_SIZE / (1024 * 1024)}MB"
+        )
+
+    try:
+        profile = await export_import.import_profile_from_zip(content, db)
+        return profile
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/profiles/{profile_id}", response_model=models.VoiceProfileResponse)
+async def get_profile(
+    profile_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get a voice profile by ID."""
+    profile = await profiles.get_profile(profile_id, db)
+    if not profile:
+        raise HTTPException(status_code=404, detail="Profile not found")
+    return profile
+
+
+@router.put("/profiles/{profile_id}", response_model=models.VoiceProfileResponse)
+async def update_profile(
+    profile_id: str,
+    data: models.VoiceProfileCreate,
+    db: Session = Depends(get_db),
+):
+    """Update a voice profile."""
+    try:
+        profile = await profiles.update_profile(profile_id, data, db)
+        if not profile:
+            raise HTTPException(status_code=404, detail="Profile not found")
+        return profile
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/profiles/{profile_id}")
+async def delete_profile(
+    profile_id: str,
+    db: Session = Depends(get_db),
+):
+    """Delete a voice profile."""
+    success = await profiles.delete_profile(profile_id, db)
+    if not success:
+        raise HTTPException(status_code=404, detail="Profile not found")
+    return {"message": "Profile deleted successfully"}
+
+
+@router.post("/profiles/{profile_id}/samples", response_model=models.ProfileSampleResponse)
+async def add_profile_sample(
+    profile_id: str,
+    file: UploadFile = File(...),
+    reference_text: str = Form(...),
+    db: Session = Depends(get_db),
+):
+    """Add a sample to a voice profile."""
+    _allowed_audio_exts = {".wav", ".mp3", ".m4a", ".ogg", ".flac", ".aac", ".webm", ".opus"}
+    _uploaded_ext = Path(file.filename or "").suffix.lower()
+    file_suffix = _uploaded_ext if _uploaded_ext in _allowed_audio_exts else ".wav"
+
+    with tempfile.NamedTemporaryFile(suffix=file_suffix, delete=False) as tmp:
+        content = await file.read()
+        tmp.write(content)
+        tmp_path = tmp.name
+
+    try:
+        sample = await profiles.add_profile_sample(
+            profile_id,
+            tmp_path,
+            reference_text,
+            db,
+        )
+        return sample
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to process audio file: {str(e)}")
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+@router.get("/profiles/{profile_id}/samples", response_model=list[models.ProfileSampleResponse])
+async def get_profile_samples(
+    profile_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get all samples for a profile."""
+    return await profiles.get_profile_samples(profile_id, db)
+
+
+@router.delete("/profiles/samples/{sample_id}")
+async def delete_profile_sample(
+    sample_id: str,
+    db: Session = Depends(get_db),
+):
+    """Delete a profile sample."""
+    success = await profiles.delete_profile_sample(sample_id, db)
+    if not success:
+        raise HTTPException(status_code=404, detail="Sample not found")
+    return {"message": "Sample deleted successfully"}
+
+
+@router.put("/profiles/samples/{sample_id}", response_model=models.ProfileSampleResponse)
+async def update_profile_sample(
+    sample_id: str,
+    data: models.ProfileSampleUpdate,
+    db: Session = Depends(get_db),
+):
+    """Update a profile sample's reference text."""
+    sample = await profiles.update_profile_sample(sample_id, data.reference_text, db)
+    if not sample:
+        raise HTTPException(status_code=404, detail="Sample not found")
+    return sample
+
+
+@router.post("/profiles/{profile_id}/avatar", response_model=models.VoiceProfileResponse)
+async def upload_profile_avatar(
+    profile_id: str,
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+):
+    """Upload or update avatar image for a profile."""
+    with tempfile.NamedTemporaryFile(delete=False, suffix=Path(file.filename).suffix) as tmp:
+        content = await file.read()
+        tmp.write(content)
+        tmp_path = tmp.name
+
+    try:
+        profile = await profiles.upload_avatar(profile_id, tmp_path, db)
+        return profile
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+@router.get("/profiles/{profile_id}/avatar")
+async def get_profile_avatar(
+    profile_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get avatar image for a profile."""
+    profile = await profiles.get_profile(profile_id, db)
+    if not profile:
+        raise HTTPException(status_code=404, detail="Profile not found")
+
+    if not profile.avatar_path:
+        raise HTTPException(status_code=404, detail="No avatar found for this profile")
+
+    avatar_path = Path(profile.avatar_path)
+    if not avatar_path.exists():
+        raise HTTPException(status_code=404, detail="Avatar file not found")
+
+    return FileResponse(avatar_path)
+
+
+@router.delete("/profiles/{profile_id}/avatar")
+async def delete_profile_avatar(
+    profile_id: str,
+    db: Session = Depends(get_db),
+):
+    """Delete avatar image for a profile."""
+    success = await profiles.delete_avatar(profile_id, db)
+    if not success:
+        raise HTTPException(status_code=404, detail="Profile not found or no avatar to delete")
+    return {"message": "Avatar deleted successfully"}
+
+
+@router.get("/profiles/{profile_id}/export")
+async def export_profile(
+    profile_id: str,
+    db: Session = Depends(get_db),
+):
+    """Export a voice profile as a ZIP archive."""
+    try:
+        profile = await profiles.get_profile(profile_id, db)
+        if not profile:
+            raise HTTPException(status_code=404, detail="Profile not found")
+
+        zip_bytes = export_import.export_profile_to_zip(profile_id, db)
+
+        safe_name = "".join(c for c in profile.name if c.isalnum() or c in (" ", "-", "_")).strip()
+        if not safe_name:
+            safe_name = "profile"
+        filename = f"profile-{safe_name}.voicebox.zip"
+
+        return StreamingResponse(
+            io.BytesIO(zip_bytes),
+            media_type="application/zip",
+            headers={"Content-Disposition": safe_content_disposition("attachment", filename)},
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/profiles/{profile_id}/channels")
+async def get_profile_channels(
+    profile_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get list of channel IDs assigned to a profile."""
+    try:
+        channel_ids = await channels.get_profile_channels(profile_id, db)
+        return {"channel_ids": channel_ids}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/profiles/{profile_id}/channels")
+async def set_profile_channels(
+    profile_id: str,
+    data: models.ProfileChannelAssignment,
+    db: Session = Depends(get_db),
+):
+    """Set which channels a profile is assigned to."""
+    try:
+        await channels.set_profile_channels(profile_id, data, db)
+        return {"message": "Profile channels updated successfully"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/profiles/{profile_id}/effects", response_model=models.VoiceProfileResponse)
+async def update_profile_effects(
+    profile_id: str,
+    data: models.ProfileEffectsUpdate,
+    db: Session = Depends(get_db),
+):
+    """Set or clear the default effects chain for a voice profile."""
+    import json as _json
+
+    profile = db.query(DBVoiceProfile).filter_by(id=profile_id).first()
+    if not profile:
+        raise HTTPException(status_code=404, detail="Profile not found")
+
+    if data.effects_chain is not None:
+        from ..utils.effects import validate_effects_chain
+
+        chain_dicts = [e.model_dump() for e in data.effects_chain]
+        error = validate_effects_chain(chain_dicts)
+        if error:
+            raise HTTPException(status_code=400, detail=error)
+        profile.effects_chain = _json.dumps(chain_dicts)
+    else:
+        profile.effects_chain = None
+
+    profile.updated_at = datetime.utcnow()
+    db.commit()
+    db.refresh(profile)
+
+    return _profile_to_response(profile)
@@ -0,0 +1,223 @@
+"""Story endpoints."""
+
+import io
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from sqlalchemy.orm import Session
+
+from .. import database, models
+from ..services import stories
+from ..app import safe_content_disposition
+from ..database import get_db
+
+router = APIRouter()
+
+
+@router.get("/stories", response_model=list[models.StoryResponse])
+async def list_stories(db: Session = Depends(get_db)):
+    """List all stories."""
+    return await stories.list_stories(db)
+
+
+@router.post("/stories", response_model=models.StoryResponse)
+async def create_story(
+    data: models.StoryCreate,
+    db: Session = Depends(get_db),
+):
+    """Create a new story."""
+    try:
+        return await stories.create_story(data, db)
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/stories/{story_id}", response_model=models.StoryDetailResponse)
+async def get_story(
+    story_id: str,
+    db: Session = Depends(get_db),
+):
+    """Get a story with all its items."""
+    story = await stories.get_story(story_id, db)
+    if not story:
+        raise HTTPException(status_code=404, detail="Story not found")
+    return story
+
+
+@router.put("/stories/{story_id}", response_model=models.StoryResponse)
+async def update_story(
+    story_id: str,
+    data: models.StoryCreate,
+    db: Session = Depends(get_db),
+):
+    """Update a story."""
+    story = await stories.update_story(story_id, data, db)
+    if not story:
+        raise HTTPException(status_code=404, detail="Story not found")
+    return story
+
+
+@router.delete("/stories/{story_id}")
+async def delete_story(
+    story_id: str,
+    db: Session = Depends(get_db),
+):
+    """Delete a story."""
+    success = await stories.delete_story(story_id, db)
+    if not success:
+        raise HTTPException(status_code=404, detail="Story not found")
+    return {"message": "Story deleted successfully"}
+
+
+@router.post("/stories/{story_id}/items", response_model=models.StoryItemDetail)
+async def add_story_item(
+    story_id: str,
+    data: models.StoryItemCreate,
+    db: Session = Depends(get_db),
+):
+    """Add a generation to a story."""
+    item = await stories.add_item_to_story(story_id, data, db)
+    if not item:
+        raise HTTPException(status_code=404, detail="Story or generation not found")
+    return item
+
+
+@router.delete("/stories/{story_id}/items/{item_id}")
+async def remove_story_item(
+    story_id: str,
+    item_id: str,
+    db: Session = Depends(get_db),
+):
+    """Remove a story item from a story."""
+    success = await stories.remove_item_from_story(story_id, item_id, db)
+    if not success:
+        raise HTTPException(status_code=404, detail="Story item not found")
+    return {"message": "Item removed successfully"}
+
+
+@router.put("/stories/{story_id}/items/times")
+async def update_story_item_times(
+    story_id: str,
+    data: models.StoryItemBatchUpdate,
+    db: Session = Depends(get_db),
+):
+    """Update story item timecodes."""
+    success = await stories.update_story_item_times(story_id, data, db)
+    if not success:
+        raise HTTPException(status_code=400, detail="Invalid timecode update request")
+    return {"message": "Item timecodes updated successfully"}
+
+
+@router.put("/stories/{story_id}/items/reorder", response_model=list[models.StoryItemDetail])
+async def reorder_story_items(
+    story_id: str,
+    data: models.StoryItemReorder,
+    db: Session = Depends(get_db),
+):
+    """Reorder story items and recalculate timecodes."""
+    items = await stories.reorder_story_items(story_id, data.generation_ids, db)
+    if items is None:
+        raise HTTPException(
+            status_code=400, detail="Invalid reorder request - ensure all generation IDs belong to this story"
+        )
+    return items
+
+
+@router.put("/stories/{story_id}/items/{item_id}/move", response_model=models.StoryItemDetail)
+async def move_story_item(
+    story_id: str,
+    item_id: str,
+    data: models.StoryItemMove,
+    db: Session = Depends(get_db),
+):
+    """Move a story item (update position and/or track)."""
+    item = await stories.move_story_item(story_id, item_id, data, db)
+    if item is None:
+        raise HTTPException(status_code=404, detail="Story item not found")
+    return item
+
+
+@router.put("/stories/{story_id}/items/{item_id}/trim", response_model=models.StoryItemDetail)
+async def trim_story_item(
+    story_id: str,
+    item_id: str,
+    data: models.StoryItemTrim,
+    db: Session = Depends(get_db),
+):
+    """Trim a story item."""
+    item = await stories.trim_story_item(story_id, item_id, data, db)
+    if item is None:
+        raise HTTPException(status_code=404, detail="Story item not found or invalid trim values")
+    return item
+
+
+@router.post("/stories/{story_id}/items/{item_id}/split", response_model=list[models.StoryItemDetail])
+async def split_story_item(
+    story_id: str,
+    item_id: str,
+    data: models.StoryItemSplit,
+    db: Session = Depends(get_db),
+):
+    """Split a story item at a given time, creating two clips."""
+    items = await stories.split_story_item(story_id, item_id, data, db)
+    if items is None:
+        raise HTTPException(status_code=404, detail="Story item not found or invalid split point")
+    return items
+
+
+@router.post("/stories/{story_id}/items/{item_id}/duplicate", response_model=models.StoryItemDetail)
+async def duplicate_story_item(
+    story_id: str,
+    item_id: str,
+    db: Session = Depends(get_db),
+):
+    """Duplicate a story item."""
+    item = await stories.duplicate_story_item(story_id, item_id, db)
+    if item is None:
+        raise HTTPException(status_code=404, detail="Story item not found")
+    return item
+
+
+@router.put("/stories/{story_id}/items/{item_id}/version", response_model=models.StoryItemDetail)
+async def set_story_item_version(
+    story_id: str,
+    item_id: str,
+    data: models.StoryItemVersionUpdate,
+    db: Session = Depends(get_db),
+):
+    """Pin a story item to a specific generation version."""
+    item = await stories.set_story_item_version(story_id, item_id, data, db)
+    if item is None:
+        raise HTTPException(status_code=404, detail="Story item or version not found")
+    return item
+
+
+@router.get("/stories/{story_id}/export-audio")
+async def export_story_audio(
+    story_id: str,
+    db: Session = Depends(get_db),
+):
+    """Export story as single mixed audio file."""
+    try:
+        story = db.query(database.Story).filter_by(id=story_id).first()
+        if not story:
+            raise HTTPException(status_code=404, detail="Story not found")
+
+        audio_bytes = await stories.export_story_audio(story_id, db)
+        if not audio_bytes:
+            raise HTTPException(status_code=400, detail="Story has no audio items")
+
+        safe_name = "".join(c for c in story.name if c.isalnum() or c in (" ", "-", "_")).strip()
+        if not safe_name:
+            safe_name = "story"
+        filename = f"{safe_name}.wav"
+
+        return StreamingResponse(
+            io.BytesIO(audio_bytes),
+            media_type="audio/wav",
+            headers={"Content-Disposition": safe_content_disposition("attachment", filename)},
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
@@ -0,0 +1,125 @@
+"""Task and cache management endpoints."""
+
+from datetime import datetime
+
+from fastapi import APIRouter
+
+from .. import models
+from ..utils.cache import clear_voice_prompt_cache
+from ..utils.progress import get_progress_manager
+from ..utils.tasks import get_task_manager
+from fastapi import HTTPException
+
+router = APIRouter()
+
+
+@router.post("/tasks/clear")
+async def clear_all_tasks():
+    """Clear all download tasks and progress state."""
+    task_manager = get_task_manager()
+    progress_manager = get_progress_manager()
+
+    task_manager.clear_all()
+
+    with progress_manager._lock:
+        progress_manager._progress.clear()
+        progress_manager._last_notify_time.clear()
+        progress_manager._last_notify_progress.clear()
+
+    return {"message": "All task state cleared"}
+
+
+@router.post("/cache/clear")
+async def clear_cache():
+    """Clear all voice prompt caches (memory and disk)."""
+    try:
+        deleted_count = clear_voice_prompt_cache()
+        return {
+            "message": "Voice prompt cache cleared successfully",
+            "files_deleted": deleted_count,
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to clear cache: {str(e)}")
+
+
+@router.get("/tasks/active", response_model=models.ActiveTasksResponse)
+async def get_active_tasks():
+    """Return all currently active downloads and generations."""
+    task_manager = get_task_manager()
+    progress_manager = get_progress_manager()
+
+    active_downloads = []
+    task_manager_downloads = task_manager.get_active_downloads()
+    progress_active = progress_manager.get_all_active()
+
+    download_map = {task.model_name: task for task in task_manager_downloads}
+    progress_map = {p["model_name"]: p for p in progress_active}
+
+    all_model_names = set(download_map.keys()) | set(progress_map.keys())
+    for model_name in all_model_names:
+        task = download_map.get(model_name)
+        progress = progress_map.get(model_name)
+
+        if task:
+            error = task.error
+            if not error:
+                with progress_manager._lock:
+                    pm_data = progress_manager._progress.get(model_name)
+                    if pm_data:
+                        error = pm_data.get("error")
+            prog = progress or {}
+            if not prog:
+                with progress_manager._lock:
+                    pm_data = progress_manager._progress.get(model_name)
+                    if pm_data:
+                        prog = pm_data
+            active_downloads.append(
+                models.ActiveDownloadTask(
+                    model_name=model_name,
+                    status=task.status,
+                    started_at=task.started_at,
+                    error=error,
+                    progress=prog.get("progress"),
+                    current=prog.get("current"),
+                    total=prog.get("total"),
+                    filename=prog.get("filename"),
+                )
+            )
+        elif progress:
+            timestamp_str = progress.get("timestamp")
+            if timestamp_str:
+                try:
+                    started_at = datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
+                except (ValueError, AttributeError):
+                    started_at = datetime.utcnow()
+            else:
+                started_at = datetime.utcnow()
+
+            active_downloads.append(
+                models.ActiveDownloadTask(
+                    model_name=model_name,
+                    status=progress.get("status", "downloading"),
+                    started_at=started_at,
+                    error=progress.get("error"),
+                    progress=progress.get("progress"),
+                    current=progress.get("current"),
+                    total=progress.get("total"),
+                    filename=progress.get("filename"),
+                )
+            )
+
+    active_generations = []
+    for gen_task in task_manager.get_active_generations():
+        active_generations.append(
+            models.ActiveGenerationTask(
+                task_id=gen_task.task_id,
+                profile_id=gen_task.profile_id,
+                text_preview=gen_task.text_preview,
+                started_at=gen_task.started_at,
+            )
+        )
+
+    return models.ActiveTasksResponse(
+        downloads=active_downloads,
+        generations=active_generations,
+    )
@@ -0,0 +1,74 @@
+"""Transcription endpoints."""
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+
+from .. import models
+from ..services import transcribe
+from ..services.task_queue import create_background_task
+from ..utils.tasks import get_task_manager
+
+router = APIRouter()
+
+UPLOAD_CHUNK_SIZE = 1024 * 1024  # 1MB
+
+
+@router.post("/transcribe", response_model=models.TranscriptionResponse)
+async def transcribe_audio(
+    file: UploadFile = File(...),
+    language: str | None = Form(None),
+):
+    """Transcribe audio file to text."""
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
+        while chunk := await file.read(UPLOAD_CHUNK_SIZE):
+            tmp.write(chunk)
+        tmp_path = tmp.name
+
+    try:
+        from ..utils.audio import load_audio
+
+        audio, sr = await asyncio.to_thread(load_audio, tmp_path)
+        duration = len(audio) / sr
+
+        whisper_model = transcribe.get_whisper_model()
+        model_size = whisper_model.model_size
+
+        if not whisper_model.is_loaded() and not whisper_model._is_model_cached(model_size):
+            progress_model_name = f"whisper-{model_size}"
+            task_manager = get_task_manager()
+
+            async def download_whisper_background():
+                try:
+                    await whisper_model.load_model_async(model_size)
+                    task_manager.complete_download(progress_model_name)
+                except Exception as e:
+                    task_manager.error_download(progress_model_name, str(e))
+
+            task_manager.start_download(progress_model_name)
+            create_background_task(download_whisper_background())
+
+            raise HTTPException(
+                status_code=202,
+                detail={
+                    "message": f"Whisper model {model_size} is being downloaded. Please wait and try again.",
+                    "model_name": progress_model_name,
+                    "downloading": True,
+                },
+            )
+
+        text = await whisper_model.transcribe(tmp_path, language)
+
+        return models.TranscriptionResponse(
+            text=text,
+            duration=duration,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
@@ -6,6 +6,39 @@ absolute imports instead of relative imports.
 """

 import sys
+import os
+
+# On Windows with --noconsole (PyInstaller), sys.stdout/stderr are None.
+# They can also be broken file objects in some edge cases.
+# Redirect to devnull to prevent crashes from print()/tqdm/logging.
+def _is_writable(stream):
+    """Check if a stream is usable for writing."""
+    if stream is None:
+        return False
+    try:
+        stream.write("")
+        return True
+    except Exception:
+        return False
+
+if not _is_writable(sys.stdout):
+    sys.stdout = open(os.devnull, 'w')
+if not _is_writable(sys.stderr):
+    sys.stderr = open(os.devnull, 'w')
+
+# PyInstaller + multiprocessing: child processes re-execute the frozen binary
+# with internal arguments. freeze_support() handles this and exits early.
+import multiprocessing
+multiprocessing.freeze_support()
+
+# In frozen builds, piper_phonemize's espeak-ng C library falls back to
+# /usr/share/espeak-ng-data/ which doesn't exist.  Point it at the bundled
+# data directory instead.
+if getattr(sys, 'frozen', False):
+    _meipass = getattr(sys, '_MEIPASS', os.path.dirname(sys.executable))
+    _espeak_data = os.path.join(_meipass, 'piper_phonemize', 'espeak-ng-data')
+    if os.path.isdir(_espeak_data):
+        os.environ.setdefault('ESPEAK_DATA_PATH', _espeak_data)

 # Fast path: handle --version before any heavy imports so the Rust
 # version check doesn't block for 30+ seconds loading torch etc.
@@ -0,0 +1 @@
+# Services layer — generation orchestration and background task management.
@@ -7,14 +7,14 @@ from datetime import datetime
 import uuid
 from sqlalchemy.orm import Session

-from .models import (
+from ..models import (
    AudioChannelCreate,
    AudioChannelUpdate,
    AudioChannelResponse,
    ChannelVoiceAssignment,
    ProfileChannelAssignment,
 )
-from .database import (
+from ..database import (
    AudioChannel as DBAudioChannel,
    ChannelDeviceMapping as DBChannelDeviceMapping,
    ProfileChannelMapping as DBProfileChannelMapping,
@@ -14,9 +14,9 @@ import sys
 from pathlib import Path
 from typing import Optional

-from .config import get_data_dir
-from .utils.progress import get_progress_manager
-from . import __version__
+from ..config import get_data_dir
+from ..utils.progress import get_progress_manager
+from .. import __version__

 logger = logging.getLogger(__name__)

@@ -11,8 +11,8 @@ from typing import List, Optional
 from sqlalchemy.orm import Session
 from sqlalchemy.exc import IntegrityError

-from .database import EffectPreset as DBEffectPreset
-from .models import EffectPresetResponse, EffectPresetCreate, EffectPresetUpdate, EffectConfig
+from ..database import EffectPreset as DBEffectPreset
+from ..models import EffectPresetResponse, EffectPresetCreate, EffectPresetUpdate, EffectConfig


 def _preset_response(p: DBEffectPreset) -> EffectPresetResponse:
@@ -12,16 +12,11 @@ from pathlib import Path
 from typing import Optional
 from sqlalchemy.orm import Session

-from .models import VoiceProfileResponse
-from .database import VoiceProfile as DBVoiceProfile, ProfileSample as DBProfileSample, Generation as DBGeneration, GenerationVersion as DBGenerationVersion
+from ..models import VoiceProfileResponse
+from ..database import VoiceProfile as DBVoiceProfile, ProfileSample as DBProfileSample, Generation as DBGeneration, GenerationVersion as DBGenerationVersion
 from .profiles import create_profile, add_profile_sample
-from .models import VoiceProfileCreate
-from . import config
-
-
-def _get_profiles_dir() -> Path:
-    """Get profiles directory from config."""
-    return config.get_profiles_dir()
+from ..models import VoiceProfileCreate
+from .. import config


 def _get_unique_profile_name(name: str, db: Session) -> str:
@@ -99,7 +94,7 @@ def export_profile_to_zip(profile_id: str, db: Session) -> bytes:

        # Create samples.json mapping
        samples_data = {}
-        profile_dir = _get_profiles_dir() / profile_id
+        profile_dir = config.get_profiles_dir() / profile_id

        for sample in samples:
            # Get filename from audio_path (should be {sample_id}.wav)
@@ -181,7 +176,7 @@ async def import_profile_from_zip(file_bytes: bytes, db: Session) -> VoiceProfil
            profile = await create_profile(profile_create, db)

            # Extract and add samples
-            profile_dir = _get_profiles_dir() / profile.id
+            profile_dir = config.get_profiles_dir() / profile.id
            profile_dir.mkdir(parents=True, exist_ok=True)

            # Handle avatar if present
@@ -351,7 +346,7 @@ async def import_generation_from_zip(file_bytes: bytes, db: Session) -> dict:
    import tempfile
    import shutil
    from datetime import datetime
-    from . import config
+    from .. import config
    
    zip_buffer = io.BytesIO(file_bytes)
    
@@ -0,0 +1,253 @@
+"""
+Unified TTS generation orchestration.
+
+Replaces the three near-identical closures (_run_generation, _run_retry,
+_run_regenerate) that lived in main.py with a single ``run_generation()``
+function parameterized by *mode*.
+
+Mode differences:
+  - "generate"   : full pipeline -- save clean version, optionally apply
+                    effects and create a processed version.
+  - "retry"      : re-runs a failed generation with the same seed.
+                    No effects, no version creation.
+  - "regenerate" : re-runs with seed=None for variation.  Creates a new
+                    version with an auto-incremented "take-N" label.
+"""
+
+from __future__ import annotations
+
+import traceback
+from typing import Literal, Optional
+
+from .. import config
+from . import history, profiles
+from ..database import get_db
+from ..utils.tasks import get_task_manager
+
+
+async def run_generation(
+    *,
+    generation_id: str,
+    profile_id: str,
+    text: str,
+    language: str,
+    engine: str,
+    model_size: str,
+    seed: Optional[int],
+    normalize: bool = False,
+    effects_chain: Optional[list] = None,
+    instruct: Optional[str] = None,
+    mode: Literal["generate", "retry", "regenerate"],
+    max_chunk_chars: Optional[int] = None,
+    crossfade_ms: Optional[int] = None,
+    version_id: Optional[str] = None,
+) -> None:
+    """Execute TTS inference and persist the result.
+
+    This is the single entry point for all background generation work.
+    It is designed to be enqueued via ``services.task_queue.enqueue_generation``.
+    """
+    from ..backends import load_engine_model, get_tts_backend_for_engine, engine_needs_trim
+    from ..utils.chunked_tts import generate_chunked
+    from ..utils.audio import normalize_audio, save_audio, trim_tts_output
+
+    task_manager = get_task_manager()
+    bg_db = next(get_db())
+
+    try:
+        tts_model = get_tts_backend_for_engine(engine)
+
+        if not tts_model.is_loaded():
+            await history.update_generation_status(generation_id, "loading_model", bg_db)
+
+        await load_engine_model(engine, model_size)
+
+        voice_prompt = await profiles.create_voice_prompt_for_profile(
+            profile_id,
+            bg_db,
+            use_cache=True,
+            engine=engine,
+        )
+
+        await history.update_generation_status(generation_id, "generating", bg_db)
+        trim_fn = trim_tts_output if engine_needs_trim(engine) else None
+
+        gen_kwargs: dict = dict(
+            language=language,
+            seed=seed if mode != "regenerate" else None,
+            instruct=instruct,
+            trim_fn=trim_fn,
+        )
+        if max_chunk_chars is not None:
+            gen_kwargs["max_chunk_chars"] = max_chunk_chars
+        if crossfade_ms is not None:
+            gen_kwargs["crossfade_ms"] = crossfade_ms
+
+        audio, sample_rate = await generate_chunked(tts_model, text, voice_prompt, **gen_kwargs)
+
+        # --- Normalize (generate and regenerate always; retry skips) -----
+        if normalize or mode == "regenerate":
+            audio = normalize_audio(audio)
+
+        duration = len(audio) / sample_rate
+
+        # --- Persist audio and update status -----------------------------
+        if mode == "generate":
+            final_path = _save_generate(
+                generation_id=generation_id,
+                audio=audio,
+                sample_rate=sample_rate,
+                effects_chain=effects_chain,
+                save_audio=save_audio,
+                db=bg_db,
+            )
+        elif mode == "retry":
+            final_path = _save_retry(
+                generation_id=generation_id,
+                audio=audio,
+                sample_rate=sample_rate,
+                save_audio=save_audio,
+            )
+        elif mode == "regenerate":
+            final_path = _save_regenerate(
+                generation_id=generation_id,
+                version_id=version_id,
+                audio=audio,
+                sample_rate=sample_rate,
+                save_audio=save_audio,
+                db=bg_db,
+            )
+
+        await history.update_generation_status(
+            generation_id=generation_id,
+            status="completed",
+            db=bg_db,
+            audio_path=final_path,
+            duration=duration,
+        )
+
+    except Exception as e:
+        traceback.print_exc()
+        await history.update_generation_status(
+            generation_id=generation_id,
+            status="failed",
+            db=bg_db,
+            error=str(e),
+        )
+    finally:
+        task_manager.complete_generation(generation_id)
+        bg_db.close()
+
+
+def _save_generate(
+    *,
+    generation_id: str,
+    audio,
+    sample_rate: int,
+    effects_chain: Optional[list],
+    save_audio,
+    db,
+) -> str:
+    """Save clean version and optionally an effects-processed version.
+
+    Returns the final audio path (processed if effects were applied,
+    otherwise clean).
+    """
+    from . import versions as versions_mod
+
+    clean_audio_path = config.get_generations_dir() / f"{generation_id}.wav"
+    save_audio(audio, str(clean_audio_path), sample_rate)
+
+    has_effects = effects_chain and any(e.get("enabled", True) for e in effects_chain)
+
+    versions_mod.create_version(
+        generation_id=generation_id,
+        label="original",
+        audio_path=str(clean_audio_path),
+        db=db,
+        effects_chain=None,
+        is_default=not has_effects,
+    )
+
+    final_audio_path = str(clean_audio_path)
+
+    if has_effects:
+        from ..utils.effects import apply_effects, validate_effects_chain
+
+        error_msg = validate_effects_chain(effects_chain)
+        if error_msg:
+            import logging
+            logging.getLogger(__name__).warning("invalid effects chain, skipping: %s", error_msg)
+            versions_mod.set_default_version(
+                versions_mod.list_versions(generation_id, db)[0].id, db
+            )
+        else:
+            processed_audio = apply_effects(audio, sample_rate, effects_chain)
+            processed_path = config.get_generations_dir() / f"{generation_id}_processed.wav"
+            save_audio(processed_audio, str(processed_path), sample_rate)
+            final_audio_path = str(processed_path)
+            versions_mod.create_version(
+                generation_id=generation_id,
+                label="version-2",
+                audio_path=str(processed_path),
+                db=db,
+                effects_chain=effects_chain,
+                is_default=True,
+            )
+
+    return final_audio_path
+
+
+def _save_retry(
+    *,
+    generation_id: str,
+    audio,
+    sample_rate: int,
+    save_audio,
+) -> str:
+    """Save retry output -- single file, no versions.
+
+    Returns the audio path.
+    """
+    audio_path = config.get_generations_dir() / f"{generation_id}.wav"
+    save_audio(audio, str(audio_path), sample_rate)
+    return str(audio_path)
+
+
+def _save_regenerate(
+    *,
+    generation_id: str,
+    version_id: Optional[str],
+    audio,
+    sample_rate: int,
+    save_audio,
+    db,
+) -> str:
+    """Save regeneration output as a new version with auto-label.
+
+    Returns the audio path.
+    """
+    from . import versions as versions_mod
+
+    import uuid as _uuid
+
+    suffix = _uuid.uuid4().hex[:8]
+    audio_path = config.get_generations_dir() / f"{generation_id}_{suffix}.wav"
+    save_audio(audio, str(audio_path), sample_rate)
+
+    # Count via DB query rather than list length to avoid TOCTOU race
+    from ..database import GenerationVersion as DBGenerationVersion
+
+    count = db.query(DBGenerationVersion).filter_by(generation_id=generation_id).count()
+    label = f"take-{count + 1}"
+
+    versions_mod.create_version(
+        generation_id=generation_id,
+        label=label,
+        audio_path=str(audio_path),
+        db=db,
+        effects_chain=None,
+        is_default=True,
+    )
+
+    return str(audio_path)
@@ -10,14 +10,9 @@ from pathlib import Path
 from sqlalchemy.orm import Session
 from sqlalchemy import or_

-from .models import GenerationRequest, GenerationResponse, HistoryQuery, HistoryResponse, HistoryListResponse, GenerationVersionResponse, EffectConfig
-from .database import Generation as DBGeneration, GenerationVersion as DBGenerationVersion, VoiceProfile as DBVoiceProfile
-from . import config
-
-
-def _get_generations_dir() -> Path:
-    """Get generations directory from config."""
-    return config.get_generations_dir()
+from ..models import GenerationRequest, GenerationResponse, HistoryQuery, HistoryResponse, HistoryListResponse, GenerationVersionResponse, EffectConfig
+from ..database import Generation as DBGeneration, GenerationVersion as DBGenerationVersion, VoiceProfile as DBVoiceProfile
+from .. import config


 def _get_versions_for_generation(generation_id: str, db: Session) -> tuple:
@@ -10,23 +10,23 @@ from pathlib import Path
 from sqlalchemy.orm import Session
 from sqlalchemy import func, select

-from .models import (
+from ..models import (
    VoiceProfileCreate,
    VoiceProfileResponse,
    ProfileSampleCreate,
    ProfileSampleResponse,
 )
-from .database import (
+from ..database import (
    VoiceProfile as DBVoiceProfile,
    ProfileSample as DBProfileSample,
    Generation as DBGeneration,
 )
-from .models import EffectConfig
-from .utils.audio import validate_reference_audio, load_audio, save_audio
-from .utils.images import validate_image, process_avatar
-from .utils.cache import _get_cache_dir, clear_profile_cache
+from ..models import EffectConfig
+from ..utils.audio import validate_reference_audio, load_audio, save_audio
+from ..utils.images import validate_image, process_avatar
+from ..utils.cache import _get_cache_dir, clear_profile_cache
 from .tts import get_tts_model
-from . import config
+from .. import config
 import json as _json


@@ -43,6 +43,7 @@ def _profile_to_response(
            effects_chain = [EffectConfig(**e) for e in raw]
        except Exception as e:
            import logging
+
            logging.warning(f"Failed to parse effects_chain for profile {profile.id}: {e}")
    return VoiceProfileResponse(
        id=profile.id,
@@ -58,11 +59,6 @@ def _profile_to_response(
    )


-def _get_profiles_dir() -> Path:
-    """Get profiles directory from config."""
-    return config.get_profiles_dir()
-
-
 async def create_profile(
    data: VoiceProfileCreate,
    db: Session,
@@ -80,12 +76,10 @@ async def create_profile(
    Raises:
        ValueError: If a profile with the same name already exists
    """
-    # Check if profile name already exists
    existing_profile = db.query(DBVoiceProfile).filter_by(name=data.name).first()
    if existing_profile:
        raise ValueError(f"A profile with the name '{data.name}' already exists. Please choose a different name.")

-    # Create profile in database
    db_profile = DBVoiceProfile(
        id=str(uuid.uuid4()),
        name=data.name,
@@ -99,8 +93,7 @@ async def create_profile(
    db.commit()
    db.refresh(db_profile)

-    # Create profile directory
-    profile_dir = _get_profiles_dir() / db_profile.id
+    profile_dir = config.get_profiles_dir() / db_profile.id
    profile_dir.mkdir(parents=True, exist_ok=True)

    return _profile_to_response(db_profile)
@@ -114,56 +107,50 @@ async def add_profile_sample(
 ) -> ProfileSampleResponse:
    """
    Add a sample to a voice profile.
-    
+
    Args:
        profile_id: Profile ID
        audio_path: Path to temporary audio file
        reference_text: Transcript of audio
        db: Database session
-        
+
    Returns:
        Created sample
    """
-    # Validate profile exists
    profile = db.query(DBVoiceProfile).filter_by(id=profile_id).first()
    if not profile:
        raise ValueError(f"Profile {profile_id} not found")
-    
-    # Validate audio
+
    is_valid, error_msg = validate_reference_audio(audio_path)
    if not is_valid:
        raise ValueError(f"Invalid reference audio: {error_msg}")
-    
-    # Create sample ID and directory
+
    sample_id = str(uuid.uuid4())
-    profile_dir = _get_profiles_dir() / profile_id
+    profile_dir = config.get_profiles_dir() / profile_id
    profile_dir.mkdir(parents=True, exist_ok=True)
-    
-    # Copy audio file to profile directory
+
    dest_path = profile_dir / f"{sample_id}.wav"
    audio, sr = load_audio(audio_path)
    save_audio(audio, str(dest_path), sr)
-    
-    # Create database entry
+
    db_sample = DBProfileSample(
        id=sample_id,
        profile_id=profile_id,
        audio_path=str(dest_path),
        reference_text=reference_text,
    )
-    
+
    db.add(db_sample)
-    
-    # Update profile timestamp
+
    profile.updated_at = datetime.utcnow()
-    
+
    db.commit()
    db.refresh(db_sample)
-    
+
    # Invalidate combined audio cache for this profile
    # Since a new sample was added, any cached combined audio is now stale
    clear_profile_cache(profile_id)
-    
+
    return ProfileSampleResponse.model_validate(db_sample)


@@ -173,18 +160,18 @@ async def get_profile(
 ) -> Optional[VoiceProfileResponse]:
    """
    Get a voice profile by ID.
-    
+
    Args:
        profile_id: Profile ID
        db: Database session
-        
+
    Returns:
        Profile or None if not found
    """
    profile = db.query(DBVoiceProfile).filter_by(id=profile_id).first()
    if not profile:
        return None
-    
+
    return _profile_to_response(profile)


@@ -194,11 +181,11 @@ async def get_profile_samples(
 ) -> List[ProfileSampleResponse]:
    """
    Get all samples for a profile.
-    
+
    Args:
        profile_id: Profile ID
        db: Database session
-        
+
    Returns:
        List of samples
    """
@@ -209,33 +196,27 @@ async def get_profile_samples(
 async def list_profiles(db: Session) -> List[VoiceProfileResponse]:
    """
    List all voice profiles with generation and sample counts.
-    
+
    Args:
        db: Database session
-        
+
    Returns:
        List of profiles
    """
-    profiles = db.query(DBVoiceProfile).order_by(
-        DBVoiceProfile.created_at.desc()
-    ).all()
+    profiles = db.query(DBVoiceProfile).order_by(DBVoiceProfile.created_at.desc()).all()

    if not profiles:
        return []

    # Batch-fetch generation counts
    gen_counts_rows = (
-        db.query(DBGeneration.profile_id, func.count(DBGeneration.id))
-        .group_by(DBGeneration.profile_id)
-        .all()
+        db.query(DBGeneration.profile_id, func.count(DBGeneration.id)).group_by(DBGeneration.profile_id).all()
    )
    gen_counts = {row[0]: row[1] for row in gen_counts_rows}

    # Batch-fetch sample counts
    sample_counts_rows = (
-        db.query(DBProfileSample.profile_id, func.count(DBProfileSample.id))
-        .group_by(DBProfileSample.profile_id)
-        .all()
+        db.query(DBProfileSample.profile_id, func.count(DBProfileSample.id)).group_by(DBProfileSample.profile_id).all()
    )
    sample_counts = {row[0]: row[1] for row in sample_counts_rows}

@@ -272,13 +253,11 @@ async def update_profile(
    if not profile:
        return None

-    # Check if the new name conflicts with another profile
    if profile.name != data.name:
        existing_profile = db.query(DBVoiceProfile).filter_by(name=data.name).first()
        if existing_profile:
            raise ValueError(f"A profile with the name '{data.name}' already exists. Please choose a different name.")

-    # Update fields
    profile.name = data.name
    profile.description = data.description
    profile.language = data.language
@@ -296,33 +275,30 @@ async def delete_profile(
 ) -> bool:
    """
    Delete a voice profile and all associated data.
-    
+
    Args:
        profile_id: Profile ID
        db: Database session
-        
+
    Returns:
        True if deleted, False if not found
    """
    profile = db.query(DBVoiceProfile).filter_by(id=profile_id).first()
    if not profile:
        return False
-    
-    # Delete samples from database
+
    db.query(DBProfileSample).filter_by(profile_id=profile_id).delete()
-    
-    # Delete profile from database
+
    db.delete(profile)
    db.commit()
-    
-    # Delete profile directory
-    profile_dir = _get_profiles_dir() / profile_id
+
+    profile_dir = config.get_profiles_dir() / profile_id
    if profile_dir.exists():
        shutil.rmtree(profile_dir)
-    
+
    # Clean up combined audio cache files for this profile
    clear_profile_cache(profile_id)
-    
+
    return True


@@ -332,34 +308,32 @@ async def delete_profile_sample(
 ) -> bool:
    """
    Delete a profile sample.
-    
+
    Args:
        sample_id: Sample ID
        db: Database session
-        
+
    Returns:
        True if deleted, False if not found
    """
    sample = db.query(DBProfileSample).filter_by(id=sample_id).first()
    if not sample:
        return False
-    
+
    # Store profile_id before deleting
    profile_id = sample.profile_id
-    
-    # Delete audio file
+
    audio_path = Path(sample.audio_path)
    if audio_path.exists():
        audio_path.unlink()
-    
-    # Delete from database
+
    db.delete(sample)
    db.commit()
-    
+
    # Invalidate combined audio cache for this profile
    # Since the sample set changed, any cached combined audio is now stale
    clear_profile_cache(profile_id)
-    
+
    return True


@@ -370,30 +344,30 @@ async def update_profile_sample(
 ) -> Optional[ProfileSampleResponse]:
    """
    Update a profile sample's reference text.
-    
+
    Args:
        sample_id: Sample ID
        reference_text: Updated reference text
        db: Database session
-        
+
    Returns:
        Updated sample or None if not found
    """
    sample = db.query(DBProfileSample).filter_by(id=sample_id).first()
    if not sample:
        return None
-    
+
    # Store profile_id before updating
    profile_id = sample.profile_id
-    
+
    sample.reference_text = reference_text
    db.commit()
    db.refresh(sample)
-    
+
    # Invalidate combined audio cache for this profile
    # Since the reference text changed, cache keys and combined text are now stale
    clear_profile_cache(profile_id)
-    
+
    return ProfileSampleResponse.model_validate(sample)


@@ -415,9 +389,8 @@ async def create_voice_prompt_for_profile(
    Returns:
        Voice prompt dictionary
    """
-    from .backends import get_tts_backend_for_engine
+    from ..backends import get_tts_backend_for_engine

-    # Get all samples for profile
    samples = db.query(DBProfileSample).filter_by(profile_id=profile_id).all()

    if not samples:
@@ -426,7 +399,6 @@ async def create_voice_prompt_for_profile(
    tts_model = get_tts_backend_for_engine(engine)

    if len(samples) == 1:
-        # Single sample - use directly
        sample = samples[0]
        voice_prompt, _ = await tts_model.create_voice_prompt(
            sample.audio_path,
@@ -435,11 +407,9 @@ async def create_voice_prompt_for_profile(
        )
        return voice_prompt
    else:
-        # Multiple samples - combine them
        audio_paths = [s.audio_path for s in samples]
        reference_texts = [s.reference_text for s in samples]

-        # Combine audio
        combined_audio, combined_text = await tts_model.combine_voice_prompts(
            audio_paths,
            reference_texts,
@@ -448,18 +418,16 @@ async def create_voice_prompt_for_profile(
        # Save combined audio to cache directory (persistent)
        # Create a hash of sample IDs to identify this specific combination
        import hashlib
+
        sample_ids_str = "-".join(sorted([s.id for s in samples]))
        combination_hash = hashlib.md5(sample_ids_str.encode()).hexdigest()[:12]
-        
-        # Store in cache directory
+
        cache_dir = _get_cache_dir()
        cache_dir.mkdir(parents=True, exist_ok=True)
        combined_path = cache_dir / f"combined_{profile_id}_{combination_hash}.wav"
-        
-        # Save combined audio
+
        save_audio(combined_audio, str(combined_path), 24000)

-        # Create prompt from combined audio
        voice_prompt, _ = await tts_model.create_voice_prompt(
            str(combined_path),
            combined_text,
@@ -484,17 +452,14 @@ async def upload_avatar(
    Returns:
        Updated profile
    """
-    # Validate profile exists
    profile = db.query(DBVoiceProfile).filter_by(id=profile_id).first()
    if not profile:
        raise ValueError(f"Profile {profile_id} not found")

-    # Validate image
    is_valid, error_msg = validate_image(image_path)
    if not is_valid:
        raise ValueError(error_msg)

-    # Delete existing avatar if present
    if profile.avatar_path:
        old_avatar = Path(profile.avatar_path)
        if old_avatar.exists():
@@ -502,27 +467,22 @@ async def upload_avatar(

    # Determine file extension from uploaded file
    from PIL import Image
+
    with Image.open(image_path) as img:
        # Normalize JPEG variants (MPO is multi-picture format from some cameras)
        img_format = img.format
-        if img_format in ('MPO', 'JPG'):
-            img_format = 'JPEG'
-        
-        ext_map = {
-            'PNG': '.png',
-            'JPEG': '.jpg',
-            'WEBP': '.webp'
-        }
-        ext = ext_map.get(img_format, '.png')
+        if img_format in ("MPO", "JPG"):
+            img_format = "JPEG"

-    # Save processed image to profile directory
-    profile_dir = _get_profiles_dir() / profile_id
+        ext_map = {"PNG": ".png", "JPEG": ".jpg", "WEBP": ".webp"}
+        ext = ext_map.get(img_format, ".png")
+
+    profile_dir = config.get_profiles_dir() / profile_id
    profile_dir.mkdir(parents=True, exist_ok=True)
    output_path = profile_dir / f"avatar{ext}"

    process_avatar(image_path, str(output_path))

-    # Update database
    profile.avatar_path = str(output_path)
    profile.updated_at = datetime.utcnow()

@@ -550,12 +510,10 @@ async def delete_avatar(
    if not profile or not profile.avatar_path:
        return False

-    # Delete avatar file
    avatar_path = Path(profile.avatar_path)
    if avatar_path.exists():
        avatar_path.unlink()

-    # Update database
    profile.avatar_path = None
    profile.updated_at = datetime.utcnow()

@@ -10,7 +10,7 @@ from pathlib import Path
 from sqlalchemy.orm import Session
 from sqlalchemy import func

-from .models import (
+from ..models import (
    StoryCreate,
    StoryResponse,
    StoryDetailResponse,
@@ -22,9 +22,14 @@ from .models import (
    StoryItemSplit,
    StoryItemVersionUpdate,
 )
-from .database import Story as DBStory, StoryItem as DBStoryItem, Generation as DBGeneration, VoiceProfile as DBVoiceProfile
+from ..database import (
+    Story as DBStory,
+    StoryItem as DBStoryItem,
+    Generation as DBGeneration,
+    VoiceProfile as DBVoiceProfile,
+)
 from .history import _get_versions_for_generation
-from .utils.audio import load_audio, save_audio
+from ..utils.audio import load_audio, save_audio
 import numpy as np


@@ -49,11 +54,11 @@ def _build_item_detail(
        id=item.id,
        story_id=item.story_id,
        generation_id=item.generation_id,
-        version_id=getattr(item, 'version_id', None),
+        version_id=getattr(item, "version_id", None),
        start_time_ms=item.start_time_ms,
        track=item.track,
-        trim_start_ms=getattr(item, 'trim_start_ms', 0),
-        trim_end_ms=getattr(item, 'trim_end_ms', 0),
+        trim_start_ms=getattr(item, "trim_start_ms", 0),
+        trim_end_ms=getattr(item, "trim_end_ms", 0),
        created_at=item.created_at,
        profile_id=generation.profile_id,
        profile_name=profile_name,
@@ -95,10 +100,7 @@ async def create_story(
    db.commit()
    db.refresh(db_story)

-    # Get item count
-    item_count = db.query(func.count(DBStoryItem.id)).filter(
-        DBStoryItem.story_id == db_story.id
-    ).scalar()
+    item_count = db.query(func.count(DBStoryItem.id)).filter(DBStoryItem.story_id == db_story.id).scalar()

    response = StoryResponse.model_validate(db_story)
    response.item_count = item_count
@@ -118,17 +120,15 @@ async def list_stories(
        List of stories with item counts
    """
    stories = db.query(DBStory).order_by(DBStory.updated_at.desc()).all()
-    
+
    result = []
    for story in stories:
-        item_count = db.query(func.count(DBStoryItem.id)).filter(
-            DBStoryItem.story_id == story.id
-        ).scalar()
-        
+        item_count = db.query(func.count(DBStoryItem.id)).filter(DBStoryItem.story_id == story.id).scalar()
+
        response = StoryResponse.model_validate(story)
        response.item_count = item_count
        result.append(response)
-    
+
    return result


@@ -150,22 +150,15 @@ async def get_story(
    if not story:
        return None

-    # Get all items ordered by start_time_ms
-    items = db.query(
-        DBStoryItem,
-        DBGeneration,
-        DBVoiceProfile.name.label('profile_name')
-    ).join(
-        DBGeneration,
-        DBStoryItem.generation_id == DBGeneration.id
-    ).join(
-        DBVoiceProfile,
-        DBGeneration.profile_id == DBVoiceProfile.id
-    ).filter(
-        DBStoryItem.story_id == story_id
-    ).order_by(DBStoryItem.start_time_ms).all()
+    items = (
+        db.query(DBStoryItem, DBGeneration, DBVoiceProfile.name.label("profile_name"))
+        .join(DBGeneration, DBStoryItem.generation_id == DBGeneration.id)
+        .join(DBVoiceProfile, DBGeneration.profile_id == DBVoiceProfile.id)
+        .filter(DBStoryItem.story_id == story_id)
+        .order_by(DBStoryItem.start_time_ms)
+        .all()
+    )

-    # Build item details
    item_details = []
    for item, generation, profile_name in items:
        item_details.append(_build_item_detail(item, generation, profile_name, db))
@@ -202,10 +195,7 @@ async def update_story(
    db.commit()
    db.refresh(story)

-    # Get item count
-    item_count = db.query(func.count(DBStoryItem.id)).filter(
-        DBStoryItem.story_id == story.id
-    ).scalar()
+    item_count = db.query(func.count(DBStoryItem.id)).filter(DBStoryItem.story_id == story.id).scalar()

    response = StoryResponse.model_validate(story)
    response.item_count = item_count
@@ -267,10 +257,7 @@ async def add_item_to_story(
        return None

    # Check if generation is already in story
-    existing = db.query(DBStoryItem).filter_by(
-        story_id=story_id,
-        generation_id=data.generation_id
-    ).first()
+    existing = db.query(DBStoryItem).filter_by(story_id=story_id, generation_id=data.generation_id).first()
    if existing:
        # Return existing item
        profile = db.query(DBVoiceProfile).filter_by(id=generation.profile_id).first()
@@ -283,18 +270,16 @@ async def add_item_to_story(
    if data.start_time_ms is not None:
        start_time_ms = data.start_time_ms
    else:
-        # Find the maximum end time on the target track only
-        existing_items = db.query(
-            DBStoryItem,
-            DBGeneration
-        ).join(
-            DBGeneration,
-            DBStoryItem.generation_id == DBGeneration.id
-        ).filter(
-            DBStoryItem.story_id == story_id,
-            DBStoryItem.track == track,
-        ).all()
-        
+        existing_items = (
+            db.query(DBStoryItem, DBGeneration)
+            .join(DBGeneration, DBStoryItem.generation_id == DBGeneration.id)
+            .filter(
+                DBStoryItem.story_id == story_id,
+                DBStoryItem.track == track,
+            )
+            .all()
+        )
+
        if not existing_items:
            start_time_ms = 0
        else:
@@ -302,7 +287,7 @@ async def add_item_to_story(
            for item, gen in existing_items:
                item_end_ms = item.start_time_ms + int(gen.duration * 1000)
                max_end_time_ms = max(max_end_time_ms, item_end_ms)
-            
+
            # Add 200ms gap after the last item
            start_time_ms = max_end_time_ms + 200

@@ -317,10 +302,10 @@ async def add_item_to_story(
    )

    db.add(item)
-    
+
    # Update story updated_at
    story.updated_at = datetime.utcnow()
-    
+
    db.commit()
    db.refresh(item)

@@ -349,10 +334,14 @@ async def move_story_item(
        Updated item detail or None if not found
    """
    # Get the item
-    item = db.query(DBStoryItem).filter_by(
-        id=item_id,
-        story_id=story_id,
-    ).first()
+    item = (
+        db.query(DBStoryItem)
+        .filter_by(
+            id=item_id,
+            story_id=story_id,
+        )
+        .first()
+    )
    if not item:
        return None

@@ -395,10 +384,14 @@ async def remove_item_from_story(
    Returns:
        True if removed, False if not found
    """
-    item = db.query(DBStoryItem).filter_by(
-        id=item_id,
-        story_id=story_id,
-    ).first()
+    item = (
+        db.query(DBStoryItem)
+        .filter_by(
+            id=item_id,
+            story_id=story_id,
+        )
+        .first()
+    )
    if not item:
        return False

@@ -433,10 +426,14 @@ async def trim_story_item(
        Updated item detail or None if not found
    """
    # Get the item
-    item = db.query(DBStoryItem).filter_by(
-        id=item_id,
-        story_id=story_id,
-    ).first()
+    item = (
+        db.query(DBStoryItem)
+        .filter_by(
+            id=item_id,
+            story_id=story_id,
+        )
+        .first()
+    )
    if not item:
        return None

@@ -487,10 +484,14 @@ async def split_story_item(
        List of two updated item details (original and new) or None if not found/invalid
    """
    # Get the item
-    item = db.query(DBStoryItem).filter_by(
-        id=item_id,
-        story_id=story_id,
-    ).first()
+    item = (
+        db.query(DBStoryItem)
+        .filter_by(
+            id=item_id,
+            story_id=story_id,
+        )
+        .first()
+    )
    if not item:
        return None

@@ -500,8 +501,8 @@ async def split_story_item(
        return None

    # Calculate effective duration and validate split point
-    current_trim_start = getattr(item, 'trim_start_ms', 0)
-    current_trim_end = getattr(item, 'trim_end_ms', 0)
+    current_trim_start = getattr(item, "trim_start_ms", 0)
+    current_trim_end = getattr(item, "trim_end_ms", 0)
    original_duration_ms = int(generation.duration * 1000)
    effective_duration_ms = original_duration_ms - current_trim_start - current_trim_end

@@ -520,7 +521,7 @@ async def split_story_item(
        id=str(uuid.uuid4()),
        story_id=story_id,
        generation_id=item.generation_id,  # Same generation, different trim
-        version_id=getattr(item, 'version_id', None),  # Preserve pinned version
+        version_id=getattr(item, "version_id", None),  # Preserve pinned version
        start_time_ms=item.start_time_ms + data.split_time_ms,
        track=item.track,
        trim_start_ms=absolute_split_ms,
@@ -566,10 +567,14 @@ async def duplicate_story_item(
        New item detail or None if not found
    """
    # Get the original item
-    original_item = db.query(DBStoryItem).filter_by(
-        id=item_id,
-        story_id=story_id,
-    ).first()
+    original_item = (
+        db.query(DBStoryItem)
+        .filter_by(
+            id=item_id,
+            story_id=story_id,
+        )
+        .first()
+    )
    if not original_item:
        return None

@@ -579,8 +584,8 @@ async def duplicate_story_item(
        return None

    # Calculate effective duration
-    current_trim_start = getattr(original_item, 'trim_start_ms', 0)
-    current_trim_end = getattr(original_item, 'trim_end_ms', 0)
+    current_trim_start = getattr(original_item, "trim_start_ms", 0)
+    current_trim_end = getattr(original_item, "trim_end_ms", 0)
    original_duration_ms = int(generation.duration * 1000)
    effective_duration_ms = original_duration_ms - current_trim_start - current_trim_end

@@ -589,7 +594,7 @@ async def duplicate_story_item(
        id=str(uuid.uuid4()),
        story_id=story_id,
        generation_id=original_item.generation_id,  # Same generation as original
-        version_id=getattr(original_item, 'version_id', None),  # Preserve pinned version
+        version_id=getattr(original_item, "version_id", None),  # Preserve pinned version
        start_time_ms=original_item.start_time_ms + effective_duration_ms + 200,  # 200ms gap
        track=original_item.track,
        trim_start_ms=current_trim_start,
@@ -673,19 +678,13 @@ async def reorder_story_items(
        return None

    # Get all items for this story with their generation data
-    items_with_gen = db.query(
-        DBStoryItem,
-        DBGeneration,
-        DBVoiceProfile.name.label('profile_name')
-    ).join(
-        DBGeneration,
-        DBStoryItem.generation_id == DBGeneration.id
-    ).join(
-        DBVoiceProfile,
-        DBGeneration.profile_id == DBVoiceProfile.id
-    ).filter(
-        DBStoryItem.story_id == story_id
-    ).all()
+    items_with_gen = (
+        db.query(DBStoryItem, DBGeneration, DBVoiceProfile.name.label("profile_name"))
+        .join(DBGeneration, DBStoryItem.generation_id == DBGeneration.id)
+        .join(DBVoiceProfile, DBGeneration.profile_id == DBVoiceProfile.id)
+        .filter(DBStoryItem.story_id == story_id)
+        .all()
+    )

    # Create maps for quick lookup
    item_map = {item.generation_id: (item, gen, profile_name) for item, gen, profile_name in items_with_gen}
@@ -700,13 +699,13 @@ async def reorder_story_items(

    for gen_id in generation_ids:
        item, generation, profile_name = item_map[gen_id]
-        
+
        # Update the item's start time
        item.start_time_ms = current_time_ms
-        
+
        # Calculate the duration in ms
        duration_ms = int(generation.duration * 1000)
-        
+
        # Move to next position (current end + gap)
        current_time_ms += duration_ms + gap_ms

@@ -738,10 +737,14 @@ async def set_story_item_version(
    Returns:
        Updated item detail or None if not found
    """
-    item = db.query(DBStoryItem).filter_by(
-        id=item_id,
-        story_id=story_id,
-    ).first()
+    item = (
+        db.query(DBStoryItem)
+        .filter_by(
+            id=item_id,
+            story_id=story_id,
+        )
+        .first()
+    )
    if not item:
        return None

@@ -751,11 +754,16 @@ async def set_story_item_version(

    # Validate version_id belongs to this generation if provided
    if data.version_id:
-        from .database import GenerationVersion as DBGenerationVersion
-        version = db.query(DBGenerationVersion).filter_by(
-            id=data.version_id,
-            generation_id=item.generation_id,
-        ).first()
+        from ..database import GenerationVersion as DBGenerationVersion
+
+        version = (
+            db.query(DBGenerationVersion)
+            .filter_by(
+                id=data.version_id,
+                generation_id=item.generation_id,
+            )
+            .first()
+        )
        if not version:
            return None

@@ -793,15 +801,13 @@ async def export_story_audio(
        return None

    # Get all items ordered by start_time_ms
-    items = db.query(
-        DBStoryItem,
-        DBGeneration
-    ).join(
-        DBGeneration,
-        DBStoryItem.generation_id == DBGeneration.id
-    ).filter(
-        DBStoryItem.story_id == story_id
-    ).order_by(DBStoryItem.start_time_ms).all()
+    items = (
+        db.query(DBStoryItem, DBGeneration)
+        .join(DBGeneration, DBStoryItem.generation_id == DBGeneration.id)
+        .filter(DBStoryItem.story_id == story_id)
+        .order_by(DBStoryItem.start_time_ms)
+        .all()
+    )

    if not items:
        return None
@@ -813,8 +819,9 @@ async def export_story_audio(
    for item, generation in items:
        # Resolve audio path: use pinned version if set, otherwise generation default
        resolved_audio_path = generation.audio_path
-        if getattr(item, 'version_id', None):
-            from .database import GenerationVersion as DBGenerationVersion
+        if getattr(item, "version_id", None):
+            from ..database import GenerationVersion as DBGenerationVersion
+
            version = db.query(DBGenerationVersion).filter_by(id=item.version_id).first()
            if version:
                resolved_audio_path = version.audio_path
@@ -826,33 +833,37 @@ async def export_story_audio(
        try:
            audio, sr = load_audio(str(audio_path), sample_rate=sample_rate)
            sample_rate = sr  # Use actual sample rate from first file
-            
+
            # Get trim values
-            trim_start_ms = getattr(item, 'trim_start_ms', 0)
-            trim_end_ms = getattr(item, 'trim_end_ms', 0)
-            
+            trim_start_ms = getattr(item, "trim_start_ms", 0)
+            trim_end_ms = getattr(item, "trim_end_ms", 0)
+
            # Calculate effective duration
            original_duration_ms = int(generation.duration * 1000)
            effective_duration_ms = original_duration_ms - trim_start_ms - trim_end_ms
-            
+
            # Slice audio based on trim values
            trim_start_sample = int((trim_start_ms / 1000.0) * sample_rate)
            trim_end_sample = int((trim_end_ms / 1000.0) * sample_rate)
-            
+
            # Extract the trimmed portion
            if trim_end_ms > 0:
-                trimmed_audio = audio[trim_start_sample:-trim_end_sample] if trim_end_sample > 0 else audio[trim_start_sample:]
+                trimmed_audio = (
+                    audio[trim_start_sample:-trim_end_sample] if trim_end_sample > 0 else audio[trim_start_sample:]
+                )
            else:
                trimmed_audio = audio[trim_start_sample:]
-            
+
            # Store audio with its timecode info
            start_time_ms = item.start_time_ms
-            
-            audio_data.append({
-                'audio': trimmed_audio,
-                'start_time_ms': start_time_ms,
-                'duration_ms': effective_duration_ms,
-            })
+
+            audio_data.append(
+                {
+                    "audio": trimmed_audio,
+                    "start_time_ms": start_time_ms,
+                    "duration_ms": effective_duration_ms,
+                }
+            )
        except Exception:
            # Skip files that can't be loaded
            continue
@@ -861,33 +872,30 @@ async def export_story_audio(
        return None

    # Calculate total duration: max(start_time_ms + duration_ms)
-    max_end_time_ms = max(
-        (data['start_time_ms'] + data['duration_ms'] for data in audio_data),
-        default=0
-    )
-    
+    max_end_time_ms = max((data["start_time_ms"] + data["duration_ms"] for data in audio_data), default=0)
+
    # Convert to samples
    total_samples = int((max_end_time_ms / 1000.0) * sample_rate)
-    
+
    # Create output buffer initialized to zeros
    final_audio = np.zeros(total_samples, dtype=np.float32)

    # Mix each audio segment at its timecode position
    for data in audio_data:
-        audio = data['audio']
-        start_time_ms = data['start_time_ms']
-        
+        audio = data["audio"]
+        start_time_ms = data["start_time_ms"]
+
        # Calculate start sample index
        start_sample = int((start_time_ms / 1000.0) * sample_rate)
-        
+
        # Ensure we don't exceed buffer bounds
        audio_length = len(audio)
        end_sample = min(start_sample + audio_length, total_samples)
-        
+
        if start_sample < total_samples:
            # Trim audio if it extends beyond buffer
-            audio_to_mix = audio[:end_sample - start_sample]
-            
+            audio_to_mix = audio[: end_sample - start_sample]
+
            # Mix: add audio to existing buffer (overlapping audio will sum)
            # Normalize to prevent clipping (simple approach: divide by max)
            final_audio[start_sample:end_sample] += audio_to_mix
@@ -898,14 +906,14 @@ async def export_story_audio(
        final_audio = final_audio / max_val

    # Save to temporary file
-    with tempfile.NamedTemporaryFile(suffix='.wav', delete=False) as tmp:
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
        tmp_path = tmp.name

    try:
        save_audio(final_audio, tmp_path, sample_rate)

        # Read file bytes
-        with open(tmp_path, 'rb') as f:
+        with open(tmp_path, "rb") as f:
            audio_bytes = f.read()

        return audio_bytes
@@ -0,0 +1,48 @@
+"""
+Serial generation queue — ensures only one TTS inference runs at a time
+to avoid GPU contention.
+"""
+
+import asyncio
+import traceback
+
+# Keep references to fire-and-forget background tasks to prevent GC
+_background_tasks: set = set()
+
+# Generation queue — serializes TTS inference to avoid GPU contention
+_generation_queue: asyncio.Queue = None  # type: ignore  # initialized at startup
+
+
+def create_background_task(coro) -> asyncio.Task:
+    """Create a background task and prevent it from being garbage collected."""
+    task = asyncio.create_task(coro)
+    _background_tasks.add(task)
+    task.add_done_callback(_background_tasks.discard)
+    return task
+
+
+async def _generation_worker():
+    """Worker that processes generation tasks one at a time."""
+    while True:
+        coro = await _generation_queue.get()
+        try:
+            await coro
+        except Exception:
+            traceback.print_exc()
+        finally:
+            _generation_queue.task_done()
+
+
+def enqueue_generation(coro):
+    """Add a generation coroutine to the serial queue."""
+    _generation_queue.put_nowait(coro)
+
+
+def init_queue():
+    """Initialize the generation queue and start the worker.
+
+    Must be called once during application startup (inside a running event loop).
+    """
+    global _generation_queue
+    _generation_queue = asyncio.Queue()
+    create_background_task(_generation_worker())
@@ -3,7 +3,7 @@ STT (Speech-to-Text) module - delegates to backend abstraction layer.
 """

 from typing import Optional
-from .backends import get_stt_backend, STTBackend
+from ..backends import get_stt_backend, STTBackend


 def get_whisper_model() -> STTBackend:
@@ -7,7 +7,7 @@ import numpy as np
 import io
 import soundfile as sf

-from .backends import get_tts_backend, TTSBackend
+from ..backends import get_tts_backend, TTSBackend


 def get_tts_model() -> TTSBackend:
@@ -14,12 +14,12 @@ from typing import List, Optional

 from sqlalchemy.orm import Session

-from .database import (
+from ..database import (
    GenerationVersion as DBGenerationVersion,
    Generation as DBGeneration,
 )
-from .models import GenerationVersionResponse, EffectConfig
-from . import config
+from ..models import GenerationVersionResponse, EffectConfig
+from .. import config


 def _version_response(v: DBGenerationVersion) -> GenerationVersionResponse:
@@ -1,66 +0,0 @@
-"""
-Audio studio module for timeline editing.
-"""
-
-from typing import List, Dict, Optional
-import numpy as np
-
-
-class AudioStudio:
-    """Audio editing and timeline management."""
-    
-    async def get_word_timestamps(
-        self,
-        audio_path: str,
-        text: str,
-    ) -> List[Dict[str, float]]:
-        """
-        Get word-level timestamps for audio.
-        
-        Args:
-            audio_path: Path to audio file
-            text: Corresponding text
-            
-        Returns:
-            List of word timestamps: [{"word": "...", "start": 0.0, "end": 0.5}, ...]
-        """
-        # TODO: Implement Whisper alignment
-        raise NotImplementedError("Word timestamps not yet implemented")
-    
-    async def mix_audio(
-        self,
-        audio_paths: List[str],
-        volumes: Optional[List[float]] = None,
-    ) -> bytes:
-        """
-        Mix multiple audio files together.
-        
-        Args:
-            audio_paths: List of audio file paths
-            volumes: Optional volume levels (0.0-1.0) for each track
-            
-        Returns:
-            Mixed audio bytes (WAV format)
-        """
-        # TODO: Implement audio mixing
-        raise NotImplementedError("Audio mixing not yet implemented")
-    
-    async def trim_audio(
-        self,
-        audio_path: str,
-        start: float,
-        end: float,
-    ) -> bytes:
-        """
-        Trim audio to specified time range.
-        
-        Args:
-            audio_path: Path to audio file
-            start: Start time in seconds
-            end: End time in seconds
-            
-        Returns:
-            Trimmed audio bytes (WAV format)
-        """
-        # TODO: Implement audio trimming
-        raise NotImplementedError("Audio trimming not yet implemented")
@@ -37,11 +37,10 @@ async def monitor_sse_stream(model_name: str, timeout: int = 120):
                    if line.startswith("data: "):
                        try:
                            data = json.loads(line[6:])
-                            print(f"[{timestamp}] → SSE Event: {data['status']:12} {data.get('progress', 0):6.1f}% {data.get('filename', '')}")
-                            events.append({
-                                **data,
-                                "_timestamp": timestamp
-                            })
+                            print(
+                                f"[{timestamp}] → SSE Event: {data['status']:12} {data.get('progress', 0):6.1f}% {data.get('filename', '')}"
+                            )
+                            events.append({**data, "_timestamp": timestamp})

                            # Stop if complete or error
                            if data.get("status") in ("complete", "error"):
@@ -74,12 +73,15 @@ async def trigger_generation(profile_id: str, text: str, model_size: str = "1.7B

    try:
        async with httpx.AsyncClient(timeout=120) as client:
-            response = await client.post(url, json={
-                "profile_id": profile_id,
-                "text": text,
-                "language": "en",
-                "model_size": model_size,
-            })
+            response = await client.post(
+                url,
+                json={
+                    "profile_id": profile_id,
+                    "text": text,
+                    "language": "en",
+                    "model_size": model_size,
+                },
+            )

            print(f"[{_timestamp()}] Response: {response.status_code}")

@@ -140,7 +142,7 @@ def _timestamp():
 async def test_generation_with_cached_model():
    """
    Test Case 1: Generation when model is already cached.
-    
+
    This should NOT show any download progress events.
    If it does, that's the UX bug we're trying to fix.
    """
@@ -194,7 +196,7 @@ async def test_generation_with_cached_model():
 async def test_generation_with_fresh_download():
    """
    Test Case 2: Generation when model needs to be downloaded.
-    
+
    This SHOULD show download progress events.
    """
    print("\n" + "=" * 80)
@@ -292,24 +294,6 @@ async def main():
        print("  Users see progress events even when the model is already cached,")
        print("  making them think the model is downloading again.")

-    # Test Case 2: Fresh download (optional, commented out by default)
-    # Uncomment if you want to test download progress
-    # print("\n" + "🧪 " * 20)
-    # events_download = await test_generation_with_fresh_download()
-    #
-    # print("\n" + "=" * 80)
-    # print("TEST CASE 2 RESULTS: Generation with Model Download")
-    # print("=" * 80)
-    #
-    # if not events_download:
-    #     print("ℹ Model was already cached, no download occurred")
-    # else:
-    #     print(f"✓ Received {len(events_download)} download progress events")
-    #     print("\nDownload Timeline:")
-    #     for i, event in enumerate(events_download, 1):
-    #         timestamp = event.pop("_timestamp", "??:??:??.???")
-    #         print(f"  {i}. [{timestamp}] {event}")
-
    print("\n" + "=" * 80)
    print("Test Complete!")
    print("=" * 80)
@@ -45,8 +45,8 @@ def test_db():
@pytest.fixture
 def mock_profiles_dir(monkeypatch, tmp_path):
    """Mock the profiles directory to use a temporary path."""
-    import profiles
-    monkeypatch.setattr(profiles, '_get_profiles_dir', lambda: tmp_path)
+    from backend import config
+    monkeypatch.setattr(config, 'get_profiles_dir', lambda: tmp_path)
    return tmp_path


@@ -3,12 +3,15 @@ Voice prompt caching utilities.
 """

 import hashlib
+import logging
 import torch
 from pathlib import Path
 from typing import Optional, Union, Dict, Any

 from .. import config

+logger = logging.getLogger(__name__)
+

 def _get_cache_dir() -> Path:
    """Get cache directory from config."""
@@ -93,17 +96,17 @@ def cache_voice_prompt(
 def clear_voice_prompt_cache() -> int:
    """
    Clear all voice prompt caches (memory and disk).
-    
+
    Returns:
        Number of cache files deleted
    """
    # Clear memory cache
    _memory_cache.clear()
-    
+
    # Clear disk cache
    cache_dir = _get_cache_dir()
    deleted_count = 0
-    
+
    if cache_dir.exists():
        # Delete prompt cache files
        for cache_file in cache_dir.glob("*.prompt"):
@@ -111,32 +114,32 @@ def clear_voice_prompt_cache() -> int:
                cache_file.unlink()
                deleted_count += 1
            except Exception as e:
-                print(f"Failed to delete cache file {cache_file}: {e}")
-        
+                logger.warning("Failed to delete cache file %s: %s", cache_file, e)
+
        # Delete combined audio files
        for audio_file in cache_dir.glob("combined_*.wav"):
            try:
                audio_file.unlink()
                deleted_count += 1
            except Exception as e:
-                print(f"Failed to delete combined audio file {audio_file}: {e}")
-    
+                logger.warning("Failed to delete combined audio file %s: %s", audio_file, e)
+
    return deleted_count


 def clear_profile_cache(profile_id: str) -> int:
    """
    Clear cache files for a specific profile.
-    
+
    Args:
        profile_id: Profile ID
-    
+
    Returns:
        Number of cache files deleted
    """
    cache_dir = _get_cache_dir()
    deleted_count = 0
-    
+
    if cache_dir.exists():
        # Delete combined audio files for this profile
        pattern = f"combined_{profile_id}_*.wav"
@@ -145,6 +148,6 @@ def clear_profile_cache(profile_id: str) -> int:
                audio_file.unlink()
                deleted_count += 1
            except Exception as e:
-                print(f"Failed to delete combined audio file {audio_file}: {e}")
-    
+                logger.warning("Failed to delete combined audio file %s: %s", audio_file, e)
+
    return deleted_count
@@ -58,11 +58,6 @@ _ABBREVIATIONS = frozenset(
 _PARA_TAG_RE = re.compile(r"\[[^\]]*\]")


-# ---------------------------------------------------------------------------
-# Text splitting
-# ---------------------------------------------------------------------------
-
-
 def split_text_into_chunks(text: str, max_chars: int = DEFAULT_MAX_CHUNK_CHARS) -> List[str]:
    """Split *text* at natural boundaries into chunks of at most *max_chars*.

@@ -174,11 +169,6 @@ def _safe_hard_cut(segment: str, max_chars: int) -> int:
    return cut


-# ---------------------------------------------------------------------------
-# Audio concatenation
-# ---------------------------------------------------------------------------
-
-
 def concatenate_audio_chunks(
    chunks: List[np.ndarray],
    sample_rate: int,
@@ -211,11 +201,6 @@ def concatenate_audio_chunks(
    return result


-# ---------------------------------------------------------------------------
-# Engine-agnostic chunked generation
-# ---------------------------------------------------------------------------
-
-
 async def generate_chunked(
    backend,
    text: str,
@@ -264,7 +249,11 @@ async def generate_chunked(
    if len(chunks) <= 1:
        # Short text — single-shot fast path
        audio, sample_rate = await backend.generate(
-            text, voice_prompt, language, seed, instruct,
+            text,
+            voice_prompt,
+            language,
+            seed,
+            instruct,
        )
        if trim_fn is not None:
            audio = trim_fn(audio, sample_rate)
@@ -273,7 +262,9 @@ async def generate_chunked(
    # Long text — chunked generation
    logger.info(
        "Splitting %d chars into %d chunks (max %d chars each)",
-        len(text), len(chunks), max_chunk_chars,
+        len(text),
+        len(chunks),
+        max_chunk_chars,
    )
    audio_chunks: List[np.ndarray] = []
    sample_rate: int | None = None
@@ -281,7 +272,9 @@ async def generate_chunked(
    for i, chunk_text in enumerate(chunks):
        logger.info(
            "Generating chunk %d/%d (%d chars)",
-            i + 1, len(chunks), len(chunk_text),
+            i + 1,
+            len(chunks),
+            len(chunk_text),
        )
        # Vary the seed per chunk to avoid correlated RNG artefacts,
        # but keep it deterministic so the same (text, seed) pair
@@ -289,7 +282,11 @@ async def generate_chunked(
        chunk_seed = (seed + i) if seed is not None else None

        chunk_audio, chunk_sr = await backend.generate(
-            chunk_text, voice_prompt, language, chunk_seed, instruct,
+            chunk_text,
+            voice_prompt,
+            language,
+            chunk_seed,
+            instruct,
        )
        if trim_fn is not None:
            chunk_audio = trim_fn(chunk_audio, chunk_sr)
@@ -35,10 +35,6 @@ from pedalboard import (
 )


-# ---------------------------------------------------------------------------
-# Effect registry: maps type names -> (pedalboard class, param definitions)
-# ---------------------------------------------------------------------------
-
 # Each param definition: (default, min, max, description)
 EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
    "chorus": {
@@ -46,11 +42,17 @@ EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
        "label": "Chorus / Flanger",
        "description": "Modulated delay for flanging or chorus effects. Short centre_delay_ms (<10) gives flanger; longer gives chorus.",
        "params": {
-            "rate_hz":          {"default": 1.0,  "min": 0.01, "max": 20.0,  "step": 0.01, "description": "LFO speed (Hz)"},
-            "depth":            {"default": 0.5,  "min": 0.0,  "max": 1.0,   "step": 0.01, "description": "Modulation depth"},
-            "feedback":         {"default": 0.0,  "min": 0.0,  "max": 0.95,  "step": 0.01, "description": "Feedback amount"},
-            "centre_delay_ms":  {"default": 7.0,  "min": 0.5,  "max": 50.0,  "step": 0.1,  "description": "Centre delay (ms)"},
-            "mix":              {"default": 0.5,  "min": 0.0,  "max": 1.0,   "step": 0.01, "description": "Wet/dry mix"},
+            "rate_hz": {"default": 1.0, "min": 0.01, "max": 20.0, "step": 0.01, "description": "LFO speed (Hz)"},
+            "depth": {"default": 0.5, "min": 0.0, "max": 1.0, "step": 0.01, "description": "Modulation depth"},
+            "feedback": {"default": 0.0, "min": 0.0, "max": 0.95, "step": 0.01, "description": "Feedback amount"},
+            "centre_delay_ms": {
+                "default": 7.0,
+                "min": 0.5,
+                "max": 50.0,
+                "step": 0.1,
+                "description": "Centre delay (ms)",
+            },
+            "mix": {"default": 0.5, "min": 0.0, "max": 1.0, "step": 0.01, "description": "Wet/dry mix"},
        },
    },
    "reverb": {
@@ -58,11 +60,11 @@ EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
        "label": "Reverb",
        "description": "Room reverb effect.",
        "params": {
-            "room_size":  {"default": 0.5,  "min": 0.0,  "max": 1.0,  "step": 0.01, "description": "Room size"},
-            "damping":    {"default": 0.5,  "min": 0.0,  "max": 1.0,  "step": 0.01, "description": "High frequency damping"},
-            "wet_level":  {"default": 0.33, "min": 0.0,  "max": 1.0,  "step": 0.01, "description": "Wet level"},
-            "dry_level":  {"default": 0.4,  "min": 0.0,  "max": 1.0,  "step": 0.01, "description": "Dry level"},
-            "width":      {"default": 1.0,  "min": 0.0,  "max": 1.0,  "step": 0.01, "description": "Stereo width"},
+            "room_size": {"default": 0.5, "min": 0.0, "max": 1.0, "step": 0.01, "description": "Room size"},
+            "damping": {"default": 0.5, "min": 0.0, "max": 1.0, "step": 0.01, "description": "High frequency damping"},
+            "wet_level": {"default": 0.33, "min": 0.0, "max": 1.0, "step": 0.01, "description": "Wet level"},
+            "dry_level": {"default": 0.4, "min": 0.0, "max": 1.0, "step": 0.01, "description": "Dry level"},
+            "width": {"default": 1.0, "min": 0.0, "max": 1.0, "step": 0.01, "description": "Stereo width"},
        },
    },
    "delay": {
@@ -70,9 +72,15 @@ EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
        "label": "Delay",
        "description": "Echo / delay line.",
        "params": {
-            "delay_seconds": {"default": 0.3,  "min": 0.01, "max": 2.0,  "step": 0.01, "description": "Delay time (seconds)"},
-            "feedback":      {"default": 0.3,  "min": 0.0,  "max": 0.95, "step": 0.01, "description": "Feedback amount"},
-            "mix":           {"default": 0.3,  "min": 0.0,  "max": 1.0,  "step": 0.01, "description": "Wet/dry mix"},
+            "delay_seconds": {
+                "default": 0.3,
+                "min": 0.01,
+                "max": 2.0,
+                "step": 0.01,
+                "description": "Delay time (seconds)",
+            },
+            "feedback": {"default": 0.3, "min": 0.0, "max": 0.95, "step": 0.01, "description": "Feedback amount"},
+            "mix": {"default": 0.3, "min": 0.0, "max": 1.0, "step": 0.01, "description": "Wet/dry mix"},
        },
    },
    "compressor": {
@@ -80,10 +88,16 @@ EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
        "label": "Compressor",
        "description": "Dynamic range compression for consistent loudness.",
        "params": {
-            "threshold_db": {"default": -20.0, "min": -60.0, "max": 0.0,   "step": 0.5, "description": "Threshold (dB)"},
-            "ratio":        {"default": 4.0,   "min": 1.0,   "max": 20.0,  "step": 0.1, "description": "Compression ratio"},
-            "attack_ms":    {"default": 10.0,  "min": 0.1,   "max": 100.0, "step": 0.1, "description": "Attack time (ms)"},
-            "release_ms":   {"default": 100.0, "min": 10.0,  "max": 1000.0,"step": 1.0, "description": "Release time (ms)"},
+            "threshold_db": {"default": -20.0, "min": -60.0, "max": 0.0, "step": 0.5, "description": "Threshold (dB)"},
+            "ratio": {"default": 4.0, "min": 1.0, "max": 20.0, "step": 0.1, "description": "Compression ratio"},
+            "attack_ms": {"default": 10.0, "min": 0.1, "max": 100.0, "step": 0.1, "description": "Attack time (ms)"},
+            "release_ms": {
+                "default": 100.0,
+                "min": 10.0,
+                "max": 1000.0,
+                "step": 1.0,
+                "description": "Release time (ms)",
+            },
        },
    },
    "gain": {
@@ -99,7 +113,13 @@ EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
        "label": "High-Pass Filter",
        "description": "Removes frequencies below the cutoff.",
        "params": {
-            "cutoff_frequency_hz": {"default": 80.0, "min": 20.0, "max": 8000.0, "step": 1.0, "description": "Cutoff frequency (Hz)"},
+            "cutoff_frequency_hz": {
+                "default": 80.0,
+                "min": 20.0,
+                "max": 8000.0,
+                "step": 1.0,
+                "description": "Cutoff frequency (Hz)",
+            },
        },
    },
    "lowpass": {
@@ -107,7 +127,13 @@ EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
        "label": "Low-Pass Filter",
        "description": "Removes frequencies above the cutoff.",
        "params": {
-            "cutoff_frequency_hz": {"default": 8000.0, "min": 200.0, "max": 20000.0, "step": 1.0, "description": "Cutoff frequency (Hz)"},
+            "cutoff_frequency_hz": {
+                "default": 8000.0,
+                "min": 200.0,
+                "max": 20000.0,
+                "step": 1.0,
+                "description": "Cutoff frequency (Hz)",
+            },
        },
    },
    "pitch_shift": {
@@ -121,10 +147,6 @@ EFFECT_REGISTRY: Dict[str, Dict[str, Any]] = {
 }


-# ---------------------------------------------------------------------------
-# Built-in presets
-# ---------------------------------------------------------------------------
-
 BUILTIN_PRESETS: Dict[str, Dict[str, Any]] = {
    "robotic": {
        "name": "Robotic",
@@ -233,10 +255,6 @@ BUILTIN_PRESETS: Dict[str, Dict[str, Any]] = {
 }


-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
 def get_available_effects() -> List[Dict[str, Any]]:
    """Return the list of available effect types with their parameter definitions.

@@ -244,15 +262,14 @@ def get_available_effects() -> List[Dict[str, Any]]:
    """
    result = []
    for effect_type, info in EFFECT_REGISTRY.items():
-        result.append({
-            "type": effect_type,
-            "label": info["label"],
-            "description": info["description"],
-            "params": {
-                name: {k: v for k, v in pdef.items()}
-                for name, pdef in info["params"].items()
-            },
-        })
+        result.append(
+            {
+                "type": effect_type,
+                "label": info["label"],
+                "description": info["description"],
+                "params": {name: {k: v for k, v in pdef.items()} for name, pdef in info["params"].items()},
+            }
+        )
    return result


@@ -1,26 +1,26 @@
-"""
-Monkey patch for huggingface_hub to force offline mode with cached models.
-This prevents mlx_audio from making network requests when models are already downloaded.
+"""Monkey-patch huggingface_hub to force offline mode with cached models.
+
+Prevents mlx_audio from making network requests when models are already
+downloaded. Must be imported BEFORE mlx_audio.
 """

+import logging
 import os
 from pathlib import Path
 from typing import Optional, Union

+logger = logging.getLogger(__name__)
+

 def patch_huggingface_hub_offline():
-    """
-    Monkey-patch huggingface_hub to force offline mode.
-    This must be called BEFORE importing mlx_audio.
-    """
+    """Monkey-patch huggingface_hub to force offline mode."""
    try:
-        import huggingface_hub
+        import huggingface_hub  # noqa: F401 -- need the package loaded
        from huggingface_hub import constants as hf_constants
        from huggingface_hub.file_download import _try_to_load_from_cache
-        
-        # Store original function
+
        original_try_load = _try_to_load_from_cache
-        
+
        def _patched_try_to_load_from_cache(
            repo_id: str,
            filename: str,
@@ -28,11 +28,6 @@ def patch_huggingface_hub_offline():
            revision: Optional[str] = None,
            repo_type: Optional[str] = None,
        ):
-            """
-            Patched version that forces offline mode.
-            Returns None if not cached (instead of making network request).
-            """
-            # Always use the original function, but we're already in HF_HUB_OFFLINE mode
            result = original_try_load(
                repo_id=repo_id,
                filename=filename,
@@ -40,61 +35,54 @@ def patch_huggingface_hub_offline():
                revision=revision,
                repo_type=repo_type,
            )
-            
+
            if result is None:
-                # File not in cache - log this for debugging
                cache_path = Path(hf_constants.HF_HUB_CACHE) / f"models--{repo_id.replace('/', '--')}"
-                print(f"[HF_PATCH] File not cached: {repo_id}/{filename}")
-                print(f"[HF_PATCH] Expected at: {cache_path}")
+                logger.debug("file not cached: %s/%s (expected at %s)", repo_id, filename, cache_path)
            else:
-                print(f"[HF_PATCH] Cache hit: {repo_id}/{filename}")
-            
+                logger.debug("cache hit: %s/%s", repo_id, filename)
+
            return result
-        
-        # Replace the function
+
        import huggingface_hub.file_download as fd
+
        fd._try_to_load_from_cache = _patched_try_to_load_from_cache
-        
-        print("[HF_PATCH] huggingface_hub patched for offline mode")
-        
+        logger.debug("huggingface_hub patched for offline mode")
+
    except ImportError:
-        print("[HF_PATCH] huggingface_hub not found, skipping patch")
-    except Exception as e:
-        print(f"[HF_PATCH] Error patching huggingface_hub: {e}")
+        logger.debug("huggingface_hub not available, skipping offline patch")
+    except Exception:
+        logger.exception("failed to patch huggingface_hub for offline mode")


 def ensure_original_qwen_config_cached():
+    """Symlink the original Qwen repo cache to the MLX community version.
+
+    mlx_audio may try to fetch config from the original Qwen repo. If only
+    the MLX community variant is cached, create a symlink so the cache lookup
+    succeeds without a network request.
    """
-    The MLX community model is based on the original Qwen model.
-    mlx_audio may try to fetch config from the original repo.
-    We need to ensure that config is available in the cache.
-    """
-    from huggingface_hub import constants as hf_constants
-    
-    # Original Qwen model that mlx_audio might reference
+    try:
+        from huggingface_hub import constants as hf_constants
+    except ImportError:
+        return
+
    original_repo = "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
    mlx_repo = "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16"
-    
+
    cache_dir = Path(hf_constants.HF_HUB_CACHE)
-    
    original_path = cache_dir / f"models--{original_repo.replace('/', '--')}"
    mlx_path = cache_dir / f"models--{mlx_repo.replace('/', '--')}"
-    
-    # If original repo cache doesn't exist but MLX does, create a symlink or copy config
+
    if not original_path.exists() and mlx_path.exists():
-        print(f"[HF_PATCH] Original repo not cached, but MLX version is")
-        print(f"[HF_PATCH] Creating symlink from {original_repo} -> {mlx_repo}")
-        
        try:
-            # Create a symlink so the cache lookup succeeds
            original_path.parent.mkdir(parents=True, exist_ok=True)
            original_path.symlink_to(mlx_path, target_is_directory=True)
-            print(f"[HF_PATCH] Symlink created successfully")
-        except Exception as e:
-            print(f"[HF_PATCH] Could not create symlink: {e}")
+            logger.info("created cache symlink: %s -> %s", original_repo, mlx_repo)
+        except Exception:
+            logger.warning("could not create cache symlink for %s", original_repo, exc_info=True)


-# Auto-apply patch when module is imported
 if os.environ.get("VOICEBOX_OFFLINE_PATCH", "1") != "0":
    patch_huggingface_hub_offline()
    ensure_original_qwen_config_cached()
@@ -4,13 +4,16 @@ HuggingFace Hub download progress tracking.

 from typing import Optional, Callable
 from contextlib import contextmanager
+import logging
 import threading
 import sys

+logger = logging.getLogger(__name__)
+

 class HFProgressTracker:
    """Tracks HuggingFace Hub download progress by intercepting tqdm."""
-    
+
    def __init__(self, progress_callback: Optional[Callable] = None, filter_non_downloads: bool = False):
        self.progress_callback = progress_callback
        self.filter_non_downloads = filter_non_downloads  # Only filter if True
@@ -23,12 +26,12 @@ class HFProgressTracker:
        self._current_filename = ""
        self._active_tqdms = {}  # Track active tqdm instances
        self._hf_tqdm_original_update = None  # For monkey-patching hf's tqdm
-    
+
    def _create_tracked_tqdm_class(self):
        """Create a tqdm subclass that tracks progress."""
        tracker = self
        original_tqdm = self._original_tqdm_class
-        
+
        class TrackedTqdm(original_tqdm):
            """A tqdm subclass that reports progress to our tracker."""

@@ -39,7 +42,7 @@ class HFProgressTracker:
                    first_arg = args[0]
                    if isinstance(first_arg, str):
                        desc = first_arg
-                
+
                filename = ""
                if desc:
                    # Try to extract filename from description
@@ -48,38 +51,68 @@ class HFProgressTracker:
                        filename = desc.split(":")[0].strip()
                    else:
                        filename = desc.strip()
-                
+
                # Filter out non-standard kwargs that huggingface_hub might pass
                # These are custom kwargs that tqdm doesn't understand
                filtered_kwargs = {}
                # Known tqdm kwargs - pass these through
                tqdm_kwargs = {
-                    'iterable', 'desc', 'total', 'leave', 'file', 'ncols', 'mininterval',
-                    'maxinterval', 'miniters', 'ascii', 'disable', 'unit', 'unit_scale',
-                    'dynamic_ncols', 'smoothing', 'bar_format', 'initial', 'position',
-                    'postfix', 'unit_divisor', 'write_bytes', 'lock_args', 'nrows',
-                    'colour', 'color', 'delay', 'gui', 'disable_default', 'pos'
+                    "iterable",
+                    "desc",
+                    "total",
+                    "leave",
+                    "file",
+                    "ncols",
+                    "mininterval",
+                    "maxinterval",
+                    "miniters",
+                    "ascii",
+                    "disable",
+                    "unit",
+                    "unit_scale",
+                    "dynamic_ncols",
+                    "smoothing",
+                    "bar_format",
+                    "initial",
+                    "position",
+                    "postfix",
+                    "unit_divisor",
+                    "write_bytes",
+                    "lock_args",
+                    "nrows",
+                    "colour",
+                    "color",
+                    "delay",
+                    "gui",
+                    "disable_default",
+                    "pos",
                }
                for key, value in kwargs.items():
                    if key in tqdm_kwargs:
                        filtered_kwargs[key] = value
-                
+
+                # Force-enable the progress bar — we're tracking progress ourselves,
+                # we don't need tqdm to render to a terminal, but we DO need
+                # self.n to be updated when update() is called.
+                filtered_kwargs["disable"] = False
+
                # Try to initialize with filtered kwargs, fall back to all kwargs if that fails
                try:
                    super().__init__(*args, **filtered_kwargs)
                except TypeError:
                    # If filtering failed, try with all kwargs (maybe tqdm version accepts them)
+                    kwargs["disable"] = False
                    super().__init__(*args, **kwargs)
-                
+
                self._tracker_filename = filename or "unknown"
-                
+
                with tracker._lock:
                    if filename:
                        tracker._current_filename = filename
                    tracker._active_tqdms[id(self)] = {
                        "filename": self._tracker_filename,
                    }
-            
+
            def update(self, n=1):
                result = super().update(n)

@@ -89,95 +122,97 @@ class HFProgressTracker:
                        filename = tracker._active_tqdms[id(self)]["filename"]
                        current = getattr(self, "n", 0)
                        total = getattr(self, "total", 0)
-                        
+
                        if total and total > 0:
                            # Always filter out non-byte progress bars (e.g., "Fetching 12 files")
                            # These cause crazy percentages because they're counting files, not bytes
                            if self._is_non_byte_progress(filename):
                                return result
-                            
+
                            # When model is cached, also filter out generation-related progress
                            if tracker.filter_non_downloads:
                                if not self._is_download_progress(filename):
                                    return result
-                            
+
                            # Update per-file tracking
                            tracker._file_sizes[filename] = total
                            tracker._file_downloaded[filename] = current
-                            
+
                            # Calculate totals across all files
                            tracker._total_size = sum(tracker._file_sizes.values())
                            tracker._total_downloaded = sum(tracker._file_downloaded.values())
-                            
+
                            # Only report progress once we have a meaningful total (at least 1MB)
                            # This avoids the "100% at 0MB" issue when small config
                            # files are counted before the real model files
                            MIN_TOTAL_BYTES = 1_000_000  # 1MB
                            if tracker._total_size < MIN_TOTAL_BYTES:
                                return result
-                            
+
                            # Call progress callback
                            if tracker.progress_callback:
-                                tracker.progress_callback(
-                                    tracker._total_downloaded,
-                                    tracker._total_size,
-                                    filename
-                                )
-                
+                                tracker.progress_callback(tracker._total_downloaded, tracker._total_size, filename)
+
                return result
-            
+
            def _is_non_byte_progress(self, filename: str) -> bool:
                """Check if this progress bar should be SKIPPED (returns True to skip).
-                
+
                We want to track byte-based progress bars. This method identifies
                progress bars that count files/items instead of bytes, which would
                cause crazy percentages if mixed with our byte counting.
-                
+
                Returns:
                    True = SKIP this bar (it's not byte-based)
                    False = TRACK this bar (it counts bytes)
                """
                if not filename:
                    return False
-                
+
                filename_lower = filename.lower()
-                
+
                # Skip "Fetching X files" - it counts files (total=12), not bytes
                # Don't skip "Downloading (incomplete total...)" - that IS byte-based
                skip_patterns = [
-                    'fetching',  # "Fetching 12 files" has total=12 files, not bytes
+                    "fetching",  # "Fetching 12 files" has total=12 files, not bytes
                ]
                return any(pattern in filename_lower for pattern in skip_patterns)
-            
+
            def _is_download_progress(self, filename: str) -> bool:
                """Check if this is a real file download progress bar vs internal processing."""
                if not filename or filename == "unknown":
                    return False
-                
+
                # Real downloads have file extensions
                download_extensions = [
-                    '.safetensors', '.bin', '.pt', '.pth',  # Model weights
-                    '.json', '.txt', '.py',  # Config files
-                    '.msgpack', '.h5',  # Other formats
+                    ".safetensors",
+                    ".bin",
+                    ".pt",
+                    ".pth",  # Model weights
+                    ".json",
+                    ".txt",
+                    ".py",  # Config files
+                    ".msgpack",
+                    ".h5",  # Other formats
                ]
-                
+
                filename_lower = filename.lower()
                has_extension = any(filename_lower.endswith(ext) for ext in download_extensions)
-                
+
                # Skip generation-related progress indicators
-                skip_patterns = ['segment', 'processing', 'generating', 'loading']
+                skip_patterns = ["segment", "processing", "generating", "loading"]
                has_skip_pattern = any(pattern in filename_lower for pattern in skip_patterns)
-                
+
                return has_extension and not has_skip_pattern
-            
+
            def close(self):
                with tracker._lock:
                    if id(self) in tracker._active_tqdms:
                        del tracker._active_tqdms[id(self)]
                return super().close()
-        
+
        return TrackedTqdm
-    
+
    @contextmanager
    def patch_download(self):
        """Context manager to patch tqdm for progress tracking."""
@@ -186,7 +221,7 @@ class HFProgressTracker:

            # Store original tqdm class
            self._original_tqdm_class = tqdm_module.tqdm
-            
+
            # Reset totals
            with self._lock:
                self._total_downloaded = 0
@@ -195,7 +230,7 @@ class HFProgressTracker:
                self._file_downloaded = {}
                self._current_filename = ""
                self._active_tqdms = {}
-            
+
            # Create our tracked tqdm class
            tracked_tqdm = self._create_tracked_tqdm_class()

@@ -207,13 +242,13 @@ class HFProgressTracker:
            if hasattr(tqdm_module, "auto") and hasattr(tqdm_module.auto, "tqdm"):
                self._original_tqdm_auto = tqdm_module.auto.tqdm
                tqdm_module.auto.tqdm = tracked_tqdm
-            
+
            # Patch in sys.modules to catch already-imported references
            # huggingface_hub uses: from tqdm.auto import tqdm as base_tqdm
            # So we need to patch both 'tqdm' and 'base_tqdm' attributes
            self._patched_modules = {}
-            tqdm_attr_names = ['tqdm', 'base_tqdm', 'old_tqdm']  # Various names used
-            
+            tqdm_attr_names = ["tqdm", "base_tqdm", "old_tqdm"]  # Various names used
+
            patched_count = 0
            for module_name in list(sys.modules.keys()):
                if "huggingface" in module_name or module_name.startswith("tqdm"):
@@ -224,10 +259,13 @@ class HFProgressTracker:
                                attr = getattr(module, attr_name)
                                # Only patch if it's a tqdm class (not already patched)
                                is_tqdm_class = (
-                                    attr is self._original_tqdm_class or 
-                                    (self._original_tqdm_auto and attr is self._original_tqdm_auto) or
-                                    (hasattr(attr, "__name__") and attr.__name__ == "tqdm" and 
-                                     hasattr(attr, "update"))  # tqdm classes have update method
+                                    attr is self._original_tqdm_class
+                                    or (self._original_tqdm_auto and attr is self._original_tqdm_auto)
+                                    or (
+                                        hasattr(attr, "__name__")
+                                        and attr.__name__ == "tqdm"
+                                        and hasattr(attr, "update")
+                                    )  # tqdm classes have update method
                                )
                                if is_tqdm_class:
                                    key = f"{module_name}.{attr_name}"
@@ -236,31 +274,33 @@ class HFProgressTracker:
                                    patched_count += 1
                    except (AttributeError, TypeError):
                        pass
-            
+
            # ALSO monkey-patch the update method on huggingface_hub's tqdm class
            # This is needed because the class was already defined at import time
            self._hf_tqdm_original_update = None
            try:
                from huggingface_hub.utils import tqdm as hf_tqdm_module
-                if hasattr(hf_tqdm_module, 'tqdm'):
+
+                if hasattr(hf_tqdm_module, "tqdm"):
                    hf_tqdm_class = hf_tqdm_module.tqdm
                    self._hf_tqdm_original_update = hf_tqdm_class.update
-                    
+
                    # Create a wrapper that calls our tracking
                    tracker = self  # Reference to HFProgressTracker instance
+
                    def patched_update(tqdm_self, n=1):
                        result = tracker._hf_tqdm_original_update(tqdm_self, n)
-                        
+
                        # Track this progress
                        with tracker._lock:
-                            desc = getattr(tqdm_self, 'desc', '') or ''
-                            current = getattr(tqdm_self, 'n', 0)
-                            total = getattr(tqdm_self, 'total', 0) or 0
-                            
+                            desc = getattr(tqdm_self, "desc", "") or ""
+                            current = getattr(tqdm_self, "n", 0)
+                            total = getattr(tqdm_self, "total", 0) or 0
+
                            # Skip non-byte progress bars
-                            if 'fetching' in desc.lower():
+                            if "fetching" in desc.lower():
                                return result
-                            
+
                            # Skip until we have a meaningful total (at least 1MB)
                            # This avoids the "100% at 0MB" issue when small config
                            # files are counted before the real model files
@@ -268,22 +308,22 @@ class HFProgressTracker:
                            if total >= MIN_TOTAL_BYTES:
                                tracker._total_downloaded = current
                                tracker._total_size = total
-                                
+
                                if tracker.progress_callback:
                                    tracker.progress_callback(current, total, desc)
-                        
+
                        return result
-                    
+
                    hf_tqdm_class.update = patched_update
                    patched_count += 1
-                    print(f"[HFProgressTracker] Monkey-patched huggingface_hub.utils.tqdm.tqdm.update")
+                    logger.debug("Monkey-patched huggingface_hub.utils.tqdm.tqdm.update")
            except (ImportError, AttributeError) as e:
-                print(f"[HFProgressTracker] Could not monkey-patch hf_tqdm: {e}")
-            
-            print(f"[HFProgressTracker] Patched {patched_count} tqdm references")
-            
+                logger.warning("Could not monkey-patch hf_tqdm: %s", e)
+
+            logger.debug("Patched %d tqdm references", patched_count)
+
            yield
-            
+
        except ImportError:
            # If tqdm not available, just yield without patching
            yield
@@ -292,11 +332,12 @@ class HFProgressTracker:
            if self._original_tqdm_class:
                try:
                    import tqdm as tqdm_module
+
                    tqdm_module.tqdm = self._original_tqdm_class
-                    
+
                    if self._original_tqdm_auto:
                        tqdm_module.auto.tqdm = self._original_tqdm_auto
-                    
+
                    # Restore patched modules
                    for key, (module, attr_name, original) in self._patched_modules.items():
                        try:
@@ -305,26 +346,28 @@ class HFProgressTracker:
                        except (AttributeError, TypeError):
                            pass
                    self._patched_modules = {}
-                    
+
                    # Restore hf_tqdm's original update method
                    if self._hf_tqdm_original_update:
                        try:
                            from huggingface_hub.utils import tqdm as hf_tqdm_module
-                            if hasattr(hf_tqdm_module, 'tqdm'):
+
+                            if hasattr(hf_tqdm_module, "tqdm"):
                                hf_tqdm_module.tqdm.update = self._hf_tqdm_original_update
                        except (ImportError, AttributeError):
                            pass
                        self._hf_tqdm_original_update = None
-                    
+
                except (ImportError, AttributeError):
                    pass


 def create_hf_progress_callback(model_name: str, progress_manager):
    """Create a progress callback for HuggingFace downloads."""
+
    def callback(downloaded: int, total: int, filename: str = ""):
        """Progress callback.
-        
+
        Note: We send updates even when total=0 (unknown) to provide feedback
        during the "incomplete total" phase of huggingface_hub downloads.
        The frontend handles total=0 gracefully.
@@ -336,4 +379,5 @@ def create_hf_progress_callback(model_name: str, progress_manager):
            filename=filename or "",
            status="downloading",
        )
+
    return callback
@@ -1,66 +0,0 @@
-"""
-Input validation utilities.
-"""
-
-from typing import Tuple, Optional
-from pathlib import Path
-
-
-def validate_text(text: str, max_length: int = 5000) -> Tuple[bool, Optional[str]]:
-    """
-    Validate text input.
-    
-    Args:
-        text: Text to validate
-        max_length: Maximum length
-        
-    Returns:
-        Tuple of (is_valid, error_message)
-    """
-    if not text or not text.strip():
-        return False, "Text cannot be empty"
-    
-    if len(text) > max_length:
-        return False, f"Text too long (maximum {max_length} characters)"
-    
-    return True, None
-
-
-def validate_language(language: str) -> Tuple[bool, Optional[str]]:
-    """
-    Validate language code.
-
-    Supported languages for Qwen3-TTS:
-    Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian
-
-    Args:
-        language: Language code
-
-    Returns:
-        Tuple of (is_valid, error_message)
-    """
-    valid_languages = ["zh", "en", "ja", "ko", "de", "fr", "ru", "pt", "es", "it"]
-    if language not in valid_languages:
-        return False, f"Invalid language (must be one of: {', '.join(valid_languages)})"
-
-    return True, None
-
-
-def validate_file_path(path: str) -> Tuple[bool, Optional[str]]:
-    """
-    Validate file path exists.
-    
-    Args:
-        path: File path
-        
-    Returns:
-        Tuple of (is_valid, error_message)
-    """
-    file_path = Path(path)
-    if not file_path.exists():
-        return False, f"File not found: {path}"
-    
-    if not file_path.is_file():
-        return False, f"Path is not a file: {path}"
-    
-    return True, None
@@ -6,13 +6,23 @@ from PyInstaller.utils.hooks import copy_metadata

 datas = []
 binaries = []
-hiddenimports = ['backend', 'backend.main', 'backend.config', 'backend.database', 'backend.models', 'backend.profiles', 'backend.history', 'backend.tts', 'backend.transcribe', 'backend.platform_detect', 'backend.backends', 'backend.backends.pytorch_backend', 'backend.utils.audio', 'backend.utils.cache', 'backend.utils.progress', 'backend.utils.hf_progress', 'backend.utils.validation', 'backend.cuda_download', 'backend.effects', 'backend.utils.effects', 'backend.versions', 'pedalboard', 'torch', 'transformers', 'fastapi', 'uvicorn', 'sqlalchemy', 'librosa', 'soundfile', 'qwen_tts', 'qwen_tts.inference', 'qwen_tts.inference.qwen3_tts_model', 'qwen_tts.inference.qwen3_tts_tokenizer', 'qwen_tts.core', 'qwen_tts.cli', 'pkg_resources.extern', 'backend.backends.mlx_backend', 'mlx', 'mlx.core', 'mlx.nn', 'mlx_audio', 'mlx_audio.tts', 'mlx_audio.stt']
+hiddenimports = ['backend', 'backend.main', 'backend.config', 'backend.database', 'backend.models', 'backend.profiles', 'backend.history', 'backend.tts', 'backend.transcribe', 'backend.platform_detect', 'backend.backends', 'backend.backends.pytorch_backend', 'backend.utils.audio', 'backend.utils.cache', 'backend.utils.progress', 'backend.utils.hf_progress', 'backend.utils.validation', 'backend.cuda_download', 'backend.effects', 'backend.utils.effects', 'backend.versions', 'pedalboard', 'chatterbox', 'chatterbox.tts_turbo', 'chatterbox.mtl_tts', 'backend.backends.chatterbox_backend', 'backend.backends.chatterbox_turbo_backend', 'backend.backends.luxtts_backend', 'zipvoice', 'zipvoice.luxvoice', 'torch', 'transformers', 'fastapi', 'uvicorn', 'sqlalchemy', 'librosa', 'soundfile', 'qwen_tts', 'qwen_tts.inference', 'qwen_tts.inference.qwen3_tts_model', 'qwen_tts.inference.qwen3_tts_tokenizer', 'qwen_tts.core', 'qwen_tts.cli', 'requests', 'pkg_resources.extern', 'backend.backends.mlx_backend', 'mlx', 'mlx.core', 'mlx.nn', 'mlx_audio', 'mlx_audio.tts', 'mlx_audio.stt']
 datas += collect_data_files('qwen_tts')
 datas += copy_metadata('qwen-tts')
+datas += copy_metadata('requests')
+datas += copy_metadata('transformers')
+datas += copy_metadata('huggingface-hub')
+datas += copy_metadata('tokenizers')
+datas += copy_metadata('safetensors')
+datas += copy_metadata('tqdm')
 hiddenimports += collect_submodules('qwen_tts')
 hiddenimports += collect_submodules('jaraco')
 hiddenimports += collect_submodules('mlx')
 hiddenimports += collect_submodules('mlx_audio')
+tmp_ret = collect_all('zipvoice')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
+tmp_ret = collect_all('linacodec')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('mlx')
 datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('mlx_audio')
@@ -1,70 +0,0 @@
-# Accessibility: screen reader and keyboard improvements
-
-## Summary
-
-Improvements to support screen reader and keyboard users across the main app surfaces: audio player, generation UI, voice selection, history, voices tab, model management, server tab, and stories.
-
-**Tested with NVDA and Narrator on Windows.**
-
---
-
-## What changed
-
-### Audio player (after generating audio)
-
- **Play/Pause, Loop, Mute, Close** – `aria-label` added so each control is announced (e.g. "Play", "Pause", "Loop", "Mute", "Close player").
- **Playback position slider** – `aria-label="Playback position"` and `aria-valuetext` with current/total time (e.g. "0:30 of 2:15").
- **Volume** – Wrapped in a labelled group; volume slider has an associated screen-reader-only label and `aria-valuetext` for the level (e.g. "Volume level, 75%").
-
-### Generation UI (text box and voice choice)
-
- **Generate speech** (submit) and **Fine-tune instructions** (sliders) – Icon buttons now have `aria-label` (and state for fine-tune, e.g. "Fine-tune instructions, on").
-
-### Voice selection (cards on Generate screen)
-
- Each **voice card** is focusable (`tabIndex={0}`), has `role="button"`, and an `aria-label` (e.g. "Prashant, en. Select as voice for generation.") with `aria-pressed` when selected.
- **Enter/Space** on the card selects that voice; tab order is card → Export/Edit/Delete.
-
-### History list (generated samples)
-
- Each **sample row** is focusable with `role="button"` and an `aria-label` (e.g. "Sample from [profile], [duration], [date]. Press Enter to play."); **Enter/Space** plays or restarts.
- **Transcript textarea** has `aria-label` (e.g. "Transcript for sample from [profile], [duration]") so when you focus on the text area, the sample is announced in context.
-
-### Voices tab (table)
-
- Each **voice row** is focusable with `role="button"` and an `aria-label` (e.g. "[Name], [language], [N] generations, [N] samples. Press Enter to edit."); **Enter/Space** opens edit (except when focus is in a control).
- **Actions** dropdown trigger has `aria-label="Actions for [profile name]"`.
-
-### Model management
-
- Each **model row** is a focusable region (`tabIndex={0}`, `role="group"`) with an `aria-label` (e.g. "[Model name], [status], [size]. Use Tab to reach Download or Delete.").
- **Download** and **Delete** (and Downloading) buttons have `aria-label` (e.g. "Download [name]", "Delete [name]").
-
-### Server tab (panels)
-
- **Server Connection**, **Server Status**, and **App Updates** cards are landmarks: `role="region"`, `aria-label`, and `tabIndex={0}` so each panel is focusable and announced (e.g. "Server Connection", "Server Status", "App Updates").
-
-### Stories list
-
- Each **story row** is a focusable control (`role="button"`, `tabIndex={0}`) with `aria-label` (e.g. "Story [name], [N] items, [date]. Press Enter to select."); **Enter/Space** selects the story. Actions button has `aria-label="Actions for [story name]"`.
-
-### Other controls
-
- **Story list** – Actions (⋮) button: `aria-label="Actions for [story name]"`.
- **Story track editor** – Play/Pause, Stop, Split, Duplicate, Delete, Zoom in/out: `aria-label` on all icon buttons.
- **Voice profile samples** (SampleList, AudioSampleUpload, AudioSampleRecording, AudioSampleSystem) – Play/Pause and Stop: `aria-label` (e.g. "Play sample", "Pause", "Stop playback").
- **SampleList** mini sample player – Seek slider has `aria-label="Sample playback position"` and `aria-valuetext` for time.
-
---
-
-## Testing
-
- **Screen readers:** Tested with **NVDA** and **Narrator** on Windows.
- **Keyboard:** Tab order and Enter/Space activation verified for focusable rows and buttons.
-
---
-
-## Tech note
-
- React + TypeScript; Radix UI primitives; labels added via `aria-label`, `aria-labelledby`, `aria-valuetext`, and `role`/`tabIndex` where needed.
- No new dependencies.
@@ -48,7 +48,7 @@ Windows SmartScreen may warn that the app is unrecognized.
    lsof -i :17493

    # Windows
-    netstat -ano | findstr :17493
+    powershell -Command "Get-NetTCPConnection -LocalPort 17493 -State Listen"
    ```

    Kill the process using the port:
@@ -0,0 +1,363 @@
+# Adding a TTS Engine to Voicebox
+
+Guide for adding new TTS model backends. Based on the implementation of LuxTTS (#254), Chatterbox Multilingual (#257), Chatterbox Turbo (#258), and the PyInstaller fixes in v0.2.3.
+
+---
+
+## Overview
+
+Adding an engine touches ~10 files across 4 layers. The backend protocol work is straightforward — the real time sink is dependency hell, upstream library bugs, and PyInstaller bundling.
+
+The backend is split into layers: `routes/` (thin HTTP handlers), `services/` (business logic), `backends/` (engine implementations), and `utils/` (shared utilities). New engines only need to touch `backends/` and `models.py` on the backend side — the route and service layers use a model config registry that handles dispatch automatically.
+
+---
+
+## Phase 1: Backend Implementation
+
+### 1.1 Create the backend file
+
+`backend/backends/<engine>_backend.py` (~200-300 lines)
+
+Implement the `TTSBackend` protocol from `backend/backends/__init__.py`:
+
+```python
+class YourBackend:
+    """Must satisfy the TTSBackend protocol."""
+
+    async def load_model(self, model_size: str = "default") -> None: ...
+    async def create_voice_prompt(self, audio_path: str, reference_text: str, use_cache: bool = True) -> tuple[dict, bool]: ...
+    async def combine_voice_prompts(self, audio_paths: list[str], ref_texts: list[str]) -> tuple[np.ndarray, str]: ...
+    async def generate(self, text: str, voice_prompt: dict, language: str = "en", seed: int | None = None, instruct: str | None = None) -> tuple[np.ndarray, int]: ...
+    def unload_model(self) -> None: ...
+    def is_loaded(self) -> bool: ...
+    def _get_model_path(self, model_size: str) -> str: ...
+```
+
+Key decisions per engine:
+
+| Decision | Options | Examples |
+|----------|---------|---------|
+| **Voice prompt storage** | Pre-computed tensors vs deferred file paths | Qwen PyTorch stores tensor dicts; Chatterbox stores `{"ref_audio": path, "ref_text": text}` |
+| **Caching** | Use voice prompt cache or skip it | LuxTTS caches with `luxtts_` prefix; Chatterbox skips caching entirely |
+| **Device selection** | CUDA / MPS / CPU | Chatterbox forces CPU on macOS (MPS tensor bugs); LuxTTS supports MPS |
+| **Model download** | Library handles it vs manual `snapshot_download` | Turbo uses manual download to bypass upstream `token=True` bug |
+| **Sample rate** | Engine-specific | LuxTTS outputs 48kHz, everything else is 24kHz |
+
+### 1.2 Voice prompt patterns
+
+There are three patterns in use. Pick the one that fits your model:
+
+**Pattern A: Pre-computed tensors** (Qwen PyTorch, LuxTTS)
+```python
+# create_voice_prompt returns opaque dict of tensors
+# Cached via torch.save(), reused across generations
+encoded = model.encode_prompt(audio_path)
+return encoded, False  # (prompt_dict, was_cached)
+```
+
+**Pattern B: Deferred file paths** (Chatterbox, MLX)
+```python
+# Just store paths, process at generation time
+return {"ref_audio": audio_path, "ref_text": reference_text}, False
+```
+
+**Pattern C: Hybrid** (possible for new engines)
+```python
+# Pre-compute speaker embeddings, store alongside paths
+embedding = model.extract_speaker(audio_path)
+return {"embedding": embedding, "ref_audio": audio_path}, False
+```
+
+If caching, prefix your cache keys to avoid collisions with other engines using the same reference audio:
+```python
+cache_key = "yourengine_" + get_cache_key(audio_path, reference_text)
+```
+
+### 1.3 Register the engine
+
+In `backend/backends/__init__.py`, three things:
+
+**1. Add a `ModelConfig` entry** in `_get_non_qwen_tts_configs()`:
+
+```python
+ModelConfig(
+    model_name="your-engine",
+    display_name="Your Engine",
+    engine="your_engine",
+    hf_repo_id="org/model-repo",
+    size_mb=3200,
+    needs_trim=False,  # set True if output needs trim_tts_output()
+    languages=["en", "fr", "de"],
+),
+```
+
+This single entry replaces what used to be 6+ scattered dicts in `main.py`. The registry helpers (`get_model_config()`, `check_model_loaded()`, `engine_needs_trim()`, etc.) all derive from this config automatically.
+
+**2. Add to `TTS_ENGINES` dict:**
+
+```python
+TTS_ENGINES = {
+    ...
+    "your_engine": "Your Engine",
+}
+```
+
+**3. Add an elif branch in `get_tts_backend_for_engine()`:**
+
+```python
+elif engine == "your_engine":
+    from .your_backend import YourBackend
+    backend = YourBackend()
+```
+
+The import is deferred so platform-specific deps aren't loaded until the engine is first requested.
+
+### 1.4 Update request models
+
+In `backend/models.py`:
+
+- Add engine name to `GenerationRequest.engine` regex pattern
+- Add any new language codes to the language regex on both `GenerationRequest` and `VoiceProfileCreate`
+
+---
+
+## Phase 2: Route and Service Integration
+
+With the model config registry, the route and service layers have **zero per-engine dispatch points**. All endpoints use registry helpers like `get_model_config()`, `load_engine_model()`, `engine_needs_trim()`, `check_model_loaded()`, etc.
+
+**You don't need to touch any route or service files** unless your engine needs custom behavior in the generate pipeline (e.g. a new post-processing step beyond `trim_tts_output`).
+
+### 2.1 What the registry handles automatically
+
+| Route file | Registry function used |
+|------------|----------------------|
+| `routes/generations.py` | `load_engine_model(engine, size)` + `engine_needs_trim(engine)` |
+| `routes/models.py` | `get_all_model_configs()` + `check_model_loaded(config)` |
+| `routes/models.py` | `get_model_config(name)` + `get_model_load_func(config)` |
+| `services/generation.py` | `get_tts_backend_for_engine()` + `ensure_model_cached_or_raise()` |
+
+### 2.2 Post-processing
+
+If your model produces trailing silence or hallucinated audio, set `needs_trim=True` on your `ModelConfig`. The generation service checks `engine_needs_trim(engine)` and applies `trim_tts_output()` automatically.
+
+---
+
+## Phase 3: Frontend Integration
+
+### 3.1 TypeScript types
+
+In `app/src/lib/api/types.ts`:
+- Add to the `engine` union type on `GenerationRequest`
+
+### 3.2 Language maps
+
+In `app/src/lib/constants/languages.ts`:
+- Add entry to `ENGINE_LANGUAGES` record
+- Add any new language codes to `ALL_LANGUAGES` if needed
+
+### 3.3 Engine/model selector (shared component)
+
+The model selector is a shared component — update one file:
+
+- `app/src/components/Generation/EngineModelSelector.tsx`
+
+Add an entry to `ENGINE_OPTIONS` and `ENGINE_DESCRIPTIONS`. If the engine is English-only, add it to `ENGLISH_ONLY_ENGINES`. The `handleEngineChange()` function handles language validation automatically (resets to first available language if the current one isn't supported).
+
+Both `GenerationForm.tsx` and `FloatingGenerateBox.tsx` use `<EngineModelSelector>` — no changes needed in either.
+
+Handle engine-specific UI conditionals in the form components if needed:
+- Hide instruct field for engines that don't support it
+- Show engine-specific controls (e.g. `ParalinguisticInput` for Turbo)
+
+### 3.4 Form hook
+
+In `app/src/lib/hooks/useGenerationForm.ts`:
+- Add to Zod schema enum for `engine`
+- Add engine-to-model-name mapping (e.g. `"your_engine"` → `"your-engine"`)
+- Update payload construction to conditionally include engine-specific fields
+
+### 3.5 Model management
+
+In `app/src/components/ServerSettings/ModelManagement.tsx`:
+- Add description to `MODEL_DESCRIPTIONS` record
+- The model list auto-renders from `/models/status` data
+
+---
+
+## Phase 4: Dependencies
+
+### 4.1 Python dependencies
+
+Add to `backend/requirements.txt`. Watch for:
+
+**Pinned dependency conflicts** — If the model package pins old versions of numpy, torch, or transformers, install with `--no-deps` and list sub-dependencies manually. This is what Chatterbox requires:
+```
+# In justfile (NOT requirements.txt):
+pip install --no-deps chatterbox-tts
+
+# In requirements.txt — list the transitive deps:
+conformer
+diffusers
+omegaconf
+# ... etc
+```
+
+**Non-PyPI packages** — Some deps only exist as git repos:
+```
+linacodec @ git+https://github.com/user/repo.git
+Zipvoice @ git+https://github.com/user/repo.git
+```
+
+**Custom package indexes** — Some packages need `--find-links`:
+```
+--find-links https://k2-fsa.github.io/icefall/piper_phonemize.html
+```
+
+### 4.2 Identifying hidden sub-dependencies
+
+When using `--no-deps`, you need to manually figure out what the package actually imports. There's no shortcut:
+
+1. Install the package normally in a throwaway venv
+2. Run `pip show <package>` to get its `Requires:` list
+3. Cross-reference against what's already in our requirements.txt
+4. Test that the engine loads and generates without import errors
+
+---
+
+## Phase 5: PyInstaller Bundling
+
+This is where most of the pain lives. If your model's Python package or its dependencies use any of the following at runtime, PyInstaller won't bundle them automatically:
+
+### 5.1 Common PyInstaller issues
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| **`inspect.getsource()` at import time** | "could not get source code" | `--collect-all <package>` (bundles `.py` source files, not just bytecode) |
+| **Data files (yaml, .pth.tar, lang dicts)** | FileNotFoundError at runtime | `--collect-all <package>` or `--collect-data <package>` |
+| **Native data paths (espeak-ng, etc.)** | Library looks at `/usr/share/...` | Set env var in frozen builds: `os.environ["ESPEAK_DATA_PATH"] = bundled_path` |
+| **`importlib.metadata` lookups** | "No package metadata found" | `--copy-metadata <package>` |
+| **Dynamic imports** | ModuleNotFoundError | `--hidden-import <module>` |
+| **`typeguard` / `@typechecked`** | Calls `inspect.getsource()` on decorated functions | `--collect-all` for the decorated package |
+
+### 5.2 Testing frozen builds
+
+You can't skip this. Models that work in `python -m uvicorn` will break in the PyInstaller binary. The flow:
+
+1. Build the binary: `just build` or the PyInstaller spec
+2. Run it and try to download + load + generate with the new engine
+3. Check stderr for the actual error (macOS/Linux: stdout/stderr go to Tauri sidecar logs)
+4. Fix, rebuild, repeat
+
+### 5.3 Real examples from v0.2.3
+
+These were all models that worked perfectly in dev:
+
+- **LuxTTS**: `typeguard`'s `@typechecked` calls `inspect.getsource()` at import → needed `--collect-all inflect`. `piper_phonemize` bundles `espeak-ng-data/` → needed `--collect-all piper_phonemize` + `ESPEAK_DATA_PATH` env var
+- **Chatterbox**: `resemble-perth` bundles a pretrained watermark model (`.pth.tar`, `hparams.yaml`) → needed `--collect-all perth`
+- **Both**: `huggingface_hub` silently disables tqdm based on logger level → progress bars showed 0% in frozen builds until we force-enabled the internal counter
+
+---
+
+## Phase 6: Common Upstream Workarounds
+
+Almost every model library has bugs you'll need to work around. Here's the catalog:
+
+### 6.1 torch.load device mismatch
+
+If model weights were saved on CUDA but you're loading on CPU/MPS:
+```python
+_original_torch_load = torch.load
+def _patched_torch_load(*args, **kwargs):
+    kwargs.setdefault("map_location", "cpu")
+    return _original_torch_load(*args, **kwargs)
+torch.load = _patched_torch_load
+```
+Used by both Chatterbox backends. Use a threading lock if patching globally.
+
+### 6.2 Float64/Float32 dtype mismatch
+
+`librosa` returns float64, model weights are float32. Patch the offending methods:
+```python
+original_fn = SomeClass.some_method
+def patched_fn(self, *args, **kwargs):
+    result = original_fn(self, *args, **kwargs)
+    return result.float()  # float64 → float32
+SomeClass.some_method = patched_fn
+```
+Used by Chatterbox for `S3Tokenizer.log_mel_spectrogram` and `VoiceEncoder.forward`.
+
+### 6.3 Transformers attention implementation
+
+If the model uses `output_attentions=True` with transformers >= 4.36:
+```python
+for module in model.modules():
+    if hasattr(module, '_attn_implementation'):
+        module._attn_implementation = "eager"
+```
+SDPA (the new default) doesn't support `output_attentions`. Force eager attention.
+
+### 6.4 HuggingFace token bug
+
+Some models' `from_pretrained()` passes `token=True` which requires a stored HF token even for public repos:
+```python
+from huggingface_hub import snapshot_download
+local_path = snapshot_download(repo_id=REPO, token=None)
+model = ModelClass.from_local(local_path, device=device)
+```
+Used by Chatterbox Turbo.
+
+### 6.5 MPS tensor issues
+
+MPS (Apple Silicon GPU) has incomplete operator coverage. If generation crashes on MPS:
+```python
+def _get_device(self):
+    if torch.cuda.is_available():
+        return "cuda"
+    return "cpu"  # Skip MPS entirely
+```
+Used by both Chatterbox backends. LuxTTS works fine on MPS.
+
+### 6.6 HuggingFace progress tracking
+
+To get download progress bars in the UI, wrap model loading with `HFProgressTracker`:
+```python
+from ..utils.hf_progress import HFProgressTracker
+tracker = HFProgressTracker(model_name, progress_manager)
+with tracker.patch_download():
+    model = ModelClass.from_pretrained(repo_id)
+```
+The tracker monkey-patches tqdm to intercept HuggingFace's internal progress bars. Must be set up BEFORE importing the model library if it imports HF at module level.
+
+---
+
+## Checklist
+
+### Backend
+- [ ] `backend/backends/<engine>_backend.py` — implements TTSBackend protocol
+- [ ] `backend/backends/__init__.py` — `ModelConfig` entry + `TTS_ENGINES` + `get_tts_backend_for_engine()` elif
+- [ ] `backend/models.py` — engine name in regex, any new language codes
+- [ ] `backend/requirements.txt` — dependencies added (check for `--no-deps` needs)
+- [ ] `justfile` — `--no-deps` install step if needed
+
+### Routes and services
+No changes needed — the model config registry handles all dispatch automatically.
+
+### Frontend
+- [ ] `app/src/lib/api/types.ts` — engine union type
+- [ ] `app/src/lib/constants/languages.ts` — `ENGINE_LANGUAGES` entry
+- [ ] `app/src/components/Generation/EngineModelSelector.tsx` — `ENGINE_OPTIONS` + `ENGINE_DESCRIPTIONS` + `ENGLISH_ONLY_ENGINES`
+- [ ] `app/src/lib/hooks/useGenerationForm.ts` — Zod schema + model mapping
+- [ ] `app/src/components/ServerSettings/ModelManagement.tsx` — model description
+
+### Production
+- [ ] PyInstaller spec — `--collect-all`, `--hidden-import`, `--copy-metadata` as needed
+- [ ] Test in frozen binary — download, load, generate all work
+- [ ] Download progress — `HFProgressTracker` wired up, progress shows in UI
+
+### Upstream workarounds (check which apply)
+- [ ] torch.load device mapping (CUDA weights on CPU)
+- [ ] Float64→Float32 patches (librosa interaction)
+- [ ] Eager attention forcing (transformers >= 4.36)
+- [ ] HF token bypass (snapshot_download + from_local)
+- [ ] MPS skip (if operators not supported)
+- [ ] espeak-ng / native data path env vars
@@ -1,435 +0,0 @@
-# External Provider Support
-
-**Status:** Planned for v0.2.0
-**Discussion:** [Reddit Thread](https://reddit.com/r/LocalLLaMA/...)
-
-## Overview
-
-External provider support allows you to connect Voicebox to remotely-hosted TTS and Whisper services instead of running models locally. This is useful for:
-
- **Existing GPU Infrastructure**: You already have Qwen3-TTS running on a GPU server
- **AMD GPU Users**: Run models on your AMD hardware, use Voicebox as the UI
- **Cloud Deployments**: Host models on Modal, Replicate, RunPod, etc.
- **Team Sharing**: Multiple users share one GPU server running models
- **Mixed Deployments**: Local Whisper + remote TTS, or vice versa
-
-## Architecture
-
-```
-┌─────────────────┐         HTTP/API         ┌──────────────────┐
-│   Voicebox UI   │ ───────────────────────> │  Your TTS Server │
-│   + Backend     │                           │  (Qwen3-TTS on   │
-│                 │ <─────────────────────── │   AMD/NVIDIA GPU)│
-│  - Profiles     │      Audio + Metadata     └──────────────────┘
-│  - History      │
-│  - Audio Edit   │         HTTP/API         ┌──────────────────┐
-│  - UI           │ ───────────────────────> │ Whisper Service  │
-└─────────────────┘                           │ (OpenAI API or   │
-                                              │  self-hosted)    │
-                                              └──────────────────┘
-```
-
-**What Voicebox Still Handles:**
- Voice profile management
- Generation history
- Audio trimming/editing
- Multi-track story editor
- UI/UX layer
-
-**What External Providers Handle:**
- Model inference (TTS generation, transcription)
- GPU allocation
- Model loading/caching
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# TTS Provider
-TTS_MODE=remote                              # local | remote
-TTS_REMOTE_URL=http://192.168.1.100:8000    # Your TTS server URL
-TTS_API_KEY=your-api-key                     # Optional authentication
-
-# Whisper Provider
-WHISPER_MODE=openai-api                      # local | openai-api | remote
-WHISPER_REMOTE_URL=http://localhost:9000     # For self-hosted Whisper
-OPENAI_API_KEY=sk-...                        # For OpenAI Whisper API
-```
-
-### Voicebox Config UI (Planned)
-
-Settings page will include:
- Provider selection dropdowns
- URL/API key inputs
- Connection test button
- Latency/status indicators
-
-## Hosting External Services
-
-### Option 1: Simple FastAPI Server (Recommended)
-
-Create a lightweight server to expose your local Qwen3-TTS model:
-
-```python
-# tts_server.py
-from fastapi import FastAPI, UploadFile, File
-from qwen_tts import Qwen3TTSModel
-import numpy as np
-import base64
-
-app = FastAPI()
-model = Qwen3TTSModel.from_pretrained(
-    "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
-    device_map="cuda"  # or "cpu" for AMD ROCm: use torch+rocm
-)
-
-@app.post("/v1/generate")
-async def generate(
-    text: str,
-    voice_prompt: dict,
-    language: str = "en",
-    seed: int = None
-):
-    """Generate speech from text using voice prompt."""
-    audio, sample_rate = model.generate_voice_clone(
-        text=text,
-        voice_clone_prompt=voice_prompt,
-    )
-
-    # Return as base64 for transport
-    audio_bytes = audio.tobytes()
-    return {
-        "audio": base64.b64encode(audio_bytes).decode(),
-        "sample_rate": sample_rate,
-        "dtype": str(audio.dtype)
-    }
-
-@app.post("/v1/create_voice_prompt")
-async def create_voice_prompt(
-    audio: UploadFile = File(...),
-    reference_text: str = ""
-):
-    """Create voice prompt from reference audio."""
-    # Save uploaded audio temporarily
-    audio_path = f"/tmp/{audio.filename}"
-    with open(audio_path, "wb") as f:
-        f.write(await audio.read())
-
-    # Create voice prompt
-    voice_prompt = model.create_voice_clone_prompt(
-        ref_audio=audio_path,
-        ref_text=reference_text,
-    )
-
-    return {"voice_prompt": voice_prompt}
-
-@app.get("/health")
-async def health():
-    return {
-        "status": "healthy",
-        "model": "Qwen3-TTS-12Hz-1.7B-Base",
-        "device": str(model.device)
-    }
-
-if __name__ == "__main__":
-    import uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=8000)
-```
-
-**Run it:**
-```bash
-# Install dependencies
-pip install fastapi uvicorn qwen-tts torch
-
-# For AMD GPUs, use ROCm PyTorch:
-pip install torch --index-url https://download.pytorch.org/whl/rocm6.4
-
-# Start server
-python tts_server.py
-```
-
-### Option 2: vLLM (If Supported)
-
-```bash
-vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-Base \
-  --host 0.0.0.0 \
-  --port 8000 \
-  --gpu-memory-utilization 0.9
-```
-
-### Option 3: Cloud Platforms
-
-**Modal.com Example:**
-```python
-import modal
-
-app = modal.App("qwen-tts")
-image = modal.Image.debian_slim().pip_install("qwen-tts", "torch")
-
-@app.function(gpu="A10G", image=image)
-@modal.web_endpoint(method="POST")
-def generate(text: str, voice_prompt: dict):
-    from qwen_tts import Qwen3TTSModel
-    model = Qwen3TTSModel.from_pretrained("Qwen/Qwen3-TTS-12Hz-1.7B-Base")
-    audio, sr = model.generate_voice_clone(text, voice_prompt)
-    return {"audio": audio.tolist(), "sample_rate": sr}
-```
-
-Deploy: `modal deploy tts_server.py`
-Get URL: `https://yourapp--generate.modal.run`
-
-## API Specification
-
-External TTS providers must implement these endpoints:
-
-### `POST /v1/generate`
-
-Generate speech from text.
-
-**Request:**
-```json
-{
-  "text": "Hello, this is a test.",
-  "voice_prompt": { /* voice prompt object */ },
-  "language": "en",
-  "seed": 12345
-}
-```
-
-**Response:**
-```json
-{
-  "audio": "base64-encoded-audio-bytes",
-  "sample_rate": 24000,
-  "dtype": "float32"
-}
-```
-
-### `POST /v1/create_voice_prompt`
-
-Create a voice prompt from reference audio.
-
-**Request:** (multipart/form-data)
- `audio`: Audio file upload
- `reference_text`: Transcript of the audio
-
-**Response:**
-```json
-{
-  "voice_prompt": { /* voice prompt object */ }
-}
-```
-
-### `GET /health`
-
-Health check endpoint.
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "model": "Qwen3-TTS-12Hz-1.7B-Base",
-  "device": "cuda:0"
-}
-```
-
-## Whisper External Providers
-
-### OpenAI Whisper API
-
-Simply set:
-```bash
-WHISPER_MODE=openai-api
-OPENAI_API_KEY=sk-...
-```
-
-Voicebox will use OpenAI's Whisper API automatically.
-
-### Self-Hosted Whisper
-
-Run your own Whisper server:
-
-```python
-# whisper_server.py
-from fastapi import FastAPI, UploadFile, File
-from transformers import WhisperProcessor, WhisperForConditionalGeneration
-import librosa
-
-app = FastAPI()
-processor = WhisperProcessor.from_pretrained("openai/whisper-base")
-model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-base")
-
-@app.post("/v1/transcribe")
-async def transcribe(audio: UploadFile = File(...), language: str = None):
-    # Load audio
-    audio_path = f"/tmp/{audio.filename}"
-    with open(audio_path, "wb") as f:
-        f.write(await audio.read())
-
-    audio_data, sr = librosa.load(audio_path, sr=16000)
-
-    # Process
-    inputs = processor(audio_data, sampling_rate=16000, return_tensors="pt")
-    predicted_ids = model.generate(inputs["input_features"])
-    transcription = processor.batch_decode(predicted_ids, skip_special_tokens=True)[0]
-
-    return {"text": transcription}
-```
-
-Configure Voicebox:
-```bash
-WHISPER_MODE=remote
-WHISPER_REMOTE_URL=http://localhost:9000
-```
-
-## Use Cases
-
-### 1. AMD GPU User with Existing Setup
-
-**Scenario:** You have a Radeon 7900 XTX running Qwen3-TTS on Linux.
-
-**Setup:**
-1. Run `tts_server.py` on your AMD box (ROCm PyTorch)
-2. Configure Voicebox: `TTS_MODE=remote`, `TTS_REMOTE_URL=http://amd-box:8000`
-3. Use Voicebox UI for profiles, generation, editing
-4. TTS happens on your AMD GPU
-
-### 2. Team Deployment
-
-**Scenario:** 5 team members, 1 GPU server.
-
-**Setup:**
-1. Deploy TTS server on shared GPU box
-2. Each person runs Voicebox desktop app locally
-3. All point to same `TTS_REMOTE_URL`
-4. Profiles and history stay local per user
-5. GPU usage is shared
-
-### 3. Hybrid Local/Remote
-
-**Scenario:** Fast local Whisper, heavy TTS on cloud.
-
-**Setup:**
-```bash
-TTS_MODE=remote
-TTS_REMOTE_URL=https://your-modal-app.modal.run
-
-WHISPER_MODE=local  # Fast transcription on your CPU
-```
-
-### 4. OpenAI Whisper + Self-Hosted TTS
-
-**Scenario:** Use OpenAI's API for transcription, run TTS locally.
-
-**Setup:**
-```bash
-TTS_MODE=local
-
-WHISPER_MODE=openai-api
-OPENAI_API_KEY=sk-...
-```
-
-## Security Considerations
-
-### Authentication
-
-Add API key authentication to your external server:
-
-```python
-from fastapi import Header, HTTPException
-
-API_KEY = "your-secret-key"
-
-async def verify_api_key(x_api_key: str = Header(...)):
-    if x_api_key != API_KEY:
-        raise HTTPException(status_code=401, detail="Invalid API key")
-
-@app.post("/v1/generate", dependencies=[Depends(verify_api_key)])
-async def generate(...):
-    ...
-```
-
-Configure Voicebox:
-```bash
-TTS_API_KEY=your-secret-key
-```
-
-### Network Security
-
- **VPN/Tailscale**: Use private network for remote servers
- **HTTPS**: Use reverse proxy (nginx/Caddy) with SSL certificates
- **Firewall**: Restrict access to known IPs
-
-### Rate Limiting
-
-Protect your external server:
-
-```python
-from slowapi import Limiter
-from slowapi.util import get_remote_address
-
-limiter = Limiter(key_func=get_remote_address)
-app.state.limiter = limiter
-
-@app.post("/v1/generate")
-@limiter.limit("10/minute")
-async def generate(...):
-    ...
-```
-
-## Performance Considerations
-
-### Latency
-
-External providers add network latency:
- **Local network**: ~10-50ms overhead (negligible)
- **Same datacenter**: ~1-5ms overhead
- **Cross-region cloud**: 50-200ms+ overhead
-
-For real-time applications, keep TTS server on local network or same cloud region.
-
-### Caching
-
-Implement response caching on external server:
-
-```python
-from functools import lru_cache
-
-@lru_cache(maxsize=1000)
-def get_cached_generation(text, voice_prompt_hash, language, seed):
-    return model.generate_voice_clone(text, voice_prompt)
-```
-
-### Load Balancing
-
-For high-traffic deployments, run multiple TTS servers behind a load balancer:
-
-```
-Voicebox ──> Load Balancer ──> TTS Server 1 (GPU 1)
-                           ├──> TTS Server 2 (GPU 2)
-                           └──> TTS Server 3 (GPU 3)
-```
-
-## Future Enhancements
-
- [ ] **Provider Marketplace**: Built-in directory of compatible providers
- [ ] **Automatic Fallback**: If remote fails, fallback to local
- [ ] **Cost Tracking**: Monitor API usage and costs
- [ ] **Performance Metrics**: Latency, throughput dashboards
- [ ] **Multi-Provider**: Use different providers for different voices/languages
-
-## Contributing
-
-If you build an external provider, please share:
-1. Server implementation
-2. Performance benchmarks
-3. Deployment guide
-
-Submit to: [GitHub Discussions](https://github.com/jamiepine/voicebox/discussions)
-
-## Questions?
-
- **Discord**: [Join the community](https://discord.gg/...)
- **GitHub**: [Open an issue](https://github.com/jamiepine/voicebox/issues)
- **Docs**: [Full documentation](https://voicebox.sh/docs)
@@ -1,396 +0,0 @@
-# MLX Audio Integration
-
-**Status:** Validated ✅
-**Context:** [mlx-audio v0.3.1 release](https://github.com/Blaizzy/mlx-audio)
-
-## Validation Results
-
-We validated mlx-audio in an isolated environment (`mlx-test/`). Key findings:
-
-| Metric | Result |
-|--------|--------|
-| MLX Version | 0.30.4 |
-| Model Load Time | ~1s (after initial download) |
-| Generation RTF | **0.5-0.6x** (1.7-2x faster than real-time) |
-| Test Hardware | Apple Silicon Mac |
-
-### Model Mapping
-
-| voicebox (PyTorch) | mlx-audio (MLX) |
-|--------------------|-----------------|
-| `Qwen/Qwen3-TTS-12Hz-1.7B-Base` | `mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16` |
-| `Qwen/Qwen3-TTS-12Hz-0.6B-Base` | (not yet converted) |
-
-### mlx-audio API
-
-The API uses a **generator-based streaming pattern**:
-
-```python
-from mlx_audio.tts import load
-
-model = load("mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16")
-
-# generate() yields GenerationResult objects
-for result in model.generate("Hello world"):
-    audio = result.audio           # numpy array of samples
-    sample_rate = result.sample_rate  # 24000
-    rtf = result.real_time_factor  # e.g., 0.55
-```
-
-### Known Warnings (harmless)
-
-```
-You are using a model of type qwen3_tts to instantiate a model of type .
-The tokenizer you are loading... with an incorrect regex pattern...
-```
-
-These warnings appear but don't affect functionality or output quality.
-
-### Demo Script
-
-Run `mlx-test/demo.py` to test:
-```bash
-cd mlx-test && source venv/bin/activate && python demo.py "Your text here"
-```
-
-## Problem
-
-Apple Silicon users are stuck on CPU inference while Windows and Linux users get CUDA acceleration. The current PyTorch MPS backend has stability issues (lines 34-36 in `backend/tts.py` and `backend/transcribe.py`), forcing a CPU fallback that makes voicebox significantly slower on M1/M2/M3 Macs.
-
-This creates a poor experience for a large portion of users who bought Apple Silicon specifically for ML workloads.
-
-## Solution
-
-Integrate [mlx-audio](https://github.com/Blaizzy/mlx-audio) as the inference engine for macOS Apple Silicon builds. MLX is Apple's native ML framework, optimized for Metal and the unified memory architecture. It's fast, stable, and already supports the same Qwen3-TTS models we use.
-
-**Key wins:**
- Native GPU acceleration on Apple Silicon (no more CPU fallback)
- Streaming TTS support (faster perceived latency)
- Memory optimizations (run larger models on less RAM)
- Fixed 0.6B silence bug that we currently ship
- Same Qwen3-TTS models (zero migration cost for users)
-
-## Architecture
-
-### Current Stack
-```
-┌─────────────────────────┐
-│   PyTorch + Qwen3-TTS   │
-│   (CPU only on macOS)   │
-└─────────────────────────┘
-```
-
-### Proposed Stack
-```
-┌─────────────────────────────────────────┐
-│  Platform Detection at Runtime          │
-└─────────────────────────────────────────┘
-           │
-           ├─── Apple Silicon (aarch64-darwin)
-           │    ┌─────────────────────────┐
-           │    │  MLX Audio Backend      │
-           │    │  - Qwen3-TTS (mlx)      │
-           │    │  - Whisper (mlx)        │
-           │    │  - Streaming support    │
-           │    └─────────────────────────┘
-           │
-           └─── Other (x86_64, Windows, Linux)
-                ┌─────────────────────────┐
-                │  PyTorch Backend        │
-                │  - Qwen3-TTS (pytorch)  │
-                │  - Whisper (pytorch)    │
-                │  - CUDA if available    │
-                └─────────────────────────┘
-```
-
-## Implementation Phases
-
-### Phase 1: Platform Detection & Dependency Management
-
-Create a backend that switches between PyTorch and MLX based on runtime platform detection.
-
-**New files:**
- `backend/platform.py` - Detect Apple Silicon, return backend type
- `backend/backends/__init__.py` - Backend factory pattern
- `backend/requirements-mlx.txt` - MLX-specific deps (macOS only)
-
-**Modified files:**
- `backend/requirements.txt` - Keep PyTorch as default
- `backend/main.py` - Import from backend factory instead of direct imports
-
-**Platform detection logic:**
-```python
-def get_backend_type() -> str:
-    """Detect best backend for current platform."""
-    if platform.system() == "Darwin" and platform.machine() == "arm64":
-        # Apple Silicon detected
-        try:
-            import mlx
-            return "mlx"
-        except ImportError:
-            return "pytorch"  # Fallback if mlx not installed
-    return "pytorch"
-```
-
-### Phase 2: MLX Backend Implementation
-
-Create parallel implementations of TTS and STT using mlx-audio.
-
-**New files:**
- `backend/backends/mlx_backend.py` - MLX inference engine
- `backend/backends/pytorch_backend.py` - Refactor current code into backend
-
-**Interface both backends must implement:**
-```python
-class TTSBackend(Protocol):
-    async def load_model(self, model_size: str) -> None: ...
-    async def create_voice_prompt(self, audio_path: str, reference_text: str) -> dict: ...
-    async def generate(self, text: str, voice_prompt: dict, **kwargs) -> Tuple[np.ndarray, int]: ...
-    async def generate_streaming(self, text: str, voice_prompt: dict, **kwargs) -> AsyncIterator[bytes]: ...
-    def unload_model(self) -> None: ...
-
-class STTBackend(Protocol):
-    async def load_model(self, model_size: str) -> None: ...
-    async def transcribe(self, audio_path: str, language: Optional[str]) -> str: ...
-    def unload_model(self) -> None: ...
-```
-
-**MLX backend implementation notes:**
-
-mlx-audio's `generate()` returns a generator by default (streaming is built-in):
-
-```python
-# MLX backend wrapper
-from mlx_audio.tts import load
-
-class MLXTTSBackend:
-    def __init__(self):
-        self.model = None
-    
-    async def load_model(self, model_size: str) -> None:
-        model_map = {
-            "1.7B": "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16",
-            # "0.6B": needs conversion to mlx format
-        }
-        self.model = load(model_map[model_size])
-    
-    async def generate(self, text: str, voice_prompt: dict, **kwargs) -> Tuple[np.ndarray, int]:
-        # Collect all chunks from generator
-        chunks = []
-        for result in self.model.generate(text):  # TODO: add voice_prompt support
-            chunks.append(np.array(result.audio))
-        return np.concatenate(chunks), 24000
-```
-
-**MLX-specific features to expose:**
- Streaming TTS (new endpoint: `/api/generate/stream`)
- Memory-optimized model loading
- Qwen3-ASR for transcription (in addition to Whisper)
-
-### Phase 3: API Layer Updates
-
-Update FastAPI endpoints to support new streaming capabilities and maintain backward compatibility.
-
-**Modified files:**
- `backend/main.py` - Add streaming endpoints
- `backend/tts.py` - Refactor to use backend abstraction
- `backend/transcribe.py` - Refactor to use backend abstraction
-
-**New endpoints:**
-```python
-@app.post("/api/generate/stream")
-async def generate_stream(...) -> StreamingResponse:
-    """Stream TTS chunks as they're generated (MLX only)."""
-    backend = get_backend()
-    if not hasattr(backend, 'generate_streaming'):
-        raise HTTPException(501, "Streaming not supported on this backend")
-    return StreamingResponse(backend.generate_streaming(...), media_type="audio/wav")
-```
-
-**Backward compatibility:**
- Keep all existing `/api/generate` endpoints unchanged
- PyTorch backend users see no behavior change
- MLX users automatically get faster inference, streaming is opt-in
-
-### Phase 4: Frontend Integration
-
-Add UI indicators for backend type and streaming progress.
-
-**Modified files:**
- `app/src/hooks/useGenerationForm.tsx` - Add streaming support
- `app/src/components/GenerationForm.tsx` - Show backend badge, streaming toggle
- `app/src/lib/api.ts` - Add streaming API client
-
-**UI additions:**
- Badge showing current backend ("MLX" or "PyTorch")
- Toggle for streaming mode (disabled if PyTorch)
- Real-time streaming playback (WaveSurfer progressive loading)
-
-### Phase 5: Build & Distribution
-
-Create separate installers for MLX (Apple Silicon) and PyTorch (Universal).
-
-**Modified files:**
- `tauri/src-tauri/tauri.conf.json` - Add target-specific builds
- `.github/workflows/release.yml` - Build both variants
-
-**Build matrix:**
-```yaml
- target: aarch64-apple-darwin
-  backend: mlx
-  installer: voicebox-macos-silicon-{version}.dmg
-
- target: x86_64-apple-darwin
-  backend: pytorch
-  installer: voicebox-macos-intel-{version}.dmg
-
- target: x86_64-pc-windows-msvc
-  backend: pytorch
-  installer: voicebox-windows-{version}.exe
-```
-
-**Installation flow:**
- Auto-detect architecture, recommend correct installer
- MLX installer includes `mlx-audio` in embedded Python
- PyTorch installer includes `torch` in embedded Python
- Both can coexist (different backend, same profile format)
-
-### Phase 6: Testing & Validation
-
-Ensure both backends produce compatible outputs.
-
-**New files:**
- `backend/tests/test_backend_parity.py` - Verify both backends produce similar audio
- `backend/tests/test_streaming.py` - Streaming-specific tests
-
-**Test scenarios:**
- Same voice prompt on both backends → similar (not identical) audio output
- Profile created on MLX → loads on PyTorch (and vice versa)
- Streaming chunks assemble into valid WAV file
- Model downloads work on both backends
- Memory usage stays within bounds
-
-### Phase 7: Documentation
-
-Update user-facing docs and developer guides.
-
-**New files:**
- `docs/developer/BACKENDS.md` - Guide for adding new backends
- `docs/overview/performance.md` - Backend comparison benchmarks
-
-**Modified files:**
- `README.md` - Note Apple Silicon acceleration
- `docs/TROUBLESHOOTING.md` - Add MLX-specific issues
-
-**Key docs to write:**
- Which installer to download (architecture detection)
- Performance comparison (MLX vs PyTorch on same M2 hardware)
- How streaming mode works
- How to force PyTorch on Apple Silicon (for debugging)
-
-## Technical Decisions
-
-### Why Dual Backend Instead of MLX-Only?
-
-**Pros of dual backend:**
- Windows and Intel Mac users unaffected
- Easier testing (can compare outputs)
- Fallback if MLX has issues
-
-**Cons of dual backend:**
- More code to maintain
- Two dependency trees
- Build complexity (separate installers)
-
-**Decision:** Dual backend. The maintenance cost is worth it to avoid breaking existing users and to have a fallback.
-
-### Why Separate Installers Instead of Runtime Detection?
-
-**Pros of separate installers:**
- Smaller bundle size (don't ship both PyTorch and MLX)
- Clearer to users which version they have
- Easier to debug (no "which backend am I running?" confusion)
- Can optimize each build for its target
-
-**Cons:**
- More installers to build and test
- Users might download the wrong one
-
-**Decision:** Separate installers. Bundle size matters (PyTorch + MLX would be huge), and we can auto-detect architecture on the download page.
-
-### Streaming vs Batch Generation
-
-MLX supports streaming, PyTorch doesn't (without significant work). Should streaming be:
-1. MLX-only feature (✅ chosen)
-2. Implemented for both (lots of work)
-3. Not exposed at all (wasted opportunity)
-
-**Decision:** MLX-only. Expose as opt-in feature with graceful degradation (button disabled on PyTorch backend).
-
-## Migration Path
-
-Nothing needs migrating, macos users will just notice a speed-boost in inference
-
-**Data format compatibility:**
- Profiles (SQLite) → no schema changes needed
- Voice prompts (cached) → backend-agnostic (just numpy arrays)
- Audio files → unchanged
-
-## Performance Expectations
-
-### Measured Results (from validation)
-
-| Metric | MLX (measured) | PyTorch CPU (estimated) |
-|--------|----------------|-------------------------|
-| **6s audio generation** | ~3-4s | ~10-15s |
-| **Real-time factor** | 0.5-0.6x | 2-3x |
-| **Model load (cached)** | ~1s | ~3-5s |
-
-### TTS Generation (1.7B model, ~20s output)
- **PyTorch CPU (M2 Max):** ~45-60s (slower than real-time)
- **MLX (M2 Max):** ~8-12s (faster than real-time)
- **Improvement:** ~4-5x faster
-
-### Whisper Transcription (10s audio clip)
- **PyTorch CPU:** ~5-8s
- **MLX:** ~1-2s
- **Improvement:** ~3-4x faster
-
-### Memory Usage (1.7B model)
- **PyTorch:** ~8-10GB (no GPU offload, so CPU RAM)
- **MLX:** ~4-6GB (unified memory, better optimization)
- **Improvement:** ~40% less RAM
-
-Full benchmarks will be in `docs/overview/performance.md` after Phase 6.
-
-## Open Questions
-
- **Should we support Qwen3-ASR (MLX-only) in addition to Whisper?** Adds another model option but increases complexity. Probably phase 8+. - Sure
- **Should we backport streaming to PyTorch?** Would require chunking and callback-based generation. Probably not worth it given mlx-audio already has it. - No
- **What's the auto-update UX for migrating PyTorch→MLX users?** Needs design. Don't want to force reinstall, but also want to make upgrade obvious. - it just updates, users see nothing
- **Do we expose backend selection in settings or hide it?** Leaning toward auto-detect only, with env var override for power users.
-
-## Success Metrics
-
-How we'll know this worked:
-
-1. **Performance:** Apple Silicon users report generation faster than real-time
-2. **Adoption:** >80% of macOS downloads are MLX build within 1 month
-3. **Stability:** <5% increase in bug reports (backend abstraction doesn't introduce regressions)
-4. **Feedback:** Positive sentiment in Discord/GitHub about macOS performance
-
-## Related Work
-
- [PyTorch MPS tracking issue](https://github.com/pytorch/pytorch/issues/77764) - Why we can't use MPS directly
- [mlx-audio server implementation](https://github.com/Blaizzy/mlx-audio/blob/main/examples/server.py) - Reference for streaming API
- [MLX Whisper benchmarks](https://github.com/ml-explore/mlx-examples/tree/main/whisper) - Performance data
-
-## Next Steps
-
-1. ~~Validate mlx-audio can load Qwen3-TTS models (quick test)~~ ✅ Done - see `mlx-test/`
-2. Get approval on dual-backend architecture
-3. Start Phase 1 (platform detection)
-
-## Questions?
-
-Feedback welcome in GitHub discussions or Discord.
@@ -1,500 +0,0 @@
-# PR #33 — CUDA Provider System Review
-
-> Branch: `external-provider-binaries` | Created: 2026-02-01 | 34 commits, 136 files, +10,266 lines
-> Reviewed: 2026-03-12
-
---
-
-## The Problem
-
-The CUDA PyTorch binary is ~2.4 GB. GitHub Releases has a 2 GB artifact limit. This means:
-
- Windows/Linux users with NVIDIA GPUs cannot get GPU acceleration from official releases
- 19 open issues about "GPU not detected" — the single most reported problem category
- Users who want GPU must clone the repo and run from source
- Every app update forces re-download of the entire binary
-
-This is the #1 user pain point by volume.
-
---
-
-## What PR #33 Does
-
-Splits the monolithic Voicebox binary into two layers:
-
-```
-┌──────────────────────────────────────┐
-│  Main App (~150MB Win/Lin, ~300 Mac) │
-│  Tauri + React + FastAPI + Whisper   │
-│  No PyTorch. MLX bundled on macOS.   │
-├──────────────────────────────────────┤
-│           HTTP (localhost)           │
-├──────────────────────────────────────┤
-│  Provider Binary (downloaded later)  │
-│  PyTorch CPU (~300MB)                │
-│  PyTorch CUDA (~2.4GB)              │
-│  Hosted on Cloudflare R2             │
-└──────────────────────────────────────┘
-```
-
-### New Backend Code
-
-| File | Purpose |
-|------|---------|
-| `backend/providers/__init__.py` (327 lines) | `ProviderManager` — lifecycle management, subprocess spawning, port allocation |
-| `backend/providers/base.py` (97 lines) | `TTSProvider` Protocol definition |
-| `backend/providers/bundled.py` (144 lines) | `BundledProvider` — wraps existing MLX/PyTorch backends for the new interface |
-| `backend/providers/local.py` (191 lines) | `LocalProvider` — HTTP client that talks to external provider processes |
-| `backend/providers/installer.py` (262 lines) | Download, extract, delete provider binaries |
-| `backend/providers/types.py` (34 lines) | `ProviderType` enum, `ProviderInfo` dataclass |
-| `backend/providers/checksums.py` (11 lines) | Checksum dict (currently empty) |
-
-### Provider Servers (Standalone Executables)
-
-| File | Purpose |
-|------|---------|
-| `providers/pytorch-cpu/main.py` (238 lines) | FastAPI server wrapping PyTorch CPU inference |
-| `providers/pytorch-cuda/main.py` (238 lines) | FastAPI server wrapping PyTorch CUDA inference |
-| `providers/pytorch-*/build.py` | PyInstaller build scripts |
-| `providers/pytorch-*/requirements.txt` | Isolated dependencies |
-
-### Frontend
-
-| File | Purpose |
-|------|---------|
-| `app/src/components/ServerSettings/ProviderSettings.tsx` (400 lines) | Provider download/start/stop/delete UI |
-
-### Also Included (Scope Creep)
-
-The PR bundles several unrelated changes that inflate the diff:
-
- `docs2/` — Entire documentation site rewrite (Fumadocs migration, ~3000 lines)
- `Dockerfile`, `Dockerfile.cuda`, `docker-compose.yml` — Docker support
- `landing/` — Banner removal
- UI refactors in Stories, History, Voice Profiles, Audio tab
- Linux audio capture module
- Various dependency bumps
-
---
-
-## Bug Report
-
-### Critical — Will Crash at Runtime
-
-#### C1. Provider `generate` endpoint can't parse requests
-
-**`providers/pytorch-cpu/main.py:91-97`** (same in pytorch-cuda)
-
-```python
-@app.post("/tts/generate")
-async def generate(
-    text: str,
-    voice_prompt: dict,
-    language: str = "auto",
-    seed: int = None,
-    model_size: str = "1.7B"
-):
-```
-
-Parameters declared as function arguments. FastAPI interprets these as **query parameters**, not JSON body. But `LocalProvider.generate()` sends a JSON body via `httpx`:
-
-```python
-# backend/providers/local.py:33-40
-response = await self.client.post("/tts/generate", json={
-    "text": text,
-    "voice_prompt": voice_prompt,
-    ...
-})
-```
-
-**Result:** Every generation call to an external provider returns HTTP 422 (Validation Error). The generation path is completely broken for external providers.
-
-**Fix:** Use a Pydantic request body model:
-```python
-class GenerateRequest(BaseModel):
-    text: str
-    voice_prompt: dict
-    language: str = "auto"
-    seed: Optional[int] = None
-    model_size: str = "1.7B"
-
-@app.post("/tts/generate")
-async def generate(data: GenerateRequest):
-```
-
-#### C2. Timeout error handler references undefined variables
-
-**`backend/providers/__init__.py:82-90`**
-
-```python
-stdout_content = ""
-stderr_content = ""
-# ... threads write to stdout_queue / stderr_queue ...
-except TimeoutError:
-    while not stdout_queue.empty():
-        stdout_lines.append(stdout_queue.get_nowait())  # NameError
-    while not stderr_queue.empty():
-        stderr_lines.append(stderr_queue.get_nowait())  # NameError
-```
-
-`stdout_lines` and `stderr_lines` are never defined. Every provider startup timeout will throw `NameError`, masking the real failure cause. Then `stdout_content` and `stderr_content` are logged but they're still empty strings — the queue data is never assigned back.
-
-#### C3. Sync `get_tts_model()` ignores external provider in async context
-
-**`backend/tts.py:15-29`**
-
-```python
-def get_tts_model():
-    manager = get_provider_manager()
-    loop = asyncio.get_event_loop()
-    if loop.is_running():
-        # We're in an async context, but can't await here
-        return manager._get_default_provider()
-```
-
-FastAPI routes are async. This function is called from several code paths during generation. In async context it **always returns the bundled provider**, ignoring whatever external provider the user selected. The user downloads and starts a CUDA provider, but generation still runs on CPU.
-
-### Critical — Security
-
-#### C4. Path traversal via `tarfile.extractall()` (CVE-2007-4559)
-
-**`backend/providers/installer.py:115-118`**
-
-```python
-with tarfile.open(archive_path, 'r:gz') as tar_ref:
-    tar_ref.extractall(providers_dir)
-```
-
-No member path filtering. A crafted `.tar.gz` from a compromised CDN can write files anywhere on disk via `../` entries. Python 3.12+ emits a deprecation warning for exactly this pattern.
-
-**Fix:**
-```python
-tar_ref.extractall(providers_dir, filter='data')  # Python 3.12+
-```
-
-Or manually validate each member:
-```python
-for member in tar_ref.getmembers():
-    member_path = os.path.join(providers_dir, member.name)
-    if not os.path.commonpath([providers_dir, member_path]).startswith(str(providers_dir)):
-        raise ValueError(f"Path traversal attempt: {member.name}")
-tar_ref.extractall(providers_dir)
-```
-
-#### C5. No checksum verification on downloaded binaries
-
-**`backend/providers/checksums.py`**
-
-```python
-PROVIDER_CHECKSUMS = {}
-```
-
-Empty dict. `download_provider()` in `installer.py` never calls any verification function. Downloaded binaries are `chmod 0o755`'d and executed without integrity checks. A MitM or CDN compromise delivers arbitrary code.
-
-**Fix:** Populate checksums per release. Verify SHA-256 after download before extraction:
-```python
-import hashlib
-sha256 = hashlib.sha256(archive_path.read_bytes()).hexdigest()
-if sha256 != expected:
-    archive_path.unlink()
-    raise ValueError(f"Checksum mismatch for {provider_type}")
-```
-
-#### C6. Provider servers have no authentication
-
-**`providers/pytorch-cpu/main.py:18-23`**
-
-```python
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    ...
-)
-```
-
-Zero auth. Any local process — including browser JavaScript via localhost — can send requests to the provider on its ephemeral port. Port is discoverable by scanning.
-
-**Fix:** Generate a random token in the parent process, pass via environment variable to the child, validate in middleware:
-```python
-# Parent (ProviderManager)
-token = secrets.token_urlsafe(32)
-env = {**os.environ, "VOICEBOX_PROVIDER_TOKEN": token}
-process = subprocess.Popen([...], env=env, ...)
-
-# Child (provider server)
-EXPECTED_TOKEN = os.environ.get("VOICEBOX_PROVIDER_TOKEN")
-
-@app.middleware("http")
-async def verify_token(request, call_next):
-    if request.headers.get("X-Provider-Token") != EXPECTED_TOKEN:
-        return JSONResponse(status_code=403, content={"error": "unauthorized"})
-    return await call_next(request)
-```
-
-### Major — Will Cause Problems in Production
-
-#### M1. Leaked file handles on subprocess stdout/stderr
-
-**`backend/providers/__init__.py:68-73`**
-
-```python
-process = subprocess.Popen(
-    [...],
-    stdout=open(stdout_log, 'w'),   # leaked handle
-    stderr=open(stderr_log, 'w'),   # leaked handle
-)
-```
-
-File handles passed directly from `open()` without storing references. They close on GC, not deterministically. On Windows the log files stay locked and unreadable until the process exits.
-
-**Fix:**
-```python
-stdout_fh = open(stdout_log, 'w')
-stderr_fh = open(stderr_log, 'w')
-try:
-    process = subprocess.Popen([...], stdout=stdout_fh, stderr=stderr_fh)
-finally:
-    stdout_fh.close()
-    stderr_fh.close()
-```
-
-#### M2. No subprocess crash detection or recovery
-
-**`backend/providers/__init__.py:56-110`**
-
-Once `start_provider()` succeeds, the `Popen` object is stored but never polled. If the provider process crashes mid-session:
- `LocalProvider` HTTP calls fail with `httpx.ConnectError`
- No auto-restart
- No health-check loop
- User sees cryptic "connection refused" errors
- Must manually restart provider from UI
-
-**Fix:** Background asyncio task that polls `process.poll()` every few seconds. On crash, update provider status and optionally auto-restart:
-```python
-async def _watch_provider_process(self):
-    while self._provider_process and self._provider_process.poll() is None:
-        await asyncio.sleep(5)
-    if self._provider_process and self._provider_process.returncode != 0:
-        logger.error(f"Provider crashed with code {self._provider_process.returncode}")
-        self.active_provider = self._default_provider
-        # Notify frontend via next health check
-```
-
-#### M3. Port allocation race condition (TOCTOU)
-
-**`backend/providers/__init__.py:145-149`**
-
-```python
-def _get_free_port(self) -> int:
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        s.bind(('', 0))
-        return s.getsockname()[1]
-    # Socket closed here — port is free but unprotected
-```
-
-Between this function returning and the provider process binding, another process can claim the port. On busy systems this causes "address already in use" failures.
-
-**Fix options:**
- Pass the socket fd to the child process (complex, platform-specific)
- Retry with a new port on bind failure (simplest)
- Use a fixed port range and try sequentially
-
-#### M4. `delete_provider()` leaves hundreds of MB behind
-
-**`backend/providers/installer.py:155-168`**
-
-```python
-provider_path.unlink()  # Deletes just the executable
-```
-
-PyInstaller `--onedir` produces a directory with the executable plus all shared libraries. `unlink()` only removes the binary file, leaving behind hundreds of MB of `.so`/`.dll`/`.dylib` files.
-
-**Fix:**
-```python
-provider_dir = provider_path.parent
-shutil.rmtree(provider_dir)
-```
-
-#### M5. `LocalProvider.combine_voice_prompts()` bypasses the provider
-
-**`backend/providers/local.py:68-88`**
-
-This method imports from `..utils.audio` and processes locally instead of sending to the provider server. If the user chose an external provider because they lack local dependencies (e.g., no PyTorch on the machine), this will crash with `ImportError`.
-
-#### M6. Download errors silently swallowed
-
-**`backend/main.py:1640`**
-
-```python
-asyncio.create_task(download_provider(provider_type))
-```
-
-Fire-and-forget. If the download fails, the exception is logged as "Task exception was never retrieved." The frontend SSE progress stream may hang forever showing "downloading" without the error.
-
-**Fix:** Store the task, add an error callback:
-```python
-task = asyncio.create_task(download_provider(provider_type))
-task.add_done_callback(lambda t: t.exception() if not t.cancelled() else None)
-```
-And propagate errors through the progress manager so the SSE stream surfaces them.
-
-#### M7. `LocalProvider.is_loaded()` always returns `True`
-
-**`backend/providers/local.py:105-108`**
-
-```python
-def is_loaded(self) -> bool:
-    return True  # Return True optimistically
-```
-
-Health/status checks always report the model as loaded for external providers, even when the provider hasn't loaded anything yet. This breaks the "download model if not cached" logic in the generation flow.
-
-#### M8. `instruct` parameter silently dropped
-
-**`backend/providers/local.py:33-40`**
-
-The `generate()` method accepts `instruct` but never includes it in the JSON payload. The provider server also hardcodes `instruct=None`. Delivery instructions silently do nothing for external providers.
-
-### Minor
-
-| # | Issue | Location |
-|---|-------|----------|
-| m1 | `pytorch-cpu/main.py` and `pytorch-cuda/main.py` are 95% identical | Both files | 
-| m2 | `build.py` scripts also nearly identical | Both build files |
-| m3 | `navigator.platform` is deprecated | `ProviderSettings.tsx:20-23` |
-| m4 | `console.log('currentProvider', ...)` left in | `ProviderSettings.tsx:151` |
-| m5 | `ProviderType` enum defined but never used for validation | `types.py:10-15` |
-| m6 | `list_installed()` reimplements platform detection | `__init__.py:129-143` |
-| m7 | New `httpx.AsyncClient` created per health poll iteration | `__init__.py:151-165` |
-| m8 | `load_model_async()` only stores size, doesn't actually preload | `local.py:95-99` |
-
---
-
-## Scope Creep
-
-The PR should be split. These are independent changes bundled in:
-
-| Change | Lines | Should Be Separate PR |
-|--------|-------|-----------------------|
-| `docs2/` site rewrite | ~3000 | Yes |
-| Docker support (Dockerfile, compose, docs) | ~600 | Yes — overlaps with PR #161 |
-| Landing page banner removal | ~30 | Yes |
-| UI refactors (Stories, History, Voices, Audio) | ~400 | Yes |
-| Linux audio capture module | ~10 | Yes |
-| Dependency bumps | ~100 | Yes |
-
-**Core provider system** (the actual feature) is ~2500 lines across backend + frontend + provider servers. That's the reviewable scope.
-
---
-
-## What's Well-Designed
-
-These parts should survive any rewrite:
-
-1. **`TTSProvider` Protocol** (`base.py`) — Structural typing via `@runtime_checkable Protocol`. Right pattern. Comprehensive interface.
-
-2. **`BundledProvider` / `LocalProvider` split** — Clean separation between in-process and HTTP-based inference. The wrapper pattern in `BundledProvider` correctly delegates to existing `TTSBackend`.
-
-3. **R2 distribution strategy** — Provider binaries on Cloudflare R2, main app on GitHub Releases. Correct solution to the 2 GB limit.
-
-4. **Progress tracking** — SSE-based download progress integrated with the existing `ProgressManager`. Good UX.
-
-5. **Subprocess log files** — Writing provider stdout/stderr to log files in the data directory is pragmatic and debuggable.
-
-6. **Frontend `ProviderSettings.tsx`** — Clean component structure. Proper loading/disabled states, confirmation dialogs, platform-aware visibility.
-
-7. **CI split** — Separate `build-providers` and `release` jobs. Providers built and uploaded to R2 independently.
-
---
-
-## Options for Moving Forward
-
-### Option A — Fix and Slim PR #33
-
-Strip the PR down to just the provider system (~2500 lines). Fix the 5 critical and 8 major bugs. Rebase onto current `main`.
-
-**Effort:** ~2-3 days focused work
-**Pros:** Full auto-managed provider lifecycle. Foundation for multi-model.
-**Cons:** Still complex. Process management is inherently fragile cross-platform.
-
-### Option B — Manual External Server Mode
-
-Skip subprocess management entirely. Ship a "Connect to External Server" feature:
-
-1. User downloads CUDA provider zip from `downloads.voicebox.sh`
-2. User runs it manually (`./tts-provider-pytorch-cuda --port 8100`)
-3. In Voicebox UI: paste `http://localhost:8100` as the TTS server URL
-4. Voicebox routes generation to that URL via `LocalProvider`
-
-This reuses `LocalProvider` from PR #33 but removes:
- `ProviderManager` subprocess spawning (the buggiest part)
- `installer.py` download/extract logic (the security risks)
- Port allocation (user picks the port)
- Process lifecycle management (user's responsibility)
-
-**Effort:** ~1 day. `LocalProvider` + a URL input field + health check.
-**Pros:** Simple, reliable, no process management bugs, no security surface.
-**Cons:** Manual setup. Not seamless. But CUDA users are already technical (they run from source today).
-
-### Option C — Hybrid (Recommended)
-
-Ship Option B first as v0.2.0. Then iterate toward auto-management:
-
-**Phase 1 (v0.2.0):** Manual external server mode
- `LocalProvider` HTTP client (from PR #33, with the 422 bug fixed)
- Server URL input in Settings
- Health indicator
- CUDA provider published as standalone zip on R2
- One page of docs: "download, unzip, run, paste URL"
-
-**Phase 2 (v0.2.x):** Auto-download + auto-start
- `installer.py` with checksum verification and safe extraction
- `ProviderManager` subprocess spawning with crash detection
- Provider settings UI with download/start/stop buttons
-
-**Phase 3 (v0.3.0):** Multi-model providers
- Provider per model family (not just per hardware)
- LuxTTS provider, Chatterbox provider, etc.
- Provider marketplace / registry
-
-This gets CUDA into users' hands immediately (Phase 1 is ~1 day) while building toward the full vision incrementally. Each phase is independently shippable and testable.
-
-### Option D — GitHub Workaround
-
-Avoid the provider architecture entirely. Host CUDA binaries on R2 and add a download link in the app that opens the user's browser. User downloads the full monolithic CUDA build, replaces their existing install.
-
-**Effort:** Minimal — just hosting + a link.
-**Pros:** Zero architecture changes.
-**Cons:** Doesn't solve: multi-model, independent app updates, or the re-download-everything-on-update problem. Kicks the can.
-
---
-
-## Recommendation
-
-**Option C (Hybrid)** is the strongest path. Specifically:
-
-1. **Now:** Close PR #33 as-is. It's too large, too buggy, and too stale to salvage as a single merge.
-
-2. **Extract:** Cherry-pick the good parts into small focused PRs:
-   - PR: `TTSProvider` Protocol + `BundledProvider` + `LocalProvider` (the abstractions)
-   - PR: Provider settings UI (the frontend)
-   - PR: `installer.py` + checksums (the download system)
-   - PR: CI changes for R2 upload (the distribution)
-
-3. **Ship Phase 1:** Manual external server mode. One small PR. Unblocks every CUDA user immediately.
-
-4. **Iterate:** Layer in auto-management once the manual mode is proven stable.
-
-The critical bugs in PR #33 (C1-C6) are all fixable, but the PR's size makes review unreliable. Splitting it ensures each piece gets proper attention and nothing ships broken.
-
---
-
-## Bug Summary
-
-| Severity | Count | Blocks Ship? |
-|----------|-------|-------------|
-| Critical (runtime crash) | 3 | Yes — C1, C2, C3 |
-| Critical (security) | 3 | Yes — C4, C5, C6 |
-| Major | 8 | Some — M1, M2, M3 are high risk |
-| Minor | 8 | No |
-| **Total** | **22** | |
@@ -50,9 +50,10 @@

 | Layer | File | Purpose |
 |-------|------|---------|
-| Backend entry | `backend/main.py` | FastAPI app, all API routes (~2100 lines) |
-| TTS protocol | `backend/backends/__init__.py:14-81` | `TTSBackend` Protocol definition |
-| TTS factory | `backend/backends/__init__.py:138-178` | Thread-safe engine registry (double-checked locking) |
+| Backend entry | `backend/main.py` | FastAPI app, all API routes (~2850 lines) |
+| TTS protocol | `backend/backends/__init__.py:32-101` | `TTSBackend` Protocol definition |
+| Model registry | `backend/backends/__init__.py:17-29,153-366` | `ModelConfig` dataclass + registry helpers |
+| TTS factory | `backend/backends/__init__.py:382-426` | Thread-safe engine registry (double-checked locking) |
 | PyTorch TTS | `backend/backends/pytorch_backend.py` | Qwen3-TTS via `qwen_tts` package |
 | MLX TTS | `backend/backends/mlx_backend.py` | Qwen3-TTS via `mlx_audio.tts` |
 | LuxTTS | `backend/backends/luxtts_backend.py` | LuxTTS — fast, CPU-friendly |
@@ -64,6 +65,7 @@
 | Audio utils | `backend/utils/audio.py` | `trim_tts_output()`, normalize, load/save audio |
 | Frontend API | `app/src/lib/api/client.ts` | Hand-written fetch wrapper |
 | Frontend types | `app/src/lib/api/types.ts` | TypeScript API types |
+| Engine selector | `app/src/components/Generation/EngineModelSelector.tsx` | Shared engine/model dropdown |
 | Generation form | `app/src/components/Generation/GenerationForm.tsx` | TTS generation UI |
 | Floating gen box | `app/src/components/Generation/FloatingGenerateBox.tsx` | Compact generation UI |
 | Model manager | `app/src/components/ServerSettings/ModelManagement.tsx` | Model download/status/progress UI |
@@ -101,8 +103,10 @@ POST /generate
 - Multi-engine TTS architecture with thread-safe backend registry (PR #254)
 - LuxTTS integration — fast, CPU-friendly English TTS (PR #254)
 - Chatterbox Multilingual TTS — 23 languages including Hebrew (PR #257)
- Delivery instructions (instruct parameter, Qwen only)
+- Instruct parameter UI exists but is non-functional across all backends (see #224, Known Limitations)
 - Single flat model dropdown (Qwen 1.7B, Qwen 0.6B, LuxTTS, Chatterbox, Chatterbox Turbo)
+- Centralized model config registry (`ModelConfig` dataclass) — no per-engine dispatch maps in `main.py`
+- Shared `EngineModelSelector` component — engine/model dropdown defined once, used in both generation forms

 **Infrastructure:**
 - CUDA backend swap via binary download and restart (PR #252)
@@ -125,13 +129,13 @@ POST /generate

 ### TTS Engine Comparison

-| Engine | Model Name | Languages | Size | Key Features |
-|--------|-----------|-----------|------|-------------|
-| Qwen3-TTS 1.7B | `qwen-tts-1.7B` | 10 (zh, en, ja, ko, de, fr, ru, pt, es, it) | ~3.5 GB | Instruct mode, highest quality |
-| Qwen3-TTS 0.6B | `qwen-tts-0.6B` | 10 | ~1.2 GB | Lighter, faster |
-| LuxTTS | `luxtts` | English | ~300 MB | CPU-friendly, 48 kHz, fast |
-| Chatterbox | `chatterbox-tts` | 23 (incl. Hebrew, Arabic, Hindi, etc.) | ~3.2 GB | Zero-shot cloning, multilingual |
-| Chatterbox Turbo | `chatterbox-turbo` | English | ~1.5 GB | Paralinguistic tags ([laugh], [cough]), 350M params, low latency |
+| Engine | Model Name | Languages | Size | Key Features | Instruct Support |
+|--------|-----------|-----------|------|-------------|-----------------|
+| Qwen3-TTS 1.7B | `qwen-tts-1.7B` | 10 (zh, en, ja, ko, de, fr, ru, pt, es, it) | ~3.5 GB | Highest quality, voice cloning | None (Base model has no instruct path) |
+| Qwen3-TTS 0.6B | `qwen-tts-0.6B` | 10 | ~1.2 GB | Lighter, faster | None |
+| LuxTTS | `luxtts` | English | ~300 MB | CPU-friendly, 48 kHz, fast | None |
+| Chatterbox | `chatterbox-tts` | 23 (incl. Hebrew, Arabic, Hindi, etc.) | ~3.2 GB | Zero-shot cloning, multilingual | Partial — `exaggeration` float (0-1) for expressiveness |
+| Chatterbox Turbo | `chatterbox-turbo` | English | ~1.5 GB | Paralinguistic tags ([laugh], [cough]), 350M params, low latency | Partial — inline tags only, no separate instruct param |

 ### Multi-Engine Architecture (Shipped)

@@ -149,6 +153,7 @@ The singleton TTS backend blocker described in the previous version of this doc
 - **HF XET progress**: Large files downloaded via `hf-xet` (HuggingFace's new transfer backend) report `n=0` in tqdm updates. Progress bars may appear stuck for large `.safetensors` files even though the download is proceeding. This is a known upstream limitation.
 - **Chatterbox Turbo upstream token bug**: `from_pretrained()` passes `token=os.getenv("HF_TOKEN") or True` which fails without a stored HF token. Our backend works around this by calling `snapshot_download(token=None)` + `from_local()`.
 - **chatterbox-tts must install with `--no-deps`**: It pins `numpy<1.26`, `torch==2.6.0`, `transformers==4.46.3` — all incompatible with our stack (Python 3.12, torch 2.10, transformers 4.57.3). Sub-deps listed explicitly in `requirements.txt`.
+- **Instruct parameter is non-functional** (#224): The UI exposes an instruct text field, but it's silently dropped by every backend. The Qwen3-TTS Base model we ship only supports voice cloning — instruct requires the separate CustomVoice model variant (`Qwen3-TTS-12Hz-1.7B-CustomVoice`), which uses predefined speakers instead of ref audio. The instruct UI should be hidden until a backend with real support is integrated.
 - **Streaming generation** only works for Qwen on MLX. Other engines use the non-streaming `/generate` endpoint.
 - **dicta-onnx** (Hebrew diacritization) not included — upstream Chatterbox bug requires `model_path` arg but calls `Dicta()` with none. Hebrew works fine without it.

@@ -323,41 +328,43 @@ Notable requests:

 ### Models Worth Supporting (2026 SOTA — updated March 13)

-| Model | Cloning | Speed | Sample Rate | Languages | VRAM | Integration Ease | Status |
-|-------|---------|-------|-------------|-----------|------|-----------------|--------|
-| **Qwen3-TTS** | 10s zero-shot | Medium | 24 kHz | 10 | Medium | **Shipped** | v0.1.13 |
-| **LuxTTS** | 3s zero-shot | 150x RT, CPU ok | 48 kHz | English | <1 GB | **Shipped** | PR #254 |
-| **Chatterbox MTL** | 5s zero-shot | Medium | 24 kHz | 23 | Medium | **Shipped** | PR #257 |
-| **Chatterbox Turbo** | 5s zero-shot | Fast | 24 kHz | English | Low | **PR #258** | In review |
-| **HumeAI TADA 1B/3B** | Zero-shot | 5× faster than LLM-TTS | — | EN (1B), Multilingual (3B) | Medium | Needs vetting | MIT, 700s+ coherent, synced transcript output |
-| **MOSS-TTS Family** | Zero-shot | — | — | Multilingual | Medium | Needs vetting | Apache 2.0, multi-speaker dialogue, text-to-voice design (no ref audio) |
-| **VoxCPM 1.5** | Zero-shot (seconds) | ~0.15 RTF streaming | — | Bilingual (EN/ZH) | Medium | Needs vetting | Apache 2.0, tokenizer-free continuous diffusion, LoRA-friendly |
-| **Pocket TTS** | Zero-shot + streaming | >1× RT on CPU | — | English | ~100M params, CPU-first | Needs vetting | MIT, Kyutai Labs, no GPU required |
-| **Kokoro-82M** | 3s instant | CPU realtime | 24 kHz | English | Tiny (82M) | Ready | Apache 2.0, multi-engine arch in place |
-| **XTTS-v2** | 6s zero-shot | Mid-GPU | 24 kHz | 17+ | Medium | Ready | Multi-engine arch in place |
-| **Fish Speech** | 10-30s few-shot | Real-time | 24-44 kHz | 50+ | Medium | Ready | Multi-engine arch in place |
-| **CosyVoice2-0.5B** | 3-10s zero-shot | Very fast | 24 kHz | Multilingual | Low | Ready | Multi-engine arch in place |
+| Model | Cloning | Speed | Sample Rate | Languages | VRAM | Instruct Support | Integration Ease | Status |
+|-------|---------|-------|-------------|-----------|------|-----------------|-----------------|--------|
+| **Qwen3-TTS** | 10s zero-shot | Medium | 24 kHz | 10 | Medium | None (Base); Yes (CustomVoice variant, predefined speakers only) | **Shipped** | v0.1.13 |
+| **LuxTTS** | 3s zero-shot | 150x RT, CPU ok | 48 kHz | English | <1 GB | None | **Shipped** | PR #254 |
+| **Chatterbox MTL** | 5s zero-shot | Medium | 24 kHz | 23 | Medium | Partial — `exaggeration` float | **Shipped** | PR #257 |
+| **Chatterbox Turbo** | 5s zero-shot | Fast | 24 kHz | English | Low | Partial — inline tags only | **PR #258** | In review |
+| **CosyVoice2-0.5B** | 3-10s zero-shot | Very fast | 24 kHz | Multilingual | Low | **Yes** — `inference_instruct2()`, works with cloning | Ready | Best instruct candidate |
+| **Fish Speech** | 10-30s few-shot | Real-time | 24-44 kHz | 50+ | Medium | **Yes** — inline text descriptions, word-level control | Ready | Multi-engine arch in place |
+| **MOSS-TTS Family** | Zero-shot | — | — | Multilingual | Medium | **Yes** — text prompts for style + timbre design | Needs vetting | Apache 2.0, multi-speaker dialogue |
+| **HumeAI TADA 1B/3B** | Zero-shot | 5× faster than LLM-TTS | — | EN (1B), Multilingual (3B) | Medium | Partial — automatic prosody from text context | Needs vetting | MIT, 700s+ coherent, synced transcript output |
+| **VoxCPM 1.5** | Zero-shot (seconds) | ~0.15 RTF streaming | — | Bilingual (EN/ZH) | Medium | Partial — automatic context-aware prosody | Needs vetting | Apache 2.0, tokenizer-free continuous diffusion |
+| **Kokoro-82M** | 3s instant | CPU realtime | 24 kHz | English | Tiny (82M) | Partial — automatic style inference | Ready | Apache 2.0, multi-engine arch in place |
+| **XTTS-v2** | 6s zero-shot | Mid-GPU | 24 kHz | 17+ | Medium | Partial — style transfer from ref audio only | Ready | Multi-engine arch in place |
+| **Pocket TTS** | Zero-shot + streaming | >1× RT on CPU | — | English | ~100M params, CPU-first | None | Needs vetting | MIT, Kyutai Labs, no GPU required |

 #### Notes on New Candidates (March 2026)

- **HumeAI TADA** — Text-Audio Dual Alignment arch. Near-zero hallucinations/drift, free synced transcript. 700+ seconds coherent audio. Best candidate for Stories long-form reliability. [HF: HumeAI/tada-1b](https://huggingface.co/HumeAI/tada-1b) | [GitHub: HumeAI/tada](https://github.com/HumeAI/tada)
- **MOSS-TTS** — Modular suite: flagship cloning, MOSS-TTSD (multi-speaker dialogue), MOSS-VoiceGenerator (create voices from text descriptions, no ref audio). Unique UX for Stories voice design. [GitHub: OpenMOSS/MOSS-TTS](https://github.com/OpenMOSS/MOSS-TTS)
- **VoxCPM 1.5** — Tokenizer-free continuous diffusion + autoregressive. No discrete token artifacts. Context-aware prosody/emotion, real-time streaming, LoRA fine-tuning. Trained on 1.8M+ hours. [GitHub: OpenBMB/VoxCPM](https://github.com/OpenBMB/VoxCPM)
- **Pocket TTS** — 100M param CPU-first model from Kyutai Labs (Moshi team). Runs >1× realtime without GPU. Broadens hardware support significantly. [GitHub: kyutai-labs/pocket-tts](https://github.com/kyutai-labs/pocket-tts)
+- **CosyVoice2-0.5B** — Best candidate for instruct support. `inference_instruct2()` accepts a text instruct parameter for emotions, speed, volume, dialects — and it works alongside voice cloning. This is the closest match to what users expect from our instruct UI. [HF: FunAudioLLM/CosyVoice2-0.5B](https://huggingface.co/FunAudioLLM/CosyVoice2-0.5B)
+- **HumeAI TADA** — Text-Audio Dual Alignment arch. Near-zero hallucinations/drift, free synced transcript. 700+ seconds coherent audio. Best candidate for Stories long-form reliability. Prosody/emotion is automatic from text context, not user-controllable. [HF: HumeAI/tada-1b](https://huggingface.co/HumeAI/tada-1b) | [GitHub: HumeAI/tada](https://github.com/HumeAI/tada)
+- **MOSS-TTS** — Modular suite: flagship cloning, MOSS-TTSD (multi-speaker dialogue), MOSS-VoiceGenerator (create voices from text descriptions). VoiceGenerator unifies timbre design and style control via text prompts, usable as a layer for downstream TTS including cloning. [HF: OpenMOSS-Team/MOSS-VoiceGenerator](https://huggingface.co/OpenMOSS-Team/MOSS-VoiceGenerator) | [GitHub: OpenMOSS/MOSS-TTS](https://github.com/OpenMOSS/MOSS-TTS)
+- **Fish Speech** — Word-level fine-grained control using plain language descriptions inline in the script. Works with cloning. Note: Fish Audio S2 has a restrictive research license (commercial use requires approval), but the open-source Fish Speech model may differ. Needs license clarification. [fish.audio blog](https://fish.audio/blog/fish-audio-s2-fine-grained-ai-voice-control-at-the-word-level)
+- **VoxCPM 1.5** — Tokenizer-free continuous diffusion + autoregressive. No discrete token artifacts. Prosody/emotion is context-aware but automatic, not explicitly controllable via text prompt. Real-time streaming, LoRA fine-tuning. Trained on 1.8M+ hours. [GitHub: OpenBMB/VoxCPM](https://github.com/OpenBMB/VoxCPM)
+- **Pocket TTS** — 100M param CPU-first model from Kyutai Labs (Moshi team). Runs >1× realtime without GPU. No style control. Broadens hardware support significantly. [GitHub: kyutai-labs/pocket-tts](https://github.com/kyutai-labs/pocket-tts)
 - **Watch list:** MioTTS-2.6B (fast LLM-based EN/JP, vLLM compatible), Oolel-Voices (Soynade Research, expressive modular control)
- **Skipped:** Fish Audio S2 — restrictive research license (commercial use requires approval), despite strong features

 ### Adding a New Engine (Now Straightforward)

-With the multi-engine architecture shipped, adding a new TTS engine requires:
+With the model config registry and shared `EngineModelSelector` component, adding a new TTS engine requires:

 1. **Create `backend/backends/<engine>_backend.py`** — implement `TTSBackend` protocol (~200-300 lines)
-2. **Register in `backend/backends/__init__.py`** — add to `TTS_ENGINES` dict + factory function
+2. **Register in `backend/backends/__init__.py`** — add `ModelConfig` entry + `TTS_ENGINES` entry + factory elif
 3. **Update `backend/models.py`** — add engine name to regex
-4. **Update `backend/main.py`** — add engine cases in generate, stream, model-status, download, delete (5 dispatch points)
-5. **Update frontend** — add to engine union type, form schema, model dropdown, language map (5-6 files)
+4. **Update frontend** — add to engine union type, `EngineModelSelector` options, form schema, language map (4 files)

-Total effort: **~1 day** for a well-documented model with a PyPI package.
+`main.py` requires **zero changes** — the registry handles all dispatch automatically.
+
+Total effort: **~1 day** for a well-documented model with a PyPI package. See `docs/plans/ADDING_TTS_ENGINES.md` for the full guide.

 ---

@@ -367,13 +374,13 @@ Total effort: **~1 day** for a well-documented model with a PyPI package.

 The singleton TTS backend was replaced with a thread-safe per-engine registry in PR #254. Multiple engines can now be loaded simultaneously.

-### 2. `main.py` is 2100+ Lines
+### ~~2. `main.py` Dispatch Point Duplication~~ — RESOLVED

-All API routes, all model configs, all business logic in one file. Five separate dispatch points for each engine. Any new engine touches this file in 5 places. A model config registry pattern would reduce duplication.
+Previously, each engine required updates to 6+ hardcoded dispatch maps across `main.py` (~320 lines of if/elif chains). A model config registry in `backend/backends/__init__.py` now centralizes all model metadata (`ModelConfig` dataclass) with helper functions (`load_engine_model()`, `check_model_loaded()`, `engine_needs_trim()`, etc.). Adding a new engine requires zero changes to `main.py`.

-### 3. Model Config is Scattered (Improved)
+### ~~3. Model Config is Scattered~~ — RESOLVED

-Model identifiers are still duplicated across `main.py` (3 dicts), backend files, frontend components, and the languages constant. However, the pattern is now consistent and well-understood. A centralized model registry would help but isn't blocking.
+Model identifiers, HF repo IDs, display names, and engine metadata are now consolidated in the `ModelConfig` registry. Backend-aware branching (e.g. MLX vs PyTorch Qwen repo IDs) happens inside the registry. Frontend model options are centralized in `EngineModelSelector.tsx`.

 ### 4. Voice Prompt Cache Assumes PyTorch Tensors

@@ -410,7 +417,7 @@ The generation form now uses a flat model dropdown with engine-based routing. Pe
 | 1 | **#253** — 48kHz speech tokenizer | Quality improvement | Medium |
 | 2 | **#161** — Docker deployment | Server/headless users | Medium |
 | 3 | **#154** — Audiobook tab | Long-form users | Medium |
-| 4 | **Model config registry** | Reduce 5-dispatch-point duplication in main.py | Medium |
+| 4 | ~~**Model config registry**~~ | ~~Reduce dispatch duplication in main.py~~ | **Done** |
 | 5 | **#225** — Custom HuggingFace models | User-supplied models | High (needs rework for multi-engine) |

 ### Tier 3 — Future (v0.3.0+)
@@ -421,7 +428,7 @@ The generation form now uses a flat model dropdown with engine-based routing. Pe
 | 2 | **Pocket TTS** (Kyutai) | CPU-first 100M model, broadens hardware support. Kyutai ships clean code. Needs API vetting. |
 | 3 | **MOSS-TTS** | Text-to-voice design (no ref audio) is unique. Multi-speaker dialogue for Stories. Needs thorough API vetting. |
 | 4 | **Kokoro-82M** | 82M params, CPU realtime, Apache 2.0. Easy win. |
-| 5 | **Model config registry refactor** | Reduce 5-dispatch-point duplication in main.py — do before adding 3+ more engines |
+| 5 | ~~**Model config registry refactor**~~ | **Done** — consolidated in `backend/backends/__init__.py` + `EngineModelSelector.tsx` |
 | 6 | XTTS-v2 / Fish Speech / CosyVoice | Multi-engine arch is ready; just needs backend implementation |
 | 7 | **VoxCPM 1.5** | Tokenizer-free streaming, interesting but uncertain integration surface |
 | 8 | OpenAI-compatible API (plan doc exists) | Low effort once API is stable |
@@ -1,964 +0,0 @@
-# TTS Provider Architecture
-
-**Status:** Planned for v0.1.13
-**Created:** 2025-01-31
-**Problem:** GitHub 2GB release limit + poor UX for frequent updates requiring 2.4GB re-downloads
-
---
-
-## Overview
-
-Split the monolithic backend into modular components:
-
-1. **Main App** (~150-200MB): Tauri + FastAPI backend + Whisper + UI/profiles/history
-2. **TTS Providers** (downloadable plugins): Separate executables for model inference
-
-This architecture solves:
-
- ✅ GitHub 2GB release artifact limit
- ✅ Frequent app updates without re-downloading large python binaries
- ✅ User choice of compute backend (CPU/GPU/Cloud)
- ✅ External provider support (OpenAI, custom servers)
- ✅ Future extensibility
-
---
-
-## Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Voicebox App (Tauri + Backend)           ~150MB        │
-│  ├─ UI Layer (React)                                    │
-│  ├─ Backend (FastAPI)                                   │
-│  │  ├─ Voice Profiles                                   │
-│  │  ├─ Generation History                               │
-│  │  ├─ Audio Editing / Stories                          │
-│  │  └─ Provider Manager ◄──────────────┐                │
-│  └─ Whisper (bundled, tiny ~50MB)      │                │
-└─────────────────────────────────────────┼────────────────┘
-                                          │
-                            HTTP/IPC      │
-                                          │
-         ┌────────────────────────────────┼─────────────────┐
-         │                                │                 │
-         ▼                                ▼                 ▼
-┌─────────────────┐      ┌─────────────────┐   ┌──────────────────┐
-│ TTS Provider:   │      │ TTS Provider:   │   │ TTS Provider:    │
-│ PyTorch CPU     │      │ PyTorch CUDA    │   │ MLX (Apple)      │
-│                 │      │                 │   │                  │
-│ ~300MB          │      │ ~2.4GB          │   │ ~800MB           │
-│                 │      │                 │   │                  │
-│ Local inference │      │ GPU inference   │   │ Metal inference  │
-└─────────────────┘      └─────────────────┘   └──────────────────┘
-         │                        │                     │
-         └────────────────────────┴─────────────────────┘
-                                  │
-                    ┌─────────────▼──────────────┐
-                    │  Future Providers:         │
-                    │  • Remote Server           │
-                    │  • OpenAI API              │
-                    │  • ElevenLabs              │
-                    │  • Custom Docker Container │
-                    └────────────────────────────┘
-```
-
---
-
-## Problem Statement
-
-### Current Architecture Issues
-
-**Monolithic Binary:**
-
- CPU version: ~295MB
- CUDA version: ~2.37GB
- GitHub releases: 2GB file size limit (BLOCKED)
- Updates require re-downloading entire binary
- Poor UX: update app → restart → download CUDA update → restart again
-
-**User Pain Points:**
-
-1. Cannot release CUDA version on GitHub (over 2GB)
-2. Every app update forces 2.4GB re-download for GPU users
-3. No flexibility (can't use OpenAI, remote servers, etc.)
-4. Wastes bandwidth for small bug fixes
-
---
-
-## Solution: Pluggable TTS Providers
-
-### Component Breakdown
-
-#### 1. Main App (voicebox.exe / .app / .AppImage)
-
-**Size:** ~100-150MB
-
-**Includes:**
-
- Tauri runtime + React UI
- FastAPI backend (pure Python, no PyTorch)
- Whisper model (tiny, ~50MB)
- SQLite database
- Profile/history/audio editing logic
- Provider management system
-
-**Does NOT include:**
-
- PyTorch (CPU or CUDA)
- TTS models (Qwen3-TTS)
- Heavy ML dependencies
-
-**Updates frequently:** UI fixes, feature additions, non-ML changes
-
---
-
-#### 2. TTS Provider: PyTorch CPU
-
-**Binary:** `tts-provider-pytorch-cpu.exe`
-**Size:** ~200MB
-
-**Includes:**
-
- PyTorch CPU build
- Qwen3-TTS package
- Transformers
- No CUDA libraries
-
-**Download source:** Cloudflare R2
-**Updates rarely:** Only when model code changes
-
---
-
-#### 3. TTS Provider: PyTorch CUDA
-
-**Binary:** `tts-provider-pytorch-cuda.exe`
-**Size:** ~2.4GB
-
-**Includes:**
-
- PyTorch CUDA build (cu121)
- Qwen3-TTS package
- CUDA runtime, cuDNN, cuBLAS
- Transformers
-
-**Download source:** Cloudflare R2
-**Platform:** Windows + Linux (NVIDIA GPU)
-**Updates rarely:** Only when model code or CUDA version changes
-
---
-
-#### 4. TTS Provider: MLX
-
-**Binary:** `tts-provider-mlx`
-**Size:** ~150MB
-
-**Includes:**
-
- MLX framework
- MLX-optimized Qwen3-TTS
- Metal acceleration
-
-**Platform:** macOS only (Apple Silicon)
-**Download source:** Cloudflare R2
-
---
-
-#### 5. TTS Provider: Remote
-
-**Binary:** None (built-in config)
-**Size:** 0MB
-
-**How it works:**
-
- User provides URL to their own TTS server
- Backend proxies requests to that server
- Implements API spec from `EXTERNAL_PROVIDERS.md`
-
-**Use cases:**
-
- AMD GPU users running their own server
- Team deployments with shared GPU server
- Cloud hosting (Modal, RunPod, Replicate)
-
---
-
-#### 6. TTS Provider: OpenAI
-
-**Binary:** None (API wrapper)
-**Size:** 0MB
-
-**How it works:**
-
- User provides OpenAI API key
- Backend wraps OpenAI Audio API
- Voice profiles map to OpenAI voices
-
-**Benefits:**
-
- Zero local compute
- Pay-per-use
- Instant setup
-
---
-
-## Communication Protocol
-
-### Provider API Specification
-
-All TTS providers must implement these endpoints:
-
-#### POST /tts/generate
-
-Generate speech from text.
-
-**Request:**
-
-```json
-{
-	"text": "Hello world!",
-	"voice_prompt": {
-		/* voice prompt object */
-	},
-	"language": "en",
-	"seed": 12345,
-	"model_size": "1.7B"
-}
-```
-
-**Response:**
-
-```json
-{
-	"audio": "base64-encoded-audio",
-	"sample_rate": 24000,
-	"duration": 2.5
-}
-```
-
-#### POST /tts/create_voice_prompt
-
-Create voice prompt from reference audio.
-
-**Request:** (multipart/form-data)
-
- `audio`: Audio file
- `reference_text`: Transcript
-
-**Response:**
-
-```json
-{
-	"voice_prompt": {
-		/* serialized prompt */
-	}
-}
-```
-
-#### GET /tts/health
-
-Health check.
-
-**Response:**
-
-```json
-{
-	"status": "healthy",
-	"provider": "pytorch-cuda",
-	"version": "1.0.0",
-	"model": "Qwen3-TTS-12Hz-1.7B-Base",
-	"device": "cuda:0"
-}
-```
-
-#### GET /tts/status
-
-Model status.
-
-**Response:**
-
-```json
-{
-	"model_loaded": true,
-	"model_size": "1.7B",
-	"available_sizes": ["0.6B", "1.7B"],
-	"gpu_available": true,
-	"vram_used_mb": 1234
-}
-```
-
---
-
-## Backend Implementation
-
-### Provider Manager
-
-**File:** `backend/providers/__init__.py`
-
-```python
-class ProviderManager:
-    """Manages TTS provider lifecycle."""
-
-    def __init__(self):
-        self.active_provider: Optional[Provider] = None
-        self.config = load_provider_config()
-
-    async def start_provider(self, provider_type: str) -> str:
-        """Start a TTS provider process."""
-        if provider_type == "pytorch-cpu":
-            return await self._start_local_provider("tts-provider-pytorch-cpu.exe")
-        elif provider_type == "pytorch-cuda":
-            return await self._start_local_provider("tts-provider-pytorch-cuda.exe")
-        elif provider_type == "mlx":
-            return await self._start_local_provider("tts-provider-mlx")
-        elif provider_type == "remote":
-            return self.config["remote_url"]
-        elif provider_type == "openai":
-            return None  # No subprocess, API wrapper
-
-    async def _start_local_provider(self, binary_name: str) -> str:
-        """Start local provider subprocess."""
-        provider_path = get_provider_binary_path(binary_name)
-
-        if not provider_path.exists():
-            raise ProviderNotInstalledException(binary_name)
-
-        # Start subprocess on random port
-        port = get_free_port()
-        process = subprocess.Popen([
-            str(provider_path),
-            "--port", str(port),
-            "--data-dir", str(config.get_data_dir())
-        ])
-
-        # Wait for provider to be ready
-        await wait_for_provider_health(f"http://localhost:{port}")
-
-        self.active_provider = Provider(process, port)
-        return f"http://localhost:{port}"
-
-    async def stop_provider(self):
-        """Stop active provider."""
-        if self.active_provider:
-            self.active_provider.process.terminate()
-            self.active_provider = None
-```
-
---
-
-### Provider Abstraction
-
-**File:** `backend/providers/base.py`
-
-```python
-class TTSProvider(ABC):
-    """Abstract base for TTS providers."""
-
-    @abstractmethod
-    async def generate(
-        self,
-        text: str,
-        voice_prompt: dict,
-        language: str,
-        seed: Optional[int]
-    ) -> tuple[np.ndarray, int]:
-        """Generate speech audio."""
-        pass
-
-    @abstractmethod
-    async def create_voice_prompt(
-        self,
-        audio_path: str,
-        reference_text: str
-    ) -> dict:
-        """Create voice prompt from reference audio."""
-        pass
-```
-
-**File:** `backend/providers/local.py`
-
-```python
-class LocalProvider(TTSProvider):
-    """Provider that communicates with local subprocess via HTTP."""
-
-    def __init__(self, base_url: str):
-        self.base_url = base_url
-        self.client = httpx.AsyncClient()
-
-    async def generate(self, text, voice_prompt, language, seed):
-        response = await self.client.post(
-            f"{self.base_url}/tts/generate",
-            json={
-                "text": text,
-                "voice_prompt": voice_prompt,
-                "language": language,
-                "seed": seed
-            }
-        )
-        data = response.json()
-        audio = np.frombuffer(base64.b64decode(data["audio"]), dtype=np.float32)
-        return audio, data["sample_rate"]
-```
-
-**File:** `backend/providers/openai.py`
-
-```python
-class OpenAIProvider(TTSProvider):
-    """Provider that wraps OpenAI Audio API."""
-
-    def __init__(self, api_key: str):
-        self.client = OpenAI(api_key=api_key)
-
-    async def generate(self, text, voice_prompt, language, seed):
-        # Map voice_prompt to OpenAI voice name
-        voice = map_profile_to_openai_voice(voice_prompt)
-
-        response = await self.client.audio.speech.create(
-            model="tts-1",
-            voice=voice,
-            input=text
-        )
-
-        # Convert to numpy array
-        audio_data = response.content
-        audio, sr = load_audio_from_bytes(audio_data)
-        return audio, sr
-```
-
---
-
-## Provider Installation
-
-### Download Manager
-
-**File:** `backend/providers/installer.py`
-
-```python
-class ProviderInstaller:
-    """Handles provider download and installation."""
-
-    async def download_provider(self, provider_type: str):
-        """Download provider binary from R2."""
-
-        binary_name = {
-            "pytorch-cpu": "tts-provider-pytorch-cpu.exe",
-            "pytorch-cuda": "tts-provider-pytorch-cuda.exe",
-            "mlx": "tts-provider-mlx"
-        }[provider_type]
-
-        download_url = f"https://downloads.voicebox.sh/providers/v{PROVIDER_VERSION}/{binary_name}"
-
-        # Download with progress tracking (reuse existing SSE system)
-        await download_with_progress(
-            url=download_url,
-            destination=get_provider_install_path(binary_name),
-            progress_key=f"provider-{provider_type}"
-        )
-```
-
-**Provider Storage Location:**
-
- Windows: `%APPDATA%/voicebox/providers/`
- macOS: `~/Library/Application Support/voicebox/providers/`
- Linux: `~/.local/share/voicebox/providers/`
-
---
-
-## Frontend Implementation
-
-### Provider Settings UI
-
-**Component:** `app/src/components/ServerSettings/ProviderSettings.tsx`
-
-```tsx
-export function ProviderSettings() {
-	const [selectedProvider, setSelectedProvider] =
-		useState<ProviderType>("auto");
-	const {data: installedProviders} = useQuery({
-		queryKey: ["providers", "installed"],
-		queryFn: () => apiClient.getInstalledProviders(),
-	});
-
-	return (
-		<Card>
-			<CardHeader>
-				<CardTitle>TTS Provider</CardTitle>
-				<CardDescription>Choose how Voicebox generates speech</CardDescription>
-			</CardHeader>
-			<CardContent>
-				<RadioGroup
-					value={selectedProvider}
-					onValueChange={setSelectedProvider}
-				>
-					{/* Auto-detect */}
-					<div className="flex items-center space-x-2">
-						<RadioGroupItem value="auto" id="auto" />
-						<Label htmlFor="auto">
-							<div className="font-medium">Auto-detect (Recommended)</div>
-							<div className="text-sm text-muted-foreground">
-								Automatically choose the best available provider
-							</div>
-						</Label>
-					</div>
-
-					{/* PyTorch CUDA */}
-					<div className="flex items-center justify-between">
-						<div className="flex items-center space-x-2">
-							<RadioGroupItem
-								value="pytorch-cuda"
-								id="cuda"
-								disabled={!gpuAvailable}
-							/>
-							<Label htmlFor="cuda">
-								<div className="font-medium">PyTorch CUDA (NVIDIA GPU)</div>
-								<div className="text-sm text-muted-foreground">
-									4-5x faster inference on NVIDIA GPUs
-								</div>
-							</Label>
-						</div>
-						{!installedProviders?.includes("pytorch-cuda") && gpuAvailable && (
-							<Button
-								onClick={() => downloadProvider("pytorch-cuda")}
-								size="sm"
-							>
-								Download (2.4GB)
-							</Button>
-						)}
-					</div>
-
-					{/* PyTorch CPU */}
-					<div className="flex items-center justify-between">
-						<div className="flex items-center space-x-2">
-							<RadioGroupItem value="pytorch-cpu" id="cpu" />
-							<Label htmlFor="cpu">
-								<div className="font-medium">PyTorch CPU</div>
-								<div className="text-sm text-muted-foreground">
-									Works on any system, slower inference
-								</div>
-							</Label>
-						</div>
-						{!installedProviders?.includes("pytorch-cpu") && (
-							<Button onClick={() => downloadProvider("pytorch-cpu")} size="sm">
-								Download (300MB)
-							</Button>
-						)}
-					</div>
-
-					{/* MLX (macOS only) */}
-					{isMacOS && (
-						<div className="flex items-center justify-between">
-							<div className="flex items-center space-x-2">
-								<RadioGroupItem value="mlx" id="mlx" />
-								<Label htmlFor="mlx">
-									<div className="font-medium">MLX (Apple Silicon)</div>
-									<div className="text-sm text-muted-foreground">
-										Optimized for M1/M2/M3 chips
-									</div>
-								</Label>
-							</div>
-							{!installedProviders?.includes("mlx") && (
-								<Button onClick={() => downloadProvider("mlx")} size="sm">
-									Download (800MB)
-								</Button>
-							)}
-						</div>
-					)}
-
-					{/* Remote */}
-					<div className="space-y-2">
-						<div className="flex items-center space-x-2">
-							<RadioGroupItem value="remote" id="remote" />
-							<Label htmlFor="remote">
-								<div className="font-medium">Remote Server</div>
-								<div className="text-sm text-muted-foreground">
-									Connect to your own TTS server
-								</div>
-							</Label>
-						</div>
-						{selectedProvider === "remote" && (
-							<Input placeholder="http://your-server:8000" className="ml-6" />
-						)}
-					</div>
-
-					{/* OpenAI */}
-					<div className="space-y-2">
-						<div className="flex items-center space-x-2">
-							<RadioGroupItem value="openai" id="openai" />
-							<Label htmlFor="openai">
-								<div className="font-medium">OpenAI API</div>
-								<div className="text-sm text-muted-foreground">
-									Use OpenAI's TTS API (requires API key)
-								</div>
-							</Label>
-						</div>
-						{selectedProvider === "openai" && (
-							<Input type="password" placeholder="sk-..." className="ml-6" />
-						)}
-					</div>
-				</RadioGroup>
-			</CardContent>
-		</Card>
-	);
-}
-```
-
---
-
-## File Structure
-
-```
-voicebox/
-├── backend/
-│   ├── main.py                    # Main FastAPI app (no TTS code)
-│   ├── providers/
-│   │   ├── __init__.py            # ProviderManager
-│   │   ├── base.py                # TTSProvider ABC
-│   │   ├── local.py               # LocalProvider (subprocess)
-│   │   ├── remote.py              # RemoteProvider (HTTP)
-│   │   ├── openai.py              # OpenAIProvider (API wrapper)
-│   │   └── installer.py           # Provider download logic
-│   ├── profiles.py                # Voice profile management
-│   ├── history.py                 # Generation history
-│   ├── transcribe.py              # Whisper (still bundled)
-│   └── ... (other backend modules)
-│
-├── providers/
-│   ├── pytorch-cpu/
-│   │   ├── main.py                # FastAPI server for TTS
-│   │   ├── tts_backend.py         # PyTorch TTS logic
-│   │   ├── requirements.txt       # torch (CPU), qwen-tts, transformers
-│   │   └── build.spec             # PyInstaller spec
-│   │
-│   ├── pytorch-cuda/
-│   │   ├── main.py                # FastAPI server for TTS
-│   │   ├── tts_backend.py         # PyTorch TTS logic
-│   │   ├── requirements.txt       # torch+cu121, qwen-tts, transformers
-│   │   └── build.spec             # PyInstaller spec
-│   │
-│   └── mlx/
-│       ├── main.py                # FastAPI server for TTS
-│       ├── mlx_backend.py         # MLX TTS logic
-│       ├── requirements.txt       # mlx, qwen-tts-mlx
-│       └── build.spec             # PyInstaller spec
-│
-├── app/                           # Frontend (Tauri + React)
-│   └── src/
-│       └── components/
-│           └── ServerSettings/
-│               └── ProviderSettings.tsx
-│
-└── tauri/
-    └── src-tauri/
-        └── tauri.conf.json        # No externalBin for providers
-```
-
---
-
-## Migration Path
-
-### Phase 1: Refactor Backend (No User Changes)
-
-**Goal:** Abstract TTS behind provider interface
-
-1. Create `backend/providers/` module structure
-2. Implement `TTSProvider` abstract base class
-3. Create `LocalProvider` wrapper for current PyTorch code
-4. Modify `backend/tts.py` to use provider abstraction
-5. Keep PyTorch bundled in main app
-
-**Result:** Code is prepared, but user experience unchanged
-
---
-
-### Phase 2: Build Provider Binaries
-
-**Goal:** Create standalone TTS provider executables
-
-1. Create separate PyInstaller specs for each provider
-2. Build provider executables:
-   - `tts-provider-pytorch-cpu.exe` (~300MB)
-   - `tts-provider-pytorch-cuda.exe` (~2.4GB)
-   - `tts-provider-mlx` (~800MB, macOS)
-3. Test subprocess communication
-4. Upload providers to Cloudflare R2
-
-**Result:** Provider binaries exist but aren't used yet
-
---
-
-### Phase 3: Remove PyTorch from Main App
-
-**Goal:** Split main app from providers
-
-1. Exclude PyTorch/Qwen3-TTS from main app PyInstaller spec
-2. Main app now requires provider download
-3. Update GitHub CI to build multiple artifacts:
-   - `voicebox-{version}-{platform}.exe` (~150MB)
-   - `tts-provider-pytorch-cpu-{version}.exe`
-   - `tts-provider-pytorch-cuda-{version}.exe`
-   - `tts-provider-mlx-{version}` (macOS)
-
-**Result:** Main app is small, providers downloaded separately
-
---
-
-### Phase 4: Add Provider UI
-
-**Goal:** User-facing provider management
-
-1. Create Provider Settings page
-2. Implement provider download UI
-3. Add provider status indicators
-4. Show active provider in UI
-
-**Result:** Users can choose and download providers
-
---
-
-### Phase 5: External Providers
-
-**Goal:** Enable remote and cloud providers
-
-1. Implement `RemoteProvider` (HTTP client)
-2. Implement `OpenAIProvider` (API wrapper)
-3. Add provider configuration UI (URLs, API keys)
-4. Document external provider API spec
-
-**Result:** Full provider ecosystem
-
---
-
-## Provider Versioning
-
-### Independent Versioning
-
-Providers have their own version numbers, independent of the main app:
-
- **App version:** `v0.2.0` (frequent updates)
- **Provider version:** `v1.0.0` (rare updates)
-
-### Compatibility Matrix
-
-**Example:**
-
-| App Version | Min Provider Version | Max Provider Version |
-| ----------- | -------------------- | -------------------- |
-| v0.2.0      | v1.0.0               | v1.x.x               |
-| v0.3.0      | v1.0.0               | v1.x.x               |
-| v0.4.0      | v1.2.0               | v1.x.x               |
-| v1.0.0      | v2.0.0               | v2.x.x               |
-
-**Backend checks compatibility:**
-
-```python
-async def check_provider_compatibility(provider_version: str) -> bool:
-    """Check if provider version is compatible with current app."""
-    min_version = "1.0.0"
-    max_version = "1.999.999"
-    return min_version <= provider_version < max_version
-```
-
-**UI shows warning if incompatible:**
-
-```
-⚠️ Provider version 0.9.0 is outdated. Update to v1.0.0+
-```
-
---
-
-## User Flows
-
-### First-Time Setup
-
-1. User downloads and installs Voicebox (~150MB)
-2. App launches → detects no TTS provider installed
-3. Shows setup wizard:
-
-   ```
-   Choose your TTS provider:
-
-   [ ] PyTorch CUDA (2.4GB)    [Download]
-       ✓ Fastest on NVIDIA GPUs
-       ✗ Requires NVIDIA GPU
-
-   [●] PyTorch CPU (300MB)     [Download]
-       ✓ Works on any system
-       ✗ Slower inference
-
-   [ ] MLX (800MB)             [Download]
-       ✓ Fast on Apple Silicon
-       ✗ macOS only (M1/M2/M3)
-
-   [ ] Remote Server
-       URL: ___________________
-
-   [ ] OpenAI API
-       API Key: ________________
-   ```
-
-4. User selects provider → downloads with progress bar
-5. Provider installs to AppData/Application Support
-6. App starts provider → ready to use
-
---
-
-### App Update Flow (No Provider Change)
-
-**Scenario:** Bug fix in UI, no backend changes
-
-1. User gets update notification: "Voicebox v0.2.1 available"
-2. Downloads update (~150MB, not 2.4GB!)
-3. Installs and restarts
-4. **Provider stays the same** (no re-download needed)
-5. App starts using existing provider
-
-**User experience:** Fast updates, no multi-GB downloads
-
---
-
-### Provider Update Flow
-
-**Scenario:** New Qwen3-TTS model version released
-
-1. User opens Settings → Provider tab
-2. Sees notification: "Provider update available (v1.1.0)"
-3. Clicks "Update Provider"
-4. Downloads new provider binary
-5. Old provider binary is replaced
-6. Restart app to use new provider
-
-**Frequency:** Rare (only when TTS model/backend changes)
-
---
-
-### Switching Providers
-
-**Scenario:** User upgrades to NVIDIA GPU
-
-1. User goes to Settings → Provider
-2. Selects "PyTorch CUDA"
-3. Clicks "Download" → downloads 2.4GB
-4. Download completes → restarts app
-5. App now uses CUDA provider
-
---
-
-## Benefits
-
-| Benefit                       | Details                                                   |
-| ----------------------------- | --------------------------------------------------------- |
-| **GitHub Releases Work**      | Main app ~150MB << 2GB limit                              |
-| **Fast Updates**              | UI/feature updates don't require re-downloading providers |
-| **User Choice**               | CPU, CUDA, MLX, OpenAI, remote server                     |
-| **External Provider Support** | Users can run their own TTS servers                       |
-| **Bandwidth Savings**         | Only download provider once, app updates are small        |
-| **Future-Proof**              | Easy to add new providers (ElevenLabs, custom models)     |
-| **Team Deployments**          | Multiple users share one remote provider                  |
-| **Cloud-Ready**               | Works with Modal, Replicate, RunPod, etc.                 |
-
---
-
-## Open Questions
-
-### 1. Provider Versioning
-
-**Question:** Should providers have independent versions or match app version?
-
-**Options:**
-
- A. Independent (providers: v1.x, app: v0.2.x)
- B. Matched (both use v0.2.x)
-
-**Recommendation:** Independent versioning with compatibility matrix
-
---
-
-### 2. Auto-Update Providers
-
-**Question:** Should providers auto-update separately from app?
-
-**Options:**
-
- A. Manual updates only (user clicks "Update Provider")
- B. Optional auto-update (user can enable)
- C. Always auto-update
-
-**Recommendation:** Optional auto-update (default off)
-
---
-
-### 3. Provider Discovery
-
-**Question:** How does app find installed providers?
-
-**Options:**
-
- A. Check standard paths in AppData/Application Support
- B. Registry (Windows) / plist (macOS)
- C. Config file with provider locations
-
-**Recommendation:** Standard paths + config fallback
-
---
-
-### 4. Fallback Behavior
-
-**Question:** What if no provider is installed?
-
-**Options:**
-
- A. Show setup wizard on first launch
- B. Block app until provider installed
- C. Allow app to run in "demo mode" (transcription only)
-
-**Recommendation:** Setup wizard on first launch
-
---
-
-### 5. Provider Auto-Start
-
-**Question:** Should provider start automatically with app?
-
-**Options:**
-
- A. Always start selected provider on app launch
- B. Start on-demand (when user generates speech)
- C. User preference
-
-**Recommendation:** Auto-start (configurable in settings)
-
---
-
-## Future Enhancements
-
- [ ] **Provider Marketplace:** Built-in directory of community providers
- [ ] **Multi-Provider Support:** Use different providers per voice/language
- [ ] **Provider Health Monitoring:** Automatic failover if provider crashes
- [ ] **Cost Tracking:** Monitor API usage for OpenAI/cloud providers
- [ ] **Performance Metrics:** Latency, throughput, VRAM usage dashboards
- [ ] **Docker Providers:** Run providers in Docker containers
- [ ] **Provider Plugins:** Load custom providers from user scripts
-
---
-
-## Related Documents
-
- [EXTERNAL_PROVIDERS.md](./EXTERNAL_PROVIDERS.md) - External provider support plan
- [OPENAI_SUPPORT.md](./OPENAI_SUPPORT.md) - OpenAI API compatibility
- [github-2gb-limit-issue.md](../github-2gb-limit-issue.md) - Original problem
- [r2-setup.md](../r2-setup.md) - Cloudflare R2 configuration
-
---
-
-## Contributing
-
-If you want to build a custom TTS provider:
-
-1. Implement the provider API spec (see above)
-2. Test with Voicebox locally
-3. Package as executable (PyInstaller, Docker, etc.)
-4. Share in GitHub Discussions
-
-**Questions?**
-
- GitHub Issues: [voicebox/issues](https://github.com/jamiepine/voicebox/issues)
- Discord: Coming soon
@@ -52,7 +52,7 @@ setup-python:
        {{ pip }} install -r {{ backend_dir }}/requirements-mlx.txt
    fi
    {{ pip }} install git+https://github.com/QwenLM/Qwen3-TTS.git
-    {{ pip }} install pyinstaller -q
+    {{ pip }} install pyinstaller ruff pytest pytest-asyncio -q
    echo "Python environment ready."

 [windows]
@@ -75,7 +75,7 @@ setup-python:
    & "{{ pip }}" install -r {{ backend_dir }}/requirements.txt
    & "{{ pip }}" install --no-deps chatterbox-tts
    & "{{ pip }}" install git+https://github.com/QwenLM/Qwen3-TTS.git
-    & "{{ pip }}" install pyinstaller -q
+    & "{{ pip }}" install pyinstaller ruff pytest pytest-asyncio -q
    Write-Host "Python environment ready."

 # Install JavaScript dependencies
@@ -234,21 +234,50 @@ build-web:

 # ─── Code Quality ────────────────────────────────────────────────────

-# Run all checks (lint + format + typecheck)
-check:
+# Run all checks (JS + Python lint + format)
+check: check-js check-python
+
+# JS/TS: lint + format + typecheck (Biome)
+check-js:
    bun run check

-# Lint with Biome
-lint:
+# Python: lint + format check (ruff)
+check-python: _ensure-venv
+    {{ venv_bin }}/ruff check {{ backend_dir }}
+    {{ venv_bin }}/ruff format --check {{ backend_dir }}
+
+# Lint with Biome (JS) + ruff (Python)
+lint: _ensure-venv
    bun run lint
+    {{ venv_bin }}/ruff check {{ backend_dir }}

-# Format with Biome
-format:
+# Format with Biome (JS) + ruff (Python)
+format: _ensure-venv
    bun run format
+    {{ venv_bin }}/ruff format {{ backend_dir }}

-# Fix lint + format issues
-fix:
+# Fix lint + format issues (JS + Python)
+fix: _ensure-venv
    bun run check:fix
+    {{ venv_bin }}/ruff check {{ backend_dir }} --fix
+    {{ venv_bin }}/ruff format {{ backend_dir }}
+
+# Python lint only
+lint-python: _ensure-venv
+    {{ venv_bin }}/ruff check {{ backend_dir }}
+
+# Python format only
+format-python: _ensure-venv
+    {{ venv_bin }}/ruff format {{ backend_dir }}
+
+# Python auto-fix lint issues
+fix-python: _ensure-venv
+    {{ venv_bin }}/ruff check {{ backend_dir }} --fix
+    {{ venv_bin }}/ruff format {{ backend_dir }}
+
+# Run Python tests
+test: _ensure-venv
+    {{ venv_bin }}/python -m pytest {{ backend_dir }}/tests -v

 # ─── Database ─────────────────────────────────────────────────────────

@@ -1,6 +1,6 @@
 {
  "name": "@voicebox/landing",
-  "version": "0.2.4",
+  "version": "0.2.3",
  "description": "Landing page for voicebox.sh",
  "scripts": {
    "dev": "bun --bun next dev --turbo",
@@ -0,0 +1,42 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { getLatestRelease } from '@/lib/releases';
+
+export const dynamic = 'force-dynamic';
+
+const PLATFORM_MAP: Record<
+  string,
+  keyof Awaited<ReturnType<typeof getLatestRelease>>['downloadLinks']
+> = {
+  'mac-arm': 'macArm',
+  'mac-intel': 'macIntel',
+  windows: 'windows',
+  linux: 'linux',
+};
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ platform: string }> },
+) {
+  const { platform } = await params;
+  const key = PLATFORM_MAP[platform];
+
+  if (!key) {
+    return NextResponse.json(
+      { error: `Unknown platform: ${platform}. Use: ${Object.keys(PLATFORM_MAP).join(', ')}` },
+      { status: 404 },
+    );
+  }
+
+  try {
+    const release = await getLatestRelease();
+    const url = release.downloadLinks[key];
+
+    if (!url) {
+      return NextResponse.json({ error: `No download available for ${platform}` }, { status: 404 });
+    }
+
+    return NextResponse.redirect(url);
+  } catch {
+    return NextResponse.redirect(`https://github.com/jamiepine/voicebox/releases/latest`);
+  }
+}
@@ -62,9 +62,9 @@ export async function getLatestRelease(): Promise<ReleaseInfo> {
        continue;
      }

-      if ((name.includes('aarch64') || name.includes('arm64')) && name.endsWith('.app.tar.gz')) {
+      if ((name.includes('aarch64') || name.includes('arm64')) && name.endsWith('.dmg')) {
        downloadLinks.macArm = url;
-      } else if (name.includes('x64') && name.endsWith('.app.tar.gz')) {
+      } else if (name.includes('x64') && name.endsWith('.dmg')) {
        downloadLinks.macIntel = url;
      } else if (name.endsWith('.msi')) {
        downloadLinks.windows = url;
@@ -83,8 +83,10 @@ export async function getLatestRelease(): Promise<ReleaseInfo> {
      version,
      totalDownloads,
      downloadLinks: {
-        macArm: downloadLinks.macArm || `${baseUrl}/voicebox_aarch64.app.tar.gz`,
-        macIntel: downloadLinks.macIntel || `${baseUrl}/voicebox_x64.app.tar.gz`,
+        macArm:
+          downloadLinks.macArm || `${baseUrl}/Voicebox_${version.replace('v', '')}_aarch64.dmg`,
+        macIntel:
+          downloadLinks.macIntel || `${baseUrl}/Voicebox_${version.replace('v', '')}_x64.dmg`,
        windows:
          downloadLinks.windows || `${baseUrl}/voicebox_${version.replace('v', '')}_x64_en-US.msi`,
        linux: downloadLinks.linux || `${baseUrl}/voicebox_x86_64-unknown-linux-gnu.AppImage`,
@@ -1,6 +1,6 @@
 {
  "name": "voicebox",
-  "version": "0.2.4",
+  "version": "0.2.3",
  "private": true,
  "workspaces": [
    "app",
@@ -1,7 +1,7 @@
 {
  "name": "@voicebox/tauri",
  "private": true,
-  "version": "0.2.4",
+  "version": "0.2.3",
  "type": "module",
  "scripts": {
    "dev": "vite",
@@ -5041,7 +5041,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"

 [[package]]
 name = "voicebox"
-version = "0.2.1"
+version = "0.2.3"
 dependencies = [
 "base64 0.22.1",
 "core-foundation-sys",
@@ -1,6 +1,6 @@
 [package]
 name = "voicebox"
-version = "0.2.4"
+version = "0.2.3"
 description = "A production-quality desktop app for Qwen3-TTS voice cloning and generation"
 authors = ["you"]
 license = ""
@@ -12,6 +12,47 @@ use tokio::sync::mpsc;
 const LEGACY_PORT: u16 = 8000;
 const SERVER_PORT: u16 = 17493;

+/// Find a voicebox-server process listening on a given port (Windows only).
+///
+/// Uses PowerShell `Get-NetTCPConnection` to look up the PID owning the port,
+/// then verifies via `tasklist` that it's a voicebox process. The caller is
+/// responsible for checking port occupancy first (e.g. `TcpStream::connect_timeout`).
+/// Replaces the previous `netstat -ano` approach which failed on systems with
+/// corrupted system DLLs (see #277).
+#[cfg(windows)]
+fn find_voicebox_pid_on_port(port: u16) -> Option<u32> {
+    use std::process::Command;
+
+    // Use PowerShell's Get-NetTCPConnection to find the PID listening on the port.
+    // This is a built-in cmdlet that doesn't depend on netstat.exe.
+    let ps_script = format!(
+        "Get-NetTCPConnection -LocalPort {} -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess",
+        port
+    );
+    if let Ok(output) = Command::new("powershell")
+        .args(["-NoProfile", "-Command", &ps_script])
+        .output()
+    {
+        let output_str = String::from_utf8_lossy(&output.stdout);
+        for line in output_str.lines() {
+            if let Ok(pid) = line.trim().parse::<u32>() {
+                // Verify this PID is a voicebox process
+                if let Ok(tasklist_output) = Command::new("tasklist")
+                    .args(["/FI", &format!("PID eq {}", pid), "/FO", "CSV", "/NH"])
+                    .output()
+                {
+                    let tasklist_str = String::from_utf8_lossy(&tasklist_output.stdout);
+                    if tasklist_str.to_lowercase().contains("voicebox") {
+                        return Some(pid);
+                    }
+                }
+            }
+        }
+    }
+
+    None
+}
+
 struct ServerState {
    child: Mutex<Option<tauri_plugin_shell::process::CommandChild>>,
    server_pid: Mutex<Option<u32>>,
@@ -68,31 +109,22 @@ async fn start_server(
    
    #[cfg(windows)]
    {
-        use std::process::Command;
-        if let Ok(output) = Command::new("netstat")
-            .args(["-ano"])
-            .output()
-        {
-            let output_str = String::from_utf8_lossy(&output.stdout);
-            for line in output_str.lines() {
-                if line.contains(&format!(":{}", SERVER_PORT)) && line.contains("LISTENING") {
-                    if let Some(pid_str) = line.split_whitespace().last() {
-                        if let Ok(pid) = pid_str.parse::<u32>() {
-                            if let Ok(tasklist_output) = Command::new("tasklist")
-                                .args(["/FI", &format!("PID eq {}", pid), "/FO", "CSV", "/NH"])
-                                .output()
-                            {
-                                let tasklist_str = String::from_utf8_lossy(&tasklist_output.stdout);
-                                if tasklist_str.to_lowercase().contains("voicebox") {
-                                    println!("Found existing voicebox-server on port {} (PID: {}), reusing it", SERVER_PORT, pid);
-                                    // Store the PID so we can kill it on exit if needed
-                                    *state.server_pid.lock().unwrap() = Some(pid);
-                                    return Ok(format!("http://127.0.0.1:{}", SERVER_PORT));
-                                }
-                            }
-                        }
-                    }
-                }
+        use std::net::TcpStream;
+        if TcpStream::connect_timeout(
+            &format!("127.0.0.1:{}", SERVER_PORT).parse().unwrap(),
+            std::time::Duration::from_secs(1),
+        ).is_ok() {
+            // Port is in use — check if it's a voicebox process
+            if let Some(pid) = find_voicebox_pid_on_port(SERVER_PORT) {
+                println!("Found existing voicebox-server on port {} (PID: {}), reusing it", SERVER_PORT, pid);
+                *state.server_pid.lock().unwrap() = Some(pid);
+                return Ok(format!("http://127.0.0.1:{}", SERVER_PORT));
+            } else {
+                return Err(format!(
+                    "Port {} is already in use by another application. \
+                     Close the other application or change the Voicebox port.",
+                    SERVER_PORT
+                ));
            }
        }
    }
@@ -102,24 +134,20 @@ async fn start_server(
    #[cfg(unix)]
    {
        use std::process::Command;
-        // Find processes listening on legacy port 8000 with their command names
        if let Ok(output) = Command::new("lsof")
            .args(["-i", &format!(":{}", LEGACY_PORT), "-sTCP:LISTEN"])
            .output()
        {
            let output_str = String::from_utf8_lossy(&output.stdout);
-            for line in output_str.lines().skip(1) { // Skip header line
-                // lsof output format: COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+            for line in output_str.lines().skip(1) {
                let parts: Vec<&str> = line.split_whitespace().collect();
                if parts.len() >= 2 {
                    let command = parts[0];
                    let pid_str = parts[1];
                    
-                    // Only kill if it's a voicebox-server process
                    if command.contains("voicebox") {
                        if let Ok(pid) = pid_str.parse::<i32>() {
                            println!("Found orphaned voicebox-server on legacy port {} (PID: {}, CMD: {}), killing it...", LEGACY_PORT, pid, command);
-                            // Kill the process group
                            let _ = Command::new("kill")
                                .args(["-9", "--", &format!("-{}", pid)])
                                .output();
@@ -137,35 +165,16 @@ async fn start_server(
    
    #[cfg(windows)]
    {
-        use std::process::Command;
-        // On Windows, find PIDs on legacy port 8000, then check their names
-        if let Ok(output) = Command::new("netstat")
-            .args(["-ano"])
-            .output()
-        {
-            let output_str = String::from_utf8_lossy(&output.stdout);
-            for line in output_str.lines() {
-                if line.contains(&format!(":{}", LEGACY_PORT)) && line.contains("LISTENING") {
-                    if let Some(pid_str) = line.split_whitespace().last() {
-                        if let Ok(pid) = pid_str.parse::<u32>() {
-                            // Get process name for this PID
-                            if let Ok(tasklist_output) = Command::new("tasklist")
-                                .args(["/FI", &format!("PID eq {}", pid), "/FO", "CSV", "/NH"])
-                                .output()
-                            {
-                                let tasklist_str = String::from_utf8_lossy(&tasklist_output.stdout);
-                                if tasklist_str.to_lowercase().contains("voicebox") {
-                                    println!("Found orphaned voicebox-server on legacy port {} (PID: {}), killing it...", LEGACY_PORT, pid);
-                                    let _ = Command::new("taskkill")
-                                        .args(["/PID", &pid.to_string(), "/T", "/F"])
-                                        .output();
-                                } else {
-                                    println!("Legacy port {} is in use by non-voicebox process (PID: {}), not killing", LEGACY_PORT, pid);
-                                }
-                            }
-                        }
-                    }
-                }
+        use std::net::TcpStream;
+        if TcpStream::connect_timeout(
+            &format!("127.0.0.1:{}", LEGACY_PORT).parse().unwrap(),
+            std::time::Duration::from_secs(1),
+        ).is_ok() {
+            if let Some(pid) = find_voicebox_pid_on_port(LEGACY_PORT) {
+                println!("Found orphaned voicebox-server on legacy port {} (PID: {}), killing it...", LEGACY_PORT, pid);
+                let _ = std::process::Command::new("taskkill")
+                    .args(["/PID", &pid.to_string(), "/T", "/F"])
+                    .output();
            }
        }
    }
@@ -1,7 +1,7 @@
 {
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "Voicebox",
-  "version": "0.2.4",
+  "version": "0.2.3",
  "identifier": "sh.voicebox.app",
  "build": {
    "beforeDevCommand": "bun run dev",
@@ -12,7 +12,7 @@
  "bundle": {
    "active": true,
    "targets": "all",
-    "createUpdaterArtifacts": false,
+    "createUpdaterArtifacts": "v1Compatible",
    "externalBin": ["binaries/voicebox-server"],
    "icon": [
      "icons/32x32.png",
@@ -1,7 +1,7 @@
 {
  "name": "@voicebox/web",
  "private": true,
-  "version": "0.2.4",
+  "version": "0.2.3",
  "type": "module",
  "scripts": {
    "dev": "vite",
Author	SHA1	Message	Date
James Pine	60c0fe3b92	isolate shutdown unload calls so one failure doesn't block the other	2026-03-16 03:50:28 -07:00
James Pine	c99828cf76	fix startup db session leak on error (rollback + close in finally)	2026-03-16 03:49:21 -07:00
James Pine	5c4b979480	suppress E402 for app.py (AMD env vars must precede torch import)	2026-03-16 03:47:56 -07:00
James Pine	2d1b0ae820	remove unused _get_cuda_dll_excludes function	2026-03-16 03:46:58 -07:00
James Pine	69486c2a77	handle null duration in story_items migration	2026-03-16 03:44:33 -07:00
James Pine	e9f63d6c57	reject model migration to subdirectory of source cache	2026-03-16 03:43:37 -07:00
James Pine	8906bee23e	fix docstring for find_voicebox_pid_on_port	2026-03-16 03:43:06 -07:00
James Pine	0dabb121c9	improve startup logging: version, platform, data dir, db stats Replace verbose startup messages with a clean summary: - App version, Python version, OS/arch - Database path (fix None display), data directory - Profile and generation counts - Backend, GPU, model cache path - Clean up stale loading_model status on startup - Remove noisy progress manager log line	2026-03-16 03:42:39 -07:00
James Pine	944ba227ca	soften select focus indicator opacity	2026-03-16 03:22:36 -07:00
James Pine	473bb3e9fb	fix take-label race in regeneration, add accessible focus to select - Use DB COUNT query instead of list length for take-N label to avoid TOCTOU race between list_versions and create_version - Add focus:bg-muted to SelectTrigger for keyboard focus visibility	2026-03-16 03:22:05 -07:00
James Pine	0d0b62ea93	address CodeRabbit review: fix 4 critical + 12 major issues Critical: - Remove dead backend.utils.validation PyInstaller hidden import - Fix story_items table rebuild to preserve track/trim/version columns - Guard cache migration against same source/destination path - Fix regeneration audio overwrite (use random uuid suffix per take) Major: - Engine selector: validate language on Qwen switch, clear stale modelSize - Sync language validation regex between profile create and generate (22 langs) - Guard CUDA download against duplicate concurrent requests - Only set model_size for engines that support multiple sizes - Fix 404 swallowed by generic except in history export - Validate audio_path before FileResponse in export-audio - Transcription: stream uploads in 1MB chunks, use robust cache check, call complete_download() on Whisper download success - Set clean version as default when effects chain validation fails - Return explicit error when Windows port occupied by non-voicebox process	2026-03-16 03:12:01 -07:00
James Pine	798cd40f05	delete stale planning docs	2026-03-16 02:59:24 -07:00
James Pine	3187344f01	add model loading status, effects preset dropdown, clean up UI Backend: - Generation service reports 'loading_model' status only when model is not yet in memory, then 'generating' once inference starts - Migrate hf_offline_patch.py from print() to logging module - Update ADDING_TTS_ENGINES.md for post-refactor file paths Frontend: - HistoryTable shows 'Loading model...' vs 'Generating...' based on step - FloatingGenerateBox: replace instruct toggle + inline effects editor with an effects preset dropdown (third dropdown after language and engine) - Instruct UI removed for now (form field preserved for future models) - Remove focus ring from Select component globally	2026-03-16 02:58:41 -07:00
James Pine	8efcc95606	update Cargo.lock	2026-03-16 02:20:19 -07:00
James Pine	87cab9473d	gitignore: stop tracking tauri/src-tauri/gen/Assets.car Compiled Xcode asset catalog gets regenerated every build. No reason to track it.	2026-03-16 02:20:02 -07:00
James Pine	7b0fbfb567	rewrite backend README, remove completed refactor plan, update style guide Replace the outdated backend README (473 lines of stale API docs and pre-refactor file tree) with a concise architecture document covering module structure, request flow, backend selection, API domain overview, and development commands. Delete REFACTOR_PLAN.md -- all phases are complete. Update STYLE_GUIDE.md to remove refactor plan references and replace the verbose target layout with the current actual structure.	2026-03-16 02:18:34 -07:00
James Pine	7c1ea0a1e1	fix: replace netstat with TcpStream + PowerShell for port detection (#277 ) On Windows, Voicebox shelled out to netstat.exe on startup to check for existing server processes. On systems with corrupted DLLs, netstat fails with 0xc0000142, causing an infinite loading loop. Replace with: - TcpStream::connect_timeout() for port-in-use checks (pure Rust) - PowerShell Get-NetTCPConnection for port-to-PID lookup (built-in cmdlet) - tasklist for process name verification (unchanged) Closes #277	2026-03-16 02:15:26 -07:00
James Pine	b3012ed10c	move CRUD and service modules into services/, platform_detect into utils/ Move 9 business-logic modules from the backend root into services/: channels, effects, history, profiles, stories, versions, export_import, transcribe, tts. Move platform_detect.py into utils/. Backend root now contains only infrastructure (app, main, config, server, models, build_binary) and docs. All 94 routes verified.	2026-03-16 02:15:20 -07:00
James Pine	88536d27f7	extract routes from main.py into domain routers (Phase 4) Split the 2,578-line main.py (90 routes) into 12 domain-specific router modules under routes/. main.py is now a 45-line entry point. New structure: - app.py: FastAPI instance, CORS, startup/shutdown, safe_content_disposition - routes/: health, profiles, channels, generations, history, transcription, stories, effects, audio, models, tasks, cuda - services/cuda.py: moved from cuda_download.py Also includes Phase 5 database/ package (from parallel agent): - database/__init__.py re-exports all symbols for backward compat - database/models.py, session.py, migrations.py, seed.py All 90 routes verified registered and app imports cleanly.	2026-03-16 02:03:15 -07:00
James Pine	89d6e364d4	move pyproject	2026-03-16 01:48:26 -07:00
James Pine	b7781951df	comment cleanup	2026-03-16 01:46:19 -07:00
James Pine	fe19a9ca47	add style guide, ruff config, generation service extraction, remove Makefile - Add backend/STYLE_GUIDE.md covering formatting, imports, types, docstrings, comments, error handling, async, logging, and naming conventions - Add pyproject.toml with ruff linter/formatter config (ERA, FIX, isort, pyupgrade) - Extract generation service (Phase 3): unified run_generation() replaces three duplicated closures, serial queue moved to services/task_queue.py - Delete Makefile in favor of justfile; update all references - Add Python lint/format/test commands to justfile (check-python, fix-python, test) - Install ruff, pytest, pytest-asyncio as dev tools in setup-python - Update REFACTOR_PLAN.md with Phase 3 and Phase 7 completion	2026-03-16 01:35:59 -07:00
Jamie Pine	439fedcbf2	update refactor plan with phase 1+2 progress	2026-03-16 01:10:59 -07:00
Jamie Pine	0813a3d9d6	refactor: remove dead code, deduplicate backends Phase 1 - delete dead code: - studio.py, migrate_add_instruct.py, utils/validation.py - duplicate _profile_to_response in main.py, duplicate asyncio import - pointless _get_profiles_dir/_get_generations_dir wrappers - duplicate LANGUAGE_CODE_TO_NAME and WHISPER_HF_REPOS constants Phase 2 - extract backends/base.py with shared utilities: - is_model_cached() replaces 7 copy-pasted HF cache checks - get_torch_device() replaces 5 device detection methods - combine_voice_prompts() replaces 5 identical implementations - model_load_progress() ctx manager replaces progress boilerplate in all backends - patch_chatterbox_f32() replaces identical monkey-patches in both chatterbox backends net -1078 lines across the backend	2026-03-16 01:10:02 -07:00
Jamie Pine	9514c6596c	migrations	2026-03-16 00:54:13 -07:00
Jamie Pine	4e84415da7	refactor start	2026-03-16 00:52:23 -07:00
Jamie Pine	82cd4bf2ef	Add dynamic download redirect routes and update README links	2026-03-15 23:22:03 -07:00
Jamie Pine	3c30c5bec1	Update README for v0.2.x: multi-engine, effects, 23 languages, fix download links	2026-03-15 17:12:47 -07:00
Jamie Pine	c9d7bc4f27	Fix macOS download links to use .dmg instead of .app.tar.gz	2026-03-15 17:03:17 -07:00
James Pine	34e17bd469	Fix LuxTTS + Chatterbox in prod: bundle espeak/perth data, fix multiprocessing - collect-all piper_phonemize to bundle espeak-ng-data for LuxTTS phonemization - Set ESPEAK_DATA_PATH in frozen builds so the C library finds bundled data - collect-all perth to bundle pretrained watermark model for Chatterbox - Add multiprocessing.freeze_support() to fix resource_tracker subprocess crash	2026-03-15 16:02:09 -07:00
James Pine	aada13a5c9	Collect all inflect files for PyInstaller (fixes typeguard inspect.getsource)	2026-03-15 14:32:10 -07:00
James Pine	de8558d197	Fix prod build: download progress, robust stderr, full tracebacks - Force tqdm disable=False in TrackedTqdm so byte progress works in prod (huggingface_hub disables tqdm based on logger level, which prevents self.n from updating — our progress tracking needs the counter even though we don't render to terminal) - Harden devnull redirect to test writability, not just None check - Add full traceback logging to all backend error handlers - Add chatterbox/luxtts/zipvoice hidden imports and metadata to spec	2026-03-15 14:23:11 -07:00
Jamie Pine	9d79ea367a	Only use --noconsole on Windows, macOS/Linux need stdout for Tauri logs	2026-03-15 12:07:35 -07:00
Jamie Pine	04316f7adc	Copy metadata for requests/transformers/huggingface-hub to fix PyInstaller metadata lookup	2026-03-15 11:35:05 -07:00
Jamie Pine	4e4361d350	Fix noconsole crash: redirect None stdout/stderr to devnull on Windows	2026-03-15 11:27:35 -07:00
Jamie Pine	e9a249587c	Collect all linacodec files for PyInstaller (fixes inspect.getsource in Vocos)	2026-03-15 11:06:13 -07:00
Jamie Pine	d8a9ed7d15	Enable updater artifacts with v1Compatible for tauri-action sig generation	2026-03-15 10:54:12 -07:00
Jamie Pine	3dbf1c200e	Revert "Bump version: 0.2.3 → 0.2.4" This reverts commit `40fcb8d917`.	2026-03-15 10:20:31 -07:00
				`@@ -0,0 +1 @@`
				`# Services layer — generation orchestration and background task management.`