Skip to main content
Kalam Documentation

The dictation pipeline

Every dictation follows one predictable path from key hold to inserted text. Speech engines, screen context, and Improve with AI are configured per dictation profile—on Plain dictation or your custom profiles—not through a single app-wide toggle.

Profile editor showing Hear your voice, Read your surroundings, and Improve the text. (Click to zoom)

Stages inside a dictation profile​

Inside Dictation, each profile shows three pipeline stages under What happens when you dictate:

StageLabelWhen it runs
1. SpeechHear your voiceAlways—runs the On-device or Cloud engine selected for that profile (or inherited from Models).
2. ContextRead your surroundingsPro / Pro trial when Read surroundings is enabled and the active window is not on your Sensitive apps list.
3. PolishImprove the textPro / Pro trial when Improve with AI is enabled (or when context was captured), provided a language model is configured.

Step by step​

  1. Record: Press and hold Hold to Dictate (or press Toggle Dictation). Holds shorter than 300 ms cancel cleanly with no transcription or insert.
  2. Transcribe: Recorded audio goes only to the speech engine configured on the active profile (On-device via Sherpa-ONNX / Whisper.cpp, or Cloud via your own API key).
  3. Check for Commands: If you triggered Ask Kalam or spoke a Command prefix or selection action (such as "New note…" or "Fix grammar"), Kalam skips typing into your app and runs that command instead.
  4. Capture context (Pro): When Read surroundings is enabled—and the active window is not sensitive—Kalam attaches permitted details (app name, window title, selected text, clipboard, date/time) strictly to the Improve step.
  5. AI polish (Pro): Improve with AI cleans filler words, fixes punctuation, and formats the text according to How you want it written. If the model is unavailable or Sense → Polish check flags meaning drift, Kalam falls back cleanly to your spoken transcript.
  6. Local formatting (when Improve did not run): If AI polish was off or skipped (such as in Plain dictation), Kalam applies your Snippets, Dictionary replacements, and inline Voice commands (period, new line, scratch that).
  7. Insert at cursor: On macOS, Kalam tries Accessibility typing first and falls back to Paste; on Windows and Linux, Kalam defaults to Paste. Inside Sensitive apps, Kalam forces direct keystrokes so private text never enters your clipboard.

What stays on your computer vs what can leave​

StepRuns locallyLeaves only if configured
Recording & audio cleanupAlways on your computer—
Speech recognitionOn-device models (Sherpa-ONNX, Whisper.cpp)Your chosen Cloud speech provider
Context captureAlways read locallySent only with an Improve / Commands request
AI polishLocal / custom compatible endpointsYour chosen Cloud language provider
Snippets, Dictionary, Voice commandsAlways on your computer—
Text insertionAlways on your computer—