Troubleshooting

“Local Transcriber can’t be opened”

This is macOS Gatekeeper. The app is signed and notarized by Apple, but Gatekeeper can still show this on first launch.

Fix: Right-click the app in Applications → select Open → click Open in the dialog. You only need to do this once.

No Audio Being Captured

If the app starts recording but no text appears:

1. Check microphone permission. Go to System Settings → Privacy & Security → Microphone and make sure Local Transcriber is enabled.
2. Check speech recognition permission. Go to System Settings → Privacy & Security → Speech Recognition and make sure Local Transcriber is enabled.
3. Restart the app after granting permissions — macOS sometimes doesn’t pick up permission changes until the app restarts.
4. Check your audio output. The app captures system audio from your Mac’s audio output. If you’re routing audio through an external device that macOS doesn’t recognize as the default output, system audio capture may not work.

Only Capturing One Side of the Call

If you see your own speech but not the other person’s (or vice versa):

• System audio (the other person) comes from your Mac’s audio output. Make sure your call audio is playing through your Mac speakers or headphones connected to your Mac.
• Microphone audio (your voice) comes from whichever mic your Mac is using. Check System Settings → Sound → Input to verify the right mic is selected.

Transcript Is Inaccurate

On-device speech recognition is good but not perfect. A few things that help:

• Speak clearly and avoid mumbling.
• Reduce background noise — close windows, mute notifications.
• Use a headset — this gives the cleanest audio signal.
• Wait for post-processing — the live transcript is a rough draft. Post-processing (which runs automatically after you stop) significantly improves accuracy.

Post-Processing Seems Stuck

Post-processing typically takes 10–30 seconds for a 30-minute meeting. If it seems stuck:

1. Check the status. Look at the sidebar — it shows “Processing” with a spinner while working.
2. Check the log. Open Terminal and run:

   tail -f ~/.transcriber/engine.log

   This shows what the app is doing in real time.
3. First run is slower. The first time you record, the app downloads speech models (~50 MB). This only happens once.

Models Not Loading

On first launch, the app downloads on-device speech and diarization models. This requires an internet connection. If models fail to load:

1. Check your internet connection — models are downloaded from Apple’s servers.
2. Check available disk space — models need roughly 200 MB of free space.
3. Restart the app — the download retries on next launch.

Once downloaded, models are cached and the app works fully offline.

App Doesn’t Appear in Menu Bar

Local Transcriber shows a mic icon in the macOS menu bar. If you don’t see it:

• Check the menu bar overflow. If you have many menu bar items, macOS may hide some. Look for a > chevron in the menu bar.
• Make sure the app is running. Check Activity Monitor for “Local Transcriber” or “Transcriber”.

CLI Not Working

If transcriber command isn’t found after installing:

1. Open a new terminal window — the PATH update requires a new shell session.
2. Reinstall — go to Transcriber → Install CLI & Agent Skill… in the app menu.
3. Check the symlink — run ls -la /usr/local/bin/transcriber to verify it exists and points to the app bundle.

Still Need Help?

Check the engine log for detailed diagnostics:

tail -100 ~/.transcriber/engine.log

If you’re still stuck, open an issue on GitHub with the relevant log output.