ClipVoice 🎤→📋

Voice-to-clipboard tool with global hotkey support for Linux and macOS. Press a hotkey, speak your text, release - it's in your clipboard. Fast, accurate, and runs completely offline.

Features

• 🎯 Push-to-Talk: Hold hotkey to record, release to transcribe
• 🚀 State-of-the-Art STT: NVIDIA Canary-1B, Parakeet, Whisper models
• ⚡ Fast & Accurate: Optimized for low latency
• 🔒 Privacy First: Runs 100% locally, no cloud/API calls
• 🌍 Multilingual: Supports multiple languages with Canary model
• ⌨️ Global Hotkeys: Works system-wide, customizable combinations
• 📋 Smart Clipboard: Auto-capitalize, trim, append modes
• 🔕 Voice Activity Detection: Auto-stops on silence
• 💻 Cross-Platform: Linux (X11/Wayland) and macOS

Quick Install

One-Line Installation

curl -sSL https://raw.githubusercontent.com/yourusername/clipvoice/main/install.sh | bash

Or clone and run:

git clone https://github.com/yourusername/clipvoice.git
cd clipvoice
chmod +x install.sh
./install.sh

Manual Installation

1. Install System Dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y portaudio19-dev xclip python3-pip

Fedora/RHEL:

sudo dnf install -y portaudio-devel xclip python3-pip

Arch Linux:

sudo pacman -S portaudio xclip python-pip

macOS:

brew install portaudio

2. Install ClipVoice

# Clone repository
git clone https://github.com/yourusername/clipvoice.git
cd clipvoice

# Install with Poetry
poetry install                # Core dependencies
poetry install --with ml      # ML dependencies (PyTorch, transformers)
poetry install --with nemo    # Optional: NeMo for Parakeet models

# Or use Make
make install

Recommended Models:

• ⭐ Whisper: Easiest setup, works everywhere - poetry install --with ml
• ✅ Distil-Whisper: 6x faster, near-identical accuracy - poetry install --with ml
• 🚀 Canary: Best accuracy, multilingual - poetry install --with ml --with nemo
• 🚀 Parakeet: Fast and accurate - poetry install --with ml --with nemo

Note: NVIDIA models (Canary, Parakeet) require NeMo toolkit and may have dependency conflicts. Whisper is easier but NVIDIA models offer better accuracy.

Usage

Start ClipVoice

# Using Poetry
poetry run clipvoice

# Using Make
make run

# With verbose logging
poetry run clipvoice --verbose

How to Use

1. Start the application - runs in background
2. Press and hold the hotkey (default: Ctrl+Shift+Space)
3. Speak your text while holding the key
4. Release the hotkey when done
5. Paste anywhere - text is in your clipboard!

Example Session

$ poetry run clipvoice

2024-02-04 10:30:00 - INFO - Starting ClipVoice v0.1.0...
2024-02-04 10:30:01 - INFO - ✓ Audio recorder initialized
2024-02-04 10:30:01 - INFO - ✓ Clipboard manager initialized
2024-02-04 10:30:01 - INFO - ✓ Hotkey listener initialized: <ctrl>+<shift>+<space>
2024-02-04 10:30:02 - INFO - Loading STT model: nvidia/canary-1b...
2024-02-04 10:30:15 - INFO - ✓ STT engine loaded
2024-02-04 10:30:15 - INFO - ClipVoice is running! Press hotkey to record.
2024-02-04 10:30:15 - INFO - Hotkey: <ctrl>+<shift>+<space>
2024-02-04 10:30:15 - INFO - Press Ctrl+C to exit

[Press Ctrl+Shift+Space and speak: "Hello, this is a test"]

2024-02-04 10:30:20 - INFO - Starting recording...
2024-02-04 10:30:23 - INFO - Stopping recording...
2024-02-04 10:30:23 - INFO - Transcribing audio...
2024-02-04 10:30:24 - INFO - Transcription completed in 0.85s: Hello, this is a test.
2024-02-04 10:30:24 - INFO - Text copied to clipboard successfully

[Now paste anywhere with Ctrl+V!]

Configuration

Create Config File

make config
# Or manually:
mkdir -p ~/.config/clipvoice
cp config.toml.example ~/.config/clipvoice/config.toml

Edit Configuration

nano ~/.config/clipvoice/config.toml

Configuration Options

[model]
engine = "whisper"  # Options: whisper (recommended), canary, parakeet, faster-whisper
model_name = "openai/whisper-medium"  # Most reliable option

[audio]
sample_rate = 16000
min_recording_duration = 0.5  # Prevent accidental taps
silence_threshold = 0.01      # RMS threshold for silence detection
silence_duration = 1.0        # Auto-stop after 1s of silence

[hotkey]
combination = "<ctrl>+<shift>+<space>"  # Customize your hotkey

[language]
code = "en"                    # Language code
auto_detect = false            # Auto-detect language

[clipboard]
auto_paste = false
trim_whitespace = true
auto_capitalize = true
add_period = false

[ui]
enable_notifications = true
show_preview = true

[performance]
preload_model = true           # Faster first transcription
use_gpu = true                 # Use CUDA if available

Recommended Models

Model Selection Tips

Easy Setup (Recommended for Beginners):

• Just want it to work? → openai/whisper-medium (most reliable, no hassle)
• Need speed? → distil-whisper/distil-large-v3 (6x faster, near-identical accuracy)
• Need many languages? → openai/whisper-large-v3 (99+ languages)
• Low memory? → openai/whisper-base or openai/whisper-small

Advanced Setup (Best Performance, Requires NeMo):

• Want absolute best accuracy? → nvidia/canary-1b (state-of-the-art, multilingual)
• Need translation? → nvidia/canary-1b (speech-to-text translation)
• Want speed + accuracy? → nvidia/parakeet-tdt-1.1b (fast inference)

See NeMo Installation below for NVIDIA model setup.

Development

Project Structure

clipvoice/
├── clipvoice/          # Main package
│   ├── audio/         # Audio recording & processing
│   ├── stt/           # Speech-to-text engines
│   ├── clipboard/     # Clipboard management
│   ├── hotkey/        # Global hotkey listener
│   ├── config/        # Configuration system
│   └── ui/            # Notifications & UI
├── tests/             # Test suite
├── install.sh         # Installation script
├── Makefile           # Common tasks
└── pyproject.toml     # Dependencies

Common Tasks

make help          # Show all available commands
make install       # Full installation
make run           # Run ClipVoice
make test          # Run tests
make format        # Format code with black
make lint          # Lint with ruff
make clean         # Clean build artifacts

Running Tests

poetry run pytest
# Or
make test

Uninstallation

Interactive Uninstall (Recommended)

./uninstall.sh
# Or
make uninstall

This will:

• Stop any running ClipVoice instances
• Remove virtual environment and Poetry env
• Ask if you want to remove config files
• Ask if you want to remove downloaded models (~2GB)
• Clean all build artifacts
• Show instructions for removing system dependencies

Quick Uninstall (No Prompts)

make uninstall-quick

Removes ClipVoice but keeps configuration and downloaded models.

Manual Uninstall

# Stop ClipVoice
pkill -f clipvoice

# Remove virtual environment
rm -rf .venv/
poetry env remove --all

# Remove configuration (optional)
rm -rf ~/.config/clipvoice

# Remove cached models (optional, ~2GB)
rm -rf ~/.cache/huggingface

# Remove system dependencies (optional)
sudo apt-get remove portaudio19-dev xclip  # Ubuntu/Debian

NeMo Installation

To use NVIDIA models (Canary, Parakeet), you need to install NeMo toolkit:

Automatic Installation (Recommended)

# Method 1: Run the install script and choose "yes" when asked about NeMo
./install.sh

# Method 2: Install manually and fix dependencies
poetry install --with ml --with nemo
./fix_nemo_deps.sh

The script will:

1. Install compatible dependency versions (pyarrow <21.0.0, datasets >=2.0.0)
2. Install nemo-toolkit with ASR support
3. Verify the installation

Manual Installation

# Step 1: Install NeMo
poetry install --with ml --with nemo

# Step 2: Fix dependencies (CRITICAL!)
./fix_nemo_deps.sh

# Or manually:
poetry run pip uninstall -y numpy pyarrow datasets
poetry run pip install "numpy>=1.24.0,<2.0.0" "pyarrow<21.0.0" "datasets>=2.0.0,<3.0.0" "matplotlib>=3.0.0"

Critical Versions for NeMo:

• numpy>=1.24.0,<2.0.0 - NeMo requires NumPy 1.x (np.sctypes removed in 2.0)
• pyarrow<21.0.0 - NeMo requires PyExtensionType (removed in 21.0.0+)
• datasets>=2.0.0,<3.0.0 - Compatible with pyarrow <21.0.0
• matplotlib>=3.0.0 - Required by NeMo VAD utilities

Verify NeMo Installation

poetry run python -c "import nemo.collections.asr; print('NeMo installed successfully!')"

Troubleshooting NeMo

NumPy 2.0 Compatibility (np.sctypes was removed in NumPy 2.0):

NeMo doesn't support NumPy 2.x yet. This is a common error.

# Fix: Downgrade to NumPy 1.x
poetry run pip install "numpy>=1.24.0,<2.0.0"

PyArrow Compatibility (module 'pyarrow' has no attribute 'PyExtensionType'):

PyArrow 21.0.0+ removed PyExtensionType which NeMo requires.

# Fix: Install compatible version
poetry run pip uninstall -y pyarrow datasets
poetry run pip install "pyarrow<21.0.0" "datasets>=2.0.0,<3.0.0"

Quick Fix All NeMo Errors:

./fix_nemo_deps.sh

If NeMo installation fails completely:

• Use Whisper models instead (no NeMo required)
• Check NeMo GitHub Issues for similar problems
• Consider using Docker (see NeMo official documentation)

Troubleshooting

PortAudio Not Found

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

# Fedora
sudo dnf install portaudio-devel

# macOS
brew install portaudio

Clipboard Not Working (Linux)

# Install xclip for X11
sudo apt-get install xclip

# Or wl-clipboard for Wayland
sudo apt-get install wl-clipboard

Hotkeys Not Working

• Linux X11: Should work out of the box
• Linux Wayland: May have limitations, try X11 session
• macOS: Grant accessibility permissions in System Preferences

Model Download Issues

Models are downloaded from Hugging Face on first use (~2GB for Canary). Ensure you have:

• Stable internet connection
• Sufficient disk space (~5GB free)
• No firewall blocking huggingface.co

Contributing

Contributions welcome! See TASKS.md for current development tasks.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: make test
5. Submit a pull request

Roadmap

• Support for more STT engines (Whisper variants, Parakeet models)
• System tray icon with GUI controls
• Transcription history
• Custom vocabulary support
• Real-time streaming transcription
• AppImage/Snap packaging
• Windows support

License

MIT License - see LICENSE file for details.

Acknowledgments

• NVIDIA for Canary and Parakeet models
• OpenAI for Whisper models
• Hugging Face for transformers library

---

Made with ❤️ for productivity

Press a key, speak your mind, paste anywhere.