Witticism

🎙️ One-command install. Zero configuration. Just works.

WhisperX-powered voice transcription tool that types text directly at your cursor position. Hold F9 to record, release to transcribe.

✨ Features

• 🚀 One-Command Install - Automatic GPU detection and configuration
• 🎮 True GPU Acceleration - Full CUDA support, even for older GPUs (GTX 10xx series)
• ⚡ Instant Transcription - Press F9, speak, release. Text appears at cursor
• 🔄 Continuous Dictation Mode - Toggle on for hands-free transcription
• 🎯 System Tray Integration - Runs quietly in background, always ready
• 📦 No Configuration - Works out of the box with smart defaults
• 🔧 Easy Updates - Re-run install script to upgrade to latest version

Why Witticism?

Built to solve real GPU acceleration issues with whisper.cpp. WhisperX provides:

• Proper CUDA/GPU support for faster transcription (2-10x faster than CPU)
• Word-level timestamps and alignment for accuracy
• Better accuracy with less latency
• Native Python integration that actually works

Platform support

Witticism works out of the box, with full hold-to-talk (hold the hotkey to record, release to stop), on:

• Windows
• Linux X11
• Linux Wayland with the GlobalShortcuts portal - KDE Plasma and GNOME 48+

On GNOME 46 / 47 Wayland, which do not yet expose that portal, Witticism still works out of the box with hold-to-talk: hold the hotkey to record, release to stop. It does this by registering a standard GNOME custom keyboard shortcut (the same kind you can create in Settings > Keyboard > Custom Shortcuts) - no install, no logout, and you can see and edit it there; it is removed when Witticism exits - and inferring the key release from GNOME's key-repeat stream. (If you have key auto-repeat turned off, the same hotkey works in press-to-toggle mode instead: press once to start, again to stop.) For exact, repeat-independent release timing you can optionally install a small GNOME Shell extension:

witticism-platform install-gnome-extension

This step is entirely opt-in, prompts for confirmation, and requires you to log out and back in before it takes effect. The installer never deploys it for you.

On Wayland, transcribed text is copied to your clipboard by default - just paste it (Ctrl+V, or Ctrl+Shift+V in a terminal). There are no permission dialogs at startup. If you'd like Witticism to insert text for you automatically, you can optionally enable automatic typing from the tray menu; it types the transcript into the active app (so it works everywhere, including terminals). It uses a one-time GNOME permission (a system dialog titled "Remote Desktop", covering keyboard input only) and Witticism explains what to expect before it appears. You can turn it off again at any time.

Run witticism-platform doctor at any time to see which backends are active and how to improve them. See docs/platform-adapters.md for the full support matrix.

Installation

🚀 Quick Install

Linux:

curl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.ps1 | iex

For detailed Windows installation instructions, see INSTALL_WINDOWS.md

That's it! The installer will:

• ✅ Install system dependencies automatically (asks for sudo only if needed)
• ✅ Detect your GPU automatically (GTX 1080, RTX 3090, etc.)
• ✅ Install the right CUDA/PyTorch versions
• ✅ Create desktop launcher with custom icon
• ✅ Set up auto-start on login
• ✅ Configure the system tray icon
• ✅ Handle all dependencies in an isolated environment

No Python knowledge required. No CUDA configuration. It just works.

Note: The installer will ask for your sudo password only if PortAudio needs to be installed. Witticism itself runs as your regular user.

Manual Installation

If you prefer to install manually:

Prerequisites

• Linux (Ubuntu, Fedora, Debian, etc.)
• Linux display integration: X11, Wayland with the GlobalShortcuts portal (KDE, GNOME 48+), or GNOME 46/47 Wayland (hold-to-talk out of the box via a standard GNOME custom keyboard shortcut with key-repeat release inference; optional extension for exact release timing). See Platform support.
• Python 3.10-3.12 (pipx will handle this)
• NVIDIA GPU (optional but recommended for faster transcription)

1. Install system dependencies:

# Debian/Ubuntu
sudo apt-get install portaudio19-dev

# Fedora/RHEL
sudo dnf install portaudio-devel

# Arch Linux
sudo pacman -S portaudio

1. Install pipx if needed:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

1. Install Witticism:

# For CPU-only
pipx install witticism

# For GPU with CUDA 11.8+
pipx install witticism --pip-args="--index-url https://download.pytorch.org/whl/cu118 --extra-index-url https://pypi.org/simple"

# For GPU with CUDA 12.1+
pipx install witticism --pip-args="--index-url https://download.pytorch.org/whl/cu121 --extra-index-url https://pypi.org/simple"

1. Set up auto-start (optional):

mkdir -p ~/.config/autostart
cat > ~/.config/autostart/witticism.desktop << EOF
[Desktop Entry]
Type=Application
Name=Witticism
Exec=$HOME/.local/bin/witticism
StartupNotify=false
Terminal=false
X-GNOME-Autostart-enabled=true
EOF

Desktop Integration

The quick installer automatically sets up desktop integration with launcher icon. If you installed manually, Witticism can still be launched from the terminal with the witticism command.

Upgrading

To upgrade to the latest version, simply re-run the install script:

curl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.sh | bash

The install script is idempotent and will automatically upgrade existing installations to the latest version with all dependencies.

Usage

Basic Operation

1. The app runs in your system tray (green "W" icon)
2. Hold F9 to start recording
3. Release F9 to stop and transcribe
4. Text appears instantly at your cursor position

Or use Continuous Mode:

• Toggle continuous dictation from the tray menu
• Speak naturally - transcription happens automatically
• Perfect for long-form writing

System Tray Menu

• Status: Shows current state (Ready/Recording/Transcribing)
• Model: Choose transcription model
  • tiny/tiny.en: Fastest, less accurate
  • base/base.en: Good balance (default)
  • small/medium/large-v3: More accurate, slower
• Audio Device: Select input microphone
• Quit: Exit application

Command Line Options

witticism --model base --log-level INFO

Options:

• --model: Choose model (tiny, base, small, medium, large-v3)
• --log-level: Set logging verbosity (DEBUG, INFO, WARNING, ERROR)
• --reset-config: Reset settings to defaults
• --version: Show version information

Configuration

Config file location: ~/.config/witticism/config.json

Key settings:

{
  "model": {
    "size": "base",
    "device": "auto"
  },
  "hotkeys": {
    "push_to_talk": "f9"
  }
}

Performance

With GTX 1080 GPU:

• tiny model: ~0.5s latency, 5-10x realtime
• base model: ~1-2s latency, 2-5x realtime
• large-v3: ~3-5s latency, 1-2x realtime

CPU-only fallback available but slower.

Troubleshooting

No audio input

• Check microphone permissions
• Try selecting a different audio device from tray menu

CUDA not detected

python -c "import torch; print(torch.cuda.is_available())"

Should return True if CUDA is available.

CUDA errors after suspend/resume

If you experience CUDA crashes after suspending and resuming your system, the installer (v0.6.0+) automatically configures NVIDIA to preserve GPU memory across suspend cycles. If you installed Witticism before this fix was added, you can either:

1. Re-run the installer (recommended):

   curl -sSL https://raw.githubusercontent.com/aaronstannard/witticism/main/install.sh | bash
   

   The installer is idempotent and will apply the fix without reinstalling Witticism.

2. Apply the fix manually:

   # Configure NVIDIA to preserve memory across suspend
   echo "options nvidia NVreg_PreserveVideoMemoryAllocations=1" | sudo tee /etc/modprobe.d/nvidia-power-management.conf
   echo "options nvidia NVreg_TemporaryFilePath=/tmp" | sudo tee -a /etc/modprobe.d/nvidia-power-management.conf
   sudo update-initramfs -u
   
   # Enable NVIDIA suspend services (if available)
   sudo systemctl enable nvidia-suspend.service
   sudo systemctl enable nvidia-resume.service
   
   # Reboot for changes to take effect
   sudo reboot
   

This fix prevents the nvidia_uvm kernel module from becoming corrupted during suspend/resume cycles, which is the root cause of "CUDA unspecified launch failure" errors.

Models not loading

First run downloads models (~150MB for base). Ensure stable internet connection.

Debug logging

Log file locations:

• Linux: ~/.local/share/witticism/debug.log
• Windows: %LOCALAPPDATA%\witticism\debug.log (e.g., C:\Users\YourName\AppData\Local\witticism\debug.log)

To enable debug logging, either:

• Run with --log-level DEBUG
• Edit the config file and set "logging": {"level": "DEBUG", "file": "<path-to-log-file>"}
  • Linux config: ~/.config/witticism/config.json
  • Windows config: %APPDATA%\witticism\config.json

Common issues visible in debug logs:

• "No active speech found in audio" - Check microphone connection/volume
• CUDA context errors - Restart after suspend/resume
• Model loading failures - Check GPU memory with nvidia-smi

Force Reinstall

If you need to force a complete reinstallation (e.g., to fix corrupted dependencies or reset settings):

Linux:

# Force reinstall with the installer
curl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.sh | bash -s -- --force

Windows:

# Force reinstall with all dependencies
irm https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.ps1 | iex -ForceReinstall

# Additional options can be combined:
# Force CPU-only reinstall without auto-start
$script = irm https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.ps1
& ([scriptblock]::Create($script)) -ForceReinstall -CPUOnly -SkipAutoStart

The force reinstall option will:

• Remove existing Witticism installation
• Clear the pipx/pip cache
• Reinstall all dependencies fresh
• Preserve your configuration files (unless you use --reset-config)

Uninstalling

Witticism ships with a dedicated uninstaller for each supported platform. It stops any running process and removes the application, desktop/auto-start entries, and icons — while keeping your configuration by default so a later reinstall feels seamless. Add the purge flag to also delete your config and data.

Linux:

# Uninstall (keeps ~/.config/witticism)
bash <(curl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/scripts/uninstall.sh)

# Uninstall and delete config & data
bash <(curl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/scripts/uninstall.sh) --purge

If you cloned the repo, you can run ./scripts/uninstall.sh directly.

Windows:

# Uninstall (keeps config/data)
irm https://raw.githubusercontent.com/Aaronontheweb/witticism/master/scripts/uninstall.ps1 -OutFile "$env:TEMP\witticism-uninstall.ps1"
& "$env:TEMP\witticism-uninstall.ps1"

# Uninstall and delete config/data
& "$env:TEMP\witticism-uninstall.ps1" -Purge

If you cloned the repo, you can run .\scripts\uninstall.ps1 directly. (Note: because the script uses a param() block, save it to a file and invoke it — piping to iex won't work.)

The uninstaller removes:

• The pipx (or pip --user) installation and the witticism/witticism-platform executables
• Desktop launcher entry, auto-start entry, and app icons (Linux)
• The desktop shortcut and Startup-folder auto-start shortcut (Windows)
• The optional GNOME Shell extension, if it was installed (Linux)
• Config and data directories, only with --purge / -Purge

On GPU machines, the Linux installer also configures NVIDIA power management: a systemd sleep hook (/usr/lib/systemd/system-sleep/99-nvidia-witticism) and a modprobe config (/etc/modprobe.d/nvidia-power-management.conf). The uninstaller removes the sleep hook (sudo required; it tells you the exact file if it can't), and intentionally leaves the modprobe config in place — it may predate Witticism, and it's harmless once Witticism is gone. Remove it yourself with sudo rm /etc/modprobe.d/nvidia-power-management.conf only if you're sure you no longer want it.

Development

Project Structure

src/witticism/
├── core/           # Core functionality
│   ├── whisperx_engine.py
│   ├── audio_capture.py
│   ├── hotkey_manager.py
│   └── transcription_pipeline.py
├── ui/             # User interface
│   └── system_tray.py
├── utils/          # Utilities
│   ├── output_manager.py
│   ├── config_manager.py
│   └── logging_config.py
└── main.py         # Entry point

Author

Created by Aaron Stannard

License

Apache-2.0