VoiceStudio/docs/install/linux.md

VoiceStudio — Install on Linux

This page is self-contained: follow it top to bottom and you'll end up with a working VoiceStudio install on a Debian / Ubuntu / Fedora / Arch host.

Prerequisites

Using the AppImage

• Linux x86_64 with a desktop session (X11 or Wayland) capable of running a Tauri / WebKitGTK app.
• ~10 GB free disk for the app, its Python environment, and model weights.
• Optional: an NVIDIA driver for CUDA GPU acceleration — the app runs CPU-only without one. For AMD GPUs see AMD GPU (ROCm). That's it — Python, FFmpeg/FFprobe, yt-dlp, and the model weights are bundled or bootstrapped by the app itself on first launch. No toolchain needed. (If no FFmpeg resolves anywhere, the app downloads its own checksummed static build in the background during setup; Settings → Audio tools shows exactly which binaries are in use and lets you override them or update yt-dlp.)

Building from source

Everything above, plus the toolchain:

• git — sudo apt install git (Debian/Ubuntu), sudo dnf install git (Fedora), or sudo pacman -S git (Arch).

• curl — usually preinstalled; used by the Bun and rustup install one-liners below.

• Python 3.11+ — typically sudo apt install python3.11 on Debian/Ubuntu, sudo dnf install python3.11 on Fedora, or already installed on Arch.

• Bun — curl -fsSL https://bun.sh/install | bash.

• Rust / Cargo — curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh or via your package manager (e.g., sudo apt install rustc cargo). If you use rustup, reopen the shell or source "$HOME/.cargo/env" before running bun run desktop-prod.

• GTK/WebKit deps for the Tauri shell:

  # Debian / Ubuntu
  sudo apt-get update
  sudo apt-get install -y \
    libwebkit2gtk-4.1-dev libgtk-3-dev libpango1.0-dev libcairo2-dev \
    libsoup-3.0-dev libgdk-pixbuf-2.0-dev \
    libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev \
    libasound2-dev build-essential curl wget file
  
  # Fedora
  sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel openssl-devel
  
  # Arch
  sudo pacman -S --needed base-devel webkit2gtk-4.1 libayatana-appindicator librsvg openssl xdotool
  

• Optional: a Hugging Face token for diarization + the larger TTS engines (see docs/setup/huggingface-token.md).

Install (from source)

git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun install
source "$HOME/.cargo/env"  # only needed in a shell opened before rustup finished
bun desktop               # development build with hot reload

Use bun run desktop-prod instead when you need to build and launch the production bundle. Both commands create the Python environment via uv, sync dependencies, and start the backend automatically; do not start the backend in a second terminal.

The first Rust build takes longer because Cargo compiles the Tauri shell. If it fails with Package gdk-3.0 was not found, pango.pc missing, libsoup-3.0 missing, or javascriptcoregtk-4.1 missing, install the complete Debian/Ubuntu package block above. Those messages mean the development libraries are absent, not that PKG_CONFIG_PATH needs changing. Verify them with:

pkg-config --exists \
  gdk-3.0 pango cairo libsoup-3.0 javascriptcoregtk-4.1 gdk-pixbuf-2.0 \
  && echo "Tauri system libraries are ready"

The first app launch downloads model weights on demand. Subsequent launches reuse the Rust build, Python environment, and installed models.

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.

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.

Install (AppImage)

Download the latest AppImage from the Releases page, make it executable, and run:

chmod +x VoiceStudio.Studio_*.AppImage
./VoiceStudio.Studio_*.AppImage

No FUSE? Use --appimage-extract-and-run:

./VoiceStudio.Studio_*.AppImage --appimage-extract-and-run

.deb package

Not currently published: .deb bundling is disabled in the release pipeline because of a tauri-cli bug (Failed to create control scripts) — see the comment in .github/workflows/release.yml for the tracking note. The AppImage above is the supported Linux install path until a tauri-cli version resolves it. apt install-able .debs shipped before v0.3 (see .deb ffprobe conflict below) if you're upgrading from one of those.

The desktop app uses these canonical paths (kept in sync with scripts/desktop-prod.sh by the docs-drift CI gate):

APP_ID="com.debpalash.omnivoice-studio"
APP_NAME="VoiceStudio"

AppImage white screen / EGL errors (Fedora 44, Ubuntu 24.04+, 26.04)

Two separate WebKitGTK rendering issues land the Tauri window as a fully-white frame with no UI. Which one you have depends on your WebKitGTK version (pkg-config --modversion webkit2gtk-4.1 prints it).

Modern WebKitGTK (2.48+ — Ubuntu 24.04 and newer, incl. 26.04): try this first. WebKit's DMA-BUF renderer fails against some GPU drivers; the terminal typically shows:

Could not create default EGL display: EGL_BAD_PARAMETER

Disable the DMA-BUF renderer before launching:

WEBKIT_DISABLE_DMABUF_RENDERER=1 ./VoiceStudio.Studio_*.AppImage

WebKitGTK 2.44 / 2.46 (Fedora 44, Ubuntu 24.04 at release): a compositing-mode regression blanks the surface on first paint. Disable compositing mode instead:

WEBKIT_DISABLE_COMPOSITING_MODE=1 ./VoiceStudio.Studio_*.AppImage

VoiceStudio's AppRun launcher autodetects the broken 2.44/2.46 range and sets this second variable for you (shipped in v0.3+). The manual env-var path remains the documented fallback when running from a checked-out source tree.

Last resort — if neither variable alone helps, force software rendering (slower, but always paints):

WEBKIT_DISABLE_DMABUF_RENDERER=1 LIBGL_ALWAYS_SOFTWARE=1 ./VoiceStudio.Studio_*.AppImage

If no environment variable helps at all (Mesa 26.1+)

On a host with Mesa 26.1 or newer — Arch/CachyOS, and rolling distros generally — none of the variables above make any difference, including WEBKIT_DMABUF_RENDERER_FORCE_SHM, WEBKIT_SKIA_ENABLE_CPU_RENDERING, EGL_PLATFORM=surfaceless and MESA_LOADER_DRIVER_OVERRIDE=swrast. That is expected: the failure is in EGL display creation, which happens before WebKit consults any rendering-path flag, so there is nothing left for a flag to change.

The cause is a version pairing, not a bug in either half. The AppImage bundles a WebKitGTK built on Ubuntu but ships no libEGL of its own, so that bundled WebKit runs against your Mesa. On Mesa ≥ 26.1 it calls eglGetPlatformDisplay() in a way the newer driver rejects. Your distro's own WebKitGTK is fine, because it was compiled against the Mesa you are running — which is why building from source works on the same machine.

From v0.4.1 the AppImage handles this itself: when your system has a WebKitGTK at least as new as the bundled one, the launcher lets your copy take precedence, and the bundled libraries fill in only what your system lacks.

That check reads your WebKit version from pkg-config, which is only installed alongside the development package. If you have the runtime but not the dev package, the launcher can't compare versions and keeps the bundled copy — so tell it explicitly:

OMNIVOICE_PREFER_SYSTEM_WEBKIT=1 ./VoiceStudio.Studio_*.AppImage

(Set it to 0 to force the bundled copy — useful if your distro's WebKitGTK is older than ours and you'd rather keep the newer bundled one.)

If you are on v0.4.0 or older, either update or build from source:

git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun install
bun run desktop-prod

Tracking issues: #62, #961, #1258.

AppImage: "No microphone found" while the raw binary records fine

Recording from the AppImage fails with "No microphone found. Connect or enable a microphone and try again." — but pactl list short sources shows your microphones, gst-launch-1.0 pulsesrc … ! fakesink captures, and running frontend/src-tauri/target/debug/omnivoice-studio directly records without trouble. GST_DEBUG=2 shows the real message:

WARN GST_REGISTRY gst_registry_binary_check_magic:
  Binary registry magic version is different : 1.23.90 != 1.3.0
GStreamer element appsink not found. Please install it.

Same shape as the blank-window problem above, in a different library. The AppImage bundles the GStreamer core (WebKitGTK links it) but not its plugins — those are loaded dynamically at runtime, so the packaging step cannot see them to copy. The bundled core then reads your plugin directory, whose plugins were built against your core, the version check rejects them, and the scan produces nothing. appsink is one of the elements that goes missing, and it is the one WebKit needs to hand over a capture stream — so getUserMedia() reports no device. Your raw binary works because it uses your core with your plugins, which agree.

From v0.4.3 the launcher prefers your system's GStreamer, which is the only core that can match the plugins that will actually load. It does that by preloading that one library (LD_PRELOAD) rather than by putting your system library directory ahead of the bundle — your GStreamer shares that directory with most of the system, so hoisting it would quietly replace every other bundled library too. If your distro's GStreamer is itself broken and you would rather fall back to the bundled core:

OMNIVOICE_PREFER_SYSTEM_GSTREAMER=0 ./VoiceStudio.Studio_*.AppImage

The launcher checks first that your GStreamer can actually load alongside the libraries the AppImage bundles — a system core built against newer GLib than we ship would fail to load and take the whole app down with it, which is worse than a missing microphone. If that check fails it prints a warning, keeps the bundled core, and the app still starts (with capture still broken); building from source avoids the mismatch entirely.

The AppImage also keeps its plugin-scan cache to itself, at ~/.cache/VoiceStudio/gstreamer-registry.bin, rather than in the shared ~/.cache/gstreamer-1.0/. GStreamer names that shared file by architecture alone, so two cores of different versions overwrite each other's — which both makes this failure depend on whichever application ran last, and lets the AppImage corrupt the cache every other GStreamer app on your machine reads.

If you set XDG_CACHE_HOME, the path follows it ($XDG_CACHE_HOME/VoiceStudio/gstreamer-registry.bin); ~/.cache is the default when it is unset.

Tracking issue: #1333.

.deb ffprobe conflict

Pre-v0.3 .deb packages installed ffprobe into /usr/bin/ffprobe and clobbered the system copy on some distros. v0.3+ relocates the bundled binary into /usr/lib/omnivoice-studio/bin/ffprobe and the postrm script runs dpkg --search to undo the old conflict on upgrade. If you upgraded from a pre-v0.3 .deb and ffprobe -version now reports the wrong binary, re-install 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://ghproxy.com/https://github.com/astral-sh/python-build-standalone/releases/download

# Use a PyPI mirror
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=120
export UV_HTTP_RETRIES=5

The Phase 3 install milestone (INST-07..11) ships an OS-level mirror cascade that picks these defaults automatically; for v0.3 set them by hand.

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/omnivoice-studio:rocm — with GPU acceleration out of the box; see docker.md. The rest of this section is about source/desktop installs. (On Windows there is no ROCm path at all — PyTorch publishes no Windows ROCm wheels; see windows.md.)

Three ways to opt in, in order of preference:

1. First-run setup screen (recommended). On Linux the setup screen's Compute card offers "AMD GPU (ROCm, Linux)" next to the default Auto. When VoiceStudio detects an AMD GPU and the ROCm userspace (/opt/rocm present, or rocminfo on PATH), the ROCm option is pre-selected; with an AMD GPU but no ROCm runtime it stays offered-but-unselected — install ROCm first (or continue on CPU). Choosing ROCm makes the bootstrap reinstall torch/torchaudio from the ROCm wheel index (https://download.pytorch.org/whl/rocm6.4 by default) right after the dependency sync — matched to the app's pinned torch==2.8.0 (the rocm6.2 index only ever published up to torch 2.5.1, so it silently failed the reinstall and left the CPU-only CUDA build in place).

2. Environment variable (existing installs / headless). Set OMNIVOICE_TORCH_VARIANT=rocm before launching — the next bootstrap performs the same ROCm reinstall. OMNIVOICE_TORCH_INDEX=<url> overrides the wheel index when you need a different ROCm version — e.g. AMD publishes newer driver-matched builds (7.2.x) at repo.radeon.com as a --find-links page rather than a PyPI-style index:

uv pip install --reinstall torch==2.8.0 torchaudio==2.8.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.8.0 pin — a different ROCm point release
# (e.g. rocm6.2, rocm7.x) may not carry that exact torch build.
uv pip install --reinstall torch torchaudio \
  --index-url https://download.pytorch.org/whl/rocm6.4

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 for consumer cards whose GFX ID isn't in the official ROCm support matrix. Relaunch and the Settings → System panel 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))"

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 (e.g. export HSA_OVERRIDE_GFX_VERSION=11.0.0) to the nearest supported architecture before launching.
• ZLUDA (CUDA-on-ROCm translation) can work but is unsupported here — prefer a native ROCm wheel.

Tracking issue: #124.

Hugging Face token (optional but recommended)

See docs/setup/huggingface-token.md.

Troubleshooting

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