Troubleshooting

On-device transcription

In Settings → Transcript Agent, choose On-device only. BlabToText checks whether Apple Speech supports the current device and language. Speech Recognition and Microphone permissions may be required.

Cloud providers

In Settings → Transcript Agent, choose a cloud mode, select OpenAI, Groq, xAI, or Google, and enter that provider's own API key. Save applies the selected mode and settings. This is bring-your-own-key (BYOK), not a ChatGPT or Claude desktop connection; provider API charges are separate from those subscriptions. OpenAI, Groq, and Google expose model choices; xAI selects its REST transcription model automatically. Keys stay in separate Apple Keychain entries. The named Test button (for example, Test xAI Connection) queries only the selected provider; no audio is sent. Switching providers keeps each draft key, model and completed check with its provider while the dialog is open. Save lists all entered keys it will store separately; Cancel discards drafts. Saved-key status is checked only when needed, not probed merely by opening this dialog. Connection details expands exact endpoints and advanced manual model entry; xAI uses Automatic with no model picker. Before testing, the models are bundled suggestions, not verified for your key. Listing success does not prove transcription access or available quota. xAI/Grok and Z.ai/GLM are different services; Z.ai is not supported in this beta.

Mac permissions

Microphone records speech. Input Monitoring detects the push-to-talk key without reading or storing typed content. Direct builds can request Accessibility for optional automatic paste; the Mac App Store build uses the Clipboard.

When testing through TestFlight, grant Input Monitoring to /Applications/BlabToText.app, not a local development preview with a similar name. Quit and reopen after the grant if requested. Check Settings → Record Shortcut Key for the selected key; new installs default to Right Option.

Recording problems

Confirm the input device in System Settings, grant Microphone access, and run Help → Test Microphone (3 Seconds). Recording stops automatically after up to two minutes; older Apple Speech modes use a shorter safety limit. Press Escape to cancel recording or transcription.

It recorded, but did not paste

Try ⌘V first: copying is the default and the App Store build is clipboard-only. In the direct build, check Settings → Recording Mode and Accessibility permission. Keep the original app, window, and text field focused. If the target cannot be verified, BlabToText copies instead. Latest Transcript also lets you recover and copy your words.

Pause countdown or Enter is unexpected

In Settings → Recording Mode, choose tap-and-pause mode and adjust the interval and sensitivity. Ambient noise can reset the countdown; it is based on volume, not word recognition. Transcription happens after the countdown. Enter requires the direct build, automatic paste, the explicit Enter setting, and completion by silence.

Where is the recording indicator?

It appears near the bottom of the display containing your pointer when recording starts. Check your other display if needed. Copper means recording, amber means a pause countdown, and teal means transcribing. The BlabToText menu-bar mark also indicates recording. Escape cancels even if the floating indicator is obscured.

Imported text or a draft seems missing

In Latest Transcript, choose Load Latest to view a newer result when your edited draft is being protected. Imports require Apple on-device support and do not use cloud fallback. Completed sections remain after cancellation, but the workspace is session-only: copy anything you need before quitting.

Provider errors

Verify that the key belongs to the selected provider, the model is enabled for your account, and your provider quota is available. You can remove and replace a key from Settings without editing files.

Still stuck?

Use the BlabToText support form with your Mac model, macOS version, selected mode/provider, and the exact error message. Never send an API key or a private recording.