Skip to main content

Troubleshooting

Common problems and fixes for dictation, hotkeys, insertion, and accuracy. Still stuck? Open an issue on GitHub or email hello@balacode.io with your OS, version (Settings → About), and logs from Diagnostics and logs.

Microphone not detected or no permission​

Problem: No mics in the status bar, or recording is silent.

Fix:

  1. Grant microphone access in the OS (Windows: Privacy → Microphone; macOS: Privacy & Security → Microphone → Kalam).
  2. Pick System default or a specific device in the status bar mic selector.
  3. Use Test microphone under Settings → Voice Input if available — confirm playback of your sample.
  4. Unplug/replug USB mics; close apps that exclusively lock the device.

Hotkey not firing​

Problem: Hold or toggle does nothing.

Fix:

  1. Confirm the shortcut under Settings → General → Keyboard shortcuts and that recording behavior includes Hold and/or Toggle.
  2. Hold longer than the minimum hold (default 300 ms) — short taps cancel.
  3. Check another app is not capturing the same combo; try a different shortcut.
  4. On macOS, grant Input Monitoring (and Accessibility) for Kalam.
  5. Ensure dictation is not off (status bar should show Ready, not Dictation off).
  6. Run hotkey diagnostics under Settings → Advanced → Diagnostics if needed.

Text not inserting (clipboard fallback)​

Problem: Pill or status bar says text was copied — paste manually.

Fix:

  1. Click into a writable field, then paste (Ctrl+V / Cmd+V).
  2. macOS: add Kalam under Accessibility (and Input Monitoring).
  3. Windows: if the target app runs as Administrator, run Kalam elevated too, or use a non-elevated target.
  4. Some Electron apps need a click in the field first; retry after focusing the input.
  5. Sensitive apps prefer typing over paste — if injection fails, paste may still work from the fallback.

Phrase typed instead of acting​

Problem: You said “online search …” or “press enter” and Kalam typed the words.

Fix:

  1. Prefixes must be at the start of the utterance (search the archives is ordinary dictation; search for archives is a voice action).
  2. Press enter is off by default — enable it under Settings → General → Voice actions. Until then the words stay in the typed text.
  3. Full table: Voice actions.

Enter fired in the wrong app​

Problem: After dictation, Return submitted a different window.

Fix:

  1. Kalam only sends Return after a successful inject into the saved target. If you saw a clipboard-fallback pill, Enter was not sent — paste manually.
  2. Keep the target field focused; do not switch apps mid-dictation if you rely on press-enter.
  3. Disable Press Enter in Settings if you do not want Return at all.

Poor accuracy​

Problem: Wrong words, missing terms, or messy punctuation.

Fix:

  1. Prefer a cloud or Kalam Cloud engine for hard accents/noise; use Local only when you need privacy/offline.
  2. Add proper nouns to the Dictionary.
  3. Enable the audio filter (Light preset) under voice/audio settings.
  4. For polished prose, turn on Improve with AI with clear writing instructions.
  5. Speak closer to the mic; reduce fan/keyboard noise.

Dictation cuts off or misses the end​

Problem: Recording stops early or trails off.

Fix:

  1. Keep holding until you finish (hold mode) or press toggle again only when done.
  2. Raise minimum hold only for accidental starts — cutting off mid-sentence is usually release-too-soon or VAD/noise.
  3. Enable/adjust the audio filter; test the mic.
  4. On slow local engines, wait for Processing to finish — do not mash Cancel.

Offline / local engine errors​

Problem: No network, or sensitive-app error about local engines.

Fix:

  1. Download a local engine (SenseVoice Small, Whisper Base, Parakeet, or Moonshine) under Settings → AI & Models → Local engines — see Local models.
  2. Set the mode's voice provider to Local.
  3. For sensitive apps, a local engine is required — cloud will not be used as a fallback.

App won't launch or crashes​

Problem: Startup crash or immediate quit.

Fix:

  1. Confirm a supported OS build from the download page.
  2. Update via Settings → About if the app opens briefly; otherwise reinstall the latest package.
  3. Export logs if you can open Settings → Advanced → Logging, then reset only as a last resort (erases local data).
  4. Attach version, OS, and log exports to a GitHub issue.
Clipboard fallback is not a failure forever

Many apps eventually accept injection after focus or permission fixes. Until then, paste is the safe path so you never lose the transcript.