FlowSuite

KO | EN

gitlite — search

#python #hacktoberfest #go #rust #deep-learning #linux #docker #nodejs #java #windows #security #ios #mcp #openai

(★ 11)

Local voice-to-text engine with 3 hotkeys: dictate prose, or speak Python/C++ that turns into real syntax. Runs fully offline on Windows/macOS/Linux, GPU optional. No cloud, no account, no telemetry.

FlowSuite Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# FlowSuite — one local voice engine, three hotkeys

Turn your voice into **prose** *and* **code**, entirely on your own machine.
Hold a hotkey, speak, release — the text appears at your cursor in **any** app
(browser code editor, VS Code, Word, terminal). No cloud, no account, no
telemetry, no data ever leaves your computer.

| Hold | Mode | What it does |
|------|------|--------------|
| **F4**  | prose  | Natural dictation — fillers stripped, capitalized |
| **F8**  | python | Spoken Python → real syntax (e.g. "for i in range n" → `for i in range(n):`) |
| **F9**  | cpp    | Spoken C++ → real syntax (e.g. "for i from 0 to n" → `for (int i = 0; i < n; i++) {`) |

Runs on **Windows, macOS, and Linux**. Uses your GPU if you have an NVIDIA one,
otherwise runs on the CPU — **no GPU is required.**

---

## Quick start

```bash
git clone https://github.com/The-AlphaWolf/FlowSuite.git
cd FlowSuite
pip install -r requirements.txt
python doctor.py           # verify mic, clipboard, hotkeys, GPU/CPU (recommended)
python flowsuite.py        # Windows;  use  python3 flowsuite.py  on macOS/Linux
```

> Run **`python doctor.py`** any time you hit trouble — it checks every
> dependency and permission and tells you exactly what to fix, per platform.

On first run it downloads the speech model (~460 MB for `small`) once, prints
`[ready]`, then listens. Hold **F8** in a code editor and say
"for i in range n". That's it.

> **Heads-up:** most systems need one small OS-level dependency first
> (PortAudio for the mic, and on Linux a clipboard tool). See your platform
> below.

---

## Requirements

- **Python 3.10 or newer**
- A microphone
- ~1–2 GB free disk for the model cache
- Optional: an **NVIDIA GPU** for faster transcription (see
  [GPU acceleration](#gpu-acceleration-optional)). Everything works on CPU
  without it.

The Python packages (installed by `pip install -r requirements.txt`):
`faster-whisper`, `sounddevice`, `numpy`, `pynput`, `pyperclip`, `pystray`,
`Pillow`.

---

## Install per platform

### Windows

```powershell
pip install -r requirements.txt
python flowsuite.py
```

- If global hotkeys don't fire inside an elevated app, run your terminal
  **as Administrator**.
- `sounddevice` ships PortAudio on Windows — nothing extra to install.

### macOS

```bash
brew install portaudio          # microphone backend for sounddevice
pip3 install -r requirements.txt
python3 flowsuite.py
```

- The **first time**, macOS will prompt for **Microphone** and **Accessibility**
  permission (Accessibility is needed to send the hotkey/paste). Grant both to
  your terminal app (or to `python3`) under
  **System Settings → Privacy & Security**.
- Apple-Silicon and Intel Macs run on the **CPU** (no NVIDIA CUDA on macOS).
  The `small` model is comfortably fast on Apple Silicon.

### Linux

```bash
# Debian/Ubuntu (use your distro's equivalents elsewhere)
sudo apt install portaudio19-dev xclip
pip3 install -r requirements.txt
python3 flowsuite.py
```

- **X11 sessions only.** The hotkey/paste backend (`pynput`) does not support
  Wayland. On recent GNOME/Fedora/Ubuntu, log into an "Ubuntu on Xorg" / X11
  session instead.
- `xclip` (or `xsel`) is required for clipboard paste — install one.
- If the hotkey doesn't register, add your user to the `input` group
  (`sudo usermod -aG input $USER`, then log out/in).

---

## GPU acceleration (optional)

FlowSuite auto-detects your hardware: `device: "auto"` in the config uses an
**NVIDIA GPU if one is present**, otherwise the CPU. You don't have to configure
anything.

To actually use an NVIDIA GPU you need the CUDA runtime libraries. The easiest
way is via pip wheels (no system CUDA install required):

```bash
pip install nvidia-cublas-cu12 nvidia-cudnn-cu12 nvidia-cuda-runtime-cu12
```

- **Windows:** FlowSuite adds these wheels' folders to the DLL search path
  automatically — nothing else to do.
- **Linux:** you may also need
  `export LD_LIBRARY_PATH=$(python3 -c "import os,nvidia;print(':'.join(os.path.join(p,'lib') for p in __import__('glob').glob(os.path.dirname(nvidia.__file__)+'/*')))")`
  before launching, or install your distro's CUDA/cuDNN packages.
- **macOS / no NVIDIA GPU / AMD / Intel:** ignore all of the above — FlowSuite
  runs on the CPU, which is plenty for short dictation.

Force a specific backend by editing `flowsuite_config.json`:
`"device": "cpu"` (+ `"compute_type": "int8"`) or
`"device": "cuda"` (+ `"compute_type": "float16"`).

---

## Model size vs. speed & accuracy

Set `"model_size"` in `flowsuite_config.json`. Larger = more accurate, slower,
more memory. First use of a size downloads it once.

| Size | Rough VRAM/RAM | Notes |
|------|----------------|-------|
| `tiny` / `base` | small | fastest, least accurate — fine on slow CPUs |
| `small` (default) | ~0.5 GB | good balance; recommended |
| `medium` | ~2 GB | more accurate, noticeably slower on CPU |
| `large-v3` | ~4 GB+ | best accuracy; realistically GPU-only |

CPU-only machine? Stick to `tiny`/`base`/`small`.

---

## Autostart at login (optional)

**Windows** — copy `start_flowsuite.vbs` into the folder that opens with
`Win+R → shell:startup`. It launches FlowSuite hidden on every boot.

**macOS**
```bash
bash macos/install_autostart.sh
```

**Linux (desktop session)**
```bash
bash linux/install_autostart.sh
```
(The script also prints a systemd-user alternative for headless setups.)

---

## How it works

```
hold hotkey → mic → faster-whisper → clean_text | transpile → keystrokes at cursor
```

- **Prose** strips um/uh, fixes spacing, capitalizes.
- **Code** runs a deterministic rule-based transpiler (`spoken_python.py` /
  `spoken_cpp.py`, backed by `fs_protect.py` and `fs_casing.py`) — **no
  LLM**, nothing to train, fully offline. String literals, comments, and
  casing commands are carved out into protected spans before the rest of
  the pipeline lowercases and rewrites the line, so their contents survive
  untouched.
- **Indentation is the editor's job.** Code editors auto-indent after `:`
  (Python) or `{` (C++), so FlowSuite never types leading spaces. Say
  **"new line"** (or **"then"**) for Enter, **"dedent"** to leave a block.

---

## Dictation cheat-sheets

### Structure commands (code modes)
`new line` / `then` = Enter · `dedent` = leave block · `indent` = extra indent
Brackets: `open/close paren` `( )` · `open/close bracket` `[ ]` · `open/close brace` `{ }`
Say `comma` `colon` `dot` for literal punctuation.

### Strings, comments & casing (both code modes)
| Say | Get |
|-----|-----|
| quote hello world quote | `"hello world"` (contents spoken verbatim, not mangled) |
| string hello end string | `"hello"` |
| comment this fixes the edge case | `# This fixes the edge case` (`//` in C++) |
| camel case max profit | `maxProfit` |
| pascal case two sum | `TwoSum` |
| snake case max profit | `max_profit` |
| constant case max size | `MAX_SIZE` |

A casing command stops at the next clause word (`gets`, `comma`, `new line`, …)
or after 5 words, whichever comes first — say "camel case max profit gets 0"
for `maxProfit = 0`.

### Python (F8)
| Say | Get |
|-----|-----|
| for i in range n / range of n | `for i in range(n):` |
| for i in range 1 to n | `for i in range(1, n):` |
| for x in nums | `for x in nums:` |
| if x greater than y and y less than z | `if x > y and y < z:` |
| dp of i | `dp[i]`  ·  grid of i of j → `grid[i][j]` |
| dp at i minus 1 | `dp[i - 1]` (computed index, see tip below) |
| dp of i gets max of dp of i comma nums of i | `dp[i] = max(dp[i], nums[i])` |
| nums dot append i / stack dot pop | `nums.append(i)` / `stack.pop()` |
| len/sum/min/max/sorted **of** … | `len(…)`, `min(…)`, … |
| negative infinity | `float('-inf')` |
| x not in seen · a if x greater than 0 else b | membership / ternary |
| define function two sum with nums comma target | `def two_sum(nums, target):` |
| if x is greater than 0 then return true | `if x > 0:` `<Enter>` `return True` |

Constants: `true`/`false`/`none` → `True`/`False`/`None`. Words that collide
with an operator keyword (`mod`, `and`, `or`, `not`, `index`, `count`, `times`)
stay identifiers when they sit right before `gets`/`set to`/`assign` — "mod
gets 5" gives `mod = 5`, not a stray `%`.

### C++ (F9)
| Say | Get |
|-----|-----|
| int result gets 0 | `int result = 0;` *(auto `;`)* |
| for i from 0 to n | `for (int i = 0; i < n; i++) {` |
| for each x in nums | `for (auto& x : nums) {` |
| vector of int dp open paren n comma 0 close paren | `vector<int> dp(n, 0);` |
| vector of vector of int dp | `vector<vector<int>> dp;` (containers nest) |
| if x equals to 5 and y greater than 0 | `if (x == 5 && y > 0) {` |
| nums dot push back x / dot size | `nums.push_back(x)` / `.size()` |
| sort of v dot begin comma v dot end | `sort(v.begin(), v.end());` |
| dp of i / grid of i of j | `dp[i]` / `grid[i][j]` |
| ans gets int max | `ans = INT_MAX;` |
| return result / close brace | `return result;` / `}` |
| and gets 5 | `and_ = 5;` (C++ reserves `and`/`or`/`not` as operator tokens too) |

Logic: and→`&&`, or→`||`, not→`!`. Statements auto-get `;`; control headers auto-get ` {`.

**Tip — computed indices:** say `dp at i minus 1` for `dp[i - 1]` directly.
`dp of i minus 1` still means `dp[i] - 1` (arithmetic on the plain index) —
`at` is the one that means "put the whole expression inside the brackets."
You can still speak the brackets explicitly if you prefer: "dp open bracket
i minus 1 close bracket".

---

## Configuration — `flowsuite_config.json`

Created on first run; per-machine, not tracked by git.

| Key | Default | Notes |
|-----|---------|-------|
| `hotkeys` | `{"f4":"prose","f8":"python","f9":"cpp"}` | hotkey → mode |
| `model_size` | `"small"` | see table above (restart to change) |
| `device` / `compute_type` | `"auto"` / `"auto"` | GPU if present, else CPU (restart to change) |
| `language` | `"en"` | pin a language, or `null` to auto-detect |
| `prompts` | `{"prose":null,"python":…,"cpp":…}` | per-mode whisper `initial_prompt` — Python and C++ get separate vocab, so C++ mode is no longer primed with Python-only words |
| `hotwords` | `{"python":[…],"cpp":[…]}` | extra per-mode whisper `hotwords`, combined with `identifier_aliases` values and budget-capped |
| `pronunciations` | `{}` | fix a recurring mishearing outright, e.g. `{"no de": "node"}` — applied to the raw transcript before anything else |
| `identifier_aliases` | `{"d p":"dp", …}` | exact whole-word fix for words whisper mishears |
| `alias_fuzzy` | `false` | opt-in fuzzy fallback for `identifier_aliases` (off by default — see below) |
| `alias_fuzzy_threshold` | `0.86` | similarity cutoff (0–1) when `alias_fuzzy` is on |
| `reserved_identifiers` | `[]` | extra words to always treat as identifiers, not operators, near `gets`/`set to`/`assign` |
| `key_delay` | `0.02` | pause between injected keystrokes |

Editing `flowsuite_config.json` while FlowSuite is running takes effect on the
next utterance — no restart needed, **except** for `model_size`, `device`,
and `compute_type`, which require reloading the whisper model.

---

## Correcting mistakes

- **A word is consistently misheard** ("no de" for "node") → add it to
  `pronunciations` in `flowsuite_config.json`. This runs on the raw
  transcript before anything else, in every mode.
- **A short identifier gets mangled** (`dp` heard as "d p") → add it to
  `identifier_aliases`. The `[stt]` line in the log shows exactly what was
  heard, so you can copy it straight into the config.
- **Similar-sounding identifiers keep slipping through** → set
  `"alias_fuzzy": true`. This only kicks in when the exact match misses,
  only for words 4+ letters long, and only against your own declared
  aliases — it will not, for example, ever turn "sum" into "some" or
  vice versa. Every fuzzy substitution is logged as `[vocab] alias: ...`.
- **An identifier collides with an operator word** (`mod`, `and`, `or`,
  `not`, `index`, `count`, `times`) → these already stay identifiers next to
  `gets`/`set to`/`assign` out of the box; add more to `reserved_identifiers`
  if you hit others.

---

## Troubleshooting

**First, run `python doctor.py`** — it verifies Python, packages, microphone,
clipboard, hotkey backend, and compute device, and prints a fix hint for each
failure. Common issues:

- **Nothing is inserted, no beep** — the hotkey isn't reaching the app. On macOS
  grant Accessibility permission; on Linux use an X11 session / join the `input`
  group; on Windows run the terminal as Administrator.
- **Beeps but nothing appears** — check the console/`flowsuite.log`. A CUDA error
  means the GPU libs are missing → it auto-falls back to CPU (or set
  `"device": "cpu"`).
- **Paste does nothing on Linux** — install `xclip` or `xsel`.
- **Wrong words for short identifiers** (`dp` heard as "d p") — add them to
  `identifier_aliases` in `flowsuite_config.json`. The `[stt]` line in the log
  shows exactly what was heard. See [Correcting mistakes](#correcting-mistakes)
  for pronunciations and fuzzy matching too.
- **Hotkey conflicts** with an app — change `hotkeys` in the config to other
  F-keys.

---

## Privacy

- Audio is held in memory only, never written to disk.
- Inference is 100% on-device (CTranslate2). No API keys, no accounts.
- The only network access is the one-time model download; after that FlowSuite
  works fully offline.

---

## Files

- `flowsuite.py` — the app (hotkeys, model, text injection)
- `spoken_python.py` / `spoken_cpp.py` — transpilers (`transpile(text, cfg) → ops`)
- `fs_protect.py` — protected spans for strings/comments/identifier-vs-operator
  collisions, plus the bracket-`balance()` safety net
- `fs_casing.py` — `camel case` / `pascal case` / `snake case` / `constant case`
  commands
- `fs_vocab.py` — per-mode STT prompts/hotwords, `pronunciations`, and the
  opt-in fuzzy `identifier_aliases` fallback
- `whisperflow.py` — shared mic capture + prose `clean_text`
- `doctor.py` — environment self-check (`python doctor.py`)
- `tests/` — pytest suite for the transpilers and the new modules above
  (`pip install -r requirements-dev.txt && pytest`)
- `run_flowsuite.bat` (Windows) / `run_flowsuite.sh` (macOS/Linux) — launchers
- `start_flowsuite.vbs`, `macos/`, `linux/` — autostart helpers per OS

Extending the code vocabulary: add rows to the phrase tables in
`spoken_python.py` / `spoken_cpp.py`, add a case to `tests/test_spoken_python.py`
or `tests/test_spoken_cpp.py`, then run `pytest` (or `python spoken_python.py`
for the quick manual smoke test).

---

## Standalone WhisperFlow (prose-only)

`whisperflow.py` is the original prose-dictation tool and the shared library
FlowSuite builds on. If you only want dictation (no code modes) it runs on its
own — `python whisperflow.py` (default hotkey F9), same platform notes as above.

FlowSuite

FlowSuite Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

FlowSuite

FlowSuite Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README