Skip to main content

Installation and Setup

Learn how to install, set up, and run the Estuary Lens Studio SDK to integrate conversational AI characters directly within your Snap Spectacles projects.

Introduction​

The Estuary Lens Studio SDK allows you to seamlessly integrate Estuary's advanced conversational AI characters into your Lens Studio projects. This guide walks you through the complete setup process to get your first AI-powered Lens running on Spectacles.

Prerequisites​

Before you begin, ensure you have:

RequirementVersion/Details
Lens Studio5.9 or newer (5.12+ recommended for Preview networking)
Estuary AccountSign up at app.estuary-ai.com
API KeyGenerated from your Estuary dashboard
Character IDThe UUID of your AI character
Snap SpectaclesRequired for testing

Installation Guide​

Follow these steps to install and configure the Estuary SDK.

Get the SDK Source​

The Estuary Lens Studio SDK is distributed as TypeScript source. Clone or download the repository from GitHub:

github.com/estuary-ai/estuary-lens-studio-sdk

The repository contains:

  • src/ — Core SDK source (Components, Core, Models, Utilities)
  • Examples/ — Reference scripts (EstuaryVoiceConnection, EstuaryTextConnection, EstuaryCamera, ExampleCharacterActions)
  • LICENSE and README.md

Create a New Lens Studio Project​

  1. Open Lens Studio
  2. Click New Project
  3. Choose a template (recommended: Blank Project for Spectacles)
  4. Name your project and click Create

:::tip Spectacles Template For the best experience, use a Spectacles-compatible template or ensure your project is configured for Spectacles deployment. :::

Import the SDK into Your Project​

Copy the SDK files into your Lens Studio project's Assets/ folder:

  1. Locate your Lens Studio project's Assets/ directory on disk
  2. Copy the cloned src/ folder (and optionally Examples/) into a new subfolder, for example Assets/estuary-lens-studio-sdk/
  3. Back in Lens Studio, the imported scripts will appear in the Assets Panel

Your project structure should look like:

Assets/
├── estuary-lens-studio-sdk/
│   ├── src/
│   │   ├── Components/
│   │   │   ├── EstuaryActionManager.ts
│   │   │   ├── EstuaryCharacter.ts
│   │   │   ├── EstuaryCredentials.ts
│   │   │   ├── EstuaryManager.ts
│   │   │   └── EstuaryMicrophone.ts
│   │   ├── Core/
│   │   │   ├── EstuaryClient.ts
│   │   │   ├── EstuaryConfig.ts
│   │   │   ├── EstuaryEvents.ts
│   │   │   └── EstuaryHttpClient.ts
│   │   ├── Models/
│   │   └── Utilities/
│   └── Examples/
│       ├── EstuaryVoiceConnection.ts
│       ├── EstuaryTextConnection.ts
│       ├── EstuaryCamera.ts
│       └── ExampleCharacterActions.ts
└── ... (your other assets)

:::tip Examples are optional You only need src/ to build with the SDK. The Examples/ folder contains drop-in scripts (EstuaryVoiceConnection, EstuaryTextConnection, EstuaryCamera) that match the setup described in this guide — copy any you intend to use directly into your project. :::

Import Required Dependencies​

The Estuary SDK requires additional Lens Studio packages:

RemoteServiceGateway.lspkg

This package provides essential components:

  • MicrophoneRecorder - For capturing microphone audio
  • DynamicAudioOutput - For playing TTS audio responses

To import:

  1. Go to Asset Library in Lens Studio
  2. Search for "RemoteServiceGateway"
  3. Click Import to add it to your project

Project Setup​

Setting Up Your Credentials​

  1. Create a new SceneObject (e.g., name it "Estuary Credentials")
  2. Add the EstuaryCredentials script component
  3. Configure the following fields in the Inspector:
FieldDescription
API KeyYour Estuary API key from the dashboard
Character IDThe UUID of your AI character
Debug ModeEnable for detailed logging (recommended during development)
// The EstuaryCredentials component handles:
// - API key storage
// - Character ID configuration  
// - Automatic User ID generation and persistence
// - Debug mode toggling

Setting Up the Connection​

  1. Create a new SceneObject (e.g., "Estuary Connection")
  2. Add the EstuaryVoiceConnection script component (from Examples/EstuaryVoiceConnection.ts)
  3. Configure the inputs in the Inspector:
InputDescription
Credentials ObjectDrag your EstuaryCredentials SceneObject here
Internet ModuleConnect the InternetModule from your scene
Microphone Recorder ObjectSceneObject with MicrophoneRecorder script
Dynamic Audio Output ObjectSceneObject with DynamicAudioOutput script

Setting Up Audio Components​

Microphone Input

  1. Create a SceneObject (e.g., "Microphone")
  2. Add the MicrophoneRecorder script from RemoteServiceGateway
  3. Add a Microphone Audio asset if required

Audio Output

  1. Create a SceneObject (e.g., "Audio Output")
  2. Add the DynamicAudioOutput script
  3. Add an Audio Component to the same object
  4. Create an Audio Track asset and assign it to DynamicAudioOutput

Adding the InternetModule​

  1. In the Scene Hierarchy, right-click and add a resource
  2. Search for Internet Module and add it
  3. Connect it to your EstuaryVoiceConnection component

Setting Up Camera (Optional)​

To enable AI vision capabilities (camera capture for image analysis):

  1. Create a new SceneObject (e.g., "Estuary Camera")
  2. Add the EstuaryCamera script component (from Examples/EstuaryCamera.ts)
  3. Configure the inputs in the Inspector:
InputDescription
Debug ModeEnable debug logging (default: true)
Capture ResolutionImage resolution (smaller dimension in pixels, default: 512)

The camera listens for cameraCaptureRequest events from the server. When the AI agent determines it needs visual context, it sends a capture request to the client automatically.

Complete Scene Setup​

Here's what your final scene hierarchy should look like:

Scene
├── Estuary Credentials         [EstuaryCredentials script]
├── Estuary Connection          [EstuaryVoiceConnection script]
├── Estuary Camera              [EstuaryCamera script] (optional)
├── Microphone                  [MicrophoneRecorder script]
├── Audio Output                [DynamicAudioOutput script + AudioComponent]
├── Internet Module             [InternetModule resource]
└── ... (your other scene objects)

Testing Your Setup​

In Lens Studio Desktop Preview​

:::warning Simulator Limitation Lens Studio does not support Acoustic Echo Cancellation (AEC), so characters may hear and respond to themselves. We highly recommend testing conversations with headphones for the best experience.

:::

:::warning Simulator Limitation The Camera Module only functions when deployed to Spectacles hardware due to Lens Studio API limitations.

:::

  1. Enable Spectacles in your project
    In Lens Studio, open Project → Project Info and ensure Made For Spectacles is checked. This enables Spectacles connectivity in the preview flow.

On Spectacles Hardware​

  1. Connect Spectacles to Lens Studio (choose one):

    • Wired (recommended): Plug Spectacles into your computer with a USB-C cable. In the Spectacles mobile app, go to Developer Settings → Lens Development and turn on Enable Wired Connectivity (one-time). Spectacles will connect automatically when plugged in.
    • Wireless: Sign into Lens Studio with the same Snap account paired to your Spectacles. Put Spectacles and your computer on the same Wi‑Fi network (no client/AP isolation). Keep Spectacles awake with the display on.

  2. Send the Lens to Spectacles
    In the Lens Studio toolbar, click Preview Lens. The first time, Lens Studio connects to Spectacles; after that, it sends your Lens. The Lens appears in the Draft folder on Spectacles (you can enable Send On Project Save in Preferences for faster iteration).

  3. Put on your Spectacles and start talking!

When successfully connected, you'll see logs like:

[EstuaryCredentials] Credentials configured successfully
[EstuaryVoiceConnection] MicrophoneRecorder configured successfully
[EstuaryVoiceConnection] DynamicAudioOutput configured (24000Hz)
===========================================
  Connected! Starting mic stream...
  Session: abc123-def456-...
===========================================

Troubleshooting​

Common Issues​

IssueSolution
"InternetModule is required"Ensure InternetModule is added to your scene and connected
"No EstuaryCredentials found"Create and connect the EstuaryCredentials SceneObject
"MicrophoneRecorder not found"Import RemoteServiceGateway.lspkg and add MicrophoneRecorder component
Connection closes immediatelyCheck your API key and Character ID are correct
No audio playbackEnsure DynamicAudioOutput has an AudioComponent and AudioTrack

Debug Mode​

Enable debug mode in EstuaryCredentials for verbose logging:

// In EstuaryCredentials Inspector:
debugMode: true

This will log:

  • Connection state changes
  • Audio streaming statistics
  • Bot responses and STT transcripts
  • Action triggers

Example Projects​

Two complete Snap Spectacles projects are available on GitHub:

See Example Projects for templates across all platforms.

Next Steps​

Now that your SDK is installed and configured:

  1. Voice Connection Guide - Learn the details of voice input/output
  2. Text Connection - A text-only on-ramp via EstuaryTextConnection (no microphone or audio output required)
  3. User Management - Understand User ID persistence
  4. Action System - Trigger scene actions from AI responses
  5. Camera Module - Enable AI vision capabilities
  6. API Reference - Detailed component documentation
Last updated