FAQ & Troubleshooting

No. All transcription and AI cleanup runs on your Mac using on-device ML models. No cloud AI, no subscription, no audio leaves your machine. Models are downloaded once from HuggingFace; after that, no internet connection is needed.

macOS 14.0 (Sonoma) or later, Apple Silicon (M1 or later). Intel Macs are not supported — the app relies on Apple's Neural Engine and the MLX framework which only run on Apple Silicon.

Yes. Parakeet covers 6 languages. Whisper Large covers 10+. For cleanup, Gemma 3 supports 140+ languages. Best multilingual combo: Whisper Large v3 + Gemma 3 (4B or 1B).

Yes. Settings → Cleanup → Off. Raw STT output will be pasted directly. This is also the fastest pipeline — no LLM latency at all.

Highlight text in any app, hold the hotkey, and speak a command: "make this more professional" or "translate this to Spanish" or "summarize this." YapYap sends the selected text + your spoken command to the LLM and pastes the result back in place.

This is the most common issue. There are two possible causes:

1. Missing Accessibility permission (most likely)

Go to System Settings → Privacy & Security → Accessibility and toggle YapYap ON. Without this, the synthetic Cmd+V event is silently blocked by macOS.

2. App doesn't accept synthetic keyboard events

Some apps — certain browser input fields, Electron apps, apps with custom input handling — block synthetic keyboard events. YapYap still puts the text in your clipboard.

Context is captured when you press the hotkey, not when you release it. YapYap then pastes into whatever was frontmost at the time of the key press. Make sure your cursor is in the right text field before pressing the hotkey. If this is inconvenient, use manual paste (Cmd+V) — the text is always in your clipboard.

This is a Whisper behavior — it generates text even from silence or background noise.

• YapYap strips [BLANK_AUDIO], [Music], and similar Whisper artifact strings automatically. If you still see them, file a bug.
• For hallucinations on silence: increase the VAD threshold in Settings → Advanced → Microphone, or switch to the Noisy preset.
• Fastest fix: switch from Whisper to Parakeet TDT v3 — Parakeet doesn't hallucinate on silence.

Two possible causes:

ANE compiler queue backup (developers)

After multiple build cycles, the CoreML ANE compiler can back up with a 60+ min CPU queue. Check with ps aux | grep ANECompiler. Fix: wait it out, or kill it with sudo kill [pid].

iCloud-evicted model files

If you previously had models in ~/Documents/, iCloud may have evicted the files to the cloud. Accessing them causes stat() to block indefinitely. YapYap now stores models in ~/Library/Application Support/YapYap/models/ to prevent this. Re-download your models from Settings → Models.

• Make sure YapYap is running — check for the creature in your menu bar
• The default hotkey is ⌥ Option+Space. If another app uses this shortcut, change it in Settings → Hotkeys
• Check that microphone permission is granted — Settings → Privacy on Mac, or YapYap Settings → Permissions
• If models aren't downloaded yet, the first recording triggers a download — wait for it to complete

The prefill time is the canary: <1s = warm, 5–10s+ = model has been swapped to disk due to memory pressure.

• On 8GB: switch to a smaller LLM (Qwen 1.5B or Llama 1B), or disable LLM cleanup entirely
• Close memory-heavy apps (browser with many tabs, Docker, etc.)
• Switch to a smaller model tier entirely
• The keep-alive timer (every 30 min) prevents eviction — but heavy system load can still push the model out

All models are in ~/Library/Application Support/YapYap/models/. STT models go in .../models/whisperkit/, MLX LLM models in .../models/llm/, GGUF models in .../models/gguf/. This location was chosen specifically to avoid iCloud syncing, which evicts large binary files when disk is low.

Yes, using the Ollama backend. Install Ollama, pull any model (ollama pull mistral or ollama pull phi4), then in YapYap: Settings → Models → LLM Backend → Ollama, type the model name. See the Backends guide.

You only download what you choose. Common combos:

• Minimal (8GB Mac): Parakeet (~600MB) + Qwen 1.5B (~1GB) = ~1.6GB
• Recommended (16GB Mac): Parakeet (~600MB) + Gemma 4B (~3GB) = ~3.6GB
• Maximum (32GB Mac): Whisper Large (~1.5GB) + Qwen 7B (~4.7GB) = ~6.2GB

Small models (≤2B) can echo few-shot examples verbatim when the examples are too memorable or the prompt is too complex.

• YapYap auto-detects model size and uses ultra-minimal prompts for small models — this should not happen out of the box
• If you have custom prompt overrides: Settings → Advanced → Prompts → Reset to Default
• Try switching to a medium-tier model (3B+) which can handle richer prompts

Lower the cleanup level: Settings → Cleanup → Light. This tells the LLM to fix punctuation and capitalization only, keeping all words. If the issue continues with a custom prompt, add: "Do NOT change word choice or sentence structure. Only fix punctuation and capitalization."

Add it to your Personal Dictionary: Settings → Personal Dictionary → Add entry. For pronunciation corrections (e.g., "gema" → "Gemma") use the Vocabulary type. For exact phrase replacements use the Replacements type. These are injected into the LLM prompt automatically.

Settings → Advanced → Prompts → click "Reset to Default" next to any section. Or toggle the "Custom enabled" switch off to temporarily disable an override without deleting it.