Merge pull request #1144 from jamiepine/prep/pr-1031

fix(setup): pin dev venv to Python 3.12

docs/content/docs/developer/architecture.mdx

@@ -48,7 +48,7 @@ These two layers communicate via HTTP on `localhost:17493`, with the frontend ma
 
 ### Tech Stack
 
-- **Framework**: FastAPI (Python 3.11+)
+- **Framework**: FastAPI (Python 3.12)
 - **TTS Engines**: Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox, Chatterbox Turbo, TADA, Kokoro
 - **Transcription**: Whisper (PyTorch or MLX-Whisper)
 - **Inference Backends**: MLX (Apple Silicon), PyTorch (CUDA / ROCm / XPU / DirectML / CPU)

docs/content/docs/developer/setup.mdx

@@ -32,11 +32,13 @@ Ensure you have these installed:
     curl -fsSL https://bun.sh/install | bash
     ```
   </Card>
-  <Card title="Python 3.11+" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
+  <Card title="Python 3.12" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
     [Download Python](https://python.org)
     ```bash
-    python --version
+    python3.12 --version  # macOS/Linux — should be 3.12.x
+    py -3.12 --version    # Windows
     ```
+    Voicebox pins its venv to 3.12 to match CI, because some dependencies have no 3.13 release yet. On Debian/Ubuntu also install `python3.12-venv`.
   </Card>
   <Card title="Rust" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="m6 9 6 6 6-6"/></svg>}>
     [Install Rust](https://rustup.rs)
@@ -65,7 +67,7 @@ Run `just --list` to see all available commands. Highlights:
 
 | Command | Description |
 |---------|-------------|
-| `just setup` | Full setup (Python venv + JS deps + dev sidecar). Detects Apple Silicon for MLX and NVIDIA/Intel Arc on Windows for accelerated PyTorch. |
+| `just setup` | Full setup (Python venv + JS deps + dev sidecar). Pins the venv to Python 3.12 (recreating a wrong-version one) and detects Apple Silicon for MLX and NVIDIA/Intel Arc on Windows for accelerated PyTorch. |
 | `just setup-python` | Python venv + dependencies only |
 | `just setup-js` | `bun install` only |
 
@@ -214,8 +216,10 @@ This installs dependencies for:
 ```bash
 cd backend
 
-# Create virtual environment
-python -m venv venv
+# Create virtual environment (use Python 3.12 — see Prerequisites)
+python3.12 -m venv venv   # macOS/Linux
+# or
+py -3.12 -m venv venv     # Windows
 
 # Activate virtual environment
 source venv/bin/activate  # macOS/Linux
@@ -277,7 +281,7 @@ bun run tauri dev
 
 <AccordionGroup>
   <Accordion title="Backend won't start">
-    - Check Python version (must be 3.11+)
+    - Check Python version (must be 3.12)
     - Ensure virtual environment is activated: `source backend/venv/bin/activate`
     - Verify all dependencies are installed: `pip install -r requirements.txt`
     - Check if port 17493 is available

docs/content/docs/overview/troubleshooting.mdx

@@ -292,13 +292,22 @@ This is expected behavior. The first generation downloads the selected TTS engin
 
 <AccordionGroup>
   <Accordion title="Python Version">
-    Ensure Python 3.11 or higher:
+    Ensure Python 3.12:
 
     ```bash
-    python --version
+    python3.12 --version  # macOS/Linux
+    py -3.12 --version    # Windows
     ```
 
-    If not, install Python 3.11+ and recreate the virtual environment.
+    Voicebox pins its venv to Python 3.12 because some dependencies have no 3.13
+    release yet. `just setup` recreates a venv that was built on the wrong version,
+    so re-running it is usually the fix.
+
+    If `just setup` can't find a usable 3.12, install one: `uv python install 3.12`
+    works anywhere; `brew install [email protected]` on macOS; `sudo apt install
+    python3.12 python3.12-venv` on Debian/Ubuntu; or on Windows install from
+    [python.org](https://python.org) / `winget install -e --id Python.Python.3.12`
+    and use the `py -3.12` launcher.
   </Accordion>
 
   <Accordion title="Virtual Environment">