Photos

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 [email protected].

session.camera.takePhoto captures a still on glasses that have a camera, like Mentra Live. It resolves after the photo is captured and uploaded, and hands you back a download URL.

src/background/index.ts

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

registerMiniapp((session) => {
  session.input.onButtonPress(async () => {
    if (!session.capabilities?.hasCamera) return;
    const photo = await session.camera.takePhoto();
    session.display.render([{type: "image", id: "photo", box: {x: 144, y: 44, w: 288, h: 200}, data: photo.photoUrl}]);
  });
});

Camera needs the CAMERA permission and glasses with a camera. Declare a CAMERA permission in your manifest so the call is allowed, and a CAMERA hardware requirement so the miniapp only installs on glasses that can capture. Check session.capabilities.hasCamera before calling so you don’t fire a request the glasses can’t satisfy.

Take a photo

takePhoto sends the request, waits while the glasses capture and the phone uploads, then resolves with the photo metadata. The returned photoUrl is a signed download URL with a short TTL (about 30 minutes), so fetch or display it soon after.

const photo = await session.camera.takePhoto({ size: "high", sound: false });
// photo.photoUrl  – signed URL, ~30 min TTL
// photo.mimeType  – e.g. "image/jpeg"
// photo.size      – bytes

All options are optional. The defaults are listed below.

Option	Type	Default	What it does
`size`	`"low" \| "medium" \| "high" \| "max"`	`"medium"`	Capture resolution.
`transferMethod`	`"auto" \| "direct" \| "ble"`	`"auto"`	Use `"direct"` for webhook upload without BLE fallback, or `"ble"` to always relay through the phone.
`compress`	`"none" \| "low" \| "medium" \| "high"`	`"none"`	JPEG compression applied before upload.
`sound`	`boolean`	`true`	Play a shutter sound on the glasses.
`saveToGallery`	`boolean`	`false`	Keep a copy in the glasses gallery.
`exposureTimeNs`	`number`	auto	Manual shutter time in nanoseconds. Honored only on cameras with manual exposure; ignored otherwise. Omit to auto-expose.

Unknown runtime transferMethod values are rejected instead of being treated as "auto". The result is a PhotoTaken:

Field	Type	Description
`requestId`	`string`	Correlates the request with ASG status and upload logs.
`photoUrl`	`string`	Signed download URL for the captured image (~30 min TTL).
`mimeType`	`string`	MIME type of the image, e.g. `"image/jpeg"`.
`size`	`number`	Image size in bytes.

Field of view

setFov applies a temporary FOV/ROI override owned by the calling miniapp and resolves after the ASG client reports it was applied. It applies to all captures (photos and video) while that miniapp is active. When the miniapp closes, the host restores the previous live miniapp override or the persistent base setting. The factory/missing base is the centered standard preset (102 degrees); existing saved user values are preserved.

// A named preset. The simplest option, always center ROI.
await session.camera.setFov({ preset: "wide" });

// Or an explicit horizontal FOV with a region.
await session.camera.setFov({ fov: 102, roiPosition: "bottom" });

The argument is one of two shapes:

Field	Type	Notes
`preset`	`"narrow" \| "standard" \| "wide"`	Named preset. Uses center ROI. Mutually exclusive with `fov`/`roiPosition`.
`fov`	`number`	Horizontal FOV in degrees. Pair with `roiPosition`.
`roiPosition`	`"center" \| "bottom" \| "top"`	Region position for the `fov` form. Defaults to `"center"`.

It resolves with a CameraFovResult:

Field	Type	Description
`requestId`	`string`	Correlates the request with ASG logs.
`fov`	`number`	The applied horizontal FOV in degrees.
`roiPosition`	`"center" \| "bottom" \| "top"`	The applied region position.
`timestamp`	`number`	When the setting was applied.

Errors

Every method returns a promise that rejects with { code, message } on failure. Wrap calls in try/catch and read code.

Code	When
`PERMISSION_NOT_DECLARED`	The miniapp didn’t declare the `CAMERA` permission.
`REQUEST_ABORTED`	The request timed out, or the session was torn down before it completed.
`INTERNAL`	The phone-side handler threw. The glasses have no camera, capture or upload failed, or another device error occurred. Read `message`.

try {
  const photo = await session.camera.takePhoto();
  session.display.render([{type: "image", id: "photo", box: {x: 144, y: 44, w: 288, h: 200}, data: photo.photoUrl}]);
} catch (err) {
  if (err.code === "PERMISSION_NOT_DECLARED") {
    session.display.render([
      {type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: "Camera permission not granted"},
    ]);
  }
}

For video, see Videos. For live video streaming, see Streaming.

Breaking change: photo compression

Photo compression now accepts exactly none, low, medium, and high, sent unchanged across the Mentra Miniapp SDK, Bluetooth SDKs, and glasses. The default is none everywhere. Glasses encode these as JPEG Q95, Q88, Q78, and Q60 respectively; size controls dimensions separately. none still uses lossy JPEG encoding. Unknown values are rejected. Cloud only allocates upload/download URLs: it takes no photo options and ignores any request body. Photo compression is handled by the phone and glasses. The former heavy spelling is removed; callers must use high. Android’s native default changes from medium to none. Existing miniapps may therefore produce different JPEG quality or payload sizes. There are no compatibility aliases or wire translations.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Take a photo

Field of view

Errors

Breaking change: photo compression

​Take a photo

​Field of view

​Errors

​Breaking change: photo compression

Take a photo

Field of view

Errors

Breaking change: photo compression