@agenticros/eyes 1.0.0 → 1.1.0

package/NOTICE

@@ -0,0 +1,2 @@
+@agenticros/eyes includes a procedural R2D2-style synthesizer adapted from
+https://github.com/chrismatthieu/r2d2 (Apache License 2.0). See lib/synth.js.

package/README.md

@@ -1,6 +1,6 @@
 # @agenticros/eyes
 
-Fullscreen robot eyes for an Ubuntu tablet or robot display, driven by ROS 2 `cmd_vel` (`geometry_msgs/Twist`).
+Fullscreen robot eyes for an Ubuntu tablet or robot display, driven by ROS 2 `cmd_vel` (`geometry_msgs/Twist`). Includes procedural R2D2-style chirps (idle + excited on motion).
 
 Part of the [AgenticROS](https://github.com/agenticros/agenticros) monorepo. Prefer launching via the CLI:
 
@@ -8,10 +8,11 @@ Part of the [AgenticROS](https://github.com/agenticros/agenticros) monorepo. Pre
 agenticros eyes
 agenticros eyes --no-browser
 agenticros eyes --no-teleop          # gaze only (no WASD publish)
+agenticros eyes --no-sound           # mute R2D2 chirps
 agenticros up real --eyes            # start eyes after the real-robot stack
 ```
 
-See [docs/eyes.md](../../docs/eyes.md) for setup, config, and keyboard teleop.
+See [docs/eyes.md](../../docs/eyes.md) for setup, config, sounds, and keyboard teleop.
 
 ## Direct run (development)
 
@@ -22,4 +23,8 @@ pnpm install   # from monorepo root is preferred
 pnpm start
 ```
 
-Requires Node 18+, ROS 2, and a graphical display (`DISPLAY`) for kiosk mode.
+Requires Node 18+, ROS 2, a graphical display (`DISPLAY`) for kiosk mode, and `afplay` / `paplay` / `aplay` for sounds.
+
+## License
+
+MIT. The synthesizer in `lib/synth.js` is adapted from [r2d2](https://github.com/chrismatthieu/r2d2) under Apache-2.0 (see [NOTICE](NOTICE)).

package/lib/sounds.js

@@ -0,0 +1,218 @@
+/**
+ * Idle + excited R2D2 sound loop for @agenticros/eyes.
+ *
+ * Plays synthesized WAV via afplay (macOS), paplay, or aplay (Linux).
+ * Excited bursts are triggered by active cmd_vel (see exciteFromTwist).
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { synthesizeExcited, synthesizeRandom } from "./synth.js";
+
+const MIN_GAP_MS = Number(process.env.SOUND_MIN_GAP_MS || 300);
+const MAX_GAP_MS = Number(process.env.SOUND_MAX_GAP_MS || 2500);
+const EXCITE_COOLDOWN_MS = Number(process.env.SOUND_EXCITE_COOLDOWN_MS || 600);
+const LINEAR_DEADZONE = Number(process.env.SOUND_LINEAR_DEADZONE || 0.02);
+
+/** @type {string | null} */
+let playerBin = null;
+let playerWarned = false;
+let running = false;
+/** @type {import('node:child_process').ChildProcess | null} */
+let currentPlayer = null;
+const tempFiles = new Set();
+let pendingExcitement = 0;
+/** @type {(() => void) | null} */
+let wakeSleep = null;
+let lastExciteAt = 0;
+/** @type {Promise<void> | null} */
+let loopPromise = null;
+
+function sleepInterruptible(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      wakeSleep = null;
+      resolve();
+    }, ms);
+    wakeSleep = () => {
+      clearTimeout(timer);
+      wakeSleep = null;
+      resolve();
+    };
+  });
+}
+
+function randomGapMs() {
+  return MIN_GAP_MS + Math.random() * (MAX_GAP_MS - MIN_GAP_MS);
+}
+
+function findPlayer() {
+  if (playerBin !== null) return playerBin || null;
+  const candidates = ["afplay", "paplay", "aplay"];
+  for (const bin of candidates) {
+    try {
+      execFileSync("which", [bin], { stdio: "ignore" });
+      playerBin = bin;
+      return bin;
+    } catch {
+      // try next
+    }
+  }
+  playerBin = "";
+  return null;
+}
+
+function stopCurrentPlayback() {
+  if (currentPlayer && !currentPlayer.killed) {
+    currentPlayer.kill("SIGTERM");
+  }
+}
+
+/**
+ * Queue an excited burst (interrupt idle playback / gap).
+ * Rate-limited by SOUND_EXCITE_COOLDOWN_MS.
+ */
+export function excite() {
+  if (!running) return;
+  const now = Date.now();
+  if (now - lastExciteAt < EXCITE_COOLDOWN_MS) return;
+  lastExciteAt = now;
+  pendingExcitement += 1;
+  stopCurrentPlayback();
+  if (wakeSleep) wakeSleep();
+}
+
+/**
+ * Excite when Twist has meaningful linear.x or angular.z.
+ * @param {object} msg geometry_msgs/Twist-like
+ * @param {number} angularDeadzone
+ */
+export function exciteFromTwist(msg, angularDeadzone = 0.05) {
+  const lx = Math.abs(msg?.linear?.x ?? 0);
+  const az = Math.abs(msg?.angular?.z ?? 0);
+  if (lx < LINEAR_DEADZONE && az < angularDeadzone) return;
+  excite();
+}
+
+async function playWav(wavPath) {
+  const bin = findPlayer();
+  if (!bin) {
+    if (!playerWarned) {
+      playerWarned = true;
+      console.warn(
+        "No audio player found (afplay / paplay / aplay). R2D2 sounds disabled.",
+      );
+    }
+    return;
+  }
+
+  const args = bin === "aplay" ? ["-q", wavPath] : [wavPath];
+
+  return new Promise((resolve, reject) => {
+    const player = spawn(bin, args, { stdio: "ignore" });
+    currentPlayer = player;
+
+    player.on("error", (err) => {
+      currentPlayer = null;
+      reject(err);
+    });
+
+    player.on("close", (code, signal) => {
+      currentPlayer = null;
+      if (!running || signal === "SIGTERM" || signal === "SIGINT") {
+        resolve();
+        return;
+      }
+      if (code === 0) resolve();
+      else reject(new Error(`${bin} exited with code ${code}`));
+    });
+  });
+}
+
+async function cleanupTemp(path) {
+  tempFiles.delete(path);
+  try {
+    await unlink(path);
+  } catch {
+    // already gone
+  }
+}
+
+async function playGesture(excited) {
+  const { wav } = excited ? synthesizeExcited() : synthesizeRandom();
+  const wavPath = join(tmpdir(), `agenticros-eyes-${randomUUID()}.wav`);
+  tempFiles.add(wavPath);
+
+  try {
+    await writeFile(wavPath, wav);
+    if (!running) return;
+    await playWav(wavPath);
+  } catch (err) {
+    if (running) {
+      console.warn(
+        `Sound playback error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  } finally {
+    await cleanupTemp(wavPath);
+  }
+}
+
+async function soundLoop() {
+  while (running) {
+    if (pendingExcitement > 0) {
+      pendingExcitement -= 1;
+      await playGesture(true);
+      if (pendingExcitement > 0) continue;
+    } else {
+      await playGesture(false);
+      if (pendingExcitement > 0) continue;
+    }
+
+    if (!running) break;
+    await sleepInterruptible(randomGapMs());
+  }
+}
+
+/** Start idle chirps + accept excite() from cmd_vel. */
+export function startSoundLoop() {
+  if (running) return;
+  const bin = findPlayer();
+  if (!bin) {
+    if (!playerWarned) {
+      playerWarned = true;
+      console.warn(
+        "No audio player found (afplay / paplay / aplay). R2D2 sounds disabled.",
+      );
+    }
+    return;
+  }
+  running = true;
+  console.log(
+    `R2D2 sounds on (${bin}; idle gaps ${MIN_GAP_MS}–${MAX_GAP_MS} ms, ` +
+      `excite cooldown ${EXCITE_COOLDOWN_MS} ms)`,
+  );
+  loopPromise = soundLoop().catch((err) => {
+    console.warn(`Sound loop error: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}
+
+/** Stop playback and clean temp WAVs. */
+export async function stopSoundLoop() {
+  if (!running) return;
+  running = false;
+  if (wakeSleep) wakeSleep();
+  stopCurrentPlayback();
+  if (loopPromise) {
+    try {
+      await loopPromise;
+    } catch {
+      // ignore
+    }
+    loopPromise = null;
+  }
+  await Promise.all([...tempFiles].map(cleanupTemp));
+}

package/lib/synth.js

@@ -0,0 +1,185 @@
+/**
+ * Procedural R2D2-style synthesizer.
+ *
+ * Adapted from https://github.com/chrismatthieu/r2d2 (Apache License 2.0).
+ * See ../NOTICE.
+ */
+const SAMPLE_RATE = 22050;
+const AMPLITUDE = 0.35;
+
+function rand(min, max) {
+  return min + Math.random() * (max - min);
+}
+
+function randInt(min, max) {
+  return Math.floor(rand(min, max + 1));
+}
+
+function pick(arr) {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+/** Soft attack/decay envelope to avoid clicks. */
+function envelope(i, n, attack = 0.02, release = 0.08) {
+  const a = Math.max(1, Math.floor(n * attack));
+  const r = Math.max(1, Math.floor(n * release));
+  if (i < a) return i / a;
+  if (i > n - r) return (n - i) / r;
+  return 1;
+}
+
+function encodeWav(samples) {
+  const dataSize = samples.length * 2;
+  const buffer = Buffer.alloc(44 + dataSize);
+
+  buffer.write('RIFF', 0);
+  buffer.writeUInt32LE(36 + dataSize, 4);
+  buffer.write('WAVE', 8);
+  buffer.write('fmt ', 12);
+  buffer.writeUInt32LE(16, 16); // PCM chunk size
+  buffer.writeUInt16LE(1, 20); // audio format = PCM
+  buffer.writeUInt16LE(1, 22); // mono
+  buffer.writeUInt32LE(SAMPLE_RATE, 24);
+  buffer.writeUInt32LE(SAMPLE_RATE * 2, 28); // byte rate
+  buffer.writeUInt16LE(2, 32); // block align
+  buffer.writeUInt16LE(16, 34); // bits per sample
+  buffer.write('data', 36);
+  buffer.writeUInt32LE(dataSize, 40);
+
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    buffer.writeInt16LE(Math.round(clamped * 32767), 44 + i * 2);
+  }
+
+  return buffer;
+}
+
+function concatSamples(parts) {
+  const total = parts.reduce((sum, p) => sum + p.length, 0);
+  const out = new Float32Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+
+function silence(seconds) {
+  return new Float32Array(Math.max(0, Math.floor(seconds * SAMPLE_RATE)));
+}
+
+/** Constant-frequency sine with envelope. */
+function tone(freq, seconds) {
+  const n = Math.max(1, Math.floor(seconds * SAMPLE_RATE));
+  const samples = new Float32Array(n);
+  let phase = 0;
+  const step = (2 * Math.PI * freq) / SAMPLE_RATE;
+  for (let i = 0; i < n; i++) {
+    samples[i] = Math.sin(phase) * AMPLITUDE * envelope(i, n);
+    phase += step;
+  }
+  return samples;
+}
+
+/** Linear frequency sweep (chirp). */
+function chirpSamples(f0, f1, seconds) {
+  const n = Math.max(1, Math.floor(seconds * SAMPLE_RATE));
+  const samples = new Float32Array(n);
+  let phase = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / (n - 1 || 1);
+    const freq = f0 + (f1 - f0) * t;
+    samples[i] = Math.sin(phase) * AMPLITUDE * envelope(i, n, 0.03, 0.12);
+    phase += (2 * Math.PI * freq) / SAMPLE_RATE;
+  }
+  return samples;
+}
+
+function makeChirp() {
+  const up = Math.random() < 0.55;
+  const low = rand(700, 1200);
+  const high = rand(1600, 2800);
+  const seconds = rand(0.08, 0.25);
+  return chirpSamples(up ? low : high, up ? high : low, seconds);
+}
+
+function makeWarble() {
+  const center = rand(900, 1800);
+  const count = randInt(3, 6);
+  const parts = [];
+  for (let i = 0; i < count; i++) {
+    const offset = (i % 2 === 0 ? 1 : -1) * rand(120, 450);
+    const freq = Math.max(400, center + offset);
+    parts.push(tone(freq, rand(0.04, 0.09)));
+    if (i < count - 1) parts.push(silence(rand(0.008, 0.025)));
+  }
+  return concatSamples(parts);
+}
+
+function makeBeeps() {
+  const count = randInt(2, 5);
+  const base = rand(800, 2000);
+  const parts = [];
+  for (let i = 0; i < count; i++) {
+    const freq = base * rand(0.85, 1.25);
+    parts.push(tone(freq, rand(0.035, 0.08)));
+    if (i < count - 1) parts.push(silence(rand(0.02, 0.07)));
+  }
+  return concatSamples(parts);
+}
+
+/** Fast, high, dense — used on active cmd_vel (excited). */
+function makeExcited() {
+  const parts = [];
+  const bursts = randInt(2, 4);
+  for (let b = 0; b < bursts; b++) {
+    const kind = randInt(0, 2);
+    if (kind === 0) {
+      parts.push(chirpSamples(rand(1400, 2200), rand(2600, 3800), rand(0.05, 0.12)));
+    } else if (kind === 1) {
+      const center = rand(1600, 2600);
+      const count = randInt(4, 8);
+      for (let i = 0; i < count; i++) {
+        const offset = (i % 2 === 0 ? 1 : -1) * rand(200, 600);
+        parts.push(tone(Math.max(800, center + offset), rand(0.025, 0.05)));
+        if (i < count - 1) parts.push(silence(rand(0.004, 0.012)));
+      }
+    } else {
+      const count = randInt(3, 6);
+      const base = rand(1500, 2800);
+      for (let i = 0; i < count; i++) {
+        parts.push(tone(base * rand(0.9, 1.35), rand(0.02, 0.045)));
+        if (i < count - 1) parts.push(silence(rand(0.01, 0.03)));
+      }
+    }
+    if (b < bursts - 1) parts.push(silence(rand(0.02, 0.06)));
+  }
+  return concatSamples(parts);
+}
+
+const GESTURES = [
+  { name: 'chirp', fn: makeChirp },
+  { name: 'warble', fn: makeWarble },
+  { name: 'beeps', fn: makeBeeps },
+];
+
+/**
+ * Synthesize a random R2D2-style gesture.
+ * @returns {{ name: string, wav: Buffer }}
+ */
+export function synthesizeRandom() {
+  const gesture = pick(GESTURES);
+  const samples = gesture.fn();
+  return { name: gesture.name, wav: encodeWav(samples) };
+}
+
+/**
+ * Synthesize an excited R2D2 burst (higher, faster, denser).
+ * @returns {{ name: string, wav: Buffer }}
+ */
+export function synthesizeExcited() {
+  return { name: 'excited', wav: encodeWav(makeExcited()) };
+}
+
+export { SAMPLE_RATE };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agenticros/eyes",
-  "version": "1.0.0",
-  "description": "Fullscreen robot eyes for tablet/display devices, driven by ROS 2 cmd_vel Twist",
+  "version": "1.1.0",
+  "description": "Fullscreen robot eyes for tablet/display devices, driven by ROS 2 cmd_vel Twist, with R2D2-style sounds",
   "type": "module",
   "main": "./src/index.js",
   "bin": {
@@ -9,8 +9,10 @@
   },
   "files": [
     "src",
+    "lib",
     "public",
-    "README.md"
+    "README.md",
+    "NOTICE"
   ],
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

package/src/index.js

@@ -4,6 +4,8 @@
  *
  * Subscribes to CMD_VEL_TOPIC for gaze (left/right turns). Optionally publishes
  * the same topic from invisible WASD keyboard teleop (disabled with --no-teleop).
+ * Plays procedural R2D2 chirps (idle) and excited bursts on active cmd_vel
+ * (disabled with --no-sound).
  *
  * Env (set by `agenticros eyes` from ~/.agenticros/config.json):
  *   CMD_VEL_TOPIC, MAX_LINEAR_VELOCITY, MAX_ANGULAR_VELOCITY, PORT, …
@@ -16,6 +18,12 @@ import { fileURLToPath } from "url";
 import { spawn, execFileSync } from "child_process";
 import { WebSocketServer } from "ws";
 
+import {
+  exciteFromTwist,
+  startSoundLoop,
+  stopSoundLoop,
+} from "../lib/sounds.js";
+
 const require = createRequire(import.meta.url);
 let rclnodejs;
 try {
@@ -41,6 +49,9 @@ const NO_BROWSER = process.argv.includes("--no-browser");
 const NO_TELEOP =
   process.argv.includes("--no-teleop") ||
   process.env.AGENTICROS_EYES_NO_TELEOP === "1";
+const NO_SOUND =
+  process.argv.includes("--no-sound") ||
+  process.env.AGENTICROS_EYES_NO_SOUND === "1";
 
 const MAX_LINEAR = Number(process.env.MAX_LINEAR_VELOCITY || 1.0);
 const MAX_ANGULAR = Number(process.env.MAX_ANGULAR_VELOCITY || 1.5);
@@ -348,6 +359,9 @@ async function main() {
       gazeX: state.gazeX,
       driving: state.driving,
     });
+    if (!NO_SOUND) {
+      exciteFromTwist(msg, ANGULAR_DEADZONE);
+    }
   });
 
   setInterval(() => {
@@ -377,6 +391,11 @@ async function main() {
           `(base linear=${TELOP_LINEAR}, angular=${TELOP_ANGULAR})`,
       );
     }
+    if (NO_SOUND) {
+      console.log("R2D2 sounds disabled (--no-sound)");
+    } else {
+      startSoundLoop();
+    }
     if (!NO_BROWSER) {
       launchKiosk(url);
     } else {
@@ -389,6 +408,7 @@ async function main() {
   const shutdown = async () => {
     console.log("\nShutting down…");
     try {
+      await stopSoundLoop();
       publishStop();
       wss.close();
       server.close();