The repository includes a community-maintained Nix flake (flake.nix) with development shells for Linux and Apple Silicon, an FHS environment for NixOS, and a Nix-built Linux x64 app. The non-blocking Nix flake CI workflow (.github/workflows/nix.yml) evaluates it and builds the Linux app on every change that can reach the build (docs-, test- and mobile-only changes are skipped); the release installers remain the supported install path.
- Nix with flakes enabled.
bun run dev installs the JavaScript dependencies and creates the Python environment itself (it skips the Python setup when OMNIVOICE_BACKEND_CMD or VOICESTUDIO_SKIP_BACKEND=1 selects an external backend), so each shell below needs only that command.
PyTorch, WhisperX and the other wheels uv installs expect standard Linux paths such as /lib64 and /usr/lib. The FHS environment (Linux only) provides them and lets uv use its own managed CPython:
git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
nix develop .#fhs # or: nix run .#fhs
bun run devnix develop
bun run devOn Linux the shell provides:
- Toolchains:
bun,nodejs_22,uv,python311,rustc,cargo,clang,cmake,pkg-config. - Libraries:
alsa-lib,libxdo(built from xdotool's sources, because nixpkgs'xdotoolships no sharedlibxdo),libXtst,libx11,libxkbcommon,wayland,openssl,ffmpeg, plus the Electron runtime libraries. - nixpkgs' patched Electron 44 for
bun run dev(ELECTRON_OVERRIDE_DIST_PATH), since the binary the npm package downloads cannot start on NixOS. UV_PYTHON_PREFERENCE=only-system, so the repository's.venvuses the shell's Python 3.11, and the GCC runtime onLD_LIBRARY_PATHfor the PyTorch wheels.
If a wheel still fails to load a library on NixOS, use the FHS environment above. On Apple Silicon, nix develop gives a plain toolchain shell (bun, Node 22, uv, Rust, ffmpeg) and setup works as described in the macOS guide.
A backend-only shell is available as nix develop .#backend (bun run setup:api && bun run dev:api).
nix build # the unpacked Linux app in ./result
nix run . # launch it straight from this checkout- First run installs Python like the AppImage does. The app downloads uv's managed CPython into its data folder. That interpreter needs a standard ELF loader, so on NixOS enable nix-ld (
programs.nix-ld.enable = true;) or run from source in the FHS environment instead. - OmniVoice GGUF runtime included. The package builds the pinned
omnivoice.cppruntime (Vulkan and CPU) and itsbin/checksums.sha256manifest, as the installers ship them. - Updates come from Nix. The package is a read-only store path, so its launcher sets
VOICESTUDIO_DISABLE_UPDATER=1; update it with Nix. - No installer artifacts.
bun run distcannot run under Nix: electron-builder downloads its own tool binaries (the AppImage runtime andfpm) from GitHub at build time, which the Nix sandbox blocks. Release AppImage and.debartifacts come from CI.
nix flake check --no-build first checks that every regular JavaScript and
TypeScript module survives the app's source filter. Dependency and VCS directories
are excluded before traversal, and symlinks are not followed. Nix result*
symlinks are excluded, while regular source files with those names are retained.
nix flake check also builds the app and verifies the packaged resources, the
dictation helper's libxdo link, the launcher and the pruned runtime node_modules.
Inside the development shell, you can compile and test the native components:
# Run tests for the native Rust desktop bridge
cargo test --manifest-path native/desktop-bridge/Cargo.toml
# Check types and packaging contracts
bun run check:electron