Push-to-talk dictation that types what you actually said - for prompting AI agents, writing docs, or just messaging.
Keeps your words (and your jargon) intact - never reworded. Record your voice, transcribe it, fix only the mechanics, and paste it at your cursor. Cross-platform: macOS (Apple Silicon) and Windows, one codebase.
© 2026 Cloudelipute · MIT License · v4.0.0
| Push-to-talk | Hold a key to dictate. Toggle and wake-word modes too. |
| Faithful, never reworded | Types your actual words - wording, tone, slang and jargon/code kept verbatim, never paraphrased. Say "um so like i'll be there in ten" and it stays your sentence; say "cube cuttle apply dash f deployment dot yaml" and you get kubectl apply -f deployment.yaml. |
| Output modes | Clean (default - faithful: fix only caps/punctuation + fillers, keep your words) · Polished (opt-in tidy rewrite) · Verbatim (raw, no AI). |
| Spoken symbols | "dash dash help" → --help, "dot py" → .py, "open paren" → (. |
| Vocabulary | Teach it your terms: "cube cuttle" → kubectl, "next J S" → Next.js. CSV import. |
| Cloud or on-device | Default cloud scribe_v2 (ElevenLabs Scribe); optional local mlx-whisper/faster-whisper. |
| Recording HUD | Frameless always-on-top pill with live waveform and idle->listening->transcribing->done states. |
| Unicode-safe paste | Clipboard-paste primary (Cmd/Ctrl+V), pynput type fallback - emoji & CJK safe. |
| Native notifications | Cross-platform toasts; HUD is the always-on fallback. |
| BYOK | Your ElevenLabs key, your machine. No telemetry, no middleman. |
Full architecture drawings - system overview, threading model, dictation sequence, engine abstraction, and the formatting pipeline - are in docs/ARCHITECTURE.md.
flowchart TB
subgraph UI["UI layer - PySide6 / Qt (one event loop)"]
tray["Tray"] --- wizard["Wizard"] --- settings["Settings"]
settings --- hud["HUD"] --- history["History"] --- notif["Notifications"]
end
UI -- "Qt signals/slots" --> CTRL
subgraph CTRL["Controller (app orchestrator)"]
direction LR
c["wires: hotkeys -> record -> engine -> formatting -> insert -> HUD"]
end
CTRL --> hotkeys["hotkeys<br/>(pynput) PTT/toggle"]
CTRL --> audio["audio<br/>(sounddevice + vad)"]
CTRL --> engines["engines (STT)<br/>cloud / local"]
CTRL --> formatting["formatting<br/>faithful · vocab · mode"]
CTRL --> typer["typer<br/>(pynput / clipboard)"]
CTRL --> hist["history"]
hotkeys --> perms["permissions<br/>(mac TCC)"]
engines --> api["api (ElevenLabs Scribe) /<br/>local model runtimes"]
classDef plat fill:#1b1b22,stroke:#ec2a8e,color:#fff;
class perms,api plat;
flowchart TD
idle(["idle"]) -->|"PTT key down / toggle / wake word"| listen["HUD: listening + waveform"]
listen --> record["record (sounddevice, 16 kHz mono)"]
record -->|"key up / stop"| vad{"VAD: speech?"}
vad -->|"silent"| idle
vad -->|"speech"| bias["vocabulary -> Scribe keyterms bias"]
bias --> stt["Engine.transcribe()<br/>cloud ElevenLabs scribe_v2<br/>or local mlx / faster-whisper"]
stt --> fmt["Formatting:<br/>strip wake words -> expand spoken symbols -><br/>canonical vocab correction -> mode cleanup<br/>(clean / polished / verbatim) -><br/>optional translate (gpt-5-nano)"]
fmt --> paste["Typer: clipboard-paste at cursor (Cmd/Ctrl+V)"]
paste --> done["HUD: done · sound cue · history.add() · notify"]
done --> idle
flowchart LR
welcome["Welcome"] --> engine["Engine<br/>cloud / local"]
engine --> connect["Connect<br/>API key or model download"]
connect --> perms["Permissions<br/>(macOS only)"]
perms --> voice["Hotkey & Voice<br/>PTT/toggle · key capture · mic test"]
voice --> done["All set"]
connect -. "Windows skips Permissions" .-> voice
Yapper installs from source with uv. No Python install dance, no embedded runtime.
Prerequisite: install uv once -
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"git clone https://github.com/romiteld/yapper.git
cd yapper
./setup # uv sync - creates .venv, installs deps (+ macOS pyobjc helpers)
./run.command # or ./run.shgit clone https://github.com/romiteld/yapper.git
cd yapper
setup.bat
run.batgit clone https://github.com/romiteld/yapper.git
cd yapper
./setup
./run.shLinux is best-effort: global hotkeys need X/uinput and tray support varies by desktop. Not a release target.
uv sync --extra local # mlx-whisper on macOS arm64, faster-whisper on Windows/LinuxUnsigned .app/.dmg (macOS) and .zip (Windows) are attached to GitHub Releases as a convenience.
On macOS Sequoia/Tahoe, clear the quarantine flag on first launch:
xattr -dr com.apple.quarantine /Applications/Yapper.app(or System Settings → Privacy & Security → Open Anyway). Notifications may be unavailable on the unsigned build - the HUD covers all feedback.
- Dictate: hold your hotkey (push-to-talk), speak, release - the text is pasted at your cursor. Toggle and wake-word activation are selectable too.
- Menu-bar / tray: quick-toggle the engine (cloud/local), output mode (Clean/Polished/Verbatim), and language inline; open Settings or History; quit.
- Settings (sidebar): General · Engine & Models · Vocabulary (teach it your terms) · Formatting (mode + spoken symbols) · Hotkeys · Audio · History · About. Edits apply on Save.
- History: search past dictations, copy, re-insert, reprocess with current settings, clear, or export.
- Scripted / no GUI:
uv run python -m app --oncedoes a single record→type;--seconds Nsets the recording window.
See docs/ARCHITECTURE.md for the full architecture drawings (system overview, threading model, dictation sequence, engine abstraction, formatting pipeline, and the UI-surface map).
macOS only re-reads permissions at process start - after granting anything, quit & relaunch Yapper.
| Permission | Why | How |
|---|---|---|
| Microphone | Record your voice | OS prompts on first capture |
| Accessibility | Paste / type at the cursor | System Settings → Privacy & Security → Accessibility → enable Yapper |
| Input Monitoring | Capture the push-to-talk hotkey | System Settings → Privacy & Security → Input Monitoring → enable Yapper |
Grant these to the Yapper app's identity (the .app, or your terminal/Python when running from source). Without Accessibility, key injection fails silently - the first-run wizard detects and guides you through it.
Windows and Linux require no special TCC grants (Windows hotkeys may need an elevated terminal in some configurations).
| Role | Default | Alternative | Notes |
|---|---|---|---|
| Cloud STT | scribe_v2 (ElevenLabs Scribe v2) |
scribe_v1 |
low-latency cloud STT with 90+ languages and keyterm prompting |
| On-device STT | mlx-whisper (mac) / faster-whisper (win) |
size selectable (base...) |
runs offline; install via --extra local |
| Text cleanup / translate | gpt-5-nano (reasoning_effort='minimal') |
gpt-5.4-nano |
deterministic spoken-symbol + vocabulary cleanup runs locally |
Output modes (output_mode setting): Clean (default) faithfully fixes only caps/punctuation and fillers while keeping your exact words, tone, and any code/jargon verbatim. Polished is an opt-in heavier rewrite into tidy prose. Verbatim makes no AI call at all (the deterministic spoken-symbol + vocabulary stages still run, so it works with no API key).
A few minutes of dictation per day on the cloud default costs cents. On-device is free after download.
Yapper is bring-your-own-key. You paste your own ElevenLabs API key during onboarding; it is stored locally in app/settings.json (gitignored) and used only to call ElevenLabs directly from your machine.
- No telemetry. Yapper phones home to nothing.
- No middleman. Audio and text go straight from your machine to the API you chose.
- Local-only option. With
--extra local, transcription never leaves your device. - Your key, gitignored.
app/settings.jsonis never committed.
uv sync --extra dev # pytest, pytest-qt, pyinstaller
uv run pytest # run the test suite
uv run python -m app # run from source© 2026 Cloudelipute · Released under the MIT License.