Troubleshooting

Recording Issues

Hotkey Not Working

Symptoms:

• Pressing the hotkey does nothing
• No recording overlay appears

Solutions:

1. Check Accessibility permissions (macOS)

   • Go to System Settings → Privacy & Security → Accessibility
   • Ensure Yap is enabled
   • Try removing and re-adding if already enabled

2. Try a different hotkey

   • Go to Settings → Recording Hotkey
   • Select an alternative (Left Option, Fn, or Double-tap)

3. Check for conflicts

   • Other apps may be capturing the hotkey
   • Try quitting other apps that use global hotkeys

4. Restart Yap

   • Quit completely (including from menu bar)
   • Reopen the app

No Audio Recording

Symptoms:

• Recording starts but transcription is empty
• Waveform shows no activity

Solutions:

1. Check Microphone permissions (macOS)

   • Go to System Settings → Privacy & Security → Microphone
   • Ensure Yap is enabled

2. Select the correct audio device

   • Go to Settings → Audio Input Device
   • Choose your active microphone

3. Test your microphone

   • Use another app to verify the mic works
   • Check system sound settings

4. Check physical connections

   • Ensure external mics are properly connected
   • Check USB connections

Transcription Issues

Transcription Fails

Symptoms:

• Error message after recording
• “Transcription failed” error

Solutions:

1. For local transcription:

   • Ensure whisper-cpp is installed:

     brew install whisper-cpp
     

   • Verify it’s in PATH:

     which whisper-cli
     

   • Ensure a model is downloaded in Settings

2. For OpenAI:

   • Verify your API key is correct
   • Check your OpenAI account has credits
   • Test API access:

     curl https://api.openai.com/v1/models \
       -H "Authorization: Bearer YOUR_API_KEY"
     

Poor Transcription Quality

Symptoms:

• Many mistakes in transcription
• Missing words or phrases

Solutions:

1. Use a larger model

   • Try small.en or medium.en for better accuracy
   • large-v3 offers highest accuracy

2. Improve audio quality

   • Use an external microphone
   • Reduce background noise
   • Speak clearly and not too fast

3. Try cloud transcription

   • OpenAI Whisper often has better accuracy
   • Enable in Settings → Provider → Cloud

Slow Transcription

Symptoms:

• Long wait time after recording
• App appears frozen during transcription

Solutions:

1. Use a smaller model

   • tiny.en or base.en are fastest
   • Larger models take longer

2. Use cloud transcription

   • OpenAI’s servers are faster than local processing
   • Especially helpful on older hardware

Auto-Paste Issues

Text Not Pasting

Symptoms:

• Transcription completes but text doesn’t appear
• Text goes to clipboard but doesn’t paste

Solutions:

1. Check Accessibility permissions

   • Auto-paste requires Accessibility access
   • Re-add Yap in System Settings

2. Check target application

   • Some apps block paste commands
   • Try pasting manually with Cmd+V

3. Disable and re-enable auto-paste

   • Go to Settings → Auto-Paste
   • Toggle off, then on

4. Try another application

   • Test with a simple app like Notes or TextEdit
   • Some apps have non-standard text input

Model Issues

Model Download Fails

Symptoms:

• Download starts but never completes
• Error during download

Solutions:

1. Check internet connection

   • Models are downloaded from HuggingFace
   • Verify you can access https://huggingface.co

2. Check disk space

   • Large models need several GB
   • Free up space if needed

3. Retry the download

   • Cancel and try again
   • Network issues may be temporary

4. Manual download

   • Download models directly from HuggingFace
   • Place in ~/Library/Application Support/yap/models/

Model Not Found

Symptoms:

• “Model not found” error
• Transcription fails with model error

Solutions:

1. Download the model

   • Go to Settings and download the selected model

2. Check model files

   • Verify model exists:

     ls ~/Library/Application\ Support/yap/models/
     

3. Re-download corrupted model

   • Delete the model file
   • Download again from Settings

Installation Issues

macOS Security Warning

Symptoms:

• “Cannot be opened because it is from an unidentified developer”
• App won’t launch

Solutions:

1. Allow in Security settings

   • Go to System Settings → Privacy & Security
   • Find the message about Yap
   • Click “Open Anyway”

2. Remove quarantine attribute

   xattr -d com.apple.quarantine /Applications/Yap.app
   

App Crashes on Launch

Symptoms:

• App immediately closes after opening
• Crash report appears

Solutions:

1. Check system requirements

   • macOS 10.15 or later required
   • Apple Silicon or Intel (via Rosetta)

2. Reset configuration

   rm ~/Library/Application\ Support/yap/config.json
   

3. Reinstall the app

   • Delete from Applications
   • Download fresh from releases

Performance Issues

High CPU Usage

Symptoms:

• Fan running during transcription
• System slowdown

Solutions:

1. Use a smaller model

   • tiny.en uses least CPU

2. Use cloud transcription

   • Offloads processing to OpenAI

3. Close unnecessary applications

   • Free up CPU resources

High Memory Usage

Solutions:

1. Use smaller models

   • Large models load entirely into RAM

2. Quit and restart

   • Clears any memory leaks

Getting Help

If these solutions don’t help:

1. Check GitHub Issues

   • Search for similar problems
   • github.com/ApplauseLab/yap/issues

2. Open a new issue

   • Include your OS version
   • Include Yap version
   • Describe steps to reproduce
   • Include any error messages