# How to Set Up VoiceStudio Locally: A Complete Installation Guide

> Learn how to set up VoiceStudio locally with our easy-to-follow guide. Install Node and Python, clone the repo, and launch the application to start your local VoiceStudio setup.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: getting-started
- Published: 2026-09-05

---

**To set up VoiceStudio locally, install Node 20+ and Python 3.11+, clone the repository, install dependencies with `bun install`, and launch the application with `bun run desktop`—the first run automatically creates a Python virtual environment with `uv` and downloads the default model.**

VoiceStudio is a cross-platform desktop application that combines a **Tauri v2** frontend shell with a **FastAPI** backend. This open-source voice cloning and text-to-speech studio runs entirely on your local hardware at `localhost:3900`. Whether you need the full desktop experience or prefer an API-only deployment, this guide covers every setup path based on the official source code.

## Prerequisites

Before installing VoiceStudio, ensure your system meets these requirements:

- **Node.js 20+** or **Bun** – Required for building and running the UI
- **Python 3.11+** – Runtime for the FastAPI backend
- **uv** – Fast Python package and environment manager (installed automatically on first launch)
- **Git** – For cloning the repository

## Clone the Repository

Start by fetching the complete source tree:

```bash
git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio

```

The repository structure separates the desktop shell (`frontend/src-tauri/`), the React UI (`frontend/src/`), and the Python backend (`backend/`).

## Install UI Dependencies

VoiceStudio uses **Bun** as its preferred package manager, though `npm` works as an alternative:

```bash
bun install

```

For `npm` users:

```bash
npm ci

```

This command installs the React + Vite toolchain and Tauri CLI tools needed to build the desktop application.

## Launch the Desktop Application

The standard way to run VoiceStudio locally is through the Tauri desktop launcher:

```bash
bun run desktop

```

This command orchestrates multiple setup steps automatically:

1. **Environment creation** – Creates `backend/.venv` using `uv` if it doesn't exist
2. **Python dependency installation** – Installs packages from [`backend/pyproject.toml`](https://github.com/debpalash/VoiceStudio/blob/main/backend/pyproject.toml)
3. **Backend startup** – Launches [`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py), which binds to `localhost:3900`
4. **Deferred model loading** – Heavy imports (PyTorch, CTranslate2) load in a background thread while `/health` responds in ~1 second

The first launch downloads the default **OmniVoice model** (~2 GB) into `omnivoice_data/`. Subsequent launches reuse both the virtual environment and cached models.

### Architecture Overview

```

Tauri desktop shell → IPC → FastAPI backend (localhost:3900)
   ↳ React + Vite UI (served from frontend/dist)
   ↳ Engine registries (backend/engines/)
   ↳ Worker system for remote GPU workers (backend/worker/)
   ↳ SQLite + Alembic storage (omnivoice_data/)

```

## Run the Backend Only (API-Only Mode)

For headless deployments or integration workflows, skip the desktop shell entirely:

```bash
uv run python backend/main.py

```

The server starts immediately on `http://localhost:3900` with these endpoints available:

- **OpenAI-compatible API** – `/v1/audio/speech`, `/v1/audio/transcriptions`
- **Server-Sent Events** – Real-time stream progress updates
- **WebSocket** – Low-latency audio streaming
- **MCP server** – Model Context Protocol for agent integration

### Test the Local API with Python

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:3900/v1", api_key="local")

resp = client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="default",
    input="Hello from my own hardware!",
    response_format="wav",
)
resp.stream_to_file("hello.wav")

```

### Test with curl

```bash
curl http://localhost:3900/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"default","input":"Hello world!","response_format":"wav"}' \
  --output hello.wav

```

## Docker Deployment

For reproducible environments or server deployments, use the official container:

```bash
docker run -d \
  -p 127.0.0.1:3900:3900 \
  -v omnivoice-data:/app/omnivoice_data \
  --name voicestudio \
  palashdeb/omnivoice-studio:stable

```

This binds the API to localhost only and persists model data in a named volume.

## Key Source Files and Their Roles

| Path | Purpose |
|------|---------|
| [`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py) | FastAPI entry point with deferred startup logic (lines 998-1022 implement the background loading pattern) |
| `frontend/src-tauri/` | Tauri v2 desktop shell—window lifecycle, system tray, auto-updater |
| `frontend/src/` | React + Vite SPA—UI components and state management |
| `backend/engines/` | TTS/ASR engine adapters (OmniVoice, WhisperX, etc.) |
| `backend/worker/` | Remote GPU worker orchestration and authentication |
| `docs/install/` | Platform-specific installation guides |

The deferred startup implementation in [`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py) is particularly notable—all heavy ML frameworks load after the socket binds, keeping the `/health` endpoint responsive within approximately one second even as multi-gigabyte models initialize.

## Summary

- **Install Node 20+ and Python 3.11+** as base prerequisites
- **Use `bun run desktop`** for the full local setup—automatically handles Python environment and model downloads
- **Use `uv run python backend/main.py`** for API-only deployments without the desktop shell
- **Consider Docker** for reproducible server environments or CI/CD pipelines
- **Expect ~2 GB download** on first launch for the default OmniVoice model cache

## Frequently Asked Questions

### What if the first launch takes a long time?

The initial `bun run desktop` command creates a Python virtual environment with `uv`, installs dependencies, and downloads the ~2 GB OmniVoice model. This one-time setup typically completes in 5–10 minutes depending on connection speed. Monitor `omnivoice_data/` for download progress.

### Can I use VoiceStudio without the desktop UI?

Yes. Running `uv run python backend/main.py` starts the FastAPI server independently. The OpenAI-compatible API at `localhost:3900/v1` supports all core TTS and ASR functions, making it suitable for server deployments or integration with other applications.

### How do I update VoiceStudio after the initial setup?

Pull the latest changes with `git pull`, then run `bun install` to update Node dependencies and `bun run desktop` to trigger any Python dependency updates. The `uv` tool handles incremental package updates automatically.

### Where are models and project data stored?

All persistent data lives in the `omnivoice_data/` directory: SQLite databases for project storage, Alembic migration state, and downloaded TTS/ASR model weights. Back up this directory to preserve your work and avoid re-downloading models.