Initial commit, basic functionality in place.

This commit is contained in:
Agent
2026-03-11 23:58:39 +00:00
commit 9af3805f87
8 changed files with 6199 additions and 0 deletions

1
.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
node_modules/

82
README.md Normal file
View File

@@ -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 (0100) |
**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.

199
main.js Normal file
View File

@@ -0,0 +1,199 @@
'use strict';
const { app, BrowserWindow, Tray, Menu, ipcMain, nativeImage } = require('electron');
const path = require('path');
const fs = require('fs');
// ---------------------------------------------------------------------------
// CLI argument parsing
// ---------------------------------------------------------------------------
function parseCliArgs() {
const args = process.argv.slice(2);
const overrides = {};
for (let i = 0; i < args.length; i++) {
switch (args[i]) {
case '--host':
if (args[i + 1]) overrides.host = args[++i];
break;
case '--port': {
const p = parseInt(args[++i], 10);
if (!isNaN(p)) overrides.port = p;
break;
}
case '--volume': {
const v = parseInt(args[++i], 10);
if (!isNaN(v)) overrides.volume = Math.min(100, Math.max(0, v));
break;
}
}
}
return overrides;
}
// ---------------------------------------------------------------------------
// Config persistence
// ---------------------------------------------------------------------------
const CONFIG_DEFAULTS = { host: 'localhost', port: 8888, volume: 80 };
function getConfigPath() {
return path.join(app.getPath('userData'), 'config.json');
}
function loadConfig() {
try {
const raw = fs.readFileSync(getConfigPath(), 'utf8');
return Object.assign({}, CONFIG_DEFAULTS, JSON.parse(raw));
} catch {
return Object.assign({}, CONFIG_DEFAULTS);
}
}
function writeConfig(cfg) {
try {
fs.writeFileSync(getConfigPath(), JSON.stringify(cfg, null, 2), 'utf8');
} catch (e) {
console.error('Failed to write config:', e);
}
}
// ---------------------------------------------------------------------------
// App state
// ---------------------------------------------------------------------------
let mainWindow = null;
let tray = null;
const cliArgs = parseCliArgs();
// savedConfig loaded in app.whenReady() — app.getPath('userData') not available before then
let savedConfig = { ...CONFIG_DEFAULTS };
// Effective runtime config = saved + CLI overrides (CLI does not persist).
// Only include cliArgs keys that are explicitly set (not undefined).
function getRuntimeConfig() {
const definedCli = Object.fromEntries(
Object.entries(cliArgs).filter(([, v]) => v !== undefined)
);
return Object.assign({}, savedConfig, definedCli);
}
// Show and focus the main window from any context.
function showWindow() {
if (mainWindow) {
mainWindow.show();
mainWindow.focus();
}
}
// ---------------------------------------------------------------------------
// Tray icon — generated programmatically from raw RGBA pixels (16×16 cyan circle)
// ---------------------------------------------------------------------------
function createTrayIcon() {
// Build a 16×16 RGBA buffer with a filled circle in --cyan (#12c2e9)
const SIZE = 16;
const buf = Buffer.alloc(SIZE * SIZE * 4, 0); // fully transparent
const cx = 7.5, cy = 7.5, r = 6.5;
for (let y = 0; y < SIZE; y++) {
for (let x = 0; x < SIZE; x++) {
const dx = x - cx, dy = y - cy;
if (dx * dx + dy * dy <= r * r) {
const i = (y * SIZE + x) * 4;
buf[i] = 0x12; // R
buf[i + 1] = 0xc2; // G
buf[i + 2] = 0xe9; // B
buf[i + 3] = 0xff; // A
}
}
}
return nativeImage.createFromBuffer(buf, { width: SIZE, height: SIZE });
}
// ---------------------------------------------------------------------------
// Window creation
// ---------------------------------------------------------------------------
function createWindow() {
mainWindow = new BrowserWindow({
width: 360,
height: 540,
resizable: true,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false,
},
title: 'Kokoro Widget',
backgroundColor: '#0d1220',
});
mainWindow.setMenuBarVisibility(false);
mainWindow.loadFile(path.join(__dirname, 'renderer', 'index.html'));
// Hide to tray on close instead of quitting
mainWindow.on('close', (event) => {
if (!app.isQuitting) {
event.preventDefault();
mainWindow.hide();
}
});
}
// ---------------------------------------------------------------------------
// Tray creation
// ---------------------------------------------------------------------------
function createTray() {
const icon = createTrayIcon();
tray = new Tray(icon);
tray.setToolTip('Kokoro Widget');
const contextMenu = Menu.buildFromTemplate([
{
label: 'Show',
click: showWindow,
},
{ type: 'separator' },
{
label: 'Quit',
click: () => {
app.isQuitting = true;
app.quit();
},
},
]);
tray.setContextMenu(contextMenu);
tray.on('double-click', showWindow);
// On macOS, single click shows the window
if (process.platform === 'darwin') {
tray.on('click', showWindow);
}
}
// ---------------------------------------------------------------------------
// IPC handlers
// ---------------------------------------------------------------------------
ipcMain.handle('get-config', () => {
return getRuntimeConfig();
});
ipcMain.handle('save-config', (_event, newConfig) => {
// Merge new values into savedConfig
savedConfig = Object.assign({}, savedConfig, newConfig);
writeConfig(savedConfig);
// Return effective runtime config (saved + CLI overrides)
return getRuntimeConfig();
});
// ---------------------------------------------------------------------------
// App lifecycle
// ---------------------------------------------------------------------------
app.whenReady().then(() => {
savedConfig = loadConfig(); // safe here — app.getPath('userData') now available
createWindow();
createTray();
app.on('activate', showWindow);
});
// Do NOT quit when all windows are closed — tray keeps the app alive
app.on('window-all-closed', () => {
// intentionally empty — tray icon keeps the process running
});

5277
package-lock.json generated Normal file

File diff suppressed because it is too large Load Diff

40
package.json Normal file
View File

@@ -0,0 +1,40 @@
{
"name": "kokoro-widget",
"version": "1.0.0",
"description": "Standalone PAI Voice audio widget — receives WebSocket audio and plays through speakers",
"main": "main.js",
"scripts": {
"start": "node node_modules/electron/cli.js --no-sandbox .",
"build": "electron-builder",
"build:linux": "electron-builder --linux",
"build:mac": "electron-builder --mac",
"build:win": "electron-builder --win"
},
"devDependencies": {
"electron": "^33.0.0",
"electron-builder": "^25.0.0"
},
"build": {
"appId": "com.pai.kokoro-widget",
"productName": "Kokoro Widget",
"directories": {
"output": "dist"
},
"linux": {
"target": ["AppImage", "deb"],
"category": "Utility"
},
"mac": {
"target": ["dmg", "zip"],
"category": "public.app-category.utilities"
},
"win": {
"target": ["nsis", "portable"]
},
"files": [
"main.js",
"preload.js",
"renderer/**"
]
}
}

8
preload.js Normal file
View File

@@ -0,0 +1,8 @@
'use strict';
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('kokoro', {
getConfig: () => ipcRenderer.invoke('get-config'),
saveConfig: (config) => ipcRenderer.invoke('save-config', config),
});

329
renderer/index.html Normal file
View File

@@ -0,0 +1,329 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Kokoro Widget</title>
<style>
:root {
--bg-primary: #0d1220;
--bg-secondary: #141c2c;
--bg-tertiary: #1c2638;
--text-primary: #f0f2f5;
--text-secondary: #c0c8d4;
--text-muted: #8a919d;
--cyan: #12c2e9;
--purple: #c471ed;
--pink: #ff6b9d;
--teal: #2dd4bf;
--orange: #F39C12;
--border: rgba(255, 255, 255, 0.08);
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: var(--bg-primary);
color: var(--text-primary);
min-height: 100vh;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
padding: 1rem;
-webkit-app-region: no-drag;
user-select: none;
}
/* Make window draggable by the panel header area */
.voice-panel {
background: var(--bg-secondary);
border: 1px solid var(--border);
border-radius: 16px;
padding: 1.5rem 2rem;
width: 300px;
text-align: center;
}
.panel-header {
-webkit-app-region: drag;
cursor: move;
margin-bottom: 0.25rem;
}
.voice-panel h1 {
font-size: 1.2rem;
font-weight: 700;
color: var(--cyan);
margin-bottom: 0;
}
.voice-panel .subtitle {
font-size: 0.75rem;
color: var(--text-muted);
margin-bottom: 1.25rem;
}
/* Status indicator */
.status {
display: flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
margin-bottom: 1rem;
font-size: 0.85rem;
}
.status-dot {
width: 10px;
height: 10px;
border-radius: 50%;
background: var(--text-muted);
transition: background 0.3s, box-shadow 0.3s;
flex-shrink: 0;
}
.status-dot.connected {
background: var(--teal);
box-shadow: 0 0 8px rgba(45, 212, 191, 0.4);
}
.status-dot.connecting {
background: var(--orange);
animation: pulse 1.5s infinite;
}
.status-dot.error {
background: var(--pink);
}
.status-text {
color: var(--text-secondary);
font-size: 0.85rem;
}
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.4; }
}
/* Speaking indicator */
.speaking-indicator {
height: 36px;
display: flex;
align-items: center;
justify-content: center;
gap: 4px;
margin-bottom: 0.75rem;
opacity: 0;
transition: opacity 0.3s;
}
.speaking-indicator.active {
opacity: 1;
}
.speaking-bar {
width: 4px;
height: 8px;
background: var(--cyan);
border-radius: 2px;
}
.speaking-indicator.active .speaking-bar {
animation: bars 0.8s ease-in-out infinite;
}
.speaking-bar:nth-child(1) { animation-delay: 0s; }
.speaking-bar:nth-child(2) { animation-delay: 0.1s; }
.speaking-bar:nth-child(3) { animation-delay: 0.2s; }
.speaking-bar:nth-child(4) { animation-delay: 0.3s; }
.speaking-bar:nth-child(5) { animation-delay: 0.2s; }
.speaking-bar:nth-child(6) { animation-delay: 0.1s; }
.speaking-bar:nth-child(7) { animation-delay: 0s; }
@keyframes bars {
0%, 100% { height: 8px; }
50% { height: 26px; }
}
/* Last message */
.last-message {
font-size: 0.78rem;
color: var(--text-muted);
min-height: 1.4em;
margin-bottom: 1rem;
font-style: italic;
line-height: 1.4;
word-break: break-word;
}
/* Divider */
.divider {
border: none;
border-top: 1px solid var(--border);
margin: 0 0 1rem 0;
}
/* Volume row */
.volume-row {
display: flex;
align-items: center;
gap: 0.5rem;
margin-bottom: 1rem;
}
.volume-row label {
font-size: 0.7rem;
color: var(--text-muted);
text-transform: uppercase;
letter-spacing: 0.05em;
white-space: nowrap;
min-width: 3rem;
text-align: left;
}
.volume-row input[type="range"] {
flex: 1;
accent-color: var(--cyan);
cursor: pointer;
}
/* Settings section */
.settings-section {
border-top: 1px solid var(--border);
padding-top: 1rem;
text-align: left;
}
.settings-section h3 {
font-size: 0.65rem;
color: var(--text-muted);
text-transform: uppercase;
letter-spacing: 0.08em;
margin-bottom: 0.75rem;
}
.settings-row {
display: flex;
align-items: center;
gap: 0.5rem;
margin-bottom: 0.5rem;
}
.settings-row label {
font-size: 0.75rem;
color: var(--text-secondary);
min-width: 2.5rem;
text-align: right;
}
.settings-row input {
flex: 1;
background: var(--bg-tertiary);
border: 1px solid var(--border);
border-radius: 6px;
padding: 0.35rem 0.5rem;
color: var(--text-primary);
font-size: 0.8rem;
font-family: inherit;
outline: none;
transition: border-color 0.2s;
}
.settings-row input:focus {
border-color: rgba(18, 194, 233, 0.5);
}
.settings-row input[type="number"]::-webkit-outer-spin-button,
.settings-row input[type="number"]::-webkit-inner-spin-button {
-webkit-appearance: none;
margin: 0;
}
.save-row {
display: flex;
justify-content: flex-end;
margin-top: 0.75rem;
}
#saveBtn {
background: var(--cyan);
color: #0d1220;
border: none;
border-radius: 6px;
padding: 0.4rem 1.1rem;
font-size: 0.8rem;
font-weight: 600;
font-family: inherit;
cursor: pointer;
transition: opacity 0.2s;
}
#saveBtn:hover {
opacity: 0.85;
}
#saveBtn:active {
opacity: 0.7;
}
#saveBtn.saved {
background: var(--teal);
}
</style>
</head>
<body>
<div class="voice-panel">
<div class="panel-header">
<h1>PAI Voice</h1>
<p class="subtitle">Voice notifications from your AI assistant</p>
</div>
<div class="status">
<span class="status-dot connecting" id="statusDot"></span>
<span class="status-text" id="statusText">Connecting...</span>
</div>
<div class="speaking-indicator" id="speakingIndicator">
<div class="speaking-bar"></div>
<div class="speaking-bar"></div>
<div class="speaking-bar"></div>
<div class="speaking-bar"></div>
<div class="speaking-bar"></div>
<div class="speaking-bar"></div>
<div class="speaking-bar"></div>
</div>
<div class="last-message" id="lastMessage">Waiting for notifications...</div>
<hr class="divider">
<div class="volume-row">
<label for="volume">Volume</label>
<input type="range" id="volume" min="0" max="100" value="80">
</div>
<div class="settings-section">
<h3>Settings</h3>
<div class="settings-row">
<label for="hostInput">Host</label>
<input type="text" id="hostInput" placeholder="localhost" value="localhost">
</div>
<div class="settings-row">
<label for="portInput">Port</label>
<input type="number" id="portInput" placeholder="8888" value="8888" min="1" max="65535">
</div>
<div class="save-row">
<button id="saveBtn">Save</button>
</div>
</div>
</div>
<script src="renderer.js"></script>
</body>
</html>

263
renderer/renderer.js Normal file
View File

@@ -0,0 +1,263 @@
'use strict';
// ---------------------------------------------------------------------------
// State
// ---------------------------------------------------------------------------
let ws = null;
let config = {}; // populated from IPC in init() — no hardcoded defaults here
let everConnected = false; // true after first successful onopen
let reconnectTimer = null;
const audioQueue = [];
const AUDIO_QUEUE_MAX = 25;
let isPlaying = false;
let consecutiveAudioErrors = 0;
const AUDIO_ERROR_LIMIT = 5;
let volumeSaveTimer = null;
// DOM refs — populated after DOMContentLoaded
let statusDot, statusText, speakingIndicator, lastMessage;
let volumeSlider, hostInput, portInput, saveBtn;
// ---------------------------------------------------------------------------
// WebSocket URL
// ---------------------------------------------------------------------------
function getWsUrl() {
return `ws://${config.host}:${config.port}/stream`;
}
// ---------------------------------------------------------------------------
// Status display
// ---------------------------------------------------------------------------
function setStatus(state, text) {
statusDot.className = 'status-dot ' + state;
statusText.textContent = text;
}
function setSpeaking(active) {
if (active) {
speakingIndicator.classList.add('active');
} else {
speakingIndicator.classList.remove('active');
}
}
// ---------------------------------------------------------------------------
// WebSocket connection
// ---------------------------------------------------------------------------
function connect() {
// Clean up any existing connection
if (ws) {
ws.onopen = null;
ws.onmessage = null;
ws.onclose = null;
ws.onerror = null;
ws.close();
ws = null;
}
clearReconnectTimer();
setStatus('connecting', 'Connecting...');
try {
ws = new WebSocket(getWsUrl());
ws.binaryType = 'arraybuffer';
ws.onopen = () => {
everConnected = true;
// Socket open but no data yet — show a distinct waiting state
setStatus('connected', 'Connected — waiting for audio');
};
ws.onmessage = (event) => {
if (typeof event.data === 'string') {
try {
const msg = JSON.parse(event.data);
if (msg.type === 'notification' && msg.message) {
lastMessage.textContent = msg.message;
setStatus('connected', 'Connected');
}
} catch {
// Ignore malformed JSON
}
} else if (event.data instanceof ArrayBuffer) {
// First real data confirms the server is live
setStatus('connected', 'Connected');
if (audioQueue.length < AUDIO_QUEUE_MAX) {
audioQueue.push(event.data);
if (!isPlaying) playNext();
} else {
console.warn('Audio queue full — dropping incoming frame');
}
}
};
ws.onclose = () => {
ws = null;
if (everConnected) {
// Was previously connected — show that we lost it
setStatus('error', 'Disconnected — retrying...');
} else {
// Never connected yet — stay in the neutral "Connecting..." state
// so there is no blink during the retry loop
setStatus('connecting', 'Connecting...');
}
scheduleReconnect();
};
ws.onerror = () => {
// onclose always fires after onerror — let onclose handle the status
// update so there is no intermediate blink from this handler.
if (ws) ws._hadError = true;
};
} catch (e) {
console.error('WebSocket connection failed:', e);
setStatus('error', 'Connection error');
scheduleReconnect();
}
}
function scheduleReconnect() {
clearReconnectTimer();
reconnectTimer = setTimeout(() => {
if (ws === null) connect();
}, 3000);
}
function clearReconnectTimer() {
if (reconnectTimer) {
clearTimeout(reconnectTimer);
reconnectTimer = null;
}
}
// ---------------------------------------------------------------------------
// Audio playback queue
// ---------------------------------------------------------------------------
async function playNext() {
if (audioQueue.length === 0) {
isPlaying = false;
setSpeaking(false);
return;
}
isPlaying = true;
setSpeaking(true);
const buffer = audioQueue.shift();
let url = null;
try {
const blob = new Blob([buffer], { type: 'audio/mpeg' });
url = URL.createObjectURL(blob);
const audio = new Audio(url);
audio.volume = Math.min(1, Math.max(0, config.volume / 100));
audio.onended = () => {
URL.revokeObjectURL(url);
consecutiveAudioErrors = 0;
playNext();
};
audio.onerror = (e) => {
console.error('Audio error:', e);
URL.revokeObjectURL(url);
consecutiveAudioErrors++;
if (consecutiveAudioErrors >= AUDIO_ERROR_LIMIT) {
console.error(`Audio failed ${AUDIO_ERROR_LIMIT} times in a row — stopping playback`);
isPlaying = false;
setSpeaking(false);
setStatus('error', 'Audio error');
audioQueue.length = 0;
return;
}
playNext();
};
await audio.play();
consecutiveAudioErrors = 0;
} catch (e) {
console.error('Audio playback failed:', e);
if (url) URL.revokeObjectURL(url); // prevent leak on play() rejection
consecutiveAudioErrors++;
if (consecutiveAudioErrors >= AUDIO_ERROR_LIMIT) {
console.error(`Audio failed ${AUDIO_ERROR_LIMIT} times in a row — stopping playback`);
isPlaying = false;
setSpeaking(false);
setStatus('error', 'Audio error');
audioQueue.length = 0;
return;
}
playNext();
}
}
// ---------------------------------------------------------------------------
// Initialization
// ---------------------------------------------------------------------------
async function init() {
// Grab DOM refs
statusDot = document.getElementById('statusDot');
statusText = document.getElementById('statusText');
speakingIndicator = document.getElementById('speakingIndicator');
lastMessage = document.getElementById('lastMessage');
volumeSlider = document.getElementById('volume');
hostInput = document.getElementById('hostInput');
portInput = document.getElementById('portInput');
saveBtn = document.getElementById('saveBtn');
// Load config from main process (merged saved + CLI args)
try {
config = await window.kokoro.getConfig();
} catch (e) {
console.error('Failed to load config:', e);
}
// Populate UI with loaded values
volumeSlider.value = config.volume;
hostInput.value = config.host;
portInput.value = config.port;
// Volume slider: live update + debounce save
volumeSlider.addEventListener('input', () => {
config.volume = parseInt(volumeSlider.value, 10);
clearTimeout(volumeSaveTimer);
volumeSaveTimer = setTimeout(async () => {
try {
await window.kokoro.saveConfig({ volume: config.volume });
} catch (e) {
console.error('Failed to save volume:', e);
}
}, 500);
});
// Save button: update host/port, save, reconnect
saveBtn.addEventListener('click', async () => {
const newHost = hostInput.value.trim() || 'localhost';
const newPort = parseInt(portInput.value, 10);
const validPort = (!isNaN(newPort) && newPort > 0 && newPort <= 65535) ? newPort : 8888;
hostInput.value = newHost;
portInput.value = validPort;
try {
config = await window.kokoro.saveConfig({ host: newHost, port: validPort });
// Visual feedback
saveBtn.textContent = 'Saved!';
saveBtn.classList.add('saved');
setTimeout(() => {
saveBtn.textContent = 'Save';
saveBtn.classList.remove('saved');
}, 1500);
// Reconnect with new settings
connect();
} catch (e) {
console.error('Failed to save config:', e);
}
});
// Connect to WebSocket
connect();
}
document.addEventListener('DOMContentLoaded', init);