@voicethere/agent 0.5.6 → 0.7.0

package/templates/positional-tts/agent.ts

@@ -0,0 +1,115 @@
+/**
+ * Positional TTS template — each listener hears TTS orbiting their own pose.
+ *
+ * Requires voice or Voice+Data runner mode ({@link isTtsPoseAvailable}). Mix group
+ * APIs still require Voice+Data ({@link isMixAvailable}).
+ *
+ * Build:
+ *   npx @voicethere/agent build --entry templates/positional-tts/agent.ts
+ */
+import {
+  agentLog,
+  clearTtsPose,
+  defineAgent,
+  isTtsPoseAvailable,
+  parseChatText,
+  setPositionalMixing,
+  setTtsPose,
+  speak,
+} from "@voicethere/agent";
+
+import { orbitTtsPose } from "./orbit.js";
+
+const ORBIT_INTERVAL_MS = 50;
+
+const orbitTimers = new Map<string, ReturnType<typeof setInterval>>();
+const sessionStartTimes = new Map<string, number>();
+
+function clearOrbit(sessionId: string): void {
+  const timer = orbitTimers.get(sessionId);
+  if (timer) {
+    clearInterval(timer);
+    orbitTimers.delete(sessionId);
+  }
+  sessionStartTimes.delete(sessionId);
+}
+
+async function safeMixCall(
+  sessionId: string,
+  label: string,
+  fn: () => Promise<{ ok: boolean; reason?: string }>,
+): Promise<void> {
+  try {
+    const result = await fn();
+    if (!result.ok) {
+      agentLog(
+        "warn",
+        `positional-tts ${label} failed: ${result.reason}`,
+        sessionId,
+      );
+    }
+  } catch (err) {
+    agentLog(
+      "warn",
+      `positional-tts ${label} error: ${String(err)}`,
+      sessionId,
+    );
+  }
+}
+
+defineAgent({
+  onAgentStart() {
+    orbitTimers.clear();
+    sessionStartTimes.clear();
+  },
+
+  onSessionStart(ctx) {
+    const { sessionId } = ctx;
+
+    if (!isTtsPoseAvailable(ctx)) {
+      agentLog(
+        "warn",
+        "positional-tts requires voice or Voice+Data — TTS pose APIs unavailable",
+        sessionId,
+      );
+      return;
+    }
+
+    void (async () => {
+      await safeMixCall(sessionId, "setPositionalMixing", () =>
+        setPositionalMixing(true),
+      );
+
+      const startMs = Date.now();
+      sessionStartTimes.set(sessionId, startMs);
+
+      const timer = setInterval(() => {
+        const started = sessionStartTimes.get(sessionId);
+        if (!started) return;
+        const elapsedSec = (Date.now() - started) / 1000;
+        void safeMixCall(sessionId, "setTtsPose", () =>
+          setTtsPose(sessionId, orbitTtsPose(elapsedSec)),
+        );
+      }, ORBIT_INTERVAL_MS);
+
+      orbitTimers.set(sessionId, timer);
+      speak(sessionId, "I'll circle around you.");
+    })();
+  },
+
+  onUserSpeechFinal({ sessionId, text }) {
+    speak(sessionId, `You said: ${text}`);
+  },
+
+  onDataChannelMessage(ctx) {
+    const text = parseChatText(ctx.message);
+    if (!text) return;
+    speak(ctx.sessionId, `You said: ${text}`);
+  },
+
+  onSessionEnd({ sessionId }) {
+    clearOrbit(sessionId);
+    void safeMixCall(sessionId, "clearTtsPose", () => clearTtsPose(sessionId));
+    agentLog("info", `positional-tts session_end ${sessionId}`, sessionId);
+  },
+});

package/templates/positional-tts/orbit.ts

@@ -0,0 +1,11 @@
+import type { MixPose } from "@voicethere/agent";
+
+/** Circle in the XZ plane around the listener origin (Y-up, look −Z). */
+export function orbitTtsPose(elapsedSec: number, radius = 2): MixPose {
+  const x = Math.cos(elapsedSec) * radius;
+  const z = Math.sin(elapsedSec) * radius;
+  return {
+    position: { x, y: 0, z },
+    orientation: { x: 0, y: 0, z: 0, w: 1 },
+  };
+}

package/templates/voice-showcase/agent.ts

@@ -19,8 +19,13 @@ import {
   handleUtterance,
   resolveWeatherTurn,
   type ConversationState,
-  type OutboundMessage,
+  type ConversationTurnResult,
 } from "./conversation.js";
+import {
+  applyOutboundOps,
+  greetingOps,
+  spokenThenPlayOps,
+} from "./delivery.js";
 
 const sessions = new Map<string, ConversationState>();
 
@@ -42,25 +47,23 @@ function relaySpeechEvent(sessionId: string, event: SpeechEvent): void {
   });
 }
 
-function deliverMessages(sessionId: string, messages: OutboundMessage[]): void {
-  for (const message of messages) {
-    sendToClient(sessionId, message);
-  }
-}
-
-function speakLines(sessionId: string, lines: string[]): void {
-  for (const line of lines) {
-    speak(sessionId, line);
-  }
+function deliverSpokenThenPlay(
+  sessionId: string,
+  result: Pick<ConversationTurnResult, "messages" | "speakLines">,
+): void {
+  applyOutboundOps(
+    sessionId,
+    spokenThenPlayOps(result.messages, result.speakLines),
+    { sendToClient, speak },
+  );
 }
 
 async function applyTurn(
   sessionId: string,
-  result: Awaited<ReturnType<typeof handleUtterance>>,
+  result: ConversationTurnResult,
 ): Promise<void> {
   sessions.set(sessionId, result.state);
-  speakLines(sessionId, result.speakLines);
-  deliverMessages(sessionId, result.messages);
+  deliverSpokenThenPlay(sessionId, result);
 
   if (result.pendingWeather) {
     const weatherResult = await resolveWeatherTurn(
@@ -69,8 +72,7 @@ async function applyTurn(
       result.pendingWeather.country,
     );
     sessions.set(sessionId, weatherResult.state);
-    speakLines(sessionId, weatherResult.speakLines);
-    deliverMessages(sessionId, weatherResult.messages);
+    deliverSpokenThenPlay(sessionId, weatherResult);
   }
 }
 
@@ -83,13 +85,10 @@ async function onUserText(sessionId: string, text: string): Promise<void> {
 defineAgent({
   onSessionStart({ sessionId }) {
     sessions.set(sessionId, createInitialState());
-    sendToClient(sessionId, {
-      type: "agent_event",
-      event: "session_start",
-      sessionId,
+    applyOutboundOps(sessionId, greetingOps(sessionId, GREETING), {
+      sendToClient,
+      speak,
     });
-    speak(sessionId, GREETING);
-    sendToClient(sessionId, { type: "chat_reply", text: GREETING });
     agentLog("info", `voice-showcase session_start ${sessionId}`);
   },
 

package/templates/voice-showcase/delivery.ts

@@ -0,0 +1,57 @@
+/**
+ * Voice-showcase outbound order: send spoken TTS text to the client first,
+ * then trigger TTS play. Parent IPC preserves this order.
+ */
+
+import type { OutboundMessage } from "./conversation.js";
+
+export type OutboundOp =
+  | { kind: "send"; message: OutboundMessage }
+  | { kind: "play"; text: string };
+
+export interface OutboundDeps {
+  sendToClient: (sessionId: string, payload: unknown) => void;
+  speak: (sessionId: string, text: string) => void;
+}
+
+/** All DataChannel payloads, then TTS play commands. */
+export function spokenThenPlayOps(
+  messages: OutboundMessage[],
+  speakLines: string[],
+): OutboundOp[] {
+  const ops: OutboundOp[] = [];
+  for (const message of messages) {
+    ops.push({ kind: "send", message });
+  }
+  for (const text of speakLines) {
+    ops.push({ kind: "play", text });
+  }
+  return ops;
+}
+
+export function greetingOps(
+  sessionId: string,
+  greeting: string,
+): OutboundOp[] {
+  return spokenThenPlayOps(
+    [
+      { type: "agent_event", event: "session_start", sessionId },
+      { type: "chat_reply", text: greeting },
+    ],
+    [greeting],
+  );
+}
+
+export function applyOutboundOps(
+  sessionId: string,
+  ops: OutboundOp[],
+  deps: OutboundDeps,
+): void {
+  for (const op of ops) {
+    if (op.kind === "send") {
+      deps.sendToClient(sessionId, op.message);
+    } else {
+      deps.speak(sessionId, op.text);
+    }
+  }
+}