Initial commit, basic functionality in place.

README.md

@@ -0,0 +1,82 @@
+# 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.