Skip to content

Troubleshooting

Diagnose Yap startup, model, microphone, hotkey, paste, and transcription problems on macOS, Windows, and Linux.

Start here

Note your Yap version, OS version, architecture, provider, and model. The latest stable version is 0.5.0; release status lists its fixes and features. Upgrade older builds before comparing behavior.

Test a short recording from Home, then test the hotkey in a plain-text editor. This separates capture/transcription failures from desktop integration problems.

Hotkey Not Working

  • macOS: enable Accessibility for the installed copy in Applications. After an update, quit Yap and re-add that copy if the old permission entry is stale. The 0.5.0 recovery screen can re-register the hotkey.
  • Windows: the default is Right Alt, not Option. Try F9 if AltGr or another application uses the key. Test in a non-elevated editor.
  • Linux: global keys use X11. Native Wayland support is not implemented. Use X11 or start recording from Home.

Change both recording and cancel keys through Settings. There is no universal Return-to-stop shortcut.

No Audio Recording

Check the chosen microphone, hardware mute, and system input level. On macOS enable Yap under Microphone privacy settings; on Windows enable microphone access for desktop apps. On Linux check PulseAudio/PipeWire routing.

Compare against a built-in or USB microphone if a Bluetooth headset changes profile or sounds poor. An animated recording illustration is not proof that useful audio reached the recorder.

Transcription Fails

Local

Wait for a downloaded model to become ready. The release app bundles Whisper runtimes; do not begin by installing an unrelated Homebrew version.

  • Windows portable: extract the entire ZIP and retain portaudio.dll and bin. Copying Yap.exe alone is insufficient.
  • macOS: confirm you are using the Apple Silicon build on an Apple Silicon Mac. Quit and reinstall the package if bundled files are missing.
  • Linux: check the selected ubuntu22/ubuntu24 package against your GTK/WebKit libraries. Launch from a terminal to see missing-library messages.

Yap 0.5.0 improves runtime verification, Windows child-process handling, and macOS Metal/CPU fallback.

OpenAI

Check the saved API key, internet connectivity, and your OpenAI API billing/quota. A ChatGPT subscription does not supply API credit. Never paste a key into an issue or screenshot.

Poor Transcription Quality

Use .en only for English. Pick a multilingual model for other languages. The explicit auto language selection fix from PR #18 ships in 0.5.0. If multilingual output is wrong, report the model and language along with your version.

Reduce background noise and compare a larger model on the same recording conditions. Review important text manually; model size does not guarantee correctness.

Slow Transcription

Try Tiny or Base and distinguish initial model warmup from later recordings. Large models need more memory and compute. Yap 0.5.0 includes Metal-first local inference on Apple Silicon with CPU fallback. Do not assume GPU acceleration or a fixed processing time on every platform.

Text Not Pasting

Confirm auto-paste is enabled, your target input is focused, and that it accepts normal paste. Retrieve text from History if necessary.

  • macOS: verify Accessibility; use Cmd+V manually to test the clipboard.
  • Windows: test a normal editor rather than an elevated app. Yap simulates Ctrl+V through PowerShell.
  • Linux: install xdotool and xclip or xsel in an X11 environment. Some terminals use Ctrl+Shift+V instead of the simulated Ctrl+V. Native Wayland applications may not accept this workflow.

Model Download Fails

Check access to Hugging Face and available disk space. In the Models Library, cancel the active download, wait for cancellation, and retry. Only one download runs at once; downloading does not select the model automatically outside onboarding.

For 0.4.2 use its Settings model controls. Quit Yap before manually inspecting the models directory. A missing or incomplete ggml-*.bin needs a fresh download, not just a filename change.

Transcription text file not saved

In Settings, choose an existing writable output folder and enable Save transcriptions as .txt. Choosing a folder alone does not enable saving. Only future successful transcriptions are saved; existing history is not exported.

If Yap reports an output error, check disk space, folder permissions, and whether an external or network drive is connected. The transcript remains in History and clipboard/auto-paste proceeds independently. Choose a writable folder or disable saving to clear the error. A later successful save also clears it, but the failed file is not retried automatically: copy that transcript from History and save it manually.

App Crashes on Launch

Do not reset all user data as the first step. Collect logs, verify the package architecture, and reinstall the complete package first.

  • macOS: the distributed DMG is arm64, not universal. Intel-through-Rosetta instructions in older docs were incorrect. Check Privacy & Security if Gatekeeper blocks opening.
  • Windows: check WebView2 and the extracted/installed runtime files. The 0.5.0 bundled local runtime requires AVX2; older releases may have different CPU behavior.
  • Linux: check WebKitGTK 4.0 versus 4.1, FUSE support for AppImage, and the display session. Prefer apt install ./filename.deb to resolve dependencies.

Logs and crash diagnostics

Find logs/ in your data directory. Normal logs are named yap-YYYY-MM-DD.log and retained for seven days.

Yap 0.5.0 additionally captures yap-stderr-YYYY-MM-DD.log and reports unclean previous sessions. Older 0.4.2 builds do not include this crash capture.

When reporting an issue, include reproduction steps, OS/architecture, version or commit, model/provider, and relevant errors. Review logs for personal paths and text, and exclude API keys, private recordings, and config.json.