Palash DebnathandClaude Opus 5
168e8e5c61
* fix(macos): declare the floor the app actually delivers (13.3, not 12) The app declared minimumSystemVersion 12.0 and the docs promised Monterey, while the frontend required Safari 16.4 in three independent places: Vite's default build target (baseline-widely-available = safari16.4), Tailwind v4's own documented floor, and `@property` throughout its generated utilities. On Monterey's WKWebView 15.6 the focus ring and accent surfaces resolve invalid, and a bundled dependency ships a RegExp lookbehind that is a PARSE-time SyntaxError no polyfill can reach. Option B — actually supporting 15.6 — means setting build.target back, replacing 64 color-mix() calls, dropping Tailwind v4 and replacing that dependency, indefinitely, for an OS that stopped receiving security updates in late 2024. The council was unanimous on A, and the precedent is uniform (Chrome 117, Electron 27, VS Code, Firefox 116). minimumSystemVersion is also the guard: macOS itself refuses to launch a bundle below it, so a Monterey user gets an explicit OS refusal rather than an app that opens to a blank window — which matters because the Tauri updater has no per-OS gating of its own. Docs updated in the same change (README support table, docs/install/macos.md) and the webCompat floor assertion re-derived to 16.4, so the post-floor API list must be revisited the next time the floor moves. Closes #1268 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(macos): raise the floor in the macOS overlay too, and assert it Greptile P1, and correct: Tauri merges tauri.macos.conf.json OVER the base config for a macOS build, and that file carried its own minimumSystemVersion: 12.0. Changing the base config alone decided nothing — the shipped bundle would have stayed Monterey-installable while the base config, the README and the install docs all said 13.3. Worse, the guard I added read only the base config, so it would have gone on passing. A test that validates the wrong file is not a guard; it now asserts both, with a comment saying why the overlay is the one that ships. Also per review: the changelog entry was an editorial paragraph rather than a one-line entry, and the section was missing ### Docs. Both fixed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(webcompat): the module header still described the old 12.0 floor The floor moved to 13.3/Safari 16.4 in this PR and the test was re-derived, but webCompat.js still told the next reader the oldest supported WebView was 15.6 — which would make every fill here look mandatory instead of retained for Linux's unpinnable WebKitGTK (CodeRabbit). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
8.6 KiB
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).
Important
Intel Macs are not supported. The app UI installs and launches, but the local Python backend cannot run: PyTorch stopped shipping Intel-Mac (macOS x86_64) wheels after 2.2.x, and OmniVoice's dependencies require a newer torch — so the first-run dependency install can never succeed, from the DMG or from source (#889). The app detects this at first launch and tells you directly instead of failing with a raw installer error. Your options on an Intel Mac: point the UI at a remote backend running on another machine (Settings → Sharing → Remote backend), or run OmniVoice on an Apple Silicon Mac, Windows, or Linux.
Prerequisites
Using the DMG
- macOS 13.3 (Ventura) or newer — Apple Silicon (Intel: UI only, see the note above).
- ~10 GB free disk for the app, its Python environment, and model weights.
That's it — GPU acceleration (Apple MPS) is automatic on Apple Silicon, and Python, FFmpeg, and the model weights are bundled or bootstrapped by the app itself on first launch. No toolchain needed.
Building from source
Everything above, plus the toolchain:
- Xcode Command Line Tools —
xcode-select --install(includes git and the C toolchain;curlships with macOS). - Python 3.11+ —
brew install python@3.11(or usepyenv/ the system Python if you already have ≥3.11). - Bun —
curl -fsSL https://bun.sh/install | bash. - Rust / Cargo —
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shorbrew install rust. If you use rustup, reopen the terminal or source"$HOME/.cargo/env"before runningbun run desktop-prod.
FFmpeg/FFprobe and yt-dlp are not prerequisites on any install path: the app resolves them itself (a static build ships with the Python environment; if nothing resolves, the app downloads its own checksummed build on first run). Power users can inspect or override the binaries in Settings → Audio tools — including pointing at a Homebrew copy.
Optional but recommended:
- A Hugging Face account for diarization and the larger TTS models. See docs/setup/huggingface-token.md.
Install (from source)
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,
double-click to mount, drag OmniVoice Studio.app into /Applications.
Pick the DMG that matches your Mac (check Apple menu → About This Mac → Chip/Processor):
| Mac | DMG to download |
|---|---|
| Apple Silicon (M1/M2/M3/M4…) | OmniVoice.Studio_<version>_aarch64.dmg |
| Intel | OmniVoice.Studio_<version>_x64.dmg — UI only: the local backend cannot run on Intel (#889) |
The architectures are not interchangeable: an Intel Mac cannot run the
aarch64 build (Rosetta 2 only translates the other direction — it lets Apple
Silicon run Intel apps, never the reverse). And note the Intel caveat above:
the x64 DMG installs and launches, but is only useful together with a
remote backend — the local Python backend cannot install on Intel because
PyTorch no longer ships Intel-Mac wheels. Installing from source does not
help; the dependency resolution fails the same way.
If the first launch is blocked by macOS Gatekeeper ("OmniVoice Studio cannot be opened because the developer cannot be verified"), see the next section — it opens with one right-click, no Terminal.
App is "damaged" / can't be opened (Gatekeeper)
On first launch you'll see "OmniVoice Studio cannot be opened because the developer cannot be verified" — macOS Gatekeeper blocking an app it can't trace to a paid Apple Developer account (issues #134, #72).
Why: the build is ad-hoc code-signed (a valid signature, free) but not
yet notarised by Apple, so macOS quarantines any copy downloaded from the
internet and asks you to confirm the first launch. This is expected for
open-source builds — releases are notarised (warning-free) only once the
project's Apple Developer ID pipeline is funded (see "For maintainers" below).
Confirming is safe because you downloaded from the official repo / Releases
page; for belt-and-braces, verify the SHA-256 against the *.dmg.sha256 checksum
on the release page first.
Fix — GUI, no Terminal (do this): in Finder, right-click (or Control-click) OmniVoice Studio.app → Open → click Open again in the dialog. (On macOS 15 Sequoia: double-click once, then go to System Settings → Privacy & Security, scroll down, and click "Open Anyway".) This is a one-time confirmation per install; afterwards it launches by double-click.
If you instead see the harsher "app is damaged and can't be opened. Move to Trash" with no Open option, the download was corrupted or it's a pre-signing build — re-download the latest release, or use the Terminal fallback below.
Fix — Terminal: after dragging the app into /Applications, run:
xattr -dr com.apple.quarantine "/Applications/OmniVoice Studio.app"
(Adjust the path if you put the app somewhere other than /Applications.)
That clears the quarantine attribute so Gatekeeper stops blocking the launch — a one-time fix per install.
For maintainers — enabling notarised builds
The release workflow (.github/workflows/release.yml) is already wired to
code-sign + notarise the macOS bundle; it activates automatically once these
repository secrets are set (it skips signing — producing today's unsigned
build — when they're absent):
| Secret | What |
|---|---|
APPLE_CERTIFICATE |
Developer ID Application cert, exported as a base64-encoded .p12 |
APPLE_CERTIFICATE_PASSWORD |
password for that .p12 |
APPLE_SIGNING_IDENTITY |
e.g. Developer ID Application: Your Name (TEAMID) |
APPLE_ID |
Apple ID email used for notarisation |
APPLE_PASSWORD |
an app-specific password for that Apple ID |
APPLE_TEAM_ID |
your 10-char Apple Developer Team ID |
Requires a paid Apple Developer account ($99/yr). Once set, downloaded DMGs open without the quarantine step.
Apple Silicon vs Intel
- Apple Silicon (M-series): OmniVoice automatically picks the
mlx-whisperandmlx-audiobackends where available — these use the Apple Neural Engine and Metal Performance Shaders for ~2× the throughput of the CPU path. Installing the Parakeet TDT v3 (MLX) model from Settings → Models additionally makes dictation/capture prefer theparakeet-mlxengine (25 European languages, word timestamps, ~2 GB unified memory) — it is never downloaded without that explicit install, and it is only auto-preferred when your system language is one of its 25 covered languages (other languages — CJK, Arabic, … — keep the multilingual Whisper engine so dictation coverage never regresses; pinASR_MODEL_PARAKEET_MLXto force it). - Intel Macs: the local backend is unsupported — PyTorch no longer ships Intel-Mac wheels, so the Python environment can never install (#889). The UI works only when pointed at a remote backend (Settings → Sharing → Remote backend).
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.
Troubleshooting
Hit a wall? See docs/install/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.