tuxwhisper 0.2.0__tar.gz

tuxwhisper-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+recordings/
+claude.txt
+notes.md
+vocab.txt
+replacements.txt
+modes.txt
+PRODUCT.md
+.impeccable/
+dist/
+*.egg-info/

tuxwhisper-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibrahim Almajai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tuxwhisper-0.2.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: tuxwhisper
+Version: 0.2.0
+Summary: Private, offline push-to-talk dictation for Linux, on X11 and Wayland
+Project-URL: Homepage, https://github.com/ialmajai/tuxwhisper
+Project-URL: Documentation, https://github.com/ialmajai/tuxwhisper#readme
+Project-URL: Issues, https://github.com/ialmajai/tuxwhisper/issues
+Author: Ibrahim Almajai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dictation,linux,speech-to-text,voice-typing,wayland,whisper
+Classifier: Environment :: X11 Applications
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: <3.15,>=3.11
+Requires-Dist: evdev-binary>=1.6
+Requires-Dist: faster-whisper<2,>=1.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: sounddevice>=0.5
+Provides-Extra: cuda
+Requires-Dist: nvidia-cublas-cu12; extra == 'cuda'
+Requires-Dist: nvidia-cudnn-cu12==9.*; extra == 'cuda'
+Provides-Extra: vulkan
+Requires-Dist: pywhispercpp<2,>=1.5; extra == 'vulkan'
+Description-Content-Type: text/markdown
+
+# TuxWhisper
+
+**Private, offline dictation for Linux.** Press a key, speak, and your words are typed wherever
+your cursor is: a browser text box, an LLM chat prompt, your editor or your terminal. Speech
+recognition ([faster-whisper](https://github.com/SYSTRAN/faster-whisper)) and the optional LLM
+cleanup ([Ollama](https://ollama.com)) run on your own machine with free, open models.
+
+![TuxWhisper demo](https://raw.githubusercontent.com/ialmajai/tuxwhisper/main/docs/demo.gif)
+
+## Install
+
+```bash
+uv tool install tuxwhisper        # NVIDIA GPU: uv tool install 'tuxwhisper[cuda]'
+tuxwhisper setup
+```
+
+`tuxwhisper setup` installs the system packages it needs (Debian, Ubuntu, Fedora, Arch and
+openSUSE), sets up the background service and, on GNOME, binds the keys. It says what each step
+does and asks before anything that needs your password. On an AMD or Intel GPU, it builds the
+Vulkan engine for you.
+
+Then click into any text box, press F5, wait for the start sound, speak, and press F5 again.
+
+| Key | Action |
+|-----|--------|
+| **F5** | Tap to start and stop, or hold to talk |
+| **F3** | Same, with local LLM cleanup |
+| **F4** | Save the last recording for fine-tuning |
+| **Alt+F9** | Settings menu |
+
+Documentation, other desktops and troubleshooting: <https://github.com/ialmajai/tuxwhisper>

tuxwhisper-0.2.0/README.md

@@ -0,0 +1,113 @@
+# 🐧 TuxWhisper
+
+**Private, offline dictation for Linux.** Press a key, speak, and your words are typed
+wherever your cursor is: a browser text box, an LLM chat prompt, your editor or your
+terminal. Everything runs on your own machine with free, open models. Your voice never
+reaches a cloud service, and there's nothing to pay for.
+
+[![CI](https://github.com/ialmajai/tuxwhisper/actions/workflows/ci.yml/badge.svg)](https://github.com/ialmajai/tuxwhisper/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Platform: Linux](https://img.shields.io/badge/platform-Linux-blue?logo=linux&logoColor=white)
+![X11 | Wayland](https://img.shields.io/badge/display-X11%20%7C%20Wayland-555)
+
+![Animated re-enactment of TuxWhisper: tap the dictation key, speak, tap again, and the sentence is typed into Google's search box in Chrome; in a terminal running Claude Code, the cleanup key also removes filler words; the settings key opens the settings menu](docs/demo.gif)
+
+<sub>Re-enactment over real screenshots; the cleaned-up sentence is a local LLM's actual output.</sub>
+
+## Features
+
+- **Fast:** OpenAI's open Whisper model ([faster-whisper](https://github.com/SYSTRAN/faster-whisper))
+  types your words about half a second after you release the key, with an NVIDIA GPU. AMD
+  and Intel GPUs work through Vulkan.
+- **Types anywhere:** browsers, editors, terminals, on X11 and Wayland (including GNOME).
+- **LLM cleanup (optional):** F3 runs your words through a local [Ollama](https://ollama.com)
+  model (Meta's Llama 3.2 by default) that removes "um"s and fixes punctuation, or rewrites
+  them as an email, bullet points or your own mode. The model must fit in the GPU memory of
+  the machine running Ollama; otherwise F3 pastes the raw transcript.
+- **Many languages:** dictate in any of Whisper's 100 languages. F3 replies in the language
+  you spoke; Llama 3.2 is weak outside English, so [pick a stronger model](docs/llm-cleanup.md)
+  for other languages.
+
+**Also:** tap or hold to talk, a custom vocabulary for names and jargon, replacements such as
+"new line" → line break, a settings menu with your last 20 transcripts, and
+[saved recordings](docs/saving-takes.md) for fine-tuning Whisper to your voice and accent.
+TuxWhisper types by pasting, then puts back the text you had copied.
+
+Tested on GNOME (Wayland) with an NVIDIA GPU and in CPU mode, and on
+[Sway 1.12 and i3 4.25](docs/other-desktops.md) in containers.
+
+## Usage
+
+| Key | Action |
+|-----|--------|
+| **F5** | Tap to start, tap to stop, or hold to talk. The text is typed at your cursor. |
+| **F3** | Same as F5, with [LLM cleanup](docs/llm-cleanup.md). |
+| **F4** | [Save the last recording](docs/saving-takes.md) and its transcript for fine-tuning. |
+| **Alt+F9** | Open the [settings menu](docs/configuration.md#settings-menu). |
+
+The installer binds these keys on GNOME. Wait for the "🎙 Recording…" notification and the start
+sound before speaking.
+
+## Install
+
+You need Linux with systemd, [uv](https://docs.astral.sh/uv/), and a GPU with about 1.5 GB of
+free memory: NVIDIA (CUDA), or AMD or Intel ([Vulkan](docs/configuration.md#amd-and-intel-gpus-vulkan),
+not yet tested on those). No GPU? TuxWhisper runs on the CPU too, more slowly.
+No uv yet? Its official installer:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then:
+
+```bash
+git clone https://github.com/ialmajai/tuxwhisper.git ~/tuxwhisper
+cd ~/tuxwhisper
+./install.sh
+```
+
+The installer says what each step does and asks before anything that needs your password.
+It's safe to run again. [Read it](install.sh) first if you like. It installs system packages
+on Debian, Ubuntu, Fedora, Arch and openSUSE; on other distros, use the manual install below.
+
+**Advanced:** [Manual install](docs/manual-install.md) runs every step by hand.
+[Other desktops](docs/other-desktops.md) covers KDE, Hyprland, Sway and i3.
+
+### Try it
+
+Click into any text box, hold F5, wait for the start sound, speak, and release. Nothing
+typed? See [Troubleshooting](docs/troubleshooting.md).
+
+> [!TIP]
+> F5 and F3 replace page refresh and find-next in browsers and many editors. Ctrl+R and Ctrl+G
+> still do those.
+
+### Optional: LLM cleanup (F3)
+
+F3 needs [Ollama](https://ollama.com) and about 2 GB more GPU memory:
+[set it up](docs/llm-cleanup.md#install).
+
+## Uninstall
+
+```bash
+./uninstall.sh
+```
+
+It asks before removing the virtual keyboard rule, and keeps your settings, saved recordings and
+downloaded models, listing where they are.
+
+## Documentation
+
+- [Manual install](docs/manual-install.md)
+- [LLM cleanup (F3)](docs/llm-cleanup.md)
+- [Saving recordings for fine-tuning (F4)](docs/saving-takes.md)
+- [Configuration](docs/configuration.md): settings menu, custom vocabulary, replacements, GPU and CPU modes
+- [Other desktops](docs/other-desktops.md)
+- [How it works](docs/how-it-works.md)
+- [Security](docs/security.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## License
+
+[MIT](LICENSE) © 2026 Ibrahim Almajai

tuxwhisper-0.2.0/asr

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Runs TuxWhisper from a git clone: the package in tuxwhisper/ with the clone's .venv.
+# Also puts pip-installed cuDNN/cuBLAS and whisper.cpp libraries (if any) on the library path.
+DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
+for SITE in "$DIR"/.venv/lib/python3*/site-packages; do
+    [ -d "$SITE/nvidia" ] && export LD_LIBRARY_PATH="$SITE/nvidia/cudnn/lib:$SITE/nvidia/cublas/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+    [ -e "$SITE/libwhisper.so.1" ] && export LD_LIBRARY_PATH="$SITE${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+done
+export TUXWHISPER_CMD="$DIR/asr" TUXWHISPER_LIBS_SET=1 PYTHONPATH="$DIR${PYTHONPATH:+:$PYTHONPATH}"
+exec "$DIR/.venv/bin/python" -m tuxwhisper "$@"

tuxwhisper-0.2.0/docs/pypi.md

@@ -0,0 +1,31 @@
+# TuxWhisper
+
+**Private, offline dictation for Linux.** Press a key, speak, and your words are typed wherever
+your cursor is: a browser text box, an LLM chat prompt, your editor or your terminal. Speech
+recognition ([faster-whisper](https://github.com/SYSTRAN/faster-whisper)) and the optional LLM
+cleanup ([Ollama](https://ollama.com)) run on your own machine with free, open models.
+
+![TuxWhisper demo](https://raw.githubusercontent.com/ialmajai/tuxwhisper/main/docs/demo.gif)
+
+## Install
+
+```bash
+uv tool install tuxwhisper        # NVIDIA GPU: uv tool install 'tuxwhisper[cuda]'
+tuxwhisper setup
+```
+
+`tuxwhisper setup` installs the system packages it needs (Debian, Ubuntu, Fedora, Arch and
+openSUSE), sets up the background service and, on GNOME, binds the keys. It says what each step
+does and asks before anything that needs your password. On an AMD or Intel GPU, it builds the
+Vulkan engine for you.
+
+Then click into any text box, press F5, wait for the start sound, speak, and press F5 again.
+
+| Key | Action |
+|-----|--------|
+| **F5** | Tap to start and stop, or hold to talk |
+| **F3** | Same, with local LLM cleanup |
+| **F4** | Save the last recording for fine-tuning |
+| **Alt+F9** | Settings menu |
+
+Documentation, other desktops and troubleshooting: <https://github.com/ialmajai/tuxwhisper>

tuxwhisper-0.2.0/install.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# TuxWhisper installer. Safe to run again: each step skips what is already done.
+# Run it from a git clone (./install.sh), or as `tuxwhisper setup` after installing from PyPI.
+# docs/manual-install.md does the same steps by hand.
+#   --yes            answer yes to every question
+#   --packages-only  install the system packages and stop (used by CI)
+#   --engine=E       cuda (NVIDIA), vulkan (AMD/Intel GPUs) or cpu; detected when not given
+set -euo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$DIR"
+# `tuxwhisper setup` runs this script from inside the installed package and passes its command;
+# a git clone runs ./asr, which uses the clone's .venv.
+PACKAGED="${TUXWHISPER_PACKAGED:-}"
+CMD="${TUXWHISPER_CMD:-$DIR/asr}"
+UNIT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+APPS_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/applications"
+RULE=/etc/udev/rules.d/60-uinput.rules
+RULE_TEXT='KERNEL=="uinput", TAG+="uaccess", OPTIONS+="static_node=uinput"'
+YES=0 PACKAGES_ONLY=0 engine=
+for arg in "$@"; do
+    case "$arg" in
+        --yes) YES=1 ;;
+        --packages-only) PACKAGES_ONLY=1 ;;
+        --engine=cuda|--engine=vulkan|--engine=cpu) engine=${arg#--engine=} ;;
+        *) echo "Unknown option: $arg" >&2; exit 2 ;;
+    esac
+done
+SUDO=sudo; [ "$(id -u)" = 0 ] && SUDO=
+
+step() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+note() { printf '  %s\n' "$*"; }
+ask() { local a; [ "$YES" = 1 ] && return 0; read -r -p "  $1 [Y/n] " a; [[ -z $a || $a =~ ^[Yy] ]]; }
+
+case "$DIR$CMD" in *[\"\|\&\\]*) echo "Move TuxWhisper to a path without \" | & or \\ characters." >&2; exit 1 ;; esac
+
+# Speech engine: faster-whisper with CUDA on NVIDIA, whisper.cpp with Vulkan on AMD or Intel GPUs
+# (PCI vendors 0x1002 and 0x8086), otherwise faster-whisper on the CPU.
+if [ -z "$engine" ]; then
+    if command -v nvidia-smi >/dev/null && nvidia-smi -L >/dev/null 2>&1; then engine=cuda
+    elif grep -qsxE '0x(1002|8086)' /sys/class/drm/card*/device/vendor; then engine=vulkan
+    else engine=cpu; fi
+fi
+
+step "1/6  System packages"
+# A compiler and kernel headers build the keyboard library; PortAudio reads the microphone.
+# The rest are clipboard tools, the settings menu, notifications and the start/stop sounds.
+# CI installs these lists on each distro; keep docs/manual-install.md in sync.
+# shellcheck source=/dev/null
+. /etc/os-release 2>/dev/null || true
+case " ${ID:-} ${ID_LIKE:-} " in
+    *" debian "*|*" ubuntu "*) pm=(apt-get install -y) pkgs=(libportaudio2 xclip wl-clipboard zenity libnotify-bin sound-theme-freedesktop)
+        vulkan=(g++ cmake libvulkan-dev glslc spirv-headers glslang-tools mesa-vulkan-drivers) ;;
+    *" fedora "*) pm=(dnf install -y) pkgs=(portaudio xclip wl-clipboard zenity libnotify sound-theme-freedesktop)
+        vulkan=(gcc-c++ cmake vulkan-loader-devel glslc spirv-headers-devel glslang mesa-vulkan-drivers) ;;
+    *" arch "*) pm=(pacman -S --needed --noconfirm) pkgs=(portaudio xclip wl-clipboard zenity libnotify sound-theme-freedesktop)
+        vulkan=(gcc cmake vulkan-icd-loader vulkan-headers shaderc spirv-headers glslang vulkan-radeon vulkan-intel) ;;
+    *" suse "*|*" opensuse "*) pm=(zypper -n install) pkgs=(portaudio xclip wl-clipboard zenity libnotify-tools sound-theme-freedesktop)
+        vulkan=(gcc-c++ cmake vulkan-devel shaderc spirv-headers glslang-devel libvulkan_radeon libvulkan_intel) ;;
+    *) pm=() pkgs=() vulkan=() ;;
+esac
+# The Vulkan engine is compiled on install: a C++ compiler, CMake, Vulkan headers and shader tools.
+[ "$engine" = vulkan ] && pkgs+=("${vulkan[@]}")
+have_all() {
+    { command -v xclip || command -v wl-copy; } && command -v zenity && command -v notify-send &&
+        [ -f /usr/share/sounds/freedesktop/stereo/device-added.oga ] &&
+        { ldconfig -p 2>/dev/null || /sbin/ldconfig -p; } | grep libportaudio >/dev/null &&
+        { [ "$engine" != vulkan ] || { command -v g++ && command -v cmake && command -v glslc &&
+            command -v glslangValidator && [ -f /usr/include/vulkan/vulkan.h ]; }; }
+} >/dev/null 2>&1
+if have_all; then
+    note "Already installed."
+elif [ ${#pm[@]} = 0 ]; then
+    note "Unknown distro (${ID:-?}). Install the packages listed in docs/manual-install.md, then run this again."
+    exit 1
+else
+    note "This runs: ${SUDO:+sudo }${pm[*]} ${pkgs[*]}"
+    if ask "Install them?"; then
+        [ "${pm[0]}" = apt-get ] && $SUDO apt-get update -q
+        $SUDO "${pm[@]}" "${pkgs[@]}"
+    else
+        note "Skipped. Without them the Python packages may fail to build in the next step."
+    fi
+fi
+[ "$PACKAGES_ONLY" = 1 ] && exit 0
+
+# uv's installer puts uv in ~/.local/bin, which a shell opened before it isn't searching yet.
+command -v uv >/dev/null || PATH="${XDG_BIN_HOME:-$HOME/.local/bin}:$PATH"
+command -v uv >/dev/null || { echo "Install uv first: https://docs.astral.sh/uv/getting-started/installation/" >&2; exit 1; }
+command -v systemctl >/dev/null || { echo "TuxWhisper needs systemd. See docs/manual-install.md." >&2; exit 1; }
+
+step "2/6  Python packages"
+case "$engine" in
+    cuda) extra="[cuda]"; note "NVIDIA GPU: using the CUDA build." ;;
+    vulkan) extra="[vulkan]"
+        note "AMD or Intel GPU: using whisper.cpp with Vulkan, built here (a few minutes)."
+        note "Untested on AMD and Intel so far; if it's slow, run this again with --engine=cpu." ;;
+    cpu) extra=""; note "No supported GPU: using the CPU build (slower)." ;;
+esac
+build=(); [ "$engine" = vulkan ] && build=(env GGML_VULKAN=1)
+if [ -n "$PACKAGED" ]; then
+    # Installed with uv or pip: add the GPU libraries if this install lacks them.
+    PY="$TUXWHISPER_PY"
+    case "$engine" in
+        cuda) check='import nvidia.cudnn, nvidia.cublas' ;;
+        vulkan) check='import os, sysconfig; assert os.path.exists(sysconfig.get_paths()["purelib"] + "/libggml-vulkan.so")' ;;
+        cpu) check='pass' ;;
+    esac
+    if "$PY" -c "$check" 2>/dev/null; then
+        note "Already installed."
+    else
+        spec="tuxwhisper$extra==$TUXWHISPER_VERSION"
+        nobin=(); [ "$engine" = vulkan ] && nobin=(--no-binary-package pywhispercpp)
+        note "This runs: ${build[*]} uv tool install --reinstall ${nobin[*]} '$spec'"
+        "${build[@]}" uv tool install -q --reinstall "${nobin[@]}" "$spec"
+    fi
+else
+    [ -d .venv ] || uv venv -q --python 3.12 .venv
+    uv pip uninstall -q --python .venv evdev 2>/dev/null || true  # replaced by evdev-binary in 0.2
+    nobin=(); [ "$engine" = vulkan ] && nobin=(--no-binary pywhispercpp)
+    "${build[@]}" uv pip install -q --python .venv "${nobin[@]}" -e ".$extra"
+fi
+
+step "3/6  Virtual keyboard (lets TuxWhisper type for you)"
+if [ -f "$RULE" ] && grep -qF "$RULE_TEXT" "$RULE"; then
+    note "Already set up."
+else
+    note "This writes one line to $RULE:"
+    note "  $RULE_TEXT"
+    note "It lets any program you run send keystrokes, not only TuxWhisper (docs/security.md)."
+    if ask "Allow it? Needs your password once."; then
+        echo "$RULE_TEXT" | $SUDO tee "$RULE" >/dev/null
+        $SUDO udevadm control --reload
+        $SUDO udevadm trigger --name-match=uinput
+    else
+        note "Skipped: TuxWhisper will copy each transcript for you to paste with Ctrl+V."
+    fi
+fi
+
+step "4/6  Background service"
+service=1
+if ! systemctl --user is-active -q graphical-session.target; then
+    service=0
+    note "Your desktop doesn't start systemd's graphical session (common on i3 and Sway)."
+    note "Start TuxWhisper from your window manager's config instead, e.g.:"
+    note "  exec \"$CMD\" serve"
+    note "See docs/other-desktops.md."
+else
+    mkdir -p "$UNIT_DIR"
+    if [ -f "$UNIT_DIR/tuxwhisper.service" ]; then
+        note "Keeping your existing $UNIT_DIR/tuxwhisper.service."
+    else
+        sed "s|^ExecStart=.*|ExecStart=\"$CMD\" serve|" tuxwhisper.service > "$UNIT_DIR/tuxwhisper.service"
+        note "Installed $UNIT_DIR/tuxwhisper.service."
+    fi
+    # One drop-in file names the engine; NVIDIA needs none (cuda is the default).
+    rm -f "$UNIT_DIR/tuxwhisper.service.d/cpu.conf" "$UNIT_DIR/tuxwhisper.service.d/vulkan.conf"
+    if [ "$engine" != cuda ]; then
+        mkdir -p "$UNIT_DIR/tuxwhisper.service.d"
+        printf '[Service]\nEnvironment=ASR_DEVICE=%s\n' "$engine" > "$UNIT_DIR/tuxwhisper.service.d/$engine.conf"
+        note "Set ASR_DEVICE=$engine."
+    fi
+    systemctl --user daemon-reload
+    systemctl --user enable -q tuxwhisper
+    since="$(date '+%Y-%m-%d %H:%M:%S')"
+    systemctl --user restart tuxwhisper
+    note "Started; it also starts at every login."
+fi
+
+step "5/6  Keyboard shortcuts and app-grid launcher"
+if [[ "${XDG_CURRENT_DESKTOP:-}" == *GNOME* ]]; then
+    "$CMD" bind | sed 's/^/  /'
+    note "F5 and F3 now replace page refresh and find-next in browsers; Ctrl+R and Ctrl+G still work."
+else
+    note "Bind these in your desktop's shortcut settings (docs/other-desktops.md):"
+    note "  F5 -> \"$CMD\" toggle      F3 -> \"$CMD\" rewrite"
+    note "  F4 -> \"$CMD\" save        Alt+F9 -> \"$CMD\" settings"
+fi
+mkdir -p "$APPS_DIR"
+sed "s|@CMD@|$CMD|" tuxwhisper-settings.desktop > "$APPS_DIR/tuxwhisper-settings.desktop"
+note "Added \"TuxWhisper Settings\" to your app grid."
+
+step "6/6  Loading the speech model"
+if [ "$service" = 0 ]; then
+    note "Skipped: start TuxWhisper from your window manager (step 4), then press F5 to dictate."
+    exit 0
+fi
+note "The first start downloads it (about 1.5 GB; the CPU model is smaller). Later starts take about 15 s."
+for _ in $(seq 1 600); do
+    log="$(journalctl --user -u tuxwhisper --since "$since" -o cat 2>/dev/null || true)"
+    if grep -qx "ready" <<<"$log"; then
+        step "Done. Click into any text box, hold F5, wait for the start sound, speak, and release."
+        note "Settings: Alt+F9.  Optional LLM cleanup (F3): docs/llm-cleanup.md"
+        exit 0
+    fi
+    if ! systemctl --user is-active -q tuxwhisper && [ -n "$log" ]; then
+        echo "TuxWhisper stopped while starting. Last log lines:" >&2
+        tail -n 5 <<<"$log" >&2
+        echo "See docs/troubleshooting.md." >&2
+        exit 1
+    fi
+    sleep 2
+done
+echo "Still loading after 20 minutes. Watch it with: journalctl --user -u tuxwhisper -f" >&2
+exit 1

tuxwhisper-0.2.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "tuxwhisper"
+dynamic = ["version"]
+description = "Private, offline push-to-talk dictation for Linux, on X11 and Wayland"
+readme = "docs/pypi.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ibrahim Almajai" }]
+requires-python = ">=3.11,<3.15"  # ctranslate2 (faster-whisper) has wheels up to 3.14
+keywords = ["dictation", "speech-to-text", "whisper", "wayland", "linux", "voice-typing"]
+classifiers = [
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Environment :: X11 Applications",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "faster-whisper>=1.2,<2",
+    "numpy>=1.24",
+    "sounddevice>=0.5",
+    "evdev-binary>=1.6",  # prebuilt evdev: no compiler or kernel headers needed
+]
+
+[project.optional-dependencies]
+# NVIDIA GPUs (ASR_DEVICE=cuda, the default): CUDA libraries for faster-whisper.
+cuda = ["nvidia-cublas-cu12", "nvidia-cudnn-cu12==9.*"]
+# AMD and Intel GPUs (ASR_DEVICE=vulkan): whisper.cpp. The PyPI wheels are CPU-only; build it
+# with GGML_VULKAN=1 and --no-binary-package pywhispercpp (tuxwhisper setup does this).
+vulkan = ["pywhispercpp>=1.5,<2"]
+
+[project.scripts]
+tuxwhisper = "tuxwhisper.asr:main"
+
+[project.urls]
+Homepage = "https://github.com/ialmajai/tuxwhisper"
+Documentation = "https://github.com/ialmajai/tuxwhisper#readme"
+Issues = "https://github.com/ialmajai/tuxwhisper/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "tuxwhisper/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tuxwhisper"]
+
+# `tuxwhisper setup` and `uninstall` run the same scripts as a git clone.
+[tool.hatch.build.targets.wheel.force-include]
+"install.sh" = "tuxwhisper/data/install.sh"
+"uninstall.sh" = "tuxwhisper/data/uninstall.sh"
+"tuxwhisper.service" = "tuxwhisper/data/tuxwhisper.service"
+"tuxwhisper-settings.desktop" = "tuxwhisper/data/tuxwhisper-settings.desktop"
+
+[tool.hatch.build.targets.sdist]
+include = ["tuxwhisper", "install.sh", "uninstall.sh", "tuxwhisper.service",
+           "tuxwhisper-settings.desktop", "asr", "docs/pypi.md", "LICENSE", "README.md"]

tuxwhisper-0.2.0/tuxwhisper/__init__.py

@@ -0,0 +1,2 @@
+"""TuxWhisper: private, offline push-to-talk dictation for Linux."""
+__version__ = "0.2.0"

tuxwhisper-0.2.0/tuxwhisper/__main__.py

@@ -0,0 +1,3 @@
+from tuxwhisper.asr import main
+
+main()