Port authenticated voice session UX

README.md

@@ -97,7 +97,11 @@ Three modes, picked by env (`/api/config` tells the client which one is active):
 - **`LOAD_BALANCER_URL` env** — the original flow: the browser POSTs the
   same-origin `/api/session` proxy, the server forwards to the LB, and the
   browser dials the per-session compute URL the LB hands back. The LB address
-  never reaches the browser; the Settings URL field is hidden.
+  never reaches the browser; the Settings URL field is hidden. When a visitor
+  signs in with Hugging Face, the proxy forwards their OAuth access token to the
+  allocator through `X-Reachy-Mini-Authorization`; the token remains
+  server-side. Set `REQUIRE_LOGIN=true` to reject anonymous allocation and ask
+  visitors to sign in before starting.
 - **Neither** — **Settings → Speech-to-speech server URL**: paste a full
   `connect_url` (`wss://host/v1/realtime?...`) or a bare host like `localhost:8080`
   (the app adds `/v1/realtime`), and the browser connects to it directly.
@@ -123,6 +127,8 @@ leaves the app unmetered. Tunable via env:
 |-----|---------|------|
 | `LIMIT_ANON_SEC` | `300` | Daily seconds for anonymous visitors (5 min) |
 | `LIMIT_FREE_SEC` | `600` | Daily seconds for signed-in non-PRO users (10 min) |
+| `REQUIRE_LOGIN` | unset | Set to `true` to require HF sign-in before allocating or claiming a session |
+| `STARTUP_GREETING` | one-sentence greeting prompt | Hidden prompt that opens the conversation and warms the model; set empty to disable |
 | `UNLIMITED_ORGS` | _(adds to defaults)_ | Extra HF org names whose members get **unlimited** usage, like PRO |
 | `USAGE_HASH_SECRET` | _(random)_ | HMAC secret for hashing identity keys + signing the anon cookie |
 
@@ -155,6 +161,8 @@ Then open <http://localhost:7860/>, click the orb, allow the mic, talk.
 | Key | What |
 |-----|------|
 | Load balancer URL | Base URL of your S2S deployment. App POSTs `<lb>/session`. |
+| Microphone | Input device for capture. Applies on the next conversation or Restart. |
+| Speakers | Assistant-audio output. Chrome/Edge can switch live; other browsers use the system default. |
 | Voice | Qwen3-TTS speaker name (Aiden, Ryan, Dylan, Eric, Ono_Anna, Serena, Sohee, Uncle_Fu, Vivian) |
 | Instructions | System prompt sent in `session.update` once the WS opens |
 
@@ -173,12 +181,18 @@ NOT collide with the WebRTC variant.
 | `auth.py` | HF OAuth + per-request identity (tier, hashed keys) |
 | `limiter.py` | SQLite per-day talk-time budget (chunked server-clock reservation) |
 | `ws/s2s-ws-client.js` | WebSocket handshake + OpenAI Realtime GA protocol |
+| `ws/user-audio-recorder.js` | Bounded browser-local PCM capture and WAV replay for user turns |
 | `ws/codec.js` | base64 <-> PCM helpers + transcript extraction (pure) |
 | `ws/orb-visualizer.js` | `OrbVisualiser`: FFT bands -> orb CSS custom properties |
 | `worklets/mic-capture.js` | AudioWorklet: 48 kHz Float32 -> 16 kHz Int16 PCM, posts ~40 ms chunks |
 | `worklets/audio-playback.js` | AudioWorklet: 24 kHz Float32 ring buffer -> 48 kHz, linear interp, fade in/out |
 | `style.css` | Orb animations, layout, dark theme (verbatim from the WebRTC app) |
 
+The chat history keeps the exact post-gate audio sent over WebSocket and exposes
+it through a local replay control. Backend VAD also drives an immediate
+“Listening…” → “Sending voice…” bubble; when STT is enabled, the same bubble and
+history row are updated with the transcript.
+
 ## Audio pipeline notes
 
 - **Input**: `getUserMedia({ echoCancellation, noiseSuppression, autoGainControl })`

auth.py

@@ -106,6 +106,19 @@ def current_user(request):
     return _field(current_oauth(request), "user_info")
 
 
+def current_access_token(request) -> "str | None":
+    """The signed-in user's HF OAuth access token, or None.
+
+    Keep this server-side: it is used to attribute load-balancer session
+    requests to the signed-in HF account and must never be returned to the
+    browser.
+    """
+    token = _field(current_oauth(request), "access_token")
+    if token is None:
+        return None
+    return str(token).strip() or None
+
+
 def _user_org_names(user) -> "set[str]":
     """The user's organisations from the OAuth userinfo, by username/name/id."""
     names = set()

index.html

@@ -258,6 +258,24 @@
               </label>
             </div>
 
+            <label class="field">
+              <span>Microphone</span>
+              <select id="audio-input">
+                <option value="">System default</option>
+              </select>
+              <small>Applies on the next conversation (or Restart).</small>
+            </label>
+
+            <label class="field" id="audio-output-field">
+              <span>Speakers</span>
+              <select id="audio-output">
+                <option value="">System default</option>
+              </select>
+              <small id="audio-output-hint">
+                Where assistant audio plays. Chrome/Edge support switching outputs.
+              </small>
+            </label>
+
             <div class="field">
               <span class="field-head">
                 Noise gate

main.js

@@ -44,6 +44,8 @@ const STORAGE_KEYS = {
   tools: "s2s.ws.tools",
   searchKey: "s2s.ws.searchKey",
   noiseGate: "s2s.ws.noiseGate",
+  audioInputId: "s2s.audio.inputId",
+  audioOutputId: "s2s.audio.outputId",
 };
 
 // ── Noise gate ──────────────────────────────────────────────────────────────
@@ -102,6 +104,8 @@ function loadSettings() {
     voice: localStorage.getItem(STORAGE_KEYS.voice) || DEFAULT_VOICE,
     instructions: localStorage.getItem(STORAGE_KEYS.instructions) || DEFAULT_INSTRUCTIONS,
     noiseGate: loadGateThreshold(),
+    audioInputId: localStorage.getItem(STORAGE_KEYS.audioInputId) || "",
+    audioOutputId: localStorage.getItem(STORAGE_KEYS.audioOutputId) || "",
   };
 }
 
@@ -124,6 +128,8 @@ function saveSettings(s) {
   localStorage.setItem(STORAGE_KEYS.voice, s.voice);
   localStorage.setItem(STORAGE_KEYS.instructions, s.instructions);
   localStorage.setItem(STORAGE_KEYS.noiseGate, String(s.noiseGate));
+  localStorage.setItem(STORAGE_KEYS.audioInputId, s.audioInputId || "");
+  localStorage.setItem(STORAGE_KEYS.audioOutputId, s.audioOutputId || "");
 }
 
 /** @returns {{ web_search: boolean, camera_snapshot: boolean }} */
@@ -238,6 +244,12 @@ const connField = $("#conn-field");
 const connHint = $("#conn-hint");
 /** @type {HTMLSelectElement} */
 const inputVoice = $("#voice");
+/** @type {HTMLSelectElement} */
+const inputAudioInput = $("#audio-input");
+/** @type {HTMLSelectElement} */
+const inputAudioOutput = $("#audio-output");
+/** @type {HTMLElement} */
+const audioOutputHint = $("#audio-output-hint");
 /** @type {HTMLTextAreaElement} */
 const inputInstructions = $("#instructions");
 /** @type {HTMLInputElement} */
@@ -280,6 +292,9 @@ let allowDirect = true;
 // Deploy-pinned s2s URL (SPEECH_TO_SPEECH_URL). Non-empty -> locked direct
 // mode: the field displays it read-only and the saved user URL is untouched.
 let pinnedUrl = "";
+// Optional hidden user prompt supplied by the deployment. When non-empty, the
+// client asks the model to greet once after the initial session configuration.
+let startupGreeting = "";
 
 // ── Tool state ──────────────────────────────────────────────────────────────
 let toolsEnabled = loadTools();
@@ -321,7 +336,13 @@ function pushToolsToSession() {
 // ── Chat view ───────────────────────────────────────────────────────────────
 // Owns the history panel, the ephemeral bubbles, and all transcript/tool
 // streaming state. The client's events are forwarded to its on* methods.
-const chat = new ChatView();
+let userAudioReplaying = false;
+const chat = new ChatView({
+  onUserAudioPlaybackChange(playing) {
+    userAudioReplaying = playing;
+    syncMicMuteState();
+  },
+});
 
 // ── Account / limiter ─────────────────────────────────────────────────────
 // Login chip + daily-limit modal (inert unless the deploy is in LB mode). The
@@ -329,6 +350,7 @@ const chat = new ChatView();
 // and tears down when the server reports the budget is spent.
 const account = new Account();
 let limiterOn = false;
+let loginRequired = false;
 let heartbeatTimer = 0;
 let trackedSessionId = "";
 let trackedTier = "";
@@ -342,6 +364,15 @@ let client = null;
 let micStream = null;
 let micMuted = false;
 
+/** Apply both the user's mute choice and the temporary replay guard. */
+function syncMicMuteState() {
+  const muted = micMuted || userAudioReplaying;
+  for (const track of micStream?.getAudioTracks() ?? []) {
+    track.enabled = !muted;
+  }
+  client?.setMuted(muted);
+}
+
 /** @param {AppState} next */
 function setState(next) {
   currentState = next;
@@ -408,6 +439,7 @@ function openSettings() {
   inputInstructions.value = settings.instructions;
   syncGateUi();
   updateRestartAvailability();
+  void refreshAudioDeviceLists();
   settingsModal.showModal();
 }
 
@@ -837,6 +869,10 @@ async function fetchConfig() {
       allowDirect = json.allowDirect ?? !lbMode;
       // Deploy-pinned direct URL (overrides the LB server-side already).
       pinnedUrl = (json.s2sUrl || "").trim();
+      startupGreeting = typeof json.startupGreeting === "string"
+        ? json.startupGreeting.trim()
+        : "";
+      loginRequired = !!json.requireLogin;
       // The conversation-time limiter rides on the LB being present.
       limiterOn = lbMode;
     }
@@ -846,7 +882,10 @@ async function fetchConfig() {
   }
   if (DEBUG) console.debug(`[ui] config: allowDirect=${allowDirect} lbMode=${lbMode}`);
   // Login chip + remaining-budget (no-op / hidden when the limiter is off).
-  void account.refresh();
+  await account.refresh();
+  if (currentState === "idle" && loginRequired && !account.loggedIn) {
+    setCaption("Sign in to start");
+  }
   syncToolsUi();
   syncConnectionUi();
 }
@@ -920,6 +959,8 @@ function readSettingsFromForm() {
     voice: inputVoice.value || DEFAULT_VOICE,
     instructions: inputInstructions.value.trim() || DEFAULT_INSTRUCTIONS,
     noiseGate: readGateThreshold(),
+    audioInputId: inputAudioInput.value || "",
+    audioOutputId: inputAudioOutput.value || "",
   };
 }
 
@@ -978,9 +1019,12 @@ settingsForm.addEventListener("submit", (event) => {
   saveSettings(settings);
 
   // Voice + instructions can apply to a live session without reconnecting; a
-  // changed connection URL only takes effect on the next restart.
+  // changed connection URL only takes effect on the next restart. Speaker
+  // output can switch live when the browser supports AudioContext.setSinkId;
+  // mic device changes need a Restart (new getUserMedia stream).
   if (client && LIVE_STATES.has(currentState)) {
     client.updateSession({ voice: settings.voice, instructions: effectiveInstructions() });
+    void client.setAudioOutputDevice(settings.audioOutputId);
   }
 });
 
@@ -992,6 +1036,10 @@ inputNoiseGate.addEventListener("input", () => {
 
 restartBtn.addEventListener("click", async () => {
   if (currentState === "connecting") return; // a connect is already underway
+  if (loginRequired && !account.loggedIn) {
+    account.showLoginRequired();
+    return;
+  }
   settings = readSettingsFromForm();
   saveSettings(settings);
   if (missingServerUrl()) { promptServerUrl(); return; } // keep settings open
@@ -1010,6 +1058,10 @@ restartBtn.addEventListener("click", async () => {
 circleBtn.addEventListener("click", async () => {
   try {
     if (currentState === "idle" || currentState === "error") {
+      if (loginRequired && !account.loggedIn) {
+        account.showLoginRequired();
+        return;
+      }
       if (missingServerUrl()) { promptServerUrl(); return; }
       await doStart();
     }
@@ -1022,6 +1074,11 @@ circleBtn.addEventListener("click", async () => {
  *  a real fault (surface it). doStart already closed any orphan AudioContext.
  *  @param {any} err */
 async function handleStartError(err) {
+  if (err && err.code === "login-required") {
+    await teardown();
+    account.showLoginRequired(err.loginUrl);
+    return;
+  }
   if (err && err.code === "limit") {
     await teardown();
     account.showLimit(err.tier);
@@ -1055,10 +1112,7 @@ async function handleStartError(err) {
 micBtn.addEventListener("click", () => {
   if (!micStream || !client) return;
   micMuted = !micMuted;
-  for (const track of micStream.getAudioTracks()) {
-    track.enabled = !micMuted;
-  }
-  client.setMuted(micMuted);
+  syncMicMuteState();
   micBtn.classList.toggle("muted", micMuted);
   micBtn.setAttribute("aria-label", micMuted ? "Unmute" : "Mute");
   micBtn.title = micMuted ? "Unmute" : "Mute";
@@ -1081,16 +1135,104 @@ joinQueueBtn.addEventListener("click", () => {
   if (client) client.join();
 });
 
-const MIC_CONSTRAINTS = {
-  audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
+const MIC_CONSTRAINTS_BASE = {
+  echoCancellation: true,
+  noiseSuppression: true,
+  autoGainControl: true,
 };
 
+/** @returns {MediaStreamConstraints} */
+function micConstraints() {
+  /** @type {MediaTrackConstraints} */
+  const audio = { ...MIC_CONSTRAINTS_BASE };
+  if (settings.audioInputId) {
+    // ideal (not exact): if the saved device was unplugged, fall back quietly.
+    audio.deviceId = { ideal: settings.audioInputId };
+  }
+  return { audio };
+}
+
+/** True when Web Audio can route playback to a chosen output device. */
+function supportsAudioOutputSelection() {
+  const Ctx = window.AudioContext || /** @type {any} */ (window).webkitAudioContext;
+  return typeof Ctx?.prototype?.setSinkId === "function";
+}
+
+/**
+ * Rebuild the mic/speaker <select>s from enumerateDevices. Labels are blank
+ * until mic permission has been granted at least once.
+ */
+async function refreshAudioDeviceLists() {
+  const canPickOutput = supportsAudioOutputSelection();
+  inputAudioOutput.disabled = !canPickOutput;
+  audioOutputHint.textContent = canPickOutput
+    ? "Where assistant audio plays. Can change live while connected."
+    : "Speaker selection needs a browser with AudioContext.setSinkId (Chrome/Edge).";
+
+  /** @type {MediaDeviceInfo[]} */
+  let devices = [];
+  try {
+    devices = await navigator.mediaDevices.enumerateDevices();
+  } catch (err) {
+    console.warn("[main] enumerateDevices failed:", err);
+  }
+
+  const inputs = devices.filter((d) => d.kind === "audioinput");
+  const outputs = devices.filter((d) => d.kind === "audiooutput");
+  const labelsReady = devices.some((d) => d.label);
+
+  fillDeviceSelect(inputAudioInput, inputs, settings.audioInputId, "Microphone");
+  fillDeviceSelect(inputAudioOutput, outputs, settings.audioOutputId, "Speaker");
+
+  const hint = inputAudioInput.parentElement?.querySelector("small");
+  if (hint) {
+    hint.textContent = labelsReady
+      ? "Applies on the next conversation (or Restart)."
+      : "Allow microphone access (tap Start once) to see device names. Mic changes apply on Restart.";
+  }
+}
+
+/**
+ * @param {HTMLSelectElement} select
+ * @param {MediaDeviceInfo[]} devices
+ * @param {string} selectedId
+ * @param {string} fallbackLabel
+ */
+function fillDeviceSelect(select, devices, selectedId, fallbackLabel) {
+  const prev = selectedId || select.value || "";
+  select.replaceChildren();
+  const def = document.createElement("option");
+  def.value = "";
+  def.textContent = "System default";
+  select.appendChild(def);
+  devices.forEach((d, i) => {
+    const opt = document.createElement("option");
+    opt.value = d.deviceId;
+    opt.textContent = d.label || `${fallbackLabel} ${i + 1}`;
+    select.appendChild(opt);
+  });
+  if (prev && ![...select.options].some((o) => o.value === prev)) {
+    const missing = document.createElement("option");
+    missing.value = prev;
+    missing.textContent = `${fallbackLabel} (saved, not found)`;
+    select.appendChild(missing);
+  }
+  select.value = prev;
+  if (select.value !== prev) select.value = "";
+}
+
+if (navigator.mediaDevices?.addEventListener) {
+  navigator.mediaDevices.addEventListener("devicechange", () => {
+    if (settingsModal.open) void refreshAudioDeviceLists();
+  });
+}
+
 /** Prompt for mic permission up front, then immediately release the tracks so no
  *  recording indicator lingers during a queue wait. Throws a friendly error if the
  *  user denies. */
 async function primeMicPermission() {
   try {
-    const s = await navigator.mediaDevices.getUserMedia(MIC_CONSTRAINTS);
+    const s = await navigator.mediaDevices.getUserMedia(micConstraints());
     for (const track of s.getTracks()) track.stop();
   } catch (err) {
     throw new Error(
@@ -1102,7 +1244,7 @@ async function primeMicPermission() {
 /** Acquire the live capture stream once a slot is granted. Permission was primed
  *  in the tap gesture, so this is silent. Stored module-side for mute + teardown. */
 async function acquireMicStream() {
-  micStream = await navigator.mediaDevices.getUserMedia(MIC_CONSTRAINTS);
+  micStream = await navigator.mediaDevices.getUserMedia(micConstraints());
   return micStream;
 }
 
@@ -1183,12 +1325,15 @@ async function doStart(audioContext = null) {
     ...target,
     voice: settings.voice,
     instructions: effectiveInstructions(),
+    startupGreeting,
     acquireMic: acquireMicStream,
     tools: activeToolDefs(),
     noiseGate: gateParams(settings.noiseGate),
+    audioOutputId: settings.audioOutputId || "",
     ...(audioContext ? { audioContext } : {}),
   });
   client = c;
+  c.setMuted(micMuted || userAudioReplaying);
 
   c.addEventListener("queue", (e) => {
     const { position, queueId } = /** @type {CustomEvent<{ position: number; queueId: string }>} */ (e).detail;
@@ -1212,11 +1357,24 @@ async function doStart(audioContext = null) {
   c.addEventListener("status", (e) => {
     const detail = /** @type {CustomEvent<{ status: string }>} */ (e).detail;
     onClientStatus(detail.status);
+    if (detail.status === "ai-speaking") chat.onAssistantActivity();
   });
   c.addEventListener("transcript", (e) => {
     const d = /** @type {CustomEvent<{ role: "user" | "assistant"; text: string; partial: boolean; itemId?: string; responseId?: string }>} */ (e).detail;
     chat.onTranscript(d);
   });
+  c.addEventListener("user-turn-started", (e) => {
+    const detail = /** @type {CustomEvent<{ itemId?: string }>} */ (e).detail;
+    chat.onUserTurnStarted(detail);
+  });
+  c.addEventListener("user-turn-stopped", (e) => {
+    const detail = /** @type {CustomEvent<{ itemId?: string }>} */ (e).detail;
+    chat.onUserTurnStopped(detail);
+  });
+  c.addEventListener("user-audio", (e) => {
+    const detail = /** @type {CustomEvent<{ itemId?: string; audio: Blob; durationMs?: number; truncated?: boolean }>} */ (e).detail;
+    chat.onUserAudio(detail);
+  });
 
   c.addEventListener("response-finished", (e) => {
     const detail = /** @type {CustomEvent<{ responseId: string; status: string; audible?: boolean; transcript?: string }>} */ (e).detail;

server.py

@@ -77,10 +77,24 @@ if SPEECH_TO_SPEECH_URL:
 # but nothing is metered: no budget, no reservations, no sign-in gating.
 SPACE_ID = os.environ.get("SPACE_ID", "").strip()
 LIMITER_ENABLED = bool(LOAD_BALANCER_URL) and bool(SPACE_ID)
+# Optional deployment gate. When enabled, session allocation fails closed unless
+# Hugging Face OAuth is available and the requester is signed in.
+REQUIRE_LOGIN = os.environ.get("REQUIRE_LOGIN", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+DEFAULT_STARTUP_GREETING = (
+    "Start the conversation now with a brief, spontaneous greeting in character. "
+    "Keep it to one sentence, invite the user in naturally, and vary the wording each time."
+)
+STARTUP_GREETING = os.environ.get("STARTUP_GREETING", DEFAULT_STARTUP_GREETING).strip()
 SERPER_URL = "https://google.serper.dev/search"
 # Cap results so the tool output stays small enough to feed back to the model.
 MAX_RESULTS = 5
 HERE = os.path.dirname(os.path.abspath(__file__))
+LB_USER_AGENT = "hf-realtime-voice-space"
 
 app = FastAPI(title="s2s-demo")
 
@@ -127,7 +141,9 @@ def config():
         # Deploy-pinned direct s2s URL (empty when unset). Not a secret: the
         # browser dials it itself, and Settings shows it locked.
         "s2sUrl": SPEECH_TO_SPEECH_URL,
+        "startupGreeting": STARTUP_GREETING,
         "auth": AUTH_ENABLED,
+        "requireLogin": REQUIRE_LOGIN,
     }
 
 
@@ -144,6 +160,7 @@ async def me(request: Request):
     out = {
         "enabled": True,
         "auth": AUTH_ENABLED,
+        "loginRequired": REQUIRE_LOGIN,
         **view,
         "remainingSec": rem,
         "limitSec": limiter.budget_for(tier),
@@ -156,6 +173,26 @@ async def me(request: Request):
     return resp
 
 
+def _login_gate(request: Request) -> JSONResponse | None:
+    """Reject anonymous session use when this deployment requires HF login."""
+    if not REQUIRE_LOGIN:
+        return None
+    if not AUTH_ENABLED:
+        return JSONResponse(
+            {"reason": "auth_unavailable"},
+            status_code=503,
+        )
+    if auth.current_user(request) is None:
+        return JSONResponse(
+            {
+                "reason": "login_required",
+                "loginUrl": auth.OAUTH_LOGIN_PATH,
+            },
+            status_code=401,
+        )
+    return None
+
+
 @app.post("/api/search")
 async def search(req: SearchRequest):
     """Proxy a Google search via Serper.dev. The key stays on the server unless
@@ -230,6 +267,10 @@ async def session(request: Request):
         # never call this. 404 so it's indistinguishable from a missing route.
         raise HTTPException(status_code=404, detail="Not found.")
 
+    login_error = _login_gate(request)
+    if login_error is not None:
+        return login_error
+
     tier, keys, set_cookie = auth.resolve_identity(request)
     # Metering runs only on the deployed Space; off-Space the LB still proxies but
     # nothing is tracked. Within metering, unlimited tiers (pro, org) aren't either.
@@ -250,7 +291,11 @@ async def session(request: Request):
     url = f"{LOAD_BALANCER_URL.rstrip('/')}/session"
     try:
         async with httpx.AsyncClient(timeout=15.0) as http:
-            lb = await http.post(url, headers={"Content-Type": "application/json"}, content="{}")
+            lb = await http.post(
+                url,
+                headers=_load_balancer_headers(request),
+                content="{}",
+            )
     except httpx.RequestError as exc:
         logger.warning("Load balancer unreachable: %r", exc)
         raise HTTPException(status_code=502, detail="Speech service unreachable.")
@@ -286,6 +331,24 @@ async def session(request: Request):
     return await _finalize_grant(data, keys, tier, tracked, set_cookie)
 
 
+def _load_balancer_headers(request: Request) -> dict[str, str]:
+    """Headers for the server-to-server session allocation request.
+
+    Reachy Mini uses this dedicated header for an optional HF user token. The
+    load balancer fingerprints it immediately and resolves the account through
+    whoami asynchronously, so allocation remains fast. Anonymous visitors send
+    no credential header.
+    """
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": LB_USER_AGENT,
+    }
+    token = auth.current_access_token(request)
+    if token:
+        headers["X-Reachy-Mini-Authorization"] = f"Bearer {token}"
+    return headers
+
+
 @app.get("/api/queue/{queue_id}")
 async def queue_status(queue_id: str, request: Request):
     """Poll a waiting ticket: relay the position, or — when the head of the line
@@ -294,6 +357,10 @@ async def queue_status(queue_id: str, request: Request):
     if not LOAD_BALANCER_URL:
         raise HTTPException(status_code=404, detail="Not found.")
 
+    login_error = _login_gate(request)
+    if login_error is not None:
+        return login_error
+
     tier, keys, set_cookie = auth.resolve_identity(request)
     tracked = LIMITER_ENABLED and limiter.budget_for(tier) is not None
 

style.css

@@ -1752,6 +1752,52 @@ body.cam-on .footer {
 .bubble.user .bubble-role { color: var(--voice-user); }
 .bubble.assistant .bubble-role { color: var(--voice-assistant); }
 
+.bubble.user.voice .bubble-body {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  min-width: 126px;
+  color: var(--text-dim);
+}
+.voice-turn-wave {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  height: 16px;
+  color: var(--voice-user);
+}
+.voice-turn-wave i {
+  display: block;
+  width: 2px;
+  height: 12px;
+  border-radius: 999px;
+  background: currentColor;
+  transform-origin: center;
+  animation: user-turn-wave 0.85s ease-in-out infinite;
+}
+.voice-turn-wave i:nth-child(2),
+.voice-turn-wave i:nth-child(4) {
+  animation-delay: -0.22s;
+}
+.voice-turn-wave i:nth-child(3) {
+  animation-delay: -0.44s;
+}
+.voice-turn-wave i:nth-child(5) {
+  animation-delay: -0.11s;
+}
+.bubble.user.sending .voice-turn-wave i {
+  animation-duration: 1.15s;
+}
+.voice-turn-state {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  letter-spacing: 0.02em;
+}
+@keyframes user-turn-wave {
+  0%, 100% { transform: scaleY(0.28); opacity: 0.5; }
+  50% { transform: scaleY(1); opacity: 1; }
+}
+
 /* ─── Conversation history panel ─────────────────────────────────────── */
 
 .chat-panel {
@@ -1884,6 +1930,29 @@ body.cam-on .footer {
  * distinguishing, so the panel reads as one quiet column. */
 .hist-msg.user .hist-body.partial { opacity: 0.65; }
 
+.hist-audio {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  padding: 8px 10px;
+  border: 1px solid color-mix(in srgb, var(--voice-user) 22%, var(--border));
+  border-radius: var(--radius-md);
+  background: color-mix(in srgb, var(--voice-user) 6%, var(--bg-elev-2));
+}
+.hist-audio-label {
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: color-mix(in srgb, var(--voice-user) 68%, var(--text-faint));
+}
+.hist-audio audio {
+  display: block;
+  width: min(260px, 100%);
+  height: 34px;
+  color-scheme: light dark;
+}
+
 /* ─── Tool call history item ─────────────────────────────────────────── */
 
 .hist-tool-header {
@@ -2549,6 +2618,9 @@ body.cam-on .footer {
   }
 }
 @media (prefers-reduced-motion: reduce) {
+  .voice-turn-wave i {
+    animation: none;
+  }
   .cam-pip {
     transition: opacity 0.22s ease;
     transform: none;

ui/account.js

@@ -36,7 +36,7 @@ export class Account {
     /** @type {HTMLAnchorElement} */
     this._modalCta = /** @type {any} */ ($("#limit-cta"));
 
-    /** @type {{enabled:boolean, auth?:boolean, loggedIn?:boolean, username?:string, avatar?:string, tier?:string, remainingSec?:number|null, limitSec?:number|null, loginUrl?:string|null, logoutUrl?:string|null}} */
+    /** @type {{enabled:boolean, auth?:boolean, loginRequired?:boolean, loggedIn?:boolean, username?:string, avatar?:string, tier?:string, remainingSec?:number|null, limitSec?:number|null, loginUrl?:string|null, logoutUrl?:string|null}} */
     this._me = { enabled: false };
     this._popoverOpen = false;
 
@@ -56,6 +56,14 @@ export class Account {
     return this._me.tier || "anon";
   }
 
+  get loggedIn() {
+    return !!this._me.loggedIn;
+  }
+
+  get loginUrl() {
+    return this._me.loginUrl || "";
+  }
+
   /** Fetch `/api/me` and (re)render the chip. Safe to call repeatedly (load,
    *  after the OAuth redirect, after a conversation ends). */
   async refresh() {
@@ -80,7 +88,8 @@ export class Account {
     if (!me.loggedIn) {
       // Signed-out: a sign-in pill (only when OAuth is actually available).
       if (me.auth && me.loginUrl) {
-        this._root.innerHTML = `<a class="signin-pill" href="${escHtml(me.loginUrl)}" title="Sign in for more time"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4"/><polyline points="10 17 15 12 10 7"/><line x1="15" y1="12" x2="3" y2="12"/></svg><span>Sign in</span></a>`;
+        const title = me.loginRequired ? "Sign in to use the demo" : "Sign in for more time";
+        this._root.innerHTML = `<a class="signin-pill" href="${escHtml(me.loginUrl)}" title="${escHtml(title)}"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4"/><polyline points="10 17 15 12 10 7"/><line x1="15" y1="12" x2="3" y2="12"/></svg><span>Sign in</span></a>`;
       } else {
         this._root.innerHTML = "";
         this._root.hidden = true;
@@ -176,6 +185,23 @@ export class Account {
     if (!this._modal.open) this._modal.showModal();
   }
 
+  /** Prompt an anonymous visitor to sign in before starting a conversation.
+   *  @param {string} [loginUrl] */
+  showLoginRequired(loginUrl = this.loginUrl) {
+    this._modalTitle.textContent = "Sign in to start";
+    this._modalMsg.textContent =
+      "This demo is available to signed-in Hugging Face users.";
+    this._modalNote.textContent = "A Hugging Face account is free.";
+    if (loginUrl) {
+      this._modalCta.innerHTML = `${HF_MARK}<span>Sign in with Hugging Face</span>`;
+      this._modalCta.href = loginUrl;
+      this._modalCta.hidden = false;
+    } else {
+      this._modalCta.hidden = true;
+    }
+    if (!this._modal.open) this._modal.showModal();
+  }
+
   /** Show a warm "we're at capacity" message when even the waiting line is full.
    *  Reuses the limit modal shell; no call-to-action, just reassurance. */
   showBusy() {

ui/chat.js

@@ -2,8 +2,8 @@
 /**
  * ChatView — owns the whole conversation surface: the slide-in history panel,
  * the ephemeral on-orb bubbles, and all the transcript/tool/streaming
- * bookkeeping. main.js wires the realtime client's events straight to the
- * `on*` methods here and otherwise doesn't touch chat state.
+ * and user-audio bookkeeping. main.js wires the realtime client's events
+ * straight to the `on*` methods here and otherwise doesn't touch chat state.
  *
  * Two parallel surfaces share one shape (see `_buildMessageEl`):
  *   - ephemeral bubbles  (`.bubble` / `.bubble-*`)  fade on a timer
@@ -24,7 +24,10 @@ const CHAT_BUBBLE_SVG = `<svg width="28" height="28" viewBox="0 0 24 24" fill="n
 const EMPTY_STATE_HTML = `<div id="chat-empty" class="chat-empty">${CHAT_BUBBLE_SVG}<span class="chat-empty-title">No messages yet</span><span class="chat-empty-hint">Tap the orb and start talking</span></div>`;
 
 export class ChatView {
-  constructor() {
+  /**
+   * @param {{ onUserAudioPlaybackChange?: (playing: boolean) => void }} [options]
+   */
+  constructor(options = {}) {
     /** @type {HTMLButtonElement} */
     this._chatBtn = $("#chat-btn");
     /** @type {HTMLSpanElement} */
@@ -46,6 +49,13 @@ export class ChatView {
     // ── User transcript state (keyed by item_id) ───────────────────────────
     /** @type {Map<string, HTMLElement>} */
     this._userHistByItem = new Map();
+    /** @type {Map<string, { audio: HTMLAudioElement, url: string }>} */
+    this._userAudioByItem = new Map();
+    /** @type {Set<string>} */
+    this._audioUrls = new Set();
+    /** @type {HTMLAudioElement | null} */
+    this._activeUserAudio = null;
+    this._onUserAudioPlaybackChange = options.onUserAudioPlaybackChange ?? (() => {});
     /** @type {HTMLElement | null} */
     this._activeUserBubble = null;
     this._activeUserItemId = "";
@@ -121,7 +131,7 @@ export class ChatView {
     const el = document.createElement("div");
     el.className = `${container} ${role}`;
     const label = role === "user" ? "You" : "Assistant";
-    el.innerHTML = `<div class="${prefix}-role">${label}</div><div class="${prefix}-body${partial ? " partial" : ""}">${escHtml(text)}</div>`;
+    el.innerHTML = `<div class="${prefix}-role">${label}</div><div class="${prefix}-body${partial ? " partial" : ""}"${text ? "" : " hidden"}>${escHtml(text)}</div>`;
     return el;
   }
 
@@ -148,10 +158,50 @@ export class ChatView {
     return el;
   }
 
+  /**
+   * Show an immediate placeholder for a user voice turn. It occupies the same
+   * bubble as a transcript would, so a late STT event can replace the animation
+   * in place instead of adding a second user message.
+   * @param {"listening"|"sending"} state
+   * @returns {HTMLElement}
+   */
+  _spawnVoiceBubble(state) {
+    const el = this._spawnBubble("user", "");
+    el.classList.add("voice");
+    el.setAttribute("role", "status");
+    el.setAttribute("aria-live", "polite");
+    const body = /** @type {HTMLElement | null} */ (el.querySelector(".bubble-body"));
+    if (body) {
+      body.hidden = false;
+      body.innerHTML = `
+        <span class="voice-turn-wave" aria-hidden="true">
+          <i></i><i></i><i></i><i></i><i></i>
+        </span>
+        <span class="voice-turn-state"></span>
+      `;
+    }
+    this._setVoiceBubbleState(el, state);
+    return el;
+  }
+
+  /** @param {HTMLElement} el @param {"listening"|"sending"} state */
+  _setVoiceBubbleState(el, state) {
+    el.classList.toggle("listening", state === "listening");
+    el.classList.toggle("sending", state === "sending");
+    const label = el.querySelector(".voice-turn-state");
+    if (label) label.textContent = state === "listening" ? "Listening…" : "Sending voice…";
+  }
+
   /** @param {HTMLElement} el @param {string} text */
   _updateBubbleText(el, text) {
-    const t = el.querySelector(".bubble-body");
-    if (t) t.textContent = text;
+    el.classList.remove("voice", "listening", "sending");
+    el.removeAttribute("role");
+    el.removeAttribute("aria-live");
+    const t = /** @type {HTMLElement | null} */ (el.querySelector(".bubble-body"));
+    if (t) {
+      t.textContent = text;
+      t.hidden = !text;
+    }
   }
 
   /** @param {HTMLElement} el */
@@ -195,6 +245,25 @@ export class ChatView {
     }
   }
 
+  /**
+   * Point the shared reaper at the current oldest bubble. This must run when an
+   * expiry moves earlier as well as later: a listening bubble starts with a
+   * long fail-safe, then gets a much shorter deadline once speech stops.
+   */
+  _scheduleBubbleReaper() {
+    if (this._reaperHandle) clearTimeout(this._reaperHandle);
+    this._reaperHandle = 0;
+    const oldest = /** @type {HTMLElement | null} */ (
+      this._bubbleStack.querySelector(".bubble:not(.out)")
+    );
+    if (!oldest) return;
+    const expiry = this._bubbleExpiry.get(oldest) ?? Date.now();
+    this._reaperHandle = setTimeout(
+      () => this._reapBubbles(),
+      Math.max(50, expiry - Date.now()),
+    );
+  }
+
   /**
    * (Re)arm a bubble's auto-dismiss by pushing its expiry out by `delay`.
    * Calling it again resets the countdown — so a bubble that keeps updating
@@ -204,7 +273,20 @@ export class ChatView {
    */
   _bumpDismiss(el, delay = 4000) {
     this._bubbleExpiry.set(el, Date.now() + delay);
-    if (!this._reaperHandle) this._reaperHandle = setTimeout(() => this._reapBubbles(), delay);
+    this._scheduleBubbleReaper();
+  }
+
+  /**
+   * Remove a pending voice placeholder once the assistant has visibly started
+   * answering. A transcript can arrive before audible output, while direct
+   * audio models may only trigger the ai-speaking status, so both call here.
+   */
+  onAssistantActivity() {
+    const bubble = this._activeUserBubble;
+    if (!bubble?.isConnected || !bubble.classList.contains("voice")) return;
+    this._dismissBubble(bubble);
+    this._activeUserBubble = null;
+    this._scheduleBubbleReaper();
   }
 
   // ── History ───────────────────────────────────────────────────────────────
@@ -216,6 +298,11 @@ export class ChatView {
 
   /** Reset the panel to the empty state and clear the unread badge. */
   clear() {
+    this._stopUserAudioPlayback();
+    for (const url of this._audioUrls) URL.revokeObjectURL(url);
+    this._audioUrls.clear();
+    this._userAudioByItem.clear();
+    this._userHistByItem.clear();
     this.renderEmptyState();
     this._chatBadge.classList.remove("visible");
   }
@@ -236,10 +323,28 @@ export class ChatView {
     const body = /** @type {HTMLElement | null} */ (el.querySelector(".hist-body"));
     if (!body) return;
     body.textContent = text;
+    body.hidden = !text;
     body.classList.toggle("partial", partial);
     this._scrollToBottom();
   }
 
+  /** @param {string} itemId */
+  _ensureUserHist(itemId) {
+    let hist = this._userHistByItem.get(itemId);
+    if (!hist) {
+      hist = this._appendHistMsg("user", "", false);
+      this._userHistByItem.set(itemId, hist);
+    }
+    return hist;
+  }
+
+  _stopUserAudioPlayback() {
+    const active = this._activeUserAudio;
+    this._activeUserAudio = null;
+    if (active && !active.paused) active.pause();
+    this._onUserAudioPlaybackChange(false);
+  }
+
   /**
    * Append a tool-call row to the conversation. We only add it once the tool
    * has run, so the expandable toggle carries BOTH the call input and its result.
@@ -320,6 +425,46 @@ export class ChatView {
 
   // ── Client event handlers ─────────────────────────────────────────────────
 
+  /**
+   * Show a voice bubble as soon as backend VAD recognizes speech.
+   * @param {{ itemId?: string }} [detail]
+   */
+  onUserTurnStarted(detail = {}) {
+    const id = detail.itemId || `_u${++this._anonSeq}`;
+    const reusable = this._activeUserItemId === id
+      && this._activeUserBubble?.isConnected
+      && !this._activeUserBubble.classList.contains("out");
+    if (!reusable) {
+      if (this._activeUserBubble?.classList.contains("voice")) {
+        this._dismissBubble(this._activeUserBubble);
+      }
+      this._activeUserBubble = this._spawnVoiceBubble("listening");
+      this._activeUserItemId = id;
+    } else if (this._activeUserBubble.classList.contains("voice")) {
+      this._setVoiceBubbleState(this._activeUserBubble, "listening");
+    }
+    this._bumpDismiss(this._activeUserBubble, 30000);
+  }
+
+  /**
+   * Transition the active voice bubble while the closed turn is in flight.
+   * If speech_started was missed, create the sending state directly.
+   * @param {{ itemId?: string }} [detail]
+   */
+  onUserTurnStopped(detail = {}) {
+    const id = detail.itemId || this._activeUserItemId || `_u${++this._anonSeq}`;
+    const reusable = this._activeUserItemId === id
+      && this._activeUserBubble?.isConnected
+      && !this._activeUserBubble.classList.contains("out");
+    if (!reusable) {
+      this._activeUserBubble = this._spawnVoiceBubble("sending");
+      this._activeUserItemId = id;
+    } else if (this._activeUserBubble.classList.contains("voice")) {
+      this._setVoiceBubbleState(this._activeUserBubble, "sending");
+    }
+    this._bumpDismiss(this._activeUserBubble, 6000);
+  }
+
   /**
    * A streamed transcript delta (user or assistant).
    * @param {{ role: "user" | "assistant"; text: string; partial: boolean; itemId?: string; responseId?: string }} d
@@ -335,19 +480,18 @@ export class ChatView {
       const id = d.itemId || this._activeUserItemId || `_u${++this._anonSeq}`;
       const text = d.text;
 
-      let hist = this._userHistByItem.get(id);
-      if (!hist) {
-        hist = this._appendHistMsg("user", text, d.partial);
-        this._userHistByItem.set(id, hist);
-      } else {
-        this._updateHistMsg(hist, text, d.partial);
-      }
+      const hist = this._ensureUserHist(id);
+      this._updateHistMsg(hist, text, d.partial);
 
       // One ephemeral bubble per active item. Purely timer-based: the timer is
       // refreshed on every delta, so it stays while the user keeps talking and
       // fades a few seconds after they stop — no dependency on a response ever
       // arriving, so it can never get stuck.
-      if (this._activeUserItemId !== id || !this._activeUserBubble) {
+      if (
+        this._activeUserItemId !== id
+        || !this._activeUserBubble?.isConnected
+        || this._activeUserBubble.classList.contains("out")
+      ) {
         this._activeUserBubble = this._spawnBubble("user", text);
         this._activeUserItemId = id;
       } else {
@@ -356,6 +500,7 @@ export class ChatView {
       this._bumpDismiss(this._activeUserBubble, 6000);
       this._markUnread();
     } else if (d.role === "assistant") {
+      this.onAssistantActivity();
       // Assistant transcript arrives once, as the full text, keyed by
       // response_id so a cancelled speculative response can be removed later. A
       // missing id gets a unique key so two id-less replies never collide.
@@ -374,6 +519,71 @@ export class ChatView {
     }
   }
 
+  /**
+   * Attach the browser-local recording to its user turn. This also creates an
+   * audio-only row when STT is disabled and no transcript events arrive.
+   * Reopened VAD segments reuse item_id; the client sends a replacement WAV
+   * containing the accumulated utterance, so the row keeps one player.
+   * @param {{ itemId?: string, audio: Blob, durationMs?: number, truncated?: boolean }} detail
+   */
+  onUserAudio(detail) {
+    const id = detail.itemId || `_u${++this._anonSeq}`;
+    const hist = this._ensureUserHist(id);
+    let container = /** @type {HTMLElement | null} */ (hist.querySelector(".hist-audio"));
+    const isNewPlayer = !container;
+    if (!container) {
+      container = document.createElement("div");
+      container.className = "hist-audio";
+      container.innerHTML = `
+        <div class="hist-audio-label">Audio sent to the model</div>
+        <audio controls preload="metadata" aria-label="Replay your audio"></audio>
+      `;
+      hist.appendChild(container);
+    }
+
+    const audio = /** @type {HTMLAudioElement} */ (container.querySelector("audio"));
+    const previous = this._userAudioByItem.get(id);
+    if (previous) {
+      if (this._activeUserAudio === previous.audio) this._stopUserAudioPlayback();
+      URL.revokeObjectURL(previous.url);
+      this._audioUrls.delete(previous.url);
+    }
+
+    const url = URL.createObjectURL(detail.audio);
+    this._audioUrls.add(url);
+    this._userAudioByItem.set(id, { audio, url });
+    audio.src = url;
+    audio.title = detail.truncated
+      ? "Replay your audio (the beginning was no longer buffered)"
+      : "Replay the audio sent to the model";
+    const label = container.querySelector(".hist-audio-label");
+    if (label) {
+      label.textContent = detail.truncated
+        ? "Audio sent to the model · beginning unavailable"
+        : "Audio sent to the model";
+    }
+
+    if (isNewPlayer) {
+      audio.addEventListener("play", () => {
+        if (this._activeUserAudio && this._activeUserAudio !== audio) {
+          this._activeUserAudio.pause();
+        }
+        this._activeUserAudio = audio;
+        this._onUserAudioPlaybackChange(true);
+      });
+      const stopped = () => {
+        if (this._activeUserAudio !== audio) return;
+        this._activeUserAudio = null;
+        this._onUserAudioPlaybackChange(false);
+      };
+      audio.addEventListener("pause", stopped);
+      audio.addEventListener("ended", stopped);
+      audio.addEventListener("error", stopped);
+    }
+    this._scrollToBottom();
+    this._markUnread();
+  }
+
   /**
    * A response closed (completed or cancelled).
    * @param {{ responseId: string; status: string; audible?: boolean; transcript?: string }} detail
@@ -381,6 +591,7 @@ export class ChatView {
   onResponseFinished(detail) {
     const { responseId, status, audible, transcript } = detail;
     if (DEBUG) console.debug(`[ui] response-finished resp=${responseId} status=${status} audible=${audible} known=${this._asstByResp.has(responseId)}`);
+    this.onAssistantActivity();
     // Without an id we can't target a specific response; the bubble will
     // auto-dismiss on its own timer regardless.
     if (!responseId) return;

ws/s2s-ws-client.js

@@ -51,6 +51,8 @@
  *   session POST and dials it directly — no load balancer in between.
  * @property {string} voice
  * @property {string} instructions
+ * @property {string} [startupGreeting] Hidden user prompt that asks the model
+ *   to greet once after the initial session configuration is sent.
  * @property {MediaStream} [micStream] Live mic stream. Provide this OR `acquireMic`.
  * @property {() => Promise<MediaStream>} [acquireMic] Lazily obtain the mic stream,
  *   called only once a session is actually granted (after any queue wait). Lets the
@@ -65,6 +67,8 @@
  *   executes and replies via `sendToolOutput` + `requestResponse`.
  * @property {NoiseGate} [noiseGate] Client-side noise gate applied to the mic
  *   before it's sent. Tunable live via `setNoiseGate`.
+ * @property {string} [audioOutputId] MediaDeviceInfo.deviceId for speakers.
+ *   Applied via AudioContext.setSinkId when the browser supports it.
  *
  * @typedef {Object} NoiseGate
  * @property {boolean} enabled
@@ -89,6 +93,7 @@ import {
   trimTrailingSlash,
 } from "./codec.js";
 import { OrbVisualiser, VIS_FFT_SIZE } from "./orb-visualizer.js";
+import { SentAudioRecorder } from "./user-audio-recorder.js";
 
 /** Build an Error carrying a `code` (and optional extra fields) so callers can
  *  branch on the failure kind: "limit" | "queue-full" | "queue-expired" | "aborted".
@@ -198,6 +203,11 @@ export class S2sWsRealtimeClient extends EventTarget {
     /** @type {Promise<void> | null} */
     this._readyPromise = null;
     this._sessionConfigured = false;
+    this._startupGreeting = options.startupGreeting?.trim() ?? "";
+    this._startupGreetingSent = false;
+    // Bounded, browser-local copy of the exact PCM frames sent over this
+    // socket. Backend VAD timestamps turn it into replayable user utterances.
+    this._userAudioRecorder = new SentAudioRecorder();
     this._debug = (() => { try { return localStorage.getItem("s2s.debug") === "1"; } catch { return false; } })();
   }
 
@@ -346,6 +356,12 @@ export class S2sWsRealtimeClient extends EventTarget {
       headers: { "Content-Type": "application/json" },
       body: "{}",
     });
+    if (response.status === 401) {
+      const body = await response.json().catch(() => ({}));
+      throw _codedError("Hugging Face sign-in required", "login-required", {
+        loginUrl: body?.loginUrl,
+      });
+    }
     if (response.status === 402) {
       // The session proxy refused: today's per-tier time budget is spent. Surface
       // it as a typed error so the UI shows the limit modal, not a crash.
@@ -404,6 +420,12 @@ export class S2sWsRealtimeClient extends EventTarget {
         const body = await response.json().catch(() => ({}));
         throw _codedError("Daily conversation limit reached", "limit", { tier: body?.tier });
       }
+      if (response.status === 401) {
+        const body = await response.json().catch(() => ({}));
+        throw _codedError("Hugging Face sign-in required", "login-required", {
+          loginUrl: body?.loginUrl,
+        });
+      }
       if (response.status === 404) {
         throw _codedError("Queue timed out", "queue-expired");
       }
@@ -526,10 +548,30 @@ export class S2sWsRealtimeClient extends EventTarget {
     this._outAnalyser = outAnalyser;
     this._playbackNode = playbackNode;
 
+    await this.setAudioOutputDevice(this.options.audioOutputId || "");
+
     this._visualiser = new OrbVisualiser(micAnalyser, outAnalyser, () => this._aiSpeaking);
     this._visualiser.start();
   }
 
+  /**
+   * Route Web Audio playback to a specific output device (Chrome/Edge).
+   * Empty string restores the system default.
+   * @param {string} [deviceId]
+   * @returns {Promise<boolean>}
+   */
+  async setAudioOutputDevice(deviceId = "") {
+    const ctx = this._ctx;
+    if (!ctx || typeof /** @type {any} */ (ctx).setSinkId !== "function") return false;
+    try {
+      await /** @type {any} */ (ctx).setSinkId(deviceId || "");
+      return true;
+    } catch (err) {
+      console.warn("[ws] setSinkId failed:", err);
+      return false;
+    }
+  }
+
   /** @param {string} connectUrl */
   _openWebSocket(connectUrl) {
     return new Promise((resolve, reject) => {
@@ -581,6 +623,9 @@ export class S2sWsRealtimeClient extends EventTarget {
     if (this._muted) return;
     const b64 = base64FromArrayBuffer(pcm16Buffer);
     this._send({ type: "input_audio_buffer.append", audio: b64 });
+    // Record only after the append is accepted for sending. This intentionally
+    // excludes pre-configuration and muted audio, just like the backend input.
+    this._userAudioRecorder.append(pcm16Buffer);
   }
 
   /**
@@ -625,11 +670,16 @@ export class S2sWsRealtimeClient extends EventTarget {
         // out). We only push the user-tunable bits: voice + instructions.
         this._sendSessionUpdate();
         this._sessionConfigured = true;
+        // The s2s server does not echo session.updated. WebSocket messages are
+        // ordered, so this hidden item and response.create are handled only
+        // after the session.update sent immediately above.
+        this._sendStartupGreeting();
         if (this._status === "connecting") this._setStatus("connected");
         break;
 
       case "session.updated":
-        // Acknowledged by server, nothing to do.
+        // Some Realtime servers acknowledge session.update; the greeting was
+        // already queued from session.created and is guarded against repeats.
         break;
 
       case "input_audio_buffer.speech_started":
@@ -640,10 +690,32 @@ export class S2sWsRealtimeClient extends EventTarget {
         // otherwise keep playing over the user's barge-in.
         this._playbackNode?.port.postMessage({ kind: "clear" });
         this._aiSpeaking = false;
+        this._userAudioRecorder.speechStarted({
+          itemId: typeof event.item_id === "string" ? event.item_id : "",
+          audioStartMs: Number(event.audio_start_ms),
+        });
+        this.dispatchEvent(new CustomEvent("user-turn-started", {
+          detail: {
+            itemId: typeof event.item_id === "string" ? event.item_id : "",
+          },
+        }));
         this._setStatus("user-speaking");
         break;
 
       case "input_audio_buffer.speech_stopped":
+        {
+          const itemId = typeof event.item_id === "string" ? event.item_id : "";
+          const recording = this._userAudioRecorder.speechStopped({
+            itemId,
+            audioEndMs: Number(event.audio_end_ms),
+          });
+          if (recording) {
+            this.dispatchEvent(new CustomEvent("user-audio", { detail: recording }));
+          }
+          this.dispatchEvent(new CustomEvent("user-turn-stopped", {
+            detail: { itemId },
+          }));
+        }
         if (this._status === "user-speaking") this._setStatus("processing");
         break;
 
@@ -965,6 +1037,26 @@ export class S2sWsRealtimeClient extends EventTarget {
     });
   }
 
+  /**
+   * Ask the model to open the conversation exactly once. The synthetic user
+   * prompt stays in conversation history, so the greeting warms the actual
+   * prompt prefix reused by the first spoken turn.
+   */
+  _sendStartupGreeting() {
+    if (!this._startupGreeting || this._startupGreetingSent) return;
+    this._startupGreetingSent = true;
+    this._send({
+      type: "conversation.item.create",
+      item: {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: this._startupGreeting }],
+      },
+    });
+    this.requestResponse();
+    if (this._debug) console.debug("[ws] startup greeting queued");
+  }
+
   /**
    * Ask the model to generate a response now (after feeding tool results).
    * Serialized: if a response is already in flight we queue this request and
@@ -1035,6 +1127,7 @@ export class S2sWsRealtimeClient extends EventTarget {
     // Abort a queue wait in progress: flag it and wake the poll sleep so
     // `_pollQueue` throws "aborted" and connect() unwinds cleanly.
     this._closed = true;
+    this._userAudioRecorder.reset();
     if (this._queueWake) {
       clearTimeout(this._queueTimer);
       const wake = this._queueWake;

ws/user-audio-recorder.js

@@ -0,0 +1,201 @@
+// @ts-check
+/**
+ * Keep a bounded copy of the PCM16 frames sent over the realtime WebSocket and
+ * turn the backend's VAD boundaries into browser-playable WAV blobs.
+ *
+ * This records the post-resampling, post-noise-gate signal—not a second raw-mic
+ * capture—so replay is as close as the browser can get to the audio delivered
+ * to the backend. Nothing leaves the page beyond the existing realtime stream.
+ */
+
+export const USER_AUDIO_SAMPLE_RATE = 16000;
+const BYTES_PER_SAMPLE = 2;
+const DEFAULT_PREROLL_MS = 5000;
+const DEFAULT_MAX_BUFFER_MS = 120000;
+
+/** @param {DataView} view @param {number} offset @param {string} value */
+function _writeAscii(view, offset, value) {
+  for (let i = 0; i < value.length; i++) {
+    view.setUint8(offset + i, value.charCodeAt(i));
+  }
+}
+
+/**
+ * Wrap little-endian mono PCM16 in a standard WAV container.
+ * @param {Uint8Array} pcm
+ * @param {number} [sampleRate]
+ * @returns {Blob}
+ */
+export function pcm16ToWavBlob(pcm, sampleRate = USER_AUDIO_SAMPLE_RATE) {
+  const dataLength = pcm.byteLength - (pcm.byteLength % BYTES_PER_SAMPLE);
+  const wav = new ArrayBuffer(44 + dataLength);
+  const view = new DataView(wav);
+  _writeAscii(view, 0, "RIFF");
+  view.setUint32(4, 36 + dataLength, true);
+  _writeAscii(view, 8, "WAVE");
+  _writeAscii(view, 12, "fmt ");
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * BYTES_PER_SAMPLE, true);
+  view.setUint16(32, BYTES_PER_SAMPLE, true);
+  view.setUint16(34, 16, true);
+  _writeAscii(view, 36, "data");
+  view.setUint32(40, dataLength, true);
+  new Uint8Array(wav, 44).set(pcm.subarray(0, dataLength));
+  return new Blob([wav], { type: "audio/wav" });
+}
+
+/** @param {Uint8Array} first @param {Uint8Array} second */
+function _concat(first, second) {
+  const result = new Uint8Array(first.byteLength + second.byteLength);
+  result.set(first, 0);
+  result.set(second, first.byteLength);
+  return result;
+}
+
+export class SentAudioRecorder {
+  /**
+   * @param {{ sampleRate?: number, preRollMs?: number, maxBufferMs?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.sampleRate = options.sampleRate ?? USER_AUDIO_SAMPLE_RATE;
+    this._preRollSamples = Math.round(
+      (this.sampleRate * (options.preRollMs ?? DEFAULT_PREROLL_MS)) / 1000,
+    );
+    this._maxBufferSamples = Math.round(
+      (this.sampleRate * (options.maxBufferMs ?? DEFAULT_MAX_BUFFER_MS)) / 1000,
+    );
+    /** @type {{ startSample: number, endSample: number, bytes: Uint8Array }[]} */
+    this._chunks = [];
+    this._sentSamples = 0;
+    /** @type {{ itemId: string, requestedStartSample: number } | null} */
+    this._active = null;
+    this._lastItemId = "";
+    this._lastItemPcm = new Uint8Array(0);
+  }
+
+  /** Store one PCM16 frame that was actually sent to the backend.
+   * @param {ArrayBuffer} buffer */
+  append(buffer) {
+    const evenLength = buffer.byteLength - (buffer.byteLength % BYTES_PER_SAMPLE);
+    if (evenLength <= 0) return;
+    const bytes = new Uint8Array(buffer.slice(0, evenLength));
+    const startSample = this._sentSamples;
+    const endSample = startSample + evenLength / BYTES_PER_SAMPLE;
+    this._chunks.push({ startSample, endSample, bytes });
+    this._sentSamples = endSample;
+    this._prune();
+  }
+
+  /**
+   * Remember where the backend says this speech item began. The event normally
+   * arrives after confirmation, so the bounded pre-roll retains its onset.
+   * @param {{ itemId?: string, audioStartMs?: number }} boundary
+   */
+  speechStarted(boundary) {
+    const itemId = boundary.itemId || `audio_${this._sentSamples}`;
+    const requestedStartSample = this._sampleAtMs(boundary.audioStartMs, this._sentSamples);
+    this._active = { itemId, requestedStartSample };
+    if (itemId !== this._lastItemId) {
+      this._lastItemId = itemId;
+      this._lastItemPcm = new Uint8Array(0);
+    }
+    this._prune();
+  }
+
+  /**
+   * Finalize the active VAD segment. Reopened segments carrying the same
+   * item_id replace the prior recording with their concatenation, matching the
+   * chat view's one-row-per-item behavior.
+   * @param {{ itemId?: string, audioEndMs?: number }} boundary
+   * @returns {{ itemId: string, audio: Blob, durationMs: number, truncated: boolean } | null}
+   */
+  speechStopped(boundary) {
+    const active = this._active;
+    if (!active) return null;
+    this._active = null;
+
+    const itemId = boundary.itemId || active.itemId;
+    const availableStart = this._chunks[0]?.startSample ?? this._sentSamples;
+    const startSample = Math.max(active.requestedStartSample, availableStart);
+    let endSample = this._sampleAtMs(boundary.audioEndMs, this._sentSamples);
+    if (endSample <= startSample) endSample = this._sentSamples;
+    endSample = Math.min(endSample, this._sentSamples);
+
+    const segment = this._slice(startSample, endSample);
+    if (segment.byteLength === 0) {
+      this._prune();
+      return null;
+    }
+
+    if (itemId !== this._lastItemId) {
+      this._lastItemId = itemId;
+      this._lastItemPcm = new Uint8Array(0);
+    }
+    this._lastItemPcm = _concat(this._lastItemPcm, segment);
+    const durationMs =
+      (this._lastItemPcm.byteLength / BYTES_PER_SAMPLE / this.sampleRate) * 1000;
+    const result = {
+      itemId,
+      audio: pcm16ToWavBlob(this._lastItemPcm, this.sampleRate),
+      durationMs,
+      truncated: active.requestedStartSample < availableStart,
+    };
+    this._prune();
+    return result;
+  }
+
+  reset() {
+    this._chunks = [];
+    this._sentSamples = 0;
+    this._active = null;
+    this._lastItemId = "";
+    this._lastItemPcm = new Uint8Array(0);
+  }
+
+  /** @param {number | undefined} ms @param {number} fallback */
+  _sampleAtMs(ms, fallback) {
+    if (!Number.isFinite(ms) || Number(ms) < 0) return fallback;
+    return Math.max(
+      0,
+      Math.min(Math.round((Number(ms) * this.sampleRate) / 1000), this._sentSamples),
+    );
+  }
+
+  /** @param {number} startSample @param {number} endSample */
+  _slice(startSample, endSample) {
+    /** @type {Uint8Array[]} */
+    const parts = [];
+    let length = 0;
+    for (const chunk of this._chunks) {
+      const overlapStart = Math.max(startSample, chunk.startSample);
+      const overlapEnd = Math.min(endSample, chunk.endSample);
+      if (overlapEnd <= overlapStart) continue;
+      const from = (overlapStart - chunk.startSample) * BYTES_PER_SAMPLE;
+      const to = (overlapEnd - chunk.startSample) * BYTES_PER_SAMPLE;
+      const part = chunk.bytes.slice(from, to);
+      parts.push(part);
+      length += part.byteLength;
+    }
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+      result.set(part, offset);
+      offset += part.byteLength;
+    }
+    return result;
+  }
+
+  _prune() {
+    const hardFloor = Math.max(0, this._sentSamples - this._maxBufferSamples);
+    const softFloor = this._active
+      ? this._active.requestedStartSample
+      : Math.max(0, this._sentSamples - this._preRollSamples);
+    const floor = Math.max(hardFloor, softFloor);
+    while (this._chunks.length && this._chunks[0].endSample <= floor) {
+      this._chunks.shift();
+    }
+  }
+}