​
MentraOS Cloud Events

MentraOS Cloud uses an event-driven architecture to communicate real-time data from the smartglasses to your MentraOS app. Your app can subscribe to specific events and receive data as it becomes available. This document describes how to subscribe to events, the available event types, and the data structure for each event.

​
Subscribing to Events

The AppSession class in the @mentra/sdk provides several ways to subscribe to events. You’ll typically do this within the onSession method of your AppServer: 
protected async onSession(session: AppSession, sessionId: string, userId: string): Promise<void> {
  // ... your session setup ...

  // Subscribe to transcription events
  const unsubscribe = session.events.onTranscription((data) => {
    // Handle transcription data
    console.log(data.text);
  });

  // ... other event subscriptions ...

  // **Important:** Unsubscribe when the session ends.
  this.addCleanupHandler(unsubscribe);
}
session.events is an EventManager instance that provides a consistent interface for all event subscriptions. All subscription methods return an unsubscribe function, which you must call when you no longer need the subscription (typically when the session ends).

​
Subscription Methods

You can subscribe to events using the EventManager. These methods are type-safe for each event type. 
session.events.onTranscription((data: TranscriptionData) => { ... });
session.events.onHeadPosition((data: HeadPosition) => { ... });
session.events.onButtonPress((data: ButtonPress) => { ... });
// ... other methods ...

​
Unsubscribing from Events

Event subscription functions return a function that can be called to unsubscribe from the event. Call this when you no longer need a subscription, for example to stop listening to transcription events when the user requests turning off the microphone. 
const unsubscribe = session.events.onTranscription((data) => {
  // ... handle transcription ...
});

// Later, when you no longer need the subscription:
unsubscribe();

​
Available Events

The following table lists the available event types, their descriptions, and the corresponding data types. You can find the full list with more details in the EventManager reference.
Event TypeDescriptionData Type
TranscriptionReal-time speech-to-text transcription.TranscriptionData
TranslationReal-time translation of transcribed text.TranslationData
Head PositionUser’s head position (‘up’ or ‘down’).HeadPosition
Button PressHardware button press on the glasses.ButtonPress
Phone NotificationNotification received from the user’s connected phone.PhoneNotification
Glasses Battery UpdateBattery level update from the glasses.GlassesBatteryUpdate
Phone Battery UpdateBattery level update from the phone.PhoneBatteryUpdate
Glasses Connection StateConnection status of the glasses.GlassesConnectionState
Voice Activity Detection (VAD)Indicates whether voice activity is detected.Vad
Notification DismissedUser dismissed a notification.NotificationDismissed
Audio ChunkRaw audio data (for advanced use cases).ArrayBuffer