TypeWhisper/typewhisper-mac

Local speech-to-text for macOS on-device AI, fully private, optional cloud - TypeWhisper/typewhisper-mac

1.6k stars · 112 forks · Swift Topics: macos, privacy, speech-to-text, transcription, dictation, whisper, on-device, swiftui, apple-silicon, whisperkit

README

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.5 is the current stable release for macOS. It includes system-wide dictation, file transcription, unified workflows, history, dictionary, snippets, bundled integrations, the community plugin registry, local automation APIs, app-aware insertion, expanded provider support, and local-model reliability improvements. The main branch is now preparing the 1.6 release-candidate line; 1.5 receives hotfixes only from release/1.5. See the release readiness guide, support matrix, and release checklist for the active 1.6 release definition and ship gates.

typewhisper-demo-full-with-voiceover.mp4

Screenshots

What's New in 1.5

App-aware dictation insertion - Dictation output now better respects sentence position, trailing spaces, terminal paste behavior, rich-text targets, and target-app context Expanded speech and AI providers - Gemini speech transcription, Cartesia speech transcription, Sber SaluteSpeech, OpenRouter speech-to-text, Reson8, Mistral AI, Soniox regions and TTS, and OpenAI-compatible profiles broaden the bundled provider set Local model reliability - MLX memory-footprint controls, idle auto-unload behavior, stalled Gemma 4 download recovery, and Parakeet vocabulary repair improve local model setup and day-to-day stability Dictionary learning and normalization - Auto-learned corrections, target-app correction learning, per-term CTC tuning plumbing, multilingual number-word normalization, English ordinals, digit sequences, and French decimal cleanup improve recognition output Workflow and hotkey reliability - Hybrid modifier timing, non-Control modifier taps, global push-to-talk, Pages workflow hotkeys, menu-based dictation pause, Esc confirmation, and automatic workflow output resolution all received targeted fixes Recording and indicator polish - Virtual audio input support, media pause/resume hardening, fullscreen indicator fixes, recorder final-failure surfacing, FaceTime built-in microphone capture, and TaskForge insertion fallback improve real-world capture and insertion flows Release and plugin metadata cleanup - Cloud ASR upload fallback handling, plugin host-compatibility metadata, plugin uninstall cleanup, and GitHub Latest protection keep the 1.5 distribution path clean

Features Transcription

Eleven engines - WhisperKit (99+ languages, streaming, translation), Parakeet TDT v3 (25 European languages, extremely fast), Apple SpeechAnalyzer (macOS 26+, no model download needed), Granite Speech (MLX-based), Qwen3 ASR (MLX-based), Voxtral (local Voxtral Mini 4B, MLX-based), Groq Whisper, OpenAI Whisper, Smallest Pulse, xAI/Grok STT, and OpenAI Compatible (any OpenAI-compatible API) On-device or cloud - All processing happens locally on your Mac, or use Groq/OpenAI/xAI APIs for faster processing 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 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 Indicator styles - Choose Notch, Overlay, or Minimal, 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 - Gemma 4 via MLX runs on-device on Apple Silicon, with the current verified release path limited to the E2B/E4B 4-bit 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 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, filters, bulk delete, multi-select export, auto-retention, and a standalone window accessible from the tray menu

Integration & Extensibility

Plugin system - Extend TypeWhisper with custom LLM providers, transcription engines, TTS providers, post-processors, and action plugins. Gemini, Granite, Groq, Linear, OpenAI / ChatGPT, OpenAI Compatible, Qwen3, Smallest Pulse, Supertonic, Voxtral, Webhook, and xAI/Grok ship as bundled plugins, alongside the local engine plugins. Linear plugin enables voice-to-issue creation. See TypeWhisperPluginSDK/Plugins/README.md 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 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 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 and German 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 such as 1.6.0-rc* and daily builds such as v1.6.0-daily.* 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

Install TypeWhisper from Homebrew or the latest DMG. Open Settings and grant Microphone plus Accessibility access. Pick an engine and, if needed, download a local model. 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.

Quit TypeWhisper if it is running. Delete the app bundle: rm -rf /Applications/TypeWhisper.app

Delete app data and plugins: rm -rf ~/Library/Application\ Support/TypeWhisper

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

Delete widget and app group data used by official releases: rm -rf ~/Library/Group\ Containers/2D8ALY3LCL.com.typewhisper.mac

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.

If you installed the CLI tool from Settings > Advanced, remove it too: rm -f /usr/local/bin/typewhisper

Optional: if you want to remove exported user files as well, delete: rm -rf ~/Documents/TypeWhisper\ Recordings

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 Some features (Apple Translate, improved Settings UI) require macOS 15+. Apple Intelligence and SpeechAnalyzer require macOS 26+.

Gemma 4 Support TypeWhisper includes a bundled local Gemma 4 plugin powered by MLX for on-device prompt processing on Apple Silicon. In the current verified release path, Gemma 4 support is limited to the dense E2B 4-bit and E4B 4-bit variants; larger or unverified variants stay visible in the UI but remain disabled until they are validated end to end. Model Recommendations

RAM Recommended Models

< 8 GB Whisper Tiny, Whisper Base

8-16 GB Whisper Small, Whisper Large v3 Turbo, Parakeet TDT v3, Voxtral Mini 4B

16 GB

Build

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

Open in Xcode 16+: open TypeWhisper.xcodeproj

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

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

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). 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 "file=@recording.wav" \ -F "language=en"

curl -X POST http://localhost:8978/v1/transcribe \ -F "file=@recording.wav" \ -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, WhisperKit only). target_language - ISO 639-1 code for translation target language (e.g., es, fr). Uses Apple Translate. 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.

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", "ready": true } ] } History

Search history

Delete entry

List recognition terms

Merge terms, or set replace=true to replace all terms

Delete one term

List post-transcription corrections

Add or update one correction by original text

Delete one correction

List all workflow-backed rules

Toggle a workflow-backed rule on/off

Start dictation (returns session id)

Stop dictation (returns same session id)

Check whether dictation is currently recording

Fetch status/result for a specific dictation session

Start recorder with microphone and system audio

Stop the active API recorder session

Check whether the recorder is currently recording

Fetch status/result for a specific recorder session

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. Conflict and lookup behavior:

Starting while the recorder is already recording or finalizing 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.

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 transcribe file.wav # Transcribe an audio file 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

Examples

Transcribe with language and JSON output

Restrict auto-detection to a shortlist

Pipe audio from stdin

Use in a script

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

source