Spaces:
Running
Running
| # OmniVoice Studio — Install on macOS | |
| This page is self-contained: follow it top to bottom and you'll end up with a | |
| working OmniVoice Studio install on macOS (Apple Silicon or Intel). | |
| ## Prerequisites | |
| - **macOS 12 (Monterey) or newer** — Apple Silicon or Intel. | |
| - **Python 3.11+** — `brew install python@3.11` (or use `pyenv` / the system Python if you already have ≥3.11). | |
| - **Bun** — `curl -fsSL https://bun.sh/install | bash`. | |
| - **Xcode Command Line Tools** — `xcode-select --install`. | |
| - **FFmpeg** (used by the dubbing + capture pipelines) — `brew install ffmpeg`. | |
| Optional but recommended: | |
| - **A Hugging Face account** for diarization and the larger TTS models. See | |
| [docs/setup/huggingface-token.md](../setup/huggingface-token.md). | |
| ## Install (from source) | |
| ```bash | |
| git clone https://github.com/debpalash/OmniVoice-Studio.git | |
| cd OmniVoice-Studio | |
| bun install | |
| bun run desktop-prod | |
| ``` | |
| The first launch builds the Tauri shell, creates the Python venv via `uv`, | |
| syncs deps, and downloads model weights (~2.4 GB). The splash screen shows | |
| live progress for every step. | |
| ## Install (pre-built `.app`) | |
| Download the latest DMG from the | |
| [Releases page](https://github.com/debpalash/OmniVoice-Studio/releases/latest), | |
| double-click to mount, drag **OmniVoice Studio.app** into `/Applications`. | |
| If the first launch shows "app is damaged and can't be opened", that's macOS | |
| Gatekeeper — see the next section. | |
| ## Gatekeeper quarantine | |
| <a id="gatekeeper-quarantine"></a> | |
| OmniVoice Studio is currently **not notarised** — the developer-ID signing + | |
| notarisation pipeline is tracked for v0.4. Until then, macOS quarantines any | |
| copy you downloaded outside the App Store. After dragging the app into | |
| `/Applications`, run: | |
| ```bash | |
| xattr -cr "/Applications/OmniVoice Studio.app" | |
| ``` | |
| That clears the quarantine xattr so Gatekeeper stops blocking the launch. It's | |
| a one-time fix per install. The app itself is open source — verify the SHA-256 | |
| against the `*.dmg.sha256` checksum on the release page before clearing the | |
| attribute if you want belt-and-braces. | |
| ## Apple Silicon vs Intel | |
| - **Apple Silicon (M-series):** OmniVoice automatically picks the `mlx-whisper` | |
| and `mlx-audio` backends where available — these use the Apple Neural Engine | |
| and Metal Performance Shaders for ~2× the throughput of the CPU path. | |
| - **Intel macs:** falls back to `faster-whisper` (CTranslate2) on CPU. Still | |
| fast; just no ANE acceleration. | |
| The picker in **Settings → Engines** shows which backend is active. | |
| ## Hugging Face token (optional but recommended) | |
| The default install works without a token, but diarization (the | |
| `pyannote/speaker-diarization-3.1` model) is gated and the larger | |
| voice-design engines also download faster with a token attached. | |
| - Open **Settings → API Keys** in the app. | |
| - Or set the env var `export HF_TOKEN=hf_…` in `~/.zshrc`. | |
| Full details: [docs/setup/huggingface-token.md](../setup/huggingface-token.md). | |
| ## Troubleshooting | |
| Hit a wall? See [docs/install/troubleshooting.md](troubleshooting.md). | |
| The in-app error UI (the React error boundary that fires on backend errors) | |
| includes an **"Open docs for this error"** button — that button deeplinks | |
| back into this docs tree at the right section for the error class. | |