Skip to main content

YazSes

Offline voice typing for Linux, macOS and Windows. Hold a key, speak, release, and your words are typed into whatever app you are using.

Speech recognition runs on your own computer, so your voice never leaves it. There is no account, no subscription and no API key. YazSes is free and open source under Apache 2.0.

Tests PyPI PyPI Downloads Snap Status License: Apache 2.0 DOI Documentation Open Source Helpers All Contributors

YazSes — hold a key, speak, release; the text is typed into the focused app

A 40-second tour of dictation, the command line and the system tray. The terminal output is real; the command-line typing was re-enacted so it is easier to read. ▶️ Watch it on YouTube, with chapters.

Install · Quick start · Voice commands · Compare · FAQ · Documentation · Contribute

🌐 Read this in other languages (27)

Read this in other languages: English · Deutsch · Nederlands · Tiếng Việt · Türkçe · bahasa Indonesia · español · français · italiano · polski · português do Brasil · svenska · čeština · ελληνικά · Русский · українська · اردو · العربية · فارسی · हिंदी · বাংলা · தமிழ் · తెలుగు · ไทย · 日本語 · 简体中文 · 繁體中文 · 한국어

✨ What it does

🎙️ Type with your voice Hold your hotkey, speak, release. The text appears in the window you are using: email, browser, chat, editor or terminal.
🗣️ Voice commands Say "scratch that", "new line" or "go to line 42" and YazSes carries out the action instead of typing the words.
📄 Transcribe recordings yazses transcribe interview.m4a turns an audio or video file into text, optionally with who said what.
👥 Meeting notes yazses meeting start … yazses meeting stop records a meeting in the room and produces a speaker-labelled transcript, plus optional minutes from a local AI model.
🔒 Private by default Everything runs on your CPU. By default, no audio and no text leave your computer.

Also included: multi-step voice macros and a personal vocabulary for words it mishears · Dysfluency-Friendly Mode, which collapses stutters and repeats (b-b-because → because) · opt-in, encrypted on-device learning, where yazses tune proposes accuracy fixes from your own corrections · editor navigation through your editor's LSP (yazses jump, Neovim bridge, opt-in) · EMG (muscle-sensor) triggering and mic calibration for accessibility · an optional voice-activity overlay near the cursor. The feature catalog lists every capability and how to turn it on.

What's optional: dictation works out of the box. Speaker labels need the diarization extra (pipx install 'yazses[diarization]', ~45 MB of models, downloaded once). Meeting minutes also need the notes extra and a local GGUF model that you supply. Both are off by default. See offline meeting notes.

⬇️ Install

Choose your operating system. Each install is one command followed by a short first-run setup.

🐧 Linux (the most tested platform)

bash <(curl -fsSL https://raw.githubusercontent.com/MSKazemi/yazses/main/install.sh)

Then log out and back in once, which gives YazSes access to the keyboard, and run yazses start. Full Linux guide →

🍎 macOS, Apple silicon (M1 or newer) (preview)

brew tap MSKazemi/yazses && brew trust MSKazemi/yazses && brew install --cask yazses

Open YazSes from Applications. The app is not signed yet, so macOS blocks it the first time: click Open Anyway in System Settings → Privacy & Security, then allow Microphone, Accessibility and Input Monitoring when asked. On an Intel Mac, download the -macos-x86_64.dmg from Releases instead. Releases after 2.43.2 put a yazses command on your PATH through the Homebrew cask; with the .dmg, or on 2.43.2, run the CLI as /Applications/YazSes.app/Contents/MacOS/YazSes --cli doctor. Full macOS guide →

🪟 Windows (preview)

winget install MSKazemi.YazSes

winget can lag behind the newest release; the installer, Scoop and Chocolatey track every release. The installer is not code-signed yet, so if Windows SmartScreen warns you, click More info → Run anyway. Then open YazSes from the Start menu. Full Windows guide →

Then start talking. Hold your hotkey, speak and release. The default hotkey is Right Alt on Linux, Right Option on macOS and Right Ctrl on Windows; yazses hotkey set <key> changes it. If nothing happens, run yazses doctor. It checks your microphone, hotkey and typing, and tells you what to fix.

macOS and Windows are previews. Linux has the most reports from real machines. The macOS and Windows builds are newer, and the validation matrix shows exactly what has and has not been confirmed on real hardware. If you try one, a short report is one of the most useful contributions you can make.

Not ready to install? Try it without installing in Docker or your browser, or read what installing actually costs first. APT, Snap, pipx, .dmg and .exe are covered under all install options.

🙌 Help build YazSes

New to open source? You are welcome here. You need no speech or AI background, and several tasks need no Python at all:

Start here: one page where you pick the row that matches what you have and finish in 15–45 minutes. No permission is needed and nothing is assigned. #22 lists everything open, and Contributing below covers the development workflow.

⭐ If YazSes is useful to you, a star is how other people find it. There is no company and no advertising budget behind this project; word of mouth is how it reaches people.


About YazSes

YazSes is a free, open-source, offline voice dictation and speech-to-text daemon for Linux (X11 and Wayland), macOS and Windows, built on faster-whisper. Use it when audio must not be sent to Google, Apple, Microsoft or Otter: because the meeting is confidential, because the machine is air-gapped, or because you do not want a subscription.

  • Compared with cloud dictation such as Wispr Flow, YazSes runs entirely on-device.
  • Compared with Talon Voice, it aims at plug-and-play use rather than advanced scripting.
  • Compared with other free on-device tools (Handy, OpenWhispr), it adds voice commands, speaker-labelled meeting capture and published benchmarks.
  • It is not the right tool if you need a conversational AI agent, non-English models out of the box, or a mobile or web app.

📖 Full documentation: mskazemi.com/yazses, with install guides, the CLI reference, configuration, features and troubleshooting.

yazses doctor — all green, fully offline by default

Prefer text to video? Watch the CLI in your browser: an asciinema recording of the happy path (-h → about → quickstart → features → status) in which every byte is real command output. The player is served from the docs site itself, not a CDN, so watching it does not report you to anyone. In your own terminal, run asciinema play docs/demo/yazses-cli.cast.


Quick Start

Want to hear how accurate it is first? Try it without installing in Docker or your browser. A sample clip ships with the repository, and --network none proves the transcription happens on your own machine.

Step 1 — Install

Use the command for your system in Install above, or any route in all install options.

The recommended Linux one-liner installs uv if needed, installs the latest YazSes, sets up every system prerequisite (audio, keystroke injection, clipboard, the input group and Wayland ydotoold), and finishes by running yazses doctor so that any missing tool shows up during the install rather than later.

Wary of piping a script from the internet into your shell? Add --dry-run. The script inspects your machine, prints every change it would make, and exits without making any: bash <(curl -fsSL .../install.sh) --dry-run

Both what installing actually costs (1.1 GB plus a 141 MB model, and what it changes on your system) and how to uninstall are published up front.

Only need to transcribe a recording? The container needs no install at all: docker run --rm -v "$PWD:/data" ghcr.io/mskazemi/yazses transcribe /data/talk.m4a --diarize. It produces a transcript with speaker labels. It does not do hold-to-talk dictation, which needs a real desktop session; see the Docker page.

Step 2 — Prepare the system (Linux only)

The one-liner and the APT install do this for you, and the Snap does not need it. After a pipx or source install, run:

yazses setup        # installs audio + injection deps, joins the input group, sets up ydotoold
# then log out and back in (the input-group change needs a fresh login)

yazses setup is safe to re-run and only does what is missing. It ends with a numbered checklist of the steps only you can do (the re-login, voice calibration with yazses mic-level --set, and yazses start) and offers to run the calibration right away.

The log-out and log-in is required, once. Joining the input group only takes effect in a new login session. Opening another terminal tab is not enough, because it inherits the old session's groups and the hotkey stays dead. yazses start warns you while the re-login is still pending. To dictate immediately without logging out, bridge the group for one session with sg input -c "yazses restart".

What yazses setup installs, and how to do it by hand
  • libportaudio2 for audio capture. Without it the daemon crashes on start with OSError: PortAudio library not found.
  • Injection backends: xdotool and xclip on X11; wtype, ydotool and wl-clipboard on Wayland.
  • The input group, which is required to read the hold-to-talk hotkey from the kernel.
  • ydotoold, the virtual-input daemon. On GNOME and KDE Wayland it is the only way to inject keystrokes (wtype is blocked there), so setup installs and enables it.

By hand: sudo apt install libportaudio2 xdotool ydotool wtype xclip wl-clipboard pipx && sudo usermod -aG input "$USER", then enable ydotoold (see install-linux). Check the result at any time with yazses doctor; you want [OK] Keyboard capture, [OK] Microphone and [OK] Injection.

On macOS and Windows, skip this step and grant the Accessibility and Microphone permissions when prompted.

Step 3 — Calibrate and start

yazses quickstart           # not sure what's next? a 3-step guide tailored to your machine
yazses doctor               # check mic, injection backend, permissions (want all [OK])
yazses mic-level --set      # tune the silence gate to your room and voice (~6 s)
yazses enroll               # optional: a longer guided calibration (20 short phrases)
yazses autostart enable     # run it at login, so it's there after a reboot
yazses start                # start the dictation daemon
yazses verify               # speak once and prove the whole pipeline works

yazses quickstart is safe to run at any time. It looks at what is already set up, tells you what to do next, and changes nothing.

Step 4 — Dictate

Hold the hotkey, speak and release. The text is typed into the focused app.

OS Default hotkey
Linux Right Alt
macOS Right Option
Windows Right Ctrl

Try "the quick brown fox" (typed as text), then "undo that", "go to line 42" or "run the tests" (carried out as commands). On a modern laptop CPU, the time from releasing the key to seeing text is a median of 1.6 s with the default base.en model, or 0.9 s with tiny.en (measured).

Shell completion: yazses --install-completion, or yazses --show-completion to print the script. See the CLI reference.


What you can say

Hold the key and talk: by default, everything you say is typed at the cursor. YazSes also recognises a set of voice commands and turns them into editor and terminal key sequences instead of typing them:

Say something like… What happens
"the quick brown fox" Types the text at the cursor (dictation)
"delete the last three words" Deletes the last 3 words
"undo that" / "undo five times" Sends undo
"save file" · "copy" · "paste" Save / copy / paste
"select all" · "select to end" Selection commands
"comment this line" Toggles a comment
"go to line 42" Jumps to line 42
"go to function parse_config" Jumps to the symbol (via LSP, opt-in)
"run the tests" / "run the build" Runs the editor/terminal action
"rename this to user_id" Renames the symbol

Commands are recognised by a fast regex grammar. You can add multi-step macros and a personal vocabulary of misheard words; see the CLI reference.


How it works

Hold hotkey → record audio → VAD gate → faster-whisper (CPU) → clean + disfluency filter
            → command grammar (Tier 1 regex; Tier 2 SLM router designed, not wired)
            → dictate? type the text   ·   command? send the key sequence

Everything runs on your CPU, with no GPU and no network. faster-whisper (int8) transcribes the audio, and a regex grammar decides whether each utterance is dictation or a command. A ~0.5B SLM router was designed to take a second look when confidence is low. Its seam exists (grammar.classify() accepts one), but nothing constructs it yet, so the regex grammar decides every utterance today.

Performance. Measured on a 13th-gen Core i7 laptop, int8 on CPU: 4.07 % WER on LibriSpeech test-clean with the default base.en, a 1.56 s median decode, and 0.29 ms of total non-decode pipeline overhead. Almost all of the latency is the speech model. The method and the commands to reproduce these numbers are on the benchmarks page.

Models

  • Speech-to-text: faster-whisper tiny.en (fastest), base.en (default) or small.en (most accurate), int8 on CPU.
  • Dictation cleanup (optional, off by default): a small offline LLM can tidy grammar and punctuation. Length and token-preservation guards stop it from changing your meaning.
  • Command routing (not wired yet): a Qwen2.5-0.5B SLM for Tier 2 intent classification. yazses model download can fetch it, but nothing loads it yet, so downloading it today gains you nothing. The command is still the right way to pre-fetch a speech model behind a firewall.

Requirements

OS Linux (primary) · macOS 14+ (preview) · Windows 10 (21H2)+ (preview)
RAM 4 GB minimum · 8 GB comfortable
Disk ~250 MB–1 GB for the faster-whisper model (downloaded on first run)
CPU 2+ cores · no GPU required
Mic Any USB or built-in microphone

Using Apple silicon, an Intel Mac, ARM64 Windows, a Raspberry Pi or another less common CPU? The platform support matrix lists the tested install channel for each OS and architecture. pipx install yazses is a portable fallback on supported Python and platform combinations, but a native package gives a better desktop experience where one exists.


Use cases

Who Why YazSes fits
Writers and journalists Draft long-form text hands-free, without your words leaving the machine.
Developers Dictate comments and commit messages, and drive the editor or terminal by voice: undo, save, go to line, run tests, rename a symbol.
Developers on remote machines Text is injected at the OS level, so dictation works in VS Code or Cursor Remote-SSH panes, terminals running a remote shell, tmux and container shells, where built-in voice input usually stops. See dictation over SSH.
Privacy-conscious professionals Dictate in law, medicine or research, where audio must never touch a cloud service.
Teams with confidential meetings Record and summarise internal, clinical, legal or pre-publication meetings without a note-taking SaaS or a bot in the call.
Researchers with recordings Batch-transcribe interviews, lectures and field recordings offline, with speaker labels, under your own retention rules.
People with motor disabilities Hold-to-talk or EMG (muscle-sensor) triggering for hands-free input, with Dysfluency-Friendly Mode for stuttered or dysarthric speech.
Offline and air-gapped sites Dictation on machines with no reliable internet, or where outbound network calls are not allowed.

Guides with setup steps: voice typing on Linux (X11 and Wayland) · voice dictation on Wayland · dictation over SSH and Remote-SSH · private and confidential work · coding by voice · accessibility and RSI · transcribing recordings · multilingual dictation


Limitations / when not to use YazSes

  • It is not an LLM agent. YazSes dictates text, transcribes recordings and runs editor and terminal commands. It does not browse, reason over your files or hold a conversation (it can set an offline timer by voice, opt-in); that was the paused Rust exploration.
  • Speaker labels and minutes are extras, not defaults. --diarize and meeting minutes each need an opt-in extra, and minutes also need a local GGUF model that you supply. Plain dictation and plain transcription need neither.
  • It uses faster-whisper on the CPU, not a cloud service. On a noisy microphone, a cloud speech service may still achieve a lower word-error rate. The trade-off is that nothing leaves your machine.
  • It is tuned for English by default. It ships with *.en Whisper models; other languages need a different model.
  • It is desktop only, for now. There is no mobile or web build. An Android app is in design: the architecture and its ten decision records are public at docs/mobile, and contributors are building it in the open. iOS and iPadOS will follow Android.

Comparison & alternatives

An honest comparison with other voice-dictation tools. Every claim is about publicly documented behaviour, and each tool has strengths YazSes does not.

YazSes Dragon Talon Voice Windows Voice Access Wispr Flow
Runs offline / on-device ✅ ✅ ✅ ✅ ❌ (cloud)
Voice commands ✅ regex grammar ✅ ✅ advanced scripting ✅ limited
Linux ✅ ❌ ✅ ❌ ❌
macOS ✅ preview ❌ (discontinued) ✅ ❌ ✅
Windows ✅ preview ✅ ✅ ✅ (built in) ✅
Price Free, Apache-2.0 Paid Free (paid beta features) Free (built into Windows 11) Paid subscription
Open source ✅ ❌ ❌ ❌ ❌

Preview means supported and installable, but not yet verified on hardware by a person on a current build; the validation matrix shows what testers have confirmed so far.

The open-source, local, free ones

A growing group of tools shares YazSes's licence model and privacy model. Leaving them out would make this comparison evasive to exactly the readers who already know about them.

YazSes Handy OpenWhispr FluidVoice VoiceInk
Runs offline / on-device ✅ ✅ ✅ (cloud optional, BYOK) ✅ ✅
Linux ✅ ✅ ✅ ❌ (announced) ❌
macOS ✅ preview ✅ ✅ ✅ ✅
Windows ✅ preview ✅ ✅ community port ❌
Price Free Free Free Free Paid (from $29)
Licence Apache-2.0 MIT MIT GPLv3 open source
Voice commands, not just dictation ✅ ❌ ✅ spoken instructions ✅ Command Mode limited
Meeting capture with speaker labels ✅ ❌ transcription, no diarization documented ❌ ❌
Published benchmarks with method ✅ ❌ ❌ ❌ ❌

Handy is the closest alternative. It is MIT-licensed, free, cross-platform and on-device, with the same hold-a-key-and-speak loop. If you want dictation and nothing else, it is an excellent choice and considerably smaller than YazSes.

Good reasons to choose another tool:

  • Handy: you want dictation only, with the smallest possible install.
  • OpenWhispr: you want a polished Electron app, and falling back to a cloud model with your own API key is a feature for you rather than a dealbreaker.
  • FluidVoice: you are on macOS and want voice control of the OS itself (launching apps, running Shortcuts), which goes beyond YazSes's editor-oriented commands.
  • VoiceInk: you are on macOS, want a native app, and prefer paying once.
  • Talon Voice: you want deep, scriptable voice control and are willing to learn its scripting model. YazSes and Talon can run side by side.
  • Windows Voice Access: you are on Windows 11 and want zero install and OS integration.
  • Dragon: you want a mature, professionally supported Windows product and can pay for it.
  • Wispr Flow: you prefer a polished cloud service and are comfortable sending audio off-device.

So what is actually different about YazSes?

Being open source, local, cross-platform and free no longer sets YazSes apart: Handy and OpenWhispr are all four. The real differences are narrower:

  1. Voice commands as well as dictation, with a documented grammar. Most of the tools above do dictation only.
  2. Linux as a first-class target, not a port: X11 and Wayland injection, evdev hold-to-talk, systemd autostart, a .deb, an APT repository and a snap.
  3. Meeting capture with speaker labels, entirely on-device.
  4. Published benchmarks with a stated method, plus an explicit list of what was not measured. See benchmarks.
  5. Accessibility as a design constraint, not an add-on: dysfluency-friendly filtering, calibrated silence gates, and activation that does not depend on a keyboard.

How current is this? It was compiled from each project's own documentation in August 2026, not from testing each tool. This space moves quickly. If a row is out of date, tell us; a comparison that flatters us by being stale is worth less than no comparison at all.


FAQ

What is YazSes? An open-source, offline hold-to-talk voice-dictation daemon for Linux, macOS and Windows. You hold a key, speak and release; your speech is transcribed on-device with faster-whisper and typed into the focused application. It also supports editor and terminal voice commands and macros.

Is there a good offline voice-dictation tool for Linux? Yes. YazSes runs natively on Linux (X11 and Wayland), transcribes locally on the CPU, and needs no cloud service or API key. It installs with a one-line script, APT, Snap or pipx.

How does YazSes compare with Talon? Both are cross-platform and work offline. YazSes focuses on plug-and-play dictation plus a practical command grammar. Talon offers far more advanced, scriptable voice control. You can use them side by side.

Does it work without internet? Yes. Transcription runs locally with faster-whisper, and by default no audio or text is sent anywhere. YazSes works fully offline, including on air-gapped machines.

Is it free and open source? Yes. YazSes is released under the Apache 2.0 licence, with no subscription or API key.

What hardware do I need? No GPU. It runs on the CPU with 4 GB of RAM at minimum (8 GB is comfortable) and any USB or built-in microphone.

Is it an AI agent? No. YazSes dictates text and runs editor and terminal voice commands; it does not browse, reason over your files or hold a conversation. An agentic version was prototyped in the archived Rust branch but has not shipped.

More in the full FAQ and the side-by-side comparison page (YazSes vs Talon, Dragon, Wispr Flow, nerd-dictation and others).


CLI commands

The most common commands. Run yazses --help, or see the CLI reference, for everything else.

Command Description
yazses quickstart New here? A 3-step, machine-tailored getting-started guide (read-only)
yazses start Start the YazSes daemon in the background (restarts cleanly if one is already running; verifies it actually came up)
yazses restart Stop all daemons (including detached) and start exactly one
yazses stop Stop the running daemon
yazses status Show daemon status — queries the daemon over IPC when reachable
yazses doctor Check prerequisites (version, daemon, model, mic, injection backend, permissions) — ends with a ✓/▲/✗ verdict
yazses enroll Calibrate your microphone — tunes vad_threshold for your voice and room
yazses mic-level Measure mic speech level and recommend (or --set) the VAD threshold
yazses features List capabilities and toggle them (enable/disable <name>). Designed but unbuilt ones are listed separately
yazses settings The same switchboard as a window — every capability as a checkbox (needs a display). Guide · --install-launcher adds it to your app grid
yazses vocab Personal dictionary of mis-heard words (add/list/remove)
yazses hotkey Show or change the hold-to-talk key (set) and the dedicated command key (command)
yazses overlay Launch the sonar voice-activity overlay (requires the overlay extra)
yazses inject TEXT Type arbitrary text into the focused window — test injection without speaking
yazses say TEXT Speak text aloud (offline TTS)
yazses test End-to-end self-test: focuses a window and types YazSes OK
yazses logs Show the daemon diagnostic log (metadata only — no dictated text is stored)
yazses mark-wrong Flag the last dictation as a misrecognition (feeds the learning corpus)
yazses tune Analyse the learning corpus and propose accuracy improvements; --apply to write changes
yazses corpus Manage the local learning corpus (status, forget, destroy)
yazses model List or download the optional SLM intent-routing model
yazses remote HOST Forward voice typing to a remote host over SSH

Configuration

The settings file lives here:

OS Path
Linux ~/.config/yazses/config.toml
macOS ~/Library/Application Support/yazses/config.toml
Windows %LOCALAPPDATA%\yazses\config.toml

You rarely need to edit it by hand. yazses features, yazses hotkey and yazses vocab change it safely and keep your comments. The essential settings are:

[stt]
model = "base.en"           # tiny.en (fast) | base.en | small.en (accurate); CPU int8
initial_prompt = ""         # vocabulary/context primed into Whisper

[hotkey]
key = "auto"                # hold-to-talk key; "auto" = Right Alt on Linux,
                            # Right Option on macOS, Right Ctrl on Windows
                            # (yazses hotkey set <key>)
command_key = ""            # optional dedicated key that forces command mode
hold_threshold_ms = 500     # how long to hold before recording starts

[audio]
sample_rate = 16000
max_record_seconds = 300    # a single hold is cut at this many seconds

[injection]
backend = "auto"            # auto | type | ydotool | wtype | clipboard
                            # ("xdotool" is not a token — on X11 `auto` already
                            #  uses xdotool; asking for it on Wayland gets ydotool)

[accessibility]
vad_threshold = 0.01        # lower for quiet speech, raise if room noise triggers (yazses mic-level --set)

Every option is documented in the configuration reference and in examples/config.example.toml.

Microphone not working?

If YazSes does nothing and the log shows Silent audio -- discarding, your speech is below the voice-activity threshold. Measure your voice, set the threshold, and restart:

yazses mic-level --set   # measure your voice and set the right threshold
yazses restart

All install options

Upgrading

pipx install yazses always installs the latest published release from PyPI. To upgrade an existing install in place:

pipx upgrade yazses          # upgrade an existing install to the latest release
pipx install --force yazses  # reinstall the latest (if upgrade reports "already at latest")

To pin an exact version, use pipx install yazses==2.15.0. Check what you have with:

yazses --version

yazses doctor also reports the version of the running daemon.

Linux

APT (Debian and Ubuntu). This tracks tagged releases; the one-line installer above remains the recommended route.

bash <(curl -fsSL https://raw.githubusercontent.com/MSKazemi/yazses/main/install-apt.sh)

pipx (any distribution with Python ≥ 3.11):

sudo apt install pipx build-essential python3-dev   # evdev is compiled from source
pipx install 'yazses[desktop]'                      # [desktop] adds the tray + overlay (Qt)
yazses setup                                        # audio/injection deps, input group, ydotoold
# then log out and back in once (the input-group change needs a new login)

Get it from the Snap Store

Snap works on X11, and on GNOME and KDE Wayland through the xdg-desktop-portal RemoteDesktop API. Both snap connect lines are required. A snap cannot connect its own interfaces, and without them the daemon starts and looks healthy but never hears you or never sees the key. See what the snap can and cannot do.

sudo snap install yazses
sudo snap connect yazses:audio-record   # microphone; without it, no audio
sudo snap connect yazses:raw-input      # hold-to-talk key; without it, nothing fires
yazses doctor                           # says if anything is still missing
yazses start

A Snap install does not need yazses setup. Strict confinement stops it from changing host packages, groups or services, so current builds only use it to print the manual permission checklist; the snap already bundles its X11 dependencies. Run yazses doctor and every other YazSes command as your normal desktop user, never through sudo.

From source (for contributors). One command does the whole loop: an editable install, yazses setup provisioning, and a start that bridges the input group so you can test before logging out.

bash scripts/dev-install.sh

macOS

# Homebrew — Apple Silicon only (see below)
brew tap MSKazemi/yazses
brew trust MSKazemi/yazses          # required: Homebrew now gates third-party taps
brew install --cask yazses

# pipx — Apple Silicon: Python ≥ 3.11.  Intel: Python 3.11–3.13 (see below)
pipx install yazses

# App bundle (.dmg) — unsigned developer preview; separate Apple Silicon and Intel builds
# https://github.com/MSKazemi/yazses/releases/latest

On an Intel Mac, use the -macos-x86_64.dmg or pipx, not Homebrew. Since v2.22.0 each release carries both …-macos-arm64.dmg and …-macos-x86_64.dmg. The Homebrew cask is still Apple silicon only: it declares arch: :arm64 and refuses to install rather than installing a broken app. Details in docs/macos-install.md.

⚠ Intel Macs have a Python ceiling set upstream. pipx install yazses needs Python 3.11–3.13 there, and yazses[all] needs 3.11–3.12, because upstream stopped building Intel macOS wheels: onnxruntime published none after 1.23.2 (which has no Python 3.14 build) and torch none after 2.4.1 (no 3.13 build). On Python 3.14 the install fails with a resolver error naming onnxruntime. It looks like a YazSes bug but is not one. On an Intel Mac, yazses doctor shows where you stand against this ceiling, so you learn about it before an upgrade. Apple silicon is unaffected.

Windows

winget install MSKazemi.YazSes                  # may trail the newest release
scoop bucket add yazses https://github.com/MSKazemi/yazses; scoop install yazses
choco install yazses                            # administrator PowerShell
# Installer (.exe) — unsigned developer preview: https://github.com/MSKazemi/yazses/releases/latest
pipx install yazses                             # Python ≥ 3.11

Documentation

mskazemi.com/yazses is the full, searchable documentation site: install guides, the complete CLI and configuration reference, the feature catalog, architecture and troubleshooting.

Guide What it covers
Install on Linux Permissions, injection backends, service setup
Install on macOS Gatekeeper, Accessibility and Microphone permissions
Install on Windows SmartScreen, antivirus exceptions, privacy settings
CLI reference Every command and flag, including macros and vocabulary
Privacy statement What stays on-device and what is never collected
Research: the science of post-keyboard input Cited surveys of eye, voice and muscle/brain input, with every design decision traced to a measurement
Students, researchers and industry Thesis-sized projects with open issues, the research platform, how to cite
Record your own demo GIF How to capture a short hold-to-talk demo

Man page: the Debian package installs one, so man yazses works after an APT or .deb install. In a source checkout, read it with man -l man/yazses.1 (regenerate it with make man). pipx, pip and Snap installs do not put man pages on the system path; use yazses --help there.


Contributing

Contributions of every kind are welcome: bug reports, documentation, translations, packaging and code.

There is nothing to sign. No CLA, no DCO, no sign-off line, no bot to authorise, and no account beyond GitHub. Opening the pull request is the whole contract; section 5 of the Apache 2.0 licence already covers the licence grant.

Ways to start

  • 🚀 First time? Start here. Pick the row that matches what you have in front of you and finish in 15–45 minutes.
  • 🎯 Want the full list? Filter the open tasks by what you have (a browser, a terminal, a specific app or unusual hardware), how much time you have, and whether you want to write code. Each task names the files you may touch, the command that says you are done, and an honest time estimate.
  • ⏱️ Fifteen minutes and no Python? Browser-only tasks can be done entirely in the GitHub web editor, with no clone and no install. Several are open to many contributors at once: translate the README (the introduction and Quick Start alone make a complete PR), add your microphone, share a config for your app or editor, or add your setup to SHOWCASE.md.
  • 🐞 Found a bug or have an idea? Open an issue (the output of yazses doctor resolves most reports on its own) or ask in Discussions.

AI coding tools are optional, and you never need to pay for one. If you use one, read the safe agent guide first, and do not assume YazSes authorises or reimburses its costs. Using Google Jules? Connect Jules to your fork; no upstream collaborator access is needed, and direct upstream Jules remains gated by #447.

Development setup

YazSes is a Python 3.11+ project managed with uv:

git clone https://github.com/MSKazemi/yazses
cd yazses
uv sync
uv run python -m pytest tests/ -v
bash scripts/install-local.sh        # install locally + run as a user service

Before you open a pull request, run the same gates as CI (see CONTRIBUTING.md):

uv run python -m pytest tests/   # tests — must be green
uv run ruff check src tests scripts paper/benchmark   # lint — must be green
uv run mypy src                  # types — advisory (currently clean; don't add errors)

make check runs the tests, lint and the hygiene check in one step. Everything is fully offline: no microphone, model download or optional extras are needed. The suite is large, so a full run takes minutes rather than seconds; that is normal, not a hang. While you work, narrow it with uv run python -m pytest tests/test_foo.py or -k pattern.

No local setup? The repository ships a Dev Container, so opening it in GitHub Codespaces gives you a ready environment in the browser. Documentation, configuration, tests and pure-logic changes work fully there; anything that needs a real microphone, hotkey device or window focus needs a local machine.

Running unreleased code. To install your working tree as the system-wide yazses command (the Snap only ever carries a published release):

uv tool install --from . yazses --force   # (re)install the working tree as the `yazses` command
yazses restart                            # restart the daemon onto the new build
yazses --version                          # confirm the installed build

YazSes is offline-first. Please do not add network calls or telemetry.

Rust HCI exploration (archived)

This repository holds one product with two implementations: two generations of the same idea, not two apps. The one you install and run is the Python implementation on main. An early-stage Rust rewrite lives on the archive/rust-hci-v1 branch. Nothing here builds, installs or depends on it.

How the two implementations compare
Python · main Rust HCI exploration · archive/rust-hci-v1
What it is The shipping app — dictation, file transcription, Meeting Mode, voice commands, macros An early-stage rewrite exploring deeper human–computer interaction: an on-device agent (LLM tool-use, personal memory, editor awareness)
Status ✅ Active — current product (v2.45.0, installed & maintained) ⏸️ Paused / archived — not shipped, not installable
Offline STT ✅ faster-whisper (CPU int8) ✅ Whisper + Moonshine v2 (~9 ms)
Voice commands ✅ regex grammar (+ optional SLM router) → key sequences ✅ via LLM tool-calls
Voice macros · Mid-Thought Undo · Punch-In · Prosody Ink · Ghost Ahead ✅ ❌
Dysfluency-Friendly Mode · learning corpus + yazses tune ✅ ❌
On-device LLM agent (OS tools: git commit, media, notes, screenshots…) ❌ (optional offline text cleanup only) ✅
Personal memory (encrypted on-device vector store) ❌ ✅
Editor context (Neovim / VS Code) ✅ LSP navigation (yazses jump), opt-in; LSP-into-prompt not wired ✅ 5-tier window detection + bridges
Screen-reader integration (AT-SPI / NVDA) ❌ ✅
Packaged & distributed (PyPI, snap, APT) ✅ ❌

Revisiting the Rust effort is a deliberate future decision, not part of day-to-day work here. To look at it:

git checkout archive/rust-hci-v1
cargo build && cargo test --workspace   # optional backends: whisper, moonshine, llama-cpp, ollama, silero

Contributors

Thank you to everyone who has helped build YazSes ✨. Every bug report, documentation fix and patch counts. Contribution types follow the all-contributors emoji key (💻 code · 📖 docs · 🌍 translation · ⚠️ tests · 🛡️ security · 🚧 maintenance):

Mohsen Seyedkazemi Ardebili
Mohsen Seyedkazemi Ardebili

🚧 💻 📖
lntutor
lntutor

📖
HeaTTap
HeaTTap

💻
jackie-cqz
jackie-cqz

💻
Parinitha-26
Parinitha-26

📖
AshSgDe29071999
AshSgDe29071999

💻 📖
Maqbool Ahmed
Maqbool Ahmed

💻
Renji
Renji

💻 ⚠️ 📖 🛡️ 🚇
Sebastian Legarraga
Sebastian Legarraga

💻 📓 📦
YossiMH
YossiMH

🤔 🐛 🔬
Prithvi4904
Prithvi4904

🌍
4nmus
4nmus

🌍
hari
hari

📖 💡
mercael
mercael

🚇 📖 ⚠️ 💡
Tanya Martin-McClellan
Tanya Martin-McClellan

📓 🐛 📦
AtmanActive
AtmanActive

🐛 📓
hoti-code
hoti-code

📓 🐛 📦
Jayavandhini M K
Jayavandhini M K

📖
Vishesh Patel
Vishesh Patel

📖 📓 🐛
fall-water-zxc
fall-water-zxc

📖 📓 🐛 📦 💡
Magnus Olsen
Magnus Olsen

🐛 🤔
Aayaann Kausar
Aayaann Kausar

📖 📓
Aurora
Aurora

💻 ⚠️ 📦 🔬
Elkero
Elkero

📖 🌍 🐛
Guruharishb
Guruharishb

🌍
DeliberateEnsemble
DeliberateEnsemble

💻
doeil1614-ops
doeil1614-ops

🌍
Musab Yusuf Üstün
Musab Yusuf Üstün

🌍
sameer
sameer

📖
Harsh Raj Singhania
Harsh Raj Singhania

📖
Laura Saldarriaga Higuita
Laura Saldarriaga Higuita

🌍
Tiyatrotist
Tiyatrotist

📖
Amoth issac raj
Amoth issac raj

📖
Adharsh Narayan
Adharsh Narayan

📖
LE-VAI
LE-VAI

🤔 🔬
yangjie-AE
yangjie-AE

🌍
Vatsal Raina
Vatsal Raina

💡
sahanaekin7-crypto
sahanaekin7-crypto

🌍
MarekMnahoncak
MarekMnahoncak

💻 ⚠️ 🚇
mrCabez
mrCabez

🌍
Vanam Shashi Haran Ram
Vanam Shashi Haran Ram

🌍
filip-dzivy
filip-dzivy

🚇 ⚠️

Want to be on this list? Pick a good first issue; your first merged pull request adds you.


Citation

YazSes is described in a preprint. If it is useful in your research or projects, please cite:

Seyedkazemi Ardebili, M. (2026). YazSes: An Offline, Privacy-First, Cross-Platform Hold-to-Talk Voice-Dictation System. arXiv:2607.28878. https://arxiv.org/abs/2607.28878

@article{seyedkazemi2026yazses,
  title   = {YazSes: An Offline, Privacy-First, Cross-Platform Hold-to-Talk Voice-Dictation System},
  author  = {Seyedkazemi Ardebili, Mohsen},
  journal = {arXiv preprint arXiv:2607.28878},
  year    = {2026},
  url     = {https://arxiv.org/abs/2607.28878}
}

See CITATION.cff for machine-readable metadata (CFF 1.2.0).

Code signing policy

Windows builds are not code-signed yet. YazSes has applied to the SignPath Foundation free programme for open-source projects and is awaiting approval. The code signing policy on the website covers what gets signed, team roles, who approves each signing request and privacy, and explains how to verify a download today.

License

Apache 2.0. See LICENSE.

If YazSes is useful to you, a ⭐ on GitHub or a mention in your project, blog or talk is the best way to support its development.

The materials in this repository are made available without warranties to the extent permitted by applicable law. Please read the Disclaimer and Responsible-Use Notice before relying on or deploying them. This notice does not change any existing software license or limit rights that cannot legally be waived.

Metadata

Release files for yazses 2.45.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for yazses 2.45.0
File Size Uploaded Provenance
yazses-2.45.0.tar.gz 25.8 MB With provenance Details

Built distribution (wheel)

Table of built distributions (wheels) for yazses 2.45.0
File Interpreter ABI Platform
yazses-2.45.0-py3-none-any.whl Python 3 none any Details

Total release size: 28.1 MB

Release files / yazses-2.45.0.tar.gz

Download URL yazses-2.45.0.tar.gz
Size 25.8 MB
Tags Source
SHA-256 checksum
How to use checksums
14311692f7b915a302ae13cfcd6dd820f9302c74457aa25db096cc7e9fc38983
BLAKE2b-256 checksum
How to use checksums
83d59f3598017aaaf5970eec91f6858e20dc39e4fefe495d701201577d8783db
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Release files / yazses-2.45.0-py3-none-any.whl

Download URL yazses-2.45.0-py3-none-any.whl
Size 2.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
46a2106d4559406f97e85621ddd6cc99a3632caed95037eaf8b5ceb33206b33d
BLAKE2b-256 checksum
How to use checksums
5cefd63968000ac2a8dd32dac3a709a30af9bccd7d0f3e009a427184bbe6070e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Security for yazses 2.45.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for yazses-2.45.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.45.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page