Skip to content
ichen27Public

About

Open-source macOS dictation with self-hosted local Whisper

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

ClearFlow

Speak naturally. Keep your words on your own hardware.

ClearFlow is an open-source macOS dictation app with Dock and menu bar access. Press Option–Shift–Space, speak, and press again to transcribe into the selected text field. Run Whisper large-v3-turbo locally through MLX on your own Apple Silicon Mac. You can also use another Mac you control, or explicitly configure your own Cloudflare Workers AI Nova 3 service.

No account with ClearFlow, bundled hosted service, or automatic cloud fallback. Independent project; not affiliated with Wispr.

ClearFlow app with synthetic sample dictation

Demo

ClearFlow UI walkthrough: select a field, speak, transcribe, insert

The walkthrough renders the app’s actual recording-bar component with synthetic text and waveform data. It illustrates the interaction; it is not a recording of live transcription or a latency benchmark. The screenshot uses sample history only. Reproduce these visuals.

Run it yourself — local Whisper

You need an Apple Silicon Mac (M1 or newer), macOS 14+, Python 3.12, and several GB of free disk space for the model and dependencies. Source builds need Xcode 16+ or compatible Command Line Tools with Swift 6. The native app and bundled MLX backend do not currently support Windows or Linux; other compatible backends may be added separately.

1. Get the app and source

Download ClearFlow-macOS-arm64.zip from Releases, extract it and move ClearFlow.app to Applications. Download the matching source archive, or clone this repository. Open a terminal in the source directory.

Open Applications → ClearFlow. To keep it in your Dock, right-click its Dock icon and choose Options → Keep in Dock. Clicking the Dock icon reopens the main window. Closing the window leaves the dictation shortcut running; use ClearFlow → Quit ClearFlow (Command–Q) to quit.

ClearFlow app icon

Editable icon source and reproduction instructions.

Alternatively, build it yourself:

scripts/build-app.sh

This creates dist/ClearFlow.app. Builds are ad-hoc signed, not notarized. macOS may require explicit approval in System Settings → Privacy & Security. Review/build the source if preferred; do not disable Gatekeeper. The downloadable app contains no model or access credentials.

2. Install and start Whisper

python3.12 local-stt/setup.py
python3.12 local-stt/run.py

Setup installs pinned Python dependencies and downloads the pinned open-weight model from Hugging Face. It creates a unique token in your private runtime directory. The service then runs on http://127.0.0.1:8768 in offline model mode. Leave this terminal running; cold startup can take a moment.

In another terminal:

curl --fail http://127.0.0.1:8768/health
python3.12 local-stt/run.py --configure-app /Applications/ClearFlow.app
# For a source build, use --configure-app dist/ClearFlow.app instead.

The configuration command sends the token directly into macOS Keychain without displaying it or putting it in command-line arguments. Run it from your logged-in macOS desktop terminal so Keychain is available. Restart ClearFlow after configuring it. No Cloudflare account or Tailscale installation is needed for same-Mac use.

Change the shortcut

In Settings → General, click the shortcut, then press your new key combination. It saves immediately and survives a restart; no separate Apply or Save is required. Press Escape, click elsewhere, or leave the app to cancel. Tap Fn/Globe alone, or include Control, Option, or Command with a letter, number, Space, or F-key. Fn toggles on release and ignores combinations such as Fn–arrow. For Fn, enable ClearFlow’s Accessibility access and set macOS Keyboard → Press 🌐 key to → Do Nothing; disable competing Fn shortcuts in other dictation apps. Fn monitoring inspects modifier/key state only, never typed characters. If permission is missing, Fn is saved but stays inactive until you enable access and refresh permission status. Key names refer to US keyboard positions. If macOS reports a conflict, try another combination or cancel to restore the previous shortcut. Avoid combinations already used by your editor or system; some app-local shortcuts cannot be detected. Press Option–Shift–Space in the recorder to restore the default. Finish or cancel active dictation before editing.

3. Dictate

  1. Open ClearFlow. In Settings → General, allow Microphone and Accessibility through the normal macOS prompts.
  2. Select an editable field in another app. Press Option–Shift–Space to start; the compact meter follows microphone input.
  3. Speak, then press the shortcut again. Keep the selected field and cursor unchanged while transcription runs.
  4. If insertion cannot be verified or the destination changed, ClearFlow keeps the transcript on the clipboard for manual paste. Check the app’s status for details.

There is no elapsed-time cutoff: recording continues until you finish or cancel. After you finish, longer recordings are transcribed sequentially in parts of at most four minutes and combined into one result. Nothing is uploaded or inserted while you are recording. A word spanning a part boundary may be less accurate. Device interruptions or disk errors can still stop capture. A persistent warning appears and ClearFlow attempts to transcribe the available audio into Recent Dictations without pasting at a stale cursor. Low disk space triggers an advance warning; a sudden hardware failure cannot always be predicted. Quitting during capture or transcription asks for confirmation and retains audio.

Transcripts are saved locally before insertion, with history enabled by default. Under Saved Recordings, choose Recover for unfinished audio from an interruption, failed request or previous launch, or Discard to delete it. Recovery never automatically pastes. Cancel with the overlay’s × while recording to discard that recording; cancelling while transcribing pauses delivery and keeps the audio. Damaged or unfinalized audio after a crash may not be transcribable, but is retained for inspection or explicit discard.

Full local setup, custom storage, startup at login, remote Mac and troubleshooting.

Optional: your own Cloudflare service

Deploy the supplied Worker in your own account, generate your own secret, and enter its HTTPS endpoint/token in Settings → Transcription. See Worker setup. This uses Deepgram Nova 3 on Cloudflare Workers AI and sends audio to Cloudflare; usage charges may apply. There is no preconfigured hosted endpoint.

Privacy

  • The only bundled endpoint is loopback. Audio and vocabulary go only to the address you explicitly configure. No automatic provider fallback.
  • Local Whisper holds request audio in memory and does not log audio or transcripts. Setup downloads dependencies/model weights; runtime uses the local model with Hugging Face offline mode.
  • Audio is stored in ~/Library/Application Support/ClearFlow/Recordings with private file permissions. It is deleted after successful transcription (and history persistence when enabled) or explicit discard. Failed, interrupted or paused requests retain audio across new recordings and app restarts. Review or delete these files under Saved Recordings; no automatic expiry. Existing temporary files from older versions are not imported.
  • Field content is read locally to guard insertion and is not uploaded. Known secure fields are rejected.
  • Transcript history is saved on this Mac by default, without automatic pruning, in ~/Library/Application Support/ClearFlow/history.json. Existing explicit history-off preferences are respected. Disable it in Settings → Data & privacy and save to remove stored history; ordinary completed dictations then stay in memory only. Interrupted audio remains recoverable until discarded. Clear recent history removes transcripts, not unfinished audio. Clipboard fallback leaves text available until replaced.
  • Your endpoint is stored in macOS preferences; the token is stored in Keychain. Keep credentials, recordings, personal endpoints and runtime data out of Git.

Development

scripts/test-native.sh
scripts/test-shortcut-registration.sh
scripts/build-app.sh
python3 -m unittest discover -s local-stt -v
python3 scripts/check-distribution.py
cd worker
npm ci
npm test
npm run typecheck
npm run build

CI validates native compilation/core checks, local API/setup tests, Worker tests/types/dry-run and distribution checks. Hardware inference, permissions and insertion across every editor are not proven by CI. Contributor workflow.

The app currently transcribes after recording stops. Streaming partials, generative rewriting, correction learning and cross-device history sync are not implemented. The local backend uses MLX and requires Apple Silicon.

License

MIT. Third-party dependencies and model weights retain their own licenses; the model is downloaded separately. No proprietary Wispr code or assets are included.

About

Open-source macOS dictation with self-hosted local Whisper

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages