Skip to main content
Kalam Documentation

Troubleshooting

Targeted fixes for common dictation, hotkey, permission, and model issues. Still stuck? Send a summary and log bundle from Diagnostics & logs through kalamvoice.com/contact.

Placeholder until troubleshooting-diagnostics.webp is added under apps/docs/static/img/screenshots/.

Microphone not detected or silent​

Symptom: No input appears in the status bar, or the pill warns that the microphone is silent.

  1. Confirm OS microphone permission under Permissions by OS.
  2. Choose System default or a specific headset/USB microphone from the status bar or Settings → Voice Input.
  3. Run Test microphone (Record then Play) under Settings → Voice Input to verify input gain.
  4. Replug USB audio hardware or quit apps claiming exclusive audio control.

Hotkey not firing​

Symptom: Pressing Hold to Dictate, Toggle Dictation, or Ask Kalam produces no response.

  1. Confirm the hotkey is assigned and Recording shortcut behavior matches how you press it under Settings → General → Keyboard shortcuts.
  2. Hold past Minimum hold time (default 300 ms)—shorter taps cancel intentionally.
  3. Verify dictation is active (not muted as Dictation off in the sidebar or tray).
  4. macOS: Grant Input Monitoring for hotkeys (Accessibility alone handles text insertion, not global key monitoring).
  5. Linux: Reassign the shortcut if your desktop environment or compositor claims Ctrl+Alt.
  6. Run the Shortcut portal check and Troubleshooting Probes under Settings → Diagnostics.
  7. Windows — Administrator window: Standard windows cannot intercept global hooks while an elevated (Run as Administrator) app is focused. Click a normal window or relaunch Kalam as Administrator for that session. (If dictation did start but only landed on your clipboard afterward, see Text not inserting.)

Text not inserting (clipboard fallback)​

Symptom: The pill, panel chip, or status bar reports Copied — paste manually (Ctrl+V / Cmd+V).

  1. Click into a writable text field and paste (Ctrl+V / Cmd+V).
  2. Windows: Elevated target apps block synthetic typing unless Kalam also runs elevated.
  3. macOS: Grant Accessibility access so Kalam can insert text natively before falling back to paste.
  4. Linux — X11: Ensure the target editor field has keyboard focus.
  5. Linux — GNOME / KDE Wayland: Approve the OS RemoteDesktop / remote interaction permission prompt on first dictation.
  6. Linux — COSMIC Wayland: Confirm compositor IME/virtual-keyboard insertion is active.

Phrase typed instead of acting​

Symptom: Spoken phrases such as "search for…" or "press enter" typed verbatim instead of running a tool.

  1. Start your sentence cleanly with the command prefix (search for Kalam triggers web search; let me search the notes types text).
  2. Press Enter After Typing starts off by default—enable it under Commands (Typing & Keys).
  3. Verify trigger phrasing and category status on Commands and Ask Kalam.

Poor accuracy or wrong language​

Symptom: Missing technical terms, wrong language guesses, or messy punctuation.

  1. Verify your profile's Hear your voice engine and recognition language under Dictation → Models or the profile editor (Speech engines).
  2. Add names and product terms under Dictionary → Recognition.
  3. Leave Audio cleanup on Light (or Moderate in noisy rooms) under Settings → Voice Input.
  4. For polished prose, enable Improve with AI (Pro) with clear writing instructions (AI polish).

Offline / local engine errors​

Symptom: Network errors or a protected-app failure complaining that no local model is ready.

  1. Install Sherpa-ONNX or Whisper.cpp and download a model (SenseVoice Small, Whisper Base, Parakeet TDT 0.6B, or Moonshine Small) under Settings → AI & Models → Local providers (Local models).
  2. Verify the profile's Hear your voice engine points to On-device (or relies on it automatically for Sensitive apps).

Sensitive app blocks Commands or context​

Symptom: Ask Kalam, Commands, or Read your surroundings do not run inside a password manager or listed app.

  1. This isolation is intentional whenever Sensitive apps matches the foreground process.
  2. Remove an app from Settings → Privacy → Sensitive apps only if you intentionally want cloud speech, screen context, and Commands active there.

Linux panel chip missing​

Symptom: No status widget appears in the top or bottom bar on Linux.

  1. Linux uses a native panel applet rather than a floating pill (Linux panel chip).
  2. Add Kalam Dictation for your desktop environment (GNOME, KDE, Cinnamon, MATE, Xfce, or COSMIC).
  3. Ensure Kalam is running—the chip displays Not running (or Kalam offline when disconnected from the background daemon).
  4. Note that the standalone tray icon hides intentionally once a panel applet connects.