# YapYap

> Free, fully offline Mac voice-to-text app with AI cleanup. 100% on-device. No cloud, no subscription.

YapYap is an open-source macOS application that captures your voice and pastes clean, formatted text into any app. It runs entirely on-device using Apple Silicon's Neural Engine and GPU — no audio ever leaves your Mac.

## What YapYap is

- A menu bar app for macOS 14+ (Sonoma) on Apple Silicon (M1 or later)
- Push-to-talk: hold Option+Space to record, release to transcribe and paste
- Hands-free mode: toggle on/off, auto-stops on silence
- Command mode: highlight text, speak a command ("make this more formal"), AI rewrites it
- Free forever, MIT open source

## How it works

Audio → VAD (Silero noise filter) → Speech-to-Text → LLM cleanup → paste into active app

1. **Audio capture**: AVAudioEngine at 16kHz mono
2. **VAD**: Silero Voice Activity Detection strips silence to prevent Whisper hallucinations
3. **STT**: Parakeet TDT v3 (default, Neural Engine) or Whisper Large/Medium/Small (CoreML GPU)
4. **LLM cleanup**: removes fillers, fixes grammar, formats for the active app category
5. **Paste**: clipboard + synthetic Cmd+V. If auto-paste fails, the text is always in the clipboard — press Cmd+V manually.

## Speech-to-Text models

| Model | Size | Backend | Notes |
|-------|------|---------|-------|
| Parakeet TDT v3 | ~600 MB | FluidAudio (ANE) | Default. Fastest. Neural Engine. 6 languages. |
| Whisper Large v3 Turbo | ~1.5 GB | WhisperKit (CoreML) | Best accuracy. 10+ languages. |
| Whisper Medium | ~769 MB | WhisperKit | Balanced. 8 languages. |
| Whisper Small | ~244 MB | WhisperKit | Lightweight. 4 languages. |
| Apple Built-in | System | SpeechAnalyzer | macOS 26+ only. No download. |

## LLM cleanup models

All run locally via MLX (safetensors), llama.cpp (GGUF), or Ollama.

| Model | Size | RAM | Notes |
|-------|------|-----|-------|
| Qwen 2.5 1.5B | ~1 GB | 8 GB | Multilingual, smallest |
| Llama 3.2 1B | ~700 MB | 8 GB | Fastest English |
| Gemma 3 1B | ~733 MB | 8 GB | 140+ languages |
| Qwen 2.5 3B | ~2 GB | 16 GB | Multilingual |
| Llama 3.2 3B | ~2 GB | 16 GB | Good English |
| Gemma 3 4B | ~3 GB | 16 GB | **Recommended default**. 140+ languages. |
| Qwen 2.5 7B | ~4.7 GB | 32 GB | High quality multilingual |
| Llama 3.1 8B | ~4.7 GB | 32 GB | Best English quality |

## Context-aware formatting

YapYap detects the frontmost app and classifies it into one of 11 categories. Each category gets different formatting rules injected into the LLM prompt:

- **Code editors** (Cursor, VS Code, Xcode, Zed): file names → @file.py, backtick wrapping
- **Email** (Mail, Outlook, Gmail): paragraph structure, formal punctuation
- **Work messaging** (Slack, Teams, Discord): professional but friendly
- **Personal messaging** (iMessage, WhatsApp): casual, minimal punctuation
- **Terminal**: shell commands preserved literally
- **Documents**: full paragraph structure, formal style
- **AI chat**: conversational, preserves question structure
- **Social media**: short-form, hashtags preserved
- **Browser**: URL/title-aware (Gmail tab → email rules, LinkedIn → professional tone)

## Customization

- **Cleanup levels**: Light (punctuation only) / Medium (fillers removed) / Heavy (full grammar fix) / Off
- **Output styles**: Very Casual / Casual / Excited / Formal — per app category
- **Custom system prompts**: override the LLM system prompt per model size tier
- **Few-shot examples**: custom input/output pairs for the LLM
- **Per-category rules**: custom instructions appended when a category is detected
- **Personal dictionary**: vocabulary corrections (gema → Gemma) and replacements (my company → Acme Corp)
- **VAD tuning**: threshold (default 0.10), quiet preset (0.05), noisy preset (0.20)

## Known issue: auto-paste failure

Auto-paste (synthetic Cmd+V via CGEvent) sometimes fails in Electron apps and certain browser input fields. **Workaround**: the transcribed text is always copied to the clipboard after every transcription — press Cmd+V manually to paste.

## Installation

```bash
brew install --cask yapyap
```

Or download the .dmg from GitHub Releases.

Requires: macOS 14.0+, Apple Silicon (M1+), 8 GB RAM minimum.

## Links

- Homepage: https://sunboy.github.io/yapyap-landing/
- Documentation: https://sunboy.github.io/yapyap-landing/docs/
- GitHub: https://github.com/sunboylabs/YapYap
- Getting Started: https://sunboy.github.io/yapyap-landing/docs/getting-started.html
- Models Guide: https://sunboy.github.io/yapyap-landing/docs/models.html
- Customization: https://sunboy.github.io/yapyap-landing/docs/customization.html
- FAQ: https://sunboy.github.io/yapyap-landing/docs/faq.html