Skip to content

Installation

Requirements

  • Linux on Wayland with GNOME Shell 47+ or KDE Plasma 6 — see Compatibility for what works where
  • Working microphone
  • ~2 GB disk space for models
  • Python 3.10–3.14 — source install only; the prebuilt packages bundle their own runtime

Tested on Fedora and NixOS.

Quick install (prebuilt packages)

The easiest path. Download the latest app package, the Parakeet pack with the speech recognition model and a language pack from the Releases page and install them together — just take the latest of each; the app and pack version numbers are independent and need not match:

sudo apt install ./easyspeak_*_amd64.deb ./easyspeak-stt-parakeet_*_all.deb ./easyspeak-lang-en_*_all.deb

sudo dnf install ./easyspeak-*.x86_64.rpm ./easyspeak-stt-parakeet-*.noarch.rpm ./easyspeak-lang-en-*.noarch.rpm

Besides English there are German, Italian, French and Spanish packs (easyspeak-lang-de, -it, -fr, -es). Install the one for the language you speak and set EASYSPEAK_LANGUAGE to its code, see Usage; you dictate in that language, EasySpeak answers in it, and most commands take that language's words too. The English commands work in every language.

This bundles the Python runtime, Piper, the GNOME Shell extension, and the speech models — no pip/uv step and no compiler. Log out and back in once after the first launch so GNOME loads the bundled extension. See the Packaging guide for offline notes, more languages, and hold-to-dictate setup.

NixOS

The flake carries the runtime tools, the Parakeet model, the English language pack and the sound theme, so there is no system-package step:

nix run github:ctsdownloads/easyspeak

Another language is one more command, then EASYSPEAK_LANGUAGE=de (or it, fr, es) when running:

nix run github:ctsdownloads/easyspeak#lang -- de

Log out and back in once after the first launch so GNOME loads the bundled Shell extension. See Contributing for the dev shell.

Install from source

For development, or to run the latest unreleased code, install from the repository. This path needs system build dependencies and a supported Python.

Python

EasySpeak is tested against Python 3.10, 3.11, 3.12, 3.13, and 3.14. Fedora 43's default python3 (3.14) works out of the box.

1. System packages

sudo dnf install \
  pipewire-utils \
  wireplumber \
  at-spi2-core \
  python3-gobject \
  qutebrowser \
  glib2 \
  ffmpeg-free \
  pulseaudio-utils \
  sound-theme-freedesktop \
  wl-clipboard \
  portaudio-devel \
  python3-devel \
  gcc

wl-clipboard is what dictation uses to place text. It types by putting the text on the clipboard and sending a paste keystroke, because accessibility-level insertion is silently ignored by Chromium-based applications — they accept the call, report success, and discard the text. Without wl-clipboard, dictation falls back to that path and quietly does nothing in a browser.

python3-gobject is needed for dictation. The tray menu's About EasySpeak dialog also needs libadwaita, which ships with any GNOME desktop. Elsewhere it's optional: without it, EasySpeak tells you its version and shows the details in a notification instead. For the graphical dialog on other desktops, install it too:

sudo dnf install libadwaita

On KDE Plasma, kdialog shows the About information in Plasma's own look instead, if it's installed (sudo dnf install kdialog).

Optionally, sudo dnf install python3-adblock gives qutebrowser Brave's element-level ad blocker. EasySpeak configures the browser to use it when it is present and falls back to host blocking when it is not, so this is worth having: ad overlays are numbered like any other element, so they take link hints away from the page underneath.

2. Piper TTS

mkdir -p ~/.local/bin
cd ~/.local/bin
wget https://github.com/rhasspy/piper/releases/download/2023.11.14-2/piper_linux_x86_64.tar.gz
tar xzf piper_linux_x86_64.tar.gz
rm piper_linux_x86_64.tar.gz

echo 'export PATH="$HOME/.local/bin/piper:$PATH"' >> ~/.bashrc
source ~/.bashrc

mkdir -p ~/.local/share/piper
cd ~/.local/share/piper
wget -O en_US-amy-medium.onnx \
  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/amy/medium/en_US-amy-medium.onnx"
wget -O en_US-amy-medium.onnx.json \
  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/amy/medium/en_US-amy-medium.onnx.json"

3. Clone the repository

git clone https://github.com/ctsdownloads/easyspeak.git ~/easyspeak
cd ~/easyspeak

4. Python packages

The simplest path is uv. Run it from the cloned repository and it does everything in one step — it creates and updates the virtual environment, installs every dependency declared in pyproject.toml, and launches EasySpeak from inside that environment. There's no separate "install the requirements" command; the first uv run sets it all up for you:

cd ~/easyspeak
uv run easyspeak

Prefer plain pip? Create a virtual environment first — most distributions ship their system Python as externally managed, so installing into it directly fails:

python3 -m venv ~/easyspeak-venv
source ~/easyspeak-venv/bin/activate
cd ~/easyspeak
pip install -e .
easyspeak

A Python-only installation has no bundled speech-recognition model, and EasySpeak stays offline by default (EASYSPEAK_OFFLINE=strict), so on first run it reports the model as missing. Set EASYSPEAK_OFFLINE=relaxed to have it fetch Parakeet (about 640 MB) from Hugging Face for you, or Whisper's base.en (about 140 MB) with EASYSPEAK_STT=whisper; or install a language pack, whose Whisper model is used until Parakeet is installed.

Head tracking (optional)

Head tracking requires a webcam and additional dependencies. With uv, add the extra to the run command and it pulls them in for you:

uv run --extra head-tracking easyspeak

With a plain pip virtual environment, install the extra before running easyspeak:

pip install '.[head-tracking]'

The head-tracking extra pulls in sixdrepnet and opencv-python.