How to Set Up VoiceStudio Locally: A Complete Installation Guide

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:

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:

bun install

For npm users:

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:

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
3. Backend startup – Launches 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:

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

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

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:

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	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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}