83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
# 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](https://nodejs.org/) 18 or later
|
||
- npm (comes with Node.js)
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
cd kokoro_widget
|
||
npm install
|
||
```
|
||
|
||
## Running
|
||
|
||
```bash
|
||
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:**
|
||
|
||
```bash
|
||
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:
|
||
|
||
1. Enter the desired **Host** and **Port** in the Settings section at the bottom of the widget
|
||
2. Click **Save** — the app reconnects immediately using the new values
|
||
3. 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](https://www.electron.build/) (installed as a dev dependency):
|
||
|
||
```bash
|
||
# 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](https://www.electron.build/multi-platform-build) for details.
|