VoiceStudioVoiceStudio
Esc

Installation & Setup

Install VoiceStudio on macOS, Windows, Linux, or Docker, and set up your first workspace.

VoiceStudio is an open-source, local-first speech synthesis and voice modeling platform built on Electron. It packages a native desktop interface and an automated, local Python backend to let you clone voices, design characters, transcribe audio, and run local AI agents. The application can run entirely offline on macOS, Windows, and Linux, or operate as a headless web service via Docker.

Setting Up Your First Workspace#

When you launch VoiceStudio for the first time, the application walks you through a four-step onboarding process to set up your local workspace environment:

  1. System Check: The app inspects your host hardware including CPU, system RAM, disk space, and active GPU. It requires a minimum of 8 GB of system RAM and up to 10 GB of free disk space to store the local Python runtime, audio utilities (FFmpeg and yt-dlp), and initial model weights.
    If your machine has less than 8 GB of usable RAM (for instance, on laptops where integrated graphics reserve a portion of system memory), you can bypass the block by setting the environment variable OMNIVOICE_RAM_PREFLIGHT=0 before launching the app.
  2. Model Packs: Select your starting performance tier. The installer downloads the necessary speech-to-text (ASR) and text-to-speech (TTS) engines matching your hardware. You can click to install default recommended models or open Advanced mode to fine-tune individual engine parameters and downloads.
  3. Privacy: Configure your telemetry settings. Product analytics are completely opt-in and consist only of content-free usage metadata.
  4. Enter Studio: The final step loads the core Launchpad interface, registers optional dictation shortcuts, and loads your first voice cloning demo. Learn more in Voice Cloning & Gallery and Dictation & Transcription.

Customizing Storage Locations#

By default, voice models, sidecar engines, and user data are stored in your user profile folder. If you want to place these large environments (which can reach several gigabytes) on an external SSD or a different drive, you can configure them before or during the first-run installation:

  • In the Setup Screen: Click Change... next to App environment to select an external folder. This stores the Python environment, download caches, voices, and settings on that drive.
  • Environment Variables:
    • Set OMNIVOICE_ENGINES_DIR to change the destination for sidecar engine runtimes.
    • Set OMNIVOICE_DATA_DIR to redirect the folder where your projects, settings, and voices are saved.

Installation on macOS#

VoiceStudio’s desktop app is optimized for Apple Silicon Macs running macOS 13.3 (Ventura) or newer.

Intel Macs are not supported for local backend execution. Because PyTorch no longer publishes Intel-compatible wheels for its newer dependencies, the local Python environment cannot install on Intel-based hardware. Intel Mac users can run the desktop UI to connect to a remote backend.

Installation Options#

  • DMG Package: Download the DMG file matching your hardware from the releases page and drag VoiceStudio.app into your /Applications folder.
    • Apple Silicon (M1/M2/M3/M4...): Use VoiceStudio-Electron-<version>-mac-arm64.dmg (accelerated natively by Metal Performance Shaders and Apple Neural Engine).
    • Intel Macs: Use VoiceStudio-Electron-<version>-mac-x64.dmg (UI-only mode).
  • Terminal Script: Run the unified installer script to automatically download, verify the checksum of, and install the correct DMG build:
    Bash
    curl -fsSL https://voicestudio.sh/install | sh

Bypassing Gatekeeper Quarantine#

Since local development builds and ad-hoc signed releases may trigger Gatekeeper warnings ("VoiceStudio cannot be opened because the developer cannot be verified"), use one of these methods to allow the app to launch:

  • Using Finder (GUI): Locate the app in Finder, right-click (or Control-click) VoiceStudio.app, select Open, and then click Open in the confirmation dialog. On macOS 15 Sequoia, try opening the app once, then go to System Settings → Privacy & Security, scroll down, and click Open Anyway.
  • Using Terminal: If the app is installed in /Applications, remove the quarantine attribute directly:
    Bash
    xattr -dr com.apple.quarantine "/Applications/VoiceStudio.app"

Building From Source#

To run current development builds, ensure you have the Xcode Command Line Tools, Bun, uv, Node.js 22+, and Rust installed. Open a native arm64 terminal and run:

Bash
git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun install
bun run setup:api
bun run dev

Installation on Windows#

VoiceStudio runs on Windows 10 or 11 (x64), with experimental support for Windows on ARM.

GPU & Acceleration Support#

  • NVIDIA GPUs: GPU acceleration is automatically activated if an NVIDIA GPU and driver are present. The installer handles CUDA-related dependencies out of the box; no separate CUDA Toolkit installation is needed.
  • AMD / Intel GPUs: PyTorch engines run on the CPU on Windows when no NVIDIA card is present. However, you can run the Vulkan-accelerated audio.cpp engine (which drives Breeze-TTS-2) natively on Radeon discrete cards. Learn more in Models & Hardware.
  • Windows on ARM: The interface runs natively, but Python and PyTorch operate under x64 emulation on the CPU. Windows 11 24H2 or newer is recommended for AVX2 emulation support.

Installation Options#

  • Executable Installer: Download VoiceStudio-Electron-<version>-win-x64.exe (or VoiceStudio-Electron-<version>-win-arm64.exe for ARM-based PCs) from the releases page and follow the setup wizard.
  • PowerShell Installer: Open a PowerShell console and run the automated script to resolve and start the setup wizard:
    powershell
    irm https://voicestudio.sh/install | iex

Triton & Out-of-Memory Mitigations#

On Windows machines with less than 16 GB of VRAM, compiling Triton kernels during the first synthesis can result in a CUDA Out-of-Memory (OOM) error.

  • Fix: Go to Settings → Performance and enable Disable torch.compile. Alternatively, launch the application with the environment variable TORCH_COMPILE_DISABLE=1 set.

Building From Source#

To set up a local development environment, install Git, Bun, uv, Node.js 22+, Rust, and the Microsoft C++ Build Tools (including the "Desktop development with C++" workload). Run:

powershell
git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun install
bun run setup:api
bun run dev

Installation on Linux#

VoiceStudio supports x86_64 Linux distributions using either an AppImage or a native Debian package.

Installation Options#

  • AppImage: Download the AppImage from the releases page, make it executable, and run it:
    Bash
    chmod +x VoiceStudio-Electron-*-linux-x64.AppImage
./VoiceStudio-Electron-*-linux-x64.AppImage
    The AppImage includes its own static runtime and does not require libfuse2.
  • Debian / Ubuntu Package: Download the .deb package and install it using apt:
    Bash
    sudo apt install ./VoiceStudio-Electron-<version>-linux-x64.deb
  • Shell Installer: Use the automated shell script to download the AppImage, verify its checksum, and link it to ~/.local/bin/VoiceStudio (make sure this directory is in your PATH):
    Bash
    curl -fsSL https://voicestudio.sh/install | sh
  • Arch Linux (AUR): Arch users can install the community-maintained binary package:
    Bash
    yay -S voicestudio-bin

AMD GPU Acceleration (ROCm)#

ROCm acceleration is Linux-only. By default, the installer downloads the CUDA build of PyTorch. To opt into ROCm:

  1. Ensure the ROCm userspace is installed (/opt/rocm or rocminfo is available on your PATH).
  2. Launch the AppImage with the ROCm environment flag:
    Bash
    OMNIVOICE_TORCH_VARIANT=rocm ./VoiceStudio-Electron-*-linux-x64.AppImage
    The runtime setup will reinstall the compatible ROCm wheels for PyTorch and torchaudio automatically.

Wayland & Global Shortcuts#

On Wayland sessions, system-wide dictation shortcuts utilize the org.freedesktop.portal.GlobalShortcuts portal interface. Ensure your desktop has xdg-desktop-portal running with a backend that supports global shortcuts.

Because Wayland prohibits untargeted focus injection, the transcript is left on your clipboard. If you want direct text insertion into the currently focused app, you can opt in by launching the app with:

Bash
VOICESTUDIO_WAYLAND_UNTARGETED_INSERT=1

This leverages helper utilities such as wtype, dotool, or ydotool when available on your system.

Installation with Docker#

Headless servers, remote rigs, and containerized pipelines can deploy VoiceStudio using Docker. The Docker image packages the local backend and serves the user interface over HTTP, which can be accessed from any web browser.

Authentication Requirement#

Because Docker runs behind NAT networks, the backend requires an administrator API key for all configuration and model management tasks. Generate a secure random key before starting the container:

Bash
export OMNIVOICE_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"

Running with Docker CLI#

Deploy the stable container image using one of the following commands based on your hardware configuration:

  • CPU Only:
    Bash
    docker run -d --name omnivoice \
  -p 127.0.0.1:3900:3900 \
  -e OMNIVOICE_API_KEY="$OMNIVOICE_API_KEY" \
  -v omnivoice-data:/app/omnivoice_data \
  ghcr.io/debpalash/voicestudio:stable
  • NVIDIA GPU (requires the NVIDIA Container Toolkit on the host):
    Bash
    docker run -d --name omnivoice --gpus all \
  -p 127.0.0.1:3900:3900 \
  -e OMNIVOICE_API_KEY="$OMNIVOICE_API_KEY" \
  -v omnivoice-data:/app/omnivoice_data \
  ghcr.io/debpalash/voicestudio:stable
  • AMD GPU / ROCm (uses the dedicated ROCm image and mounts the direct GPU nodes):
    Bash
    docker run -d --name omnivoice \
  --device /dev/kfd --device /dev/dri \
  -p 127.0.0.1:3900:3900 \
  -e OMNIVOICE_API_KEY="$OMNIVOICE_API_KEY" \
  -v omnivoice-data:/app/omnivoice_data \
  ghcr.io/debpalash/voicestudio:stable-rocm

Running with Docker Compose#

You can launch the deployment using the compose configurations defined in the project repository:

Bash
# CPU
docker compose -f deploy/docker-compose.yml --profile cpu up -d

# NVIDIA GPU
docker compose -f deploy/docker-compose.yml --profile gpu up -d

# AMD GPU (ROCm)
docker compose -f deploy/docker-compose.yml --profile rocm up -d

Persisting Models and Settings#

The container maps all persistent databases, user voice profiles, configuration preferences, and downloaded Hugging Face model weights to a single directory. Mount a persistent volume to /app/omnivoice_data to ensure your settings and caches survive container updates.

Uninstalling VoiceStudio#

To remove VoiceStudio completely while keeping your saved projects, custom voices, and downloaded models safe:

  • macOS / Linux (Shell Script):
    Bash
    curl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall
  • Windows (PowerShell):
    powershell
    Remove-Item Env:VOICESTUDIO_VERSION -ErrorAction SilentlyContinue
$env:VOICESTUDIO_INSTALL_MODE='uninstall'; irm https://voicestudio.sh/install.ps1 | iex

If you wish to delete your custom models, database projects, and cached engines entirely, use the in-app Data removal confirmation utility located in Settings before running the uninstallation scripts.

Documentation written with Docup