parakeet · diff
git:20260131.736d88f to git:20260211.1f3148e
72 added, 35 removed. Audit A to A.
---
name: parakeet
description: >
- Local speech-to-text using NVIDIA Parakeet TDT 0.6B.
- Use for transcribing audio files or dictating voice input directly into Claude Code.
- Processes 100% locally with 3,386x realtime speed and 6% word error rate.
+ Local speech-to-text via Handy app (push-to-talk) and NeMo CLI scripts.
+ Parakeet V3: 25 languages, auto-detection, ~30x realtime on M4 Max, 6% WER.
+ This skill should be used when transcribing audio files or dictating voice input.
argument-hint: [audio-file | "dictate" | "check"]
tools: [Bash, Read, Write]
---
# Parakeet Dictation Skill
- Local speech-to-text powered by NVIDIA Parakeet TDT 0.6B (~600MB model, 100% offline).
+ Local speech-to-text powered by NVIDIA Parakeet TDT 0.6B V3 (~600MB model, 100% offline).
+ ## Two Modes
+
+ ### 1. Handy App (Primary — Push-to-Talk into Any Text Field)
+
+ [Handy](https://handy.computer/) is a free, open-source Tauri app (Rust + React) providing
+ push-to-talk dictation with Parakeet V3 built in. Inference via
+ [transcribe-rs](https://github.com/cjpais/transcribe-rs) (ONNX Runtime, int8 quantized).
+
+ ```bash
+ brew install --cask handy
+ ```
+
+ - **Default hotkey**: ⌥Space (Option-Space) on macOS, Ctrl-Space on Windows/Linux
+ - **Modes**: Push-to-talk (hold) or toggle (press to start/stop)
+ - Select **Parakeet V3** in Settings → Models (auto-downloads ~478MB)
+ - Grant microphone + accessibility permissions
+ - Includes VAD (Silero), model management UI
+ - **Additional models**: Whisper (Small/Medium/Turbo/Large), Moonshine, SenseVoice
+ - Models stored at `~/Library/Application Support/com.pais.handy/models/`
+
+ ### 2. CLI Scripts (Claude Code File Transcription & Terminal Dictation)
+
+ CLI scripts remain for headless/terminal use within Claude Code. These use NeMo/PyTorch.
+
## Performance
- - **Speed**: 3,386x realtime (1 hour audio → ~1 second)
+ | System | Speed | Engine |
+ |--------|-------|--------|
+ | **Handy (M4 Max)** | ~30x realtime | transcribe-rs / ONNX int8 |
+ | **Handy (Zen 3)** | ~20x realtime | transcribe-rs / ONNX int8 |
+ | **Handy (Skylake i5)** | ~5x realtime | transcribe-rs / ONNX int8 |
+ | **NeMo CLI (MPS)** | Varies | NeMo / PyTorch |
+
- **Accuracy**: 6.05% WER (Word Error Rate)
+ - **Languages**: 25 European languages with automatic detection (no prompting)
- **Privacy**: 100% local processing, no cloud API
- - **Acceleration**: Apple Silicon MPS, NVIDIA CUDA, or CPU fallback
+ - **License**: CC BY 4.0 (model), MIT (Handy app)
## Commands
### Transcribe Audio File
```bash
/parakeet path/to/audio.wav
/parakeet ~/recordings/interview.mp3
/parakeet meeting.m4a
```
Supported formats: `.wav`, `.mp3`, `.m4a`, `.flac`, `.ogg`, `.aac`
- ### Live Dictation
+ ### Live Dictation (Terminal)
```bash
/parakeet
/parakeet dictate
```
- Records from microphone until Enter is pressed, then transcribes.
+ Record from microphone until Enter is pressed, then transcribe.
### Check Installation
```bash
/parakeet check
```
- Verifies Parakeet is properly installed and the model can load.
+ Verify Parakeet is properly installed and model can load.
## Setup
- ### Prerequisites
+ ### Handy (Push-to-Talk UI)
- 1. **Clone the Parakeet Dictate app**:
- ```bash
- git clone https://github.com/your-org/parakeet-dictate ~/Programming/parakeet-dictate
- cd ~/Programming/parakeet-dictate
- ```
+ ```bash
+ brew install --cask handy
+ ```
- 2. **Create and activate virtual environment**:
- ```bash
- python3 -m venv .venv
- source .venv/bin/activate
- ```
+ Launch from Applications, select Parakeet V3 model, configure hotkey.
- 3. **Install dependencies**:
- ```bash
- pip install -r requirements.txt
- ```
+ ### CLI Scripts (Prerequisites)
- 4. **(Optional) Set custom install path**:
+ 1. **Parakeet Dictate repo** at `~/Programming/parakeet-dictate/` with Python venv
+ 2. **Install dependencies**:
```bash
- export PARAKEET_HOME=/path/to/parakeet-dictate
+ cd ~/Programming/parakeet-dictate
+ uv venv && uv pip install -r requirements.txt
```
- Default: `~/Programming/parakeet-dictate`
+ 3. **(Optional) Set custom path**: `export PARAKEET_HOME=/path/to/parakeet-dictate`
## Implementation
When this skill is invoked:
1. **For audio files**: Run the transcription script
```bash
cd ~/.claude/skills/parakeet/scripts && \
${PARAKEET_HOME:-~/Programming/parakeet-dictate}/.venv/bin/python transcribe.py "<filepath>"
```
2. **For live dictation**: Run the dictation script
```bash
cd ~/.claude/skills/parakeet/scripts && \
${PARAKEET_HOME:-~/Programming/parakeet-dictate}/.venv/bin/python dictate.py
```
3. **For checking setup**: Run the check script
```bash
cd ~/.claude/skills/parakeet/scripts && \
${PARAKEET_HOME:-~/Programming/parakeet-dictate}/.venv/bin/python check_setup.py
```
- ## First Run
+ ## Model Caches
- The first transcription takes ~10-30 seconds while the Parakeet model loads into memory.
- Subsequent transcriptions are instant (sub-second for typical recordings).
+ | System | Cache Location | Size | Engine |
+ |--------|---------------|------|--------|
+ | **Handy** | `~/Library/Application Support/com.pais.handy/models/` | ~478MB | transcribe-rs (ONNX int8) |
+ | **NeMo CLI** | `~/.cache/nemo/` | ~1.2GB | NeMo / PyTorch |
+ Model caches are separate. Handy's Parakeet V3 int8 model structure:
+ ```
+ parakeet-tdt-0.6b-v3-int8/
+ ├── encoder-model.int8.onnx
+ ├── decoder_joint-model.int8.onnx
+ ├── nemo128.onnx (audio preprocessor)
+ └── vocab.txt
+ ```
+
## Troubleshooting
### "No module named nemo"
- The Parakeet virtual environment needs to be used. Scripts automatically use the correct Python.
+ Use the Parakeet virtual environment. Scripts automatically use the correct Python.
### "MPS not available"
Apple Silicon Metal acceleration requires PyTorch 2.0+. Falls back to CPU automatically.
### "Permission denied: microphone"
- Grant microphone access to Terminal in System Preferences → Privacy & Security → Microphone.
+ Grant microphone access in System Preferences → Privacy & Security → Microphone.
### Model download slow
- The 600MB Parakeet model downloads on first use. Subsequent runs use the cached model.
+ The Parakeet model downloads on first use (~478MB for Handy, ~1.2GB for NeMo). Subsequent runs use cache.
## Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `PARAKEET_HOME` | `~/Programming/parakeet-dictate` | Parakeet Dictate installation path |
## Dependencies
- This skill requires:
- - **Parakeet Dictate app** at `$PARAKEET_HOME` (default: `~/Programming/parakeet-dictate`)
+ **Handy**: `brew install --cask handy` (standalone, no other deps)
+
+ **CLI scripts** require:
+ - **Parakeet Dictate repo** at `$PARAKEET_HOME` (default: `~/Programming/parakeet-dictate`)
- **Python virtual environment** at `$PARAKEET_HOME/.venv`
- **NeMo toolkit** with ASR support (`nemo_toolkit[asr]>=2.0.0`)
- **PyTorch 2.0+** (for MPS/CUDA acceleration)
- **soundfile** and **sounddevice** for audio handling