# 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.