The session

Mentra Miniapp SDK betaThe SDK is in beta, so its APIs may change before general availability.There is currently no way to distribute a miniapp built with the Miniapp SDK. In a future release, developers will upload miniapps through the Mentra Developer Console, and users will download them from the Mentra Miniapp Store. Neither service supports Miniapp SDK distribution in MentraOS 3.0.Only use the Miniapp SDK if you are comfortable with these limitations.Developing on Mentra Live? We recommend using the Mentra Bluetooth SDK.The developer tools are available in the Mentra App under Settings → Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at help@mentra.glass.

When your miniapp connects, the SDK hands your registerMiniapp handler a session. It lives in the background layer, and every capability (display, microphone, sensors, storage) is a module on it.

src/background/index.ts

import { registerMiniapp } from "@mentra/miniapp/background";

registerMiniapp((session) => {
  // session.userId       – who this user is
  // session.packageName  – your miniapp's package name
  // session.capabilities – what the connected glasses can do (null until ready)

  session.transcription.on((data) => {
    session.display.render([
      { type: "text", id: "caption", box: { x: 0, y: 0, w: 576, h: 288 }, text: data.text },
    ]);
  });
});

You don’t create or connect the session yourself. The host does it and runs your handler. Everything you do with the glasses goes through session. (For advanced or testing use you can new MiniappSession() and call connect() directly, but a normal miniapp never needs to.)

Modules

Type session. in your editor and autocomplete shows everything. Each module is covered in its own page.

Output

Module	What it does
`session.display`	Scenes of positioned text, images, and shapes on the glasses HUD.
`session.speaker`	Play audio and text-to-speech.
`session.led`	The LED on supported glasses.

Input & audio

Module	What it does
`session.transcription`	Real-time speech-to-text.
`session.translation`	Real-time translation.
`session.mic`	Raw audio chunks and voice-activity detection.
`session.input`	Glasses button presses and touchpad gestures.

Sensors & device

Module	What it does
`session.glasses`	Battery and connection state of the glasses.
`session.location`	GPS: latest fix or a stream.
`session.heading`	Compass heading.
`session.imu`	Head position, and raw accelerometer on G2.
`session.navigation`	Turn-by-turn navigation.

Phone & system

Module	What it does
`session.phone`	Notifications, calendar events, and phone battery.
`session.system`	Share sheet, downloads, clipboard, open URL.
`session.permissions`	Which permissions your miniapp declared, and changes to them.

Storage & data

Module	What it does
`session.storage`	Persistent string key-value storage.
`session.blob`	Persistent binary storage (files, images, audio).
`session.auth`	A miniapp-scoped backend token and an authenticated `fetch`.

Glasses with cameras

Module	What it does
`session.camera`	Photos and video on camera glasses.
`session.stream`	Live streaming on camera glasses.

Interop & UI

Module	What it does
`session.actions`	Expose actions Mentra AI can call.
`session.ui`	The message bus to your UI layer.
`session.cloud`	Cloud-connection status.

Lifecycle

Subscribe to lifecycle events with session.on(event, handler). Each returns an unsubscribe function.

registerMiniapp((session) => {
  session.on("ready", () => {
    // CONNECT_ACK received. session.capabilities / userId are now populated.
  });

  session.on("visibility", (state) => {
    // "foreground" | "background": the user opened or left your miniapp.
  });

  session.on("disconnect", (reason) => {
    // The session ended.
  });
});

session.capabilities, session.userId, and the user’s permissions are populated from the connect handshake, which lands after your handler first runs. Subscribe to events immediately, but read capabilities inside session.on("ready", …) (or session.onCapabilitiesChange). It’s null before then.

If the background context crashes, the host respawns it and re-runs your handler with backoff. See crash recovery.

Subscriptions

Registering a handler subscribes; calling the returned function unsubscribes. You never manage subscriptions by hand.

const stop = session.transcription.on((data) => {
  session.display.render([
    { type: "text", id: "caption", box: { x: 0, y: 0, w: 576, h: 288 }, text: data.text },
  ]);
});

stop(); // unsubscribe

Every .on(), .onUpdate(), .onChunk(), .onButtonPress(), and the rest return this cleanup function. Subscriptions are ref-counted internally: the SDK only talks to the phone on the first subscribe and last unsubscribe of a given stream.

A successful request means accepted, not done. For streaming capabilities, watch the stream for the real result rather than assuming the call already succeeded.

Properties

Property	Type	Description
`session.userId`	`string`	The user’s ID (available after `ready`).
`session.packageName`	`string`	Your miniapp’s package name.
`session.capabilities`	`GlassesCapabilities \| null`	What the connected glasses can do. `null` until `ready`.
`session.visibility`	`"foreground" \| "background"`	Whether the user is currently in your miniapp.
`session.colorScheme`	`"light" \| "dark"`	The host’s current color scheme.
`session.ready`	`boolean`	Whether the connect handshake has completed.

Next steps

Display

Show text and graphics on the glasses.

Transcription

Turn speech into text in real time.

Storage

Persist data across sessions.

Actions

Let Mentra AI call your miniapp.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Modules

Output

Input & audio

Sensors & device

Phone & system

Storage & data

Glasses with cameras

Interop & UI

Lifecycle

Subscriptions

Properties

Next steps

Display

Transcription

Storage

Actions

​Modules

​Output

​Input & audio

​Sensors & device

​Phone & system

​Storage & data

​Glasses with cameras

​Interop & UI

​Lifecycle

​Subscriptions

​Properties

​Next steps

Display

Transcription

Storage

Actions

Modules

Output

Input & audio

Sensors & device

Phone & system

Storage & data

Glasses with cameras

Interop & UI

Lifecycle

Subscriptions

Properties

Next steps