FreeFlow

Local voice dictation for Fedora. Press a shortcut, speak, and FreeFlow transcribes, cleans, copies, and pastes your words into the focused application—all on your computer.

FreeFlow uses whisper.cpp and an open Whisper model. It has no accounts, subscriptions, API keys, analytics, or usage limits.

Website · Latest release · Report a bug

Why FreeFlow

• Private by design — audio and transcription stay on your computer.
• Works anywhere — dictate into browsers, editors, chat apps, and other text fields.
• Wayland ready — supports automatic insertion on KDE Wayland through a private ydotool socket.
• Useful defaults — tuned for Indian English, with custom vocabulary support for names and specialist terms.
• Small and inspectable — a focused Bash and Python codebase with no application runtime dependencies.

Requirements

FreeFlow currently targets Fedora KDE on Wayland or X11. Installation requires:

• a microphone;
• approximately 1 GB of free disk space for the engine, model, and build files;
• an internet connection during installation;
• sudo access for the recommended system integration.

Install

git clone https://github.com/GP-commits/FreeFlow.git
cd FreeFlow
./install-fedora.sh

The installer installs the required Fedora packages, builds whisper.cpp, downloads the multilingual large-v3-turbo-q5_0 model (approximately 547 MiB), installs FreeFlow under ~/.local/share/freeflow, and configures Meta+Alt+Space as the KDE shortcut.

Log out and back in once after the first install. Place the cursor in a text field, press Meta+Alt+Space, speak, then press the shortcut again to transcribe.

To avoid system changes, use ./install-fedora.sh --user-only. Required packages must already be installed, and dictation will copy to the clipboard until ydotool is configured separately.

Usage

Open FreeFlow Voice Dictation from the application menu for a visible controller, or use the command line:

freeflow toggle                  Open or raise the controller
freeflow record-toggle           Start or stop recording without the UI
freeflow start                   Begin recording
freeflow stop                    Transcribe and paste
freeflow cancel                  Discard the active recording
freeflow status                  Print the current state
freeflow transcribe audio.wav    Transcribe an existing WAV file

Recordings stop automatically after two minutes by default. The text is always copied to the clipboard. If automatic insertion is unavailable, FreeFlow sends a notification so you can paste manually.

Configuration

FreeFlow creates ~/.config/freeflow/config on first run. The defaults are documented in config.example.

FREEFLOW_LANGUAGE=en
FREEFLOW_MODEL=large-v3-turbo-q5_0
FREEFLOW_PASTE=true
FREEFLOW_CLEANUP=true
FREEFLOW_ENTER=false
FREEFLOW_THREADS=6
FREEFLOW_AUDIO_DEVICE=default
FREEFLOW_MAX_SECONDS=120

Set FREEFLOW_LANGUAGE=auto for multilingual dictation. If you change the model, download the matching model into ~/.local/share/freeflow/models/ with the downloader included in whisper.cpp.

Add names, abbreviations, places, and domain-specific language to ~/.config/freeflow/vocabulary.txt, one term per line. FreeFlow supplies these terms to Whisper as an initial prompt.

How it works

Microphone → 16 kHz WAV → whisper.cpp → offline cleanup → clipboard → focused app

The recorder captures mono audio with ALSA. whisper.cpp performs local inference, and a conservative cleanup pass removes common hesitation fillers and converts spoken punctuation. On Wayland, ydotool inserts the result through a user-restricted virtual keyboard socket.

Privacy and security

FreeFlow contains no telemetry or network calls during normal use. Temporary recordings are removed after successful transcription. The installer accesses the network only to fetch whisper.cpp and the selected model.

The installer builds third-party code and configures a system input service. Review install-fedora.sh and setup-paste.sh if you operate in a sensitive environment. Please report vulnerabilities privately as described in SECURITY.md.

Development

python3 -m unittest discover -s tests -v
bash -n bin/freeflow install-fedora.sh setup-paste.sh uninstall.sh

Contributions are welcome. Read CONTRIBUTING.md, use the issue templates, and keep changes focused. The project follows the Contributor Covenant.

Uninstall

./uninstall.sh

This removes FreeFlow's installed application files and KDE shortcut. Fedora packages and ~/.config/freeflow are preserved.

License

FreeFlow is available under the MIT License.