voice_linux (C99)

Local hotkey dictation for Linux/X11 using:

• PulseAudio capture
• whisper.cpp transcription
• X11/XTest text injection

Build deps (Debian/Qubes AppVM)

sudo apt update
sudo apt install -y build-essential cmake git libpulse-dev libx11-dev libxtst-dev

Build whisper.cpp

mkdir -p ./vendor
cd ./vendor
git clone https://github.com/ggerganov/whisper.cpp.git
cd ./whisper.cpp
cmake -B build -DWHISPER_CUDA=ON
cmake --build build -j"$(nproc)"

If CUDA is not ready yet, you can still build whisper.cpp CPU-only by omitting -DWHISPER_CUDA=ON.

Download a model

mkdir -p ./models
wget -O ./models/ggml-base.en.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin

Build app

# builds CLI + GUI by default
bash ./build.sh

# optional switches:
WHISPER_CUDA=1 bash ./build.sh   # enable CUDA whisper.cpp build
BUILD_GUI=0 bash ./build.sh      # build CLI only
WITH_WHISPER=0 bash ./build.sh   # build without whisper integration

Run

# CLI hotkey mode (uses ./config.ini by default)
./voice_linux

# GTK3 window mode (uses ./config.ini by default)
./voice_linux_gui

Default hotkey: Ctrl+Alt+V

• Press once to start recording
• Press again to stop recording, transcribe, and type into the focused window

If you see samples=0, that was an immediate start/stop event.

If you see [stt] [BLANK_AUDIO], recording worked but audio energy was near silent. Check your input source with:

pactl list short sources

Then set audio_device= in ./config.ini to the source you want.

Versioning workflow

This project uses semantic git tags (vMAJOR.MINOR.PATCH) plus header macros in src/version.h.

Use increment_and_push.sh to increment version, update VOICE_LINUX_VERSION, commit, tag, and push:

# patch bump (default)
./increment_and_push.sh "Fix VAD trigger behavior"

# minor bump
./increment_and_push.sh -m "Add new GUI debug indicators"

# major bump
./increment_and_push.sh -M "Breaking config change"

# release mode (also runs bash ./build.sh and creates tarball)
./increment_and_push.sh -r -m "Release minor update"

Notes

• This implementation targets X11 (not native Wayland).
• In template-based AppVMs, system packages may not persist unless installed in the template.