# The session

> Your background-layer handle to everything on the glasses.

Source: https://docs.glassly.ai/app-devs/core-concepts/session/

When your miniapp connects, the SDK hands your
[`registerMiniapp`](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md#the-background-layer)
handler a `session`. It lives in the **background layer**, and every capability
(display, microphone, sensors, storage) is a module on it.

```typescript src/background/index.ts
import { registerMiniapp } from "@glassly/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.mirror`](https://docs.glassly.ai/app-devs/core-concepts/display/mirror.md) | Query and preview intended glasses output across miniapps; requires `DISPLAY_MIRROR`. |
| [`session.display`](https://docs.glassly.ai/app-devs/core-concepts/display/layouts.md) | Scenes of positioned text, images, and shapes on the glasses HUD. |
| [`session.speaker`](https://docs.glassly.ai/app-devs/core-concepts/speakers/text-to-speech.md) | Play audio and text-to-speech. |
| [`session.led`](https://docs.glassly.ai/app-devs/core-concepts/led/overview.md) | The LED on supported glasses. |
| [`session.dashboard`](https://docs.glassly.ai/app-devs/core-concepts/display/layouts.md#dashboard-view) | Bring the glasses' native dashboard to the foreground. |

### Input & audio

| Module | What it does |
|---|---|
| [`session.transcription`](https://docs.glassly.ai/app-devs/core-concepts/microphone/speech-to-text.md) | Real-time speech-to-text. |
| [`session.translation`](https://docs.glassly.ai/app-devs/core-concepts/translation.md) | Real-time translation. |
| [`session.mic`](https://docs.glassly.ai/app-devs/core-concepts/microphone/audio-chunks.md) | Raw audio chunks and voice-activity detection. |
| [`session.input`](https://docs.glassly.ai/app-devs/core-concepts/input.md) | Glasses button presses and touchpad gestures. |

### Sensors & device

| Module | What it does |
|---|---|
| [`session.glasses`](https://docs.glassly.ai/app-devs/core-concepts/glasses.md) | Battery and connection state of the glasses. |
| [`session.location`](https://docs.glassly.ai/app-devs/core-concepts/location.md) | GPS: latest fix or a stream. |
| [`session.imu`](https://docs.glassly.ai/app-devs/core-concepts/imu.md) | Head position, and raw accelerometer on G2. |
| [`session.compass`](https://docs.glassly.ai/app-devs/core-concepts/imu.md#compass) | Glasses compass heading. |
| [`session.lightSensor`](https://docs.glassly.ai/app-devs/core-concepts/light-sensor.md) | Ambient light on G2 custom firmware. |
| [`session.navigation`](https://docs.glassly.ai/app-devs/core-concepts/navigation.md) | Turn-by-turn navigation. |

### Phone & system

| Module | What it does |
|---|---|
| [`session.phone`](https://docs.glassly.ai/app-devs/core-concepts/phone.md) | Notifications, calendar events, phone compass, and phone battery. |
| [`session.settings`](https://docs.glassly.ai/app-devs/reference/system-apis.md#platform-settings) | Host settings: read, write, and follow allowlisted values. Needs `PLATFORM_SETTINGS`. |
| [`session.system`](https://docs.glassly.ai/app-devs/core-concepts/system.md) | Share sheet, downloads, clipboard, open URL. |
| [`session.permissions`](https://docs.glassly.ai/app-devs/core-concepts/permissions.md) | Which permissions your miniapp declared, and changes to them. |

### Storage & data

| Module | What it does |
|---|---|
| [`session.storage`](https://docs.glassly.ai/app-devs/core-concepts/storage.md) | Persistent string key-value storage. |
| [`session.blob`](https://docs.glassly.ai/app-devs/core-concepts/blob.md) | Persistent binary storage (files, images, audio). |
| [`session.auth`](https://docs.glassly.ai/app-devs/core-concepts/auth.md) | A miniapp-scoped backend token and an authenticated `fetch`. |
| [`session.keys`](https://docs.glassly.ai/app-devs/core-concepts/keys.md) | User-supplied provider API keys (Settings > Privacy > API Keys). Requires `API_KEYS`. |
| [`session.memory`](https://docs.glassly.ai/app-devs/core-concepts/memory.md) | The user's shared, phone-local memory timeline. Requires `MEMORY`. |
| [`session.ai`](https://docs.glassly.ai/app-devs/core-concepts/ai.md) | Platform LLM completions. Requires `AI`. |
| `session.speakers` | Resolve enrolled-speaker ids to display names. Requires `SPEAKERS`. |

### Glasses with cameras

| Module | What it does |
|---|---|
| [`session.camera`](https://docs.glassly.ai/app-devs/core-concepts/camera/photos.md) | Photos and video on camera glasses. |
| [`session.stream`](https://docs.glassly.ai/app-devs/core-concepts/stream.md) | Live streaming on camera glasses. |

### Interop & UI

| Module | What it does |
|---|---|
| [`session.actions`](https://docs.glassly.ai/app-devs/core-concepts/miniapp-interop.md) | Expose actions Glassly AI can call. |
| [`session.ui`](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md#talking-between-layers) | The message bus to your UI layer. |
| [`session.cloud`](https://docs.glassly.ai/app-devs/core-concepts/cloud.md) | Cloud-connection status. |
| `session.miniapps` | Inter-miniapp lifecycle and discovery. Needs `MANAGE_MINIAPPS`. |

## Lifecycle

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

```typescript
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.
  });
});
```

| Event | Handler argument | Fires when |
|---|---|---|
| `ready` | — | The connect handshake landed. `capabilities`, `userId`, `preferences`, `launchSource` are populated. |
| `error` | `Error` | The transport failed, or a send threw after `ready`. |
| `beforeDisconnect` | `reason: string` | Last chance before the transport closes. |
| `disconnect` | `reason: string` | The session ended. |
| `visibility` | `"foreground" \| "background"` | The user opened or left your miniapp. |
| `pause` | `reason: "glasses_disconnected"` | The host paused your miniapp. See [pausing](#pausing). |
| `resume` | — | The host resumed your miniapp. |
| `capabilities` | `GlassesCapabilities \| null` | Different glasses connected, or they disconnected. |
| `preferences` | `MiniappPreferences` | The user changed unit system or clock format in Settings > Appearance. |
| `colorScheme` | `"light" \| "dark"` | The host switched light/dark. |
| `permissions` | `PermissionRecord` | The manifest permission record changed. |
| `speakerState` | `SpeakerStateEvent` | Audio playback state changed. See [`session.speaker`](https://docs.glassly.ai/app-devs/core-concepts/speakers/text-to-speech.md). |
| `auth` | `MiniappAuthState` | The miniapp-scoped auth token changed. See [`session.auth`](https://docs.glassly.ai/app-devs/core-concepts/auth.md). |

Links opened for your miniapp arrive only through `session.onLink`, not
`session.on("link")`. See [getting a result back](https://docs.glassly.ai/app-devs/core-concepts/system.md#getting-a-result-back).

Seven of these have a named subscriber that reads better than the string form
and is otherwise identical: `session.onBeforeDisconnect`,
`session.onVisibilityChange`, `session.onPause`, `session.onResume`,
`session.onCapabilitiesChange`, `session.onPreferencesChange`, and
`session.onColorSchemeChange`.

### Pausing

When the glasses stay disconnected for about ten seconds, the host pauses every
miniapp: `pause` fires, streams stop (transcription, sensors, touch, location),
the mic is released, and nothing reaches the glasses until `resume`. The
background context and its state survive, so a teleprompter keeps its position
and a timer keeps its count. Stop your own timers and glasses-facing work in
`onPause` and pick them up in `onResume`.

`session.paused` is seeded from the connect handshake, so check it in `ready`
too: a miniapp started while the glasses are away begins paused and hears
`resume` first.

```typescript
session.onPause(() => clearInterval(tick));
session.onResume(() => startTicking());
```

### Rendering one last frame

`beforeDisconnect` fires when the phone announces an imminent disconnect (about
50 ms of grace) or when `disconnect()` is called locally, and it's the only
place a final frame still reaches the glasses. Handlers run synchronously, so
issue the call and don't await it, and don't start async work here: it won't
finish before the socket closes.

```typescript
session.onBeforeDisconnect(() => {
  session.display.render([]); // clear the screen on the way out
});
```

`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](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md#crash-recovery).

## Subscriptions

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

```typescript
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.preferences` | `MiniappPreferences \| null` | The user's Glassly App preferences: `unitSystem` (`"metric" \| "imperial"`, from Settings > Appearance) and `twelveHourTime` (the phone's own 12/24-hour clock setting). Follow these by default and offer your own override on top. `null` until `ready`, or on hosts that predate the field. Subscribe with `session.onPreferencesChange(prefs => …)`. |
| `session.ready` | `boolean` | Whether the connect handshake has completed. |
| `session.launchSource` | `"phone" \| "glasses" \| null` | Where the user started this session from: the Glassly App or the glasses menu. Null until the handshake completes, or on hosts that do not report it. |

## Next steps

- [Display](https://docs.glassly.ai/app-devs/core-concepts/display/layouts.md)
Show text and graphics on the glasses.
- [Transcription](https://docs.glassly.ai/app-devs/core-concepts/microphone/speech-to-text.md)
Turn speech into text in real time.
- [Storage](https://docs.glassly.ai/app-devs/core-concepts/storage.md)
Persist data across sessions.
- [Actions](https://docs.glassly.ai/app-devs/core-concepts/miniapp-interop.md)
Let Glassly AI call your miniapp.
