A macOS menu bar app for real-time speech-to-text using MLX Whisper
Press a hotkey, speak, and the transcribed text is automatically pasted into the active input field.
- 🎙️ Menu Bar App — lives in the system tray, always accessible
- ⌨️ Hotkey Triggered — configurable keyboard shortcut (default: Option+Tab)
- 🔄 Push-to-Talk or Toggle Mode — hold the hotkey or press to start/stop
- 🔒 On-Device Transcription — runs locally via MLX Whisper, no cloud API needed
- 📋 Auto-Paste — transcribed text is automatically inserted into the focused input field
- 💬 Floating Bubble UI — visual feedback with waveform animation during recording
- 🌏 Multi-Language Support — optimized for Traditional Chinese with English code-switching
- ⚡ Auto-Setup — automatically creates Python venv and installs dependencies on first launch
┌─────────────────────────────────────────────────────────────┐
│ ⌥ Tab │
│ ────── │
│ │
│ 1. Press Option+Tab ──→ 🎙️ Recording starts │
│ ┌───────────────────┐ │
│ │ ● Recording... │ │
│ │ ≋≋≋≋≋≋≋≋≋≋≋≋≋≋ │ │
│ └───────────────────┘ │
│ │
│ 2. Speak ──→ 🔊 Audio captured locally │
│ │
│ 3. Release / Press ──→ ⚙️ MLX Whisper transcribes │
│ (on-device, no cloud) │
│ │
│ 4. Done ──→ 📋 Text auto-pasted to cursor │
│ (Cmd+V via CGEvent) │
└─────────────────────────────────────────────────────────────┘
- Download
WhisperEcho-v1.0.0.zipfrom Releases - Extract and move
WhisperEcho.appto/Applications - Launch WhisperEcho
# Install XcodeGen if not already installed
brew install xcodegen
# Clone the repository
git clone https://github.com/tsungtwu/whisper-echo.git
cd whisper-echo
# Build and install
make install| Command | Description |
|---|---|
make build |
Debug build |
make run |
Debug build + launch |
make release |
Release build + package zip to release/ |
make install |
Release build + reset permissions + copy to /Applications |
make clean |
Clean build artifacts |
make reset-permissions |
Reset app permissions only |
- Launch WhisperEcho — it appears in the menu bar
- Grant Microphone permission when prompted
- Grant Accessibility permission when prompted (required for auto-paste)
- Add WhisperEcho to Input Monitoring in System Settings > Privacy & Security (required for hotkey)
- The app will automatically create
~/.mlx-whisper-envand installmlx-whisper - Wait for the model to download (first time only)
Note: When updating to a new build,
make installautomatically resets permissions to avoid stale entries. You will need to re-grant permissions on first launch after update.
- Click the menu bar icon to see status and settings
- Press the hotkey (default: Option+Tab) to start recording
- Speak — the floating bubble shows a waveform animation
- Release (push-to-talk) or press again (toggle) to stop
- Text is transcribed and automatically pasted into the active input field
| Setting | Options | Default |
|---|---|---|
| Language | English, Traditional Chinese, Japanese, Korean, ... | Traditional Chinese |
| Model | whisper-large-v3-turbo, large-v3, medium, small, base, tiny | large-v3-turbo |
| Mode | Push-to-talk, Toggle | Toggle |
| Hotkey | Any modifier + key combo | Option+Tab |
| Launch at Login | On/Off | Off |
WhisperEcho/
├── WhisperEchoApp.swift # App entry point (MenuBarExtra)
├── AppCoordinator.swift # Central orchestrator
├── AppState.swift # Observable state machine
├── Audio/
│ ├── AudioRecorder.swift # AVAudioEngine recording
│ └── AudioLevelMonitor.swift # Audio level tracking
├── Transcription/
│ ├── PythonBridge.swift # Python venv setup & PythonKit init
│ ├── PythonThread.swift # Dedicated thread for Python GIL
│ └── WhisperEngine.swift # MLX Whisper transcription
├── Hotkey/
│ └── HotkeyManager.swift # CGEvent tap for global hotkey
├── UI/
│ ├── MenuBarView.swift # Menu bar dropdown UI
│ ├── BubbleWindow.swift # Floating bubble window
│ ├── BubbleView.swift # Bubble content view
│ └── WaveformView.swift # Waveform animation
├── Output/
│ └── TextOutputManager.swift # Clipboard + Cmd+V paste
├── Settings/
│ └── Settings.swift # UserDefaults persistence
├── Permissions/
│ └── PermissionChecker.swift # Permission checks & openers
└── Resources/
├── Info.plist
├── WhisperEcho.entitlements
└── Assets.xcassets/
- Language: Swift 5.9
- UI: SwiftUI + MenuBarExtra
- Audio: AVAudioEngine (16kHz mono float32)
- Transcription: MLX Whisper via PythonKit
- Hotkey: CGEvent tap
- Build: XcodeGen + xcodebuild
- macOS 14 (Sonoma) or later
- Apple Silicon Mac (M1/M2/M3/M4)
- Python 3.9+ installed (Homebrew or system)
- Xcode 15+ and XcodeGen (for building from source)
MIT License - see LICENSE for details.
tsungtwu - @tsungtwu
Built with assistance from Claude Code 🤖
⭐ Star this repo if you find it useful!