KokoLink-Linux

A lightweight, high-performance, system-wide offline Text-to-Speech (TTS) integration framework and PyQt control panel for Linux, powered under the hood by the state-of-the-art Kokoro TTS model.

This project wraps the official hexgrad/Kokoro-82M open-weight model into a local background daemon, integrates it directly into speech-dispatcher, and provides a PyQt system tray control panel to manage active models, search and install new weights, and dynamically blend speaker embeddings.

---

Features

• System-Wide TTS Integration: Registered natively as a speech-dispatcher output module. Any reading application (e.g., Foliate, Okular, GNOME Screen Reader) will automatically use Kokoro.
• PyQt Control Panel & System Tray: Sleek, modern dark-mode PyQt5/PyQt6 control panel that runs in the background and can be minimized to the system tray.
• Horizontal Model Selector: Scans your local Hugging Face cache automatically and presents your downloaded models as individual horizontal cards.
• Dynamic HF Model Installation: Features an interactive Hugging Face model search interface so you can search and download new Kokoro repositories directly from the app.
• Dynamic Voice Fallback Resolver: Intercepts speech requests. If a client requests a voice that is missing from the active model, the daemon dynamically maps the request to a local fallback voice to prevent system-wide TTS crashes.
• Voice Blender Tab: Create custom speaker profile embeddings by blending any two standard voices at custom ratios (e.g. 70% George / 30% Michael) and save them as new reusable voice cards.
• Instant System-wide Switching: Click any voice card to immediately apply it as system default. The daemon restarts seamlessly, showing a loading overlay and dispatching a desktop notification when ready.

---

Directory Structure

• install.sh — The automated installer script (system packages, venv creation, configurations).
• kokoro_server.py — The local UNIX socket daemon that keeps PyTorch and Kokoro weights loaded in memory.
• kokoro_tray.py — The multi-tab PyQt control panel GUI tray application.
• speak.py — Standard speech-dispatcher forwarder client script.
• test_voices.py — TTS voice generator test script.
• kokoro.service — Systemd user service template configuration.
• kokoro-tray.desktop — XDG desktop autostart entry configuration.
• kokoro-generic.conf — Speech-dispatcher generic module definition.

---

Installation

Run the automated installer script inside the directory:

chmod +x install.sh
./install.sh

What the installer does:

1. Installs system requirements (espeak-ng, speech-dispatcher, python312, paplay) using yay or pacman.
2. Creates a Python 3.12 virtual environment at ~/kokoro/venv.
3. Installs and updates python dependencies (kokoro, soundfile, torch).
4. Deploys the systemd user service (kokoro.service) and the desktop autostart entry (kokoro-tray.desktop).
5. Configures speech-dispatcher to make Kokoro your system default TTS engine.
6. Downloads and pre-caches the official standard model hexgrad/Kokoro-82M.

---

Usage & Commands

Opening the Control Panel

The panel is registered to start automatically at login. You can launch it manually at any time by running:

python ~/kokoro/kokoro_tray.py &

Manual CLI Synthesis

You can synthesize text directly from your terminal using the helper client:

echo "Hello, this is a manual test." | python ~/kokoro/speak.py

Or override the voice explicitly:

echo "Testing voice override." | python ~/kokoro/speak.py bm_lewis

Service Controls

Manage the background socket daemon using systemd user unit commands:

# Check status
systemctl --user status kokoro.service

# Restart daemon
systemctl --user restart kokoro.service

# View daemon logs
journalctl --user -u kokoro.service -n 50 --no-pager

---

Custom Voice Blending

1. Open the Control Panel GUI.
2. Select the Blender tab.
3. Select your base and modifier voice profile (e.g. George and Michael).
4. Slide the ratio bar to your desired mix percentage.
5. Give it a name (e.g., wizard_voice) and click "Blend & Save Custom Voice".
6. The voice will automatically compile, save to ~/kokoro/custom_voices/, and appear as a selectable card under your Selector tab!