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
  • Left ⌘
  • Right ⌘ (default)
  • Left ⌥
  • Right ⌥

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. 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 as a transient pasteboard item that clipboard managers skip, synthesizes ⌘V, and after 250 ms restores your previous clipboard if Keebye still owns the pasteboard. "Restore clipboard after paste" is on by default.

In Terminal.app, iTerm2, Warp, WezTerm, and kitty the paste is split into chunks of at most 2000 bytes with 50 ms gaps.

Typing (terminals / SSH / any layout): Keebye sends Unicode keystrokes in 16-character chunks, 4 ms apart, without touching the clipboard. 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

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 the macOS microphone 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.