parlando 0.4.0

Local voice dictation for macOS (Apple Silicon). Tap a key, speak, tap again — your words are typed into whatever window has focus. 100% on-device: audio never leaves your machine.

Features

• Fully local & offline — MLX-accelerated Qwen3-ASR on the Apple Neural stack; works on a plane, nothing is uploaded, no API keys.
• Tap-to-dictate — single tap of right ⌥ Option starts/stops recording (the same pattern superwhisper and Wispr Flow use). No always-on mic.
• Types anywhere — text is delivered as native keyboard events (Quartz CGEvent unicode), so it works in any app, editor, terminal, or chat box.
• 30 languages — English by default; switch instantly (e.g. --language Turkish) with no model reload.
• Voice commands — "period", "comma", "question mark", "new line", "send" (presses Enter). A Turkish command set activates with --language Turkish.
• Cleanup & polish — vocalized fillers ("um", "uh", "eee") are removed automatically; optional --polish runs a small local LLM that drops contextual fillers ("you know", "yani"), stutters and false starts, and fixes punctuation — guarded so it can only edit your words, never answer them.
• Menu bar app — (idle · recording · paused) with start/stop, language switcher, and start-at-login support.
• Self-healing — audio watchdog survives sleep/wake and device changes; inference errors never kill the session.
• Streaming mode (optional) — words appear as you speak, stabilized with LocalAgreement-2 and append-only commits (typed text is never retracted).

Requirements

• macOS on Apple Silicon
• uv installed
• ~2 GB disk for the default ASR model (downloaded once from Hugging Face)

Install

One-liner (installs uv if needed, puts parlando on your PATH):

curl -fsSL https://raw.githubusercontent.com/furkanc/parlando/main/install.sh | sh

Then:

parlando            # terminal
parlando-menubar    # menu bar app

Click the window you want to type into → tap right ⌥ Option → speak → tap again. Your words appear at the cursor. The speech model (~1-2 GB) downloads once on first run; after that everything is offline.

git clone https://github.com/furkanc/parlando && cd parlando
uv run parlando              # run without installing
uv tool install .           # or install the commands from the checkout

# uninstall
uv tool uninstall parlando

Permissions (one-time)

macOS will ask for two permissions, granted to the app that runs parlando (Terminal, iTerm, VS Code, ...):

parlando detects missing permissions and tells you explicitly instead of failing silently.

Usage

parlando --language Turkish   # dictate in another language
parlando --polish             # LLM cleanup (fillers, false starts, punctuation)
parlando --enter              # press Enter after each utterance
parlando --mode stream        # live word-by-word streaming
parlando --pipe               # print to stdout (scriptable)
parlando --hotkey cmd_r       # tap right Command instead
parlando --list-devices       # list microphones
parlando-menubar --install-login   # start at login

Voice commands

Disable with --no-commands.

Models

Speech recognition (--model, MLX Qwen3-ASR — 30 languages):

Polish LLM (--polish-model, used only with --polish; scores from scripts/eval_polish.py, an 11-case cleanup benchmark):

parlando --polish --polish-model mlx-community/Qwen3-4B-4bit

All models download once from Hugging Face and are cached in ~/.cache/huggingface; everything runs on-device.

The two modes

record (default) — tap, speak freely (pauses are fine), tap again; the whole recording is transcribed once and typed in one go. Recordings longer than 28 s are split at natural silence points (2 min cap). This mode has no VAD guessing, so it is the most robust.

stream — always listening; an energy VAD (hysteresis, adaptive noise floor, optional --silero hybrid) segments utterances and words appear as you speak. More "live", more sensitive to room noise.

Troubleshooting

Note: --device indices shift when devices connect/disconnect, and virtual devices ("Microsoft Teams Audio", "ZoomAudioDevice") are not microphones. Prefer the default device.

Architecture

microphone ── 30 ms frames ──▶ hotkey-gated recorder (record mode)
                              or energy VAD w/ hysteresis + adaptive floor,
                              optional Silero hybrid, 300 ms pre-roll (stream)
                │ segment boundaries
                ▼
        segment audio only ──▶ Qwen3-ASR (MLX, on-device GPU)
                │ readings
                ▼
        LocalAgreement-2 ──▶ append-only word commits ──▶ CGEvent unicode
        (commit on 2-reading    (typed text is never        keyboard events
         agreement)              retracted)

Key decisions (each one earned by a real failure during development):

• Segment-based ASR, not a rolling window — re-decoding a growing window revises earlier words (visible flicker) and hallucinates on silence.
• Append-only, word-count-based commits — exact-prefix matching stalls permanently when the ASR reshapes punctuation on committed words.
• Normalized agreement + stall safety valve — punctuation/case flapping between readings must not freeze the stream.
• Asymmetric noise-floor learning — a symmetric EMA lets speech scraps poison the floor and the app goes progressively deaf.
• Every loop iteration guarded — a single ASR exception must not silently kill the pipeline.
• Chord-aware hotkey — ⌥+Q-style character chords never toggle dictation.

Development

uvx --with numpy pytest tests -q   # unit tests; no model/mic needed
uv run scripts/eval_polish.py      # polish quality benchmark (real local LLM)
uv build                           # build the wheel/sdist

Package layout: src/parlando/ (engine, menubar, ASR engine), entry points parlando and parlando-menubar. CI runs the test suite and a packaging build on macOS via GitHub Actions.

Roadmap

• One-line installer (install.sh) with parlando launcher command
• Proper Python package (uv tool install, entry points) — PyPI publication pending, after which uvx parlando will work
• Publish to PyPI
• Homebrew tap (brew install parlando)
• End-to-end regression tests with recorded WAV fixtures
• Custom vocabulary / context biasing

License & credits

MIT. The Qwen3-ASR MLX engine (stt.py) is from dictate.sh by Marc Puig (MIT), with local modifications (partial streaming, energy gating, error hardening). Turn-taking research: Whisper-Streaming / LocalAgreement-2. VAD: Silero VAD.