FlowVoice

Local voice dictation for Windows powered by faster-whisper on CPU.

Transcribes speech on-device and types directly into the focused window without cloud services, user accounts, or telemetry.

Note

FlowVoice runs offline. Network access is only required during initial setup to download the Whisper model.

---

Overview

FlowVoice provides a floating pill overlay and a global F8 hotkey for voice dictation on Windows. Audio records at your microphone's native sample rate, filters through polyphase FIR resampling and RMS voice activity detection, and transcribes locally using a quantized Whisper model on CPU. The resulting text is typed into whichever window has focus without moving your cursor.

hold F8 -> speak -> release -> text is typed into the active window

---

Highlights

Feature	Description
Floating overlay	Transparent pill with an audio-level waveform floating over your work.
Model precision	74M-parameter Whisper base.en model quantized to INT8 running locally on CPU.
Native capture	Records at hardware sample rates (44.1 or 48 kHz) to prevent driver-level aliasing.
FIR resampling	scipy.signal.resample_poly with a bandlimited Kaiser window for 16 kHz conversion.
Silence filtering	Adaptive RMS voice activity detection trims silence and background noise before inference.
Decoding controls	Beam search (beam_size=5), repetition penalties, and n-gram restrictions to prevent loops.
Hotkey modes	Hold F8 to speak (push-to-talk), or tap once to start and tap again to stop.
Focus retention	Uses showInactive() and focusable:false to leave cursor position untouched.

---

Architecture

flowchart LR
    MIC["Microphone"] --> ENG["Python FlowEngine<br/>engine/server.py"]
    HK["Global Hotkey F8"] --> ENG
    ENG --> PRE["Audio Preprocessor<br/>polyphase FIR · RMS VAD"]
    PRE --> WH["faster-whisper<br/>base.en · INT8"]
    WH --> INJ["Keystroke Injector<br/>pyperclip + pynput"]
    INJ --> APP["Active App<br/>Notepad · Chrome · VS Code"]
    ENG <-->|WebSocket · 127.0.0.1:48123| UI["Electron Floating Overlay"]

Loading

Component	Role
Electron app	Floating overlay and dashboard; spawns and monitors the Python engine process.
Python FlowEngine	Runs a local WebSocket server on 127.0.0.1:48123 for UI synchronization.
Preprocessor	Captures audio, applies polyphase FIR resampling, and trims silence via RMS VAD.
Whisper	Runs faster-whisper (CTranslate2, INT8) inference on CPU.
Injector	Types the transcribed string into the active window via clipboard and keystrokes.

---

Tech stack

Layer	Technology
Desktop shell	Electron 44
Speech recognition	faster-whisper (CTranslate2, INT8)
Audio recording	sounddevice / PortAudio
Signal processing	NumPy, SciPy (polyphase FIR)
Hotkeys and typing	pynput, pyperclip, ctypes Win32 API
IPC	WebSocket (ws to websockets)
Data storage	Local JSON files

---

Quick start

Requirements

• Windows 10 or 11
• Python 3.9+ with pip
• Node.js 18+
• Working microphone
• Internet connection for initial Whisper model download

1. Clone and install

git clone https://github.com/anesdevv/flow-voice.git
cd flow-voice

# Install Electron dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

2. Run the application

npm start

This launches the Electron overlay and starts the background Python engine (python engine/server.py).

To run the speech engine standalone:

npm run engine
# or
python engine/server.py

Command reference

Command	Description
npm start	Launch the full application (overlay, dashboard, and engine).
npm run engine	Start the Python speech engine standalone.
python engine/server.py	Run the Python engine script directly.

---

Usage

1. Focus any text field in Notepad, a web browser, or your editor.
2. Hold F8 while speaking and release, or tap F8 once, speak, and tap F8 again to finish.
3. Your speech transcribes locally on CPU and types directly into the active field.

Spoken punctuation commands

Voice command	Result
"period" / "full stop"	.
"comma"	,
"question mark"	?
"exclamation point"	!
"new line" / "next line"	Line break
"press enter" / "hit enter"	Enter key

---

Project structure

flow-voice/
├── app/                          # Electron desktop app
│   ├── main.js                   # Main process: spawns engine, manages windows
│   ├── preload.js                # Secure IPC bridge
│   ├── overlay.html/css/js       # Floating pill overlay
│   ├── dashboard.html/css/js     # History, notes, dictionary, settings
│   └── data_store.js             # Local JSON file storage
├── engine/                       # Python speech engine
│   ├── server.py                 # WebSocket server (127.0.0.1:48123)
│   ├── whisper_engine.py         # faster-whisper model and audio recording
│   ├── audio_preprocessor.py     # Polyphase FIR resampling and RMS VAD
│   ├── hotkey.py                 # Global F8 hotkey listener (pynput)
│   └── injector.py               # Text injection into active window
├── data/                         # Local user storage (git-ignored)
│   └── *.example.json            # Default data templates
├── package.json
├── requirements.txt              # Python speech engine dependencies
├── LICENSE
└── README.md

Files under data/ store local settings, notes, and dictation history. They are git-ignored. The repository provides data/*.example.json templates that the application copies on first launch.

---

Privacy

• Audio transcription runs entirely on your CPU. No audio or text leaves your machine.
• No user accounts or authentication tokens required.
• No telemetry or analytics tracking.
• Dictation history and settings remain in local JSON files.
• The only outbound network connection is the initial Whisper model download from Hugging Face.

---

License

Released under the ISC License. See LICENSE for details.