Palash DebnathandClaude Opus 5
41722afe3b
* refactor(launchpad): quieter, borderless design refresh The launchpad carried decoration from an earlier direction: icon chips, corner-hung count badges, a permanently visible filled arrow, uppercase mono card titles, and a dotted stipple divider — plus a frame that had been invisible since the app-wide border tokens were zeroed. Rework it around what the borderless direction actually implies: - Feature tiles get a whisper-faint surface instead of a dead frame, and read as three bands (bare glyph + count / title + arrow / description). `--card-hue` is spent sparingly — the glyph at rest, the surface, count and arrow only once raised. Titles move to sans sentence case; counts are plain tabular numerals. Lift softened 4px -> 2px, coloured glow -> neutral shadow, plus an explicit focus ring and a staggered entrance. - Hero drops the boxed "646" pill and the filled A/B-Compare button for quiet type, with a hairline standing in for the separation. - Section labels trade the dotted stipple for a single fading hairline; rows are transparent until hover and reveal "Open" on hover/focus (it stays in the DOM, so AT and keyboard always reach it). - Hero, tiles, recent files, callout and project lists now share one 1180px column — previously only the top half was capped, so lists ran edge-to-edge on a wide display while the deck stayed centred. Two bugs found and fixed while doing it: - Buttons that had `border border-solid border-transparent` removed fell back to the UA default border and rendered a visible 1px outline. They now carry `border-0` explicitly. - `.lp-animate` used `animation-fill-mode: both`, so after the entrance it kept owning `transform` — and animation-origin declarations outrank normal ones, which silently killed the card hover lift. Now `backwards`, which still holds the from-state through the stagger delay. Also drops CSS the page has not rendered since #904: the cursor-spotlight layer, the breath ring, and the per-card waveform strip. Verified with headless renders at 1600/1280/940 and the empty state. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(dictation): decode Wayland portal signals and show the capture pill The GlobalShortcuts portal declares Activated/Deactivated as (o session, s shortcut_id, t timestamp, a{sv} options). We decoded the timestamp as u32, so zbus rejected every signal with Signature mismatch: got `(osta{sv})`, expected `(osua{sv})` and the press was dropped as an invalid signal. Registration succeeded and the desktop even reported the bound chord back, so the hotkey looked wired up while doing nothing at all — on every Wayland compositor, for the whole life of the feature (#1490). Decode the 64-bit timestamp, and keep the 32-bit spelling as a fallback so a non-conforming portal degrades to working rather than to silence. With presses arriving, the second half of the failure showed: nothing had shown the widget window since it became a hidden recorder host, so a capture ran with no pill on screen — and a mic or Accessibility failure rendered into a window nobody could see. Add show_dictation_pill, which bottom-centres the capsule on the monitor under the pointer and shows it without taking focus (Windows keeps SW_SHOWNOACTIVATE so paste still lands in the user's document), and call it from the widget for every state but idle. Wayland denies clients their own placement, so the compositor picks the spot there; the pill still appears. dispatch_dictation_capture now logs whether a press was emitted or queued — a press that reaches Rust and produces nothing was otherwise indistinguishable from one the compositor never delivered. Tests: portal signals decode at both timestamp widths (the 64-bit case fails before this change with the exact production error); pill placement centres, respects a second monitor's origin, and clamps rather than going off-screen; the widget shows for a state needing the user, stays hidden while idle, and never shows for a press that arrives while dictation is disabled. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore: sync in-progress workspace changes Uncommitted work already in the tree, checkpointed so the branch matches the local machine: - Remote GPU workers: join-from-the-app flow, one-time secrets, QR join codes, a Compute control in the status bar, and the device-list Workers panel (#1516) - Model Catalogue workspace, with Settings pointing at it - Settings sidebar search and keyboard navigation - Demo assets for dubbing, dictation and voice design, plus the scripts that render them - Backend: validation-error handling, ASR request-path degradation, and the accompanying tests - CHANGELOG entries for the above and for the Wayland dictation fix Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(tests): follow Engines to the Model Catalogue, and green the sweep - test_supertonic3 asserted the license gate points at "Settings" while the engine now names Model Catalogue → Engines, which is where the accept button actually lives. The assertion follows the move; what it pins is unchanged — the hint must name a place the user can reach it. - Carries the CJK allowlist entries for the rendered dub bundle (#1517) and the regenerated route snapshot for /workers/agent (#1516), both of which this branch inherits from the workspace sync. - docs/install/linux.md: the dictation capsule is bottom-anchored everywhere except Wayland, where the protocol gives applications no say in their placement. Documented rather than left as a surprise (CodeRabbit). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * ci: stop a flaky dependency fetch from failing green runs en-core-web-sm resolves to a direct GitHub release URL, and github.com intermittently answers `http2 error: refused stream before processing any application logic`. uv's own three retries all land within the same few seconds and fail together, so the whole job dies on a dependency that has nothing to do with the change under test — it cost #1518 and #1517 an otherwise-green run tonight. Two changes: back off between whole `uv sync` attempts, which is what actually clears it, and pass --no-sync to the pytest steps. `uv run` re-resolves the environment before running, so every test step was a fresh chance to hit the same fetch even though the install step had already synced — that is exactly how #1518 failed, in the isolated backend/tests step, with all 5467 tests already passed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * ci: one retry seam for every uv sync, not just the job that failed last en-core-web-sm resolves to a direct GitHub *release* URL rather than a package index, and github.com intermittently answers `http2 error: refused stream before processing any application logic`. uv's own retries all land inside the same ~10 seconds and fail together, so a job dies on a dependency unrelated to the change under test. Tonight that cost four otherwise-green runs across #1515, #1517 and #1518 — and the first fix only covered the Tests job, so the next failure simply moved to Smoke (Linux), which syncs separately. The fetch is per-job, so the fix has to be per-job: scripts/uv-sync-retry.sh backs off between whole attempts (15s, 45s, 90s) and every workflow that syncs now goes through it — ci.yml (tests + the platform matrix), release.yml, security.yml, evals.yml. It still fails loudly after four attempts, so a genuinely broken lockfile is not disguised as a flake. The Tests job also lacked the UV_HTTP_TIMEOUT / UV_HTTP_RETRIES the smoke matrix has always set, which is part of why it was the one that kept dying; it has them now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(ci): pin the Intel-Mac contract by intent, not by command spelling test_ci_verifies_intel_mac_as_the_documented_remote_only_host asserted the literal line `run: uv sync --extra pockettts`, so routing every sync through scripts/uv-sync-retry.sh read as a broken Intel-Mac contract. The contract it exists to protect is that the pockettts extra installs ONLY on backend_supported legs — which the regex now pins, while leaving how the sync is invoked free to change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * ci: keep every uv run out of the resolver, and bound the retry budget CodeRabbit, #1517: - `uv run` re-resolves before running, so the smoke suite, the worker-artifact tests, the release test run and the eval run were each a fresh chance to hit the flaky direct-URL fetch outside the retry loop. All of them pass --no-sync now; the environment is already synced by the step that owns the retries. security.yml's `uv run --with pip-audit` is deliberately left alone — it layers an ephemeral package rather than running the project's own tests. - The retry count multiplied uv's own budget (UV_HTTP_RETRIES=5 with a 120 s timeout on the smoke matrix). Three attempts and 60 s of total backoff outlast the refusals actually observed while staying well inside the jobs' timeout-minutes. - The Intel-Mac contract test pinned the smoke command literally too, so --no-sync tripped it exactly like the sync line did. Same fix: assert the contract (smoke runs only on backend_supported legs), not its spelling. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
8.5 KiB
VoiceStudio — Install on macOS
This page is self-contained: follow it top to bottom and you'll end up with a working VoiceStudio 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 VoiceStudio'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 VoiceStudio 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/VoiceStudio.git
cd VoiceStudio
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 VoiceStudio.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…) | VoiceStudio.Studio_<version>_aarch64.dmg |
| Intel | VoiceStudio.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 ("VoiceStudio 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 "VoiceStudio 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) 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".) 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/VoiceStudio.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): 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 → 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 Model Catalogue → 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.