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:

Requirement	Version/Details
Lens Studio	5.15.2
Estuary Account	Sign up at estuary-ai.com
API Key	Generated from your Estuary dashboard
Character ID	The UUID of your AI character
Snap Spectacles	Required for testing

---

Installation Guide

Follow these steps to install and configure the Estuary SDK.

Download the SDK

Download the latest Estuary SDK package:

• Option A: Download from GitHub releases
• Option B: Use the .lspkg package file directly

The SDK package includes:

• Core SDK source files (src/)
• Example scripts (Examples/)
• License and documentation

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

Spectacles Template

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

Import the SDK Package

1. Navigate to Assets Panel → Right-click → Import
2. Select the Estuary SDK folder or .lspkg file
3. The SDK will be imported into your Assets

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
│   │   ├── Models/
│   │   └── Utilities/
│   └── Examples/
│       ├── VoiceConnection.ts
│       └── ExampleCharacterActions.ts
└── ... (your other assets)

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:

Field	Description
API Key	Your Estuary API key from the dashboard
Character ID	The UUID of your AI character
Debug Mode	Enable 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 SimpleAutoConnect script component
3. Configure the inputs in the Inspector:

Input	Description
Credentials Object	Drag your EstuaryCredentials SceneObject here
Internet Module	Connect the InternetModule from your scene
Microphone Recorder Object	SceneObject with MicrophoneRecorder script
Dynamic Audio Output Object	SceneObject 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 SimpleAutoConnect component

---

Complete Scene Setup

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

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

---

Testing Your Setup

In Lens Studio Preview

Simulator Limitation

WebSocket connections are not available in the Lens Studio Preview/Simulator. You will see an error message:

WebSocket NOT available in Lens Studio Preview!
This only works on actual Spectacles hardware.

This is expected behavior. Proceed to device testing.

On Spectacles Hardware

1. Go to File → Build
2. Select your Spectacles device
3. Click Build and Run
4. Put on your Spectacles and start talking!

When successfully connected, you'll see logs like:

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

---

Troubleshooting

Common Issues

Issue	Solution
"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 immediately	Check your API key and Character ID are correct
No audio playback	Ensure 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

---

Next Steps

Now that your SDK is installed and configured:

1. Voice Connection Guide - Learn the details of voice input/output
2. User Management - Understand User ID persistence
3. Action System - Trigger scene actions from AI responses
4. API Reference - Detailed component documentation