docs/install/windows.md

OmniVoice Studio — Install on Windows

This page is self-contained: follow it top to bottom and you'll end up with a working OmniVoice Studio install on Windows 10 / 11 (x64).

Prerequisites

• Windows 10 (21H2 or newer) or Windows 11, x64.
• Python 3.11+ — winget install Python.Python.3.11 (or download from python.org).
• Microsoft C++ Build Tools — required by some PyPI source distributions (pyannote.audio, occasional torch wheel rebuild). Install via the Visual Studio 2022 Build Tools with the "Desktop development with C++" workload checked.
• Bun — powershell -c "irm bun.sh/install.ps1 | iex".
• FFmpeg — winget install Gyan.FFmpeg.

Install (from source)

Run from a regular (non-admin) PowerShell:

git clone https://github.com/debpalash/OmniVoice-Studio.git
cd OmniVoice-Studio
bun install
bun run desktop-prod

The first launch creates the Python venv via uv, syncs deps, and downloads model weights. The splash screen shows progress.

Install (pre-built MSI)

Download the latest MSI from the Releases page, run it, follow the wizard. The shortcut lands in the Start menu as OmniVoice Studio.

HF_TOKEN persistence

The recommended path is the in-app Settings → API Keys panel: it writes the token to OmniVoice's encrypted SQLite store and to the canonical huggingface_hub location, so every subprocess the app spawns picks it up.

If you prefer setting an environment variable directly (power-user / CLI runs from source), use PowerShell with [Environment]::SetEnvironmentVariable:

[Environment]::SetEnvironmentVariable("HF_TOKEN","hf_yourtokenhere","User")

That writes to the user-scope environment and is picked up by every new shell — close and reopen PowerShell or your terminal to see it.

Don't use setx. setx HF_TOKEN "hf_..." works in theory but has three real gotchas that produce "I set it but it's empty" bug reports: it doesn't propagate to the current shell, it silently truncates values longer than 1024 chars, and it doesn't escape % characters. Use the in-app panel or the PowerShell one-liner above.

Full HF token guide: docs/setup/huggingface-token.md.

Triton / torch.compile OOM

On Windows, certain TTS engines (notably IndexTTS-2 and some CosyVoice paths) trigger torch.compile / Triton kernel compilation during the first synthesise call. On machines with <16 GB VRAM, that compile step can OOM before the audio render even begins — the error usually surfaces as OutOfMemoryError: CUDA out of memory or RuntimeError: Triton compilation failed.

The one-click fix: open Settings → Performance in the app and toggle "Disable torch.compile (Windows)" on. That sets the TORCH_COMPILE_DISABLE=1 env var on every engine subprocess OmniVoice spawns, which falls back to the eager-mode kernel path. You'll lose a few percent of peak throughput in exchange for the engine actually loading.

From the CLI / from source: set the env var manually before launching:

$env:TORCH_COMPILE_DISABLE = "1"
bun run desktop-prod

This setting is a no-op on macOS and Linux (the OOM is Windows-specific — the torch.compile kernel cache behaves differently on the other platforms). Tracking issue: #65.

Hugging Face token (optional but recommended)

See docs/setup/huggingface-token.md.

Troubleshooting

Hit a wall? See docs/install/troubleshooting.md.