typewhisper-mac

TypeWhisper for Mac

Speech-to-text and AI text processing for macOS. Transcribe audio using on-device AI models or cloud APIs (Groq, OpenAI, xAI/Grok), then transform the result with reusable workflows. Your voice data stays on your Mac with local models - or use cloud APIs for faster processing.

TypeWhisper 1.8.2 is the current stable release for macOS, available as a direct download and on the Mac App Store. The 1.8 line adds Premium speaker detection, transcription for paired iPhones with this Mac’s models, managed settings for organizations, History re-transcription, the Language Detection plugin, Correct Last Dictation, and imports of custom Parakeet models.

Development on main continues the 1.8 line; release candidates and daily builds are published as GitHub prereleases.

See the 1.8.2 release notes, release readiness guide, support matrix, and release validation process for the shipped feature set and ongoing 1.x maintenance gates. Manual ship checks are tracked per candidate with the release checklist issue template.

Screenshots

The localized macOS screenshot workflow is documented in docs/screenshot-automation.md.

What’s New in 1.8

Highlights from 1.8.0 to 1.8.2. Full details are in the 1.8.0, 1.8.1, and 1.8.2 release notes.

• Speaker detection (Premium) - See who said what, play recordings with a speaker-colored scrubber, show transcripts as a conversation, and rename, merge, or split speakers. Detection runs on the Mac
• iPhone and iPad (Premium) - A paired iPhone running TypeWhisper for iOS can transcribe with this Mac’s speech models, and optionally use the Mac’s language models and workflows, over an encrypted local connection
• Mac App Store - TypeWhisper is available on the Mac App Store, built from the same commit and version as the direct download
• Managed settings - Administrators can configure TypeWhisper through macOS configuration profiles, see the managed settings guide
• History re-transcription - Re-run saved recordings with another engine, model, language, or workflow and compare the results side by side
• Language Detection plugin - Detects which of your selected languages you speak, on the Mac, for engines that accept only one language
• Correct Last Dictation - A menu bar action and shortcut to fix the latest dictation, update History, and learn the corrected word
• Models - Granite Speech 5.0, the Local LLM (llama.cpp) plugin, GigaAM for Russian, Fluid Speech Mini, Parakeet Ultra as default, and imports of your own Parakeet models
• Local API and CLI - API token required by default, word timestamps in verbose_json, text processing with this Mac’s models and workflows, and shell completion for the typewhisper CLI

Features

Transcription

• Local and cloud engines - Choose from WhisperKit, Parakeet (Ultra, TDT v3 and v2, Fluid Speech Mini, and Nemotron 3.5 ASR Streaming, which shows text while you speak), Apple SpeechAnalyzer, Granite Speech, Qwen3 ASR, Voxtral, Cohere Transcribe, GigaAM (Russian), Groq Whisper, OpenAI Whisper, Soniox, Smallest Pulse, xAI/Grok STT, OpenAI Compatible, and additional bundled or community providers
• On-device or cloud - Keep audio on your Mac with a local engine, or explicitly configure a cloud API for faster processing and additional model choices
• Streaming preview - See partial transcription in real-time while speaking (WhisperKit)
• Short-clip handling - Better retention of brief utterances and fewer false no-speech discards
• File transcription - Batch-process multiple audio/video files with drag & drop, or start from Finder
• Custom local models - Import compatible speech models from a Hugging Face repository or a local folder in the settings of local plugins
• Subtitle export - Export transcriptions as SRT or WebVTT with timestamps

Dictation

• System-wide - Push-to-talk, toggle, or hybrid mode via global hotkey, auto-pastes into any app
• Modifier-key hotkeys - Use a single modifier key (Command, Shift, Option, Control) as your hotkey
• Last-transcription actions - Copy or paste your latest transcription with configurable global hotkeys
• Undo and raw restore - Undo Last Dictation removes the last inserted dictation, and Restore Raw Transcript replaces it with the unprocessed text, without touching the clipboard
• Dictation Recovery - Keeps failed recordings and the last three successful dictations for up to 24 hours so they can be retried
• Cancellation - Cancel with double Escape, single Escape, or immediately, or turn cancellation off
• Visual shortcut editor - Set shortcuts on a Mac keyboard that follows the active input source and shows conflicts and unavailable keys
• Indicator styles - Choose Notch, Overlay, or Minimal in Classic, Glass, or Light, with optional live transcript preview where supported
• Sound feedback - Audio cues for recording start, transcription success, and errors
• Microphone selection - Choose a specific input device with live preview and improved recovery after route changes

AI Processing

• Workflows - Build reusable transformations for translation, rewriting, extraction, formatting, and app-specific automation. Workflows can run automatically by app, website, or app + website combinations, from a dedicated hotkey, as a global fallback, or manually from the Workflow Palette. Hotkey workflows can either start dictation or process the current selection/clipboard directly.
• LLM provider fallbacks - Order Apple Intelligence (macOS 26+), Groq, OpenAI / ChatGPT, xAI/Grok, Gemini, OpenAI Compatible, and local providers in one global provider/model list. Prompts and workflows inherit that order by default; a workflow with an explicit provider stays on that single provider
• Speech providers - System voices, xAI/Grok TTS, and experimental local Supertonic TTS can provide spoken feedback and readback
• Local prompt processing - The Local LLM (MLX) plugin runs on-device on Apple Silicon. It recommends the Gemma 4 E2B/E4B 4-bit models and offers Qwen3.5 2B and LFM2.5 2.6B as experimental lighter models
• Translation - Translate transcriptions on-device using Apple Translate

Personalization

• Workflow triggers - Per-app, per-website, combined app + website, hotkey, global fallback, and manual palette-only triggers for language, task, engine, prompt, and auto-submit behavior. Website matching supports subdomains
• Dictionary - Terms improve cloud recognition accuracy. Corrections fix common transcription mistakes automatically. Auto-learns high-confidence local single-word manual corrections, while broader rewrites and deletions are skipped. Includes importable term packs and vocabulary import from Wispr Flow, Handy, and compatible CSV files
• Localized term packs - Built-in term pack names and descriptions are localized in English and German
• Snippets - Text shortcuts with trigger/replacement. Supports placeholders like {{DATE}}, {{TIME}}, and {{CLIPBOARD}}
• History - Searchable transcription history with inline editing, correction detection, app context tracking, timeline grouping, device grouping, filters, bulk delete, multi-select export, auto-retention, and a standalone window accessible from the tray menu

Premium

• Meeting automation - Connect selected calendars for local reminders, start and stop countdowns, optional automatic Recorder sessions, and structured transcript output for supported meeting providers
• Correction learning - Learn deliberate manual corrections in supported target apps using conservative local matching and dictionary integration
• iCloud sync - Sync History and Inbox between your Macs automatically through TypeWhisper’s private iCloud container
• Cloud Folder Sync - Sync Dictionary and Snippets data through a user-selected iCloud Drive, Dropbox, OneDrive, Syncthing, or custom folder
• Clear entitlement states - The Premium hub shows account access and the exact availability of each feature for the current license or signed-in Premium account

Integration & Extensibility

• Plugin system - Extend TypeWhisper with custom LLM providers, transcription engines, TTS providers, post-processors, memory providers, and action plugins. Bundled and registry integrations include local engines, major cloud providers, MCP Client, Obsidian, Linear, Script Runner, Webhook Notifications, and additional automation tools. See the plugin catalog
• Local model download controls - Bundled Qwen3, Granite, Voxtral, and Supertonic plugins support an optional HuggingFace token for higher rate limits and clearer download errors. Supertonic requires explicit OpenRAIL-M model-license acceptance before model assets download.
• HTTP API - Local REST API for integration with external tools and scripts
• CLI tool - Shell-friendly transcription and settings backup via the command line
• Discord claim service - Optional external service for Polar supporter and GitHub Sponsors Discord role claims

General

• Home dashboard - Usage statistics, activity chart, and onboarding tutorial
• Statistics and backups - Inspect local aggregate usage and export or restore supported settings and user data without uploading them to TypeWhisper
• Your data - Export all app data as a ZIP or delete it in Advanced settings
• Auto-update - Built-in updates via Sparkle with stable, release-candidate, and daily channels
• Universal binary - Runs natively on Apple Silicon and Intel Macs
• Widgets - Desktop widgets for usage stats, last transcription, activity chart, and transcription history
• Multilingual UI - English, German, Japanese, Simplified Chinese, and Spanish
• Launch at Login - Start automatically with macOS

Install

Homebrew

brew install --cask typewhisper/tap/typewhisper

Direct Download

Download the latest DMG from GitHub Releases.

Stable direct-download releases use the default Sparkle channel. Release candidates and daily builds are published as GitHub prereleases, update the shared Sparkle appcast on their own channels, and are excluded from Homebrew. Installed builds can switch channels in Settings -> About via the Update Channel picker.

Quick Start

1. Install TypeWhisper from Homebrew or the latest DMG.
2. Open Settings and grant Microphone plus Accessibility access (System Settings > Privacy & Security > Accessibility, named Device Control and Data Access on macOS 27 and later).
3. Pick an engine and, if needed, download a local model.
4. Trigger the global hotkey and complete your first dictation.

Manual Uninstall (macOS)

These steps are for official TypeWhisper release builds on macOS. They remove the app itself, its local state, widget data, and stored secrets so you can reinstall from a clean slate.

If you installed via Homebrew, you can optionally start with:

brew uninstall --cask typewhisper

That removes the app bundle, but it does not reliably remove all files in ~/Library or TypeWhisper entries in Keychain.

If ~/Library is hidden in Finder, use Go -> Go to Folder... and paste the paths below.

1. Quit TypeWhisper if it is running.
2. Delete the app bundle:

   rm -rf /Applications/TypeWhisper.app
   

3. Delete app data and plugins:

   rm -rf ~/Library/Application\ Support/TypeWhisper
   

4. Delete preferences:

   rm -f ~/Library/Preferences/com.typewhisper.mac.plist
   

5. Delete widget and app group data used by official releases:

   rm -rf ~/Library/Group\ Containers/2D8ALY3LCL.com.typewhisper.mac
   

6. Remove TypeWhisper secrets from Keychain:
   • In Keychain Access, search for com.typewhisper.mac.apikey and delete matching items.
   • This includes API and plugin secrets stored under the com.typewhisper.mac.apikey.* service prefix.
   • Also remove the license items stored under service com.typewhisper.mac.apikey.license, especially the polar-license and polar-supporter accounts.
7. If you installed the CLI tool from Settings > Advanced, remove it too:

   rm -f /usr/local/bin/typewhisper
   

8. Optional: if you want to remove exported user files as well, delete:

   rm -rf ~/Documents/TypeWhisper\ Recordings
   

   Recordings saved to a folder you chose under Settings > Recorder > Recordings Folder, or to an earlier folder listed there, are in that folder. Delete them in Finder if you want to remove them too.
9. Restart your Mac, then install the latest build again.

If a fresh install still crashes immediately after these steps, please open an issue and include your macOS version, how you installed TypeWhisper, and whether the crash happens on first launch or after granting permissions.

System Requirements

• macOS 14.0 (Sonoma) or later
• Apple Silicon (M1 or later) recommended
• 8 GB RAM minimum, 16 GB+ recommended for larger models
• Free disk space for downloaded models and their runtime caches. Under storage pressure, macOS can purge Core ML caches; rebuilding them can temporarily slow local transcription.
• Some features (Apple Translate, improved Settings UI) require macOS 15+. Apple Intelligence and SpeechAnalyzer require macOS 26+.

Local LLM (MLX)

TypeWhisper includes the Local LLM (MLX) plugin for on-device prompt processing on Apple Silicon. It recommends the dense Gemma 4 E2B 4-bit and E4B 4-bit models. Qwen3.5 2B and LFM2.5 2.6B need less memory and are available as experimental models; larger Gemma 4 variants are experimental as well. The plugin replaces the former Gemma 4 plugin (com.typewhisper.gemma4) but installs separately: existing Gemma 4 installations do not update to it, and downloaded models, the HuggingFace token, and the model selection are not carried over. Workflows and prompt actions that used Gemma 4 switch to Local LLM (MLX) once the Gemma 4 plugin is removed.

Model Recommendations

RAM	Recommended Models
< 8 GB	Whisper Tiny, Whisper Base
8-16 GB	Whisper Small, Whisper Large v3 Turbo, Parakeet Ultra, Voxtral Mini 4B
> 16 GB	Whisper Large v3

Build

1. Clone the repository:

   git clone https://github.com/TypeWhisper/typewhisper-mac.git
   cd typewhisper-mac
   

2. Open in Xcode 26.6 or later:

   open TypeWhisper.xcodeproj
   

3. Select the TypeWhisper scheme and build (Cmd+B). Swift Package dependencies (WhisperKit, FluidAudio, Sparkle, TypeWhisperPluginSDK) resolve automatically.

4. Run the app. It appears as a menu bar icon - open Settings to download a model.

5. Run the automated checks before shipping changes:

   xcodebuild test -project TypeWhisper.xcodeproj -scheme TypeWhisper -destination 'platform=macOS,arch=arm64' -parallel-testing-enabled NO CODE_SIGN_IDENTITY='-' CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO
   swift test --package-path TypeWhisperPluginSDK
   

HTTP API

The HTTP API is an advanced local automation surface. It binds to 127.0.0.1 only, is disabled by default, and is intended for local tools and scripts.

Enable the API server in Settings > Advanced (default port: 8978).

Authentication

The API server requires a bearer token by default. TypeWhisper creates the token once, keeps it in the Keychain, and writes it to an owner-only discovery file while the server runs. The command line tool, the Raycast extension, the MCP server, and the Pi extension read it automatically. Scripts can read it like this:

TYPEWHISPER_API_TOKEN="$(jq -r '.token' "$HOME/Library/Application Support/TypeWhisper/api-discovery.json")"
curl -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" http://localhost:8978/v1/models

The X-TypeWhisper-API-Token header works as well. Every endpoint except GET /v1/status needs the token; the examples below leave the header out for brevity. Settings > Advanced > Copy API Token copies it to the clipboard.

If the API server is turned on without a token when you update to 1.8.0, it keeps running without one until Require API Token is turned on, and Settings shows a warning. A server that was off during the update requires the token once it is turned on.

Independent of the token, the server rejects requests that browsers send on behalf of other websites: a Host header other than 127.0.0.1, localhost, or [::1], an Origin from a website not served from this Mac (including null), and Sec-Fetch-Site: cross-site unless the Origin is a page served from this Mac. Such requests get 403. Requests without these headers, such as those from curl or scripts, are not affected.

Check Status

curl http://localhost:8978/v1/status

{
  "status": "ready",
  "engine": "whisper",
  "model": "openai_whisper-large-v3_turbo",
  "supports_streaming": true,
  "supports_translation": true
}

Transcribe Audio

curl -X POST http://localhost:8978/v1/transcribe \
  -F "[email protected]" \
  -F "language=en"

curl -X POST http://localhost:8978/v1/transcribe \
  -F "[email protected]" \
  -F "language_hint=de" \
  -F "language_hint=en"

{
  "text": "Hello, world!",
  "language": "en",
  "duration": 2.5,
  "processing_time": 0.8,
  "engine": "whisper",
  "model": "openai_whisper-large-v3_turbo"
}

Optional parameters:

• language - ISO 639-1 code (e.g., en, de). Omit for full auto-detection.
• language_hint - Repeatable, ordered language hint for restricted auto-detection. Hint-aware engines receive the full list; other engines use the first hint as the requested language. Do not combine with language.
• task - transcribe (default) or translate (translates to English with engines that support it; Granite Speech translates into target_language when it supports that language).
• target_language - ISO 639-1 code for translation target language (e.g., es, fr). Uses Apple Translate, unless task is translate and the engine translates into this language itself, as Granite Speech 5.0 2B and 4.0 do for en, fr, de, es, pt, ja, it and zh.
• apply_corrections - Boolean, default true. Set to false to return raw transcription text without Dictionary Corrections. For raw body uploads, send x-apply-corrections: false.
• detect_speakers - Boolean, default false. Adds a speaker (Speaker 1, Speaker 2, …) to each segment of a verbose_json response. Needs Premium. For raw body uploads, send x-detect-speakers: true.
• speaker_count - Number of speakers, when known. Omit it to detect the number. For raw body uploads, send x-speaker-count.
• response_format - json (default) or verbose_json, which adds segments with start, end and text in seconds. For raw body uploads, send x-response-format.
• timestamp_granularities[] - Repeatable, segment or word. With word, a verbose_json response also contains words with the time of each word. Engines without word timing return an empty words array; ElevenLabs Scribe and Parakeet provide them. For raw body uploads, send x-timestamp-granularities: word; /v1/transcribe/local-file takes a JSON array, "timestamp_granularities": ["word"].

Word timestamps:

curl -X POST http://localhost:8978/v1/transcribe \
  -F "[email protected]" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=word"

{
  "text": "Thank you for coming. We start the interview now.",
  "language": "en",
  "duration": 2.9,
  "processing_time": 0.6,
  "engine": "elevenlabs",
  "model": "scribe_v2",
  "segments": [
    { "start": 0.08, "end": 1.0, "text": "Thank you for coming." },
    { "start": 1.32, "end": 2.68, "text": "We start the interview now." }
  ],
  "words": [
    { "word": "Thank", "start": 0.08, "end": 0.3 },
    { "word": "you", "start": 0.34, "end": 0.46 },
    { "word": "for", "start": 0.5, "end": 0.58 },
    { "word": "coming.", "start": 0.68, "end": 1.0 },
    { "word": "We", "start": 1.32, "end": 1.42 },
    { "word": "start", "start": 1.5, "end": 1.74 },
    { "word": "the", "start": 1.78, "end": 1.88 },
    { "word": "interview", "start": 1.92, "end": 2.32 },
    { "word": "now.", "start": 2.4, "end": 2.68 }
  ]
}

words are the engine’s own words: Dictionary Corrections, number formatting and translation change text and segments, not words.

Uploads to /v1/transcribe are limited to 256 MiB, including stdin uploads from the CLI. Requests above that size return 413 Payload Too Large. Local CLI file paths use a direct handoff to the running TypeWhisper app instead of uploading the file bytes.

List Models

curl http://localhost:8978/v1/models

{
  "models": [
    {
      "id": "openai_whisper-large-v3_turbo",
      "engine": "whisper",
      "name": "Large v3 Turbo",
      "status": "ready",
      "selected": true,
      "downloaded": true,
      "loaded": true
    }
  ]
}

Manage Models

Download (if needed), load, and select a model. The request returns after the model is ready or the load fails:

curl -X POST http://localhost:8978/v1/models/load \
  -H "Content-Type: application/json" \
  -d '{"engine":"whisper","model":"openai_whisper-large-v3_turbo"}'

Unload the active model while keeping its downloaded files:

curl -X POST http://localhost:8978/v1/models/unload \
  -H "Content-Type: application/json" \
  -d '{"engine":"whisper"}'

Delete downloaded model files:

curl -X DELETE "http://localhost:8978/v1/models?engine=whisper&model=openai_whisper-large-v3_turbo"

Deleting the last downloaded model of a transcription engine keeps its plugin enabled and the saved default engine unchanged (plugins without a transcription engine are still disabled when their last model is deleted). The engine is not ready until a model is downloaded again; meanwhile dictation temporarily falls back to another usable engine, preferring one that is ready, or reports the missing model if there is none. If API authentication is enabled, include the same bearer token used by the other protected endpoints.

History

# Search history
curl "http://localhost:8978/v1/history?q=meeting&limit=10&offset=0"

# Delete entry
curl -X DELETE "http://localhost:8978/v1/history?id=<uuid>"

Entries with speaker detection carry speaker_state. Once a speaker transcript exists, they also carry speakers. Each speaker has an id and a name: the confirmed name, or Speaker N. When a voice profile suggested a name that nobody has confirmed yet, it is returned as suggested_name, and name stays Speaker N. Add include=speaker_segments to get the speaker segments. Entries that came from the Recorder carry the recording_id used by GET /v1/recorder/recordings and the .transcript-ready.json sidecar.

Entries whose text an LLM processed carry llm_usage: requests, the summed input_tokens and output_tokens, and providers, one item per provider and model with provider, provider_name, model, requests, input_tokens and output_tokens. Token counts are what the providers reported, summed over every request for the text, including fallback attempts and retries. A count is absent when no request reported it, for example with Apple Intelligence or a plugin that does not report usage. Entries without LLM processing, and entries made before TypeWhisper recorded usage, have no llm_usage. TypeWhisper does not estimate costs.

"llm_usage": {
  "requests": 1,
  "input_tokens": 1284,
  "output_tokens": 18,
  "providers": [
    { "provider": "Claude", "provider_name": "Claude", "model": "claude-haiku-4-5", "requests": 1, "input_tokens": 1284, "output_tokens": 18 }
  ]
}

Name speakers and teach voice profiles

History entries with a speaker transcript also include transcript_revision and transcript_version. The latter changes when speakers or transcript text are corrected. Each speaker includes voice_state (none, canEnroll, suggestion, linked, or outdated) and, when available on this Mac, profile_id. The state reflects local voice availability and Premium access: canEnroll and outdated require Premium. Existing links and suggestions remain visible without Premium.

The following local-only endpoints always require the API bearer token, even when authentication for older API endpoints is disabled. They are not available through Remote Link. Names can be set without Premium; enrollment and confirmation require Premium, current local speaker embeddings, and at least 20 seconds of speech. Neither audio nor embeddings are accepted or returned.

1. Find the History entry whose recording_id matches the Recorder session. Wait for speaker_state: "ready"; stop on failed. Read its id, transcript_revision, transcript_version, and the exact speakers[].id you intend to name.
2. Set the name with PUT /v1/history/speakers/name. This only changes the transcript’s name, even if it matches an unconfirmed suggestion. It never teaches a profile. Changing a name unlinks the previous profile; changes in casing preserve it.
3. Use POST /v1/history/speakers/enroll to explicitly teach that voice. Omit profile_id to create a profile when no matching name exists, or pass a known profile ID to add the sample to that person. An existing name returns 409 profile_name_exists with candidate IDs in error.profile_ids. Select an ID, or send create_profile: true to explicitly create a different person with the same name. Do not combine create_profile: true with profile_id. Equal names alone never merge API enrollments. With multiple profiles of the same name, the app also disables name-only enrollment; use an explicit profile_id or give the profiles distinct names. The named speaker and the existing profile must have matching names. Alternatively, confirm a current suggestion directly with POST /v1/history/speakers/confirm, including its profile_id.

All three endpoints require both transcript identifiers in a JSON object. Unknown fields are rejected. history_id is the History entry’s id, not the Recorder’s recording_id. For example, after reading the actual identifiers and the token from the discovery file:

curl -X PUT http://localhost:8978/v1/history/speakers/name \
  -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"history_id":"<history-uuid>","transcript_revision":"<revision-uuid>","transcript_version":"<version>","speaker_id":"S1","name":"Lev"}'

curl -X POST http://localhost:8978/v1/history/speakers/enroll \
  -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"history_id":"<history-uuid>","transcript_revision":"<revision-uuid>","transcript_version":"<version>","speaker_id":"S1"}'

# In a later recording, confirm the profile_id returned with a suggestion:
curl -X POST http://localhost:8978/v1/history/speakers/confirm \
  -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"history_id":"<later-history-uuid>","transcript_revision":"<later-revision-uuid>","transcript_version":"<later-version>","speaker_id":"S2","profile_id":"<profile-uuid>"}'

A successful response includes history_id, transcript_revision, transcript_version, speaker_id, voice_state, already_learned, and the available name/profile fields. Enrollment and confirmation count each original speaker sample only once per profile, including retries after restarting the app or renumbering speakers. Merging a learned sample with an unlearned one produces a conflict; use the app’s explicit relearn action to replace that profile without double weighting. A retry can repair the History link after an interrupted write. A receipt for a deleted profile produces a conflict; retries do not recreate deleted profiles. Re-detection creates a new transcript revision. Merge, split, reassignment, and text edits change transcript_version, even within the same revision. Scripts must re-read the current transcript and reassess speaker identity after a stale_transcript conflict. Deleting a History record removes its learning receipts; deleting only a profile retains them to prevent accidental recreation. Renaming does not undo previous learning; use the app’s relearn/delete actions to correct a bad profile.

Errors use the standard error.code/error.message envelope: 400 for malformed input or invalid names, 401 for a missing/invalid token, 403 for unavailable Premium, 404 for an unknown entry/speaker, 409 for stale transcripts, not-ready detection, changed suggestions or conflicting profiles, 422 for unavailable/invalid voice samples, and 500 for persistence failures. Retry an identical request after a transient 500; inspect and resolve a 409 instead of blindly changing identifiers. Renaming a voice profile or a newer speaker correction can intentionally prevent replay of an older request.

Speaker IDs express diarization labels, not microphone/system channels. Scripts must establish which speaker belongs to the known attendee; never assume S1 means the microphone or infer identity solely from the invitation list.

Dictionary

# List recognition terms
curl http://localhost:8978/v1/dictionary/terms

# Merge terms, or set replace=true to replace all terms
curl -X PUT http://localhost:8978/v1/dictionary/terms \
  -H "Content-Type: application/json" \
  -d '{"terms":["TypeWhisper","WhisperKit"],"replace":false}'

# Delete one term
curl -X DELETE http://localhost:8978/v1/dictionary/terms \
  -H "Content-Type: application/json" \
  -d '{"term":"TypeWhisper"}'

# List post-transcription corrections
curl http://localhost:8978/v1/dictionary/corrections

# Add or update one correction by original text
curl -X PUT http://localhost:8978/v1/dictionary/corrections \
  -H "Content-Type: application/json" \
  -d '{"original":"teh","replacement":"the","caseSensitive":false}'

# Delete one correction
curl -X DELETE http://localhost:8978/v1/dictionary/corrections \
  -H "Content-Type: application/json" \
  -d '{"original":"teh"}'

Correction responses include isRegex. Set isRegex: true in PUT or DELETE to address a regular expression; omitting it addresses a literal correction. Regex patterns are identified by their exact text, including case and spaces, so \d and \D are separate rules and a literal entry can coexist with a regex entry. To change modes through the API, delete the old entry using its mode and PUT the new one. Invalid regex patterns return HTTP 400. Replacements are literal except for \n, \r, \t, \s, and \\ escapes; $1 is not a capture reference.

Settings Backup

The settings endpoints use the same JSON backup schema and merge/skip behavior as Settings > Advanced > Backup & Restore. Import applies every category present in the backup. These examples include the bearer token from the discovery file (see Authentication):

TYPEWHISPER_API_TOKEN="$(jq -r '.token' "$HOME/Library/Application Support/TypeWhisper/api-discovery.json")"

# Export the current settings backup
(
  settings_backup_tmp="$(mktemp ./typewhisper-settings.json.tmp.XXXXXX)" || exit
  trap 'rm -f "$settings_backup_tmp"' EXIT
  curl --fail --silent --show-error http://localhost:8978/v1/settings/export \
    -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
    --output "$settings_backup_tmp" && \
    mv "$settings_backup_tmp" typewhisper-settings.json
)

# Import all categories from a settings backup
curl --fail --silent --show-error -X POST http://localhost:8978/v1/settings/import \
  -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @typewhisper-settings.json

# Import and overwrite workflows, profiles, prompt actions with the same name and hotkeys
curl --fail --silent --show-error -X POST "http://localhost:8978/v1/settings/import?mode=replace" \
  -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @typewhisper-settings.json

An import skips history entries, workflows, profiles, and prompt actions that already exist unchanged, so importing a backup onto the Mac it came from does not duplicate them. The default mode=merge adds everything else and only fills empty hotkey slots. mode=replace also overwrites existing workflows, profiles, and prompt actions with the same name and the hotkeys contained in the backup. Neither mode deletes anything.

Audio Settings

GET /v1/settings/audio returns the microphone priority list and the recording audio options from Settings > Dictation. PATCH /v1/settings/audio changes any subset of them through the same code path as the settings window: the change applies to the next recording, persists across restarts, and shows up in the open settings window. TypeWhisper for Windows serves the same contract.

# Show available inputs, the priority list, and the input the next recording would use
curl http://localhost:8978/v1/settings/audio

# Record from BlackHole and turn off ducking
curl -X PATCH http://localhost:8978/v1/settings/audio \
  -H "Content-Type: application/json" \
  -d '{"input_priority":[{"id":"BlackHole2ch_UID","name":"BlackHole 2ch"}],"audio_ducking_enabled":false}'

# Use the macOS default input
curl -X PATCH http://localhost:8978/v1/settings/audio \
  -H "Content-Type: application/json" \
  -d '{"input_priority":[]}'

{
  "input_devices": [{"id": "BlackHole2ch_UID", "name": "BlackHole 2ch", "is_system_default": false}],
  "input_priority": [{"id": "AppleUSBAudioEngine:HyperX:QuadCast 2", "name": "HyperX QuadCast 2"}],
  "active_input": {"id": "BuiltInMicrophoneDevice", "name": "MacBook Pro Microphone"},
  "audio_ducking_enabled": true,
  "audio_ducking_level": 0.2,
  "pause_media_during_recording": false,
  "sound_feedback_enabled": true
}

Field	Writable	Description
input_devices	no	Input devices that are connected now. id is the CoreAudio device UID.
input_priority	yes	The saved priority list, including devices that are not connected. Each entry needs an id; name is optional and is replaced by the current name while the device is connected. [] records from the macOS default input.
active_input	no	The input the next recording would use: the first connected entry of input_priority, otherwise the macOS default input. null when there is no input.
audio_ducking_enabled	yes	Reduce the system volume during recording.
audio_ducking_level	yes	Share of the current volume kept during recording, from 0 (mute) to 1. The settings slider offers 0 to 0.5.
pause_media_during_recording	yes	Pause media playback during recording.
sound_feedback_enabled	yes	Play start, success, and error sounds.

A successful PATCH returns the full state, as GET does. It returns 400 for invalid JSON, a value of the wrong type or range, a duplicate or empty device ID, a read-only field, or an unknown field; in that case nothing changes. TypeWhisper for macOS supports every writable field of the shared contract. A field that only another platform offers is an unknown field here, and the error message names it together with the fields macOS accepts. While a dictation or the recorder is recording or still processing, PATCH returns 409 and changes nothing; GET keeps working.

To change the settings temporarily, save the GET response, send your changes, and later send the saved writable fields back:

saved="$(curl --fail --silent http://localhost:8978/v1/settings/audio)"
# ... change settings, record ...
jq 'del(.input_devices, .active_input)' <<<"$saved" | \
  curl --fail --silent -X PATCH http://localhost:8978/v1/settings/audio \
    -H "Content-Type: application/json" --data-binary @-

Workflows

# List all workflow-backed rules
curl http://localhost:8978/v1/rules

# Toggle a workflow-backed rule on/off
curl -X PUT "http://localhost:8978/v1/rules/toggle?id=<uuid>"

Dictation Control

# Start dictation (returns session id)
curl -X POST http://localhost:8978/v1/dictation/start

# Stop dictation (returns same session id)
curl -X POST http://localhost:8978/v1/dictation/stop

# Check whether dictation is currently recording
curl http://localhost:8978/v1/dictation/status

# Fetch status/result for a specific dictation session
curl "http://localhost:8978/v1/dictation/transcription?id=<uuid>"

Dictation control records microphone audio for system-wide insertion. A completed dictation session returns text that TypeWhisper can paste back into the active app.

For the last 100 dictations since the app started, the transcription response also contains a latency object with the timings of each dictation phase, from the start request to verified insertion and clipboard restoration. It never contains transcript text, audio or app content. Other sessions return latency: null.

Recorder Control

Recorder control uses the same recorder path as the TypeWhisper UI, including microphone capture, optional system audio capture, mixing, finalization, and final transcription. Use it for automations that need a saved recording file or meeting/system-audio transcription without auto-pasting into another app.

# Start recorder with microphone and system audio
curl -X POST "http://localhost:8978/v1/recorder/start?mic=true&system_audio=true"

# Stop the active API recorder session
curl -X POST http://localhost:8978/v1/recorder/stop

# Check whether the recorder is currently recording
curl http://localhost:8978/v1/recorder/status

# Fetch status/result for a specific recorder session
curl "http://localhost:8978/v1/recorder/session?id=<uuid>"

POST /v1/recorder/start accepts optional query flags:

• mic - true, false, 1, or 0. If omitted, TypeWhisper uses the current recorder microphone setting.
• system_audio - true, false, 1, or 0. If omitted, TypeWhisper uses the current recorder system-audio setting.

At least one source must be enabled. If both resolved sources are disabled, the API returns 400 Bad Request.

Start response:

{
  "id": "8F8C1F45-6D03-44D2-A38C-0C4DE4F7E5F7",
  "status": "recording"
}

Stop response:

{
  "id": "8F8C1F45-6D03-44D2-A38C-0C4DE4F7E5F7",
  "status": "finalizing"
}

Status response:

{
  "recording": true
}

Session response:

{
  "id": "8F8C1F45-6D03-44D2-A38C-0C4DE4F7E5F7",
  "status": "completed",
  "text": "Meeting notes from the recording.",
  "output_file": "/Users/alex/Documents/TypeWhisper Recordings/Recording 2026-05-20 14-30-00.m4a"
}

Recorder sessions move through recording -> finalizing -> completed or failed. If recorder transcription is disabled or produces no transcript, text is omitted and output_file still points to the finalized recording when available. Failed sessions include an error field.

A stopped session is transcribed in the background, so a new session can start while earlier sessions are still finalizing. Transcripts are made one at a time, in the order the recordings stopped, and each session reports its own status.

Conflict and lookup behavior:

• Starting while the recorder is already recording, or still saving the audio of the recording that just stopped, returns 409 Conflict.
• Stopping without an active API recorder session returns 409 Conflict.
• Polling with a missing or invalid id returns 400 Bad Request.
• Polling a valid but unknown session id returns 404 Not Found.

Completed Recorder Transcripts

GET /v1/recorder/recordings returns the latest successfully saved transcript for each recording, including recordings started manually, by the calendar integration, or through the API. Results survive app restarts and do not depend on live preview or an API session. It covers the Recorder folder chosen in Settings > Recorder and the earlier folders the Recorder still lists there.

curl "http://localhost:8978/v1/recorder/recordings?since=1791100000.123456"

{
  "recordings": [
    {
      "source": "recorder",
      "recording_id": "8F8C1F45-6D03-44D2-A38C-0C4DE4F7E5F7",
      "completion_id": "59CBC40C-274A-47A9-804C-8774AB504401",
      "completed_at": 1791100000.123456,
      "text": "Meeting notes from the recording.",
      "audio_file": "/Users/alex/Documents/TypeWhisper Recordings/Meeting.m4a",
      "transcript_file": "/Users/alex/Documents/TypeWhisper Recordings/Meeting.txt",
      "recorded_at": 1791098200.5,
      "duration_seconds": 1795.2,
      "calendar_event": {
        "title": "Weekly sync",
        "start": 1791098100,
        "end": 1791099900,
        "attendees": [
          { "name": "Alex", "email": "[email protected]", "status": "accepted", "is_current_user": true },
          { "name": "Kim", "email": "[email protected]", "status": "tentative", "is_current_user": false }
        ]
      },
      "speaker_state": "ready",
      "speakers": [
        { "id": "S1", "name": "Me", "is_me": true },
        { "id": "S2", "name": "Speaker 2", "suggested_name": "Kim", "is_me": false }
      ],
      "speaker_segments": [
        { "start": 0.4, "end": 3.1, "speaker": "S1", "text": "Meeting notes from the recording." }
      ]
    }
  ]
}

since accepts Unix seconds or an ISO 8601 timestamp and filters inclusively by successful completion time, not the recording’s start time. Results are ordered oldest completion first. After processing a response, retain its last completed_at and deduplicate by completion_id; querying inclusively avoids losing completions with equal timestamps. Invalid timestamps return 400; unreadable completion receipts return 500 so a consumer does not silently advance past them.

Each successful retranscription keeps the recording_id, assigns a new completion_id, and replaces the previous result. This is a list of the latest saved results, not a revision history. Failed attempts leave the last successful result available. markdown_file is included only when a Markdown transcript was saved and still exists; currently that applies to calendar recordings with meeting metadata. Audio and transcript paths refer to existing files.

recorded_at is when the recording started and duration_seconds its length; both are absent when the audio file does not tell. calendar_event is present for recordings started from the calendar, with title, start and end in Unix seconds, location, organizer and attendees.

Recordings with speaker detection carry speaker_state (pending, ready or failed) and, once speakers were found, speakers and speaker_segments in the shape GET /v1/history uses. is_me marks the speaker heard on the microphone, the user of this Mac; its name is the localized name for yourself until you rename it. The speakers come from the recording’s History record, so renaming a speaker there shows up in the next response. A recording transcribed again keeps its History record and the speakers found for it.

Completion receipts are saved alongside recordings as <audio filename>.transcript-ready.json. A separate <audio filename>.recording-id.json preserves the recording ID if the receipt is damaged, so retranscription can repair it without changing the ID. Both files are committed with the transcript and removed when the recording is deleted in TypeWhisper. Existing recordings become available here after their next successful transcription. Recordings without a saved transcript are omitted. The endpoint uses the same API token as the other private routes.

The Plugin SDK emits recorderTranscriptReady after the transcript and receipt have been saved. When the recording gets speaker detection, the event waits until detection has finished and carries speaker_state and the speakers, so it arrives later than the transcript files; the next recording is transcribed meanwhile. If TypeWhisper quits before detection finishes, the event is not sent. It does not emit the dictation transcriptionCompleted event or run Recorder Workflows. Event delivery is best effort while TypeWhisper and the plugin are running; use the API to catch up on missed completions.

In Webhook Notifications, enable Also send completed Recorder transcripts for each destination that should receive this event. The JSON body has the same fields as an entry above. Webhook retries keep the same completion_id.

In Script Runner, enable Also run for completed Recorder transcripts for each export command. Both options default to off, including for existing configurations, and operate independently of dictation rule/workflow filters. Recorder scripts receive the saved original through stdin and these environment variables:

Variable	Value
TYPEWHISPER_SOURCE	recorder
TYPEWHISPER_RECORDING_ID	Stable recording UUID
TYPEWHISPER_COMPLETION_ID	UUID for this successful save
TYPEWHISPER_COMPLETED_AT	Completion time in Unix seconds
TYPEWHISPER_AUDIO_FILE	Audio file path
TYPEWHISPER_TRANSCRIPT_FILE	Plain-text transcript path
TYPEWHISPER_MARKDOWN_FILE	Markdown path, when available; otherwise unset
TYPEWHISPER_MEETING_TITLE	Calendar event title
TYPEWHISPER_MEETING_START	Event start in whole Unix seconds
TYPEWHISPER_MEETING_END	Event end in whole Unix seconds
TYPEWHISPER_MEETING_ATTENDEES	Attendees, one per line: the name, or the email address when the calendar has none

The TYPEWHISPER_MEETING_* variables come from calendar_event above and are set only for recordings started from the calendar. For all other recordings they stay unset, so a script can tell the two apart. Start and end have no decimal places, so date -r "$TYPEWHISPER_MEETING_START" +%H:%M works.

Recorder scripts export the original transcript independently; stdout is ignored and may be empty. A nonzero exit status is logged as a failure. The existing five-second script timeout applies, so enqueue longer processing in a separate worker. Ordinary dictation scripts continue to transform text through stdout.

CLI Tool

TypeWhisper includes a command-line tool for shell-friendly transcription. It is part of the advanced automation surface and connects to the running local API server.

Installation

Install via Settings > Advanced > CLI Tool > Install. This places the typewhisper binary in /usr/local/bin.

Commands

typewhisper status              # Show server status
typewhisper models              # List available models
typewhisper models load --engine parakeet --model parakeet-tdt-0.6b-v3 # Load and select a model
typewhisper models unload --engine parakeet # Unload it, keeping its files
typewhisper models delete --engine whisper --model openai_whisper-large-v3_turbo # Delete downloaded files
typewhisper transcribe file.wav # Transcribe an audio file
typewhisper export settings.json # Export all supported settings
typewhisper import settings.json # Import all categories in a backup
typewhisper audio               # Show microphone priority, ducking and sound settings
typewhisper audio set changes.json # Change audio settings (see Audio Settings above)
typewhisper completions zsh     # Print a shell completion script (bash, zsh, fish)

Shell Completion

typewhisper completions <shell> prints a completion script for bash, zsh, or fish. It completes commands, subcommands, the options that apply to each command, and file paths. While TypeWhisper is running with the API server enabled, --engine and --model also suggest the installed engine and model IDs; --model only lists models of the engine given with --engine. Without a running app, commands and options still complete.

# zsh: add to ~/.zshrc after compinit
eval "$(typewhisper completions zsh)"

# bash: add to ~/.bashrc
eval "$(typewhisper completions bash)"

# fish
mkdir -p ~/.config/fish/completions
typewhisper completions fish > ~/.config/fish/completions/typewhisper.fish

If you save the script to a file, as in the fish example, generate it again after updating TypeWhisper so new commands and options are included.

Options

Option	Description
--port <N>	Server port (default: auto-detect)
--json	Output as JSON
--language <code>	Source language (e.g. en, de)
--language-hint <code>	Repeatable, ordered language hint for restricted auto-detection; engines without hint support use the first hint
--task <task>	transcribe (default) or translate
--translate-to <code>	Target language for translation
--no-corrections	Return raw transcription text without Dictionary Corrections
--engine <id>, --model <id>	transcribe: use this engine or model for the request; models load|delete: the engine and model to act on; models unload: --engine only
--replace	import only: overwrite workflows, profiles, and prompt actions with the same name and replace hotkeys

Examples

# Transcribe with language and JSON output
typewhisper transcribe recording.wav --language de --json

# Restrict auto-detection to a shortlist
typewhisper transcribe recording.wav --language-hint de --language-hint en

# Pipe audio from stdin
cat audio.wav | typewhisper transcribe -

# Use in a script
typewhisper transcribe meeting.m4a --json | jq -r '.text'

# Keep a portable backup in a dotfiles repository
typewhisper export ~/.config/typewhisper/settings.json

# Restore it and receive a machine-readable import summary
typewhisper import ~/.config/typewhisper/settings.json --json

# Apply edits made to that file, including changed hotkeys
typewhisper import ~/.config/typewhisper/settings.json --replace

# Record from BlackHole until you switch back
echo '{"input_priority":[{"id":"BlackHole2ch_UID"}]}' | typewhisper audio set -

The CLI requires the API server to be running (Settings > Advanced) and follows the documented command and flag surface for the current stable release.

Dictionary Corrections apply to CLI transcriptions by default. Use --no-corrections when a script needs the raw engine output.

Local file paths are handed to the running TypeWhisper app directly, so large files do not need to fit inside an HTTP upload body. Stdin usage (typewhisper transcribe -) still uses the regular /v1/transcribe upload endpoint and is limited to 256 MiB.

Workflows

Workflows let you configure transcription, transformation, and automation behavior per application, website, combined app + website context, hotkey, global fallback, or manual palette-only workflow. For example:

• Mail - German language, Whisper Large v3
• Slack - English language, Parakeet TDT v3
• Terminal - English language, auto-submit enabled
• github.com - English cleanup workflow that matches in any browser
• docs.google.com - German dictation workflow that translates to English

Create workflows in Settings > Workflows. Choose a template, then use Automatic to enable app, website, hotkey, or any combination of those trigger components. Always stays the global fallback, and Manual keeps the workflow palette-only. Hotkey workflows choose whether the shortcut starts dictation or processes the current selection/clipboard through the same insertion path as the Workflow Palette. Spoken language can be left on full auto-detect, fixed to one exact language, or restricted to a shortlist of likely languages for better detection accuracy. Website patterns support subdomain matching - e.g. google.com also matches docs.google.com.

LLM Prompt workflows inherit the ordered global LLM fallback list shown at the top of Settings > Workflows. TypeWhisper moves to the next provider/model when an inherited attempt is unavailable, cannot restore, is rate-limited, hits a network or API error, or returns no text. Selecting a provider inside a workflow disables that fallback behavior for the workflow and makes one strict provider call instead.

When you start dictating, TypeWhisper matches the active app and browser URL against enabled workflows with the following priority:

1. App + URL match - highest specificity (e.g. Chrome + github.com)
2. URL-only match - cross-browser workflows (e.g. github.com in any browser)
3. App-only match - generic app workflows (e.g. all of Chrome)
4. Always fallback - global workflow when no more specific workflow matches

An Always workflow can exclude apps and websites. In an excluded app or on an excluded website it does not run, and TypeWhisper behaves as if the workflow did not exist. Website exclusions use the same subdomain matching as website triggers.

Hotkeys are direct workflow shortcuts, not context conditions in the app/URL matching order. Manual workflows are excluded from automatic dictation matching. They appear only in the Workflow Palette and use the existing Workflow Palette hotkey.

The active workflow name is shown as a badge in the indicator, together with a short explanation of why it matched.

Multiple engines can be loaded simultaneously during a session for instant switching between workflows. Note that loading multiple local models increases memory usage. Set Auto-unload model to Never if you want TypeWhisper to restore previously loaded local models at launch; any active auto-unload policy keeps startup lazy and reloads the selected/downloaded model on first real use. Cloud engines (Groq, OpenAI, xAI/Grok) have negligible memory overhead.

Plugins

TypeWhisper supports plugins for adding custom LLM providers, transcription engines, TTS providers, post-processors, and action plugins. Plugins are macOS .bundle files placed in ~/Library/Application Support/TypeWhisper/Plugins/.

Bundled engines and integrations (WhisperKit, Parakeet, SpeechAnalyzer, Granite, Qwen3, Voxtral, Supertonic, Groq, OpenAI, xAI/Grok, OpenAI Compatible, Gemini, Linear, Webhook, and more) are implemented as plugins and serve as reference implementations.

See TypeWhisperPluginSDK/Plugins/README.md for the full plugin development guide, including the event bus, host services API, and manifest format.

Architecture

TypeWhisper/
├── typewhisper-cli/           # Command-line tool (transcription and settings backup)
├── PluginRegistry/            # Source registry entries for community plugin feeds
├── Plugins/                # Redirect docs and legacy entrypoint for moved first-party plugin sources
├── TypeWhisperPluginSDK/   # Plugin SDK (Swift package)
│   ├── Plugins/            # First-party plugin sources and manifests
├── TypeWhisperWidgetExtension/ # WidgetKit widgets (stats, activity, history)
├── TypeWhisperWidgetShared/    # Shared widget data models
├── App/                    # App entry point, dependency injection
├── Models/                 # Data models (TranscriptionResult, Profile, PromptAction, etc.)
├── Services/
│   ├── Cloud/              # KeychainService, WavEncoder (shared cloud utilities)
│   ├── LLM/               # Apple Intelligence provider (cloud LLM providers are plugins)
│   ├── HTTPServer/         # Local REST API (HTTPServer, APIRouter, APIHandlers)
│   ├── ModelManagerService # Transcription dispatch (delegates to plugins)
│   ├── AudioRecordingService
│   ├── AudioFileService    # Audio/video - 16kHz PCM conversion
│   ├── HotkeyService
│   ├── TextInsertionService
│   ├── WorkflowService     # Workflow matching and persistence
│   ├── HistoryService      # Transcription history persistence (SwiftData)
│   ├── DictionaryService   # Custom term corrections
│   ├── SnippetService      # Text snippets with placeholders
│   ├── PromptActionService # Prompt action persistence (SwiftData)
│   ├── PromptProcessingService # LLM orchestration for prompt execution
│   ├── PluginManager       # Plugin discovery, loading, and lifecycle
│   ├── PluginRegistryService # Plugin marketplace (download, install, update)
│   ├── PostProcessingPipeline # Priority-based text processing chain
│   ├── EventBus            # Typed publish/subscribe event system
│   ├── TranslationService  # On-device translation via Apple Translate
│   ├── SubtitleExporter    # SRT/VTT export
│   └── SoundService        # Audio feedback for recording events
├── ViewModels/             # MVVM view models with Combine
├── Views/                  # SwiftUI views
└── Resources/              # Info.plist, entitlements, localization, sounds

Patterns: MVVM with ServiceContainer singleton for dependency injection. ViewModels use a static _shared pattern. Localization via String(localized:) with Localizable.xcstrings.

License

GPLv3 - see LICENSE for details. Commercial licensing available - see LICENSE-COMMERCIAL.md.