Hotkey + first dictation¶

This is the five-minute walkthrough from a fresh install to your first injected transcript. If you haven't installed Quill yet, head back to the install page.

1. First launch — pick a polish model¶

The first time you open Quill you'll see a welcome screen with a polish-model picker. The "polish" pass is the optional LLM step that cleans up disfluencies, fixes punctuation, and softens the raw Whisper output into something you'd actually paste into a doc.

Pick one of:

Model	Size	When to use
Qwen3 4B Q4_K_M	~2.5 GB	Default embedded model. Best closed-alpha quality target.
None	0 GB	Skip polish entirely. Raw Whisper output gets injected verbatim.
Bring-your-own	—	Point Quill at a system or remote Ollama-compatible endpoint and model.

Quill will start downloading the verified GGUF in the background. It also downloads the Whisper STT model (ggml-base.en.bin, ~150 MB) in parallel. You'll see two progress bars on the setup screen — wait for both to hit 100%.

  ┌──────── Setup ────────────────────────────────┐
  │  Microphone permission ........... Granted  ✓ │
  │  Accessibility permission ........ Granted  ✓ │
  │  Whisper model (base.en) ......... 100%     ✓ │
  │  Embedded polish GGUF ............ 100%     ✓ │
  │                                               │
  │              [  Start dictating  ]            │
  └───────────────────────────────────────────────┘

When all four checks are green, click Start dictating.

2. Grant permissions¶

macOS¶

On the very first dictation attempt, macOS prompts you for:

Microphone — "Quill wants to use the microphone." Click OK. Without this, Quill cannot hear you.
Accessibility — "Quill would like to control this computer using accessibility features." Click Open System Settings, find Quill in the list, toggle it on. Without this, Quill still works but falls back to clipboard paste instead of writing directly into the focused field.

If you accidentally deny either prompt, open System Settings → Privacy & Security, find the relevant section (Microphone, Accessibility), and toggle Quill on. You may need to quit and relaunch Quill afterward.

Linux¶

On most distros the microphone is granted by default (PipeWire/PulseAudio doesn't prompt). Wayland compositors can't deliver global hotkeys to a normal user process; if you're on Wayland, see the troubleshooting page for the compositor-binding pattern.

3. Pick your hotkey¶

The default hotkey is F8. It's push-to-talk — hold it while you speak, release it when you're done. The daemon registers F8 globally, so it works no matter what window has focus.

To change it: open Settings in the Quill menu bar, pick a different function key (F1–F15) for "Quick capture" or "Enhanced capture." The change takes effect immediately — no restart.

  Quick capture     [ F8  ▼ ]   ← raw / fastest
  Enhanced capture  [ F9  ▼ ]   ← polish pass on

The two hotkeys exist so you can map a raw "fastest possible" capture and an enhanced "clean it up" capture to different keys. You can switch one or both to a different mode in the Settings panel.

4. The hold-talk-release cycle¶

Once you've granted permissions, the loop is:

  Press and hold F8       ┐
                          │  ← Quill is recording.
  Speak naturally.        │     The menu-bar icon turns red.
                          │     The level meter in the app pulses.
  Release F8              ┘

         ↓ (~200ms — Whisper transcription)

  raw transcript          ← Activity log shows the raw text

         ↓ (~300–800ms — local LLM polish)

  polished transcript     ← Replaces the raw line in the log

         ↓ (instant)

  text appears in your    ← Focused field gets the polished text.
  focused window             On macOS with AX permission: written
                             directly. Without it: clipboard paste.

You don't have to wait between captures. If you hold F8, release, hold again, the previous pipeline finishes in the background while the next one starts.

5. First sanity check¶

Open any text field — a Notes window, a fresh email draft, a terminal at a $ prompt. Hold F8 and say:

"This is a test of my new dictation tool, period. New sentence, capital T, the quick brown fox."

Release F8. After ~1 second you should see roughly:

This is a test of my new dictation tool. The quick brown fox.

If you see the raw Whisper output instead (this is a test of my new dictation tool period new sentence capital t the quick brown fox), the polish pass didn't run — check the embedded model download state on the Settings page.

If nothing appears at all, check the troubleshooting page. The most common issue is the Accessibility permission denied on macOS — Quill will be transcribing fine, but won't be able to inject the text.

What's next¶

You're done. From here it's just: hold, talk, release, repeat. The troubleshooting page lists the failure modes we've seen so far, and the privacy promise explains exactly what stays on your machine and what doesn't.