Yapper Yapper / Help Center

Recording Issues

Troubleshoot problems with voice recording and transcription

If you’re having trouble recording or getting poor transcription results, this guide will help you diagnose and fix the problem.

Recording Won’t Start

Shortcut Not Working

If pressing ⌥ Space (or your custom shortcut) does nothing:

  1. Verify Yapper is running — Look for the icon in the menu bar
  2. Check the model is loaded — Settings → Transcription, wait for “Ready” status
  3. Verify permissions — Settings → Preferences, both should show green checkmarks
  4. Test the shortcut in Settings — Go to Settings → Preferences → Keyboard Shortcuts and re-record your shortcut

Shortcut Conflict

Your shortcut might be captured by another app or the system:

  1. Try a different shortcut temporarily
  2. Check System Settings → Keyboard → Keyboard Shortcuts for conflicts
  3. Check other apps’ shortcut settings
  4. Spotlight (⌘ Space) and similar system shortcuts can conflict

App Not Responding

If Yapper seems frozen:

  1. Click the menu bar icon — does the menu appear?
  2. Check Activity Monitor for Yapper’s status
  3. Force quit Yapper: ⌘ Option Escape, select Yapper, click Force Quit
  4. Reopen Yapper from Applications

No Audio Being Captured

”No speech detected” Error

This means the recording captured silence or no recognizable speech.

Solutions:

  1. Speak louder — Your voice might be too quiet
  2. Check microphone selection — Settings → Preferences → Microphone, or use the live level meter to verify audio is being captured
  3. Test microphone — Use Voice Memos or QuickTime to verify it works
  4. Move closer to microphone — Especially with built-in mics
  5. Reduce background noise — Fan, AC, or other ambient sounds

Waveform Not Moving

If the recording overlay shows a flat waveform (no animation):

  1. Your microphone isn’t capturing audio
  2. Open Settings → Preferences and check the Microphone dropdown and level meter
  3. Verify the level meter responds when you speak
  4. Select a different input device if available

Using External Microphone

If you have multiple microphones:

  1. Open Settings → Preferences → Microphone
  2. Select your preferred microphone from the dropdown
  3. Check the live level meter responds to your voice
  4. Try recording in Yapper

Yapper supports hot-plug detection — new devices appear automatically when connected, and if your selected device is unplugged, Yapper falls back to the default system input.

Poor Transcription Quality

Wrong or Garbled Text

If transcriptions are inaccurate:

IssueLikely CauseSolution
Wrong wordsBackground noiseReduce noise, speak clearly
Missing wordsSpeaking too fastSlow down slightly
No punctuationModel limitationUse AI Transform for cleanup
Wrong languageLanguage mismatchCheck Settings → Transcription → Language

Improve Accuracy

  1. Use a better model — Parakeet TDT v3 (default) for EU languages, or Large v3 Turbo for 100+ languages
  2. Set correct language — Match Settings to the language you’re speaking
  3. Add custom vocabulary — Add frequently misheard words
  4. Speak naturally — Over-enunciation can reduce accuracy
  5. Reduce background noise — Quiet environments work best

Consistent Misrecognition

If certain words are always wrong:

  1. Add them to Custom Vocabulary (Settings → Transcription)
  2. Try spelling them phonetically
  3. Speak slower when saying those words
  4. Use AI Transform to fix recurring errors after transcription

Recording Cuts Off Early

Recording Stops Unexpectedly

If recording stops before you finish speaking:

  1. Toggle mode confusion — You might be in hold-to-record mode
    • Hold the shortcut longer than 0.3 seconds → hold mode
    • Quick press → toggle mode (press again to stop)
  2. Escape key — May have been pressed accidentally
  3. App crash — Check Console.app for Yapper crash logs

Very Short Recordings

If only part of your speech is captured:

  1. Wait a moment after pressing the shortcut before speaking
  2. Make sure you’re stopping recording correctly:
    • Toggle mode: Press shortcut again
    • Hold mode: Release the keys

Processing Takes Too Long

Normal Processing Time

Processing should take roughly:

  • Real-time on Apple Silicon (5 seconds of speech ≈ 5 seconds processing)

Longer Than Expected

If processing is very slow:

  1. Model is too large — Try Small or Base model
  2. Mac is busy — Close resource-intensive apps
  3. First processing — Initial run is slower; subsequent ones are faster
  4. AI features — AI Transform and Q&A add extra time for the network request

Stuck Processing

If the overlay shows blue (processing) for a very long time:

  1. The model may be stuck
  2. Quit Yapper (menu bar → Quit Yapper)
  3. Reopen Yapper
  4. Check model status in Settings → Transcription
  5. Try a different model

Overlay Not Appearing

No Visual Feedback

If you don’t see the recording overlay:

  1. Yapper may not be receiving the shortcut
  2. Try changing the shortcut in Settings → Preferences
  3. Check if another window is covering it (overlay appears near cursor)
  4. Restart Yapper

Overlay In Wrong Position

The overlay appears near your cursor. If it’s off-screen or the cursor-following behavior is problematic:

  1. Move your cursor to a visible area before recording
  2. The overlay adjusts to stay on-screen
  3. Enable Fixed Position in Settings → Preferences to pin the overlay to the top-center of your screen

Environment Issues

Background Noise

Yapper works best in quiet environments. To reduce noise impact:

  • Close windows near traffic
  • Turn off fans or AC during important recordings
  • Consider a directional microphone
  • Use a headset microphone
  • Position yourself closer to the microphone

Microphone Quality

Built-in MacBook microphones work but have limitations:

  • Susceptible to keyboard noise
  • Pick up ambient sound
  • Quality varies by model

External microphones often provide better results:

  • USB condenser microphones
  • Headset microphones
  • Lavalier (clip-on) microphones

Diagnostic Steps

If none of the above helps:

  1. Test microphone independently

    • Open QuickTime Player → File → New Audio Recording
    • Speak and verify audio is captured

  2. Verify permissions are working

    • Open System Settings → Privacy & Security
    • Confirm Microphone and Accessibility show Yapper enabled

  3. Check model status

    • Settings → Transcription
    • Ensure model shows “Ready” or “Loaded”

  4. Try a clean slate

    • Quit Yapper
    • Delete ~/Library/Preferences/com.yapper.app.plist
    • Reopen Yapper and reconfigure