FlowDictation

A lightweight macOS menu bar app for voice-to-text dictation powered by Groq's Whisper API. Hold a hotkey, speak, release — your words are transcribed and pasted at your cursor instantly.

Features

• Hold-to-dictate — Hold your hotkey to record, release to transcribe
• Instant paste — Transcribed text is automatically inserted at your cursor position
• Custom hotkeys — Use preset keys (Option, Control, Fn) or set any custom key combination
• Menu bar app — Lives in the menu bar, no dock icon clutter
• Fast transcription — Powered by Groq's Whisper Large V3 Turbo (free tier available)
• Sound feedback — Adjustable audio cues for recording start, stop, and completion
• Clipboard fallback — Works with or without Accessibility permission
• Zero dependencies — Pure Swift, no external packages

Requirements

• macOS 13.0 or later
• Free Groq API key

Installation

Quick Install (Recommended)

Open Terminal and paste:

curl -fsSL https://raw.githubusercontent.com/joymadhu49/FlowDictation/main/scripts/install.sh | bash

This downloads, installs to Applications, and launches automatically. No Gatekeeper issues.

Download DMG

1. Download FlowDictation.dmg from Releases
2. Open the DMG, drag FlowDictation to Applications
3. Go to Applications in Finder
4. Right-click FlowDictation > click Open
5. Click "Open" on the dialog that appears
6. If still blocked: go to System Settings > Privacy & Security > scroll down > click "Open Anyway"

Why the extra steps? macOS blocks apps downloaded from the internet that aren't notarized by Apple. Right-click > Open bypasses this. Alternatively, run xattr -cr /Applications/FlowDictation.app in Terminal.

Homebrew

brew tap joymadhu49/tap
brew install --cask flowdictation

Build from Source

git clone https://github.com/joymadhu49/FlowDictation.git
cd FlowDictation
bash scripts/build-app.sh
open build/FlowDictation.app

Setup

1. Launch the app — a microphone icon appears in the menu bar
2. Set API key — Click the mic icon, paste your Groq API key in the field
3. Grant permissions when prompted:
   • Microphone — for audio recording
   • Accessibility — for global hotkeys and auto-paste

Usage

1. Place your cursor where you want text inserted
2. Hold your configured hotkey (default: Right Option)
3. Speak clearly
4. Release the hotkey — text is transcribed and pasted

Hotkey Options

Preset	Key
Option	Either Option key
Right Option	Right Option key only (default)
Control	Control key
Fn	Function key
Custom	Any key + modifier (e.g. ⌘⇧D)

Set your hotkey in Settings > General > Hotkey.

Project Structure

FlowDictation/
├── Package.swift
├── Sources/FlowDictation/
│   ├── FlowDictationApp.swift          # App entry point
│   ├── AppDelegate.swift               # Menu bar setup
│   ├── Models/
│   │   └── DictationState.swift        # State & hotkey models
│   ├── Services/
│   │   ├── AudioRecorder.swift         # WAV recording (16kHz mono)
│   │   ├── GroqAPIClient.swift         # Whisper API client
│   │   ├── GlobalHotkeyManager.swift   # Global hotkey monitoring
│   │   ├── DictationManager.swift      # Core orchestrator
│   │   ├── TextInserter.swift          # Clipboard + paste simulation
│   │   └── SoundFeedback.swift         # Audio feedback
│   ├── Views/
│   │   ├── MenuBarView.swift           # Popover UI
│   │   └── SettingsView.swift          # Settings window
│   └── Resources/
│       ├── Info.plist
│       ├── AppIcon.icns
│       └── FlowDictation.entitlements
└── scripts/
    └── build-app.sh                    # Build .app bundle + DMG

How It Works

1. Audio is recorded as 16kHz mono WAV (optimized for Whisper)
2. Sent to Groq's whisper-large-v3-turbo model via multipart upload
3. Transcribed text is placed on the clipboard
4. Cmd+V is simulated via System Events to paste at the cursor
5. Original clipboard contents are restored after 1 second

License

MIT License — see LICENSE for details.