Skip to main content
Find your symptom and open it.
The download is fine. macOS shows this message for any app that is not signed with a paid Apple Developer certificate. SpeakoFlow is not signed yet.One Terminal command clears the block, once per .dmg you download:
Then open the app normally. Updates installed from inside the app are not tagged, so they do not need this step. If you download a new .dmg by hand, run the command again for that copy.More detail in Install.
After an update, macOS sometimes shows SpeakoFlow as allowed under Accessibility, Microphone, or Screen Recording while no longer honoring it. If a permission check in the app keeps waiting even though the toggle is on, go to the relevant section in System Settings → Privacy & Security, click Reset permission (or remove SpeakoFlow from the list), then add it back and restart the app.
The Fn (globe) key is shared between SpeakoFlow and the system emoji picker. Go to System Settings → Keyboard and set Press 🌐 key to to Do Nothing. SpeakoFlow then gets the key press without interference.Macs that were already on the older Option + Space defaults before the Fn defaults shipped keep their Option-based shortcuts after updating. You can switch to the new defaults by clicking the keys in Settings → Shortcuts and choosing “Use default”.
SpeakoFlow’s installer is not code-signed yet, so Windows SmartScreen may show a warning the first time you run it. Choose More info → Run anyway. This happens once per version.
The Whisper engine in SpeakoFlow requires a CPU with AVX2, FMA, F16C, and BMI2 support. Most CPUs made after 2013 have these. If your CPU does not, SpeakoFlow shows a message instead of crashing.Use a non-Whisper model instead: Parakeet, Canary, or any ONNX-based model in the catalog works on any CPU. You can also use cloud transcription.
Model downloads resume where they stopped. A .partial file in the models folder holds the progress. Restart the download from the Models page and it picks up from the last byte.If the download keeps failing, check your network connection. Downloads fetch eight chunks at once from Hugging Face (or a mirror), so a firewall blocking that host would stop them. The model page shows the download’s progress and any error.
A few things to check:
  1. Onboarding finished? Shortcuts are only registered after you complete the first-run setup. If you closed the app partway through, open it again and it picks the setup back up.
  2. Another app took the key? Some apps register the same global shortcut. Try recording a different shortcut in Settings → Shortcuts.
  3. Linux keyboard engine. On Linux with the Tauri engine (the default), shortcuts are registered through X11 and may only work while an X11 window has focus under native Wayland. Compositor-owned shortcuts are more reliable. See Command-line flags for examples.
  4. Linux input group. If you switched to the handy-keys engine and the log shows rdev grab error: PermissionDenied, add your user to the input group and log out:
    Or switch the engine back to Tauri in Settings → Advanced → Experimental.
The overlay needs to float above every other window. On Linux that requires wlr-layer-shell (Sway, Hyprland, KDE Plasma) or X11 “keep above” stacking.GNOME on Wayland supports neither. SpeakoFlow detects this and runs under XWayland automatically, where the overlay floats normally. No setup needed.Two escape hatches if you need them:
  • Force native Wayland: launch with SPEAKOFLOW_ALLOW_WAYLAND=1. The overlay may not stay on top.
  • Disable layer shell: launch with SPEAKOFLOW_NO_GTK_LAYER_SHELL=1 if the overlay misbehaves under a layer-shell compositor.
Setting GDK_BACKEND yourself always wins.
A crash with DrawingArea_CommitTransientZoom in the log is a WebKitGTK bug, not a SpeakoFlow bug. It affects many apps built on WebKitGTK and is tracked in tauri#13115 and wry#544.Avoid pinch-to-zoom inside the app window until there is an upstream fix. Updating your system’s webkit2gtk-4.1 packages can help.
macOS gives apps no direct way to record system audio. Windows has WASAPI loopback and Linux has PulseAudio/PipeWire monitor sources, but a Mac needs a virtual audio device.Install a loopback driver like BlackHole, create a Multi-Output Device in Audio MIDI Setup that sends sound to both your speakers and BlackHole, and make it your output. SpeakoFlow can then record the other side of the call. Your microphone is recorded either way.
Check three things:
  1. API key. Make sure the key is entered for the right provider in the cloud transcription settings on the Models page.
  2. Model. Some providers have separate model namespaces for transcription. OpenRouter, for example, requires the vendor/model slug (like openai/whisper-large-v3).
  3. Base URL. For Azure AI Speech, the URL must point to your own resource in a region that supports MAI-Transcribe.
A conversation speaks every reply regardless of the “Read answers aloud” switch. If you hear nothing:
  1. Check that a voice is selected on the Assistant page under Voice.
  2. If you use a cloud voice engine (not Kokoro or another local voice), make sure the engine has an API key and the key works.
  3. On Linux, check that your audio output device is working. The output device in Settings → Audio is for feedback sounds only. The assistant uses the system default output.
Raise the paste delay and the extra recording buffer in Debug settings.If one specific app misbehaves with clipboard paste, try the Direct paste method.
Still stuck? Open an issue with your log level raised to Debug or Trace. See Debug & advanced for where the log file is.
Last modified on August 30, 2026