kokoro-web 0.1.0

Native messaging bridge for the Kokoro Web browser extension

Kokoro Web

Read text aloud in your browser — powered by local kokoro-tts.

[!NOTE] This project stands on the shoulders of the Kokoro TTS team. Kokoro Web is only a browser extension and native messaging bridge — the model, voices, and synthesis engine are entirely their work. Thank you to everyone who built and maintains kokoro-tts for doing the difficult part that makes this add-on possible. This project is not affiliated with the Kokoro TTS team.

[!CAUTION] This project does not provide TTS services. It is a browser extension and native messaging bridge only. You must install kokoro-tts and the Kokoro model files on your system — your machine runs the actual text-to-speech engine. This setup is more involved than click-and-install.

This codebase has been tested on Linux (Debian) with Chromium and Firefox only. If you encounter issues with other browsers or operating systems, please open an issue and I'll try to help.

Features

• Local and private — synthesis runs on your machine; nothing is sent to the cloud
• Popup — paste text, pick voice and speed, play/pause/stop
• Read anywhere — select text on any page → right-click → Read with Kokoro
• Read page — read the main page content from the context menu, popup, or read-along sidebar
• Read-along sidebar — follow along while text is spoken (Firefox sidebar / Chrome side panel)
• Flexible setup — works with your existing kokoro-tts install and model files

Select text → Read with Kokoro, or open the read-along sidebar to read the full page.

See our Privacy Policy — no cloud, no analytics, no data sent to the developer.

Installation

Browser Store

Install from Firefox Add-ons or the Chrome release (use the badges at the top), restart your browser, and open the extension.

Direct Install

Prefer not to use a browser store? Download the extension zip from GitHub Releases (kokoro-web-*-firefox.zip or kokoro-web-*-chrome.zip), extract it, and load it manually.

Firefox: open about:debugging → This Firefox → Load Temporary Add-on… → select manifest.json inside the extracted folder.

Chromium: open chrome://extensions → enable Developer mode → Load unpacked → select the extracted folder.

If you have not run setup yet, register the native host once (covers Firefox and Chrome):

kokoro-web-setup

Restart the browser, open the extension, and click Test connection.

Quick start

Step 1 — Install kokoro-tts and model files

uv tool install kokoro-tts

mkdir -p ~/.kokoro && cd ~/.kokoro
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx

Step 2 — Install the browser bridge

uv run pip install kokoro-web
uv run kokoro-web-setup

The setup command registers the native host for browsers it detects (Firefox, Chrome, Chromium, Edge, Brave). To install for a specific browser, use the corresponding command below:

Browser	Command
Firefox	uv run kokoro-web-setup firefox
Chrome	uv run kokoro-web-setup chrome
Chromium	uv run kokoro-web-setup chromium
Edge	uv run kokoro-web-setup edge
Brave	uv run kokoro-web-setup brave

To register the native host for all supported browsers, use: uv run kokoro-web-setup --all

Step 3 — Install the extension

Install from Firefox Add-ons or the Chrome release (use the badges at the top), restart your browser, and open the extension.

The first time you open it, click Test connection. If setup succeeded, you can paste text and press Play.

Usage

Where	What you can do
Popup	Paste text, choose voice/speed, play/pause/stop, Read page
Context menu	Select text → Read with Kokoro, or Read page with Kokoro
Read-along sidebar	Read page aloud, play/pause/stop, search and follow along in text

Advanced paths

Open extension Settings → Advanced paths if kokoro-tts is not on your PATH or models live somewhere other than ~/.kokoro. The bridge auto-detects common locations when possible.

Why is a bridge required?

Browsers cannot run local programs directly from an extension (security). The kokoro-web pip package registers a tiny native messaging host that forwards requests to your installed kokoro-tts and streams audio back to the browser.

flowchart LR
  Extension["Browser extension"] -->|"native messaging"| Host["kokoro-web host"]
  Host --> CLI["kokoro-tts CLI"]
  CLI --> Audio["Audio stream"]
  Audio --> Extension

Firefox and Chrome use the same Python host script. They only differ in where the registration JSON file is stored.

Troubleshooting

Setup command not run

If the extension shows "One-time setup required", run:

pip install kokoro-web && kokoro-web-setup

By default, setup registers only browsers it detects on your system. To force a specific browser:

kokoro-web-setup edge

To register every supported browser:

kokoro-web-setup --all

Restart the browser, then click Test connection.

Verify native host registration

Firefox (Linux):

cat ~/.mozilla/native-messaging-hosts/com.kokoro.web.json

Firefox (macOS):

cat ~/Library/Application\ Support/Mozilla/NativeMessagingHosts/com.kokoro.web.json

Chrome or Chromium (Linux):

cat ~/.config/google-chrome/NativeMessagingHosts/com.kokoro.web.json

Chrome (macOS):

cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.kokoro.web.json

Chrome (Windows):

reg query "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.kokoro.web"

If you upgraded from an older release, you can remove the legacy Firefox manifest:

rm -f ~/.mozilla/native-messaging-hosts/com.kokoro.web_addon.json

kokoro-tts works in terminal but not the extension

• Confirm model files are in the configured model directory
• Open Settings → Advanced paths and set the full path to your kokoro-tts binary
• Click Test connection again

Developers

Want to run the extension from source, change the bridge, or contribute?
See developer guide for prerequisites, setup, and the local development workflow. Pull requests are welcome.