Hold a hotkey to record your voice, release to transcribe and automatically paste the text at your cursor. All processing happens on your Apple Silicon Mac — no internet required after setup.
- Fast transcription: Parakeet TDT 0.6B v3 by default — 10x faster than Whisper with 17% better accuracy
- Multiple STT backends: Parakeet (default), Voxtral Realtime (Mistral), or Whisper — switchable from menu bar
- Optional LLM cleanup: Post-process transcriptions with apfel for punctuation, filler word removal, and technical term correction
- Global hotkey: Hold Control+Option (⌃⌥) to record from anywhere
- Automatic text insertion: Transcribed text types at your cursor position
- Menu bar interface: Unobtrusive status control and settings
- 100% local: Your audio never leaves your Mac
- macOS 12.0 or later
- Apple Silicon Mac (M1/M2/M3) — Intel not supported
- Python 3.11 or higher
- ~1.5GB–2.5GB disk space depending on model (Parakeet: ~2.5GB, Whisper Turbo: ~1.5GB)
- 8GB RAM minimum (16GB recommended)
Run the setup script. It handles everything:
git clone https://github.com/randomm/kuiskaus.git
cd kuiskaus
./setup.shThe script:
- Verifies you're on Apple Silicon
- Installs UV for fast package management
- Installs system dependencies (portaudio, ffmpeg)
- Installs Python dependencies including MLX
- Downloads the Parakeet TDT 0.6B v3 model (~2.5GB) by default
After installation completes, grant accessibility permissions:
- Open System Settings > Privacy & Security > Accessibility
- Add your terminal app and enable it
- Restart Kuiskaus
Remove your virtual environment and reinstall:
rm -rf .venv && ./setup.shThis ensures all dependencies update cleanly.
If the setup script fails, install manually:
# Verify Apple Silicon
if [[ $(sysctl -n machdep.cpu.brand_string) != *"Apple"* ]]; then
echo "Error: This app requires Apple Silicon"
exit 1
fi
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install system dependencies
brew install portaudio ffmpeg
# Install Python packages
uv sync --group devGrant accessibility permissions as shown in Quick Install above.
./launch_kuiskaus.shClick the microphone icon (🎤) in your menu bar to:
- See current status
- Enable/disable speech recognition
- Change STT model (Parakeet, Voxtral, or Whisper)
- Toggle LLM cleanup (apfel)
- View usage statistics
- Quit the app
./launch_cli.sh [model] [--apfel]Optional arguments:
model— STT backend to use. Options:parakeet(default),voxtral,turbo,base,small,medium,large--apfel— enable LLM post-processing to clean punctuation, remove filler words, and fix technical terms (requiresapfelCLI tool)
Examples:
./launch_cli.sh # Parakeet (default)
./launch_cli.sh turbo # Whisper V3 Turbo
./launch_cli.sh parakeet --apfel # Parakeet with LLM cleanup
./launch_cli.sh voxtral # Voxtral Realtime (Mistral)- Hold Control+Option (⌃⌥) to start recording
- Speak clearly into your microphone
- Release the keys to stop recording and transcribe
- Text appears at your cursor position
| Model | Speed | Word Error Rate | Notes |
|---|---|---|---|
| Parakeet TDT 0.6B v3 | ~10x real-time | 6.32% WER | Default; best speed/accuracy balance |
| Voxtral Mini 3B | Sub-200ms | ~4% WER | 13 languages; higher RAM usage |
| Whisper V3 Turbo | 8-15x real-time | 7.6% WER | Legacy fallback |
| Whisper Large | 4-8x real-time | 5.8% WER | Highest accuracy of Whisper family |
All models run locally on Apple Silicon via MLX. First use downloads the model and caches it.
Switch models from the menu bar Model submenu, or pass as CLI argument:
| Model | CLI name | Speed | Accuracy | Size |
|---|---|---|---|---|
| Parakeet TDT 0.6B v3 | parakeet |
⚡ Fastest | ★★★★ 6.32% WER | ~2.5GB |
| Voxtral Mini 3B | voxtral |
⚡ Fast | ★★★★★ ~4% WER | ~2GB |
| Whisper V3 Turbo | turbo |
⚡ Fast | ★★★ 7.6% WER | ~1.5GB |
| Whisper Small | small |
Fast | ★★ | ~250MB |
| Whisper Medium | medium |
Moderate | ★★★ | ~750MB |
| Whisper Large | large |
Slower | ★★★★ 5.8% WER | ~3GB |
When enabled, each transcription is cleaned up by a local LLM via the apfel tool:
- Fixes punctuation and capitalisation
- Removes filler words (um, uh, er)
- Corrects common technical term mistranscriptions (e.g. "pie test" → pytest, "get hub" → GitHub)
Enable via: menu bar LLM Cleanup (apfel) toggle, or --apfel CLI flag.
Requires apfel to be installed separately. Falls back to raw transcription if unavailable.
See the apfel documentation for installation instructions.
Edit kuiskaus/hotkey_listener_cgevent.py and change required_modifiers.
Grant permissions in System Settings > Privacy & Security > Accessibility. Add your terminal app and enable it. Restart Kuiskaus after granting permissions.
- Verify your microphone works in other apps
- Ensure no other app uses the microphone exclusively
- Try a different audio input device in System Settings
- Some applications block programmatic text input
- Longer text uses clipboard paste automatically
- Ensure the target application has focus when releasing the hotkey
First-time download takes several minutes (Parakeet: ~2.5GB, Whisper Turbo: ~1.5GB). The model caches locally after download. Subsequent loads take 1-2 seconds.
You may see Info.plist errors when running from a virtual environment. This is a known rumps issue. The app still works, but notifications may not display correctly.
- On-device processing: All transcription happens locally
- Model provenance: The Voxtral model downloads from a community
Hugging Face publisher (
mzbac), not the curated MLX community hub. The weights are revision-pinned to a specific repository commit, so upstream pushes cannot change the weights this app runs. It is cached locally after first download; no other network access. - No internet required: Works completely offline after setup
- No data collection: Your audio and transcriptions never leave your Mac
- Open source: Full source code available for inspection
kuiskaus/
├── kuiskaus/ # Core application package
│ ├── transcriber.py # Transcriber protocol (interface)
│ ├── parakeet_transcriber.py # Parakeet TDT 0.6B v3 backend
│ ├── voxtral_transcriber.py # Voxtral Realtime backend
│ ├── whisper_transcriber.py # MLX Whisper backend
│ ├── postprocessor.py # apfel LLM post-processing
│ ├── audio_recorder.py # PyAudio-based recording
│ ├── hotkey_listener_cgevent.py # Global hotkey detection
│ ├── text_inserter.py # Text insertion at cursor
│ ├── app.py # CLI application
│ └── menubar.py # Menu bar application
├── tests/ # Test suite
├── setup.sh # Installation script
├── launch_kuiskaus.sh # Menu bar launcher
├── launch_cli.sh # CLI launcher
├── run_tests.sh # Test runner
├── pyproject.toml # Project metadata and dependencies
├── uv.lock # Locked dependencies (auto-generated)
└── README.md
uv sync --group devThis installs all dependencies including the ty type checker.
Run the test suite:
./run_tests.shAfter modifying pyproject.toml, regenerate the lockfile:
uv lock
uv sync --group dev# Linting
uv run ruff check kuiskaus/ tests/
# Type checking
uv run ty check kuiskaus/ tests/
# Formatting
uv run ruff format kuiskaus/ tests/Contributions are welcome! See the project structure above for code organization. Follow conventional commits format (feat:, fix:, refactor:, etc.) and name branches as feature/issue-{number}-short-description.
MIT License — see LICENSE file for details.
- NVIDIA / Senstella for the Parakeet TDT model
- Mistral AI for the Voxtral model
- OpenAI for the Whisper model
- Apple for the MLX framework
- The Python community for excellent macOS integration libraries
"Kuiskaus" is Finnish for "whisper" 🇫🇮