Troubleshooting

First, check your Mac is supported

Symptom: the installer won’t finish, or features and speech languages are missing.

Why: SpeakMercury requires macOS 26 (Tahoe) or later on an Apple Silicon Mac (M1 or newer). Intel Macs are not supported.

Fix:

1. Open the Apple menu > About This Mac and confirm it shows an Apple chip and macOS 26 or later.
2. If not, upgrade macOS or use a supported Mac.

Dictation produces nothing when a Bluetooth speaker is connected

Symptom: the engine looks live but no transcript appears.

Why: an output-only Bluetooth device makes the audio route flap. The mic input is left with a stale format and starves, and the app only rebuilds it once before giving up.

Fix:

1. Disconnect the Bluetooth speaker.
2. Quit SpeakMercury.
3. In System Settings > Sound > Input, select your Mac’s built-in microphone. Output can stay on the speaker.
4. In SpeakMercury’s Settings, set the microphone explicitly to the built-in mic instead of Automatic.
5. Relaunch and click Start dictating.

System audio turns muffled while dictating on Bluetooth headphones

Symptom: music and video drop to phone-call quality during dictation, and the app shows a one-time “Bluetooth Microphone In Use” warning.

Why: capturing audio from a Bluetooth headset forces it into a low-quality call mode, which affects all system audio, not just SpeakMercury.

Fix:

1. Dictate with the built-in mic or a wired mic.
2. Keep the Bluetooth headphones for output only.
3. Dismiss the one-time warning with OK.

The hotkey beeps but dictation never starts

Symptom: a beep, no overlay, no transcript.

Why: macOS hasn’t granted microphone access, so the app beeps and stops instead of starting.

Fix:

1. Open System Settings > Privacy & Security > Microphone.
2. Turn on SpeakMercury.
3. Relaunch SpeakMercury.
4. Press your shortcut again.

Dictation runs, but the text never pastes

Symptom: the live transcript works, but nothing lands in the text field. Or a beep when starting.

Why: pasting on your behalf (and the Esc-to-cancel tap) requires Accessibility trust.

Fix:

1. Open System Settings > Privacy & Security > Accessibility.
2. Turn on SpeakMercury.
3. Relaunch SpeakMercury.
4. Dictate again.

“Failed to start dictation” with a language error, or a long pause in a new language

Symptom: an alert saying dictation failed to start, mentioning the language. Or: the very first Start in a new language stalls, then later runs work.

Why: the selected language isn’t one your Mac’s speech recognizer supports, or its model is still downloading on first use.

Fix:

1. In SpeakMercury’s Settings, set the language to English or another language your Mac lists as available.
2. Start dictation once and let the first-use model download finish without quitting.
3. Try again. After the download, recognition runs on your Mac and later starts are quick.

Text pastes into the wrong app

Symptom: the Try It Now field stays empty and the dictated text appears somewhere else.

Why: paste follows keyboard focus. Outside onboarding, SpeakMercury pastes into the frontmost app, so if focus left the target field, the text goes wherever focus went.

Fix:

1. Click into the target text field first.
2. Start dictating.
3. During onboarding, keep the Try It Now window in front and the field focused.

Crash when clicking Start, or the mic indicator flickers on and off

Symptom: the app quits unexpectedly on Start dictating, or the mic indicator flashes on and off. Most reported on macOS 26 with a Bluetooth audio device connected.

Why: older builds had an audio-restart bug and a related crash that audio route changes could trigger. Largely fixed in version 1.4.10.

Fix:

1. Update to the latest SpeakMercury (1.4.10 or later). Download the current DMG below if you’re on an older version.
2. Remove output-only Bluetooth audio devices from the equation, or set the microphone explicitly to built-in.
3. Relaunch before clicking Start again.

The hotkey or Start does nothing at all

Symptom: pressing the shortcut or Start is a silent no-op on every attempt.

Why: most often a shortcut conflict, or being signed in without an active purchase. The app quietly does nothing until both are in order.

Fix:

1. Open Settings and confirm the shortcut is set (default: Option Space). Reset to default if you customized it.
2. Confirm the same Settings window shows your purchase active.
3. If sign-in looks stale, sign out and back in.
4. Press the shortcut with the cursor in a text field.

Onboarding reappears every launch

Symptom: the setup wizard returns after you completed it.

Why: the completed flag resets whenever microphone or Accessibility permission has been revoked, so the app re-runs setup.

Fix:

1. Re-grant Microphone and Accessibility as shown above.
2. Complete onboarding once.
3. Relaunch to confirm it stays away.

“Audio device changed and could not restart”

Symptom: that alert appears after plugging or unplugging audio gear mid-dictation.

Why: dictation was running when the audio route changed, and the engine couldn’t restart itself on the new device.

Fix:

1. Stop dictation.
2. Set the microphone back to built-in.
3. Start dictating again.

The app never offers updates

Symptom: no update checks and no update prompts.

Why: some builds ship without an update feed, so the built-in updater stays off by design.

Fix:

1. Download the latest DMG from the home page.
2. Drag it to Applications.
3. Relaunch.

Start fresh: clean uninstall or permission reset

Symptom: you want a clean slate for microphone, speech, Accessibility, settings, and license data, for example after stale permission entries.

Fix:

1. Download our uninstall script.
2. Run cd ~/Downloads && chmod +x uninstall.sh && ./uninstall.sh in Terminal.
3. Add --full to also remove settings and license data.
4. From a source checkout you can instead run make reset-permissions.