Skip to main content

​
System Requirements

OpenWhispr requires macOS 10.15 (Catalina) or later.

​
Hardware Requirements

  • Processor: Intel x64 or Apple Silicon (arm64)
  • RAM: 4GB minimum (8GB recommended for local transcription)
  • Disk Space: 500MB for app + up to 3GB for local Whisper models

​
Software Requirements

  • Node.js 18+ (for building from source)
  • Xcode Command Line Tools (for Globe key support): Install with xcode-select --install

​
Installation Methods

​
Required Permissions

​
Microphone Access

OpenWhispr needs microphone access for voice recording.
1

Grant permission when prompted

macOS will automatically prompt for microphone access on first use.
2

Manual configuration

If you accidentally denied access:
  1. Open System Settings → Privacy & Security → Microphone
  2. Enable the checkbox next to OpenWhispr
  3. Restart the app
The app provides a button to open microphone settings directly from the Control Panel.

​
Accessibility Permissions (Required for Auto-Paste)

Accessibility permissions are required for automatic text pasting. Without this, text will only be copied to clipboard.
OpenWhispr uses AppleScript and CGEvent to simulate the Cmd+V keystroke after transcription.
1

Grant accessibility permission

  1. Open System Settings → Privacy & Security → Accessibility
  2. Click the lock icon and enter your password
  3. Click + to add OpenWhispr
  4. Enable the checkbox next to OpenWhispr
  5. Restart OpenWhispr
2

Troubleshooting stuck permissions

If you’ve rebuilt or reinstalled OpenWhispr and pasting still doesn’t work:
  1. Open System Settings → Privacy & Security → Accessibility
  2. Remove ALL old OpenWhispr entries (and any “Electron” entries)
  3. Click + and add the new OpenWhispr.app
  4. Enable the checkbox
  5. Restart OpenWhispr
This is common during development when rebuilding the app. macOS caches the old app signature.

​
macOS-Specific Features

​
Globe/Fn Key Support

OpenWhispr supports the Globe (Fn) key as a hardware-level dictation trigger on macOS.
This feature uses a native Swift binary (macos-globe-listener) that monitors the Globe key press. How it works:
  • The Globe key listener runs as a background process
  • Requires Xcode Command Line Tools to be installed
  • Set as default hotkey on macOS (can be changed in Settings)
  • Alternative hotkeys: Any Electron accelerator (e.g., Cmd+Shift+K)
Installation requirement: 
xcode-select --install

​
AppleScript-Based Clipboard Integration

OpenWhispr uses two methods for automatic pasting:
  1. CGEvent API (Primary method via macos-fast-paste binary)
    • Simulates Cmd+V using Core Graphics Events
    • Fastest and most reliable method
    • Requires accessibility permissions
  2. AppleScript (Fallback method)
    • Uses osascript to send System Events keystrokes
    • Command: tell application "System Events" to key code 9 using command down
    • Also requires accessibility permissions
import Cocoa
import Carbon

// Simulates Cmd+V using CGEvent
let vKeyDown = CGEvent(keyboardEventSource: nil, virtualKey: 0x09, keyDown: true)
let vKeyUp = CGEvent(keyboardEventSource: nil, virtualKey: 0x09, keyDown: false)
vKeyDown?.flags = .maskCommand
vKeyUp?.flags = .maskCommand
vKeyDown?.post(tap: .cghidEventTap)
vKeyUp?.post(tap: .cghidEventTap)

​
Clipboard Restore Behavior

OpenWhispr temporarily replaces your clipboard content to paste transcribed text, then automatically restores the original clipboard after 450ms.

​
Troubleshooting

Cause: Missing or stuck accessibility permissions.Solution:
  1. Check accessibility permissions in System Settings
  2. Remove old OpenWhispr entries
  3. Add the current app and enable permissions
  4. Restart OpenWhispr
Manual paste: Use Cmd+V if auto-paste fails.
Cause: Xcode Command Line Tools not installed.Solution:
xcode-select --install
Restart OpenWhispr after installation.
Cause: App is not signed with an Apple Developer certificate (common for personal builds).Solution:
  1. Right-click OpenWhispr.app
  2. Select Open
  3. Click Open in the security dialog
Official releases from GitHub are signed and notarized.
Solution:
  1. Open System Settings → Sound → Input
  2. Select the correct microphone
  3. Test the input level
  4. Restart OpenWhispr
The app provides a direct button to open sound settings.
Check disk space: Whisper models range from 75MB (tiny) to 3GB (large).Models location: ~/.cache/openwhispr/whisper-models/Manual cleanup:
rm -rf ~/.cache/openwhispr/whisper-models
Or use the in-app cleanup: Settings → General → Remove Downloaded Models
Solution: Change the hotkey in Settings → Hotkeys.Suggested alternatives:
  • Control+Alt
  • Command+Shift+Space
  • F8 or F9

​
Performance Optimization

​
Local Transcription Performance

Recommended model: base - Best balance of speed and accuracy (~142MB)
Model comparison:
  • tiny: ~75MB, fastest, lowest quality
  • base: ~142MB, recommended balance ⭐
  • small: ~466MB, better quality
  • medium: ~1.5GB, high quality
  • large: ~3GB, best quality
  • turbo: ~1.6GB, fast with good quality

​
Apple Silicon Optimization

OpenWhispr includes native arm64 binaries for:
  • whisper.cpp (speech-to-text)
  • llama.cpp server (local AI processing)
  • sherpa-onnx (NVIDIA Parakeet models)
  • macos-fast-paste (clipboard integration)
  • macos-globe-listener (Globe key detection)
Performance on Apple Silicon is significantly faster than Intel Macs for local transcription.

​
Uninstallation

1

Delete the app

Drag OpenWhispr.app from Applications to Trash.
2

Remove cached models (optional)

rm -rf ~/.cache/openwhispr
Or use Finder:
  1. Press Cmd+Shift+G
  2. Enter ~/.cache/openwhispr
  3. Delete the folder
3

Remove app data (optional)

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

​
Next Steps

Configure Settings

Set up API keys, choose models, and customize hotkeys

Choose Processing Method

Compare local vs cloud transcription options

Troubleshooting Guide

Solutions for common macOS issues

Keyboard Shortcuts

Master hotkeys and activation modes

Build docs developers (and LLMs) love

Get started for freeTalk to us