# How to Set Up the VoiceStudio Backend Locally: FastAPI Setup Guide

> Learn how to set up the VoiceStudio backend locally. Follow this FastAPI setup guide to clone, install dependencies, configure env, and launch the server with simple commands. Get started today!

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: how-to-guide
- Published: 2026-09-11

---

**To set up the VoiceStudio backend locally, clone the repository, install Python 3.11+ dependencies using `uv sync`, optionally create a `.env` file with `OMNIVOICE_API_KEY` for admin access, and launch the server with `uv run python backend/main.py` on port 3900.**

VoiceStudio is an open-source voice synthesis and recognition platform built with FastAPI. This guide walks you through exactly how to set up the VoiceStudio backend locally using the source code from the `debpalash/VoiceStudio` repository.

## Prerequisites

Before starting, ensure your environment meets the following requirements:

- **Python 3.11 or higher** installed on your system
- **uv** installed as the Python package manager (a fast, modern replacement for `pip` and `venv`)
- Git for cloning the repository

## Step-by-Step Local Installation

Follow these sequential steps to get the VoiceStudio backend running on `localhost:3900`.

### Clone the Repository

First, download the source code from GitHub and navigate into the project directory:

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

```

### Install Dependencies with uv

VoiceStudio uses `uv` for reproducible environment management. Running the sync command creates a virtual environment and installs all required packages:

```bash
uv sync

```

This command reads the project dependencies and constructs a `.venv` directory with the exact package versions specified in the repository's lock file.

### Configure Environment Variables (Optional)

For local development, most features work without configuration. However, if you need access to **admin-only routes**, you must set the `OMNIVOICE_API_KEY` environment variable.

Create a `.env` file in the project root:

```bash
cat <<EOF > .env
OMNIVOICE_API_KEY=$(python -c "import secrets, sys; print(secrets.token_urlsafe(32))")
EOF

```

The [`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py) file automatically loads variables from `.env` on startup. The `OMNIVOICE_SERVER_MODE` flag is used for Docker deployments and is **not required** for local runs.

### Start the FastAPI Server

The entry point is located at [`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py). You have two methods to launch the server:

**Method 1: Using uvicorn directly**

```bash
uv run python -m uvicorn backend.main:app --host 127.0.0.1 --port 3900

```

**Method 2: Using the bundled convenience script**

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

```

When the server starts, the `lifespan` context manager (lines 31-35 in [`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py)) initializes the application. This context performs admin-key validation via `core.auth.validate_server_admin_key` and triggers deferred startup sequences in [`backend/services/model_manager.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/services/model_manager.py) to pre-load TTS and ASR engines.

### Verify the Installation

Confirm the backend is responding correctly by querying the voices endpoint:

```bash
curl http://127.0.0.1:3900/v1/audio/voices

```

A successful response returns a JSON object containing available voice models:

```json
{
  "voices": [...]
}

```

## Key Backend Components

Understanding these core files helps with troubleshooting and customization:

- **[`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py)** – The primary entry point that configures import paths, loads environment variables, registers API routers from `backend/api/`, and constructs the FastAPI application.
- **`backend/api/`** – Directory containing REST route handlers for audio processing, TTS (text-to-speech), ASR (automatic speech recognition), and OpenAI-compatible endpoints.
- **[`backend/services/model_manager.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/services/model_manager.py)** – Handles heavy initialization tasks including model loading, engine warm-up, and watermark pool startup that runs after the server binds to the port.
- **[`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py)** – Central configuration hub defining log paths, cache directories, and default port settings (3900).

## Docker Alternative

If you prefer containerized deployment instead of a local Python environment, the repository includes Docker configuration in [`deploy/docker-compose.yml`](https://github.com/debpalash/VoiceStudio/blob/main/deploy/docker-compose.yml). The Docker setup requires the same `OMNIVOICE_API_KEY` environment variable for administrative functions. See [`docs/install/docker.md`](https://github.com/debpalash/VoiceStudio/blob/main/docs/install/docker.md) for container-specific instructions.

## Summary

- **VoiceStudio** requires **Python 3.11+** and uses **uv** for dependency management via `uv sync`.
- The backend entry point is **[`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py)**, which launches a FastAPI service on **port 3900**.
- Set **`OMNIVOICE_API_KEY`** in a `.env` file only if you need admin route access; it is not required for basic local operation.
- Start the server using **`uv run python backend/main.py`** or the uvicorn equivalent.
- Verify functionality by requesting **`/v1/audio/voices`** via curl or a FastAPI TestClient.

## Frequently Asked Questions

### What is the minimum Python version required for VoiceStudio?

VoiceStudio requires **Python 3.11 or higher**. This requirement is enforced by the project's dependency specification and the modern Python features used in the FastAPI implementation.

### Why do I need an API key for local development?

You only need the **`OMNIVOICE_API_KEY`** if you intend to use admin-only routes or the administrative UI. For standard TTS, ASR, and audio processing endpoints, the backend runs without any authentication when executed locally. The key is validated through the `validate_server_admin_key` function in the `lifespan` context manager.

### Can I use pip instead of uv to install dependencies?

While the repository is optimized for `uv` (as evidenced by the `uv sync` command and project structure), you can theoretically install requirements manually if you extract them from the project's configuration files. However, using `uv` ensures you match the exact environment specified by the maintainers and avoids dependency conflicts.

### How do I change the default port from 3900?

The default port is defined in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py). You can override it by setting the appropriate environment variable in your `.env` file or by passing the `--port` argument when launching with uvicorn (e.g., `uvicorn backend.main:app --port 8080`).