Skip to content

README.md

Latest commit

 

History

History
162 lines (123 loc) · 6.1 KB

README.md

File metadata and controls

162 lines (123 loc) · 6.1 KB
Raw

FreeFlow for Windows

Voice-to-text dictation for Windows. Hold a key to record, release to transcribe and paste.

This is a Python port of the macOS FreeFlow app, providing the same voice-to-text pipeline on Windows with additional features.

Installation

Step 1: Download the installer

Download FreeFlowSetup.exe from the Releases page.

Step 2: Run the installer

  1. Double-click FreeFlowSetup.exe
  2. If Windows SmartScreen appears, click More info > Run anyway (the app is open-source but not yet code-signed)
  3. Follow the installer prompts:
    • Choose an install location (default: C:\Program Files\FreeFlow)
    • Optionally check Create a desktop shortcut
    • Optionally check Launch FreeFlow when Windows starts
  4. Click Install, then Finish

Step 3: Get a Groq API key (free)

  1. Go to console.groq.com/keys
  2. Create a free account if you don't have one
  3. Click Create API Key and copy it

Step 4: First-run setup

  1. FreeFlow launches automatically after install (or open from Start Menu / desktop shortcut)
  2. A UAC prompt will appear — click Yes (required for global hotkey capture)
  3. You'll hear a ready chime and see a tray notification confirming the hotkey is active
  4. The setup wizard walks you through:
    • API Key — paste your Groq API key
    • Push-to-Talk Key — choose F6, Right Ctrl, or Scroll Lock (default: F6)
    • Microphone — select your preferred microphone
    • Custom Vocabulary — add names or terms you use often (optional)
  5. Click Get Started

Step 5: Start dictating

  1. Look for the FreeFlow microphone icon in your system tray (bottom-right of taskbar)
  2. Hold your push-to-talk key and speak
  3. Release the key — a preview window shows your transcription
  4. Text is auto-pasted at your cursor after a short countdown (or click to paste immediately)
  5. Right-click the tray icon for Settings or Quit

Uninstalling

Use Settings > Apps > FreeFlow > Uninstall or run the uninstaller from the Start Menu. The uninstaller will ask if you want to remove your settings and history as well.

Running from Source

Prerequisites

Quick start

cd windows
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python run.py

Or double-click start.bat — it creates the venv and installs dependencies automatically.

Features

  • Push-to-talk recording with configurable hotkey (F6, Right Ctrl, or Scroll Lock)
  • Context-aware transcription — captures active window and screen content for accurate spelling
  • Tone adaptation — adjusts writing style based on the active application
  • Transcription preview — review before pasting, with auto-paste countdown
  • Personal dictionary — auto-learns corrections and supports voice snippets
  • Sound effects — audio cues for recording start, stop, completion, and errors
  • Single instance — prevents duplicate tray icons with a helpful notification
  • Recording overlay — non-focusable, click-through visual feedback during recording

Configuration

Settings are stored at %APPDATA%\FreeFlow\settings.json.

Setting Options Default
Push-to-Talk Key F6, Right Ctrl, Scroll Lock F6
Microphone System Default or specific device System Default
Custom Vocabulary Comma/newline-separated terms (empty)

Access settings via right-click on the system tray icon > Settings.

Building the Installer

Prerequisites

One-click build

cd windows
build.bat

This will:

  1. Install PyInstaller and app dependencies
  2. Generate the app icon (resources/icon.ico)
  3. Clean previous build artifacts
  4. Build dist\FreeFlow\FreeFlow.exe via PyInstaller
  5. Build dist\FreeFlowSetup.exe via Inno Setup (if installed)

Manual steps

cd windows
pip install pyinstaller
pip install -r requirements.txt
python build_icon.py
pyinstaller build.spec --noconfirm
iscc installer.iss

Architecture

freeflow/
  main.py                    # System tray + pipeline orchestration
  config.py                  # JSON settings (%APPDATA%\FreeFlow)
  models.py                  # Data classes (HotkeyOption, PipelineHistoryItem)
  hotkey_manager.py          # Global push-to-talk (keyboard library)
  audio_recorder.py          # Recording (sounddevice + soundfile)
  transcription_service.py   # Groq Whisper API
  post_processing_service.py # Groq LLM post-processing
  context_service.py         # Window info + screenshot + LLM inference
  tone_detector.py           # Per-app writing tone detection
  personal_dictionary.py     # Auto-learn vocabulary + voice snippets
  text_output.py             # Clipboard + Ctrl+V paste
  recording_overlay.py       # Non-focusable recording feedback overlay
  transcription_preview.py   # Preview with auto-paste countdown
  sound_effects.py           # Programmatic audio cues
  history_store.py           # SQLite pipeline history
  tray_icons.py              # PIL-generated system tray icons
  setup_wizard.py            # First-run tkinter wizard
  settings_window.py         # Tkinter settings UI

Troubleshooting

Issue Fix
UAC prompt on every launch Expected — the keyboard library needs admin for global hotkeys
SmartScreen blocks the installer Click More info > Run anyway
Hotkey doesn't work Make sure you clicked Yes on the UAC prompt
"FreeFlow is already running" dialog Close the existing instance from the tray icon first
No sound devices listed Check that your microphone is connected and enabled in Windows Sound settings
Transcription is slow or fails Verify your Groq API key in Settings and check your internet connection
Multiple tray icons Restart the app — the single-instance guard now prevents this