Talkeytive

Linux, Windows and macOS. Linux supports Wayland and X11. Windows and macOS use the portable keyboard backend and require the normal OS accessibility/input permission for global shortcuts and text insertion.

The npm package includes the built UI and Python sources, not Python, Qt, model weights or device permissions. Requires Node 18.18+, Python with venv support, PortAudio and optionally Qt 6 (QtQuick, Controls, WebEngine and the qml6 launcher). If Qt is absent, the configuration UI opens in the default browser. After npm installation, install the Python runtime:

python3 -m venv "$HOME/.local/share/talkeytive/venv"
"$HOME/.local/share/talkeytive/venv/bin/python" -m pip install -r "$(npm root -g)/@ortiqo/talkeytive/daemon/requirements.txt"

On Linux, direct shortcuts require read access to the keyboard's /dev/input device. The uinput fallback needs /dev/uinput access. Configure permissions for your distribution; do not run Talkeytive as root. npm install does not grant device permissions or install a service. New installations select English and download the Tiny model in the background. Larger models can be downloaded through configuration before recording. Auto processing uses CUDA when a supported CUDA device is available and otherwise uses multithreaded int8 CPU inference. Intel and AMD integrated GPUs are not directly supported by the current faster-whisper/CTranslate2 backend; set TALKEYTIVE_CPU_THREADS to tune CPU parallelism if needed.

On Ubuntu, Zorin, and other Debian-based distributions, install the host audio and Wayland text-injection libraries before first use:

sudo apt install libportaudio2 wtype

Packing runs tests and builds the UI. Installed npm packages have no runtime npm dependencies or install scripts. Machine-specific native binaries are excluded.

Local, hold-to-talk speech-to-text for your desktop. The setup UI is built with a small React/Vite bundle and is designed to pair with platform-native global shortcut and text-injection adapters.

Install

npm install -g @ortiqo/talkeytive
talkeytive

Useful flags:

• talkeytive --configure opens setup and creates the local config directory.
• talkeytive --tui opens the dependency-free terminal setup.
• talkeytive --info prints detected OS, architecture, and data location.
• TALKEYTIVE_OPEN=1 talkeytive opens the setup page automatically on Linux, macOS, or Windows.

The npm entry point owns setup/configuration and launches the local daemon. Whisper models belong in ~/.local/share/talkeytive/models on Linux, with the equivalent per-user application data directory on other systems. The Linux daemon uses evdev for global hold-to-talk input, sounddevice for microphone capture, faster-whisper for inference, and wtype/wrtype/xdotool for insertion. New setups use Ctrl+Alt+Space; left and right modifier keys are interchangeable.

Runtime shape

Talkeytive is designed as three small processes:

1. talkeytived: long-lived local daemon for microphone capture, Whisper inference, global shortcut handling, and text injection.
2. talkeytive --tui: dependency-free configuration and model management in the terminal.
3. talkeytive-overlay: a tiny native bubble that subscribes to daemon state over a local Unix socket (or named pipe on Windows).

The overlay is desktop-specific at the edge: KDE can ship a Plasma/status integration, while GNOME should use a registered desktop application and Shell extension/indicator integration. The bubble itself should be an always-on-top, click-through transparent surface positioned near the panel, not a heavy web window. When idle it uses no overlay window; on key-down it appears immediately and animates idle → listening → transcribing → inserted.

Build and package

npm install
npm run dev
npm run build
npm run build:appimage
npm run inspect:appimage

The Linux release is distributed as an AppImage. The first launch registers a per-user desktop entry and systemd user service automatically; it does not need root access. The AppImage bundles Node, the Python speech runtime, PortAudio, and the Wayland text injector. Keyboard device access and compositor security permissions remain controlled by Linux.

npm run inspect:appimage is the release inspection gate. It checks the final AppImage, its embedded runtime and libraries, icon assets, desktop metadata, and the bundled daemon self-test before the artifact is handed off.

The flatpak/ manifest bundles the setup UI and daemon launcher for KDE/Linux packaging. Build it with flatpak-builder --user --install-deps-from= flathub build-dir flatpak/com.ortiqo.Talkeytive.yml; model downloads are the only runtime network operation. The Flatpak build needs the Python runtime dependencies from daemon/requirements.txt installed in the target runtime.

Install the daemon runtime into a virtual environment with python3 -m pip install -r daemon/requirements.txt. To run the daemon in a terminal, use talkeytive --daemon. Its Unix socket is protected to the current user. python3 daemon/talkeytived.py --status reports Whisper, microphone, and keyboard capabilities; the daemon refuses to enter listening state when the required capability is unavailable.

The GNOME indicator sources are in desktop/gnome-extension. It subscribes to idle, listening, transcribing, and inserted state over the local IPC channel. On KDE, Talkeytive relies on Plasma's built-in speech indicator instead of installing a separate widget.