Metadata-Version: 2.4
Name: yazses
Version: 1.0.0
Summary: Local, offline voice dictation for Linux, macOS, and Windows — hold a key, speak, release
Project-URL: Homepage, https://github.com/novafabric/yazses
Project-URL: Repository, https://github.com/novafabric/yazses
Project-URL: Bug Tracker, https://github.com/novafabric/yazses/issues
Author-email: Mohsen Seyedkazemi Moghadam <mohsen.seyedkazemi@gmail.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: accessibility,dictation,linux,speech-to-text,voice,whisper
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Requires-Dist: cryptography>=48.0.0
Requires-Dist: evdev>=1.9.3; sys_platform == 'linux'
Requires-Dist: faster-whisper>=1.2.1
Requires-Dist: numpy>=2.4.5
Requires-Dist: onnx-asr>=0.11.0
Requires-Dist: pillow>=12.2.0; sys_platform == 'win32'
Requires-Dist: platformdirs>=4.9.6
Requires-Dist: pyobjc-framework-applicationservices>=12.1; sys_platform == 'darwin'
Requires-Dist: pyobjc-framework-avfoundation>=12.1; sys_platform == 'darwin'
Requires-Dist: pyobjc-framework-cocoa>=12.1; sys_platform == 'darwin'
Requires-Dist: pyobjc-framework-quartz>=12.1; sys_platform == 'darwin'
Requires-Dist: pystray>=0.19.5; sys_platform == 'win32'
Requires-Dist: python-xlib>=0.33; sys_platform == 'linux'
Requires-Dist: pywin32>=311; sys_platform == 'win32'
Requires-Dist: rumps>=0.4.0; sys_platform == 'darwin'
Requires-Dist: sounddevice>=0.5.5
Requires-Dist: typer>=0.25.1
Provides-Extra: all
Requires-Dist: bleak>=3.0.2; extra == 'all'
Requires-Dist: kokoro-onnx>=0.4.9; extra == 'all'
Requires-Dist: llama-cpp-python>=0.3.23; extra == 'all'
Requires-Dist: onnxruntime>=1.20; extra == 'all'
Requires-Dist: praat-parselmouth>=0.4.6; extra == 'all'
Requires-Dist: pygls>=2.1.1; extra == 'all'
Requires-Dist: pynvim>=0.6.0; extra == 'all'
Requires-Dist: pyserial>=3.5; extra == 'all'
Requires-Dist: pyside6>=6.8; extra == 'all'
Requires-Dist: soundfile>=0.13; extra == 'all'
Provides-Extra: ble
Requires-Dist: bleak>=3.0.2; extra == 'ble'
Provides-Extra: emg
Requires-Dist: pyserial>=3.5; extra == 'emg'
Provides-Extra: lsp
Requires-Dist: pygls>=2.1.1; extra == 'lsp'
Requires-Dist: pynvim>=0.6.0; extra == 'lsp'
Provides-Extra: overlay
Requires-Dist: pyside6>=6.8; extra == 'overlay'
Provides-Extra: prosody
Requires-Dist: praat-parselmouth>=0.4.6; extra == 'prosody'
Provides-Extra: slm
Requires-Dist: llama-cpp-python>=0.3.23; extra == 'slm'
Provides-Extra: tts
Requires-Dist: kokoro-onnx>=0.4.9; extra == 'tts'
Requires-Dist: onnxruntime>=1.20; extra == 'tts'
Requires-Dist: soundfile>=0.13; extra == 'tts'
Description-Content-Type: text/markdown

# YazSes

[![Tests](https://github.com/novafabric/yazses/actions/workflows/test.yml/badge.svg)](https://github.com/novafabric/yazses/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/yazses)](https://pypi.org/project/yazses/)
[![Snap Store](https://snapcraft.io/en/dark/install.svg)](https://snapcraft.io/yazses)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

**Hold a key → speak → release.** On-device voice dictation that types into any app, plus voice commands and macros — entirely offline. No cloud. No API key. No subscription.

---

## Two versions of YazSes

This repo holds **one product** with **two implementations** — not two separate apps, but two generations of the same idea. The one you install and run is **Part 1 (Python)**, on this `main` branch.

| | **Part 1 — Python** · `main` | **Rust HCI exploration** · `archive/rust-hci-v1` |
|---|---|---|
| What it is | The shipping app — voice dictation, 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** (v0.9.0, installed & maintained) | ⏸️ **Paused / archived** — not shipped, not installable |
| Hold-to-talk dictation | ✅ | ✅ |
| Offline STT | ✅ faster-whisper | ✅ Whisper + Moonshine v2 (~9 ms) |
| Voice commands → key sequences | ✅ regex grammar (+ optional SLM router) | ✅ via LLM tool-calls |
| Voice macros · Mid-Thought Undo · Punch-In · Prosody Ink · Ghost Ahead | ✅ | ❌ |
| Dysfluency-Friendly Mode · learning corpus + `yazses tune` | ✅ | ❌ |
| Friendly CLI (`-h`, examples, `yazses update`) | ✅ | ❌ |
| On-device **LLM agent** (20 tools: git commit, media, notes, screenshots…) | ❌ (optional offline text cleanup only) | ✅ |
| **Personal memory** (encrypted on-device vector store) | ❌ | ✅ |
| Editor context (Neovim / VS Code) | ✅ LSP context, opt-in | ✅ 5-tier window detection + bridges |
| Screen-reader accessibility (AT-SPI / NVDA) | ❌ | ✅ |
| Packaged & distributed (PyPI, snap, APT, …) | ✅ | ❌ |

**Bottom line:** if you want YazSes, use **Part 1** (this branch). The Rust branch is kept only for reference — nothing on `main` builds, installs, or depends on it. The Rust effort aimed at a more ambitious agentic HCI layer but was left in early stages; revisiting it is a deliberate future decision, not part of day-to-day work here.

---

## Quick Start

**Step 1 — Install**

| Platform | Command |
|---|---|
| **Linux** (Debian/Ubuntu) | `bash <(curl -fsSL https://raw.githubusercontent.com/novafabric/yazses/main/install-apt.sh)` |
| **Linux** (any distro) | `pipx install yazses` |
| **macOS** | `brew tap novafabric/yazses && brew install --cask yazses` |
| **Windows** | `winget install NovaFabric.YazSes` |

**Step 2 — Set up**

```sh
yazses doctor               # check everything is ready
yazses model pull qwen3-7b  # download the AI model (~5 GB, one-time)
yazses enroll               # calibrate your microphone (30 seconds)
yazses start                # start the daemon
```

**Step 3 — Use it**

| OS | Hold this key | Say anything |
|---|---|---|
| Linux | `Space` | "open terminal", "commit add new feature", "type hello world" |
| macOS | `Right Option` | "set volume to 50", "take a screenshot called mockup" |
| Windows | `Right Ctrl` | "remember my meeting is at 3pm", "what did I tell you yesterday?" |

Release the key — YazSes acts within one second.

> **First time on macOS?** Right-click the app → Open (Gatekeeper), then grant Accessibility + Microphone when prompted.
>
> **First time on Windows?** If SmartScreen warns you, click **More info → Run anyway**.
>
> **First time on Linux?** Run `sudo usermod -aG input "$USER"` and re-login before starting.

---

## What you can say

YazSes understands natural language and maps it to 20 built-in actions:

| Say something like… | What happens |
|---|---|
| *"type hello world"* | Types text at the cursor |
| *"commit added login feature"* | Runs `git add -A && git commit -m "added login feature"` |
| *"open main.py"* | Opens the file |
| *"go to function parse_config"* | Jumps to the symbol via LSP |
| *"set volume to 30"* | Sets system volume |
| *"take a screenshot called diagram"* | Saves `diagram.png` |
| *"remember my password expires on June 1"* | Stores in encrypted local memory |
| *"what did I remember about passwords?"* | Queries local memory |
| *"set a timer for 25 minutes"* | Starts a countdown |
| *"open VS Code"* | Launches the application |
| *"press Control S"* | Sends the key chord |

---

## How it works

```
Hold hotkey → record audio → speech-to-text → local LLM → pick tool → execute
```

Everything runs on your CPU. The LLM (Qwen3-7B by default) reads the transcript and decides which of the 20 tools to call. Result appears in the focused window within ~1 second on a modern laptop.

**Models used:**
- **STT:** Moonshine v2 (9 ms, streaming) for short commands · Whisper-large-v3-turbo for long dictation
- **LLM:** llama.cpp with GBNF tool-call grammar (Qwen3-7B default) · Ollama backend optional

---

## Requirements

| | |
|---|---|
| **OS** | Linux (primary) · macOS 13+ · Windows 10+ |
| **RAM** | 8 GB minimum · 16 GB recommended |
| **Disk** | 6–10 GB for the default model |
| **CPU** | 4+ cores · no GPU required |
| **Mic** | Any USB or built-in microphone |

---

## Key features

- **Fully offline** — no audio, no text, no data leaves the machine by default
- **Agent, not just dictation** — understands intent, not just words
- **Dual STT stack** — fast streaming for commands, accurate long-form for dictation
- **Personal memory** — encrypted local vector store, voice-queryable
- **Editor integration** — Neovim and VS Code LSP context improves accuracy on code identifiers
- **Accessibility** — AT-SPI (Linux) and NVDA (Windows) screen-reader support; Talon coexistence
- **EMG support** — works with muscle sensors for motor-disability use cases

---

## CLI commands

| Command | Description |
|---|---|
| `yazses start` | Start the YazSes daemon in the background |
| `yazses stop` | Stop the running daemon |
| `yazses status` | Show daemon status — queries the daemon over IPC when reachable |
| `yazses doctor` | Check system prerequisites (mic, AT-SPI, injection backend, permissions) |
| `yazses enroll` | Calibrate your microphone — records 20 utterances to tune `vad_threshold` and `min_silence_ms` |
| `yazses mic-level` | Measure mic speech level and recommend (or set with `--set`) the VAD threshold |
| `yazses overlay` | Launch the sonar voice-activity overlay in the foreground (requires `overlay` extra) |
| `yazses inject TEXT` | Type arbitrary text into the focused window — useful to test injection without speaking |
| `yazses test` | End-to-end self-test: focuses a window and types `YazSes OK` to confirm injection works |
| `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` | Download and manage SLM intent-routing models |
| `yazses remote HOST` | Forward voice typing to a remote host over SSH |

---

## Configuration

Config file location:

| OS | Path |
|---|---|
| Linux | `~/.config/yazses/config.toml` |
| macOS | `~/Library/Application Support/yazses/config.toml` |
| Windows | `%APPDATA%\yazses\config.toml` |

Essential settings:

```toml
[hotkey]
key = "auto"               # Space (Linux) / right_option (macOS) / right_ctrl (Windows)
hold_threshold_ms = 500    # how long to hold before recording starts

[llm]
model_path = ""            # empty = use the model from `yazses model pull`

[stt]
backend = "auto"           # "moonshine" (fast) | "whisper" (accurate) | "auto"

[audio]
device = ""                # empty = system default microphone

[memory]
passphrase = ""            # set a passphrase to encrypt the memory store
```

See the [CLI reference](docs/cli-reference.md) for all options.

### Microphone not working?

If YazSes does nothing and the log shows `Silent audio -- discarding`:

```sh
yazses mic-level --set   # measure your voice and set the right threshold
yazses stop && yazses start
```

---

## All install options

### Linux

```bash
# APT repo — Debian / Ubuntu (recommended)
bash <(curl -fsSL https://raw.githubusercontent.com/novafabric/yazses/main/install-apt.sh)

# PPA — Ubuntu
sudo add-apt-repository ppa:novafabric/yazses && sudo apt install yazses

# Snap
sudo snap install yazses --classic

# AUR — Arch / Manjaro
yay -S yazses

# pipx (Python v0.4.x)
sudo apt install libportaudio2 xdotool xclip pipx
pipx install yazses
```

### macOS

```sh
# Homebrew Cask (recommended)
brew tap novafabric/yazses && brew install --cask yazses

# Direct download
# https://github.com/novafabric/yazses/releases/latest
```

### Windows

```powershell
# winget (recommended)
winget install NovaFabric.YazSes

# Direct download
# https://github.com/novafabric/yazses/releases/latest
```

---

## Documentation

| | |
|---|---|
| [Install on Linux](docs/install-linux.md) | Detailed Linux guide — permissions, injection backends, service setup |
| [Install on macOS](docs/macos-install.md) | Gatekeeper, Accessibility, Microphone permissions |
| [Install on Windows](docs/windows-install.md) | SmartScreen, antivirus exceptions, privacy settings |
| [CLI reference](docs/cli-reference.md) | All commands and flags |
| [Plugin SDK](docs/plugin-sdk.md) | Adding custom tools and voice commands |
| [Privacy statement](docs/privacy-statement.md) | What stays on-device, what is never collected |
| [Migration v0.4 → v1.0](docs/migration-v04-to-v10.md) | Upgrading from the Python version |

---

## Development

YazSes (Part 1) is a Python project managed with `uv`:

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

### Rust HCI exploration (archived)

The early-stage Rust rewrite lives on the **`archive/rust-hci-v1`** branch, not on
`main`. It is not built or installed by anything here — see *Two versions of
YazSes* above for what it does and doesn't have. To look at it:

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

---

## License

Apache 2.0 — see [LICENSE](LICENSE).

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