# Witticism
[](https://github.com/Aaronontheweb/witticism/actions/workflows/ci.yml)
[](https://pypi.org/project/witticism/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](https://github.com/Aaronontheweb/witticism/releases/latest)
🎙️ **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
## Installation
### 🚀 Quick Install (Recommended)
**Just run this one command:**
```bash
curl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.sh | bash
```
**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.)
- **Python 3.10-3.12** (pipx will handle this)
- **NVIDIA GPU** (optional but recommended for faster transcription)
1. Install system dependencies:
```bash
# Debian/Ubuntu
sudo apt-get install portaudio19-dev
# Fedora/RHEL
sudo dnf install portaudio-devel
# Arch Linux
sudo pacman -S portaudio
```
2. Install pipx if needed:
```bash
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
3. Install Witticism:
```bash
# 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"
```
4. Set up auto-start (optional):
```bash
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:
```bash
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
```bash
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:
```json
{
"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
```bash
python -c "import torch; print(torch.cuda.is_available())"
```
Should return `True` if CUDA is available.
### Models not loading
First run downloads models (~150MB for base). Ensure stable internet connection.
### Debug logging
By default, witticism logs to `~/.local/share/witticism/debug.log` when debug level is enabled.
To enable debug logging, either:
- Run with `--log-level DEBUG`
- Edit `~/.config/witticism/config.json` and set `"logging": {"level": "DEBUG", "file": "~/.local/share/witticism/debug.log"}`
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`
## 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](https://aaronstannard.com/)
## License
Apache-2.0
Raw data
{
"_id": null,
"home_page": null,
"name": "witticism",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "transcription, whisperx, speech-recognition, push-to-talk",
"author": null,
"author_email": "Aaron Stannard <aaron@petabridge.com>",
"download_url": "https://files.pythonhosted.org/packages/85/7b/b90cc9b4c59fd54035997cef99f862b6d96faf148f82fdba4f177e79274c/witticism-0.5.0.tar.gz",
"platform": null,
"description": "# Witticism\n\n[](https://github.com/Aaronontheweb/witticism/actions/workflows/ci.yml)\n[](https://pypi.org/project/witticism/)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://www.python.org/downloads/)\n[](https://github.com/Aaronontheweb/witticism/releases/latest)\n\n\ud83c\udf99\ufe0f **One-command install. Zero configuration. Just works.**\n\nWhisperX-powered voice transcription tool that types text directly at your cursor position. Hold F9 to record, release to transcribe.\n\n## \u2728 Features\n\n- **\ud83d\ude80 One-Command Install** - Automatic GPU detection and configuration\n- **\ud83c\udfae True GPU Acceleration** - Full CUDA support, even for older GPUs (GTX 10xx series)\n- **\u26a1 Instant Transcription** - Press F9, speak, release. Text appears at cursor\n- **\ud83d\udd04 Continuous Dictation Mode** - Toggle on for hands-free transcription\n- **\ud83c\udfaf System Tray Integration** - Runs quietly in background, always ready\n- **\ud83d\udce6 No Configuration** - Works out of the box with smart defaults\n- **\ud83d\udd27 Easy Updates** - Re-run install script to upgrade to latest version\n\n## Why Witticism?\n\nBuilt to solve real GPU acceleration issues with whisper.cpp. WhisperX provides:\n- Proper CUDA/GPU support for faster transcription (2-10x faster than CPU)\n- Word-level timestamps and alignment for accuracy\n- Better accuracy with less latency\n- Native Python integration that actually works\n\n## Installation\n\n### \ud83d\ude80 Quick Install (Recommended)\n\n**Just run this one command:**\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.sh | bash\n```\n\n**That's it!** The installer will:\n- \u2705 Install system dependencies automatically (asks for sudo only if needed)\n- \u2705 Detect your GPU automatically (GTX 1080, RTX 3090, etc.)\n- \u2705 Install the right CUDA/PyTorch versions\n- \u2705 Create desktop launcher with custom icon\n- \u2705 Set up auto-start on login\n- \u2705 Configure the system tray icon\n- \u2705 Handle all dependencies in an isolated environment\n\n**No Python knowledge required. No CUDA configuration. It just works.**\n\nNote: The installer will ask for your sudo password only if PortAudio needs to be installed. Witticism itself runs as your regular user.\n\n### Manual Installation\n\nIf you prefer to install manually:\n\n### Prerequisites\n\n- **Linux** (Ubuntu, Fedora, Debian, etc.)\n- **Python 3.10-3.12** (pipx will handle this)\n- **NVIDIA GPU** (optional but recommended for faster transcription)\n\n1. Install system dependencies:\n```bash\n# Debian/Ubuntu\nsudo apt-get install portaudio19-dev\n\n# Fedora/RHEL\nsudo dnf install portaudio-devel\n\n# Arch Linux\nsudo pacman -S portaudio\n```\n\n2. Install pipx if needed:\n```bash\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n```\n\n3. Install Witticism:\n```bash\n# For CPU-only\npipx install witticism\n\n# For GPU with CUDA 11.8+\npipx install witticism --pip-args=\"--index-url https://download.pytorch.org/whl/cu118 --extra-index-url https://pypi.org/simple\"\n\n# For GPU with CUDA 12.1+\npipx install witticism --pip-args=\"--index-url https://download.pytorch.org/whl/cu121 --extra-index-url https://pypi.org/simple\"\n```\n\n4. Set up auto-start (optional):\n```bash\nmkdir -p ~/.config/autostart\ncat > ~/.config/autostart/witticism.desktop << EOF\n[Desktop Entry]\nType=Application\nName=Witticism\nExec=$HOME/.local/bin/witticism\nStartupNotify=false\nTerminal=false\nX-GNOME-Autostart-enabled=true\nEOF\n```\n\n### Desktop Integration\n\nThe 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.\n\n### Upgrading\n\nTo upgrade to the latest version, simply re-run the install script:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/Aaronontheweb/witticism/master/install.sh | bash\n```\n\nThe install script is idempotent and will automatically upgrade existing installations to the latest version with all dependencies.\n\n## Usage\n\n### Basic Operation\n\n1. The app runs in your system tray (green \"W\" icon)\n2. **Hold F9** to start recording\n3. **Release F9** to stop and transcribe\n4. Text appears instantly at your cursor position\n\n**Or use Continuous Mode:**\n- Toggle continuous dictation from the tray menu\n- Speak naturally - transcription happens automatically\n- Perfect for long-form writing\n\n### System Tray Menu\n\n- **Status**: Shows current state (Ready/Recording/Transcribing)\n- **Model**: Choose transcription model\n - `tiny/tiny.en`: Fastest, less accurate\n - `base/base.en`: Good balance (default)\n - `small/medium/large-v3`: More accurate, slower\n- **Audio Device**: Select input microphone\n- **Quit**: Exit application\n\n### Command Line Options\n\n```bash\nwitticism --model base --log-level INFO\n```\n\nOptions:\n- `--model`: Choose model (tiny, base, small, medium, large-v3)\n- `--log-level`: Set logging verbosity (DEBUG, INFO, WARNING, ERROR)\n- `--reset-config`: Reset settings to defaults\n- `--version`: Show version information\n\n## Configuration\n\nConfig file location: `~/.config/witticism/config.json`\n\nKey settings:\n```json\n{\n \"model\": {\n \"size\": \"base\",\n \"device\": \"auto\"\n },\n \"hotkeys\": {\n \"push_to_talk\": \"f9\"\n }\n}\n```\n\n## Performance\n\nWith GTX 1080 GPU:\n- **tiny model**: ~0.5s latency, 5-10x realtime\n- **base model**: ~1-2s latency, 2-5x realtime \n- **large-v3**: ~3-5s latency, 1-2x realtime\n\nCPU-only fallback available but slower.\n\n## Troubleshooting\n\n### No audio input\n- Check microphone permissions\n- Try selecting a different audio device from tray menu\n\n### CUDA not detected\n```bash\npython -c \"import torch; print(torch.cuda.is_available())\"\n```\nShould return `True` if CUDA is available.\n\n### Models not loading\nFirst run downloads models (~150MB for base). Ensure stable internet connection.\n\n### Debug logging\nBy default, witticism logs to `~/.local/share/witticism/debug.log` when debug level is enabled. \n\nTo enable debug logging, either:\n- Run with `--log-level DEBUG`\n- Edit `~/.config/witticism/config.json` and set `\"logging\": {\"level\": \"DEBUG\", \"file\": \"~/.local/share/witticism/debug.log\"}`\n\nCommon issues visible in debug logs:\n- \"No active speech found in audio\" - Check microphone connection/volume\n- CUDA context errors - Restart after suspend/resume\n- Model loading failures - Check GPU memory with `nvidia-smi`\n\n## Development\n\n### Project Structure\n```\nsrc/witticism/\n\u251c\u2500\u2500 core/ # Core functionality\n\u2502 \u251c\u2500\u2500 whisperx_engine.py\n\u2502 \u251c\u2500\u2500 audio_capture.py\n\u2502 \u251c\u2500\u2500 hotkey_manager.py\n\u2502 \u2514\u2500\u2500 transcription_pipeline.py\n\u251c\u2500\u2500 ui/ # User interface\n\u2502 \u2514\u2500\u2500 system_tray.py\n\u251c\u2500\u2500 utils/ # Utilities\n\u2502 \u251c\u2500\u2500 output_manager.py\n\u2502 \u251c\u2500\u2500 config_manager.py\n\u2502 \u2514\u2500\u2500 logging_config.py\n\u2514\u2500\u2500 main.py # Entry point\n```\n\n## Author\n\nCreated by [Aaron Stannard](https://aaronstannard.com/)\n\n## License\n\nApache-2.0\n",
"bugtrack_url": null,
"license": null,
"summary": "WhisperX-powered global transcription and push-to-talk application",
"version": "0.5.0",
"project_urls": null,
"split_keywords": [
"transcription",
" whisperx",
" speech-recognition",
" push-to-talk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "28c9314f1746ceeff6500cf12f21528d95ee79e33a8c68ee6429969710aa6233",
"md5": "65ebabbd092385b50ec4ceac6401f7b8",
"sha256": "44ff5b531057c78b4e8f8d6a88ed0ef5c8c66eb91a9e2ec4d58da38c90c344b9"
},
"downloads": -1,
"filename": "witticism-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65ebabbd092385b50ec4ceac6401f7b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 116383,
"upload_time": "2025-08-24T18:23:52",
"upload_time_iso_8601": "2025-08-24T18:23:52.398141Z",
"url": "https://files.pythonhosted.org/packages/28/c9/314f1746ceeff6500cf12f21528d95ee79e33a8c68ee6429969710aa6233/witticism-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "857bb90cc9b4c59fd54035997cef99f862b6d96faf148f82fdba4f177e79274c",
"md5": "3fe230ff7cabdc7abf8f8aa3345f1fac",
"sha256": "db9276ab750fb550b93932ee652d0d4176bde11d49d143d365ff55a05c4ebb19"
},
"downloads": -1,
"filename": "witticism-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "3fe230ff7cabdc7abf8f8aa3345f1fac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 206010,
"upload_time": "2025-08-24T18:23:53",
"upload_time_iso_8601": "2025-08-24T18:23:53.562864Z",
"url": "https://files.pythonhosted.org/packages/85/7b/b90cc9b4c59fd54035997cef99f862b6d96faf148f82fdba4f177e79274c/witticism-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 18:23:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "witticism"
}
JSON