Troubleshoot the setup in the order AFK uses it.

Model first, permissions next, then the focused app or audio file. The CLI has its own short checklist at the end.

The model is still preparing

First-run setup downloads and optimizes the speech model. Check that the Mac is online, that there is roughly 2 GB of free disk space, and that AFK remains open while setup runs. The setup screen can retry after a failed download.

If the model is ready in the app but a dictation says it is still setting up, wait for the status to settle and try again. The CLI also prepares the model on its first invocation.

License activation fails

Confirm that you pasted the key from the purchase email without extra spaces and that the Mac can reach Polar. A malformed or unknown key is different from a temporary network error. The app can continue without activating after a failed attempt, so you can retry later.

Activation sends the key to Polar's customer-portal endpoint; it does not send your audio.

The hotkey does nothing

  1. Open System Settings → Privacy & Security → Accessibility and ensure AFK is enabled.
  2. Check Microphone permission in the same Privacy & Security area.
  3. Return to AFK. It polls permission state and tries to arm the global listener again.
  4. Hold the configured key, not necessarily the default Right Option key if you changed it in Settings.

Accessibility is needed for both the global event tap and typing into other apps. Microphone is needed to capture the recording.

The transcript is not appearing in the app

Check whether the focused element is actually editable. AFK pastes into a known editable field. For an unknown or non-editable target, it keeps or places the transcript on the clipboard so you can paste manually. You can also enable Always copy to clipboard instead of typing in Settings.

If the transcript is on the clipboard, click the intended field and press Command + V. If no text appears anywhere, check Microphone permission and the speech model status first.

A dictation could not be transcribed

AFK keeps the audio of each dictation on this Mac for 24 hours. A dictation whose transcription failed appears at the top of Notes under Couldn't transcribe. Choose Try again to transcribe it again; the text goes into your notes and onto the clipboard, so paste it where you meant it to go. Delete removes it.

Dictation starts late on AirPods or Bluetooth earbuds

That short delay is macOS switching the earbuds into call mode when a mic opens, which also makes music sound flat until you stop. Wait a moment before speaking, or use wired earphones or the Mac's own mic, which have no such delay. Connecting or removing earbuds mid-dictation is fine: the recording continues on the new mic.

Hands-free mode starts or stops unexpectedly

Hands-free starts only while the dictation key is held and the full start sequence is pressed. The default start sequence is A-F-K. The default stop action is the dictation key plus Return. Both sequences are configurable, so inspect Settings if the on-screen hint does not match your memory. Escape cancels an active recording.

An audio or video file will not transcribe

  • Confirm the model is ready.
  • Start with one supported file: audio as .m4a, .wav, .mp3, .aiff, .aif, .caf, or .flac, or video as .mp4, .mov, or .m4v.
  • A video must contain an audio track. Without one, the job shows an error.
  • Try opening or playing the file in a Mac audio or video app first. AFK relies on macOS to read and convert it.
  • If one queued job fails, remove it and try again. Other queued jobs can continue.
  • If you save finished files to a folder and a job shows a save error, such as SRT for a result without timings, use that job's Save menu instead.

For the exact file flow, see Transcribe audio and video.

A finished result disappeared

Non-empty file results that were not saved expire from the local cache one hour after completion. Save the result from the card before that countdown ends. Once saved, the file is yours and the Files tab in Notes keeps a reference to it.

The CLI prints the wrong thing

  • Check the alias points to /Applications/AFK.app/Contents/MacOS/AFK, or invoke that path directly.
  • Use the form afk transcribe file.m4a. Put the audio or video path as the first bare argument.
  • Transcript output is stdout. Model progress and errors are stderr, so redirect or pipe stdout deliberately.
  • Use --srt or --json for structured output, --v2 for the English-only model, and --lang en or another ISO 639-1 hint with v3.

On the first CLI run, model preparation may need the network. Once ready, recognition is local. See the full CLI reference.

Updates are not checking

AFK uses Sparkle for in-app update checks. A failed update check does not change local dictation or transcription. Check your connection and try again later; the updater is separate from the speech-processing path.

Still blocked? If you've bought AFK, my email is in the app under Settings → About. Include the exact error text, the file extension or permission involved, and whether the model status says ready. That makes the problem reproducible without sending an audio recording.