Metadata-Version: 2.4
Name: voxtty
Version: 0.1.0
Summary: Private, local-first voice dictation for Linux and Windows — press Alt+D, speak, and your words are typed into any focused app.
Author: Andrew Dainty
License-Expression: MIT
Project-URL: Homepage, https://voxtty.com
Project-URL: Source, https://github.com/PominausGH/voxtty
Project-URL: Issues, https://github.com/PominausGH/voxtty/issues
Keywords: dictation,speech-to-text,voice,whisper,faster-whisper,stt,accessibility,offline,privacy,wayland
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Adaptive Technologies
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: numpy
Requires-Dist: pyaudio>=0.2.14
Requires-Dist: webrtcvad>=2.0.10
Requires-Dist: pystray>=0.19.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: evdev>=1.6.0; sys_platform == "linux"
Requires-Dist: pynput>=1.7.6; sys_platform == "win32"
Provides-Extra: cleanup
Requires-Dist: anthropic>=0.40.0; extra == "cleanup"
Dynamic: license-file

# Voxtty

Private, local-first voice dictation for Linux and Windows. Press **Alt+D**, speak, and your words are typed into whatever app has focus — transcribed entirely on your own machine.

Site: [voxtty.com](https://voxtty.com)

## Features

- **Local transcription** — runs [faster-whisper](https://github.com/SYSTRAN/faster-whisper) on-device; no audio ever leaves your machine
- **Global hotkey (Alt+D)** — press to start dictating, press again to stop, from anywhere
- **Types into any focused app** — terminal, browser, editor, chat, anything
- **Voice activity detection** — knows when you've stopped talking, no fixed timers
- **Offline rule-based cleanup** — punctuation/capitalization/spacing fixes, on by default, no network calls
- **Custom word replacements** — teach it names, jargon, and spellings (case-insensitive), applied locally
- **System tray icon** — runs quietly in the background via a systemd user service, starts on login
- **Optional wake word** ("hey Jarvis") — experimental alternative to the hotkey; may false-trigger in some environments, Alt+D is the reliable trigger
- **Optional AI cleanup** — opt-in only, sends the transcript text (never audio) to the Claude API to strip fillers and polish punctuation; off by default, requires your own Anthropic API key

## Requirements

- **Linux**: Ubuntu (Wayland), Python 3.10+, `ydotool` for typing, `portaudio` for audio capture
- **Windows**: Windows 10/11, Python 3.10+
- A microphone

## Installation (Linux)

```bash
git clone https://github.com/PominausGH/voxtty.git
cd voxtty
./setup.sh
```

`setup.sh` installs system dependencies (`ydotool`, `portaudio`, etc.), adds you to the `input` group, creates a Python virtual environment, and installs Voxtty as a **systemd user service** that starts automatically on login.

**Log out and back in** after setup for the `input` group change to take effect. Then press **Alt+D** anywhere to start dictating.

### With pipx

`setup.sh` is the recommended path because it installs the system packages for
you. If you would rather manage it yourself, three of Voxtty's dependencies
(`evdev`, `PyAudio`, `webrtcvad`) publish no wheels and are compiled at install
time, so you need a compiler and the relevant headers **first**:

```bash
# Debian / Ubuntu
sudo apt install gcc python3-dev portaudio19-dev ydotool
# Fedora
sudo dnf install gcc python3-devel portaudio-devel ydotool

pipx install voxtty
voxtty --install-service      # register the systemd user service and start it
```

Without those system packages `pipx install voxtty` fails with compiler errors.

### Arch Linux

A `voxtty-git` PKGBUILD lives in [`packaging/aur/`](packaging/aur/). It is not
on the AUR yet — Arch has suspended new AUR account registration while dealing
with a wave of malicious package uploads — so build it directly for now:

```bash
git clone https://github.com/PominausGH/voxtty.git
cd voxtty/packaging/aur
makepkg -si
systemctl --user enable --now voxtty.service
```

## Installation (Windows)

```powershell
git clone https://github.com/PominausGH/voxtty.git
cd voxtty
.\setup.bat
```

`setup.bat`/`setup.ps1` creates a Python virtual environment, installs dependencies, and registers a **Task Scheduler** task (runs at logon, under your own user, no elevation) that starts Voxtty automatically. Press **Alt+D** anywhere to start dictating.

A few Windows-specific things worth knowing:
- Alt+D is also a built-in "focus the address bar" shortcut in most browsers and File Explorer — both will fire together, same as the non-exclusive hook behavior on Linux.
- A global keyboard hook plus synthetic keystroke injection is a common antivirus/SmartScreen heuristic for keylogger-style tools. Voxtty isn't code-signed yet, so don't be surprised if your AV flags it on first run — it's a false positive from the technique, not the intent.
- Logs and the AI-cleanup API key file both live under `%LOCALAPPDATA%\voxtty` (Windows has no XDG-style data/config split).

## Usage (Linux)

```bash
systemctl --user status voxtty    # check status
systemctl --user restart voxtty   # restart
systemctl --user stop voxtty      # stop
journalctl --user -u voxtty -f    # live logs
```

Logs are also saved to `~/.local/share/voxtty/voxtty.log`.

`toggle_voxtty.sh` can be bound to a custom keyboard shortcut (e.g. in GNOME Settings) as an alternative to Alt+D. This is Linux-only — Alt+D's global hook works uniformly across Windows desktop sessions, so there's no equivalent need on Windows.

## Usage (Windows)

```powershell
schtasks /Query /TN Voxtty    # check status
schtasks /End /TN Voxtty      # stop
schtasks /Run /TN Voxtty      # start
```

Logs are saved to `%LOCALAPPDATA%\voxtty\voxtty.log`.

## Configuration

Voxtty writes a `config.json` in the repo directory on first run (git-ignored — your local settings, not committed). Notable options:

- `whisper_model` — Whisper model size (default `small.en`)
- `microphone_name` — substring to match your preferred input device
- `wake_word` / `wake_word_threshold` — experimental voice-triggered start, off the hotkey
- `rule_cleanup_enabled` — local, offline punctuation/formatting cleanup (default `true`)
- `cleanup_enabled` — opt-in AI cleanup pass via the Claude API (default `false`)
- `word_replacements` — a `{"heard": "typed"}` map for custom dictionary entries

To enable AI cleanup, set `cleanup_enabled: true` in `config.json` and put your Anthropic API key in the `env` file created by setup (`~/.config/voxtty/env` on Linux, `%LOCALAPPDATA%\voxtty\env` on Windows), then restart.

## Pricing

This repo is the free, open-source core — full local dictation, no license gate. See [voxtty.com/#pricing](https://voxtty.com/#pricing) for the current Pro roadmap.

## License

MIT — see [LICENSE](LICENSE).
