mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-17 13:50:39 -07:00
ae91aa9a88
* docs: audit mdx docs against multi-engine backend and refresh stale content Rewrote developer-facing docs that predated the TTSBackend Protocol / ModelConfig registry refactor (architecture, tts-generation, model-management, transcription). Updated user-facing docs to reflect all seven shipped engines (Qwen, Qwen CustomVoice, LuxTTS, Chatterbox, Chatterbox Turbo, TADA, Kokoro) instead of the outdated "5 engines" claim. Also fixes: - Stale app identifier (com.voicebox.app → sh.voicebox.app) - CUDA backend update flow (now two-archive split, not N-way chunks) - Whisper model list (removed tiny, added turbo) - Broken /development/ and /guides/ route links - Stale just commands and install steps (missing --no-deps chatterbox/tada) - Removed ASCII art diagrams from README and stories.mdx - History Generation schema sync with DB model Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * docs: add DeepWiki badge to README Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * docs: address PR review feedback - architecture.mdx: fix backends/ file list (remove nonexistent qwen_backend.py, rename tada_backend.py → hume_backend.py) - model-management.mdx: Kokoro language count 9 → 8 (matches ModelConfig) - model-management.mdx: ProgressManager path services/ → utils/ - tts-generation.mdx: ModelConfig example uses field(default_factory=...) — mutable default would raise at runtime - tts-generation.mdx: "1080p samples" → "on CUDA" (1080p is video, not audio) - PROJECT_STATUS.md: replace ASCII architecture diagram with prose (matches no-ASCII-art rule) Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(app): guard against undefined engine in FloatingGenerateBox preset check form.getValues('engine') returns string | undefined; Set<string>.has() rejects undefined under strict mode. Added a truthy guard before the preset lookup. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
147 lines
3.4 KiB
Plaintext
147 lines
3.4 KiB
Plaintext
---
|
|
title: "Remote Mode"
|
|
description: "Connect to a GPU server for faster generation"
|
|
---
|
|
|
|
## Overview
|
|
|
|
Remote Mode allows you to run the Voicebox backend on a separate machine (like a GPU server) while using the desktop app on your local machine.
|
|
|
|
## Use Cases
|
|
|
|
- **No local GPU** - Use a cloud GPU or remote workstation
|
|
- **Faster generation** - Leverage powerful remote hardware
|
|
- **Shared infrastructure** - Multiple users connect to one server
|
|
- **Laptop workflows** - Keep your laptop cool and battery-efficient
|
|
|
|
## Architecture
|
|
|
|
In Remote Mode, the Voicebox desktop app (running on your local machine) communicates with the backend server (running on a remote machine) via HTTP. The local app provides only the user interface, while the remote server handles all the heavy processing including the TTS models, API endpoints, and audio generation.
|
|
|
|
## Setting Up Remote Mode
|
|
|
|
### On the Server
|
|
|
|
<Steps>
|
|
<Step title="Install Dependencies">
|
|
```bash
|
|
# Clone the repo
|
|
git clone https://github.com/jamiepine/voicebox.git
|
|
cd voicebox/backend
|
|
|
|
# Install Python dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Engines with incompatible transitive pins — install with --no-deps
|
|
pip install --no-deps chatterbox-tts
|
|
pip install --no-deps hume-tada
|
|
|
|
# Qwen3-TTS from source
|
|
pip install git+https://github.com/QwenLM/Qwen3-TTS.git
|
|
```
|
|
|
|
Or just run `just setup` from the repo root, which handles all of this.
|
|
</Step>
|
|
|
|
<Step title="Start the Server">
|
|
```bash
|
|
# Allow external connections
|
|
uvicorn main:app --host 0.0.0.0 --port 17493
|
|
```
|
|
|
|
<Callout type="warn">
|
|
This exposes the server to your network. Use a firewall or VPN for security.
|
|
</Callout>
|
|
</Step>
|
|
|
|
<Step title="Open Firewall">
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo ufw allow 17493
|
|
|
|
# Or use your cloud provider's firewall settings
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
### On the Client
|
|
|
|
<Steps>
|
|
<Step title="Open Settings">
|
|
In Voicebox, go to **Settings → Server**
|
|
</Step>
|
|
|
|
<Step title="Enable Remote Mode">
|
|
Toggle **Use Remote Server**
|
|
</Step>
|
|
|
|
<Step title="Enter Server URL">
|
|
```
|
|
http://<server-ip>:17493
|
|
```
|
|
|
|
Replace `<server-ip>` with your server's IP address
|
|
</Step>
|
|
|
|
<Step title="Test Connection">
|
|
Click **Test Connection** to verify
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Cloud Deployment
|
|
|
|
### AWS EC2
|
|
|
|
```bash
|
|
# Launch a GPU instance (e.g., g4dn.xlarge)
|
|
# Install dependencies
|
|
# Start server with --host 0.0.0.0
|
|
```
|
|
|
|
### Vast.ai
|
|
|
|
```bash
|
|
# Rent a GPU instance
|
|
# SSH in and clone repo
|
|
# Start server
|
|
```
|
|
|
|
### RunPod
|
|
|
|
```bash
|
|
# Deploy a pod with CUDA support
|
|
# Install Voicebox backend
|
|
# Expose port 17493
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
<Callout type="warn">
|
|
The API currently has no authentication. Only use on trusted networks or with a VPN.
|
|
</Callout>
|
|
|
|
**Best Practices:**
|
|
- Use a VPN (WireGuard, Tailscale) instead of exposing to the internet
|
|
- Run behind a reverse proxy with authentication (nginx + basic auth)
|
|
- Use HTTPS with SSL certificates
|
|
- Firewall rules to limit access to specific IPs
|
|
|
|
## Performance
|
|
|
|
Expected performance on various GPUs:
|
|
|
|
| GPU | Generation Speed |
|
|
|-----|------------------|
|
|
| RTX 4090 | ~2-3s per 10 words |
|
|
| RTX 3090 | ~3-4s per 10 words |
|
|
| RTX 3060 | ~5-7s per 10 words |
|
|
| CPU (12-core) | ~20-30s per 10 words |
|
|
|
|
<Callout type="info">
|
|
A GPU with 8GB+ VRAM is recommended for best performance.
|
|
</Callout>
|
|
|
|
## Troubleshooting
|
|
|
|
See the [Troubleshooting Guide](/overview/troubleshooting) for common issues.
|