WhisperSwift

A native macOS menu bar application for lightning-fast speech-to-text transcription using the Groq API. Hold a hotkey, speak, release—your words instantly appear in any text field.

Features

Push-to-Talk Dictation

• Three hotkey options: Fn/Globe key, Right Option, or Right Control
• System-wide operation: Works in any application with text input
• Zero-click workflow: Hold to record, release to transcribe and insert

High-Quality Transcription

• Powered by Groq: Uses Whisper Large v3 Turbo for accurate, near-instant transcription
• Blazing fast: Groq's LPU inference runs Whisper at 220x realtime speed — a 10-second recording transcribes in ~45ms
• Multi-language support: Configure any language code supported by Whisper
• Smart cleanup: AI-powered cleanup removes filler words, false starts, and verbal stumbles while preserving your exact wording
• Automatic list formatting: Spoken ordinals ("first", "second", "erstens", "zweitens") are converted to proper numbered lists

App-Aware Formatting

WhisperSwift automatically adapts text formatting based on the active application:

• Email clients (Mail, Outlook, Spark, Gmail, etc.) — Proper email body formatting with paragraph structure and signature handling
• Chat apps (Slack, Discord, WhatsApp, Teams, Telegram, etc.) — Compact message formatting without unnecessary line breaks
• Developer tools (VS Code, JetBrains IDEs, Obsidian, Notion, etc.) — Markdown-compatible formatting with proper lists
• Document apps (Pages, Word, Notes, etc.) — Clean prose with readable paragraphs
• Web app detection — Recognizes web-based services (Gmail, GitHub, Linear, etc.) running in browsers

Intelligent Context Awareness

• Filename recognition: Automatically detects filenames from your active window or document
• Spoken-to-written normalization: Converts "context service dot swift" → ContextService.swift
• CamelCase and extension handling: Understands various file naming conventions

Visual Feedback

• Animated recording indicator: A floating pill with real-time audio waveform visualization
• Menu bar status: Clear visual states for idle, recording, and processing
• Smooth transitions: Elegant animations between recording and processing states

Smart Text Insertion

• Accessibility API integration: Direct text insertion at cursor position (preferred method)
• Intelligent fallback: Automatic clipboard-based insertion for apps that need it
• Application awareness: Maintains a blacklist of apps requiring special handling (VS Code, browsers, etc.)
• No-target detection: When no text field is focused, transcription is saved to clipboard with visual notification
• Manual paste shortcut: Use ⌘⌃V (Cmd+Ctrl+V) to insert the last transcription anywhere

How It Works

1. Hold hotkey (Fn/Option/Control)
       ↓
2. Speak your text
       ↓
3. Release hotkey
       ↓
4. Audio is processed (normalized, silence-trimmed)
       ↓
5. Sent to Groq API for transcription
       ↓
6. AI cleanup removes filler words, formats lists
       ↓
7. App-aware formatting adapts to active application
       ↓
8. Context service applies filename corrections
       ↓
9. Text inserted into focused application

Prerequisites

• macOS 13.0 or later (Apple Silicon optimized)
• A valid Groq API Key
• Internet connection

Installation

Option 1: Download Release

Download the latest .dmg from the Releases page.

Option 2: Build from Source

# Clone the repository
git clone https://github.com/realZachi/WhisperSwift.git
cd WhisperSwift

# Open in Xcode
open whisperswift.xcodeproj

# Or build from command line
xcodebuild -project whisperswift.xcodeproj -scheme whisperswift -configuration Release build

Setup

1. Launch WhisperSwift — it will appear in your menu bar
2. Grant permissions when prompted:
   • Microphone: Required to capture your voice
   • Accessibility: Required for global hotkeys and direct text insertion
3. Configure your API key:
   • Click the menu bar icon → Settings
   • Enter your Groq API key
   • Alternative: Set the GROQ_API_KEY environment variable

Configuration Options

Setting	Default	Description
Hotkey	Fn/Globe	Push-to-talk trigger key
API Key	—	Your Groq API authentication key
Model	whisper-large-v3-turbo	Groq transcription model
Language	de	ISO language code for transcription
Play Sounds	On	Audio feedback during recording

Keyboard Shortcuts

Shortcut	Action
Hold Fn/Option/Control	Record audio (push-to-talk)
Double-tap Fn/Option/Control	Toggle hands-free recording mode
⌘⌃V (Cmd+Ctrl+V)	Paste last transcription (when no text field was focused)

Permissions

WhisperSwift requires two system permissions:

Microphone Access

Needed to capture your voice input. The app will prompt you on first launch.

Accessibility Access

Required for:

• Detecting global hotkey presses (especially the Fn key)
• Inserting text directly into applications via the Accessibility API
• Capturing window context for intelligent filename detection

Without Accessibility permission, the app falls back to clipboard-based text insertion.

Technical Details

Audio Processing Pipeline

• Sample rate: 16 kHz (optimized for speech recognition)
• Format: Mono PCM, converted to WAV for upload
• Normalization: Automatic gain adjustment using vDSP SIMD operations
• Silence detection: RMS-based trimming with 200ms speech padding

Architecture

• Swift Actors for thread-safe audio recording and API communication
• Dual hotkey detection: CGEvent tap (primary) with NSEvent fallback
• Concurrent processing: Async/await throughout for responsive UI

Text Insertion Strategy

1. Primary: Accessibility API (kAXSelectedTextAttribute or kAXValueAttribute)
2. Fallback: Clipboard + simulated Cmd+V for blacklisted apps
3. Clipboard preservation: Original clipboard content is restored after paste

Blacklisted Applications

These apps receive clipboard-based insertion due to custom text handling:

• VS Code and variants
• Chrome, Firefox, Safari, Arc, and other browsers
• Electron-based applications

Economics

Groq API pricing is approximately $0.04 per hour of audio processed ($4 per 100 hours). This is significantly more cost-effective than:

• Running local inference on consumer hardware
• Alternative cloud transcription APIs
• Subscription-based dictation services

Privacy

• Audio is sent to Groq's servers for transcription
• No audio is stored locally or by the app
• Your API key is stored in macOS UserDefaults (or can be set via environment variable)
• See Groq's Privacy Policy for their data handling practices

Troubleshooting

Text isn't being inserted

1. Check that Accessibility permission is granted (Settings → Permissions)
2. For VS Code/browsers, text is copied to clipboard—use Cmd+V to paste
3. If no text field is focused, a notification appears showing the transcription was saved. Use ⌘⌃V (Cmd+Ctrl+V) to paste it later

Hotkey not detected

1. Ensure Accessibility permission is enabled
2. Try a different hotkey option in Settings
3. Check that no other app is capturing the same key

Poor transcription quality

1. Verify your microphone is working correctly
2. Speak clearly and at a moderate pace
3. Try adjusting the language setting to match your speech

Logs

Debug logs are written to /tmp/whisperswift.log for troubleshooting.

License

MIT License — see LICENSE for details.

Credits

• Groq for the lightning-fast Whisper API (220x realtime inference)
• Moonshot AI for Kimi K2, used for transcript cleanup
• Apple for SwiftUI and the Accessibility framework
• Built with native Swift for optimal macOS integration