Metadata-Version: 2.4
Name: whspr
Version: 1.0.0
Summary: An interactive dictation tool for local speech recognition using OpenAI's Whisper models.
Project-URL: Homepage, https://github.com/KenanHanke/whspr
Author: Kenan Hanke
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Requires-Dist: faster-whisper<2,>=1.1
Requires-Dist: pyperclip
Provides-Extra: gpu
Requires-Dist: nvidia-cublas-cu12<13,>=12.6; extra == 'gpu'
Requires-Dist: nvidia-cudnn-cu12<10,>=9.6; extra == 'gpu'
Description-Content-Type: text/markdown

# whspr

A minimalist dictation tool for local speech recognition using OpenAI's Whisper models.
Its interface is fully keyboard-driven and sound-based so as not to interfere with
windowing or application focus.

Processing is done locally using `faster-whisper`. If `whspr[gpu]` optional dependencies
are installed and an Nvidia GPU is available, the model `whisper-large-v3-turbo`
will be used; otherwise, `whisper-small.en` will be used. `whspr` is currently only
available on Linux and can be installed from [PyPI](https://pypi.org/project/whspr/).

## Usage

Bind the following commands to your preferred keyboard shortcuts (examples given here).

```bash
whspr            # Super+C
whspr --paste    # Super+V
whspr --cancel   # Super+X
```

In the example given, `Super+C` and `Super+V` will both start or stop dictation and copy the
result to the clipboard. The difference is that `Super+V` will additionally paste the result
into the currently focussed application. `Super+X` will cancel any dictation currently in progress.
Sounds will indicate when `whspr` is listening and when it has finished processing.

`whspr` can also be accessed from within Python:

```python
from whspr import transcribe
result = transcribe("path/to/audio.mp3")
```

## Installation

`whspr` depends on:

- the `aplay`, `arecord`, `ydotool` commands. The former two are part of the
  `alsa-utils` package and installed on most distros by default. `ydotool` is optional
  and only required for the `--paste` flag (see [Usage](#usage)).
- a clipboard backend compatible with `pyperclip`, e.g. `wl-clipboard` on Wayland or `xclip` on X11.
- for optional GPU-accelerated speech recognition, an Nvidia GPU and drivers are required.

On Ubuntu, simply run:

```bash
sudo apt update && sudo apt install -y alsa-utils wl-clipboard xclip ydotool pipx
pipx install whspr[gpu]  # gpu support is optional; omit [gpu] if it's not desired
whspr --finish-setup     # optional to pre-load the model from the internet before its first use
```
