agentvibes-avatars 0.1.0

package/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2026 Paul Preibisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package loads, at runtime from CDN, third-party libraries it does NOT
+bundle or redistribute:
+
+  - TalkingHead by met4citizen — MIT License
+    https://github.com/met4citizen/TalkingHead
+  - three.js by mrdoob and contributors — MIT License
+    https://github.com/mrdoob/three.js
+
+Avatar models are loaded from the TalkingHead repository at runtime and remain
+the property of their respective authors. See their repositories for terms.

package/README.md

@@ -0,0 +1,77 @@
+# agentvibes-avatars
+
+A **talking-head avatar window** on a galaxy stage that lip-syncs **any TTS audio you POST to it**. Run it, leave the window open, and `POST` audio + text to `/speak` — an avatar speaks it with synchronized lip movement, captions, and a chat log. Multiple sources (projects / remote servers) appear as their own tabs.
+
+It's a thin, zero-dependency Node HTTP server plus a browser page. The heavy 3D — the [TalkingHead](https://github.com/met4citizen/TalkingHead) library, [three.js](https://github.com/mrdoob/three.js), and the avatar models — is **loaded from CDN at runtime, not bundled**, so this package stays tiny and ships only its own code.
+
+## Install
+
+```bash
+npm install -g agentvibes-avatars
+```
+
+## Run
+
+```bash
+agentvibes-avatars            # start the server + open the avatar window
+agentvibes-avatars --port 4000
+agentvibes-avatars --view gallery.html
+```
+
+This starts the receiver on `http://localhost:3747` and opens a dedicated Chrome app window (with autoplay enabled so audio plays hands-free). If Chrome isn't found it falls back to your default browser. If a window is already open, it's refreshed in place instead of duplicated.
+
+> First run needs internet (to fetch the TalkingHead library + three.js from CDN). After that the browser caches them.
+
+## Speak to it
+
+POST JSON to `/speak`. `audioBase64` is a base64-encoded WAV; the other fields drive the labels.
+
+```bash
+curl -X POST http://localhost:3747/speak \
+  -H "Content-Type: application/json" \
+  -d '{
+    "audioBase64": "<base64 WAV>",
+    "text": "Hello from my app.",
+    "voice": "en_US-amy-medium",
+    "project": "my-app",
+    "origin": "local"
+  }'
+```
+
+| field | meaning |
+|---|---|
+| `audioBase64` | base64 WAV to play (required for audio) |
+| `text` | caption + chat bubble + lip-sync timing |
+| `voice` | logical voice name (drives avatar colour/mapping) |
+| `project` | session/tab label |
+| `origin` | source label badge: `local`, `remote`, or a server name |
+
+The window assigns a consistent avatar per voice, groups messages by `project` into tabs (with unread badges), and lets you click any chat bubble to replay it.
+
+## Endpoints
+
+| method | path | purpose |
+|---|---|---|
+| `POST` | `/speak` | play audio + show text |
+| `GET` | `/has-browser` | `{ "connected": bool }` |
+| `GET` | `/health` | liveness |
+| `POST` | `/reload` | refresh open windows |
+
+## Security
+
+The server binds **`127.0.0.1` only**. State-changing endpoints reject requests carrying a non-loopback `Origin` header (blocks CSRF from a stray browser tab); local tools that POST without an `Origin` work normally. Request bodies are size-capped.
+
+## How it fits with AgentVibes
+
+[AgentVibes](https://github.com/paulpreibisch/AgentVibes) forwards its TTS to this window automatically. But the receiver is generic — anything that can synthesize a WAV and POST it can drive the avatars.
+
+## Credits
+
+- [TalkingHead](https://github.com/met4citizen/TalkingHead) by met4citizen — MIT
+- [three.js](https://github.com/mrdoob/three.js) — MIT
+
+Loaded from CDN at runtime; not bundled or redistributed by this package. See [LICENSE](./LICENSE).
+
+## License
+
+MIT © Paul Preibisch

package/avatars.json

@@ -0,0 +1,35 @@
+{
+  "_comment": "The original models.readyplayer.me URLs no longer resolve (NXDOMAIN), so all entries point to the TalkingHead demo avatar 'brunette.glb' served via jsDelivr — it has ARKit+Oculus visemes baked in for lip sync. Replace any entry's url with your own GLB (e.g. a fresh ReadyPlayerMe export with ?morphTargets=ARKit,Oculus+Visemes) to get distinct avatars per gender.",
+  "avatars": {
+    "female-1": {
+      "url": "https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.3/avatars/brunette.glb",
+      "body": "F",
+      "label": "Female 1"
+    },
+    "female-2": {
+      "url": "https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.3/avatars/brunette.glb",
+      "body": "F",
+      "label": "Female 2"
+    },
+    "male-1": {
+      "url": "https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.3/avatars/brunette.glb",
+      "body": "M",
+      "label": "Male 1"
+    },
+    "male-2": {
+      "url": "https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.3/avatars/brunette.glb",
+      "body": "M",
+      "label": "Male 2"
+    },
+    "neutral": {
+      "url": "https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.3/avatars/brunette.glb",
+      "body": "F",
+      "label": "Neutral"
+    }
+  },
+  "genderOrder": {
+    "female": ["female-1", "female-2", "neutral"],
+    "male": ["male-1", "male-2", "neutral"],
+    "neutral": ["neutral", "female-1", "male-1"]
+  }
+}

package/bin/cli.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+'use strict';
+//
+// agentvibes-avatars — start the receiver server and open the avatar window.
+//
+// Usage:
+//   agentvibes-avatars                 # start server + open the avatar window
+//   agentvibes-avatars --port 4000     # custom port
+//   agentvibes-avatars --view gallery.html
+//
+// The window speaks any TTS audio POSTed to  http://localhost:<port>/speak
+//   { audioBase64, text, voice, project, origin }
+//
+// The TalkingHead library + three.js + avatars load from CDN at runtime — nothing
+// is bundled here. First run needs internet; after that the page is cached by the
+// browser.
+//
+
+const { spawn } = require('child_process');
+const http = require('http');
+const path = require('path');
+const os   = require('os');
+const fs   = require('fs');
+
+const argv = process.argv.slice(2);
+function flag(name, def) { const i = argv.indexOf(name); return (i >= 0 && argv[i + 1]) ? argv[i + 1] : def; }
+
+const PORT = parseInt(process.env.AVATARS_PORT || flag('--port', '3747'), 10);
+const VIEW = flag('--view', 'cosmic.html');
+const BASE = `http://localhost:${PORT}`;
+
+function get(p) {
+  return new Promise(resolve => {
+    const req = http.get(`${BASE}${p}`, res => { let b = ''; res.on('data', c => b += c); res.on('end', () => resolve({ status: res.statusCode, body: b })); });
+    req.on('error', () => resolve(null));
+    req.setTimeout(1500, () => { req.destroy(); resolve(null); });
+  });
+}
+function post(p) {
+  return new Promise(resolve => {
+    const req = http.request(`${BASE}${p}`, { method: 'POST' }, res => { res.on('data', () => {}); res.on('end', () => resolve(true)); });
+    req.on('error', () => resolve(false));
+    req.setTimeout(1500, () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+}
+
+function findChrome() {
+  const c = [];
+  if (process.platform === 'win32') {
+    c.push(`${process.env['PROGRAMFILES']}\\Google\\Chrome\\Application\\chrome.exe`,
+           `${process.env['PROGRAMFILES(X86)']}\\Google\\Chrome\\Application\\chrome.exe`,
+           `${process.env['LOCALAPPDATA']}\\Google\\Chrome\\Application\\chrome.exe`);
+  } else if (process.platform === 'darwin') {
+    c.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome');
+  } else {
+    c.push('/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium');
+  }
+  return c.find(p => { try { return p && fs.existsSync(p); } catch { return false; } });
+}
+
+function openWindow(url) {
+  const chrome = findChrome();
+  if (chrome) {
+    // Dedicated app window with autoplay enabled so audio plays hands-free.
+    const profile = path.join(os.homedir(), '.agentvibes-avatars', 'chrome-profile');
+    spawn(chrome, [`--app=${url}`, '--autoplay-policy=no-user-gesture-required',
+      `--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check'],
+      { detached: true, stdio: 'ignore' }).unref();
+    return 'chrome app window';
+  }
+  // Fallback: the OS default browser (autoplay may require one click).
+  const opener = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+               : process.platform === 'darwin' ? ['open', [url]]
+               : ['xdg-open', [url]];
+  spawn(opener[0], opener[1], { detached: true, stdio: 'ignore' }).unref();
+  return 'default browser';
+}
+
+(async () => {
+  // 1. Ensure the receiver server is running.
+  let health = await get('/health');
+  if (!health) {
+    const serverPath = path.join(__dirname, '..', 'server.js');
+    const child = spawn(process.execPath, [serverPath], {
+      detached: true, stdio: 'ignore',
+      env: { ...process.env, TALKING_HEAD_PORT: String(PORT) },
+    });
+    child.unref();
+    for (let i = 0; i < 25 && !health; i++) { await new Promise(r => setTimeout(r, 150)); health = await get('/health'); }
+    if (!health) { console.error(`agentvibes-avatars: server failed to start on ${BASE}`); process.exit(1); }
+    console.log(`agentvibes-avatars: server started on ${BASE}`);
+  } else {
+    console.log(`agentvibes-avatars: server already running on ${BASE}`);
+  }
+
+  // 2. Idempotent: if a window is already connected, refresh it instead of duplicating.
+  const hb = await get('/has-browser');
+  if (hb && /"connected":true/.test(hb.body)) {
+    await post('/reload');
+    console.log('agentvibes-avatars: existing window refreshed (no duplicate).');
+    return;
+  }
+
+  // 3. Open the window.
+  const how = openWindow(`${BASE}/${VIEW}`);
+  console.log(`agentvibes-avatars: opened ${BASE}/${VIEW} via ${how}`);
+  console.log(`POST TTS audio to ${BASE}/speak  { audioBase64, text, voice, project, origin }`);
+})();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agentvibes-avatars",
+  "version": "0.1.0",
+  "description": "A talking-head avatar window on a galaxy stage that lip-syncs any TTS audio POSTed to it. The met4citizen TalkingHead library and three.js are loaded from CDN at runtime (not bundled).",
+  "bin": {
+    "agentvibes-avatars": "bin/cli.js"
+  },
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "files": [
+    "bin/",
+    "server.js",
+    "avatars.json",
+    "public/*.html",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "avatar",
+    "talking-head",
+    "tts",
+    "text-to-speech",
+    "lip-sync",
+    "three.js",
+    "agentvibes"
+  ],
+  "author": "Paul Preibisch",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paulpreibisch/AgentVibes.git",
+    "directory": "agentvibes-avatars"
+  },
+  "homepage": "https://github.com/paulpreibisch/AgentVibes#readme"
+}