Skip to main content

Text Connection

The simplest on-ramp to Estuary on Spectacles — a text-only conversation with no microphone, audio output, or voice session required.

When to Use​

Reach for the text-only path when you want to:

  • Prototype a Lens against the Estuary backend before wiring audio components
  • Build experiences where the AI responds via text or scripted lines (no TTS)
  • Drive characters from in-Lens UI inputs (taps, gestures, chat-style overlays)
  • Avoid the microphone permission and the RemoteServiceGateway.lspkg audio components

For the full voice experience (microphone capture + TTS playback), see Voice Connection.

Example File​

The SDK ships with a complete example you can drop into a scene:

Examples/EstuaryTextConnection.ts

This script auto-connects on onAwake(), pulls credentials from an EstuaryCredentials SceneObject (or singleton), wires the EstuaryActionManager, and exposes simple methods (sendMessage, sayLine, sayLineWithVoice) for runtime use.

Scene Setup​

Create these SceneObjects:

Object NameComponents
Estuary CredentialsEstuaryCredentials script
Estuary ConnectionEstuaryTextConnection script
Internet ModuleInternetModule resource

In the EstuaryTextConnection Inspector, connect:

credentialsObject  → Estuary Credentials
internetModule     → Internet Module

Optional inputs:

InputDescription
autoSendOnConnectIf true, sends initialMessage as a user message on connect (routed through the LLM + TTS pipeline)
initialMessageText to send when autoSendOnConnect is enabled

That's it — no MicrophoneRecorder, no DynamicAudioOutput, no voice preset on the character required.

Minimal Code Skeleton​

If you'd rather write your own, here's the essential flow taken directly from the example:

import { EstuaryCharacter } from 'estuary-lens-studio-sdk';
import { EstuaryManager } from 'estuary-lens-studio-sdk';
import { EstuaryConfig } from 'estuary-lens-studio-sdk';
import { BotResponse } from 'estuary-lens-studio-sdk';

@component
export class MyTextConnection extends BaseScriptComponent {

    @input
    internetModule: InternetModule;

    private character: EstuaryCharacter | null = null;

    onAwake() {
        // REQUIRED for Lens Studio 5.9+ — assign before connecting.
        EstuaryManager.instance.internetModule = this.internetModule;

        this.character = new EstuaryCharacter("your-character-id", "unique-player-id");

        // Listen for AI text responses (no voiceReceived in text-only flow)
        this.character.on('botResponse', (response: BotResponse) => {
            if (response.isFinal) {
                print(`[AI] ${response.text}`);
            }
        });

        const config: EstuaryConfig = {
            serverUrl: "wss://api.estuary-ai.com",
            apiKey: "your-api-key",
            characterId: "your-character-id",
            playerId: "unique-player-id",
            debugLogging: true
        };

        this.character.initialize(config);

        // Drive the WebSocket send queue (required on Spectacles).
        this.createEvent("UpdateEvent").bind(() => {
            EstuaryManager.instance.tick();
        });
    }

    /** Send a free-form user message. */
    sendMessage(text: string): void {
        if (this.character?.isConnected) {
            this.character.sendText(text);
        }
    }

    /** Script a prewritten line (no TTS). */
    sayLine(text: string): void {
        if (this.character?.isConnected) {
            this.character.sayLine(text, true);
        }
    }
}

Adding Voice Later​

The text-only path uses the same EstuaryCharacter and EstuaryManager as the voice flow. To upgrade:

  1. Import RemoteServiceGateway.lspkg and add MicrophoneRecorder + DynamicAudioOutput SceneObjects
  2. Switch from EstuaryTextConnection to EstuaryVoiceConnection (or extend your custom script with the audio wiring)
  3. Subscribe to voiceReceived and start a voice session — see Voice Connection

Next Steps​

Last updated