Troubleshooting

Most things that go wrong in a live call are one of a small number of failures, and the app tries to tell you which. A channel that has stopped working keeps saying so — it is shown as a state beside the meter, not as a notice that scrolls away — so if something looks dead it should keep looking dead until it recovers.

Before a call, the fastest check is whispr doctor in a terminal. It exercises capture, transcription, every engine and the prep index, and it is quicker than guessing.

You may not have that command yet. The app does not put one on your PATH until you ask it to: open Settings → The whispr command → Install the whispr command, then open a new terminal. It writes a small shim that runs the copy of Whispr you already have — nothing is downloaded, and nothing else in the app needs it. Every whispr … command in this manual works once it is there.

Everything below can also be done from the window if you would rather not use a terminal: Preflight covers doctor and preflight, Settings covers the credentials, engines, transcriber and headroom commands, and History covers debrief.

"Not connected to the background service"

The background service is what does the work: it holds the database, the audio and the engines, and it runs whether or not the window is open. The banner means the window cannot reach it, and it now says which of three things is true.

Starting it again — it stopped on its own and Whispr is restarting it, with the attempt count once there has been more than one. Nothing to do but wait; a meeting that was being recorded has stopped, and the banner says so.

It will not start — the reason is on the banner. Quit and reopen Whispr first. If it keeps happening, whispr doctor in a terminal checks everything the service needs.

Reconnecting — the service is there and the connection dropped. It comes back on its own.

What was recorded before the break is kept. A meeting cut short this way is closed properly the next time Whispr starts, so its length in History is the length that was actually recorded.

If you are reporting it, the service's own output is in core.log, beside the database in Whispr's application-support folder. It is truncated every time the app launches, so open it before relaunching. Unlike secrets.json in the same folder, it is safe to paste — no credentials are written to it.

Symptoms

Wear headphones

The echo path is real and was measured on this app's own hardware: with the speakers playing the other side of the call, the microphone picked that voice up at close to half the level it came out at.

Two things follow. In a live call, a bled-through copy of their words can be transcribed slightly before the original, and be recorded as something you said — the app holds your microphone briefly and drops the echo, but headphones remove the problem instead of managing it.

In the spoken practice mode there is no such guard, by design: the voice agent does its own turn-taking straight off the microphone. On speakers it hears itself, decides you have started answering, and stops mid-question.

Permissions

The two platforms differ here more than anywhere else in the app, so this section is in two halves. whispr doctor reports the right one for your machine; if what it says disagrees with what you read here, believe it.

On a Mac: why an audio app wants Screen Recording

It never looks at your screen. On macOS there is no separate permission for system audio — the only sanctioned way to hear what the other side says is ScreenCaptureKit, the same API that can capture pixels, so Apple gates both behind one permission and names it Screen & System Audio Recording. Whispr asks that API for audio only.

Your microphone is a different permission and hears only you. That is why practice mode needs no Screen Recording at all: there is no other side, so nothing but the microphone is opened.

Permissions belong to the launcher. macOS grants both to the responsible app — the terminal, or Whispr itself — never to the small helper that does the capturing. whispr doctor names the one to tick, because "the app running Whispr" is not something you can find in a list: run the same command from Terminal and from another app and you get opposite answers, seconds apart. This is the single most common reason the other side of a call is silent, and it looks exactly like a bug in the app. Check permissions before suspecting anything else.

It also means the same install can be granted in one place and not another: run Whispr from a different terminal and it starts again with nothing, which is bewildering until you know why.

To be asked, run whispr permissions. It prompts macOS directly. whispr doctor deliberately cannot — it only queries the current state, which is why it could tell you a permission was missing and then leave you to find the settings pane yourself.

Two macOS rules the command works around rather than hides:

• A refusal is final. Once you have said no, macOS never shows that prompt again; the only route is System Settings, so the command opens the right pane instead of pretending to retry.
• Screen Recording needs a restart after granting, even once the tick is there. If the box is ticked and capture is still silent, quit and reopen.

whispr doctor distinguishes the two: never asked for is not a refusal, and it says so, because the fixes are different.

On Windows: there is almost nothing to grant

Hearing the other side needs no permission at all. Windows lets an application record the system mix without asking anyone, so there is no equivalent of Screen Recording, nothing to tick, and no restart. whispr doctor shows that row as passing, and it is passing rather than unchecked.

That has a consequence worth knowing when the them meter stays flat: since no permission can be the cause, the cause is almost always that nothing is playing or the output is muted. Whispr captures the mix after the volume slider, so a muted output is digital silence — the same as no call at all.

The microphone prompts once, from the app. It is an ordinary Windows microphone prompt and it appears the first time Whispr opens the microphone, not when you install it. If you dismissed it, or microphone access is off for the machine, turn Whispr on under Settings › Privacy & security › Microphone.

whispr permissions cannot raise that prompt on Windows and says so rather than appearing to try: the prompt belongs to the app window, and a command-line tool has no window to attach it to. It reports what the setting currently says and opens the right page.

Windows: the app window has to be open

This is the one real limitation of the Windows build, and it is worth knowing before a call rather than during one. Whispr captures audio inside its own window there — that is what makes the system-audio side need no permission — so a headless whispr start runs everything except the recording.

In practice: leave Whispr open during a meeting. Minimised is fine, and behind your video call is fine. Closed is not.

"Audio is arriving but nothing has been transcribed"

This notice means exactly what it says, and the important half is what it rules out: capture is working. Sound is reaching Whispr — the meters are moving, the microphone is fine — and the transcription provider has stopped returning words. The transcript for that stretch is being lost while it continues.

It waits a full minute of speech-level audio before saying anything, and it never fires on a quiet room, so if you see it something is genuinely wrong. It says it once rather than every few seconds.

What to do, in order:

1. Check the transcriber — whispr transcriber shows which one is in use. If it is a local whisper server, it may have stopped.
2. Check the key still works — whispr preflight --check proves it for real rather than reading a stored result.
3. Restart the session. The transcript already recorded is kept; only the silent stretch is gone.

Why this can happen at all: a transcription socket that is open and receiving is reported healthy, and stays reported healthy when the far end quietly stops transcribing. Gemini live also has to replace its connection every nine minutes, because Google caps a session at ten — that replacement is normal and invisible, and this notice is what tells you when one did not come back.

If a past interview looks thin, whispr debrief puts a number on it. A twenty-eight minute interview that recorded fifty words of your speech did not have a quiet candidate; it had a hole.

Nothing is thrown away

A real call happens once, so the app is built to degrade rather than stop. A missing credential skips an engine, a failed classifier falls back to simpler rules, one engine timing out never blocks another, and a partly-written answer is kept rather than discarded.

If something did go wrong, the transcript and everything produced before it are still in History.