🎤 Whisper Dictation for macOS

Free, offline, privacy-focused voice-to-text for macOS — No subscriptions, no cloud, no data leaving your machine.

A system-wide push-to-talk dictation tool that runs 100% locally on your Mac. Press a hotkey, speak, and your words appear as text wherever your cursor is. Powered by whisper.cpp with Apple Silicon GPU acceleration.

✨ Features

• 🔒 100% Private — All processing happens locally, no internet required
• ⚡ Fast — Transcribes in ~2-3 seconds on Apple Silicon
• 🎯 Accurate — Uses OpenAI's Whisper model (small.en)
• 🌍 System-wide — Works in any app (Notes, VS Code, Browser, etc.)
• 🆓 Free Forever — No subscriptions, no API costs
• 🔴 Visual Feedback — Pulsing indicator shows when recording

🖥️ Requirements

• macOS (optimized for Apple Silicon M1/M2/M3/M4)
• Homebrew installed (install here)
• ~500MB disk space for the Whisper model

🚀 Quick Install

# Clone the repository
git clone https://github.com/YOUR_USERNAME/whisper-dictation-macos.git
cd whisper-dictation-macos

# Run the installer
bash install.sh

The installer will:

1. Install dependencies (sox, cmake, Hammerspoon)
2. Build whisper.cpp with Metal GPU acceleration
3. Download the Whisper model (~466MB)
4. Set up Hammerspoon configuration

📖 Usage

1. Start Recording: Press Cmd + Shift + D
2. Speak: You'll see a pulsing red indicator 🔴
3. Stop & Transcribe: Press Cmd + Shift + D again
4. Done: Text is automatically pasted at your cursor!

🔐 Permissions Required

On first use, macOS will ask for:

• Microphone Access — To record your voice
• Accessibility Access — For Hammerspoon to use global hotkeys

Grant these in: System Settings → Privacy & Security

⚙️ Configuration

Change Hotkey

Edit ~/.hammerspoon/init.lua and modify the hotkey binding:

-- Default: Cmd+Shift+D
hs.hotkey.bind({"cmd", "shift"}, "D", function()
    dictation.toggle()
end)

-- Example: Change to Cmd+Shift+R
hs.hotkey.bind({"cmd", "shift"}, "R", function()
    dictation.toggle()
end)

Then reload Hammerspoon (click menubar icon → Reload Config).

Change Model

For faster (but less accurate) transcription, edit the model path in ~/.hammerspoon/init.lua:

-- Current: small.en (better accuracy, ~466MB)
dictation.modelPath = os.getenv("HOME") .. "/.local/whisper.cpp/models/ggml-small.en.bin"

-- Alternative: base.en (faster, ~142MB)
dictation.modelPath = os.getenv("HOME") .. "/.local/whisper.cpp/models/ggml-base.en.bin"

Download additional models:

cd ~/.local/whisper.cpp
./models/download-ggml-model.sh base.en    # Faster
./models/download-ggml-model.sh medium.en  # Best accuracy

🐛 Troubleshooting

Hotkey not working

1. Check Hammerspoon has Accessibility permissions
2. Click Hammerspoon menubar icon → Reload Config
3. Check Console.app for errors

No audio recorded

1. Grant Microphone permission to Hammerspoon
2. Test sox manually: sox -d -r 16000 -c 1 test.wav

Transcription slow

• Ensure you're on Apple Silicon (M1/M2/M3/M4)
• The first transcription may be slower (model loading)
• Try base.en model for faster results

🏗️ How It Works

┌─────────────────────────────────────────────────────────┐
│  1. Press Cmd+Shift+D                                   │
│  2. Hammerspoon starts sox recording                    │
│  3. Audio saved as WAV (16kHz, mono)                    │
│  4. Press Cmd+Shift+D again                             │
│  5. whisper.cpp transcribes using GPU                   │
│  6. Text copied to clipboard + auto-pasted              │
└─────────────────────────────────────────────────────────┘

📁 File Structure

~/.local/
├── whisper.cpp/           # Whisper engine
│   ├── build/bin/whisper-cli
│   └── models/ggml-small.en.bin
└── bin/
    └── dictate.sh         # Recording script

~/.hammerspoon/
└── init.lua               # Hotkey & UI configuration

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests

📄 License

MIT License — Free to use, modify, and distribute.

💖 Why This Exists

This project was created to provide a free alternative to paid dictation tools like:

• Wispr Flow ($10/month)
• Otter.ai ($16/month)
• Other subscription-based tools

Students, developers, and anyone should have access to great tools without paying monthly subscriptions. Everything runs locally on your machine — your voice data never leaves your computer.

⭐ Star This Repo

If this helped you, please give it a ⭐ to help others find it!

---

Made with ❤️ for the open source community