Metadata-Version: 2.4
Name: localflow
Version: 0.1.6
Summary: Push-to-talk voice dictation for macOS. Hold ⌘⌥, speak, release — text streams to your cursor.
License: MIT
Project-URL: Homepage, https://github.com/rishabhbhardwaj/localflow
Project-URL: Repository, https://github.com/rishabhbhardwaj/localflow
Project-URL: Issues, https://github.com/rishabhbhardwaj/localflow/issues
Keywords: macos,dictation,voice,whisper,menubar
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyobjc-core>=10.0
Requires-Dist: pyobjc-framework-Cocoa>=10.0
Requires-Dist: sounddevice>=0.4.6
Requires-Dist: soundfile>=0.12.1
Requires-Dist: numpy>=1.24
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: mlx-whisper>=0.3.0; platform_machine == "arm64"
Requires-Dist: faster-whisper>=1.0.0; platform_machine != "arm64"

<p align="center">
  <img src="https://res.cloudinary.com/djnojl5hn/image/upload/v1778316696/logo_sysnh5.png" width="96" alt="LocalFlow">
</p>

# 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](https://brew.sh)

---

## Installation

```bash
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**
```bash
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.

```bash
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:

```bash
LOCALFLOW_MODEL=large localflow
```

---

## How it works

1. **Global hotkey** — macOS `NSEvent` monitors for ⌘⌥ held simultaneously, across all apps
2. **Audio capture** — [sounddevice](https://python-sounddevice.readthedocs.io) 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
