Skip to content

Latest commit

 

History

History
493 lines (398 loc) · 23.5 KB

linux.md

File metadata and controls

493 lines (398 loc) · 23.5 KB

VoiceStudio — Install on Linux

VoiceStudio's Linux desktop app is built with Electron. The archived Tauri app is no longer maintained; if you still run it, follow the migration guide.

Requirements

  • Linux x86_64 with a graphical desktop session (X11 or Wayland). There are no ARM64 Linux packages.
  • ~10 GB free disk for the app, its Python environment, and model weights.
  • Optional: an NVIDIA driver for CUDA acceleration. Without one, setup installs the CPU build of PyTorch (see below). For AMD GPUs see AMD GPU (ROCm).

Python, FFmpeg/FFprobe, yt-dlp, and model weights are bootstrapped by the app on first launch; no toolchain is needed for the packaged app. If no FFmpeg resolves anywhere, the app downloads its own checksummed static build; Settings → Audio tools shows which binaries are in use and lets you override them or update yt-dlp.

Install (Snap, AppImage or .deb)

Snap Store (Ubuntu and other distributions with snapd):

Get it from the Snap Store

or from a terminal:

sudo snap install voicestudio

The snap updates itself through snapd. Recording and dictation need the microphone interface; if VoiceStudio cannot hear you, connect it once:

sudo snap connect voicestudio:audio-record

The snap runs through XWayland by default because native Wayland crashed it on some GNOME releases. To try native Wayland, launch it with VOICESTUDIO_SNAP_OZONE_PLATFORM=wayland voicestudio; on a revision built by Snapcraft Builds the variable is not read, so use voicestudio --ozone-platform=wayland instead.

Download a package from the Releases page:

Package File
AppImage (any distribution) VoiceStudio-<version>-linux-x64.AppImage
Debian / Ubuntu package VoiceStudio-<version>-linux-x64.deb

AppImage:

chmod +x VoiceStudio-*-linux-x64.AppImage
./VoiceStudio-*-linux-x64.AppImage

The AppImage uses the static AppImage runtime, so it does not need libfuse2. The shell installer (curl -fsSL https://voicestudio.sh/install | sh) downloads the latest AppImage, verifies it against the release's SHA256SUMS.txt, and installs it as ~/.local/bin/VoiceStudio.

Current builds include the unified terminal command. Debian packages expose voicestudio through /usr/bin and the shell installer through ~/.local/bin. A downloaded AppImage links ~/.local/bin/voicestudio on first launch and, if your shell does not already search ~/.local/bin, adds it to your shell profile once. Open a new terminal afterwards. voicestudio opens the app, and commands start it in the background when it is not running; no separate Python installation is needed. Existing custom launchers are not replaced; see Terminal command. The .deb also keeps the pre-rename voicestudio-electron command as a link to voicestudio, so existing scripts keep working.

.deb:

sudo apt install ./VoiceStudio-<version>-linux-x64.deb

The in-app updater's Linux feed carries the AppImage, which installs a downloaded update when you quit. A .deb installation never installs on quit (that needs an administrator prompt); update it with Restart in the app or by installing the newer .deb, and remove it with your package manager.

Compare any download with the release's SHA256SUMS.txt before installing.

Machines without an NVIDIA GPU

Laptops and desktops with Intel/AMD integrated graphics (or any GPU without an NVIDIA driver) run the whole app on the CPU, just slower. When no NVIDIA driver is found, the packaged app's runtime setup installs the small CPU build of PyTorch rather than the CUDA build and its ~3 GB of nvidia-* packages, and needs about 5 GiB of free disk instead of 9 GiB. Pick a light voice engine (KittenTTS, Supertonic-3, PocketTTS) and a small Whisper model for the best speed. OMNIVOICE_TORCH_VARIANT=cuda|cpu|rocm overrides the detection, and an existing install keeps working untouched. Source setup (bun run setup:api) also selects the locked CPU wheels on x86-64 hosts without NVIDIA. Linux ARM source installs keep their native PyPI wheels. See CPU setup and overrides.

Building from source

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.

Prerequisites:

  • git and curl

  • 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, Rust / Cargo (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh), and the native development libraries used by the Electron native helper. If you use rustup, reopen the shell or run source "$HOME/.cargo/env" first.

    # Debian / Ubuntu
    sudo apt-get update
    sudo apt-get install -y build-essential pkg-config libasound2-dev libxdo-dev \
      libxtst-dev libx11-dev libxkbcommon-dev libwayland-dev libssl-dev \
      binutils zsync
    
    # Fedora
    sudo dnf install gcc gcc-c++ make pkgconf-pkg-config alsa-lib-devel libxdo-devel \
      libXtst-devel libX11-devel libxkbcommon-devel wayland-devel openssl-devel
    
    # Arch
    sudo pacman -S --needed base-devel alsa-lib xdotool libxtst libx11 libxkbcommon wayland openssl

    bun run dist also needs readelf (binutils) and zsyncmake (part of the zsync package) to embed AppImage update information.

    The dictation helper links the shared libxdo (through enigo's default xdo feature). nixpkgs' xdotool ships no shared libxdo, so the Nix flake builds it — see Nix / NixOS below.

Then, from a clone of the repository:

git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
node electron/scripts/node-version.mjs

If 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 backend

Do not start the backend in a second terminal; Electron attaches to a backend already listening on port 3900, otherwise it starts its own. Other commands:

Command What it does
bun run desktop-prod Build Electron and launch the production bundle
bun run dist Build local installers (AppImage and .deb) in electron/release/ without publishing
bun run smoke-test Build and launch an isolated packaged app

See Electron setup for backend configuration and quality gates. The first launch downloads model weights only when you install a model.

Arch Linux (AUR)

yay -S voicestudio-bin   # or paru -S voicestudio-bin
# Development build from the current main branch:
yay -S voicestudio-git

The upstream maintainer maintains voicestudio-bin, which repackages the stable release .deb, and voicestudio-git, which builds current development sources. Install one variant at a time. The Git package builds the Electron app, native desktop bridge and pinned OmniVoice GGUF runtime; it needs a native toolchain, network access and sufficient disk space for the build. Its recipe and build instructions live in packaging/aur.

The Git-package launcher sets VOICESTUDIO_DISABLE_UPDATER=1 so pacman handles application updates. Set the same variable for other package-managed installs. Model and Python runtime setup remain explicit in the app.

Nix / NixOS

A community-maintained Nix flake (built by a non-blocking CI check) provides development shells, an FHS environment for NixOS and a Nix-built Linux x64 app. See the Nix / NixOS guide:

nix develop .#fhs   # recommended for NixOS; `nix develop` for the plain shell
bun run dev

nix run . launches the Nix-built app from a checkout. Its first run installs uv's managed Python like the AppImage does, which on NixOS needs nix-ld. Its launcher sets VOICESTUDIO_DISABLE_UPDATER=1; update it with Nix.

ChromeOS, iPad and other devices

There is no native ChromeOS or iPadOS app, and VoiceStudio does not run inside the browser alone: the models need a real backend.

  • Chromebook with Linux development environment on x86-64: install the AppImage or .deb (Install). Expect CPU-only generation (the container has no GPU access on most devices) and enough RAM for the model you pick. ARM Chromebooks are not supported: the Linux builds are x86-64 only.
  • Any browser, including ChromeOS, iPad and phones: run VoiceStudio on a PC, Mac or server and open its web interface from the device. On the same network turn on Network sharing and scan the QR code; from anywhere, use Tailscale. See Sharing & Remote Access; for a headless host see Docker.

Wayland dictation shortcut

System-wide dictation on Wayland uses the standard org.freedesktop.portal.GlobalShortcuts interface. Your desktop must run xdg-desktop-portal and a portal backend that implements that interface. The desktop owns the consent dialog and may let you replace VoiceStudio's preferred key combination.

VoiceStudio binds the replacement before saving a changed shortcut. If consent is declined or the portal is unavailable, Settings keeps the previous shortcut and reports the registration failure. The configured shortcut still works while the VoiceStudio window is focused.

While a dictation is running, VoiceStudio shows a small always-on-top capsule. It sits near the bottom of the screen your pointer is on — except on Wayland, where the protocol gives applications no say in their own placement and the compositor decides where it appears. The capsule works the same either way; only its position is out of the app's hands there.

Wayland does not expose a portable identity for the app focused at shortcut down, so VoiceStudio safely leaves the complete transcript on the clipboard and the pill says Copied instead of risking insertion into a different app.

Advanced users can opt into current-focus insertion with VOICESTUDIO_WAYLAND_UNTARGETED_INSERT=1. wlroots compositors such as Sway and Hyprland use wtype; KDE Plasma and GNOME can use dotool or ydotool to paste the Unicode clipboard payload. The opt-in targets whichever client owns keyboard focus when transcription finishes, not necessarily the app where dictation started. Tray-started dictation remains copy-only. dotool needs direct write access to /dev/uinput (normally through a distribution udev rule/group). ydotool 1.0+ needs the ydotoold daemon running with that access and its socket available to the desktop user. VoiceStudio skips either helper when its readiness check fails.

If the global shortcut stops working, restart your desktop's portal service, then save the shortcut again in Settings → Hotkey to reopen consent. Portal packages and support vary by desktop; use the backend recommended by your distribution rather than running multiple portal backends in the same session. See the portal project's service integration checks and the Arch Linux backend compatibility table for concrete service and desktop-backend checks.

Blank window or GPU errors

The Electron app renders with Chromium, not WebKitGTK, so the WEBKIT_* variables and the bundled-WebKit/GStreamer workarounds from the archived Tauri AppImage no longer apply. If the window stays blank or the terminal shows GPU process errors, start the app once with Chromium's GPU acceleration disabled:

./VoiceStudio-*-linux-x64.AppImage --disable-gpu

On Wayland sessions you can also try forcing X11 (XWayland) with --ozone-platform=x11. If either flag helps, report your distribution, desktop and GPU driver in a GitHub issue. Other Chromium or Electron switches given to the AppImage, or to voicestudio without a command, also go to the app, except the command's own options such as --version and --help, which it runs itself.

.deb ffprobe conflict

This applies only to upgrades from pre-v0.3 .deb packages, which installed ffprobe into /usr/bin/ffprobe and could clobber the system copy. If ffprobe -version reports the wrong binary after such an upgrade, reinstall the system package:

sudo apt install --reinstall ffmpeg

Restricted networks (China / Russia)

If uv times out fetching the python-build-standalone tarball or PyPI:

# Use a faster Python source mirror (China only — verify a current mirror)
export UV_PYTHON_INSTALL_MIRROR=https://gh-proxy.com/https://github.com/astral-sh/python-build-standalone/releases/download

# Use a PyPI mirror (source checkouts that resolve packages themselves; the
# locked dependency install downloads the wheel URLs pinned in uv.lock)
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple

# Or skip the download entirely if you have a compatible system Python
export UV_PYTHON_PREFERENCE=only-system

# Be tolerant of slow links
export UV_HTTP_TIMEOUT=900
export UV_HTTP_RETRIES=5

Packaged setup already tries a Python download mirror and raises the uv network budget automatically; set these to force a specific mirror, or before bun run setup:api in a source checkout. See troubleshooting. If the dependency download is slow or stalls, see First-run setup is slow or stalls on a download.

AMD GPU (ROCm)

ROCm support is Linux-only and opt-in. The default install ships the CUDA build of PyTorch (the pytorch-cuda index in pyproject.toml), so on an AMD-only machine torch.cuda.is_available() is False and VoiceStudio runs on CPU until you opt into the ROCm variant.

Running in Docker or Podman instead? There's a prebuilt ROCm image — ghcr.io/debpalash/voicestudio:stable-rocm — with GPU acceleration out of the box; see docker.md. The rest of this section is about source/desktop installs. Windows has its own opt-in ROCm setup; see windows-rocm.md.

Radeon RX 9000 series (RDNA4: RX 9060 / 9070 / 9070 XT, gfx1200/gfx1201) is supported natively by the ROCm build below (torch 2.10.0 from the rocm7.1 index includes both architectures), so it needs no HSA_OVERRIDE_GFX_VERSION. The host needs an amdgpu kernel driver new enough for RDNA4 (AMD's ROCm 6.4.1+ driver, or a recent distribution kernel); rocminfo listing your card as gfx1200/gfx1201 confirms it. Never remap an RDNA4 card onto 11.0.0: RDNA3 kernels cannot run on it.

Ways to opt in, in order of preference:

1. Packaged app (environment variable). Install the ROCm userspace (/opt/rocm or rocminfo on PATH), then launch VoiceStudio once with OMNIVOICE_TORCH_VARIANT=rocm set, for example OMNIVOICE_TORCH_VARIANT=rocm ./VoiceStudio-*-linux-x64.AppImage. Once setup finishes, the choice is saved in ~/.config/omnivoice/env, so later launches and app updates keep ROCm without the variable. To leave ROCm, launch once with OMNIVOICE_TORCH_VARIANT=cpu. Runtime setup then reinstalls torch/torchaudio/torchvision from the ROCm wheel index (https://download.pytorch.org/whl/rocm7.1 by default) right after the frozen dependency sync. That sync skips the locked CUDA Torch wheels and their NVIDIA runtime packages instead of downloading them before replacing Torch. Shared dependencies, including nvidia-ml-py for hardware metadata, stay on the locked regular index. The sync preserves a matching ROCm overlay on resume or repair; switching from CUDA removes its old runtime packages, including after an earlier switch stopped before verification. The ROCm wheels are matched to the app's pinned torch==2.10.0 (the rocm6.2 index only ever published up to torch 2.5.1). Settings → Performance → GPU acceleration reports which PyTorch build is installed. The option is ignored on macOS; on Windows it selects the opt-in stack in windows-rocm.md.

2. Source checkout. OMNIVOICE_TORCH_VARIANT=rocm bun run setup:api swaps torch right after uv sync; bun run dev then starts the backend from that environment, and bun run dev:api launches it without re-syncing, so the wheel is not reverted (#1665). Running bun run setup:api again without OMNIVOICE_TORCH_VARIANT restores the lockfile's CUDA torch build, replacing any ROCm wheel you installed by hand. To choose another ROCm release, set OMNIVOICE_TORCH_INDEX=<url>; AMD publishes newer driver-matched 7.2.x wheels on repo.radeon.com as a --find-links page rather than a PyPI-compatible index, for example:

uv pip install --reinstall-package torch --reinstall-package torchaudio \
  --reinstall-package torchvision torch==2.10.0 torchaudio==2.10.0 torchvision==0.25.0 \
  --find-links https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2.4/

run that manually if you want a specific ROCm point release; the OMNIVOICE_TORCH_INDEX env var only accepts a PEP 503 index URL, not a find-links page. If the reinstall fails (network, unsupported card), VoiceStudio keeps the default torch build and warns instead of breaking the install.

3. Manual wheel swap (fallback). Replace torch with the ROCm wheel after the first-run install populates the venv:

# From the project directory (source install), into VoiceStudio's uv venv.
# Matches the app's torch==2.10.0 pin — a different ROCm point release
# (e.g. rocm6.4, rocm7.2) may not carry that exact torch build.
# Swap all three torch packages together: a CUDA torchvision left beside a
# ROCm torch fails at generation time ("operator torchvision::nms does not
# exist"). Keep PyPI as the main index: PyTorch's index has no Pillow 13, so
# `--index-url` with `--reinstall` cannot resolve (#3158).
uv pip install \
  --reinstall-package torch --reinstall-package torchaudio --reinstall-package torchvision \
  torch==2.10.0+rocm7.1 torchaudio==2.10.0+rocm7.1 torchvision==0.25.0+rocm7.1 \
  --extra-index-url https://download.pytorch.org/whl/rocm7.1 \
  --index-strategy unsafe-best-match

Once a ROCm build of PyTorch is in the venv, detection is automatic — get_best_device() returns the GPU (ROCm-built PyTorch reports through torch.cuda.is_available()), and VoiceStudio auto-sets HSA_OVERRIDE_GFX_VERSION when your card's GFX ID is missing from the installed wheel's architecture list. The target comes from that list, not from a fixed table: the closest architecture of the same generation and the same or an older revision (gfx1152 → gfx1100, gfx1035 → gfx1030, gfx1201 → gfx1200 on a wheel that only ships gfx1200). It never crosses a generation, nor RDNA1/RDNA2 (gfx101x/gfx103x) or Vega/CDNA within gfx9, so an RDNA4 card on a wheel without any gfx12 target gets no override and a clear message. Relaunch and Settings → Performance → GPU acceleration should report the GPU device instead of cpu. Verify the wheel sees your card:

uv run python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

Device enumeration does not prove that GPU work succeeds. VoiceStudio also runs a bounded GPU self-test in a child process. If that test fails, System check warns. The VoiceStudio (OmniVoice), PyTorch Whisper and WhisperX loaders follow this test's CPU fallback, so their routing reports the failure. Independent loaders, including CTranslate2/faster-whisper, ONNX, external servers and child processes, retain their own routing; the parent test does not verify them. A pending or inconclusive test does not disable acceleration. Explicitly forcing the GPU retains the choice with a warning only for loaders that honor that override; WhisperX still follows its existing CPU fallback. Missing-kernel warnings retain their architecture-specific recovery advice. These checks identify a failed test, not its hardware or driver cause.

Notes:

  • ROCm is exercised far less than the default CUDA/MPS/CPU paths — it works, but expect rough edges on consumer cards and report what you hit.
  • Unsupported GFX (e.g. some consumer RDNA cards): if it still won't run, set HSA_OVERRIDE_GFX_VERSION yourself to a supported architecture of the same generation before launching (e.g. export HSA_OVERRIDE_GFX_VERSION=11.0.0 for a gfx11xx card, 10.3.0 for a gfx103x card; RDNA1 gfx101x cannot use 10.3.0). A remap across generations cannot work, so RDNA4 (gfx12xx) cards need a ROCm build that lists them instead. When the build lacks your card, VoiceStudio's GPU architecture notification names the exact value to try, or says that no remap exists.
  • Engines on the GPU: every PyTorch engine that runs on an NVIDIA GPU also claims ROCm (OmniVoice, IndexTTS, VoxCPM2, MOSS-TTS-Nano, CosyVoice, dots.tts, Confucius4, PyTorch Whisper, FunASR, NeMo Parakeet). On a ROCm host the one-click installs of VoxCPM2, MOSS-TTS-Nano, CosyVoice, Confucius4, dots.tts and IndexTTS put the ROCm build of the engine's own pinned torch in its venv, from the PyTorch ROCm index that publishes that version (2.7 → rocm6.3, 2.8 → rocm6.4, 2.11 → rocm7.2). An install made before this may still have a CUDA or CPU wheel. A user-selected sidecar repair builds and verifies a separate environment, keeping the existing installation available until the replacement succeeds. The previous environment remains on disk until the engine is uninstalled. A custom OMNIVOICE_TORCH_INDEX is used exactly as provided; it must carry the sidecar’s pinned Torch and torchaudio versions. The installer estimates disk space using the selected Torch wheel's downloaded and unpacked sizes, in addition to the engine's normal estimate. Measurements of the published Linux x86-64 Python 3.11 wheels on 2026-11-07 were 25.101 GiB for Torch 2.7.0, 14.873 GiB for 2.8.0 and 18.999 GiB for 2.11.0; the guard rounds up and uses the largest measured value when the version is unknown. These are estimates: custom wheels, cache locations and other dependencies can differ. Vulkan engines (OmniVoice GGUF, CosyVoice GGUF, whisper.cpp) need no ROCm at all. Faster-Whisper and WhisperX use CTranslate2, whose stock build is NVIDIA-only, so on Linux ROCm they stay on the CPU; use PyTorch Whisper, which auto-detection already prefers on ROCm.
  • ZLUDA (CUDA-on-ROCm translation) is not used or supported: its PyTorch support is incomplete and its cuDNN path can be slower than the CPU. Use the native ROCm builds above.

Tracking issue: #124.

Hugging Face token (optional but recommended)

See docs/setup/huggingface-token.md.

Troubleshooting

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