@mentra/miniapp 0.3.0-dev.0

package/dist/modules/speaker.js

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview SpeakerModule — phone-side audio output.
+ *
+ * Mirrors cloud SDK v3's SpeakerManager naming. Audio *input* (transcription,
+ * audio chunks, VAD) lives on session.mic — the split is by I/O direction.
+ *
+ * Imperative surface:
+ *   speaker.play({audioUrl})   — play an arbitrary URL via the phone's
+ *                                AudioPlaybackService.
+ *   speaker.speak(text)        — send a SPEAK request. Phone streams cloud
+ *                                TTS when connected and falls back to local
+ *                                offline TTS when cloud is unavailable.
+ *                                Resolves when playback completes; rejects
+ *                                with a TTS_* error code on cloud failure.
+ *   speaker.createStream(opts) — open a live PCM output stream (16-bit LE).
+ *                                Returns a SpeakerStreamWriter: write() PCM
+ *                                chunks as they arrive (e.g. from a WebSocket
+ *                                in the background), close() to drain, abort()
+ *                                to drop. write() resolves with {bufferedMs}
+ *                                so producers can throttle.
+ *   speaker.stop()             — stop any audio this miniapp is playing.
+ *
+ * State observability:
+ *   speaker.state              — current SpeakerState (sync getter).
+ *   speaker.isPlaying          — true iff state === "playing".
+ *   speaker.onStateChange(h)   — fires on every state transition.
+ *
+ * State machine (per miniapp):
+ *   idle ─── speak()/play() ──► loading ──► playing ──► stopped
+ *                                  │            │           │
+ *                                  └── error ───┴── stop ───┘
+ *
+ * `error` is transient — fires once with errorCode set, then settles to
+ * `stopped` so isPlaying reads false correctly.
+ */
+import { MiniappErrorCode, MiniappRequestType } from "../protocol";
+import { bytesToBase64, toUint8Array } from "./base64";
+/** Raw bytes per bridge write. PCM chunks are small; keep messages snappy. */
+export const SPEAKER_WRITE_CHUNK_BYTES = 256 * 1024;
+// Every non-final base64 slice must decode to complete 16-bit samples. Six
+// raw bytes map to eight base64 chars, preserving both base64 and PCM framing.
+const SPEAKER_WRITE_CHUNK_B64 = Math.floor(SPEAKER_WRITE_CHUNK_BYTES / 6) * 8;
+/**
+ * Soft backpressure ceiling. When the host reports more than this buffered,
+ * it holds the WRITE reply until the buffer drains below it, so a producer
+ * that awaits each write self-throttles to realtime.
+ */
+export const SPEAKER_STREAM_MAX_BUFFERED_MS = 2000;
+/**
+ * Live PCM writer returned by `speaker.createStream()`. 16-bit little-endian
+ * PCM only — decode compressed formats (MP3/Opus) server-side before sending.
+ *
+ * Call `write()` as chunks arrive (each is auto-split into bridge-safe
+ * messages), then `close()` to drain and finish, or `abort()` to drop
+ * immediately. Shaped like BlobWriter so the two stream APIs feel the same.
+ */
+export class SpeakerStreamWriter {
+    constructor(session, streamId) {
+        this.session = session;
+        this.streamId = streamId;
+        this.settled = false;
+        this.writeChain = Promise.resolve();
+    }
+    /**
+     * Append raw PCM bytes (16-bit LE). Auto-chunked. Resolves with the host's
+     * buffered-ms after the last chunk. The host holds the reply while its
+     * buffer is above the backpressure ceiling, so a producer that awaits each
+     * write self-throttles to realtime.
+     */
+    async write(chunk) {
+        this.assertOpen();
+        const bytes = toUint8Array(chunk);
+        if (bytes.byteLength === 0)
+            throw new Error("PCM chunk cannot be empty");
+        if (bytes.byteLength % 2 !== 0)
+            throw new Error("PCM chunk must contain complete 16-bit samples");
+        return this.enqueueWrite(async () => {
+            let last = { bufferedMs: 0 };
+            for (let off = 0; off < bytes.length; off += SPEAKER_WRITE_CHUNK_BYTES) {
+                last = await this.send(bytesToBase64(bytes.subarray(off, off + SPEAKER_WRITE_CHUNK_BYTES)));
+            }
+            return last;
+        });
+    }
+    /** Append already-base64-encoded PCM bytes (e.g. relayed straight off a WS frame). */
+    async writeBase64(b64) {
+        this.assertOpen();
+        if (b64.length === 0 || b64.length % 4 !== 0)
+            throw new Error("PCM base64 must be non-empty and padded");
+        const padding = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+        const decodedBytes = (b64.length / 4) * 3 - padding;
+        if (decodedBytes % 2 !== 0)
+            throw new Error("PCM base64 must contain complete 16-bit samples");
+        return this.enqueueWrite(async () => {
+            let last = { bufferedMs: 0 };
+            // Slice on 4-char boundaries so each chunk is whole base64 groups.
+            for (let off = 0; off < b64.length; off += SPEAKER_WRITE_CHUNK_B64) {
+                last = await this.send(b64.slice(off, off + SPEAKER_WRITE_CHUNK_B64));
+            }
+            return last;
+        });
+    }
+    /** Drain the remaining buffer and finish. Resolves when playback has ended. */
+    async close() {
+        this.assertOpen();
+        this.settled = true;
+        await this.writeChain;
+        // Draining takes as long as the buffered audio — opt out of the default
+        // request timeout like play()/speak() do.
+        const res = await this.session.sendRequest({ type: MiniappRequestType.SPEAKER_STREAM_CLOSE, streamId: this.streamId }, { timeoutMs: 0 });
+        return res ?? {};
+    }
+    /** Stop immediately and drop any buffered audio. Idempotent. */
+    async abort() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        await this.session.sendRequest({
+            type: MiniappRequestType.SPEAKER_STREAM_ABORT,
+            streamId: this.streamId,
+        });
+    }
+    assertOpen() {
+        if (this.settled)
+            throw new Error("SpeakerStreamWriter is already closed/aborted");
+    }
+    async send(base64) {
+        const res = await this.session.sendRequest({
+            type: MiniappRequestType.SPEAKER_STREAM_WRITE,
+            streamId: this.streamId,
+            base64,
+        });
+        return res ?? { bufferedMs: 0 };
+    }
+    /** Preserve PCM ordering even when a producer issues overlapping writes. */
+    enqueueWrite(operation) {
+        const result = this.writeChain.then(operation);
+        this.writeChain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+export class SpeakerModule {
+    constructor(session) {
+        this.session = session;
+        this._state = "idle";
+        this._lastEvent = { state: "idle" };
+    }
+    /** Current speaker playback state. */
+    get state() {
+        return this._state;
+    }
+    /** True iff state === "playing". */
+    get isPlaying() {
+        return this._state === "playing";
+    }
+    /** Play a URL. Resolves when playback completes on the phone. */
+    async play(options) {
+        // Playback length is unbounded (a clip can run for minutes), and the host
+        // only sends its REQUEST_RESULT when playback finishes or is interrupted, so
+        // opt out of the default request timeout — otherwise a long clip would reject
+        // with ACTION_TIMEOUT mid-playback. A `stop()` or disconnect still settles it.
+        await this.session.sendRequest({
+            type: MiniappRequestType.PLAY_AUDIO,
+            audioUrl: options.audioUrl,
+            volume: options.volume,
+            stopOtherAudio: options.stopOtherAudio ?? false,
+        }, { timeoutMs: 0 });
+    }
+    /**
+     * Speak text through the phone. The host streams cloud TTS when connected,
+     * then falls back to local offline TTS.
+     *
+     * Rejects with a MiniappRequestError containing a `code` field on cloud-side
+     * TTS failures: `TTS_TEXT_TOO_LONG`, `TTS_INVALID_VOICE`, `TTS_UPSTREAM_ERROR`.
+     */
+    async speak(text, options = {}) {
+        try {
+            // Like play(): resolves only when TTS playback completes, so opt out of the
+            // default request timeout (long text can outlast it). Settled by the host
+            // result, a stop(), or disconnect.
+            const result = await this.session.sendRequest({
+                type: MiniappRequestType.SPEAK,
+                text,
+                voice_id: options.voice_id,
+                voice_settings: options.voice_settings,
+                volume: options.volume,
+                stopOtherAudio: options.stopOtherAudio ?? false,
+            }, { timeoutMs: 0 });
+            return result ?? { completed: true };
+        }
+        catch (err) {
+            // Normalize so callers can `catch (e) { if (e.code === "TTS_TEXT_TOO_LONG") ...`
+            if (err && typeof err === "object" && "code" in err) {
+                throw err;
+            }
+            throw { code: MiniappErrorCode.INTERNAL, message: String(err) };
+        }
+    }
+    /**
+     * Open a live PCM output stream (16-bit LE) to the phone's audio playback
+     * service. Use from the background to play audio that arrives in chunks
+     * (e.g. live meeting audio over a WebSocket) with low latency — unlike
+     * `play()`, nothing has to be a file or URL first.
+     *
+     * One stream per miniapp: opening a second closes the first. Rejects with
+     * `NOT_IMPLEMENTED` on hosts that predate streaming. Miniapps that depend on
+     * this API must declare `minHostVersion: "2.13.0"` or newer.
+     */
+    async createStream(options = {}) {
+        if (options.volume !== undefined &&
+            (!Number.isFinite(options.volume) || options.volume < 0 || options.volume > 1)) {
+            throw new RangeError("speaker stream volume must be between 0 and 1");
+        }
+        const res = await this.session.sendRequest({
+            type: MiniappRequestType.SPEAKER_STREAM_OPEN,
+            sampleRate: options.sampleRate ?? 16000,
+            channels: options.channels ?? 1,
+            volume: options.volume,
+            stopOtherAudio: options.stopOtherAudio ?? true,
+        });
+        return new SpeakerStreamWriter(this.session, res.streamId);
+    }
+    /** Stop any audio this miniapp is currently playing. */
+    stop() {
+        this.session.sendOneShot({ type: MiniappRequestType.STOP_AUDIO });
+    }
+    /**
+     * Subscribe to speaker state transitions. Fires for every change. Does NOT
+     * fire immediately with the current value — call `state` separately if you
+     * want the seed.
+     */
+    onStateChange(handler) {
+        return this.session.on("speakerState", handler);
+    }
+    /** @internal — applied by MiniappSession on inbound SPEAKER_STATE envelope. */
+    _applyState(event) {
+        // Idempotent: skip if state didn't change. Error events are transient
+        // and are not deduped against the prior state — they're informational
+        // and the phone immediately follows up with `stopped`.
+        if (event.state === this._state && event.state !== "error")
+            return;
+        this._state = event.state;
+        this._lastEvent = event;
+    }
+    /** @internal — for tests. */
+    _getLastEvent() {
+        return { ...this._lastEvent };
+    }
+}
+//# sourceMappingURL=speaker.js.map

package/dist/modules/speaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speaker.js","sourceRoot":"","sources":["../../src/modules/speaker.ts"],"names":[],"mappings":"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"}

package/dist/modules/storage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview SimpleStorage — phone-local key-value store scoped to
+ * (userId, packageName). Mirrors cloud SDK v3's StorageManager surface.
+ *
+ * All operations round-trip to LocalMiniappRuntime, which reads/writes
+ * the phone's storage with a namespaced key format:
+ *   mentraos_localstorage_{userId}_{packageName}_{key}
+ *
+ * Values are plain strings. Callers serialize structured data with
+ * JSON.stringify themselves (matching cloud's SimpleStorage shape).
+ */
+import { MiniappSession } from "../session";
+export declare class SimpleStorage {
+    private readonly session;
+    constructor(session: MiniappSession);
+    /** Get a value by key. Resolves to null when the key is unset. */
+    get(key: string): Promise<string | null>;
+    /** Set a single key/value pair. Overwrites silently. */
+    set(key: string, value: string): Promise<void>;
+    /** Delete one key. No-op if the key is unset. */
+    delete(key: string): Promise<void>;
+    /** List every key in this miniapp's namespace. */
+    keys(): Promise<string[]>;
+    /**
+     * @deprecated Renamed to `keys()` for cloud SDK parity. This alias will be
+     * removed in a future release.
+     */
+    list(): Promise<string[]>;
+    /** Drop every key in this miniapp's namespace. */
+    clear(): Promise<void>;
+    /** True iff `key` is set in this miniapp's namespace. */
+    has(key: string): Promise<boolean>;
+    /**
+     * Read every key/value pair in this miniapp's namespace. Useful for
+     * hydrating state on bootstrap. Bounded by the underlying namespace
+     * size — keep total stored payload small (typical < 1 MB) to avoid
+     * stalling the JSContext when this resolves.
+     */
+    getAll(): Promise<Record<string, string>>;
+    /** Write many key/value pairs in one round-trip. */
+    setMultiple(values: Record<string, string>): Promise<void>;
+    /**
+     * Force any pending in-flight writes to disk. No-op today because the
+     * host writes through immediately, but reserved so a future debounced
+     * backend can honor "flush before I quit" calls without breaking the
+     * API.
+     */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/modules/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/modules/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AAEzC,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,kEAAkE;IAC5D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQ9C,wDAAwD;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpD,iDAAiD;IAC3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC,kDAAkD;IAC5C,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAO/B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAI/B,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,yDAAyD;IACnD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQxC;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAO/C,oDAAoD;IAC9C,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhE;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}

package/dist/modules/storage.js

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview SimpleStorage — phone-local key-value store scoped to
+ * (userId, packageName). Mirrors cloud SDK v3's StorageManager surface.
+ *
+ * All operations round-trip to LocalMiniappRuntime, which reads/writes
+ * the phone's storage with a namespaced key format:
+ *   mentraos_localstorage_{userId}_{packageName}_{key}
+ *
+ * Values are plain strings. Callers serialize structured data with
+ * JSON.stringify themselves (matching cloud's SimpleStorage shape).
+ */
+import { MiniappRequestType } from "../protocol";
+export class SimpleStorage {
+    constructor(session) {
+        this.session = session;
+    }
+    /** Get a value by key. Resolves to null when the key is unset. */
+    async get(key) {
+        const result = await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_GET,
+            key,
+        });
+        return result?.value ?? null;
+    }
+    /** Set a single key/value pair. Overwrites silently. */
+    async set(key, value) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_SET,
+            key,
+            value,
+        });
+    }
+    /** Delete one key. No-op if the key is unset. */
+    async delete(key) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_DELETE,
+            key,
+        });
+    }
+    /** List every key in this miniapp's namespace. */
+    async keys() {
+        const result = await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_LIST,
+        });
+        return result?.keys ?? [];
+    }
+    /**
+     * @deprecated Renamed to `keys()` for cloud SDK parity. This alias will be
+     * removed in a future release.
+     */
+    async list() {
+        return this.keys();
+    }
+    /** Drop every key in this miniapp's namespace. */
+    async clear() {
+        await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_CLEAR,
+        });
+    }
+    /** True iff `key` is set in this miniapp's namespace. */
+    async has(key) {
+        const result = await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_HAS,
+            key,
+        });
+        return !!result?.has;
+    }
+    /**
+     * Read every key/value pair in this miniapp's namespace. Useful for
+     * hydrating state on bootstrap. Bounded by the underlying namespace
+     * size — keep total stored payload small (typical < 1 MB) to avoid
+     * stalling the JSContext when this resolves.
+     */
+    async getAll() {
+        const result = await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_GET_ALL,
+        });
+        return result?.values ?? {};
+    }
+    /** Write many key/value pairs in one round-trip. */
+    async setMultiple(values) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_SET_MULTIPLE,
+            values,
+        });
+    }
+    /**
+     * Force any pending in-flight writes to disk. No-op today because the
+     * host writes through immediately, but reserved so a future debounced
+     * backend can honor "flush before I quit" calls without breaking the
+     * API.
+     */
+    async flush() {
+        await this.session.sendRequest({
+            type: MiniappRequestType.STORAGE_FLUSH,
+        });
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/modules/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/modules/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAA;AAG9C,MAAM,OAAO,aAAa;IACxB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD,kEAAkE;IAClE,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAyB;YACpE,IAAI,EAAE,kBAAkB,CAAC,WAAW;YACpC,GAAG;SACJ,CAAC,CAAA;QACF,OAAO,MAAM,EAAE,KAAK,IAAI,IAAI,CAAA;IAC9B,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QAClC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,WAAW;YACpC,GAAG;YACH,KAAK;SACN,CAAC,CAAA;IACJ,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,cAAc;YACvC,GAAG;SACJ,CAAC,CAAA;IACJ,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAmB;YAC9D,IAAI,EAAE,kBAAkB,CAAC,YAAY;SACtC,CAAC,CAAA;QACF,OAAO,MAAM,EAAE,IAAI,IAAI,EAAE,CAAA;IAC3B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,IAAI,EAAE,CAAA;IACpB,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,aAAa;SACvC,CAAC,CAAA;IACJ,CAAC;IAED,yDAAyD;IACzD,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAiB;YAC5D,IAAI,EAAE,kBAAkB,CAAC,WAAW;YACpC,GAAG;SACJ,CAAC,CAAA;QACF,OAAO,CAAC,CAAC,MAAM,EAAE,GAAG,CAAA;IACtB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM;QACV,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAmC;YAC9E,IAAI,EAAE,kBAAkB,CAAC,eAAe;SACzC,CAAC,CAAA;QACF,OAAO,MAAM,EAAE,MAAM,IAAI,EAAE,CAAA;IAC7B,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,WAAW,CAAC,MAA8B;QAC9C,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,oBAAoB;YAC7C,MAAM;SACP,CAAC,CAAA;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,aAAa;SACvC,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/modules/stream.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview StreamModule -- video streaming from glasses.
+ *
+ * Wires to cloud streaming extensions via the __phone__ subscriber path.
+ *
+ * One entry point: `startStream`. By default it provisions a Mentra-hosted
+ * stream and returns playback URLs (managed). Pass `direct` to publish straight
+ * to your own ingest URL with no relay.
+ */
+import { MiniappSession } from "../session";
+export interface StreamVideoConfig {
+    width?: number;
+    height?: number;
+    bitrate?: number;
+    fps?: number;
+}
+export interface StreamAudioConfig {
+    bitrate?: number;
+    sampleRate?: number;
+    echoCancellation?: boolean;
+    noiseSuppression?: boolean;
+}
+export interface StreamResolvedConfig {
+    transport?: "rtmp" | "srt" | "whip";
+    video?: {
+        width: number;
+        height: number;
+        captureWidth?: number;
+        captureHeight?: number;
+        bitrate: number;
+        fps: number;
+    };
+    audio?: {
+        bitrate?: number;
+        sampleRate?: number;
+        echoCancellation?: boolean;
+        noiseSuppression?: boolean;
+    };
+}
+/**
+ * Restream destination. The full stream key is part of the URL (e.g.
+ * `rtmp://yt.com/live/STREAM-KEY`). `name` is a human label that surfaces
+ * in dashboards but doesn't affect routing.
+ */
+export interface RestreamDestination {
+    url: string;
+    name?: string;
+}
+export interface StartStreamOptions {
+    /**
+     * Publish straight to your own ingest URL (rtmp/rtmps/srt/whip). The glasses
+     * connect to it directly with no Mentra relay, so no playback URLs come back.
+     * Omit this to use the managed relay (the default, best for most apps).
+     */
+    direct?: string;
+    /**
+     * Restream destinations the managed relay fans out to (YouTube, Twitch, …).
+     * Bare URL strings or `{url, name?}` objects; mix freely. Managed streams
+     * only — ignored when `direct` is set.
+     */
+    destinations?: Array<string | RestreamDestination>;
+    video?: StreamVideoConfig;
+    audio?: StreamAudioConfig;
+    /** Play glasses-side stream start/stop sounds. Defaults to true. */
+    sound?: boolean;
+    /**
+     * Managed ingest protocol, a latency/durability trade. Ignored when `direct`
+     * is set.
+     *   - "srt" (default): ~10-20s latency via LL-HLS, shareable HLS/DASH URLs,
+     *     and automatic recording.
+     *   - "whip": sub-second WebRTC playback (use `webrtcUrl`/WHEP), but no
+     *     HLS/DASH and no recording.
+     */
+    ingest?: "srt" | "whip";
+}
+export interface StreamResult {
+    streamId: string;
+    status: string;
+    resolvedConfig?: StreamResolvedConfig;
+    /** Managed streams only: the live-input UID for building hosted-player URLs. */
+    liveInputId?: string;
+    /** Managed streams only: which playback this stream serves. In "webrtc" mode
+     *  `hlsUrl` never serves content. */
+    mode?: "hls" | "webrtc";
+    /** Managed streams only: HLS playback URL. */
+    hlsUrl?: string;
+    /** Managed streams only: DASH playback URL. */
+    dashUrl?: string;
+    /** Managed streams only: WHEP playback URL (present in "webrtc" mode). */
+    webrtcUrl?: string;
+}
+/** Live encoder telemetry, when the glasses emit it (no firmware does yet). */
+export interface StreamLiveStats {
+    /** Current encoded video bitrate in bits per second. */
+    bitrate?: number;
+    /** Current encode frame rate. */
+    fps?: number;
+    droppedFrames?: number;
+    /** Seconds since the stream started. */
+    duration?: number;
+    /** Device temperature in °C, if the hardware reports it. */
+    temperatureC?: number;
+}
+export interface StreamStatus {
+    streamId: string;
+    status: string;
+    errorDetails?: string;
+    /** Negotiated encode config — forwarded once, on the first status ack. */
+    resolvedConfig?: StreamResolvedConfig;
+    stats?: StreamLiveStats;
+}
+export declare class StreamModule {
+    private readonly session;
+    constructor(session: MiniappSession);
+    /**
+     * Start a live video stream from the glasses camera.
+     *
+     * Managed (default) -- Mentra hosts the stream and the result carries
+     * `hlsUrl`/`dashUrl`/`webrtcUrl` for playback. Optionally fan out to your own
+     * `destinations`.
+     *
+     * Direct -- pass `direct` with your own ingest URL; the glasses publish to it
+     * and no playback URLs are returned.
+     */
+    startStream(options?: StartStreamOptions): Promise<StreamResult>;
+    /** Stop the active stream, or a specific one by `streamId`. */
+    stop(streamId?: string): Promise<void>;
+}
+//# sourceMappingURL=stream.d.ts.map

package/dist/modules/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/modules/stream.ts"],"names":[],"mappings":"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"}

package/dist/modules/stream.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview StreamModule -- video streaming from glasses.
+ *
+ * Wires to cloud streaming extensions via the __phone__ subscriber path.
+ *
+ * One entry point: `startStream`. By default it provisions a Mentra-hosted
+ * stream and returns playback URLs (managed). Pass `direct` to publish straight
+ * to your own ingest URL with no relay.
+ */
+import { MiniappRequestType } from "../protocol";
+export class StreamModule {
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Start a live video stream from the glasses camera.
+     *
+     * Managed (default) -- Mentra hosts the stream and the result carries
+     * `hlsUrl`/`dashUrl`/`webrtcUrl` for playback. Optionally fan out to your own
+     * `destinations`.
+     *
+     * Direct -- pass `direct` with your own ingest URL; the glasses publish to it
+     * and no playback URLs are returned.
+     */
+    async startStream(options = {}) {
+        if (options.direct !== undefined) {
+            return this.session.sendRequest({
+                type: MiniappRequestType.STREAM_START,
+                streamUrl: options.direct,
+                video: options.video,
+                audio: options.audio,
+                sound: options.sound ?? true,
+            });
+        }
+        return this.session.sendRequest({
+            type: MiniappRequestType.MANAGED_STREAM_START,
+            restreamDestinations: options.destinations,
+            video: options.video,
+            audio: options.audio,
+            sound: options.sound ?? true,
+            ingest: options.ingest,
+        });
+    }
+    /** Stop the active stream, or a specific one by `streamId`. */
+    async stop(streamId) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.STREAM_STOP,
+            streamId,
+        });
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/modules/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/modules/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAA;AAgH9C,MAAM,OAAO,YAAY;IACvB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,CAAC,UAA8B,EAAE;QAChD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAe;gBAC5C,IAAI,EAAE,kBAAkB,CAAC,YAAY;gBACrC,SAAS,EAAE,OAAO,CAAC,MAAM;gBACzB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI;aAC7B,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAe;YAC5C,IAAI,EAAE,kBAAkB,CAAC,oBAAoB;YAC7C,oBAAoB,EAAE,OAAO,CAAC,YAAY;YAC1C,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAA;IACJ,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,IAAI,CAAC,QAAiB;QAC1B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,WAAW;YACpC,QAAQ;SACT,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/modules/system.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview SystemModule — OS-level utilities (share, open URL, clipboard, download).
+ *
+ * These bridge to native phone capabilities via LocalMiniappRuntime.
+ */
+import { MiniappSession } from "../session";
+export interface ShareOptions {
+    text?: string;
+    url?: string;
+    title?: string;
+    /** Base64-encoded file data for file sharing. */
+    base64?: string;
+    /** MIME type when sharing base64 data. */
+    mimeType?: string;
+    /** Filename when sharing base64 data. */
+    filename?: string;
+}
+export interface ShareResult {
+    success: boolean;
+    cancelled?: boolean;
+}
+export interface DownloadOptions {
+    /** URL to download from, OR base64 data. */
+    url?: string;
+    base64?: string;
+    filename?: string;
+    mimeType?: string;
+}
+export interface DownloadResult {
+    success: boolean;
+    cancelled?: boolean;
+}
+export declare class SystemModule {
+    private readonly session;
+    constructor(session: MiniappSession);
+    /** Open the OS share sheet with the given content. */
+    share(options: ShareOptions): Promise<ShareResult>;
+    /** Open a URL in the system browser. Blocks dangerous schemes (javascript:, file:). */
+    openUrl(url: string): void;
+    /** Copy text to the system clipboard. */
+    copyToClipboard(text: string): Promise<void>;
+    /** Download a file. Opens the OS share sheet so user can choose save location. */
+    download(options: DownloadOptions): Promise<DownloadResult>;
+}
+//# sourceMappingURL=system.d.ts.map

package/dist/modules/system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../src/modules/system.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,sDAAsD;IAChD,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAQxD,uFAAuF;IACvF,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAO1B,yCAAyC;IACnC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD,kFAAkF;IAC5E,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAOlE"}