Voiceflow
Download
VoiceFlow documentationInstallation & permissionsQuickstartDictation modeAsk modeShortcutsCustom dictionaryHistory & statsSystem architectureAudio capture pipelineTranscription strategyAI processing & text injectionGlobal key listenerData model & storageIPC channelsConfigurationBuild & release
Introduction

VoiceFlow documentation

VoiceFlow is a macOS tray app that turns speech into clean, formatted text and pastes it into whatever app you are already using. Hold a key, talk, and the polished result lands at your cursor.

Platform

macOS 13+ · Apple silicon

Transcription

Groq · whisper-large-v3

Storage

100% local JSON

Install & grant permissionsDownload the DMG, add your Groq API key, and grant Microphone + Accessibility access.Understand the pipelineFollow audio from the microphone through transcription, AI polish, and auto-paste.

What VoiceFlow is

VoiceFlow is an open-source Electron app that lives in the macOS menu bar. Press a shortcut from anywhere, speak, and a floating overlay shows that you're recording. When you stop, the audio is transcribed by Groq's hosted Whisper model, optionally rewritten into clean written text by a language model, and pasted straight into the app you were already in.

There is no VoiceFlow account and no VoiceFlow server. Your transcript history, custom dictionary, and settings live in plain files on your Mac. The only network calls go directly from your machine to the Groq API using the key you provide.

This documentation follows the code

Everything here is written against the current source. Where the app's behavior differs from older READMEs or file names (for example the “realtime” modules that actually buffer audio), this documentation describes what the code does today.

Core capabilities

Speak into any app

Capture happens in a floating overlay and the result is pasted into the previously focused app via macOS Accessibility automation.

AI polish

Raw speech is optionally rewritten into structured, filler-free text — questions stay questions, lists become numbered lists.

Ask mode

Select text anywhere, speak an instruction, and VoiceFlow transforms the selection instead of dictating new text.

Global shortcuts

A native Rust key listener drives toggle and hold-to-talk shortcuts that work while you are in other apps.

Custom dictionary

Add proper nouns and jargon so the transcriber prefers the right spelling for names and technical terms.

Local history

Every transcription is saved as a JSON file you can browse, search, re-paste, export, or delete.

Two ways to use your voice

Every recording runs in one of two modes. The active mode is fixed at the moment recording starts, based on your defaultMode setting.

  • Dictation — your speech becomes text. With polish enabled it is rewritten into clean written form, then pasted at the cursor. This is the default mode.
  • Ask— you select text first, then speak an instruction (“make this more formal”, “translate to French”). VoiceFlow sends the selection plus your instruction to a language model and replaces the selection with the result.
Ask mode needs selected text to work on. If nothing is selected, VoiceFlow reports that Ask mode requires a selection.

How the pipeline works

From keypress to pasted text, a dictation runs through this sequence. Audio is buffered locally during recording and sent in a single request when you stop.

Shortcutnative key listener
CaptureAudioWorklet → PCM16
TranscribeGroq Whisper
Polishgpt-oss-120b
Pasteosascript ⌘V
Historylocal JSON
End-to-end dictation flow. Ask mode swaps the polish step for a text-transformation call against your selection.