OpenFlow

Current version: 1.3.045

OpenFlow is a desktop voice dictation app for Windows and macOS built with Electron on the UI layer and Faster-Whisper for local transcription.

It is designed for fast keyboard-free text capture, global shortcuts, a floating recording overlay, local model execution with on-demand downloads, and optional cloud transcription through OpenRouter.

Highlights

• Local transcription powered by Faster-Whisper
• Optional cloud transcription through OpenRouter speech-to-text models
• Electron desktop UI with history, diagnostics, settings, and dictionary rules
• Global hold-to-dictate shortcut, hands-free mode, and a paste-last shortcut
• Floating overlay with live activity feedback, drag positioning, opacity, scale, and dynamic-size controls
• On-demand Whisper model downloads stored in the user data directory
• Model timing stats, usage stats, searchable local history, and configurable history retention
• Dictionary rules for automatic phrase replacement or removal in final text
• Sound feedback, launch-at-login, and optional audio ducking while dictating
• In-app update checking and installation for packaged builds
• Separate Python workers for transcription and hotkey handling

Platforms

• Windows
• macOS

Platform Status

• Windows is the primary tested platform.
• macOS support exists in the codebase and CI packaging flow, but it has not been fully verified on a real Mac.
• The maintainer does not currently have access to macOS hardware, so treat macOS support as best effort until it is confirmed by external testing.

Stack

• Electron
• Node.js
• Python 3.12
• Faster-Whisper
• OpenRouter API for optional cloud transcription
• PyInstaller

Setup

1. Install Node.js 20+ and Python 3.12.
2. Create a virtual environment: python -m venv .venv on Windows or python3 -m venv .venv on macOS.
3. Install Python dependencies: .venv\Scripts\python.exe -m pip install -r python\requirements.txt on Windows or ./.venv/bin/python -m pip install -r python/requirements.txt on macOS.
4. Install Node dependencies: npm ci.
5. Copy .env.example to .env.
6. Start the app with npm start.

Environment

Create a local .env file by copying .env.example.

Recommended starting point:

WHISPER_MODEL=small
WHISPER_DEVICE=auto
WHISPER_COMPUTE_TYPE=
FLOW_HOTKEY=
FLOW_PASTE_LAST_HOTKEY=
ALLOWED_LANGUAGES=en
INTERFACE_LANGUAGE=en

Variable reference:

• WHISPER_MODEL: default transcription model loaded at startup. Good default: small.
• WHISPER_DEVICE: auto, cpu, or cuda.
• WHISPER_COMPUTE_TYPE: optional override for Faster-Whisper compute mode. Leave empty unless you know you need a specific value.
• WHISPER_CPU_THREADS: optional CPU thread cap for local transcription.
• FLOW_HOTKEY: optional custom dictation shortcut. Leave empty to use the platform default.
• FLOW_PASTE_LAST_HOTKEY: optional custom shortcut for pasting the latest transcription.
• ALLOWED_LANGUAGES: comma-separated detection languages such as en or en,pt.
• INTERFACE_LANGUAGE: app UI language. Default is en.
• PYTHON_BIN: optional development override for the Python executable path.
• WHISPER_MODEL_DIR: optional custom directory for downloaded Whisper models.

If you do not need custom behavior, copy the example file and keep almost everything as-is.

Cloud transcription is configured inside the app settings by saving an OpenRouter API key. The key is stored with Electron safe storage when available, and cloud mode requires accepting the in-app privacy notice before audio is sent to OpenRouter and the selected provider.

Available Scripts

• npm start: run the Electron app in development mode
• npm run check: syntax-check the tracked JavaScript files
• npm run build:python: package the Python workers with PyInstaller
• npm run dist:win: build the Windows desktop package
• npm run dist:mac: build the macOS package for the current architecture
• npm run dist:mac:x64: build the macOS Intel package
• npm run dist:mac:arm64: build the macOS Apple Silicon package
• npm run publish:mac:x64: build and publish macOS Intel update artifacts
• npm run publish:mac:arm64: build and publish macOS Apple Silicon update artifacts

Repository Layout

• src/main: Electron main process, app state, worker orchestration, tray, shortcuts
• src/renderer: desktop UI, overlay UI, styles, translations
• python: transcription and hotkey worker code
• scripts: build and platform helper scripts
• .github/workflows: CI packaging workflows for Windows and macOS

Build Notes

Packaging instructions and output details are documented in BUILDING.md.

Privacy

By default, OpenFlow runs transcription locally on the user machine. Whisper models are downloaded when needed and then cached in the app's user data directory.

If cloud transcription is enabled, recorded audio is sent to OpenRouter and the selected speech-to-text provider. Failed cloud recordings can be saved locally for retrying without recording again.

License

This repository is source-available under the custom license in LICENSE. You may view, download, use, and modify the code, but you may not sell or resell OpenFlow or substantial portions of it.