For AI agents: plain-text version at https://keebye.com/docs/dictating.md · full index at https://keebye.com/llms.txt

Skip to documentation content
Keebye Docs

Dictating

The push-to-talk key, hold versus tap, what the pill shows, how text is inserted, and where Keebye refuses to write.

Press your push-to-talk key, speak, release. Transcription runs on the whole utterance after you release, and the text is inserted into whatever app is frontmost.

The push-to-talk key

Settings › Push-to-talk hotkey: "Hold this key to dictate; release to insert." Changes apply live.

  • Fn / Globe (Right Ctrl on Windows)
  • Left ⌘ (Left Windows key on Windows)
  • Right ⌘, the default (Right Windows key on Windows)
  • Left ⌥ (Left Alt on Windows)
  • Right ⌥ (Right Alt on Windows)

Hold or tap

  • Pressing the key starts recording immediately.
  • Release after 400 ms or more: hold-to-talk. Recording stops and the text is inserted.
  • Release before 400 ms: tap. Recording stays on. A second tap stops and inserts.
  • Esc cancels an in-progress recording. Nothing is inserted.
  • A single utterance is capped at 300 seconds (5 minutes), then it stops and inserts automatically.

The pill

The pill is a small, always-visible, click-through panel at the bottom-center of your primary screen, 96 pt above the bottom edge. On a Mac it appears on all Spaces and never takes focus.

  • Resting: a microphone glyph.
  • "Downloading speech model… NN%" while a model downloads, or "Model download failed — reopen Keebye to retry".
  • "Listening…" → "Transcribing…" → "Inserting…" during a dictation.
  • Short messages for about 2.6 seconds: "Couldn't insert: <reason>", "Text left on clipboard — paste manually", or "Dictation paused: secure input on (<App>)".

How text is inserted

Paste (fast), the default: Keebye snapshots your clipboard, writes the transcript, synthesizes ⌘V (Ctrl+V on Windows), and after 250 ms restores your previous clipboard if Keebye still owns it. On a Mac the transcript is a transient pasteboard item that clipboard managers skip; on Windows only plain text is restored. "Restore clipboard after paste" is on by default.

In Terminal.app, iTerm2, Warp, WezTerm, and kitty on a Mac, and in Windows Terminal, Command Prompt, and PowerShell on Windows, the paste is split into chunks of at most 2000 bytes with 50 ms gaps.

Typing (terminals / SSH / any layout): Keebye sends Unicode keystrokes without touching the clipboard, on a Mac in 16-character chunks, 4 ms apart. It is layout-independent and works over SSH and tmux. If typing fails, the text goes on the clipboard and the pill shows "Text left on clipboard — paste manually".

Password fields and secure input

On a Mac, if secure input is on, or the focused element is a password field, Keebye writes nothing to the clipboard and shows "Couldn't insert: Secure input is active (<App>) — dictation is blocked" or "Couldn't insert: A password field is focused — dictation is blocked". Such dictations are never saved to history. A 5-second poll also warns "Dictation paused: secure input on (<App>)" while secure input stays on.

The warm microphone

The microphone stream starts on your first dictation and then stays running for the app's lifetime, so your system's microphone-in-use indicator stays on after first use. A rolling 500 ms pre-roll is added to the start of each utterance. The first dictation of a session can still pay stream-start latency, and words spoken before that 500 ms buffer can still clip. Audio is resampled to 16 kHz mono and a device change is detected within a second.