Deploy AI Voiceover Locally: VoiceStudio v0.5.6

Cloud TTS (ElevenLabs and similar) bills by character and ships your script off-box. Local AI voiceover keeps audio on your machine – better for private clones, offline batches, and long runs where credits would spike. This guide deploys VoiceStudio v0.5.6: desktop installer or Docker, health checks, and the install failures that actually show up in the wild.

I burned an evening bouncing between the Electron package and Docker before /health finally returned clean. Here’s the path that stuck.

What you’re installing (and why v0.5.6)

VoiceStudio (repo debpalash/VoiceStudio) is AGPL-3.0 software for voice cloning, voice design, video dubbing, dictation, transcription, and long-form audio on your own hardware. The site claims 646 languages. v0.5.6 (23 Sep 2026 on the GitHub releases page) is the latest stable tag as of that date; release notes also call out OpenAI-compatible /v1/audio/speech.

Optional Pro sits at $99/year or $299 once on voicestudio.sh (pricing checked on the site around late Sep 2026 – confirm before you pay). The OSS build is enough to produce real AI voiceover without an account.

System requirements

Windows install docs say Python and FFmpeg bootstrap on first launch – no manual toolchain for the .exe route. Hardware table on the README / voicestudio.sh matches the GPU rows above.

Download and install AI voiceover (desktop)

Source of truth: GitHub release v0.5.6. Grab Electron only – Tauri stopped at v0.5.3; you migrate separately if you still run Tauri.

1. Installer names: VoiceStudio-Electron-0.5.6-win-x64.exe, mac arm64/x64 DMG, or Linux AppImage/deb.
2. Or the official one-liner (checksum verify per install script docs):

# macOS / Linux - latest stable Electron
curl -fsSL https://voicestudio.sh/install | sh

# Pin exactly
curl -fsSL https://voicestudio.sh/install | sh -s -- --version 0.5.6

# Windows PowerShell (non-admin is fine)
irm https://voicestudio.sh/install | iex

Finish the wizard, launch, accept first-run runtime install when asked. If it wants a speech engine: Model Catalogue → default OmniVoice pack → wait until status reads ready.

Pro tip: Installers are unsigned/ad-hoc. macOS Gatekeeper often says the app is “damaged.” Control-click → Open once, or clear quarantine per the macOS install doc – don’t re-download in a loop.

There’s a small, dumb pleasure the first time a line synthesizes on hardware you already paid for – no second tab watching a character meter climb.

Docker deploy (headless / GPU box)

Images: ghcr.io/debpalash/voicestudio:stable (Hub mirror palashdeb/omnivoice-studio:stable). Pin :0.5.6 when you want the exact tag. Generate an admin key first.

The catch: Docker runs with server mode semantics, so admin routes still want OMNIVOICE_API_KEY even when you publish only to 127.0.0.1. Desktop loopback gating is looser; don’t copy desktop assumptions into the container.

export OMNIVOICE_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
echo "$OMNIVOICE_API_KEY" # save this

docker pull ghcr.io/debpalash/voicestudio:stable

# CPU
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
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

Open http://127.0.0.1:3900, paste the key. First boot pulls ~2.4 GB of weights – tail with docker logs -f omnivoice. AMD: :stable-rocm plus --device /dev/kfd --device /dev/dri (WSL uses a different dxg path; see docker.md).

First-time config and verify

After install, do three things: skip analytics if you prefer (OMNIVOICE_ANALYTICS_DISABLED=1 in Docker), install OmniVoice from Model Catalogue (plus one ASR if you’ll clone raw audio without a transcript), then synthesize a short line in Voice workspace. History playback = stack is alive.

# Desktop or Docker once the port is up
curl -sS http://127.0.0.1:3900/health
# Expect JSON with status ok (version/device fields when fully ready)

# Optional OpenAI-shaped smoke (Docker needs the Bearer key)
curl -sS http://127.0.0.1:3900/v1/audio/speech 
 -H "Authorization: Bearer $OMNIVOICE_API_KEY" 
 -H "Content-Type: application/json" 
 -d '{"model":"tts-1","voice":"alloy","input":"Local AI voiceover check.","response_format":"wav"}' 
 --output /tmp/vs-test.wav

Docker cold start: port can answer in about a second while /health still returns 503 and /startup/progress lists PyTorch/routes/DB steps. Official docker.md: HEALTHCHECK flips healthy only after HTTP 200. Wait – don’t thrash recreate.

Common install errors and fixes

“OmniVoice GGUF Unavailable” on v0.5.6 desktop: issue #2780 tracing showed the Electron package never ships bin/omnivoice-tts-*, so is_available() correctly reports missing. Install is fine – use default in-process OmniVoice.

FATAL: OS refused to listen… ([Errno 13] / WinError 10013): Windows excluded ranges (Hyper-V, WSL, WinNAT). netsh interface ipv4 show excludedportrange protocol=tcp, then set OMNIVOICE_PORT outside those bands (troubleshooting.md).

ModuleNotFoundError: pkg_resources / half-missing transformers: antivirus often quarantines venv files while metadata still says installed. Reinstall setuptools in the backend venv (uv pip install --reinstall 'setuptools>=75,<80'), exclude .venv from Defender, keep the tree off OneDrive.

macOS “damaged” / Linux blank window: Gatekeeper Open-once, or AppImage with --disable-gpu (add --ozone-platform=x11 on stubborn Wayland).

HF 401 on pyannote: Settings → API Keys → read token; accept the model license on Hugging Face under the same account.

Upgrade and uninstall

Desktop: drop the newer Electron build over the old one – voices, projects, settings stay. Re-run Install local runtime if the wizard asks. Tauri stays on its own track; use the electron-migration doc, not the Tauri updater.

Docker: pull stable, stop/rm the container, re-run with the same volume and API key.

# Uninstall app, keep data (official script)
curl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall

# Docker cleanup (data volume optional)
docker rm -f omnivoice
docker volume rm omnivoice-data # only for a full wipe

FAQ

Do I need a GPU for AI voiceover with VoiceStudio?

No. CPU + small PyTorch works. It’s slower. Use CUDA or Apple Metal for long dubs.

Cloud ElevenLabs vs this local deploy – when does local lose?

Picture a one-off 30-second promo and a laptop that barely idles: cloud wins – no drivers, no weights, no port fights. Local loses on weak CPUs, painful ARM Docker emulation, or when you need a managed multi-region SLA. Recurring YouTube/audiobook volume plus private clones? Local stops the meter.

Why does /health 503 right after docker run?

Expected while backend init finishes. Poll /startup/progress or logs; only recreate if it stays broken after healthy would normally land.

Next: run the one-liner or Docker block, hit /health, synthesize ~15 seconds in Voice, drop the WAV on your timeline.