The QuillMic User Manual.

QuillMic is a menu-bar dictation app for macOS. You press a hotkey, speak, and your words appear in whatever app is focused. This manual covers everything in the Mac App Store release of QuillMic so you can configure the app end-to-end without guessing.

Quick start (Simple Setup)

The fastest path through QuillMic is Simple Setup: three picks and the app configures every model for you.

What "Simple" gives you

When QuillMic launches for the first time on the Mac App Store you land on the Simple pane (Settings → Simple Setup). It surfaces three choices:

• Where should QuillMic process your speech? — On Mac (private, offline) or Cloud (best quality, needs an OpenAI API key).
• Quality — Light / Balanced / Best. Each tier is a recommendation; QuillMic automatically downgrades on small Macs and warns you when it does.
• Polish style — Conservative defaults / Light touch / Aggressive cleanup / Off. Picks which categories of corrections the AI polisher is allowed to apply.

Below the pickers a Resolved setup card shows the four roles QuillMic will configure (Speech recognition, Polish, Voice output, Nika assistant) plus any warnings or missing downloads. Pressing Apply writes the choices into the granular config that the existing providers use.

Out-of-the-box behaviour

A fresh App Store install lands at On Mac + Light with the Conservative defaults polish preset. That combination ships entirely inside the app:

• Speech recognition uses the bundled Whisper base.en model (~145 MB, English only). No download or network is required for the first dictation.
• Voice output uses the macOS system voice (free, included).
• The local AI polisher is off so first-launch users do not see "install a local model" warnings.
• Nika is disabled until the user adds an API key.

You can press the dictation hotkey within seconds of finishing onboarding and it will work offline.

What each Quality tier means

If you pick Best on a smaller Mac, Simple silently downgrades to Balanced (or Balanced → Light) and surfaces a one-line warning so you know what happened.

When to switch to Advanced

Flip the Setup mode toggle on the Simple pane to Advanced and the sidebar expands to expose every granular setting (Dictation, Polish, Nika, Models, Memory, Usage, Providers, Insertion, Language & Automation, Diagnostics, Advanced). Any pane Simple wrote to gets a banner at the top:

• "Speech recognition is managed by Simple Setup. Editing here switches this section to manual control."
• After you edit something on that pane: "Speech recognition was set by you on YYYY-MM-DD. Simple Apply will leave it alone." with a Hand back to Simple button that clears the manual stamp.

This means Simple Apply will never silently overwrite a tweak you made on an Advanced pane. The trade-off is that fields you took over no longer move with future Quality changes until you hand them back.

The Simple pane also stays reachable while you are in Advanced — the trimmed sidebar shows the Advanced disclosure and the disclosure shows Simple Setup in turn, so you can flip back without losing your place.

Switching between Simple and Cloud later

Adding an API key in Settings → Providers → OpenAI while you are in Simple mode is enough to make Cloud reachable on the next Apply. Without a key, picking Cloud surfaces a warning ("Cloud quality needs an OpenAI API key. Add one in Providers → OpenAI to enable Cloud.") and Simple falls back to On Mac + Light so you do not end up with a non-functional setup.

What QuillMic does

QuillMic listens to your microphone, transcribes what you said, and inserts the result into the app you were already using. It runs as a menu-bar item with no Dock icon. You stay in flow — you never switch to QuillMic to dictate, you press a hotkey from inside Slack, Mail, Notes, your editor, your browser, etc., and the dictated text lands in the focused field.

A second hotkey opens Nika, an in-app voice assistant who can rewrite a selection, run a few built-in commands (open settings, control Apple Music, unload local models), and answer short questions. Nika replies in text and optionally speaks the reply through the system voice or a local neural voice.

Everything that needs to work offline does. Speech recognition can run entirely on-device using one of three local engines. The text-to-speech replies can also run on-device. Cloud features exist for users who want higher accuracy or assistant intelligence, but they are off by default and clearly labelled when on.

First launch and permissions

The first time you open QuillMic the app walks you through a four-step onboarding flow:

1. Welcome. A short summary of what QuillMic does and where the menu-bar icon lives.
2. Permissions. QuillMic needs two macOS permissions to work:
   • Microphone access. Required. The Continue button stays disabled until you grant it.
   • Accessibility access. Strongly recommended. Without it, QuillMic can still type into focused fields via the system pasteboard, but the more reliable in-place insertion path is unavailable, and the menu-bar popover will show a permanent warning banner.
3. Hotkey overview. Shows the default chords for the three actions (dictate, ask Nika, speak last reply). You can change them later in Settings → Dictation.
4. Start dictating. Confirms onboarding is complete. You can press the dictation hotkey from anywhere on macOS.

If you skip the Accessibility prompt and decide later, open Settings → Diagnostics. The permission status is shown there with a "Open System Settings…" button. The menu-bar popover also surfaces a banner whenever any permission is missing — the app is not silent about it.

If you ever revoke microphone permission later, the next dictation attempt will fail with a clear error explaining how to re-enable it.

The hotkeys

Three global hotkeys drive everything. Defaults:

You change any of them in Settings → Dictation → Hotkeys. Each row exposes a recorder; click it, press the new chord, and it saves immediately.

The dictation hotkey is a toggle. First press starts recording, second press stops. While recording, the menu-bar icon changes shape and a small floating overlay appears near the menu bar showing the live state (idle, listening, transcribing, inserting). You can dismiss the overlay by pressing the same hotkey again.

If you press the dictation hotkey while QuillMic is in the background, you'll hear a short Pop sound by default — that's the start cue, an audible confirmation that the engine is now capturing audio. You can turn it off in Settings → Advanced → Audio cues.

How dictation works (the audio pipeline)

When you press the dictation hotkey, QuillMic runs a fixed pipeline:

microphone capture
    ↓ AVAudioEngine, 16 kHz mono float
audio segmentation
    ↓ endpointing detects speech vs. silence
speech recognition (the "ASR provider")
    ↓ produces raw text
deterministic text cleanup
    ↓ removes filler words, fixes spacing, collapses repeats,
      repairs common homophones, strips dangling periods
optional local LLM polish
    ↓ runs only if a local LLM is installed and the
      "Polish with on-device LLM" toggle is on
optional cloud polish
    ↓ runs only if "Allow remote transcript" is on AND the
      cloud polish toggle is on
text insertion
    ↓ pastes/types into the focused app

Two important properties of this pipeline:

• Each polishing stage is optional. The deterministic stage always runs and is safe — it does mechanical fixes like collapsing "the the" or removing a stray period after "of". Local LLM polish improves grammar but requires a downloaded model. Cloud polish requires a remote API key and explicit user opt-in.
• Each stage rejects bad output. Polishers that introduce suspicious punctuation, repeat phrases, or make the output much longer than the input are dropped — the previous stage's output is used instead. You will not get a polished sentence that lost half of what you said.

You can turn off each polish stage independently in Settings → Dictation. The deterministic stage runs unconditionally because it is fast and almost never harmful.

Choosing a speech recognizer

QuillMic ships with three on-device recognizers and two cloud recognizers. Pick whichever balances accuracy, speed, and privacy for your situation.

On-device options

Cloud options

How to pick

Start with FluidAudio Parakeet if you mostly dictate plain English at a conversational pace. It feels closest to native iOS dictation.

Switch to WhisperKit large-v3-turbo if you dictate a lot of technical vocabulary, mixed languages, or you need higher accuracy on rare words and proper nouns. Pick the variant that fits your free RAM:

• 8 GB Mac → tiny.en or base
• 16 GB Mac → small or medium
• 24 GB+ Mac → large-v3-turbo

Switch to GGML Metal Whisper large-v3-turbo Q5_0 / Q8_0 if you specifically want the fastest large-Whisper-quality on Apple Silicon. The Q5_0 quantization is slightly less accurate than Q8_0 but uses less memory; the difference is small in practice.

Pick OpenAI Whisper-1 only if you've decided that the accuracy gain is worth (a) per-minute API cost, (b) sending audio to OpenAI, and (c) being unable to dictate offline. The cloud recognizers are off until you turn on Settings → Privacy → Allow remote transcript and add an API key in Settings → Providers.

Where to switch

• Settings → Dictation → Speech recognizer picks the active recognizer.
• Settings → Models is where you download / install / unload local models. You can also kick a download from the recognizer picker by selecting a model that isn't installed yet — QuillMic prompts you.

Streaming chunked transcription

WhisperKit and GGML Metal Whisper can transcribe in streaming chunks — the recognizer starts producing text while you're still talking. Turn it on with Settings → Dictation → Streaming chunked transcription. It's off by default because it can occasionally emit a wrong word that the full-utterance pass would have corrected. Turn it on if you prefer faster preview text and don't mind the rare correction.

Choosing a text-to-speech voice

QuillMic uses TTS only when Nika speaks a reply — never to read your dictation back. Two options:

Kokoro is the higher-quality option. The voices sound natural and there are several to choose from. macOS System Voice is faster on first run because it doesn't need a model download.

Set the provider in Settings → Nika → Text-to-speech. If Kokoro is selected, a second row appears letting you pick the specific Kokoro voice. Each row has a Preview button that speaks a short sample so you can audition the voice before committing.

The first time Kokoro is invoked it downloads the model and embedding files (~900 MB). Subsequent launches are instant.

Nika — the voice assistant

Nika is the voice assistant. Press the assistant hotkey, speak a request, and Nika answers in text and optionally speaks the answer aloud.

What Nika can do

• Answer short questions — a single LLM round-trip, no tool calls, no follow-up
• Rewrite a selection — if you have text selected and the privacy toggle is on, Nika can transform it
• Run built-in commands:
  • open settings — opens the QuillMic settings window
  • unload models — frees local model memory
  • show model resources — opens the Models pane
  • music play / music pause / music toggle / music next / music previous — controls Apple Music
• Run user-defined HTTP actions — see Customization

Choosing the routing backend

Nika needs an LLM. Two options in the Mac App Store release:

Set the backend in Settings → Nika → Assistant routing. When OpenRouter is selected, an Assistant model picker appears below it; same for OpenAI.

Nika replies are gated behind Settings → Privacy → Allow remote transcript. With the toggle off, Nika refuses to run and Nika hotkey presses surface a clear error explaining what to enable. This is intentional: Nika has to send your request text to a remote server to function.

Cost cap

To prevent runaway spend, set a daily USD cap in Settings → Nika → Daily spend cap (USD). When today's recorded spend reaches that amount, Nika refuses cloud calls until the next day. 0 disables the cap. The cap reads from QuillMic's local cost ledger; it does not call the remote provider's billing API.

Apple Music control

The five music_* commands send a hardcoded AppleScript to com.apple.Music via the Apple Events scripting-targets entitlement. macOS will prompt you the first time QuillMic asks to control Music; allow it once and the rest just work.

Privacy controls

Every cloud feature is off by default. Three privacy toggles in Settings → Privacy govern what can leave your Mac:

A fourth toggle, Block insertion into secure fields, prevents QuillMic from inserting dictated text into password fields. It's on by default; leave it on.

When you turn off Allow remote transcript, QuillMic also clears the in-memory assistant conversation history so a future re-enable doesn't leak earlier turns to the cloud.

What's never persisted

• Your transcripts — past dictation history is no longer written to disk in any form. It exists only in the running session.
• Your audio — raw mic capture is held briefly in memory for the duration of one utterance and then discarded.
• Your API keys — stored in the macOS Keychain (WhenUnlockedThisDeviceOnly accessibility class). Nothing else has access while your screen is locked.

What is persisted (locally only)

• Your settings (~/Library/Preferences/com.aktica.QuillMic.plist)
• Your custom vocabulary, commands, HTTP actions, and speech substitutions
• The assistant cost ledger (~/…/Application Support/QuillMic/assistant-cost-ledger.json, mode 0600)
• Downloaded models (in your container's Application Support tree)

Insertion: how text reaches your app

QuillMic tries to insert text the cleanest way possible for the app you're in:

1. Accessibility (kAXSelectedTextAttribute) — preferred whenever the focused element exposes selected-text attribute. No clipboard touched, no synthesized keystrokes.
2. Pasteboard + Cmd-V — the fallback. QuillMic snapshots your clipboard, places the dictated text, sends Cmd-V, then restores your clipboard. Brief window where another app could read the pasteboard; controllable in Settings → Insertion.
3. Per-app override (Terminal / Warp / iTerm2 / Ghostty / Hyper / kitty / WezTerm / Alacritty / Tabby) — these terminals don't accept standard paste reliably, so QuillMic uses a hardcoded AppleScript that routes the keystrokes via System Events. The escape function is hardened against edge cases (newlines, quotes, Unicode line separators).
4. Force paste-by-typing — if you've enabled this in Settings → Insertion, QuillMic synthesizes one keystroke per character. Slowest, but works in apps that swallow Cmd-V.

If two strategies in a row fail in the same app, QuillMic auto-promotes to the next-most-reliable one for that app. You can configure the threshold in Settings → Insertion → Auto-promote fallback after.

If you don't want QuillMic to auto-paste at all, turn on Settings → Dictation → Copy transcription to clipboard. With that on, QuillMic only puts the transcript on your clipboard; you paste manually.

The Settings window, pane by pane

Open Settings from the menu bar item or with Cmd-, while QuillMic is focused.

Sidebar groups

• Setup — Overview, Dictation, Nika, Privacy
• Resources — Models, Memory, Usage
• Connect — Providers, Insertion, Language & Automation
• Support — Diagnostics, Advanced

The search box at the top searches across all panes — typing "voice" lands you on Nika and Models, typing "force paste" lands you on Insertion, typing "spend cap" lands you on Nika. Matching keyword shows under the pane name.

Pane-by-pane

Overview

A read-only dashboard of QuillMic's current state. Shows which recognizer is active, which microphone, model loadedness, recent activity. Nothing to configure here; it's a status board.

Dictation

The main dictation pane.

• Speech recognizer picker
• Streaming chunked transcription toggle
• Live transcript overlay toggle
• Endpointing presets (how aggressively QuillMic decides you've stopped speaking)
• Hotkeys: dictation, assistant, speak last
• Mute system audio while recording
• Copy transcription to clipboard
• AI transcript polishing (cloud) — gated by Privacy
• Local LLM transcript polishing — pick the local model and a polish prompt template
• Force paste-by-typing
• Block insertion into secure fields
• Speech substitutions (a quick link to the editor)

Nika

Everything Nika-related.

• Assistant routing backend (OpenRouter / OpenAI)
• Assistant model picker for the chosen backend
• Daily spend cap
• Text-to-speech provider with Preview button (when there's no per-voice picker)
• Kokoro voice with Preview button (when Kokoro is the provider)

Privacy

• Allow remote transcript
• Allow selected text
• Allow app context
• Block insertion into secure fields (mirrored here for visibility)

Models

• ASR model cards (FluidAudio, WhisperKit variants, GGML Metal Whisper variants) with download/install/unload buttons and disk/RAM footprint estimates
• Kokoro TTS model card
• Local LLM picker for transcript polishing — install and select a Qwen / Llama / equivalent model
• Resource preflight summary (disk free, RAM free)

Memory

• A live look at which models are currently loaded, what they're costing in RAM, when they were last used, and an unload-all button.

Usage

• Daily / weekly / monthly cost rollups across both cloud STT and cloud LLM
• Per-model cost breakdown
• Words-per-minute and dictation-time metrics if you've opted in

Providers

• API key fields for OpenAI and OpenRouter (stored in the keychain)
• Routing backend (mirrored from Nika)
• TTS provider (mirrored from Nika)
• Speech recognizer (mirrored from Dictation)

Insertion

• Auto-promote fallback threshold
• Per-app paste-strategy overrides
• Paste diagnostics

Language & Automation

The biggest customization surface. See Customization.

Diagnostics

• Mic / Accessibility permission status with quick "Open System Settings…" buttons
• Recent log entries
• Export logs
• A health check button

Advanced

• Launch at login
• Show / hide Dock icon
• Appearance (Light / Dark / System)
• Mini overlay vs full pill
• Audio cues — toggle the recording start tone
• Insertion auto-promote threshold (mirrored)
• Experimental: GGML Metal ASR visibility

Customization: vocabulary, commands, HTTP actions

Settings → Language & Automation is where you teach QuillMic vocabulary specific to your work and add custom voice commands.

Speech substitutions

A list of phrase pairs. When the recognizer outputs the left-hand phrase, QuillMic rewrites it to the right-hand phrase before insertion. Example:

Each rule has a scope (apply globally, only inside specific apps, or only outside specific apps), a match kind (exact / word boundary / regex), and a learned-rule cap. Learned rules accrue automatically when you correct the same word twice in a row.

Assistant vocabulary

Tells Nika who she is and which alternate names you might use. The catalog defines:

• The assistant's canonical name (default "Nika") and aliases ("Nikka", "Lika", "Hey Nika")
• Wake-phrase preambles ("hey", "ok", "yo")
• Punctuation patterns Nika should treat as a wake phrase even when the recognizer drops them

This is what makes "hey Nika rewrite this" work without you having to memorize a precise wording.

Assistant command catalog

Each entry maps a command_type (open_settings, music_play, …) to a confirmation policy and a linked automation action. Built-in commands are pre-configured; you generally don't need to touch them. You can add custom command types and link them to your own HTTP actions.

Local automation actions

The catalog of things Nika can actually execute. In the Mac App Store release the available kinds are:

• Built-in — the ones shipped with the app (open settings, Apple Music control, unload models, show model resources)
• HTTP request — any local-network or HTTPS webhook

Shell, SSH, AppleScript, and Shortcuts kinds are not available in the Mac App Store release. They exist in the Developer ID build because they need filesystem and process privileges that App Sandbox does not grant. If you need to run shell scripts, send SSH commands, or fire arbitrary AppleScript from voice, use the Developer ID build of QuillMic. The MAS build still ships the Apple Music control commands because they go through a tightly allowlisted scripting-target.

HTTP automation actions in detail

Each HTTP action carries:

• A displayName and stable id
• A method (GET / POST / PUT / PATCH / DELETE)
• A URL (must be https:// if any header or body references a {{secret:…}} placeholder)
• Headers (name + value; values can include {{secret:my_token}} placeholders that resolve from the Keychain)
• Optional body (also supports {{secret:…}} placeholders)
• A list of allowed hosts (when empty, only RFC 1918 / loopback / .local hosts are allowed)
• A confirmation policy (always, never, risky)
• A timeout

The HTTP path is hardened: hosts are normalized for IDN comparison, redirects are followed without forwarding Authorization / Cookie / X-API-Key / OpenAI-Organization headers, and https:// → http:// downgrades are refused. 429 / 503 responses are retried with exponential backoff that honours Retry-After.

Use HTTP actions for things like: ping a Home Assistant webhook, hit a local Hubitat scene, call your own Lambda. Anything that's a single HTTPS request.

Managing models

Every speech, voice, and language model lives in Settings → Models.

Each model card shows:

• Status — idle, downloading (progress %), installed, loaded, blocked-by-preflight, failed
• Disk footprint — exact MB
• Estimated RAM at load — used by the resource preflight to decide whether it's safe to load
• Action buttons — Download, Cancel, Install, Unload, Delete

Resource preflight

Before loading any model, QuillMic runs a resource preflight: is there enough free RAM, enough free disk, enough thermal headroom? If not, the load is blocked and the card explains why. You can override only by closing other apps or unloading other models from the Memory pane.

Disk locations (sandboxed)

Inside the Mac App Store sandbox container at:

~/Library/Containers/com.aktica.QuillMic/Data/Library/Application Support/QuillMic/

QuillMic stores:

• Model downloads (FluidAudio, WhisperKit, GGML Whisper, Kokoro, MLX LLMs)
• Cost ledger
• Custom automation actions
• Loaded-model state

You don't need to touch any of this manually; the Models pane is the only supported way to modify it.

Migrating from a Developer ID install

If you previously used the Developer ID build of QuillMic and downloaded large local models, the App Store build will detect an empty container on first launch and offer a one-shot import. Click Import and select the legacy ~/Library/Application Support/QuillMic/ directory; QuillMic copies the recognized files and never asks again.

Cost control

Cloud STT and cloud LLM both bill by tokens / audio minutes. QuillMic gives you three layers of control:

1. Privacy gate. With Allow remote transcript off, no cloud call ever fires, regardless of any other setting.
2. Per-call provider selection. Cloud STT and Nika both pick their model from the Settings pickers. Smaller models cost less per call.
3. Daily spend cap. Enter a positive number in Settings → Nika → Daily spend cap (USD). Nika refuses cloud calls once today's recorded spend reaches that number. The cap is enforced from the local cost ledger, no provider-side billing API needed.

The Usage pane shows you the rolling 24-hour spend, 7-day spend, and 30-day spend.

Diagnostics and troubleshooting

Settings → Diagnostics is the first place to look when something is off. It shows:

• Microphone and Accessibility permission status with one-click jumps to System Settings
• Recent activity log (the last 250 events)
• Health check that exercises the active recognizer with one second of silence
• A button to copy / export logs

Common issues

"Nothing happens when I press the dictation hotkey"

• Verify mic permission in Diagnostics. If denied, click "Open System Settings".
• Verify the hotkey hasn't been claimed by another app — try a different chord in Settings → Dictation → Hotkeys.
• Look for a red banner in the menu-bar popover; it surfaces missing permissions.

"Text appears in the wrong app"

• The focused window changed mid-utterance. Hold the dictation hotkey or use a different chord that doesn't conflict with your IDE's keyboard shortcuts.

"Transcription is wrong on technical words"

• Add a Speech substitution for the term (Settings → Language & Automation → Speech substitutions).
• Or switch to a higher-accuracy recognizer (WhisperKit small / medium / large or GGML Metal Whisper large-v3-turbo).
• Or turn on Allow remote transcript + OpenAI Whisper-1 for one session.

"Nika says 'Open Settings, go to General, Privacy, and turn on Allow remote transcript'"

• Exactly that. Open Settings → Privacy → Allow remote transcript and turn it on. Without it, Nika can't run.

"Nika says 'Today's assistant spend ($X) reached the daily cap'"

• Raise or clear the cap in Settings → Nika → Daily spend cap, or wait until tomorrow.

"Local LLM polish made my sentence weird"

• The polisher has a safety net that rejects polished output if it expanded the sentence too much, repeated phrases, added too many punctuation marks, or split the sentence at a preposition. If your specific case slipped through, turn off Local LLM polish in Settings → Dictation and use the deterministic-only path.

"Same Kokoro voice every time"

• The Kokoro voice catalog includes some experimental voices that may fail to download from the upstream CDN. Settings → Diagnostics shows which voices loaded and which were unavailable. If a voice is in the unavailable list, pick a different one.

"Insertion fell back to clipboard pasting in Slack"

• This is expected for some Electron apps. QuillMic auto-promotes to the more reliable strategy after a few failures. You can also force this in Settings → Insertion → Auto-promote fallback after.

Reporting a bug

Settings → Diagnostics → Export logs writes a redacted JSON file you can attach to a support email. Sensitive content (transcript text, API keys, file paths) is stripped automatically.

FAQ

Do I need an internet connection? Only for cloud features (cloud STT, Nika, cloud transcript polish) and for the first download of a local model. Once a local recognizer / TTS / LLM is installed, dictation and TTS work offline.

Can I use multiple microphones? QuillMic uses your system default input device. Change it via System Settings → Sound → Input or via the system menu-bar volume control while QuillMic is running.

Does QuillMic work in the background? Yes. The hotkey is global. Whatever app you're in, the hotkey starts dictation and the result lands in the focused field of that app.

Can QuillMic transcribe a video / audio file? Not in the Mac App Store release. The dictation pipeline is real-time only.

What languages does QuillMic support? Recognizers vary:

• FluidAudio Parakeet — English, plus a small set of European languages (set in Settings → Dictation → Language)
• WhisperKit — multilingual variants exist; pick one with multilingual in the name
• GGML Metal Whisper — multilingual through the large-v3-turbo variants
• Cloud Whisper — every language Whisper-1 supports

The deterministic transcript cleanup is English-tuned. Mixed-language speech is preserved as-is in the input language; the local LLM polish step is skipped automatically when mixed scripts are detected.

Does QuillMic store my dictations? No. Dictation history is held only in memory for the current session and is discarded when the app quits.

Can I share my settings across Macs? Settings persist in UserDefaults under com.aktica.QuillMic. iCloud sync of UserDefaults is not enabled in the Mac App Store release. Custom automation actions, vocabulary, and command catalogs are file-based under Application Support; copy them across Macs manually if needed.

Where can I see my API spend? Settings → Usage shows local rollups. The provider's billing dashboard is the source of truth.

How do I uninstall QuillMic? Drag the app to the Trash. The container at ~/Library/Containers/com.aktica.QuillMic/ holds your settings and downloaded models; delete that folder to remove every trace, or leave it in place if you might reinstall later. Keychain entries are removed automatically when the container is deleted.

Last updated: covers the Mac App Store release of QuillMic.