@mentra/bluetooth-sdk 0.1.11 → 0.1.12

package/README.md

@@ -150,6 +150,55 @@ uses a CoreBluetooth identifier when available, and the SDK falls back to
 platform reports RSSI, so picker UI should handle `undefined` and avoid
 reordering rows just because RSSI metadata arrives later.
 
+## Mentra SDK Usage Analytics
+
+The SDK sends two anonymous usage events to Mentra's PostHog project by default
+so Mentra can understand SDK adoption and successful glasses connections:
+
+- `bluetooth_sdk_started`: sent once per app runtime after the native SDK starts.
+- `bluetooth_sdk_glasses_connected`: sent when SDK status transitions from not connected to connected.
+
+Analytics delivery is fire-and-forget: events are submitted asynchronously, do
+not block Bluetooth SDK behavior, and are not retried if delivery fails.
+
+React Native / Expo apps can disable these events before SDK startup through
+the config plugin:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@mentra/bluetooth-sdk",
+        {
+          "analytics": false
+        }
+      ]
+    ]
+  }
+}
+```
+
+Native Android apps can pass `BluetoothSdkAnalyticsConfig.disabled()` in
+`MentraBluetoothSdkConfig` or add
+`com.mentra.bluetoothsdk.analytics.disabled=true` as application metadata.
+Native iOS apps can pass `.disabled` in `MentraBluetoothSDKConfiguration` or set
+`MentraBluetoothSdkAnalyticsDisabled` to `true` in `Info.plist`.
+
+Mentra's PostHog project API key is embedded in the SDK as a public analytics
+write token, not a private PostHog personal API key. Apps do not configure the
+analytics destination; these SDK usage events are always sent to Mentra's
+PostHog project unless analytics are disabled.
+
+Captured properties are limited to non-sensitive SDK/app metadata:
+`event_source`, `sdk_platform`, `sdk_surface`, `sdk_version`, the app package or
+bundle identifier, OS platform/version, `event_kind`, and for connection events
+only `fully_booted` plus a glasses model value when the SDK knows it. The SDK
+does not upload BLE MAC addresses, CoreBluetooth identifiers, serial numbers,
+Bluetooth device names, user ids, tokens, Wi-Fi credentials, microphone data,
+photos, or transcripts. PostHog receives a locally generated anonymous SDK
+install id as `distinct_id`, and events include `$process_person_profile: false`.
+
 ## React Hooks
 
 React Native apps can import optional lifecycle helpers from the `react`
@@ -274,7 +323,7 @@ React Native narrows returned values to success shapes where the raw listener ev
 | --- | --- | --- |
 | `requestPhoto(...)` | Terminal `PhotoSuccessResponseEvent` with `state: "success"` after capture and delivery finish. `uploadUrl` is always present; webhook JSON metadata such as `photoUrl`, `statusUrl`, `contentType`, or `fileSizeBytes` is included when the receiver returns it. | Rejects when raw `photo_response.state === "error"`, the SDK cannot send the command, or the terminal photo response times out. |
 | `startVideoRecording(...)` | `VideoRecordingStartedStatusEvent` with `success: true` and `status: "recording_started"`. | Rejects on `success: false` statuses such as `already_recording`, send failure, or timeout. |
-| `stopVideoRecording(...)` | `VideoRecordingStoppedStatusEvent` with `success: true` and `status: "recording_stopped"`. | Rejects on `success: false` statuses such as `not_recording`, send failure, or timeout. |
+| `stopVideoRecording(...)` | `VideoRecordingStoppedStatusEvent` with `success: true` and `status: "recording_stopped"`. When a webhook URL is supplied, resolves after the video upload succeeds. | Rejects on `success: false` statuses such as `not_recording`, webhook upload failure, send failure, or timeout. |
 | `rgbLedControl(...)` | `RgbLedControlSuccessResponseEvent` with `state: "success"`. | Rejects when raw `rgb_led_control_response.state === "error"` or the response times out. |
 | `checkForOtaUpdate()` / `retryOtaVersionCheck()` | `OtaQueryResult`, either `ota_update_available` or current `ota_status`. | Rejects on command transport timeout/failure. A returned `ota_status.status === "failed"` is glasses OTA state, not a command rejection. |
 
@@ -332,7 +381,7 @@ For one-shot manual capture tuning, pass `exposureTimeNs` and `iso` together. `e
 
 Use `setCameraFov({fov, roiPosition})` to configure Mentra Live camera field of view and crop position. FOV is clamped to 62-118 degrees; ROI position is `"center"`, `"bottom"`, or `"top"`. You can also call `setCameraFov({preset: "narrow" | "standard" | "wide"})`; presets map to 82, 102, and 118 degrees with center ROI. The returned `CameraFovResult` resolves only after the ASG client reports that the setting was applied to camera hardware after the restart cooldown, and the promise rejects if the glasses report an error, persist the setting without hardware application, or time out. Raw `settings_ack` events remain available through `addListener("settings_ack", ...)` for diagnostic fields such as `hardwareApplied`. Treat FOV as a framing/ROI control; output resolution and effective detail can vary by capture path, firmware, and camera mode.
 
-`startVideoRecording(...)` and `stopVideoRecording(...)` resolve from successful ASG `video_recording_status` events only when the status matches the requested operation (`recording_started` or `recording_stopped`) and reject when the ASG reports `success: false`. Raw `video_recording_status` events remain available through listeners, including `recording_status` query events with `data.recording`.
+`startVideoRecording(...)` resolves from the ASG `video_recording_status` event whose status is `recording_started`. `stopVideoRecording(...)` without a webhook resolves from `recording_stopped`; with a webhook it waits for `recording_stopped` plus a video `media_success`, and rejects on `media_error`. Raw `video_recording_status`, `media_success`, and `media_error` events remain available through listeners.
 
 ## Streaming
 
@@ -409,7 +458,7 @@ For bare native iOS apps, use the public SwiftPM repository:
 https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
 ```
 
-Add the `MentraBluetoothSDK` product to your app target at version `0.1.11` or newer.
+Add the `MentraBluetoothSDK` product to your app target at version `0.1.12` or newer.
 
 For local SDK development, add this package folder directly in Xcode:
 

package/android/build.gradle

@@ -213,6 +213,7 @@ android {
   defaultConfig {
     versionCode 1
     versionName project.version
+    buildConfigField "String", "SDK_VERSION", "\"${project.version}\""
   }
   publishing {
     singleVariant("release") {

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkAnalytics.kt

@@ -0,0 +1,182 @@
+package com.mentra.bluetoothsdk
+
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import org.json.JSONObject
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.UUID
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import java.util.concurrent.RejectedExecutionException
+
+class BluetoothSdkAnalyticsConfig private constructor(
+    val enabled: Boolean,
+    internal val surface: String,
+) {
+    @JvmOverloads
+    constructor(enabled: Boolean = true) : this(enabled, "android")
+
+    internal fun withSurface(surface: String): BluetoothSdkAnalyticsConfig =
+        BluetoothSdkAnalyticsConfig(enabled, surface)
+
+    companion object {
+        @JvmStatic
+        fun disabled(): BluetoothSdkAnalyticsConfig = BluetoothSdkAnalyticsConfig(enabled = false)
+    }
+}
+
+private data class BluetoothSdkAnalyticsRuntimeConfig(
+    val enabled: Boolean = true,
+    val surface: String = "android",
+) {
+    val isReady: Boolean
+        get() = enabled
+}
+
+internal class BluetoothSdkAnalytics(
+    private val context: Context,
+    initialConfig: BluetoothSdkAnalyticsConfig,
+) {
+    private val appContext = context.applicationContext
+    private val executor: ExecutorService = Executors.newSingleThreadExecutor { runnable ->
+        Thread(runnable, "MentraBluetoothSdkAnalytics").apply { isDaemon = true }
+    }
+    // startedCaptured/lastConnected are touched from store listeners and SDK
+    // entry points, hence @Synchronized on methods that read or write them.
+    private val config = initialConfig.toRuntimeConfig().resolvedForApp(appContext)
+    private var startedCaptured = false
+    private var lastConnected = false
+
+    @Synchronized
+    fun initializeGlassesStatus(status: GlassesStatus) {
+        lastConnected = status.analyticsConnected
+    }
+
+    @Synchronized
+    fun captureStarted() {
+        if (startedCaptured || !config.isReady) return
+        startedCaptured = true
+        capture("bluetooth_sdk_started", mapOf("event_kind" to "sdk_started"))
+    }
+
+    @Synchronized
+    fun observeGlassesStatus(status: GlassesStatus) {
+        val isConnected = status.analyticsConnected
+        val wasConnected = lastConnected
+        lastConnected = isConnected
+        if (!config.isReady) return
+        if (isConnected && !wasConnected) {
+            capture(
+                "bluetooth_sdk_glasses_connected",
+                buildMap {
+                    put("event_kind", "glasses_connected")
+                    put("fully_booted", status.fullyBooted)
+                    status.deviceModel.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
+                },
+            )
+        }
+    }
+
+    fun shutdown() {
+        executor.shutdown()
+    }
+
+    private fun capture(
+        eventName: String,
+        eventProperties: Map<String, Any>,
+    ) {
+        val activeConfig = config
+        if (!activeConfig.isReady) return
+
+        try {
+            // Payload construction stays on the executor: distinctId() reads
+            // SharedPreferences, which must not run on the caller (often main) thread.
+            executor.execute {
+                try {
+                    val payload =
+                        JSONObject(
+                            mapOf(
+                                "api_key" to DEFAULT_POSTHOG_API_KEY,
+                                "event" to eventName,
+                                "distinct_id" to distinctId(),
+                                "properties" to baseProperties(activeConfig) + eventProperties,
+                            )
+                        )
+                    val connection = URL(captureUrl()).openConnection() as HttpURLConnection
+                    connection.requestMethod = "POST"
+                    connection.connectTimeout = 4_000
+                    connection.readTimeout = 4_000
+                    connection.doOutput = true
+                    connection.setRequestProperty("Content-Type", "application/json")
+                    connection.outputStream.use { output ->
+                        output.write(payload.toString().toByteArray(Charsets.UTF_8))
+                    }
+                    connection.inputStream.close()
+                    connection.disconnect()
+                } catch (_: Exception) {
+                    // Analytics must never affect Bluetooth SDK behavior.
+                }
+            }
+        } catch (_: RejectedExecutionException) {
+            // The executor was shut down (SDK closed); dropping the event is fine.
+        }
+    }
+
+    private fun baseProperties(activeConfig: BluetoothSdkAnalyticsRuntimeConfig): Map<String, Any> =
+        buildMap {
+            put("\$process_person_profile", false)
+            put("event_source", "mentra_bluetooth_sdk")
+            put("sdk_platform", "android")
+            put("sdk_surface", activeConfig.surface)
+            put("sdk_version", BuildConfig.SDK_VERSION)
+            put("app_package", appContext.packageName)
+            put("os_platform", "android")
+            put("os_version", Build.VERSION.SDK_INT)
+        }
+
+    private fun distinctId(): String {
+        val prefs = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        prefs.getString(PREFS_DISTINCT_ID, null)?.let { return it }
+        val generated = "mentra-bt-sdk-${UUID.randomUUID()}"
+        prefs.edit().putString(PREFS_DISTINCT_ID, generated).apply()
+        return generated
+    }
+
+    private fun captureUrl(): String {
+        val normalized = DEFAULT_POSTHOG_HOST.trim().trimEnd('/')
+        return "$normalized/i/v0/e/"
+    }
+
+    companion object {
+        internal const val META_ANALYTICS_DISABLED = "com.mentra.bluetoothsdk.analytics.disabled"
+        private const val PREFS_NAME = "mentra_bluetooth_sdk_analytics"
+        private const val PREFS_DISTINCT_ID = "distinct_id"
+        private const val DEFAULT_POSTHOG_API_KEY = "phc_FCweXVAxVgU7wZK4Fk3okOx4RmyNqVHJf62YpZSfJt5"
+        private const val DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com"
+    }
+}
+
+private fun BluetoothSdkAnalyticsConfig.toRuntimeConfig(): BluetoothSdkAnalyticsRuntimeConfig =
+    BluetoothSdkAnalyticsRuntimeConfig(enabled = enabled, surface = surface)
+
+private fun BluetoothSdkAnalyticsRuntimeConfig.resolvedForApp(context: Context): BluetoothSdkAnalyticsRuntimeConfig {
+    val metadata =
+        try {
+            context.packageManager
+                .getApplicationInfo(context.packageName, PackageManager.GET_META_DATA)
+                .metaData
+        } catch (_: Exception) {
+            null
+        }
+
+    val disabledByApp = metadata?.getBoolean(BluetoothSdkAnalytics.META_ANALYTICS_DISABLED, false) == true
+
+    return copy(
+        enabled = enabled && !disabledByApp,
+    )
+}
+
+private val GlassesStatus.analyticsConnected: Boolean
+    get() = connectionState.isConnected || connected || fullyBooted

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkModule.kt

@@ -120,6 +120,10 @@ class BluetoothSdkModule : Module() {
                     sendEvent("video_recording_status", event.values)
                 }
 
+                override fun onMediaUpload(event: MediaUploadEvent) {
+                    sendEvent(event.type, event.values)
+                }
+
                 override fun onRgbLedControlResponse(event: RgbLedControlResponseEvent) {
                     sendEvent("rgb_led_control_response", event.values)
                 }
@@ -213,6 +217,8 @@ class BluetoothSdkModule : Module() {
             "photo_response",
             "photo_status",
             "video_recording_status",
+            "media_success",
+            "media_error",
             "gallery_status",
             "compatible_glasses_search_stop",
             "heartbeat_sent",
@@ -256,7 +262,14 @@ class BluetoothSdkModule : Module() {
                             ?: appContext.currentActivity
                                     ?: throw IllegalStateException("No context available")
             BleTraceLogger.logLifecycle(context, "BluetoothSdkModule", "module_create")
-            sdk = MentraBluetoothSdk.create(context, sdkListener)
+            sdk =
+                    MentraBluetoothSdk.create(
+                            context,
+                            MentraBluetoothSdkConfig(
+                                    analytics = BluetoothSdkAnalyticsConfig().withSurface("react_native")
+                            ),
+                            sdkListener,
+                    )
             deviceManager = DeviceManager.getInstance()
         }
 
@@ -505,12 +518,18 @@ class BluetoothSdkModule : Module() {
                             dim("width"),
                             dim("height"),
                             dim("fps"),
+                            dim("maxRecordingTimeMinutes"),
                     )
             ).values
         }
 
-        AsyncFunction("stopVideoRecording") { requestId: String ->
-            requireSdk().stopVideoRecording(requestId).values
+        // webhookUrl/authToken are supplied at stop (not start) so the token is
+        // fresh when the upload runs. Empty/null webhook = keep on device.
+        AsyncFunction("stopVideoRecording") {
+                requestId: String,
+                webhookUrl: String?,
+                authToken: String? ->
+            requireSdk().stopVideoRecording(requestId, webhookUrl, authToken).values
         }
 
         // MARK: - Stream Commands

package/android/src/main/java/com/mentra/bluetoothsdk/Bridge.kt

@@ -417,6 +417,16 @@ public class Bridge private constructor() {
             sendTypedMessage("video_recording_status", body)
         }
 
+        @JvmStatic
+        fun sendMediaUploadEvent(type: String, values: Map<String, Any>) {
+            val body = HashMap<String, Any>()
+            body["type"] = type
+            values.forEach { (key, value) ->
+                body[key] = value
+            }
+            sendTypedMessage(type, body)
+        }
+
         @JvmStatic
         fun sendVersionInfo(values: Map<String, Any>) {
             fun stringField(vararg keys: String): String =

package/android/src/main/java/com/mentra/bluetoothsdk/DeviceManager.kt

@@ -1505,17 +1505,22 @@ class DeviceManager {
             width: Int = 0,
             height: Int = 0,
             fps: Int = 0,
+            maxRecordingTimeMinutes: Int = 0,
     ) {
         Bridge.log(
                 "MAN: onStartVideoRecording: requestId=$requestId, save=$save, flash=true, sound=$sound, " +
-                        "resolution=${width}x${height}@${fps}fps"
+                        "resolution=${width}x${height}@${fps}fps, maxRecordingTimeMinutes=$maxRecordingTimeMinutes"
         )
-        sgc?.startVideoRecording(requestId, save, true, sound, width, height, fps)
+        sgc?.startVideoRecording(
+                requestId, save, true, sound, width, height, fps, maxRecordingTimeMinutes)
     }
 
-    fun stopVideoRecording(requestId: String) {
-        Bridge.log("MAN: onStopVideoRecording: requestId=$requestId")
-        sgc?.stopVideoRecording(requestId)
+    fun stopVideoRecording(requestId: String, webhookUrl: String?, authToken: String?) {
+        Bridge.log(
+                "MAN: onStopVideoRecording: requestId=$requestId, webhook=" +
+                        if (webhookUrl.isNullOrEmpty()) "none" else "set"
+        )
+        sgc?.stopVideoRecording(requestId, webhookUrl, authToken)
     }
 
     fun setMicState() {

package/android/src/main/java/com/mentra/bluetoothsdk/MentraBluetoothSdk.kt

@@ -23,6 +23,7 @@ class MentraBluetoothSdk private constructor(
     private val deviceManager: DeviceManager
     private val listeners =
         Collections.synchronizedSet(mutableSetOf<MentraBluetoothSdkListener>())
+    private val analytics = BluetoothSdkAnalytics(appContext, config.analytics)
     private val discoveredDeviceNames = mutableSetOf<String>()
     private val bridgeEventSinkId: String
     private val storeListenerId: String
@@ -50,7 +51,13 @@ class MentraBluetoothSdk private constructor(
         Bridge.initialize(appContext)
         deviceManager = DeviceManager.getInstance()
         bridgeEventSinkId = Bridge.addEventSink { eventName, data -> dispatchBridgeEvent(eventName, data) }
+        // Baseline the analytics connection state before subscribing to the store:
+        // store updates invoke listeners synchronously on the updating thread, so a
+        // connected status observed before the baseline would be reported as a fresh
+        // bluetooth_sdk_glasses_connected transition.
+        analytics.initializeGlassesStatus(getRawGlassesStatus())
         storeListenerId = DeviceStore.store.addListener { category, changes -> dispatchStoreUpdate(category, changes) }
+        analytics.captureStarted()
     }
 
     companion object {
@@ -58,6 +65,7 @@ class MentraBluetoothSdk private constructor(
         private val SCAN_STATE_KEYS = setOf("searching", "searchingController", "searchResults")
         private const val DEFAULT_SCAN_TIMEOUT_MS = 15_000L
         private const val DEFAULT_REQUEST_TIMEOUT_MS = 15_000L
+        private const val VIDEO_UPLOAD_STOP_TIMEOUT_MS = 10 * 60 * 1000L
         private const val STREAM_START_TIMEOUT_MS = 30_000L
         private const val STREAM_STOP_TIMEOUT_MS = 15_000L
         private const val DEFAULT_STREAM_KEEP_ALIVE_INTERVAL_SECONDS = 5
@@ -97,6 +105,9 @@ class MentraBluetoothSdk private constructor(
     private data class PendingVideoRecordingRequest(
         val expectedStatus: String,
         val pending: PendingResponse<VideoRecordingStatusEvent>,
+        val waitForUpload: Boolean = false,
+        var stoppedEvent: VideoRecordingStatusEvent? = null,
+        var uploadSucceeded: Boolean = false,
     )
 
     private data class PendingWifiScan(
@@ -184,6 +195,15 @@ class MentraBluetoothSdk private constructor(
 
     fun getDefaultDevice(): Device? = currentDefaultDevice()
 
+    private fun requireGlassesConnected(operation: String) {
+        if (!getRawGlassesStatus().connected) {
+            throw BluetoothException(
+                "glasses_not_connected",
+                "Cannot $operation because glasses are not connected.",
+            )
+        }
+    }
+
     fun setDefaultDevice(device: Device?) {
         if (device == null) {
             clearDefaultDevice()
@@ -771,6 +791,7 @@ class MentraBluetoothSdk private constructor(
 
     fun startVideoRecording(request: VideoRecordingRequest): VideoRecordingStatusEvent {
         require(request.requestId.isNotBlank()) { "requestId is required to start video recording." }
+        requireGlassesConnected("start video recording")
         val pending = PendingResponse<VideoRecordingStatusEvent>("start video recording")
         val pendingRequest = PendingVideoRecordingRequest("recording_started", pending)
         if (pendingVideoRecordingRequests.putIfAbsent(request.requestId, pendingRequest) != null) {
@@ -787,6 +808,7 @@ class MentraBluetoothSdk private constructor(
                     request.width,
                     request.height,
                     request.fps,
+                    request.maxRecordingTimeMinutes,
             )
             return pending.await()
         } finally {
@@ -794,10 +816,22 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
-    fun stopVideoRecording(requestId: String): VideoRecordingStatusEvent {
+    @JvmOverloads
+    fun stopVideoRecording(
+            requestId: String,
+            webhookUrl: String? = null,
+            authToken: String? = null,
+    ): VideoRecordingStatusEvent {
         require(requestId.isNotBlank()) { "requestId is required to stop video recording." }
+        requireGlassesConnected("stop video recording")
         val pending = PendingResponse<VideoRecordingStatusEvent>("stop video recording")
-        val pendingRequest = PendingVideoRecordingRequest("recording_stopped", pending)
+        val waitForUpload = !webhookUrl.isNullOrBlank()
+        val pendingRequest =
+            PendingVideoRecordingRequest(
+                expectedStatus = "recording_stopped",
+                pending = pending,
+                waitForUpload = waitForUpload,
+            )
         if (pendingVideoRecordingRequests.putIfAbsent(requestId, pendingRequest) != null) {
             throw BluetoothException(
                 "request_in_flight",
@@ -805,8 +839,10 @@ class MentraBluetoothSdk private constructor(
             )
         }
         try {
-            deviceManager.stopVideoRecording(requestId)
-            return pending.await()
+            deviceManager.stopVideoRecording(requestId, webhookUrl, authToken)
+            val timeoutMs =
+                if (waitForUpload) VIDEO_UPLOAD_STOP_TIMEOUT_MS else DEFAULT_REQUEST_TIMEOUT_MS
+            return pending.await(timeoutMs)
         } finally {
             pendingVideoRecordingRequests.remove(requestId, pendingRequest)
         }
@@ -917,12 +953,14 @@ class MentraBluetoothSdk private constructor(
         stopStreamKeepAliveMonitor()
         Bridge.removeEventSink(bridgeEventSinkId)
         DeviceStore.store.removeListener(storeListenerId)
+        analytics.shutdown()
         listeners.clear()
     }
 
     private fun dispatchStoreUpdate(category: String, changes: Map<String, Any>) {
         when (ObservableStore.normalizeCategory(category)) {
             "glasses" -> {
+                analytics.observeGlassesStatus(getRawGlassesStatus())
                 val state = getState()
                 dispatchToListeners {
                     it.onStateChanged(state)
@@ -1112,6 +1150,11 @@ class MentraBluetoothSdk private constructor(
                 handleVideoRecordingStatusForRequests(event)
                 dispatchToListeners { it.onVideoRecordingStatus(event) }
             }
+            "media_success", "media_error" -> {
+                val event = MediaUploadEvent(data)
+                handleMediaUploadForRequests(event)
+                dispatchToListeners { it.onMediaUpload(event) }
+            }
             "rgb_led_control_response" -> {
                 val event = RgbLedControlResponseEvent(data)
                 handleRgbLedResponseForRequests(event)
@@ -1341,7 +1384,14 @@ class MentraBluetoothSdk private constructor(
         val request = pendingVideoRecordingRequests[event.requestId] ?: return
         if (event.success) {
             if (event.status == request.expectedStatus) {
-                request.pending.resolve(event)
+                if (request.waitForUpload) {
+                    request.stoppedEvent = event
+                    if (request.uploadSucceeded) {
+                        request.pending.resolve(event)
+                    }
+                } else {
+                    request.pending.resolve(event)
+                }
             }
         } else {
             request.pending.reject(
@@ -1353,6 +1403,27 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
+    private fun handleMediaUploadForRequests(event: MediaUploadEvent) {
+        if (!event.isVideo) return
+        val request = pendingVideoRecordingRequests[event.requestId] ?: return
+        if (!request.waitForUpload) return
+        if (event.isSuccess) {
+            val stoppedEvent = request.stoppedEvent
+            if (stoppedEvent != null) {
+                request.pending.resolve(stoppedEvent)
+            } else {
+                request.uploadSucceeded = true
+            }
+        } else {
+            request.pending.reject(
+                BluetoothException(
+                    "video_upload_failed",
+                    event.errorMessage ?: "Video upload failed.",
+                )
+            )
+        }
+    }
+
     private fun handleRgbLedResponseForRequests(event: RgbLedControlResponseEvent) {
         val pending = pendingRgbLedRequests[event.requestId] ?: return
         if (event.state == "success") {

package/android/src/main/java/com/mentra/bluetoothsdk/camera/CameraModels.kt

@@ -227,6 +227,8 @@ data class VideoRecordingRequest(
     val width: Int = 0,
     val height: Int = 0,
     val fps: Int = 0,
+    // Optional auto-stop timer in minutes; 0 = record until stopped/interrupted.
+    val maxRecordingTimeMinutes: Int = 0,
 )
 
 data class VideoRecordingStatusEvent(
@@ -240,6 +242,19 @@ data class VideoRecordingStatusEvent(
     val data: Map<String, Any>? get() = stringMapValue(values["data"])
 }
 
+data class MediaUploadEvent(
+    val values: Map<String, Any>,
+) {
+    val type: String get() = stringValue(values, "type").orEmpty()
+    val requestId: String get() = stringValue(values, "requestId").orEmpty()
+    val mediaUrl: String? get() = stringValue(values, "mediaUrl")
+    val errorMessage: String? get() = stringValue(values, "errorMessage")
+    val mediaType: Int? get() = numberValue(values, "mediaType")
+    val timestamp: Long get() = longValue(values, "timestamp") ?: System.currentTimeMillis()
+    val isSuccess: Boolean get() = type == "media_success"
+    val isVideo: Boolean get() = mediaType == 2
+}
+
 data class GalleryStatusEvent(
     val values: Map<String, Any>,
 )

package/android/src/main/java/com/mentra/bluetoothsdk/events/BluetoothEvents.kt

@@ -154,6 +154,7 @@ interface MentraBluetoothSdkListener {
     fun onPhotoResponse(event: PhotoResponseEvent) {}
     fun onPhotoStatus(event: PhotoStatusEvent) {}
     fun onVideoRecordingStatus(event: VideoRecordingStatusEvent) {}
+    fun onMediaUpload(event: MediaUploadEvent) {}
     fun onRgbLedControlResponse(event: RgbLedControlResponseEvent) {}
     fun onStreamStatus(event: StreamStatusEvent) {}
     fun onKeepAliveAck(event: KeepAliveAckEvent) {}