wisp-open/README.md

WIS Free V3

WIS Free V3 is a desktop voice-dictation app built with Go and Wails. It records audio from a global shortcut, transcribes it with Groq Whisper or a local backend, optionally refines the result, and types the text into the focused application.

Windows and Linux are supported. Linux packages and source builds currently target amd64/x86_64.

Linux installation

Install a package with the native package manager so it resolves runtime dependencies. Do not use dpkg -i on its own.

Debian and Ubuntu

Download the .deb for your architecture, then run:

sudo apt install ./wis-free-v3_<version>_amd64.deb

If a previous dpkg -i attempt left dependencies unfinished, repair them first:

sudo apt -f install
sudo apt install ./wis-free-v3_<version>_amd64.deb

Fedora and other RPM-based distributions

Install the RPM with the distribution package manager:

sudo dnf install ./wis-free-v3-<version>-1.x86_64.rpm

Uninstall it from a terminal with sudo dnf remove wis-free-v3. The RPM also ships desktop and AppStream metadata so graphical software centers such as GNOME Software can show the package as an app and offer install/uninstall actions for the local RPM.

For openSUSE, use sudo zypper install ./wis-free-v3-<version>.x86_64.rpm and sudo zypper remove wis-free-v3.

After installing, launch WIS Free V3 from the application launcher or run wis-free-v3 in a terminal. A reboot is not required.

Linux first-run setup

Global shortcut

Linux uses your desktop environment's custom shortcut feature as the primary global shortcut method. Copy the Linux System Shortcut command shown in Settings and bind it to your preferred key combination:

• GNOME: Settings -> Keyboard -> Custom Shortcuts
• KDE Plasma: System Settings -> Shortcuts -> Command/URL

That command toggles recording: one press starts and the next press stops. It is shell-quoted automatically, including when the app is installed in a path containing spaces. It also works from a cold start because it uses --action=toggle.

Direct typing with ydotool

WIS Free V3 uses ydotool to type transcriptions into the active application. This works on both Wayland and X11, but it needs the persistent ydotoold service.

Install the dependency, then enable the service for your user:

# Debian / Ubuntu
sudo apt install ydotool

# Fedora
sudo dnf install ydotool

# Arch Linux
sudo pacman -S ydotool

# All distributions that provide the standard user unit
systemctl --user enable --now ydotool.service

Distribution packages normally install the required /dev/uinput rule and the ydotool.service user unit. Do not add an extra manual udev rule unless your distribution's ydotool documentation says its package does not provide one.

Open Settings again and check the Direct typing status. If the socket is still unavailable after enabling the service, log out and back in once, then run:

systemctl --user restart ydotool.service

For a ydotool installation without a packaged user unit, the source checkout can create a separate WIS Free V3 user unit without overwriting distribution files:

bash scripts/build-linux.sh --install-systemd

To diagnose it, use:

systemctl --user status ydotool.service
journalctl --user -u ydotool.service -b

The app detects sockets from the standard user-runtime directory, /tmp/.ydotool_socket, and common system-service locations. You can override detection with YDOTOOL_SOCKET=/path/to/socket before launching WIS Free V3.

GNOME tray icon

GNOME needs the AppIndicator and KStatusNotifierItem Support extension for a traditional system-tray icon. The app still runs without it, but use the launcher or a configured shortcut to open Settings. On Debian/Ubuntu:

sudo apt install gnome-shell-extension-appindicator

Enable the extension in Settings -> Extensions. Other major desktops generally expose the tray icon without an extra extension.

Build from source on Linux

Install Go 1.24+, Node.js 20+, and native dependencies. The build script handles WebKit 4.0 versus 4.1 and Wails tags automatically.

Debian / Ubuntu

sudo apt update
sudo apt install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libasound2-dev libayatana-appindicator3-dev

If your release does not provide libwebkit2gtk-4.1-dev, install libwebkit2gtk-4.0-dev instead.

Fedora

sudo dnf install -y gcc gcc-c++ make pkgconf-pkg-config gtk3-devel webkit2gtk4.1-devel alsa-lib-devel libayatana-appindicator-gtk3-devel

Arch Linux

sudo pacman -S base-devel pkgconf gtk3 webkit2gtk alsa-lib libayatana-appindicator

Then clone the repository and build:

git clone <repository-url>
cd wisp-open
go install github.com/wailsapp/wails/v2/cmd/wails@latest
bash scripts/build-linux.sh --install-user

Use --install for /usr/local/bin, --install-user for ~/.local/bin, or --no-install for a non-interactive build. The binary is written to build/bin/wis-free-v3.

Building packages

Create distribution packages from a Linux checkout:

# Build only the format available on your build host
bash scripts/package-linux.sh --deb
bash scripts/package-linux.sh --rpm

With no flag, the script builds both formats and therefore requires both dpkg-deb and rpmbuild. Packages are placed in dist/packages/. The package metadata records the WebKit and AppIndicator ABI selected during the build, preventing a package built against one implementation from silently depending on the other.

Troubleshooting

Symptom	What to check
The package installed but the app will not launch	Install it with apt install ./file.deb or dnf install ./file.rpm so runtime libraries are resolved. Launch wis-free-v3 from a terminal once to see any loader error.
The shortcut does nothing	Copy the Linux System Shortcut command from Settings and bind it in your desktop's custom shortcut settings.
Transcription completes but text is not inserted	Open Settings and complete the ydotool setup. Check systemctl --user status ydotool.service.
ydotoold socket not found	Enable the user service, then log out/in once only if the service still cannot access /dev/uinput.
The app runs but no tray icon appears on GNOME	Install and enable the AppIndicator extension.

Configuration

Settings are available from the tray menu or the Settings window. The configuration file is stored in ~/.wis-free-v3/config.json.

License

Distributed under the MIT License.