9d12667de3
connect() was unconditionally calling setStatus('connecting', ...) at the
top of each attempt, which flickered over "Disconnected — retrying..."
every 3 seconds during the retry loop.
Fix: only show "Connecting..." on the very first attempt (everConnected
is false). Once a connection has been established, preserve the
"Disconnected — retrying..." state across all subsequent reconnect
cycles until onopen fires. Also reset everConnected on Save so pointing
at a new server correctly shows "Connecting..." from a clean slate.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Kokoro Widget
A lightweight, standalone desktop audio widget that connects to the PAI Voice server via WebSocket and plays voice notifications through your system speakers. No browser required.
What it does
Kokoro Widget runs as a small floating window on your desktop. It connects to the PAI Voice WebSocket server (ws://host:port/stream), receives binary MP3 audio frames, and plays them in sequence through your speakers. The connection status and a speaking animation are displayed in real time. When you close the window, the app minimizes to the system tray and keeps running in the background.
Prerequisites
- Node.js 18 or later
- npm (comes with Node.js)
Installation
cd kokoro_widget
npm install
Running
npm start
The widget window will open and immediately attempt to connect to localhost:8888.
CLI Options
All options can be passed after -- when using npm start:
| Option | Default | Description |
|---|---|---|
--host <host> |
localhost |
WebSocket server hostname or IP |
--port <port> |
8888 |
WebSocket server port |
--volume <0-100> |
80 |
Initial playback volume (0–100) |
Example:
npm start -- --host 192.168.1.42 --port 9999 --volume 60
CLI options override saved settings for the current session but are not written back to the config file.
Configuration
Settings can also be changed in the app UI:
- Enter the desired Host and Port in the Settings section at the bottom of the widget
- Click Save — the app reconnects immediately using the new values
- Settings are persisted to disk and restored on next launch
The volume slider is also persisted automatically.
Config file location:
- Linux:
~/.config/kokoro-widget/config.json - macOS:
~/Library/Application Support/kokoro-widget/config.json - Windows:
%APPDATA%\kokoro-widget\config.json
System Tray
Closing the window does not quit the app — it hides to the system tray. To fully quit, right-click the tray icon and select Quit. Double-clicking the tray icon (or clicking Show) restores the window.
Building distributables
Requires electron-builder (installed as a dev dependency):
# Current platform
npm run build
# Specific platforms
npm run build:linux # AppImage + .deb
npm run build:mac # .dmg + .zip
npm run build:win # NSIS installer + portable .exe
Distributable files are output to the dist/ directory.
Note: Cross-platform builds require additional tooling. See the electron-builder docs for details.