Skip to main content

Core Components

Low-level components for WebSocket communication and configuration.

EstuaryClient​

Low-level WebSocket client for communicating with Estuary servers. Implements Socket.IO v4 protocol.

import { EstuaryClient, setInternetModule } from 'estuary-lens-studio-sdk';

Setup​

// REQUIRED: Set InternetModule before creating client
setInternetModule(internetModule);

const client = new EstuaryClient();

Methods​

MethodParametersDescription
connect()serverUrl, apiKey, characterId, playerIdConnect to Estuary server
disconnect()-Disconnect from server
sendText()text: stringSend text message
sayLine()text: string, textOnly?: booleanScript the character to say a specific prewritten line. When textOnly is true the server emits botResponse only (no TTS). Default false.
sendClientInterrupt()messageId?: stringCancel the in-progress bot response. The server stops generation and emits an interrupt event back. If messageId is omitted, the server interrupts whatever is currently being generated.
streamAudio()audioBase64: stringStream audio for STT
startVoiceMode()-Enable server-side STT
stopVoiceMode()-Disable server-side STT
sendCameraImage()imageBase64, mimeType?, requestId?, text?, sampleRate?Send captured image to server
notifyAudioPlaybackComplete()-Signal audio finished playing
tick()-Process WebSocket send queue (call periodically)
dispose()-Clean up resources

Properties​

PropertyTypeDescription
stateConnectionStateCurrent connection state
isConnectedbooleanWhether connected
currentSessionSessionInfo | nullSession info when connected
debugLoggingbooleanEnable debug logs
autoReconnectbooleanAuto-reconnect on disconnect

Events​

EventDataDescription
sessionConnectedSessionInfoSuccessfully connected
disconnectedstringConnection closed
botResponseBotResponseAI text response
botVoiceBotVoiceAI voice audio
sttResponseSttResponseSpeech transcription
interruptInterruptDataConversation interrupted
memoryUpdatedobjectThe server extracted new long-term memory entries from this conversation. Forwards the raw payload (memories_extracted, new_memories, etc.) — the schema is owned by the server.
errorstringError occurred
connectionStateChangedConnectionStateState changed
cameraCaptureRequestCameraCaptureRequestServer requests camera capture
voiceStartedobjectVoice mode started on server
voiceErrorobjectVoice mode error
voiceStoppedobjectVoice mode stopped on server

:::note quota_exceeded The server can also emit a quota_exceeded event when an API quota has been hit. The Lens Studio SDK currently surfaces this as a debug log only — it is not re-emitted as a public event. If you need to react to quota errors in your Lens, watch for the standard error event or check the connection state. :::

EstuaryConfig​

Configuration interface for SDK connections.

interface EstuaryConfig {
    serverUrl: string;              // Server URL (wss://...)
    apiKey?: string;                // API key
    characterId: string;            // Character UUID
    playerId: string;               // User identifier
    
    recordingSampleRate?: number;   // Default: 16000
    playbackSampleRate?: number;    // Default: 24000
    audioChunkDurationMs?: number;  // Default: 100
    
    autoReconnect?: boolean;        // Default: true
    maxReconnectAttempts?: number;  // Default: 5
    reconnectDelayMs?: number;      // Default: 2000
    
    debugLogging?: boolean;         // Default: false
}

Helper Functions​

// Merge with defaults
const config = mergeWithDefaults(partialConfig);

// Validate configuration
const error = validateConfig(config); // null if valid

// Check if valid
if (isConfigValid(config)) { ... }

// Create dev config
const devConfig = createDevConfig(apiKey, characterId, playerId);

EstuaryHttpClient​

REST API client for character management and 3D model operations. See the dedicated HTTP Client Reference for full documentation.

import { EstuaryHttpClient } from 'estuary-lens-studio-sdk';

ConnectionState​

Enum representing connection states.

enum ConnectionState {
    Disconnected = 'disconnected',
    Connecting = 'connecting',
    Connected = 'connected',
    Reconnecting = 'reconnecting',
    Error = 'error'
}
Last updated