Frequently asked questions.

No. Speech recognition runs entirely on-device using Apple's Neural Engine — Parleq bundles the Parakeet TDT v3 model (~150 MB, downloaded once on first launch from Hugging Face) and calls it in-process. There are no listening sockets on the default ASR path; the audio buffer is a Swift value handed directly to the speech model inside the same process, never across a process or network boundary. The model itself never makes outbound network calls; audio bytes never appear in any cloud log, S3 bucket, or vendor analytics pipeline. They live in process memory only — the most recent dictation's audio is held so you can re-run it (hotkey + R), and everything is cleared when you quit Parleq; audio is never written to disk. Reviewers can verify the no-listening-sockets claim with lsof -i -nP -a -p $(pgrep -n ParleqApp) on a running Parleq.

When the On-device cleanup option is used, the cleanup provider receives nothing — all processing happens in-process on your Mac with no network call. For cloud providers, the cleanup provider receives only the transcript — the same words the on-device speech model emitted, plus any custom-dictionary hints you've configured. It never receives audio. On your Mac, Parleq writes four files under ~/.parleq/: config.json (your settings), usage.jsonl (one line per cleanup call — timestamp, model, token counts, latency — metadata only, no transcript text), app.log (a diagnostic log that records lengths and timing, e.g. "post-utterance 87 ms, 142 chars / 28 words", but never the words themselves), and metrics.jsonl (one text-free record per dictation — duration, latencies, token counts, ref-attached/cleanup-failed flags — so the Stats dashboard spans sessions; no transcript text, kept to the last 30 days). Cleaned text is held in memory during the overlay session and kept in an in-memory list that backs the Parleq window's Recent Dictations section — wiped on app quit, never written to disk.

Depends on the provider you pick. Direct Google AI Studio on the free tier — yes, by default; paid tier is excluded. AWS Bedrock — no; prompts and completions stay inside your AWS account boundary, per Amazon's published policy. Google Vertex AI — no; governed by your GCP organization's enterprise terms. Azure OpenAI — no; Microsoft's documented data privacy commitments exclude foundation-model training. If training opt-out matters for your work, pick Vertex, Bedrock, or Azure. The relevant policy link is in each provider's docs page.

In the macOS Keychain — KeychainStore writes them to the user's login keychain via SecItem APIs. Never in ~/.parleq/config.json or any other plaintext file on disk. This applies to every provider's secrets: Gemini API key, OpenAI API key, Bedrock API key, AWS static IAM credentials, Vertex service-account JSON (the whole JSON is one Keychain item), and the Azure resource API key — plus, for enterprise OIDC sign-in, a refresh token and a sign-in identity snapshot (never a cloud credential).

Only if you opt in — the feature is off by default. When you enable Settings → Privacy & Features → Learn from my corrections, Parleq keeps short correction snippets in memory only — never written to disk, cleared when you quit Parleq. Occasionally — off the dictation path, so it never adds latency — it sends those in-memory snippets to the same cleanup model you already have configured and asks it to suggest custom-dictionary improvements. No new service is introduced and no new network destination is used; the request goes to whatever LLM endpoint you already authorized. High-confidence spelling fixes auto-apply to your dictionary (revertibly); lower-confidence suggestions appear in a Learned section for you to accept or dismiss. The only thing that persists on disk is the learned dictionary terms — written to your config file just like hand-added terms, not as raw dictation snippets. You can cap the in-session ring by entry count or retention window in Settings, or clear it entirely. IT administrators can pin the feature off fleet-wide via the learnFromCorrectionsEnabled MDM key, or disable the ring entirely with learnedCorrectionsMaxEntries: 0 or learnedCorrectionsRetentionHours: 0.

For personal use with no compliance constraints: Gemini direct or OpenAI direct — both offer five-minute setup using just an API key, no infrastructure to think about. If you want cleanup to run entirely on your Mac with no internet needed and no per-call cost, you have two on-device choices: Lightweight (built on Concord — a fast deterministic corrector with nothing to download and no RAM floor, though it can't freely rewrite), or the On-device LLM (a choice of Gemma 4 E4B or the lighter Qwen3-4B, both quantized — full rewriting; a one-time ~2.4–4 GB download depending on model, 8 GB+ RAM). For work where you have an existing cloud relationship: pick the one your team already uses (Bedrock for AWS, Vertex for GCP, Azure for Microsoft). All options produce comparable cleanup quality on the short text Parleq generates. The provider choice mostly comes down to where you want the bill to land, whose contract you're operating under, and whether the transcript should cross a network boundary at all.

Yes. Pick OpenAI in the provider list — it calls api.openai.com using an API key you paste from platform.openai.com. Available models include GPT-4o, GPT-4.1, GPT-4o Mini, and the o1 / o3 / o4-mini reasoning series. If your organization needs enterprise data-privacy commitments or Azure's regional controls, use Azure OpenAI instead — the same models run on Microsoft's infrastructure under your org's contract and audit logging.

Yes. Open Settings → Cleanup → Provider, pick the one you want, and click Finish & Restart when prompted (the provider is read once at app launch, so a relaunch is needed for the switch to take effect). Every provider's credentials are stored independently, so switching back later doesn't lose anything you'd configured.

Yes — two ways. For a zero-download, no-RAM-floor option, pick Lightweight in Settings → Cleanup → Provider — a deterministic on-device corrector (numbers, questions, your dictionary, voiceprints) built on Concord, ready immediately, though it can't freely rewrite text. For full on-device cleanup, select On-device in the Setup Wizard or Settings, then pick a model: Gemma 4 E4B (default, best quality) or the lighter Qwen3-4B. Parleq downloads the chosen model — quantized, ~4 GB for Gemma 4 or ~2.4 GB for Qwen3-4B — from Hugging Face once; after that, cleanup runs entirely in-process on your Mac with no network boundary and no per-call cost. The model uses about 6 GB of memory while it's running (about 4 GB for Qwen3-4B), and Parleq frees that memory after a few minutes of inactivity. Parleq also caps the pool of reusable GPU buffers the model keeps around, so the footprint you see in Activity Monitor stays close to the model's own size instead of climbing higher after a longer cleanup. Because of that footprint, Gemma 4 requires a Mac with at least 12 GB of RAM and Qwen3-4B at least 8 GB — on Macs below a model's floor, it appears in the picker but can't be selected. The model is stored at ~/Library/Application Support/Parleq/models/ and can be removed from Settings to reclaim the disk space. If you want no cleanup at all rather than local cleanup, choose None — paste raw ASR instead, which pastes the on-device speech model's output without any cleanup pass.

Yes. Each provider's Model picker has a Custom (enter below) option that reveals a free-form text field — paste any model identifier the provider supports. (For Azure, this is replaced by a Model family picker since Azure routes by deployment name; pick Standard or Reasoning to match the underlying model your deployment serves.) Custom IDs are saved alongside everything else; if the provider rejects the model, the cleanup overlay surfaces the error and dictation falls back to raw ASR.

Apple Silicon (M1 / M2 / M3 / M4) running macOS 14 (Sonoma) or later, required. The shipping binary is built arm64-only — Intel Macs can mount the DMG and drag Parleq.app into Applications, but launching it will fail with macOS's "Bad CPU type" error since Rosetta only translates Intel→ARM, not the other way. The requirement is twofold: on-device speech recognition runs on the Apple Neural Engine (which Intel Macs lack), and the optional on-device cleanup tier runs on Apple MLX, which only targets Apple Silicon GPUs. On a low-memory Apple Silicon Mac (8 GB) speech recognition is fine, but on-device cleanup is below its 12 GB minimum — use a cloud cleanup provider or skip cleanup. An Intel build was evaluated and isn't planned: even past the launch blocker, on-device speech would fall back to CoreML on CPU/GPU with no Neural Engine (an estimated 5–20× slower, undercutting the low-latency design) and the MLX cleanup tier can't run there at all. The full reasoning and capability matrix are in issue #1.

Yes — and in two places. The menu-bar Parleq icon has a Microphone submenu listing System Default plus every connected input device, with a checkmark on the active one — useful for switching mid-session (laptop mic at home, USB mic at the desk, AirPods on the go). The same picker is in Settings → Audio for set-and-forget configuration. Selections are persisted by the device's Core Audio UID, so unplugging and reconnecting a USB mic later restores it. If your saved device isn't currently connected, Parleq falls back to System Default and surfaces a "Selected microphone disconnected" hint until the device reconnects.

Yes, but by default Parleq forces input to the built-in mic when the system default is Bluetooth — otherwise BT headphones drop from A2DP (high-quality stereo output) to HFP/SCO (low-quality bidirectional) the moment recording starts, and your music pauses or sounds awful for the duration of the dictation. Settings → Audio → "Keep music playing while dictating" controls this; default is on. Disable it if you actually want to record from your BT headset's mic and don't mind the audio-quality drop.

About 30–60 seconds on Apple Silicon. Parleq downloads the Parakeet TDT v3 speech model (~150 MB) from Hugging Face on first launch, then warms it up. The menu-bar icon switches from a download glyph to a microphone when ready. Subsequent launches are under 5 seconds.

Microphone is for capturing audio (obviously). Accessibility is for two things: (1) reading which app currently has keyboard focus when you press the hotkey, so the cleaned text pastes back into that app even if your focus drifts mid-dictation; (2) synthesizing the paste keystrokes via CGEventTap — macOS's standard mechanism for system-wide hotkey + paste apps. Parleq doesn't use Accessibility for any kind of screen reading, keystroke logging, or window inspection beyond identifying the originally-focused app's bundle ID. Screen Recording is a third permission, requested lazily — only when you use Reference Windows for the first time, not at startup.

Hold your dictation hotkey and tap P to summon the Parleq window from anywhere — or pick Show Parleq… from the menu-bar icon. (The hold-then-P gesture has a 200 ms threshold, so a quick Option-P still types π; only a deliberate hotkey hold opens the window.) The window has one sidebar with four sections: Recent Dictations (your cleaned-text history, with Copy / Paste-here / delete per entry), Stats (dictation counts, speaking time, ASR/LLM latencies, token usage + cost on a rolling window), Settings (every preference pane, expandable in the sidebar), and About. On a narrow window the sidebar auto-hides to give the content room; a toggle in the title bar brings it back. Cmd-W closes the window — Parleq keeps running in the menu bar.

Beyond hold-to-dictate, a few one-key gestures speed things up. Double-tap-and-hold the hotkey for quick dictation that pastes straight away with no review step, or double-tap-and-release to record hands-free for a longer dictation — tap once more to stop. While holding the hotkey — or while reviewing a result — tap Space to pick a window as context, C to attach the window you're already looking at, or P to cancel and bring up the Parleq window. Hold the hotkey and tap R to recover (re-run) your last dictation if you lost it — also available as "Recover last dictation" in the menu bar. While reviewing, press Enter to accept and paste, E to edit the text yourself before accepting, V to send the text to a different window, or hold the hotkey again to refine it by voice ("make it shorter"). And ? (or /) opens an in-app card listing every gesture — the same reference lives on the details page.

Yes — Settings → Hotkey → Binding. Default is right-Option (⌥), chosen because it's globally available, doesn't conflict with any standard macOS shortcut, and is comfortable to hold. Other options include left-Option, either Control, either Command, either Shift, or Fn. Pick one that doesn't fight a shortcut you already use. You can also choose what the double-tap-and-release gesture does — hands-free recording (the default), quick dictation, a plain dictation with review, or nothing — under Settings → Hotkey.

Yes — Settings → Custom Dictionary. Add terms Parleq commonly mis-transcribes (people's names, project codenames, technical jargon), with optional aliases for variant spellings the speech model often emits (e.g. "Parlay" / "Parlez" → canonical "Parleq") and an optional context blurb that helps the LLM judge whether the surrounding speech topic actually matches. Each entry has a per-term toggle for STT-side biasing — leave on for terms with distinctive phonetics, turn off when a term's sounds overlap a common word and trigger false positives.

Yes — it's the voice enrollment feature, and it's opt-in, per term. Some names sound almost identical to a common word ("Keavi" vs. the fruit "kiwi", "Claude" vs. "clawed"), and spelling alone can't separate them. From a term's entry in Settings → Custom Dictionary, you can run a short read-aloud wizard: speak a few carrier sentences, and Parleq learns the sound of *you* saying that word. On later dictations it disambiguates by sound — recovering the name you meant, and leaving the everyday word alone when that's what you actually said. It runs entirely on-device with no LLM and no cloud. What's stored is a mathematical voiceprint (an embedding) — a fingerprint of the sound, not a transcript of your words. Voiceprints are biometric data, so they're kept encrypted at rest (AES-GCM) under a Keychain key that is device-only and never synced to iCloud, and you can delete a single term's voiceprint or all of them at any time. By default, Parleq also keeps those short enrollment clips — encrypted on your Mac under that same device-only key — only so your voiceprint can be re-derived after an on-device model update; you can turn clip storage off at any time, which erases them. Either way, nothing about enrollment leaves your Mac.

Yes — that's the Reference Windows feature. The fastest path is the Space gesture: while holding your dictation hotkey, tap Space — audio pauses, the window picker opens, you pick a window (arrow keys + Enter, or click), and the overlay enters a "latched" state. Hold the hotkey again to keep dictating with the reference attached, or just tap-and-release to send. Tap Space mid-dictation again to attach a second, third, … reference into the same composition. If you'd rather use the mouse, click the "+" button on the overlay to open the picker directly. Other attach paths: file picker, clipboard, drag-drop. The captured text (or image, if you're using a vision-capable model) is included in the cleanup prompt so the LLM can use it as context when processing your speech. Captures stay in memory only — released on accept or cancel, never written to disk.

Not through Settings today. The cleanup prompt is curated to produce light edits — punctuation, capitalization, light filler removal, common ASR misrecognitions — without rewriting your voice. If you want a heavier-handed pass, use the refinement loop instead: hold the hotkey again while the overlay is open and say what you want different ("make it more professional", "shorter, end with a question mark"). The cleanup prompt itself lives in SystemPrompts.swift if you want to fork.

Yes — Settings → Audio. Parleq plays a short cue when capture starts and another when it ends; you can set each one independently to any macOS system sound (Tink, Bottle, Frog, Pop, …) or turn either off. Both are governed by the master Acoustic feedback toggle, so one switch silences everything. Defaults are Tink (start) and Bottle (end).

Yes, both. If you correct yourself mid-sentence — "scratch that", "no wait", "I mean Rob" — the cleanup pass drops the retracted words and keeps only your final intent (conservatively: if it can't tell whether you're correcting or genuinely listing both, it leaves your words alone). And if you spell a word out loud — "M I R A" — it assembles the letters into the single word and capitalizes it correctly (a name stays a name, an acronym like URL stays all-caps) — the easiest way to fix a name the speech model keeps mishearing.

Parleq itself is free and open-source under Apache-2.0. The cleanup pass costs whatever your chosen provider charges per token. Cleanup prompts are short (a few hundred input tokens, a few hundred output tokens), so a typical day of personal dictation runs to single-digit cents.^† Direct Gemini has a free tier^† you can sign up for without a credit card; whether your usage stays inside the current per-minute and per-day quotas depends on how heavily you dictate. Bedrock / Vertex / Azure bill per token to your existing cloud account at that provider's published rates. Settings → Usage shows running totals.

Probably yes, but it depends on your company's policies. Parleq has no Parleq-side backend — calls flow through whichever cloud account you point it at, governed by that cloud's contract. If your organization has already approved AWS Bedrock, GCP Vertex, or Azure OpenAI for other work, Parleq fits inside that existing approval; there's no separate vendor to onboard. If your work hasn't approved any of those, the question shifts to whether you can sanction direct calls to Google AI Studio (consumer terms — usually not appropriate for sensitive work), which is the only configuration that doesn't lean on your org's existing cloud relationships.

Yes. Parleq reads macOS Managed Configuration at startup, so your IT team can push a .mobileconfig profile via any MDM (Jamf, Kandji, Mosyle, Intune, and others) that pins the LLM provider, restricts the allowed model list, and disables optional features — all enforced at runtime so users cannot change them through Settings. If your organization has already approved AWS Bedrock, Google Vertex AI, or Azure OpenAI for other work, Parleq fits inside that existing approval without a separate vendor review or data-flow diagram. For the full deployment walkthrough, see the Admin Guide.

The managed configuration schema has 32 supported keys. The main categories: Provider and model — pin the cleanup provider (e.g. cleanupProvider: bedrock), restrict the allowed model list, and disable the custom-model entry field so users cannot route around the list. Auth mode — force federated identity (AWS SSO, Entra ID, gcloud ADC) and disable all static API-key paths globally; previously-stored Keychain credentials are not deleted but are not used while the policy is active. Feature toggles — disable image reference capture, file reference, or other optional features your security review requires off. Updates — disable automatic update checks, or redirect the Sparkle feed URL to an internal mirror your security team vets before distribution. Destination pins — pin the cloud project, region, resource, and ASR endpoint so an allowed provider can't be re-targeted at a personal tenant. Transcript-history retention — bound the in-memory Recent Dictations history by entry count or age, or set it to 0 to disable dictation history (and the text-free Stats metrics) entirely. Logging mode — assert the lengthOnly policy for auditors. All keys are documented in the Managed Configuration reference.

Starting with v0.10.0, Parleq checks for new releases automatically using Sparkle — the open-source auto-update framework most third-party Mac apps use. On launch and once every 24 hours afterwards, Parleq checks parleq.app/appcast.xml for a newer release and prompts you to install if one's available. You can also trigger a check manually from Settings → Updates → Check for Updates Now or the menu bar's Check for Updates… item. To opt out of automatic checks, toggle off Settings → Updates → Automatically check for updates; the manual check stays available either way.

Yes. Every Parleq release is signed with an Ed25519 cryptographic key. The matching public key ships inside every Parleq build, and Sparkle on your Mac verifies each downloaded .dmg's signature against that public key before installing — a mismatch refuses the update and surfaces a clear error. The private half lives only in the maintainer's macOS Keychain plus a password-manager backup; it never enters the public repository or any built artifact. So an attacker who compromised parleq.app, intercepted your network connection, or swapped out the .dmg on GitHub couldn't push an arbitrary binary to your installed Parleq — they'd need the private key, which doesn't leave the maintainer's machine. Full posture in SECURITY_REVIEW.md §7a.

An HTTP GET to parleq.app/appcast.xml. Sparkle's User-Agent header on that request carries the current Parleq version and your macOS version (e.g. "Parleq/0.10.0 macOS/14.5") so the server could in principle see which version + OS combinations are checking in. No user identifier, no install ID, no telemetry payload, no transcript content (Parleq has no backend anyway). The appcast itself is a static XML file — there's no per-user response, no logging tied to your install. If you accept an update prompt, a second GET fetches the new .dmg from github.com/parleq/parleq-speech/releases/... — same posture as if you downloaded a release manually from a browser.

Because Parleq lives in /Applications, which is owned by the system rather than your user account. To install an update there, Sparkle's installer service needs a brief privilege escalation — and macOS Ventura+ treats anything that runs in the background with elevated access as a "Background Item" that requires explicit user approval via System Settings → General → Login Items & Extensions. The prompt fires once per install; after you toggle the switch and let Sparkle's installer through, subsequent updates from the same Parleq install go through without prompting. Nothing about Parleq specifically triggers this — it's the standard macOS flow for any auto-updating app that installs to a system-owned location.

macOS built-in dictation also runs on-device (since Sonoma) and is integrated wherever a text field appears. It's free, well-tuned for short messages, and needs no setup. Parleq's differences: (1) the cleanup pass — punctuation, capitalization, filler removal, smart proper-noun handling — is doing work the system dictation doesn't; (2) the refinement loop lets you say "make it more professional" or "shorter" and watch the text change without typing; (3) the custom vocabulary feature handles names and jargon the system dictation can't be configured for. Built-in dictation is the right choice for short messages into a chat app. Parleq is built for longer-form composition and voice-driven editing.

On GitHub at parleq/parleq-speech, under Apache-2.0. Issues are open for bugs and feature requests; PRs are welcome — small, targeted fixes are easier to review than sweeping refactors. The README has a developer setup section if you want to build from source.