# Kokoro Read-Aloud – select text in any app, hear it read locally

> Source: <https://github.com/sayed-qutob-work/kokoro-read-aloud>
> Published: 2026-11-20 21:15:10+00:00

**Key takeaway:** The default CPU build runs Paradee-8M, an 8.5 MB copy of Kokoro-82M, with no GPU or PyTorch, starting speech about 30 ms after text arrives and synthesizing 50–70× faster than playback on an i5-12400F.

**Select text in any app, press Ctrl+Alt+R, and a neural voice running on your
own machine reads it aloud.**

No GPU needed: the default build is a 0.2 GB download that runs
[Paradee-8M](https://github.com/sahilmahendrakar/paradee), an 8.5 MB copy of
[Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M), on the CPU. On an
i5-12400F it starts speaking about 30 ms after it gets the text, and
synthesizes 50 to 70 times faster than it plays. With an NVIDIA GPU, the GPU build adds
Kokoro itself and its 28 voices. It runs on Linux (Omarchy, Fedora GNOME) and
Windows 11, and your text never leaves the machine.

[Install](#install) • [Usage](#usage) • [Settings](#settings) •
[Troubleshooting](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/troubleshooting.md) •
[Report a bug](https://github.com/sayed-qutob-work/kokoro-read-aloud/issues/new?template=bug_report.yml)

- **Light.** 0.2 GB to download, 0.6 GB on disk, about 0.35–0.7 GB of RAM
while it runs, and no PyTorch. Four voices; the GPU build has 28.
- **Fast listening that stays clear.** Listen at up to 3× with the voice's
pitch kept, and see the fastest speed your machine keeps up with.
- **It shows where you are.** A caption strip shows the sentence being read,
whatever app the text came from.
- **The VRAM back when you need it.** With the GPU build on Omarchy, the bar
switches between Kokoro on the GPU, Paradee on the CPU and off, so a game
or a local LLM can have the GPU.
- **Pinned and offline.** Packages and model files are pinned to tested
versions and hashes, and on Linux the server makes no network connection
after setup.
- **Windows 11 support.** The same server, hotkeys and settings as on Linux.
Retested 2026-10-19 in a VM without a GPU, before the CPU build became
Paradee; the new CPU build is not tested on Windows yet.

The details behind each of these are in
[how it works](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/how-it-works.md).

- **English only.** There are 28 American and British voices, four on the CPU. Other languages
in the Latin alphabet get English pronunciation, and other scripts and emoji
are skipped.
- **Download size.** The CPU build downloads about 0.2 GB and takes about
0.6 GB on disk. The GPU build, which adds Kokoro's 28 voices, downloads
about 4 GB and takes about 7 GB.
- **The GPU build needs NVIDIA.** It is for Kokoro's 28 voices and its better
sound, not for speed. Paradee's sound quality is slightly lower, most
noticeably on headphones, but on an i5-12400F it starts speaking as fast as
the GPU does ([measurements](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/how-it-works.md#cpu-or-gpu) ).
- **No in-place highlighting on Linux,** only the caption strip.

| Platform | Tested | 
|---|---|
| Omarchy 4.0.4 (Hyprland), NVIDIA | Clean GPU install from this repository, 2026-10-18; the CPU build's packages and model installed and read aloud, 2026-11-01 | 
| Fedora 44 (GNOME), NVIDIA | Last run 2026-09-30; the installer not yet run there | 
| Windows 11 | Fresh install in a VM without a GPU, 2026-10-19, before the CPU build became Paradee; the GPU path last tested mid-August 2026 | 

On Linux, one command, `kokoroctl setup`, installs everything without root,
outside the code folder. Outside Omarchy it needs a few system packages first.

## **Omarchy** (Hyprland)

```
omarchy plugin add https://github.com/sayed-qutob-work/kokoro-read-aloud --enable
```

1. Omarchy asks you to confirm, because plugins run unsandboxed in the shell. Then it asks which bar section to use.
2. A Kokoro icon appears there, as five dim dots. Click it, and pick a build:
**CPU** (about 0.2 GB, the default) or**GPU** (about 4 GB, NVIDIA only).
3. A notification says when Kokoro is ready. Ctrl+Alt+R, T and S are bound for you.

The caption strip and the More settings window also need Tk, the one package a fresh Omarchy lacks. Reading works without it. To add them, any time:

```
sudo pacman -S --needed tk
```

To set up from a terminal instead:

```
~/.config/omarchy/plugins/io.github.sayed-qutob-work.kokoro-read-aloud/linux/kokoroctl setup
```

## **Fedora** (GNOME)

```
sudo dnf install python3-tkinter python3-xlib portaudio wl-clipboard jq curl libnotify
git clone https://github.com/sayed-qutob-work/kokoro-read-aloud.git
cd kokoro-read-aloud
linux/kokoroctl setup
```

Setup doesn't bind GNOME shortcuts; it prints the three commands. Bind
them in Settings > Keyboard > View and Customize Shortcuts > Custom Shortcuts.
`kokoroctl setup` has not been run on Fedora yet; please
[report](https://github.com/sayed-qutob-work/kokoro-read-aloud/issues/new?template=bug_report.yml)
what happens.

## **Windows 11** (retested 2026-10-19 in a VM, without a GPU)

You need [Python 3.12](https://www.python.org/downloads/) (exactly 3.12),
[AutoHotkey v2](https://www.autohotkey.com/) and the
[Visual C++ runtime](https://aka.ms/vs/17/release/vc_redist.x64.exe), which
the GPU build's torch needs and a fresh Windows lacks
(`winget install Microsoft.VCRedist.2015+.x64`).

In PowerShell or Command Prompt:

```
git clone https://github.com/sayed-qutob-work/kokoro-read-aloud.git
cd kokoro-read-aloud
py -3.12 -m venv env
env\Scripts\python.exe -m pip install -r requirements-cuda.txt
env\Scripts\python.exe tts_server.py
```

Without an NVIDIA GPU, install `requirements.txt` instead of
`requirements-cuda.txt`.

When it prints `ready on http://127.0.0.1:5111`, start
`read_aloud.ahk`. To start everything at login, put a shortcut to
`start_tts.vbs` in `shell:startup`.

What setup does, where the files go, and the Windows details are in
[install.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/install.md).

| Keys | Action | 
|---|---|
| `Ctrl+Alt+R` | Read the selection | 
| `Ctrl+Alt+T` | Read the clipboard as-is | 
| `Ctrl+Alt+S` | Stop | 

The hotkeys work wherever text can be selected, including terminals and
PDFs. On Linux the selection is read without copying it. On Windows the
hotkey copies it and then puts your clipboard back; Windows Terminal needs no
setting, and in VS Code's terminal you turn on
[copy-on-select](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/install.md#optional-extras).

- 
**The Omarchy bar icon:**
  - left click opens the panel: GPU / CPU / Off, voice, speed, captions;
  - right click turns the model off or on;
  - middle click stops.
 See [omarchy.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/omarchy.md) .
- 
**The caption strip** is off by default. Turn it on with Captions in the
Omarchy panel, or with`systemctl --user enable --now kokoro-overlay` on
any Linux ([options](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/settings.md#caption-strip) ).
- 
**On Windows,** the spoken word is also tinted in the app itself: in
Firefox, in Notepad, and in Chrome or Edge with the bundled extension
([details](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/windows.md) ).
- 
**From a terminal** on Linux,`kokoroctl` turns the model off and on,
switches GPU and CPU, and changes the voice and speed
([reference](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/omarchy.md#kokoroctl) ).

- **Your text stays on your machine.** The model runs locally, and the
server listens only on 127.0.0.1.
- **No network after setup, on Linux.** The server loads the pinned model
files from disk in Hugging Face's offline mode. It was tested with no
network at all. On Windows, see[install.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/install.md#windows) .
- **Web pages can't use it.** The server refuses requests from browser tabs,
including DNS rebinding, and accepts only JSON from local programs. Until
2026-10-18 a web page could make it speak and read what it was reading:[the three attacks, measured before and after the fix](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/security.md) .
Any program running as you can still use it, as with any local service.
- **Other accounts can't use it, on Linux.** The server refuses programs
of other users on the same computer, and the hotkey only sends text to a
server you run ([how](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/security.md#postscript-2026-11-14-other-accounts-on-the-same-machine) ).
- **The clipboard is never polled.** On Linux the hotkey doesn't touch it at
all.
- **Pinned downloads.** Every package and every model file is checked
against a pinned hash, and so is uv when setup downloads it.
- **No root,** except for the system packages you install yourself.
- **The Omarchy plugin runs unsandboxed** in the shell, like every Omarchy
plugin.
- **The logs stay local.**`read_aloud.log` keeps a short excerpt of each
selection, for diagnosing wrong reads. On Linux only you can read them.

The Settings panel changes the voice, speed, pauses, output device and caption strip. It also shows the fastest speed your machine keeps up with. To open it:

- **Windows:** the tray icon.
- **Omarchy:** More settings, in the bar panel. The voice and speed are also
right in the panel.
- **GNOME:** "Kokoro Settings" in the app grid.

Settings are saved in `settings.json` and survive a restart. The keys, all 28
voices with their grades, and the caption options are in
[settings.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/settings.md).

|  | Update | Uninstall | 
|---|---|---|
| Omarchy | `omarchy plugin update io.github.sayed-qutob-work.kokoro-read-aloud` , then`omarchy restart shell` and`kokoroctl setup` | `kokoroctl uninstall` , then`omarchy plugin remove io.github.sayed-qutob-work.kokoro-read-aloud` | 
| Fedora | `git pull` , then`kokoroctl setup` | `kokoroctl uninstall` , remove the GNOME shortcuts, delete the folder | 
| Windows | `git pull` , the same`pip install -r` again, restart the server | [Three steps](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/install.md#removing) | 

`kokoroctl uninstall` asks before it does anything. It keeps your settings
unless you pass `--purge`. More in [install.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/install.md#removing).

- **Something failed:** read`server.log` first. On Linux,`kokoroctl log` opens it.
- **Reads stall or stutter:** lower the reading speed until the panel's
warning clears, or use the GPU.
- **"Kokoro is off" or "still loading":** turn it on from the bar, or with`kokoroctl cpu` (or`gpu` ). Loading takes 4–6 s.
- **"No matching distribution found for kokoro" on Windows:** the venv isn't
Python 3.12.

More cases, and what each log holds, are in
[troubleshooting.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/troubleshooting.md).

A Flask server on 127.0.0.1:5111 keeps the model loaded: Paradee-8M on the CPU, or Kokoro-82M on an NVIDIA GPU. The hotkey script sends it the text. The server splits it at commas and full stops, synthesizes ahead of playback, time-stretches without changing pitch, and plays it. The caption strip, the Windows highlighter and the bar widget only read the server's state.

The details are in [how-it-works.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/how-it-works.md). The measurements
behind this README, each with the machine it was taken on, are in
[AUDIT.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/AUDIT.md), the project's engineering log.

From each project's own README, October 2026.

**Omarchy, with Kokoro:**

- [Omatalk](https://github.com/zerobearing2/omatalk) : reads the selection on F8, with Kokoro on the CPU.
- [Say It](https://github.com/txapotxapa/sayit-omarchy) : a bar player that highlights each word; 54 voices in nine languages.
- [Read Aloud: Text to Speech](https://github.com/remigius-labs/omarchy-read-aloud) : reads the clipboard from the bar; 54 voices in nine languages.
- [kokoro-tts-omarchy](https://github.com/MASH2RAFI/kokoro-tts-omarchy) : GPU builds for NVIDIA, AMD and Intel.
- [omarchy-tts](https://github.com/jagrat7/omarchy-tts) : several local and cloud voice engines behind one key.
- [omarchy-speak](https://github.com/seanpowless-dotcom/omarchy-speak) : Piper for speed, Kokoro for quality.
- [Omarchy Talks](https://github.com/Zerolxgic/Omarchy-Talks) : reads the selection through VoiceBox.

**Elsewhere:**

- [Speech Note](https://github.com/mkiol/dsnote) : an offline Linux app for text-to-speech, speech-to-text and translation.
- [Pied](https://github.com/Elleo/pied) : installs Piper voices for Speech Dispatcher, so other Linux apps can use them.
- [kokoro-sapi](https://github.com/RvRooijen/kokoro-sapi) : Kokoro as a Windows SAPI voice, for apps that use system voices.
- [TinyReadAloud](https://github.com/dorofino/TinyReadAloud) : a Windows tray app that reads the selection on Ctrl+Alt+R.
- [Read Aloud](https://github.com/ken107/read-aloud) : a browser extension that reads web pages.
- [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) : Kokoro behind an OpenAI-compatible speech API, in Docker.

The code here is MIT-licensed. It builds on, and redistributes none of:

- [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) and[kokoro](https://github.com/hexgrad/kokoro) by hexgrad (Apache-2.0);
- [Paradee-8M](https://github.com/sahilmahendrakar/paradee) by
sahilmahendrakar (Apache-2.0), the CPU voice;
- PyTorch;
- eSpeak NG (GPL-3.0);
- and more.

The full list, and what redistributing a bundle would require, is in
[licenses.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/licenses.md). This project is not affiliated with hexgrad
or the Kokoro project.

Bug reports and ideas welcome via
[issues](https://github.com/sayed-qutob-work/kokoro-read-aloud/issues/new/choose).
For pull requests, please open an issue first.

- **Bugs:** the[bug report form](https://github.com/sayed-qutob-work/kokoro-read-aloud/issues/new?template=bug_report.yml) asks for your platform,`kokoroctl status` and the logs.
- **Security problems:** please report them privately, as described in[SECURITY.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/SECURITY.md) .
- **Before changing code,** read[docs/README.md](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/docs/README.md) . The
engineering docs record what was measured, and what was tried and
rejected.

MIT, see [LICENSE](https://github.com/sayed-qutob-work/kokoro-read-aloud/blob/main/LICENSE).
