Contracts Bridge Kiosk
Transport: ws://127.0.0.1:8777
Auth: none — loopback only, bound explicitly to 127.0.0.1, never 0.0.0.0 (except dev LAN gates).
Roles: Bridge = server · Kiosk = client (reconnects with backoff).
Status: SPEC (audio path VERIFIED 2026-08-02)
Envelope: Contracts Overview.
| type | data | meaning |
|---|---|---|
state |
{state, userid?, displayName?} |
Attention state changed. Kiosk adjusts idle animation / gaze. |
speak |
{text, audioUrl, visemes?, mood?} |
Render this utterance. audioUrl is a loopback HTTP URL served by the bridge. |
speak.cancel |
{} |
Barge-in or timeout. Stop immediately, return to idle. |
listening |
{active, level?} |
Show/hide listening indicator; level 0–1 for mic meter. |
thinking |
{active} |
Orchestration in flight. |
pairing.qr |
{active, url?, userCode?, qrSvg?} |
OAuth device-code QR overlay. active:false clears. |
admin.qr |
{active, url?, qrSvg?, ip?, iface?, port?, type?, hotspot?, ssid?} |
Debug / SoftAP admin QR (http://<ip>:8781/admin/?token=…). Prefer ethernet, then Wi‑Fi client, then hotspot 10.87.65.1. When hotspot is true, show ssid under the QR. active:false clears. Never log the token. (ADR 0014) |
error |
{code, message} |
Non-fatal error affordance. |
config |
{avatarUrl, mood, cameraPose} |
Sent once on connect. |
| type | data | meaning |
|---|---|---|
ready |
{avatarLoaded, webglVendor, fps} |
Avatar / shell ready. Bridge should not enter Engaged before this when GLB is required. |
speak.started |
{} |
First audio frame played. Closes avatar_start span. |
speak.ended |
{} |
Playback complete. Opens the follow-up window — not when TTS finished generating. |
span |
{name, ms} |
Kiosk-side timing. |
error |
{code, message} |
Render / WebGL / GLB failure. |
The follow-up window opens on speak.ended from the kiosk, never on a bridge-side timer alone.
If the kiosk dies mid-utterance, the bridge must time out at tts_total + 5s and return to Ambient rather than hang.
TTS plays in Chromium via HTMLAudioElement (ADR 0001). The bridge serves WAV/bytes over loopback HTTP (audioUrl).