first vesion

examples/webpage/README.md

@@ -0,0 +1,83 @@
+# Webpage Example — Realtime Voice Chat
+
+A self-contained browser client for the engine's product websocket
+(`/ws-product`, protocol `va.ws.v1`).
+
+## Features
+
+- **Connect / Disconnect** to any `ws://` or `wss://` URL.
+- **Mic on/off toggle** — getUserMedia is requested with
+  `echoCancellation`, `noiseSuppression`, and `autoGainControl` so the
+  browser handles AEC against the bot's voice.
+- **Text composer** — type a message and press <kbd>Enter</kbd> to send
+  an `input.text` event (Shift+Enter for newline). Sending interrupts
+  any in-flight bot audio so the next reply is heard cleanly.
+- **Chat history** rendered from `input.transcript.final` (you, when
+  spoken), streamed `response.text.delta` / `response.text.final`
+  (assistant — deltas arrive ahead of the synthesized audio), and locally
+  for text you submit (the engine doesn't echo text input back as a
+  transcript).
+- **Gapless TTS playback** by scheduling each `response.audio.delta`
+  chunk back-to-back on the AudioContext.
+- **Live VU meter** + mic and bot activity indicators.
+- **Clear** button to reset history.
+
+No build step, no dependencies — just three files plus an AudioWorklet.
+
+## Layout
+
+```text
+examples/webpage/
+├── index.html
+├── styles.css
+├── app.js
+└── pcm-recorder.worklet.js
+```
+
+## Run
+
+1. Start the engine (default port `8001`):
+
+   ```bash
+   cd AI-VideoAssistant-engine-v5-pipecat-minimal
+   source .venv/bin/activate
+   export OPENAI_API_KEY=...
+   uvicorn engine.main:app --host 127.0.0.1 --port 8001
+   ```
+
+2. In another terminal, serve the page from a port that's on the
+   engine's CORS allow-list (see `config.json`). The default config
+   allows `http://localhost:8080`:
+
+   ```bash
+   cd AI-VideoAssistant-engine-v5-pipecat-minimal/examples/webpage
+   python -m http.server 8080
+   ```
+
+3. Open <http://localhost:8080> in Chrome, Edge, or Safari.
+   - Click **Connect** (uses `ws://127.0.0.1:8001/ws-product` by default).
+   - Click **Enable mic** and start speaking. The browser will prompt
+     for microphone access on first use.
+
+> The browser's mic API requires a secure context. `http://localhost`
+> qualifies; if you serve from another host, use HTTPS and a `wss://`
+> URL.
+
+## Audio details
+
+- Input: mono Float32 from `getUserMedia` is resampled in the
+  AudioWorklet to PCM16 mono @ 16 kHz, framed into 20 ms chunks, and
+  sent as **binary** websocket messages (the server accepts either
+  binary or the JSON+base64 form).
+- Output: each `response.audio.delta` carries base64-encoded PCM16 @
+  16 kHz; chunks are decoded and scheduled back-to-back through Web
+  Audio. The browser handles resampling to the device rate.
+
+## Notes
+
+- Use headphones if you still hear echo despite browser AEC; the bot's
+  voice leaking back into the open mic is the most common cause of
+  feedback loops.
+- The engine's session has an inactivity timeout
+  (`session.inactivity_timeout_sec` in `config.json`). If the bot
+  doesn't respond after a long silence, reconnect.

examples/webpage/app.js

@@ -0,0 +1,614 @@
+/**
+ * Minimal browser client for the AI VideoAssistant engine's product
+ * websocket (`/ws-product`, protocol `va.ws.v1`).
+ *
+ * Responsibilities:
+ *   - Open/close the websocket and run the session handshake.
+ *   - Capture mic audio with echoCancellation, noiseSuppression, autoGainControl.
+ *   - Downsample to PCM16 mono @ 16 kHz in an AudioWorklet and stream frames
+ *     as binary websocket messages.
+ *   - Play `response.audio.delta` frames gaplessly through Web Audio.
+ *   - Render a chat-style history of user transcripts and bot text deltas.
+ */
+
+const SAMPLE_RATE = 16000;
+const CHANNELS = 1;
+const FRAME_MS = 20;
+const PROTOCOL = "va.ws.v1";
+
+const els = {
+  url: document.getElementById("ws-url"),
+  connectBtn: document.getElementById("connect-btn"),
+  statusDot: document.getElementById("status-dot"),
+  statusText: document.getElementById("status-text"),
+  chatLog: document.getElementById("chat-log"),
+  micBtn: document.getElementById("mic-btn"),
+  micLabel: document.querySelector(".mic-btn__label"),
+  micIndicator: document.getElementById("mic-indicator"),
+  botIndicator: document.getElementById("bot-indicator"),
+  clearBtn: document.getElementById("clear-btn"),
+  meterFill: document.getElementById("meter-fill"),
+  composer: document.getElementById("composer"),
+  textInput: document.getElementById("text-input"),
+  sendBtn: document.getElementById("send-btn"),
+};
+
+const state = {
+  ws: null,
+  connected: false,
+  connecting: false,
+
+  audioContext: null,
+  micStream: null,
+  micSourceNode: null,
+  recorderNode: null,
+
+  micEnabled: false,
+
+  // Output scheduling.
+  nextPlaybackTime: 0,
+  playbackEndsAt: 0,
+  scheduledSources: [],
+  botActive: false,
+  botUiTimer: null,
+
+  // Chat state.
+  currentAssistantBubble: null,
+
+  // VU meter smoothing.
+  meterLevel: 0,
+};
+
+/* ------------------------------------------------------------------ UI */
+
+function setStatus(kind, text) {
+  els.statusDot.className = `status__dot status__dot--${kind}`;
+  els.statusText.textContent = text;
+}
+
+function setConnectButton() {
+  if (state.connecting) {
+    els.connectBtn.textContent = "Connecting…";
+    els.connectBtn.disabled = true;
+    els.connectBtn.classList.remove("is-disconnect");
+  } else if (state.connected) {
+    els.connectBtn.textContent = "Disconnect";
+    els.connectBtn.disabled = false;
+    els.connectBtn.classList.add("is-disconnect");
+  } else {
+    els.connectBtn.textContent = "Connect";
+    els.connectBtn.disabled = false;
+    els.connectBtn.classList.remove("is-disconnect");
+  }
+}
+
+function setMicButton() {
+  els.micBtn.disabled = !state.connected;
+  els.micBtn.setAttribute("aria-pressed", state.micEnabled ? "true" : "false");
+  els.micBtn.title = state.micEnabled ? "Mute mic" : "Unmute mic";
+  els.micLabel.textContent = state.micEnabled ? "Mute mic" : "Enable mic";
+  els.micIndicator.classList.toggle("is-active", state.micEnabled);
+}
+
+function setComposerEnabled(enabled) {
+  els.textInput.disabled = !enabled;
+  els.sendBtn.disabled = !enabled || els.textInput.value.trim().length === 0;
+}
+
+function setBotIndicator(active) {
+  els.botIndicator.classList.toggle("is-active", active);
+}
+
+function addBubble(role, text) {
+  if (els.chatLog.querySelector(".chat__empty")) {
+    els.chatLog.innerHTML = "";
+  }
+  const bubble = document.createElement("div");
+  bubble.className = `bubble bubble--${role}`;
+  if (role !== "system") {
+    const tag = document.createElement("span");
+    tag.className = "bubble__role";
+    tag.textContent = role === "user" ? "You" : "Assistant";
+    bubble.appendChild(tag);
+  }
+  const body = document.createElement("span");
+  body.className = "bubble__text";
+  body.textContent = text;
+  bubble.appendChild(body);
+  els.chatLog.appendChild(bubble);
+  scrollChatToBottom();
+  return bubble;
+}
+
+function appendToBubble(bubble, text) {
+  const body = bubble.querySelector(".bubble__text");
+  body.textContent += text;
+  scrollChatToBottom();
+}
+
+function scrollChatToBottom() {
+  els.chatLog.scrollTop = els.chatLog.scrollHeight;
+}
+
+function clearChat() {
+  els.chatLog.innerHTML = "";
+  state.currentAssistantBubble = null;
+  const empty = document.createElement("div");
+  empty.className = "chat__empty";
+  empty.innerHTML = "<p>Chat cleared.</p>";
+  els.chatLog.appendChild(empty);
+}
+
+/* ---------------------------------------------------------------- Audio */
+
+async function ensureAudioContext() {
+  if (!state.audioContext) {
+    const Ctx = window.AudioContext || window.webkitAudioContext;
+    state.audioContext = new Ctx();
+    await state.audioContext.audioWorklet.addModule("./pcm-recorder.worklet.js");
+  }
+  if (state.audioContext.state === "suspended") {
+    await state.audioContext.resume();
+  }
+  return state.audioContext;
+}
+
+async function startMic() {
+  const ctx = await ensureAudioContext();
+
+  state.micStream = await navigator.mediaDevices.getUserMedia({
+    audio: {
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true,
+      channelCount: 1,
+    },
+    video: false,
+  });
+
+  state.micSourceNode = ctx.createMediaStreamSource(state.micStream);
+  state.recorderNode = new AudioWorkletNode(ctx, "pcm-recorder", {
+    numberOfInputs: 1,
+    numberOfOutputs: 0,
+    channelCount: 1,
+    processorOptions: {
+      targetSampleRate: SAMPLE_RATE,
+      frameMs: FRAME_MS,
+    },
+  });
+  state.recorderNode.port.onmessage = (event) => {
+    const data = event.data;
+    if (!data || data.type !== "frame") return;
+    updateMeter(data.rms || 0);
+    if (state.connected && state.ws && state.ws.readyState === WebSocket.OPEN) {
+      state.ws.send(data.buffer);
+    }
+  };
+
+  state.micSourceNode.connect(state.recorderNode);
+  state.micEnabled = true;
+  setMicButton();
+}
+
+function stopMic() {
+  if (state.recorderNode) {
+    try {
+      state.recorderNode.port.onmessage = null;
+      state.recorderNode.disconnect();
+    } catch (_) {
+      /* ignore */
+    }
+    state.recorderNode = null;
+  }
+  if (state.micSourceNode) {
+    try {
+      state.micSourceNode.disconnect();
+    } catch (_) {
+      /* ignore */
+    }
+    state.micSourceNode = null;
+  }
+  if (state.micStream) {
+    for (const track of state.micStream.getTracks()) {
+      try {
+        track.stop();
+      } catch (_) {
+        /* ignore */
+      }
+    }
+    state.micStream = null;
+  }
+  state.micEnabled = false;
+  updateMeter(0);
+  setMicButton();
+}
+
+function updateMeter(rms) {
+  // Smooth and convert to a 0..100 width. RMS ~0.3+ is loud speech.
+  const target = Math.min(1, rms * 2.4);
+  state.meterLevel = state.meterLevel * 0.5 + target * 0.5;
+  els.meterFill.style.width = `${Math.round(state.meterLevel * 100)}%`;
+}
+
+/* ---------------------------------------------------- Bot audio playback */
+
+function schedulePlayback(int16) {
+  const ctx = state.audioContext;
+  if (!ctx) return;
+
+  const float32 = new Float32Array(int16.length);
+  for (let i = 0; i < int16.length; i++) {
+    float32[i] = int16[i] / (int16[i] < 0 ? 0x8000 : 0x7fff);
+  }
+  const buffer = ctx.createBuffer(CHANNELS, float32.length, SAMPLE_RATE);
+  buffer.copyToChannel(float32, 0);
+
+  const src = ctx.createBufferSource();
+  src.buffer = buffer;
+  src.connect(ctx.destination);
+
+  const now = ctx.currentTime;
+  // Schedule immediately after the previously scheduled chunk to keep
+  // playback contiguous, with a tiny safety margin if we fell behind.
+  const startAt = Math.max(now + 0.02, state.nextPlaybackTime);
+  src.start(startAt);
+  state.nextPlaybackTime = startAt + buffer.duration;
+  state.playbackEndsAt = state.nextPlaybackTime;
+
+  src.onended = () => {
+    const idx = state.scheduledSources.indexOf(src);
+    if (idx >= 0) state.scheduledSources.splice(idx, 1);
+  };
+  state.scheduledSources.push(src);
+
+  setBotIndicator(true);
+  if (state.botUiTimer) clearTimeout(state.botUiTimer);
+  const msUntilEnd = Math.max(0, (state.playbackEndsAt - now) * 1000) + 120;
+  state.botUiTimer = setTimeout(() => {
+    if (state.audioContext &&
+        state.audioContext.currentTime >= state.playbackEndsAt - 0.01) {
+      setBotIndicator(false);
+    }
+  }, msUntilEnd);
+}
+
+function stopPlaybackQueue() {
+  for (const src of state.scheduledSources) {
+    try {
+      src.onended = null;
+      src.stop();
+      src.disconnect();
+    } catch (_) {
+      /* already stopped */
+    }
+  }
+  state.scheduledSources = [];
+  resetPlaybackClock();
+  if (state.botUiTimer) {
+    clearTimeout(state.botUiTimer);
+    state.botUiTimer = null;
+  }
+  setBotIndicator(false);
+}
+
+function resetPlaybackClock() {
+  if (state.audioContext) {
+    state.nextPlaybackTime = state.audioContext.currentTime;
+    state.playbackEndsAt = state.audioContext.currentTime;
+  }
+}
+
+/* --------------------------------------------------------- Chat updates */
+
+function handleUserTranscript(text) {
+  if (!text) return;
+  state.currentAssistantBubble = null;
+  addBubble("user", text);
+}
+
+function sendText(text) {
+  const value = (text || "").trim();
+  if (!value) return false;
+  if (!state.ws || state.ws.readyState !== WebSocket.OPEN) return false;
+
+  // The engine does not echo text input back as a transcript event, so we
+  // render the user bubble locally. Also interrupt any in-flight bot audio
+  // so the next reply is heard cleanly. We deliberately do NOT clear
+  // `currentAssistantBubble` here — the engine will emit a
+  // `response.text.final(interrupted=true)` for the in-flight assistant
+  // turn, which finalizes that bubble in place. A brand-new bubble for the
+  // reply will be created when `response.text.started` arrives.
+  state.ws.send(
+    JSON.stringify({
+      type: "input.text",
+      text: value,
+      interrupt: true,
+    }),
+  );
+  stopPlaybackQueue();
+  addBubble("user", value);
+  return true;
+}
+
+function handleAssistantDelta(text) {
+  if (!text) return;
+  if (!state.currentAssistantBubble) {
+    state.currentAssistantBubble = addBubble("assistant", "");
+  }
+  appendToBubble(state.currentAssistantBubble, text);
+}
+
+function handleAssistantStarted() {
+  state.currentAssistantBubble = null;
+}
+
+function handleAssistantFinal(text, interrupted) {
+  if (!text) {
+    state.currentAssistantBubble = null;
+    return;
+  }
+  if (state.currentAssistantBubble) {
+    const body = state.currentAssistantBubble.querySelector(".bubble__text");
+    body.textContent = text;
+  } else {
+    state.currentAssistantBubble = addBubble("assistant", text);
+  }
+  if (interrupted) {
+    state.currentAssistantBubble.classList.add("bubble--interrupted");
+  }
+  state.currentAssistantBubble = null;
+  scrollChatToBottom();
+}
+
+function finalizeAssistantBubble() {
+  state.currentAssistantBubble = null;
+}
+
+/* ---------------------------------------------------------- Websocket IO */
+
+function decodeBase64ToInt16(b64) {
+  const binary = atob(b64);
+  const len = binary.length;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) bytes[i] = binary.charCodeAt(i);
+  return new Int16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 2);
+}
+
+function handleEvent(event) {
+  switch (event.type) {
+    case "response.audio.delta":
+      if (typeof event.audio === "string") {
+        schedulePlayback(decodeBase64ToInt16(event.audio));
+      }
+      break;
+    case "response.audio.started":
+      setBotIndicator(true);
+      break;
+    case "response.audio.stopped":
+      finalizeAssistantBubble();
+      // The indicator turns off automatically when the playback queue drains.
+      break;
+    case "response.text.delta":
+      handleAssistantDelta(event.text);
+      break;
+    case "response.text.started":
+      handleAssistantStarted();
+      break;
+    case "response.text.final":
+      handleAssistantFinal(event.text, event.interrupted);
+      break;
+    case "input.transcript.final":
+      handleUserTranscript(event.text);
+      break;
+    case "transport.message":
+      // Reserved for future structured messages; ignore silently.
+      break;
+    default:
+      // Unknown event type: log for debugging.
+      console.debug("ws event", event);
+  }
+}
+
+async function connect() {
+  if (state.connected || state.connecting) return;
+  const url = (els.url.value || "").trim();
+  if (!url) {
+    setStatus("error", "Missing URL");
+    return;
+  }
+
+  state.connecting = true;
+  setStatus("connecting", "Connecting…");
+  setConnectButton();
+
+  try {
+    // Pre-warm audio context on user gesture so playback works on Safari.
+    await ensureAudioContext();
+  } catch (err) {
+    console.error("AudioContext failed", err);
+    state.connecting = false;
+    setStatus("error", "Audio init failed");
+    setConnectButton();
+    return;
+  }
+
+  let ws;
+  try {
+    ws = new WebSocket(url);
+  } catch (err) {
+    console.error("WebSocket constructor failed", err);
+    state.connecting = false;
+    setStatus("error", "Bad URL");
+    setConnectButton();
+    return;
+  }
+  ws.binaryType = "arraybuffer";
+  state.ws = ws;
+
+  ws.addEventListener("open", () => {
+    state.connecting = false;
+    state.connected = true;
+    resetPlaybackClock();
+    setStatus("connected", "Connected");
+    setConnectButton();
+    setMicButton();
+
+    ws.send(
+      JSON.stringify({
+        type: "session.start",
+        protocol: PROTOCOL,
+        audio: {
+          encoding: "pcm_s16le",
+          sample_rate: SAMPLE_RATE,
+          channels: CHANNELS,
+        },
+      }),
+    );
+    addBubble("system", "Session started.");
+    setComposerEnabled(true);
+    els.textInput.focus();
+  });
+
+  ws.addEventListener("message", (event) => {
+    const data = event.data;
+    if (typeof data === "string") {
+      let parsed;
+      try {
+        parsed = JSON.parse(data);
+      } catch (err) {
+        console.warn("Bad JSON from server", err, data);
+        return;
+      }
+      handleEvent(parsed);
+    } else if (data instanceof ArrayBuffer) {
+      // Server doesn't currently send binary, but handle it just in case.
+      schedulePlayback(new Int16Array(data));
+    }
+  });
+
+  ws.addEventListener("error", (err) => {
+    console.error("WebSocket error", err);
+    setStatus("error", "Connection error");
+  });
+
+  ws.addEventListener("close", (event) => {
+    const wasConnected = state.connected;
+    state.ws = null;
+    state.connected = false;
+    state.connecting = false;
+    if (state.micEnabled) stopMic();
+    stopPlaybackQueue();
+    setConnectButton();
+    setMicButton();
+    setComposerEnabled(false);
+    setBotIndicator(false);
+    if (wasConnected) {
+      addBubble(
+        "system",
+        `Session ended${event.reason ? ` — ${event.reason}` : ""}.`,
+      );
+      setStatus("idle", "Disconnected");
+    } else {
+      setStatus("error", "Connection closed");
+    }
+  });
+}
+
+function disconnect() {
+  if (!state.ws) return;
+  try {
+    if (state.ws.readyState === WebSocket.OPEN) {
+      state.ws.send(
+        JSON.stringify({ type: "session.stop", reason: "client_disconnect" }),
+      );
+    }
+  } catch (_) {
+    /* ignore */
+  }
+  try {
+    state.ws.close(1000, "client_disconnect");
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+/* ---------------------------------------------------------------- Wiring */
+
+els.connectBtn.addEventListener("click", () => {
+  if (state.connected) disconnect();
+  else connect();
+});
+
+els.micBtn.addEventListener("click", async () => {
+  if (!state.connected) return;
+  els.micBtn.disabled = true;
+  try {
+    if (state.micEnabled) {
+      stopMic();
+    } else {
+      await startMic();
+    }
+  } catch (err) {
+    console.error("Mic error", err);
+    addBubble("system", `Mic error: ${err.message || err}`);
+  } finally {
+    els.micBtn.disabled = !state.connected;
+  }
+});
+
+els.clearBtn.addEventListener("click", () => {
+  clearChat();
+});
+
+function autosizeTextarea() {
+  const ta = els.textInput;
+  ta.style.height = "auto";
+  ta.style.height = `${Math.min(ta.scrollHeight, 180)}px`;
+}
+
+function submitText() {
+  const value = els.textInput.value;
+  if (!sendText(value)) return;
+  els.textInput.value = "";
+  autosizeTextarea();
+  setComposerEnabled(state.connected);
+}
+
+els.composer.addEventListener("submit", (event) => {
+  event.preventDefault();
+  submitText();
+});
+
+els.textInput.addEventListener("input", () => {
+  autosizeTextarea();
+  setComposerEnabled(state.connected);
+});
+
+els.textInput.addEventListener("keydown", (event) => {
+  if (event.key === "Enter" && !event.shiftKey && !event.isComposing) {
+    event.preventDefault();
+    submitText();
+  }
+});
+
+window.addEventListener("beforeunload", () => {
+  if (state.ws) {
+    try {
+      state.ws.close();
+    } catch (_) {
+      /* ignore */
+    }
+  }
+  if (state.audioContext) {
+    try {
+      state.audioContext.close();
+    } catch (_) {
+      /* ignore */
+    }
+  }
+});
+
+setStatus("idle", "Disconnected");
+setConnectButton();
+setMicButton();
+setComposerEnabled(false);

examples/webpage/index.html

@@ -0,0 +1,129 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>VA Voice Chat &mdash; /ws-product</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="app">
+      <header class="app__header">
+        <div class="brand">
+          <span class="brand__dot" aria-hidden="true"></span>
+          <h1>VA Voice Chat</h1>
+        </div>
+
+        <div class="connection">
+          <label class="connection__field">
+            <span>WebSocket URL</span>
+            <input
+              id="ws-url"
+              type="text"
+              value="ws://127.0.0.1:8001/ws-product"
+              spellcheck="false"
+              autocomplete="off"
+            />
+          </label>
+          <button id="connect-btn" class="btn btn--primary" type="button">
+            Connect
+          </button>
+        </div>
+
+        <div class="status">
+          <span id="status-dot" class="status__dot status__dot--idle"></span>
+          <span id="status-text" class="status__text">Disconnected</span>
+        </div>
+      </header>
+
+      <section class="chat" aria-label="Conversation history">
+        <div id="chat-log" class="chat__log" role="log" aria-live="polite">
+          <div class="chat__empty">
+            <p>Connect to the engine, enable your mic, and start talking.</p>
+            <p class="chat__hint">
+              Audio is streamed as PCM16 mono @ 16&nbsp;kHz over
+              <code>/ws-product</code>.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      <footer class="controls" aria-label="Chat controls">
+        <div class="meter" aria-hidden="true">
+          <div id="meter-fill" class="meter__fill"></div>
+        </div>
+
+        <form id="composer" class="composer" autocomplete="off">
+          <textarea
+            id="text-input"
+            class="composer__input"
+            rows="1"
+            placeholder="Type a message, or use the mic…"
+            disabled
+          ></textarea>
+          <button
+            id="send-btn"
+            class="btn btn--primary composer__send"
+            type="submit"
+            disabled
+            title="Send message (Enter)"
+          >
+            Send
+          </button>
+        </form>
+
+        <div class="controls__row">
+          <button
+            id="mic-btn"
+            class="mic-btn"
+            type="button"
+            disabled
+            aria-pressed="false"
+            title="Mic is off"
+          >
+            <svg
+              class="mic-btn__icon"
+              viewBox="0 0 24 24"
+              width="24"
+              height="24"
+              aria-hidden="true"
+            >
+              <path
+                d="M12 14a3 3 0 0 0 3-3V6a3 3 0 1 0-6 0v5a3 3 0 0 0 3 3Z"
+                fill="currentColor"
+              />
+              <path
+                d="M19 11a1 1 0 1 0-2 0 5 5 0 0 1-10 0 1 1 0 1 0-2 0 7 7 0 0 0 6 6.92V21a1 1 0 1 0 2 0v-3.08A7 7 0 0 0 19 11Z"
+                fill="currentColor"
+              />
+            </svg>
+            <span class="mic-btn__label">Enable mic</span>
+          </button>
+
+          <div class="indicators">
+            <span id="mic-indicator" class="indicator">
+              <span class="indicator__dot indicator__dot--mic"></span>
+              <span class="indicator__label">Mic</span>
+            </span>
+            <span id="bot-indicator" class="indicator">
+              <span class="indicator__dot indicator__dot--bot"></span>
+              <span class="indicator__label">Bot</span>
+            </span>
+          </div>
+
+          <button id="clear-btn" class="btn btn--ghost" type="button">
+            Clear
+          </button>
+        </div>
+
+        <p class="hint">
+          Press <kbd>Enter</kbd> to send, <kbd>Shift</kbd>+<kbd>Enter</kbd>
+          for newline. Sending text will interrupt the bot if it's speaking.
+          Browser echo cancellation is on; use headphones if echo persists.
+        </p>
+      </footer>
+    </main>
+
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

examples/webpage/pcm-recorder.worklet.js

@@ -0,0 +1,104 @@
+/**
+ * PCM Recorder AudioWorklet.
+ *
+ * Captures mono Float32 mic samples at the AudioContext's native rate,
+ * resamples them to a target sample rate (default 16 kHz) with linear
+ * interpolation, then ships PCM16 frames of a fixed duration (default 20 ms)
+ * to the main thread via `port.postMessage(ArrayBuffer)`.
+ *
+ * It also computes a simple RMS level per frame for the UI VU meter so the
+ * main thread doesn't have to re-process the audio.
+ */
+
+class PcmRecorderProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+
+    const opts = (options && options.processorOptions) || {};
+    this._targetSampleRate = opts.targetSampleRate || 16000;
+    this._frameMs = opts.frameMs || 20;
+    this._frameSamples = Math.round(
+      (this._targetSampleRate * this._frameMs) / 1000,
+    );
+
+    // Resampling state.
+    // `ratio` is input samples per output sample.
+    this._ratio = sampleRate / this._targetSampleRate;
+    this._inputBuffer = new Float32Array(0);
+    // Float position in `_inputBuffer` for the next output sample.
+    this._inputOffset = 0;
+
+    // Output framing state.
+    this._frameBuffer = new Int16Array(this._frameSamples);
+    this._frameIndex = 0;
+
+    // VU meter accumulator.
+    this._rmsSumSquares = 0;
+    this._rmsCount = 0;
+  }
+
+  process(inputs) {
+    const input = inputs[0];
+    if (!input || input.length === 0) return true;
+    const channel = input[0];
+    if (!channel || channel.length === 0) return true;
+
+    // Append new samples to the input buffer.
+    const merged = new Float32Array(this._inputBuffer.length + channel.length);
+    merged.set(this._inputBuffer, 0);
+    merged.set(channel, this._inputBuffer.length);
+    this._inputBuffer = merged;
+
+    const ratio = this._ratio;
+    const inLen = this._inputBuffer.length;
+    let pos = this._inputOffset;
+
+    while (pos + 1 < inLen) {
+      const lo = Math.floor(pos);
+      const hi = lo + 1;
+      const w = pos - lo;
+      const sample =
+        this._inputBuffer[lo] * (1 - w) + this._inputBuffer[hi] * w;
+
+      this._rmsSumSquares += sample * sample;
+      this._rmsCount += 1;
+
+      let s = sample;
+      if (s > 1) s = 1;
+      else if (s < -1) s = -1;
+      this._frameBuffer[this._frameIndex++] =
+        s < 0 ? Math.round(s * 0x8000) : Math.round(s * 0x7fff);
+
+      if (this._frameIndex === this._frameSamples) {
+        const frame = new Int16Array(this._frameSamples);
+        frame.set(this._frameBuffer);
+        const rms =
+          this._rmsCount > 0
+            ? Math.sqrt(this._rmsSumSquares / this._rmsCount)
+            : 0;
+        this.port.postMessage(
+          { type: "frame", buffer: frame.buffer, rms },
+          [frame.buffer],
+        );
+        this._frameIndex = 0;
+        this._rmsSumSquares = 0;
+        this._rmsCount = 0;
+      }
+
+      pos += ratio;
+    }
+
+    // Trim consumed samples from the input buffer; keep at least the last
+    // sample we still need to interpolate against on the next call.
+    const consumed = Math.floor(pos);
+    if (consumed > 0) {
+      this._inputBuffer = this._inputBuffer.slice(consumed);
+      pos -= consumed;
+    }
+    this._inputOffset = pos;
+
+    return true;
+  }
+}
+
+registerProcessor("pcm-recorder", PcmRecorderProcessor);

examples/webpage/styles.css

@@ -0,0 +1,516 @@
+:root {
+  color-scheme: dark;
+  --bg: #0b0d12;
+  --bg-elevated: #131722;
+  --bg-soft: #1a2030;
+  --border: #232a3b;
+  --text: #e6e9f2;
+  --text-dim: #95a0bb;
+  --accent: #4f8cff;
+  --accent-strong: #6aa1ff;
+  --user: #2f7ff0;
+  --assistant: #2a3145;
+  --danger: #ff5577;
+  --success: #2dd28b;
+  --warning: #ffb84d;
+  --radius: 14px;
+  --shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  background: radial-gradient(
+      1200px 600px at 80% -10%,
+      rgba(79, 140, 255, 0.18),
+      transparent 60%
+    ),
+    radial-gradient(
+      900px 500px at -10% 110%,
+      rgba(45, 210, 139, 0.12),
+      transparent 60%
+    ),
+    var(--bg);
+  color: var(--text);
+}
+
+body {
+  display: flex;
+  justify-content: center;
+  padding: 24px;
+}
+
+.app {
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  gap: 16px;
+  width: min(880px, 100%);
+  height: calc(100vh - 48px);
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: 20px;
+  box-shadow: var(--shadow);
+  padding: 18px;
+}
+
+/* Header ---------------------------------------------------------------- */
+
+.app__header {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 16px;
+  padding-bottom: 14px;
+  border-bottom: 1px solid var(--border);
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.brand h1 {
+  font-size: 16px;
+  margin: 0;
+  letter-spacing: 0.2px;
+}
+
+.brand__dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background: var(--accent);
+  box-shadow: 0 0 0 4px rgba(79, 140, 255, 0.18);
+}
+
+.connection {
+  display: flex;
+  align-items: end;
+  gap: 8px;
+  min-width: 0;
+}
+
+.connection__field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+  flex: 1;
+}
+
+.connection__field span {
+  font-size: 11px;
+  color: var(--text-dim);
+  text-transform: uppercase;
+  letter-spacing: 0.8px;
+}
+
+.connection__field input {
+  background: var(--bg-soft);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 8px 10px;
+  font: inherit;
+  font-size: 13px;
+  outline: none;
+  min-width: 240px;
+}
+
+.connection__field input:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px rgba(79, 140, 255, 0.18);
+}
+
+.status {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+  color: var(--text-dim);
+  white-space: nowrap;
+}
+
+.status__dot {
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  background: var(--text-dim);
+}
+
+.status__dot--idle {
+  background: var(--text-dim);
+}
+
+.status__dot--connecting {
+  background: var(--warning);
+  animation: pulse 1.2s ease-in-out infinite;
+}
+
+.status__dot--connected {
+  background: var(--success);
+}
+
+.status__dot--error {
+  background: var(--danger);
+}
+
+/* Chat ------------------------------------------------------------------ */
+
+.chat {
+  overflow: hidden;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  display: flex;
+  flex-direction: column;
+}
+
+.chat__log {
+  flex: 1;
+  overflow-y: auto;
+  padding: 18px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  scroll-behavior: smooth;
+}
+
+.chat__empty {
+  margin: auto;
+  text-align: center;
+  color: var(--text-dim);
+}
+
+.chat__empty p {
+  margin: 4px 0;
+}
+
+.chat__hint code {
+  background: var(--bg-soft);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 1px 6px;
+  font-size: 12px;
+}
+
+.bubble {
+  max-width: 78%;
+  padding: 10px 14px;
+  border-radius: 14px;
+  line-height: 1.45;
+  font-size: 14px;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+  animation: bubble-in 0.16s ease-out;
+}
+
+.bubble--user {
+  background: var(--user);
+  color: #fff;
+  align-self: flex-end;
+  border-bottom-right-radius: 4px;
+}
+
+.bubble--assistant {
+  background: var(--assistant);
+  color: var(--text);
+  align-self: flex-start;
+  border-bottom-left-radius: 4px;
+}
+
+.bubble--assistant.bubble--interrupted {
+  opacity: 0.75;
+  border-left: 2px solid var(--warning);
+}
+
+.bubble--system {
+  align-self: center;
+  background: transparent;
+  color: var(--text-dim);
+  font-size: 12px;
+  border: 1px dashed var(--border);
+  padding: 6px 10px;
+  border-radius: 999px;
+}
+
+.bubble__role {
+  display: block;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.8px;
+  opacity: 0.7;
+  margin-bottom: 4px;
+}
+
+/* Controls -------------------------------------------------------------- */
+
+.controls {
+  display: grid;
+  gap: 10px;
+  padding: 14px 16px 6px;
+  border-top: 1px solid var(--border);
+}
+
+.meter {
+  height: 6px;
+  background: var(--bg-soft);
+  border-radius: 999px;
+  overflow: hidden;
+}
+
+.meter__fill {
+  height: 100%;
+  width: 0%;
+  background: linear-gradient(90deg, var(--success), var(--accent));
+  transition: width 80ms linear;
+}
+
+.composer {
+  display: flex;
+  align-items: flex-end;
+  gap: 8px;
+}
+
+.composer__input {
+  flex: 1;
+  resize: none;
+  background: var(--bg-soft);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 10px 12px;
+  font: inherit;
+  font-size: 14px;
+  line-height: 1.4;
+  outline: none;
+  min-height: 42px;
+  max-height: 180px;
+  overflow-y: auto;
+}
+
+.composer__input:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px rgba(79, 140, 255, 0.18);
+}
+
+.composer__input:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.composer__send {
+  padding: 10px 18px;
+  border-radius: 12px;
+  min-width: 84px;
+  align-self: flex-end;
+}
+
+.composer__send:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.controls__row {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+}
+
+.mic-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 9px 14px;
+  border-radius: 999px;
+  background: var(--bg-soft);
+  color: var(--text);
+  border: 1px solid var(--border);
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  transition: transform 0.08s ease, background 0.15s ease, color 0.15s ease,
+    border-color 0.15s ease;
+}
+
+.mic-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.mic-btn:not(:disabled):hover {
+  border-color: var(--accent);
+}
+
+.mic-btn:not(:disabled):active {
+  transform: scale(0.98);
+}
+
+.mic-btn[aria-pressed="true"] {
+  background: var(--danger);
+  border-color: var(--danger);
+  color: #fff;
+  box-shadow: 0 0 0 6px rgba(255, 85, 119, 0.18);
+}
+
+.mic-btn__icon {
+  display: block;
+}
+
+.indicators {
+  display: flex;
+  gap: 12px;
+  margin-left: auto;
+}
+
+.indicator {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  color: var(--text-dim);
+}
+
+.indicator__dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--bg-soft);
+  border: 1px solid var(--border);
+}
+
+.indicator.is-active .indicator__dot--mic {
+  background: var(--success);
+  border-color: var(--success);
+  box-shadow: 0 0 0 4px rgba(45, 210, 139, 0.2);
+}
+
+.indicator.is-active .indicator__dot--bot {
+  background: var(--accent);
+  border-color: var(--accent);
+  box-shadow: 0 0 0 4px rgba(79, 140, 255, 0.22);
+  animation: pulse 1s ease-in-out infinite;
+}
+
+.indicator.is-active .indicator__label {
+  color: var(--text);
+}
+
+.btn {
+  appearance: none;
+  border: 1px solid var(--border);
+  background: var(--bg-soft);
+  color: var(--text);
+  padding: 9px 14px;
+  border-radius: 10px;
+  font: inherit;
+  font-size: 13px;
+  cursor: pointer;
+  transition: background 0.15s ease, border-color 0.15s ease;
+}
+
+.btn:hover {
+  border-color: var(--accent);
+}
+
+.btn--primary {
+  background: var(--accent);
+  color: #fff;
+  border-color: var(--accent);
+}
+
+.btn--primary:hover {
+  background: var(--accent-strong);
+  border-color: var(--accent-strong);
+}
+
+.btn--primary.is-disconnect {
+  background: transparent;
+  color: var(--danger);
+  border-color: var(--danger);
+}
+
+.btn--ghost {
+  background: transparent;
+}
+
+.hint {
+  margin: 4px 2px 0;
+  font-size: 12px;
+  color: var(--text-dim);
+}
+
+.hint kbd {
+  background: var(--bg-soft);
+  border: 1px solid var(--border);
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  padding: 0 5px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  color: var(--text);
+}
+
+/* Animations ------------------------------------------------------------ */
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.55;
+  }
+}
+
+@keyframes bubble-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Responsive ------------------------------------------------------------ */
+
+@media (max-width: 720px) {
+  body {
+    padding: 0;
+  }
+
+  .app {
+    height: 100vh;
+    border-radius: 0;
+    border: none;
+    padding: 12px;
+  }
+
+  .app__header {
+    grid-template-columns: 1fr;
+  }
+
+  .connection {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .status {
+    justify-content: flex-end;
+  }
+
+  .indicators {
+    margin-left: 0;
+  }
+}