VoiceStudio's macOS desktop app is built with Electron. The archived Tauri app is no longer maintained; if you still run it, follow the migration guide.
Important
Intel Macs are not supported for the local backend (app UI only).
PyTorch stopped shipping Intel-Mac (macOS
x86_64) wheels after 2.2.x and VoiceStudio's dependencies need a newer torch,
so a local Python backend cannot install on an Intel Mac — from the DMG or
from source (#889).
On Intel, packaged setup stops before creating a Python environment or
downloading dependencies and shows remote-backend guidance instead: use the
remote connection controls on the setup screen to point the app at a backend
on another machine, or run VoiceStudio on an Apple Silicon Mac, Windows, or
Linux. A source checkout behaves the same way: bun run setup:api stops
before syncing anything, and the app opens the same remote-backend screen
instead of reporting an incomplete Python environment
(#3584).
- macOS 13.3 (Ventura) or newer on Apple Silicon (Intel: UI only, see the note above).
- ~10 GB free disk for the app, its Python environment, and model weights.
GPU acceleration (Apple MPS) is automatic on Apple Silicon. Python, FFmpeg, and model weights are bootstrapped by the app itself on first launch; no toolchain is needed for the packaged app.
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.
The official tap installs the released DMG for your Mac’s architecture:
brew tap debpalash/tap
brew trust --cask debpalash/tap/voicestudio
brew install --cask debpalash/tap/voicestudioThe trust step is required by recent Homebrew versions for third-party casks.
Check the cask before trusting it with brew cat --cask debpalash/tap/voicestudio.
Intel Macs still need a backend on another computer. If macOS blocks the first
launch, follow the Gatekeeper instructions.
Download the DMG that matches your Mac (check Apple menu → About This Mac →
Chip/Processor) from the
Releases page,
double-click to mount it, and drag VoiceStudio.app into /Applications.
Current builds link the bundled voicestudio command into ~/.local/bin on
the first launch of the installed app (or during shell-script installation), and
add that folder to your shell profiles (~/.zshrc, ~/.profile) once if your shell does not
already search it. Open a new terminal afterwards: voicestudio opens the app,
voicestudio --help shows the CLI, and commands start the app in the background
when it is not running. Python and uv are not required. Existing custom launchers
are preserved; see the CLI migration instructions.
| Mac | DMG to download |
|---|---|
| Apple Silicon (any M-series chip) | VoiceStudio-<version>-mac-arm64.dmg |
| Intel | VoiceStudio-<version>-mac-x64.dmg — UI only: the local backend cannot run on Intel (#889) |
Every Apple Silicon Mac takes the arm64 DMG, including chips newer than this
page: VoiceStudio checks the CPU architecture, never the chip's name. If macOS
says VoiceStudio "is not supported on this Mac" or asks you to install Rosetta,
you opened the x64 DMG; install the arm64 one instead (#3074).
The architectures are not interchangeable: an Intel Mac cannot run the
arm64 build (Rosetta 2 only translates the other direction). An Apple
Silicon Mac can open the x64 build through Rosetta, but its local backend
then needs the Intel-only PyTorch wheels that no longer exist, so setup stops
and offers the Apple Silicon download instead. Install the arm64 DMG over it;
your voices and projects are kept. Compare the download with the release's
SHA256SUMS.txt before opening it.
Or install the latest release from Terminal with the
shell installer, which picks the right DMG, verifies its
checksum, and installs VoiceStudio.app into /Applications (or
~/Applications when /Applications is not writable):
curl -fsSL https://voicestudio.sh/install | shIf the first launch is blocked by macOS Gatekeeper (a "developer cannot be verified" or "damaged" dialog), see the next section for the fix.
macOS may refuse to open VoiceStudio with one of two dialogs. Both come from Gatekeeper, and neither means the download is broken:
- "VoiceStudio is damaged and can't be opened. Move to Trash": Gatekeeper
is rejecting an app that carries the browser's
com.apple.quarantineattribute but has no Apple Developer ID signature and no notarization. The wording is misleading; nothing is corrupt. - "VoiceStudio cannot be opened because the developer cannot be verified": the milder form of the same check, which offers an Open path.
The release workflow requires Developer ID signing and notarization unless an
unsigned release is explicitly approved. Older releases and local test builds
may be signed ad hoc (identity: '-'), which is not an Apple identity. Check
the signing status for the specific release you downloaded. Environments that
require signed, notarized apps must use a qualifying release; bypassing
Gatekeeper is not a substitute.
Check the download first. Compute its SHA-256 and compare it with
SHA256SUMS.txt from the same GitHub Release:
shasum -a 256 ~/Downloads/VoiceStudio*.dmgIf the values match, the file is intact and downloading it again will give the same dialog. Only re-download when the checksum does not match.
Fix for "damaged" (Terminal). After dragging the app into /Applications,
clear the quarantine attribute:
xattr -dr com.apple.quarantine "/Applications/VoiceStudio.app"(Change the path if the app lives elsewhere.) This is a one-time step per install. The shell installer already does it for you, and also repairs the signature of older releases.
If a build still refuses to open, re-sign it ad hoc on your own Mac and verify the result:
codesign --force --deep --sign - "/Applications/VoiceStudio.app"
codesign --verify --deep --strict "/Applications/VoiceStudio.app"The verify command prints nothing when the signature is valid.
Fix for "developer cannot be verified" (no Terminal). In Finder, right-click (or Control-click) VoiceStudio.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". You confirm once per install; later launches work by double-click.
The maintained Electron release workflow uses a Developer ID Application
certificate (ELECTRON_MACOS_CSC_LINK and ELECTRON_MACOS_CSC_KEY_PASSWORD)
plus APPLE_API_KEY, APPLE_API_KEY_ID and APPLE_API_ISSUER for
notarization with an App Store Connect team API key. See the release guide
for all platform credentials and verification gates. An Apple Developer
membership is required; the archived Tauri workflow's APPLE_CERTIFICATE
secrets do not sign Electron installers.
Use this for development or to run current main. To build and install a
desktop package from main without a checkout, use the shell installer's
--main mode. Local source builds are not
local-backend capable on Intel Macs either.
Prerequisites (use a native arm64 terminal on Apple Silicon):
- Xcode Command Line Tools —
xcode-select --install(includes git and the C toolchain;curlships with macOS). - Bun —
curl -fsSL https://bun.sh/install | bash. - uv —
curl -LsSf https://astral.sh/uv/install.sh | sh(it provides the managed Python 3.11 the backend uses). - Node.js 22.12.0 or newer and Rust / Cargo (
brew install rust, or rustup — reopen the terminal or source"$HOME/.cargo/env"afterwards) for the Electron native helper.
git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
node electron/scripts/node-version.mjsIf the Node check fails, stop here, upgrade Node.js, and reopen your terminal before continuing. Then install dependencies and prepare the local backend (skip API setup when using an external backend or an Intel Mac):
bun install
bun run setup:api # create the Python environment with uv
bun run dev # Electron with hot reload; it starts and supervises the backendUse bun run desktop-prod to build and launch the production bundle, or
bun run dist to create local DMG/zip packages in electron/release/ without
publishing. Local packages are unsigned. See
Electron setup for backend configuration.
- Apple Silicon (M-series): VoiceStudio 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 Model Catalogue (ASR tab → the engine's Weights) 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 connected to a remote backend.
The picker in Model Catalogue shows which backend is active.
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 → Credentials in the app.
- Or set the env var
export HF_TOKEN=hf_…in~/.zshrc.
Full details: docs/setup/huggingface-token.md.
Hit a wall? See docs/install/troubleshooting.md.
The in-app error UI includes an "Open docs for this error" button that deeplinks back into this docs tree at the right section for the error class.
If setup fails with You're on macOS (macosx_…_x86_64), but torch … only has wheels for … macosx_11_0_arm64, the runtime is being built for Intel. On an
Apple Silicon Mac that means the x64 DMG (or a Rosetta terminal for source
installs) is in use: install the mac-arm64 DMG, or run bun run setup:api
from a native arm64 terminal (uname -m prints arm64). On an Intel Mac the
local backend is unsupported; connect to a remote backend instead.
A process that exits while shutdown is signalling it can report a macOS permission error. VoiceStudio accepts this only after confirming the original process exited without being reaped (macOS can take a moment to report that exit, so it waits up to a quarter of a second), then still waits for nested operations to drain. Live-process permission errors and lost process ownership remain failures.