localflow 0.1.6

Push-to-talk voice dictation for macOS. Hold ⌘⌥, speak, release — text streams to your cursor.

LocalFlow

Push-to-talk, on your Mac. Hold a hotkey, speak, release — text streams to your cursor.

LocalFlow is a lightweight macOS menubar app that transcribes your voice locally. No cloud, no API keys, no subscriptions, no data leaving your machine — just fast, private dictation that works in any app.

---

Why LocalFlow

Most dictation tools either require a cloud subscription, only work inside a specific app, or send your audio to a remote server. LocalFlow runs entirely on-device, giving you:

• Privacy — audio never leaves your Mac
• Speed — streaming transcription starts appearing within ~300ms of releasing the key on M1
• Simplicity — one hotkey, works everywhere, no setup beyond install

---

Requirements

• macOS 13+, Intel or Apple Silicon
• Python 3.10–3.13 (Python 3.14 is not yet supported — pre-built wheels for some dependencies are unavailable)
• Homebrew

---

Installation

brew install portaudio
pip install localflow

That's it. LocalFlow detects your hardware and installs the right backend automatically:

Mac	Backend	Notes
Apple Silicon (M1/M2/M3/M4)	mlx-whisper	Fastest — runs natively via MLX
Intel	faster-whisper	CPU-optimized via CTranslate2

Permissions

LocalFlow needs three macOS permissions. Go to System Settings → Privacy & Security and grant:

Permission	Why
Microphone	To capture your voice
Accessibility	To paste transcribed text
Input Monitoring ⚠️	To detect the global ⌘⌥ hotkey

Input Monitoring is the most commonly missed permission. Without it, the hotkey silently does nothing. Add your terminal app (Terminal.app, iTerm2, etc.) under System Settings → Privacy & Security → Input Monitoring.

---

Usage

1. Launch the app

localflow

A microphone icon appears in your menubar.

2. Enable dictation

Click the menubar icon → flip the toggle ON.

3. Dictate anywhere

Hold ⌘ Command + ⌥ Option in any app, speak, then release. Text streams to your cursor as transcription progresses.

The toggle is OFF by default so the microphone is never opened until you choose to enable it.

---

Models

LocalFlow uses quantized Whisper models from Hugging Face. The model is downloaded on first use (~150MB for small) and cached locally — no network needed after that.

localflow                  # default: small
localflow --model medium   # more accurate, slightly slower
localflow --model large    # best accuracy
localflow --list-models    # show all options

Model	Speed (M1)	Accuracy
tiny	~100ms	Basic
base	~200ms	Decent
small	~300ms	Good (default)
medium	~800ms	Better
large	~2–3s	Best

You can also set the model via environment variable:

LOCALFLOW_MODEL=large localflow

---

How it works

1. Global hotkey — macOS NSEvent monitors for ⌘⌥ held simultaneously, across all apps
2. Audio capture — sounddevice records mic input at 16kHz mono
3. Streaming transcription — faster-whisper yields segments as it processes, so text starts appearing before the full audio is transcribed; mlx-whisper on Apple Silicon transcribes the whole clip in one fast batch (~300ms)
4. Text injection — each segment is copied to clipboard and pasted via osascript (⌘V simulation)

All processing is local. No audio is stored permanently — the temp WAV file is discarded after transcription.

---

Troubleshooting

Hotkey does nothing → Check Input Monitoring permission. This is almost always the cause.

No text appears after speaking → Check Accessibility permission so the app can simulate ⌘V.

Transcription is slow on first use → The model is being downloaded. Subsequent runs use the cached model.

App doesn't appear in Dock → That's intentional — LocalFlow lives in the menubar only.

---

License

MIT