VoiceFlow

Free, local push-to-talk transcription for Windows — the open-source alternative to Wispr Flow. Hold a hotkey, speak, release — transcribed text is injected directly into any active application. No cloud, no subscription, no audio ever leaving your machine.

---

Screenshots

VoiceFlow runs quietly in the system tray and surfaces a minimal overlay only while you're recording.

Recording overlay

While you hold Ctrl+Shift, the overlay appears at the bottom of your screen with a reactive waveform visualization and live streaming preview of the transcription:

Full-screen context

The overlay is non-intrusive — it floats above your active application so you can see what you're dictating into:

Live transcription preview

As you speak, partial transcription streams in real time so you can see what VoiceFlow is picking up:

After release — text injection

Once you release the hotkey, the finalized transcription is injected directly into whatever application has focus:

Idle state

When not recording, VoiceFlow sits quietly in the tray — no overlay, no distractions:

---

VoiceFlow vs. Wispr Flow

---

What is VoiceFlow?

VoiceFlow runs entirely on your machine using faster-whisper (Distil-Whisper Large v3.5 by default). There is no API call on the transcription path — audio goes in, text comes out locally, and is injected into whatever window you have focused.

It ships with a continual-learning system that adapts to your accent and vocabulary over time, a streaming preview that shows partial transcription while you speak, and a tray-first UI that stays out of the way when you're not using it.

---

Quick Start

Requirements

• Windows 10 or 11 (64-bit)
• 4 GB RAM minimum; 8 GB+ recommended for GPU mode
• NVIDIA GPU with CUDA 11.8+ for GPU acceleration (optional but recommended)

Install

Option A — Packaged EXE (recommended)

1. Download VoiceFlow-win64.exe from the latest release.
2. Run it. Windows may show a SmartScreen warning — click More info → Run anyway.
3. On first launch the setup wizard opens. Click Run Hardware Check, choose a profile, and click Save and Launch.

Option B — From source

git clone https://github.com/GrimFandango42/VoiceFlow.git
cd VoiceFlow
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
# Run from the repo root (not from src/)
python _app_entry.py

GPU users: use .venv-gpu with pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 before the editable install.

First use

1. The setup wizard opens on first launch. Run the hardware check to auto-select CPU or GPU mode.
2. Click Save and Launch.
3. Focus any text field (Notepad, VS Code, a browser input, anything).
4. Hold Ctrl+Shift, speak, then release.
5. Transcribed text appears at your cursor.

---

Features

• Hold-to-record with configurable hotkey (Ctrl+Shift default)
• Local inference — faster-whisper, no internet required after model download
• GPU acceleration — CUDA path for NVIDIA GPUs; automatic CPU fallback
• Streaming preview — partial transcription visible while speaking, with filler words (uh/um/er) stripped in real time and safe cleanup applied so the preview reads like final output; per-sentence continuity rather than a rolling word window
• Reactive waveform animation — spring physics with per-bar stiffness and damping, burst energy injected on speech onset, and sympathetic vibration between neighboring bars
• Continual learning — adapts to your accent and domain vocabulary over time
• Text injection — pastes directly into the active application
• Tray-first UI — stays out of the way; right-click tray for settings
• Three cleanup passes — light typo fix (on), safe second pass (on), heavy rewrite (opt-in)
• History & correction — review recent transcriptions, submit corrections from tray
• Cold-start elimination — model pre-warmed before first keypress
• 24/7 stability — command queue cap, idle-aware monitoring, and overlay focus hardening prevent drift during long sessions

---

Architecture Overview

voiceflow/
├── core/
│   ├── asr_engine.py        # faster-whisper inference, model tier selection
│   ├── audio_enhanced.py    # sounddevice capture, VAD, chunking
│   ├── streaming.py         # streaming partial results
│   ├── textproc.py          # cleanup passes, destination-aware formatting
│   ├── preloader.py         # background model pre-warming
│   └── config.py            # typed config dataclass
├── ui/
│   ├── cli_enhanced.py      # main entry point, hotkey listener, orchestration
│   ├── visual_indicators.py # overlay + dock UI (tkinter)
│   ├── tray.py              # system tray (pystray)
│   └── setup_wizard.py      # first-run wizard (tkinter)
├── ai/
│   ├── adaptive_memory.py   # continual learning, pattern extraction
│   ├── daily_learning.py    # nightly batch learning pass
│   └── course_corrector.py  # real-time correction pipeline
├── models/
│   └── tray_state.py        # shared state types between tray and orchestrator
└── platform/
    └── factory.py           # platform injection abstraction (Windows: pywin32)

The hotkey listener captures audio into a ring buffer, passes it through VAD, then calls the ASR engine. Text flows through the cleanup pipeline and is injected via the platform layer. The UI receives status updates over a thread-safe command queue.

---

Platform Support

---

Configuration

Most settings are available through the setup wizard (right-click tray → Setup & Defaults). Config is stored at %LOCALAPPDATA%\VoiceFlow\config.json.

Key settings:

---

Continual Learning

VoiceFlow observes the delta between raw transcripts and final text. Recurring corrections are promoted into adaptive replacement rules.

• Rules are stored locally in %LOCALAPPDATA%\VoiceFlow\adaptive_patterns.json
• Daily learning runs a nightly batch pass; reports land in %LOCALAPPDATA%\VoiceFlow\daily_learning_reports\
• Explicit corrections via the History panel rank higher than auto-inferred rules
• Add personal terminology in %LOCALAPPDATA%\VoiceFlow\engineering_terms.json

---

Contributing

1. Fork the repo and create a feature branch from main.
2. Set up the dev environment:

   pip install -e ".[dev]"
   

3. Run the test suite before and after your changes:

   pytest tests/ -x -q
   

4. Keep UI changes in visual_indicators.py; keep ASR changes in core/. Do not mix layers.
5. Test with the packaged bundle (dist\VoiceFlow\VoiceFlow.exe) for end-to-end validation.
6. Open a pull request against main with a description of what changed and why.

See CONTRIBUTING.md for the full guide.

---

License

MIT — see LICENSE.