@mentra/bluetooth-sdk 0.1.11 → 0.1.12

package/ios/Source/MentraBluetoothSDK.swift

@@ -81,10 +81,14 @@ private final class PendingHotspotStatusRequest {
 private final class PendingVideoRecordingRequest {
     let expectedStatus: String
     let pending: PendingResponse<VideoRecordingStatusEvent>
+    let waitForUpload: Bool
+    var stoppedEvent: VideoRecordingStatusEvent?
+    var uploadSucceeded = false
 
-    init(expectedStatus: String, pending: PendingResponse<VideoRecordingStatusEvent>) {
+    init(expectedStatus: String, pending: PendingResponse<VideoRecordingStatusEvent>, waitForUpload: Bool = false) {
         self.expectedStatus = expectedStatus
         self.pending = pending
+        self.waitForUpload = waitForUpload
     }
 }
 
@@ -147,13 +151,18 @@ public final class MentraBluetoothSDK {
 
     private let configuration: MentraBluetoothSDKConfiguration
     private var discoveredDeviceNames = Set<String>()
+    private var bluetoothAvailabilityListenerId: UUID?
+    private var shouldRestoreGlassesOnBluetoothRestore = false
+    private var shouldRestoreControllerOnBluetoothRestore = false
     private var bridgeEventSinkId: String?
     private var storeListenerId: String?
     private let defaultDeviceKeys: Set<String> = ["default_wearable", "device_name", "device_address"]
+    private let videoUploadStopTimeoutMs = 10 * 60 * 1000
     private var suppressDefaultDeviceEvents = false
     private var defaultDeviceApplyGeneration = 0
     private var activeScanSessions: [UUID: ActiveScanSession] = [:]
     private var activeStreamKeepAlive: ActiveStreamKeepAlive?
+    private let analytics: BluetoothSdkAnalytics
     private var pendingPhotoRequests: [String: PendingResponse<PhotoResponseEvent>] = [:]
     private var pendingVideoRecordingRequests: [String: PendingVideoRecordingRequest] = [:]
     private var pendingRgbLedRequests: [String: PendingResponse<RgbLedControlResponseEvent>] = [:]
@@ -170,7 +179,12 @@ public final class MentraBluetoothSDK {
 
     public init(configuration: MentraBluetoothSDKConfiguration = .default) {
         self.configuration = configuration
-        _ = BluetoothAvailability.shared
+        analytics = BluetoothSdkAnalytics(configuration: configuration.analytics)
+        bluetoothAvailabilityListenerId = BluetoothAvailability.shared.addStateListener { [weak self] state in
+            Task { @MainActor [weak self] in
+                self?.handleBluetoothAvailability(state)
+            }
+        }
         bridgeEventSinkId = Bridge.addEventSink { [weak self] eventName, data in
             Task { @MainActor [weak self] in
                 self?.dispatchBridgeEvent(eventName, data)
@@ -181,6 +195,8 @@ public final class MentraBluetoothSDK {
                 self?.dispatchStoreUpdate(category, changes)
             }
         }
+        analytics.initializeGlassesStatus(glassesStatus)
+        analytics.captureStarted()
     }
 
     public var state: MentraBluetoothState {
@@ -211,6 +227,15 @@ public final class MentraBluetoothSDK {
         currentDefaultDevice()
     }
 
+    private func requireGlassesConnected(operation: String) throws {
+        guard glassesStatus.connected else {
+            throw BluetoothError(
+                code: "glasses_not_connected",
+                message: "Cannot \(operation) because glasses are not connected."
+            )
+        }
+    }
+
     public func getDefaultDevice() -> Device? {
         currentDefaultDevice()
     }
@@ -296,6 +321,7 @@ public final class MentraBluetoothSDK {
     }
 
     public func connect(to device: Device, options: ConnectOptions = ConnectOptions()) throws {
+        clearBluetoothRestoreIntent()
         if device.model != .simulated {
             try BluetoothAvailability.shared.requirePoweredOn(operation: "connect to glasses")
         }
@@ -315,6 +341,7 @@ public final class MentraBluetoothSDK {
     }
 
     public func connectDefault(options: ConnectOptions = ConnectOptions()) throws {
+        clearBluetoothRestoreIntent()
         guard let device = currentDefaultDevice() else {
             throw BluetoothError(
                 code: "default_device_missing",
@@ -331,18 +358,22 @@ public final class MentraBluetoothSDK {
     }
 
     public func cancelConnectionAttempt() {
+        clearBluetoothRestoreIntent()
         DeviceManager.shared.disconnect()
     }
 
     func connectSimulated() {
+        clearBluetoothRestoreIntent()
         DeviceManager.shared.connectSimulated()
     }
 
     public func disconnect() {
+        clearBluetoothRestoreIntent()
         DeviceManager.shared.disconnect()
     }
 
     public func forget() {
+        clearBluetoothRestoreIntent()
         DeviceManager.shared.forget()
     }
 
@@ -806,6 +837,7 @@ public final class MentraBluetoothSDK {
         guard !request.requestId.isEmpty else {
             throw BluetoothError(code: "missing_request_id", message: "requestId is required to start video recording.")
         }
+        try requireGlassesConnected(operation: "start video recording")
         let pending = PendingResponse<VideoRecordingStatusEvent>(
             operation: "start video recording \(request.requestId)"
         )
@@ -825,7 +857,8 @@ public final class MentraBluetoothSDK {
             request.sound,
             request.width,
             request.height,
-            request.fps
+            request.fps,
+            request.maxRecordingTimeMinutes
         )
         do {
             let event = try await pending.wait()
@@ -837,10 +870,13 @@ public final class MentraBluetoothSDK {
         }
     }
 
-    public func stopVideoRecording(requestId: String) async throws -> VideoRecordingStatusEvent {
+    public func stopVideoRecording(
+        requestId: String, webhookUrl: String? = nil, authToken: String? = nil
+    ) async throws -> VideoRecordingStatusEvent {
         guard !requestId.isEmpty else {
             throw BluetoothError(code: "missing_request_id", message: "requestId is required to stop video recording.")
         }
+        try requireGlassesConnected(operation: "stop video recording")
         let pending = PendingResponse<VideoRecordingStatusEvent>(operation: "stop video recording \(requestId)")
         guard pendingVideoRecordingRequests[requestId] == nil else {
             throw BluetoothError(
@@ -848,13 +884,16 @@ public final class MentraBluetoothSDK {
                 message: "A video recording command is already waiting for requestId \(requestId)."
             )
         }
+        let waitForUpload = !(webhookUrl?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ?? true)
         pendingVideoRecordingRequests[requestId] = PendingVideoRecordingRequest(
             expectedStatus: "recording_stopped",
-            pending: pending
+            pending: pending,
+            waitForUpload: waitForUpload
         )
-        DeviceManager.shared.stopVideoRecording(requestId)
+        DeviceManager.shared.stopVideoRecording(requestId, webhookUrl, authToken)
         do {
-            let event = try await pending.wait()
+            let timeoutMs = waitForUpload ? videoUploadStopTimeoutMs : 15_000
+            let event = try await pending.wait(timeoutMs: timeoutMs)
             pendingVideoRecordingRequests.removeValue(forKey: requestId)
             return event
         } catch {
@@ -971,6 +1010,10 @@ public final class MentraBluetoothSDK {
 
     public func invalidate() {
         stopStreamKeepAliveMonitor()
+        if let bluetoothAvailabilityListenerId {
+            BluetoothAvailability.shared.removeStateListener(bluetoothAvailabilityListenerId)
+            self.bluetoothAvailabilityListenerId = nil
+        }
         if let bridgeEventSinkId {
             Bridge.removeEventSink(bridgeEventSinkId)
             self.bridgeEventSinkId = nil
@@ -982,6 +1025,83 @@ public final class MentraBluetoothSDK {
         delegate = nil
     }
 
+    private func handleBluetoothAvailability(_ state: CBManagerState) {
+        switch state {
+        case .poweredOff, .resetting, .unauthorized, .unsupported:
+            handleBluetoothUnavailable()
+        case .poweredOn:
+            handleBluetoothRestored()
+        case .unknown:
+            break
+        @unknown default:
+            handleBluetoothUnavailable()
+        }
+    }
+
+    private func handleBluetoothUnavailable() {
+        cancelActiveScanSessions(reason: .cancelled)
+        clearBluetoothDiscoveryState()
+        disconnectActiveConnections()
+    }
+
+    private func disconnectActiveConnections() {
+        if glassesStatus.controllerConnected {
+            DeviceManager.shared.disconnectController()
+            shouldRestoreControllerOnBluetoothRestore = true
+        }
+        if glassesStatus.deviceModel == DeviceTypes.SIMULATED
+            || DeviceManager.shared.sgc?.type.contains(DeviceTypes.SIMULATED) == true
+        {
+            return
+        }
+        if glassesStatus.connected || glassesStatus.connectionState != .disconnected {
+            DeviceManager.shared.disconnect()
+            shouldRestoreGlassesOnBluetoothRestore = true
+        }
+    }
+
+    /// Reconnect only what `handleBluetoothUnavailable` tore down, never a
+    /// connection the user closed themselves (explicit connect/disconnect
+    /// calls clear the restore intent).
+    private func handleBluetoothRestored() {
+        let restoreGlasses = shouldRestoreGlassesOnBluetoothRestore
+        let restoreController = shouldRestoreControllerOnBluetoothRestore
+        clearBluetoothRestoreIntent()
+
+        if restoreGlasses, !glassesStatus.connected, glassesStatus.connectionState == .disconnected {
+            DeviceManager.shared.connectDefault() // also restores the controller
+        } else if restoreController, !glassesStatus.controllerConnected {
+            DeviceManager.shared.connectDefaultController()
+        }
+    }
+
+    private func clearBluetoothRestoreIntent() {
+        shouldRestoreGlassesOnBluetoothRestore = false
+        shouldRestoreControllerOnBluetoothRestore = false
+    }
+
+    private func clearBluetoothDiscoveryState() {
+        discoveredDeviceNames.removeAll()
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "searching", false)
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "searchingController", false)
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "searchResults", [] as [[String: Any]])
+    }
+
+    private func cancelActiveScanSessions(reason: ScanStopReason) {
+        let ids = Array(activeScanSessions.keys)
+        guard !ids.isEmpty else {
+            if bluetoothStatus.searching || bluetoothStatus.searchingController {
+                stopScan(reason: reason)
+            }
+            return
+        }
+        for (index, id) in ids.enumerated() {
+            // Stop the underlying scan once (first session); the rest only
+            // complete their callbacks.
+            finishScanSession(id, reason: reason, shouldStopScan: index == 0)
+        }
+    }
+
     private func startStreamKeepAliveMonitor(streamId: String, intervalSeconds requestedIntervalSeconds: Int) {
         let intervalSeconds = requestedIntervalSeconds > 0 ? requestedIntervalSeconds : 5
         let tracker = ActiveStreamKeepAlive(streamId: streamId, intervalSeconds: intervalSeconds)
@@ -1162,7 +1282,14 @@ public final class MentraBluetoothSDK {
         guard let request = pendingVideoRecordingRequests[event.requestId] else { 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(
@@ -1174,6 +1301,26 @@ public final class MentraBluetoothSDK {
         }
     }
 
+    private func handleMediaUploadForRequests(_ event: MediaUploadEvent) {
+        guard event.isVideo, let request = pendingVideoRecordingRequests[event.requestId], request.waitForUpload else {
+            return
+        }
+        if event.isSuccess {
+            if let stoppedEvent = request.stoppedEvent {
+                request.pending.resolve(stoppedEvent)
+            } else {
+                request.uploadSucceeded = true
+            }
+        } else {
+            request.pending.reject(
+                BluetoothError(
+                    code: "video_upload_failed",
+                    message: event.errorMessage ?? "Video upload failed."
+                )
+            )
+        }
+    }
+
     private func handleRgbLedResponseForRequests(_ event: RgbLedControlResponseEvent) {
         guard let pending = pendingRgbLedRequests[event.requestId] else { return }
         if event.state == "success" {
@@ -1273,6 +1420,7 @@ public final class MentraBluetoothSDK {
     private func dispatchStoreUpdate(_ category: String, _ changes: [String: Any]) {
         switch ObservableStore.normalizeCategory(category) {
         case "glasses":
+            analytics.observeGlassesStatus(glassesStatus)
             let nextState = state
             delegate?.mentraBluetoothSDK(self, didUpdate: nextState)
             delegate?.mentraBluetoothSDK(self, didUpdateGlasses: nextState.glasses)
@@ -1424,6 +1572,10 @@ public final class MentraBluetoothSDK {
             let event = VideoRecordingStatusEvent(values: data)
             handleVideoRecordingStatusForRequests(event)
             delegate?.mentraBluetoothSDK(self, didReceive: .videoRecordingStatus(event))
+        case "media_success", "media_error":
+            let event = MediaUploadEvent(values: data)
+            handleMediaUploadForRequests(event)
+            delegate?.mentraBluetoothSDK(self, didReceive: .mediaUpload(event))
         case "rgb_led_control_response":
             let event = RgbLedControlResponseEvent(values: data)
             handleRgbLedResponseForRequests(event)

package/ios/Source/camera/CameraModels.swift

@@ -229,9 +229,12 @@ public struct VideoRecordingRequest {
     public let width: Int
     public let height: Int
     public let fps: Int
+    // Optional auto-stop timer in minutes; 0 = record until stopped/interrupted.
+    public let maxRecordingTimeMinutes: Int
 
     public init(
-        requestId: String, save: Bool, sound: Bool, width: Int = 0, height: Int = 0, fps: Int = 0
+        requestId: String, save: Bool, sound: Bool, width: Int = 0, height: Int = 0, fps: Int = 0,
+        maxRecordingTimeMinutes: Int = 0
     ) {
         self.requestId = requestId
         self.save = save
@@ -239,6 +242,7 @@ public struct VideoRecordingRequest {
         self.width = width
         self.height = height
         self.fps = fps
+        self.maxRecordingTimeMinutes = maxRecordingTimeMinutes
     }
 }
 
@@ -280,6 +284,50 @@ public struct VideoRecordingStatusEvent: CustomStringConvertible {
     }
 }
 
+public struct MediaUploadEvent: CustomStringConvertible {
+    public let values: [String: Any]
+
+    public init(values: [String: Any]) {
+        self.values = values
+    }
+
+    public var type: String {
+        stringValue(values, "type") ?? ""
+    }
+
+    public var requestId: String {
+        stringValue(values, "requestId") ?? ""
+    }
+
+    public var mediaUrl: String? {
+        stringValue(values, "mediaUrl")
+    }
+
+    public var errorMessage: String? {
+        stringValue(values, "errorMessage")
+    }
+
+    public var mediaType: Int? {
+        intValue(values["mediaType"])
+    }
+
+    public var timestamp: Int {
+        intValue(values["timestamp"]) ?? Int(Date().timeIntervalSince1970 * 1000)
+    }
+
+    public var isSuccess: Bool {
+        type == "media_success"
+    }
+
+    public var isVideo: Bool {
+        mediaType == 2
+    }
+
+    public var description: String {
+        "MediaUploadEvent(requestId: \(requestId), type: \(type), mediaType: \(mediaType ?? -1))"
+    }
+}
+
 public enum PhotoResponse: CustomStringConvertible, Equatable {
     public enum State: String {
         case success

package/ios/Source/events/BluetoothEvents.swift

@@ -244,6 +244,7 @@ public enum BluetoothEvent: CustomStringConvertible {
     case photoResponse(PhotoResponseEvent)
     case photoStatus(PhotoStatusEvent)
     case videoRecordingStatus(VideoRecordingStatusEvent)
+    case mediaUpload(MediaUploadEvent)
     case rgbLedControlResponse(RgbLedControlResponseEvent)
     case streamStatus(StreamStatusEvent)
     case keepAliveAck(KeepAliveAckEvent)
@@ -277,6 +278,8 @@ public enum BluetoothEvent: CustomStringConvertible {
             event.description
         case let .videoRecordingStatus(event):
             event.description
+        case let .mediaUpload(event):
+            event.description
         case let .rgbLedControlResponse(event):
             event.description
         case let .streamStatus(event):

package/ios/Source/internal/BluetoothAvailability.swift

@@ -6,6 +6,7 @@ final class BluetoothAvailability: NSObject, CBCentralManagerDelegate {
 
     private var centralManager: CBCentralManager?
     private var state: CBManagerState = .unknown
+    private var listeners: [UUID: (CBManagerState) -> Void] = [:]
 
     override private init() {
         super.init()
@@ -19,6 +20,25 @@ final class BluetoothAvailability: NSObject, CBCentralManagerDelegate {
 
     func centralManagerDidUpdateState(_ central: CBCentralManager) {
         state = central.state
+        for listener in Array(listeners.values) {
+            listener(state)
+        }
+    }
+
+    @discardableResult
+    func addStateListener(_ listener: @escaping (CBManagerState) -> Void) -> UUID {
+        // `listeners` is unsynchronized; it is only safe because the central
+        // manager queue is `.main` and all callers are main-thread bound.
+        dispatchPrecondition(condition: .onQueue(.main))
+        let id = UUID()
+        listeners[id] = listener
+        listener(state)
+        return id
+    }
+
+    func removeStateListener(_ id: UUID) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        listeners[id] = nil
     }
 
     func requirePoweredOn(operation: String) throws {

package/ios/Source/internal/BluetoothSdkAnalytics.swift

@@ -0,0 +1,160 @@
+import Foundation
+
+public struct BluetoothSdkAnalyticsConfiguration {
+    public static let disabled = BluetoothSdkAnalyticsConfiguration(enabled: false)
+
+    public let enabled: Bool
+    let surface: String
+
+    public init(enabled: Bool = true) {
+        self.enabled = enabled
+        surface = "ios"
+    }
+
+    var isReady: Bool {
+        enabled
+    }
+
+    func withSurface(_ surface: String) -> BluetoothSdkAnalyticsConfiguration {
+        BluetoothSdkAnalyticsConfiguration(
+            enabled: enabled,
+            surface: surface
+        )
+    }
+
+    private init(
+        enabled: Bool,
+        surface: String
+    ) {
+        self.enabled = enabled
+        self.surface = surface
+    }
+}
+
+final class BluetoothSdkAnalytics {
+    private static let defaultPostHogApiKey = "phc_FCweXVAxVgU7wZK4Fk3okOx4RmyNqVHJf62YpZSfJt5"
+    private static let defaultPostHogHost = "https://us.i.posthog.com"
+    private let stateQueue = DispatchQueue(label: "com.mentra.bluetoothsdk.analytics.state")
+    private let transportQueue = DispatchQueue(label: "com.mentra.bluetoothsdk.analytics.transport")
+    private let configuration: BluetoothSdkAnalyticsConfiguration
+    private var startedCaptured = false
+    private var lastConnected = false
+
+    init(configuration: BluetoothSdkAnalyticsConfiguration) {
+        self.configuration = configuration.resolvedForApp()
+    }
+
+    func initializeGlassesStatus(_ status: GlassesStatus) {
+        stateQueue.sync {
+            lastConnected = status.analyticsConnected
+        }
+    }
+
+    func captureStarted() {
+        stateQueue.sync {
+            captureStartedLocked()
+        }
+    }
+
+    private func captureStartedLocked() {
+        guard !startedCaptured, configuration.isReady else { return }
+        startedCaptured = true
+        capture(
+            event: "bluetooth_sdk_started",
+            properties: ["event_kind": "sdk_started"],
+            configuration: configuration
+        )
+    }
+
+    func observeGlassesStatus(_ status: GlassesStatus) {
+        stateQueue.sync {
+            let isConnected = status.analyticsConnected
+            let wasConnected = lastConnected
+            lastConnected = isConnected
+            guard configuration.isReady else { return }
+            if isConnected, !wasConnected {
+                var properties: [String: Any] = [
+                    "event_kind": "glasses_connected",
+                    "fully_booted": status.fullyBooted,
+                ]
+                if !status.deviceModel.isEmpty {
+                    properties["glasses_model"] = status.deviceModel
+                }
+                capture(event: "bluetooth_sdk_glasses_connected", properties: properties, configuration: configuration)
+            }
+        }
+    }
+
+    private func capture(
+        event: String,
+        properties: [String: Any],
+        configuration activeConfiguration: BluetoothSdkAnalyticsConfiguration
+    ) {
+        guard activeConfiguration.isReady else { return }
+
+        transportQueue.async {
+            let payload: [String: Any] = [
+                "api_key": Self.defaultPostHogApiKey,
+                "event": event,
+                "distinct_id": self.distinctId(),
+                "properties": self.baseProperties(configuration: activeConfiguration).merging(properties) { _, new in new },
+            ]
+            guard let body = try? JSONSerialization.data(withJSONObject: payload) else { return }
+            guard let captureURL = self.captureURL() else { return }
+            var request = URLRequest(url: captureURL)
+            request.httpMethod = "POST"
+            request.timeoutInterval = 4
+            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+            request.httpBody = body
+            URLSession.shared.dataTask(with: request).resume()
+        }
+    }
+
+    private func baseProperties(configuration: BluetoothSdkAnalyticsConfiguration) -> [String: Any] {
+        var properties: [String: Any] = [
+            "$process_person_profile": false,
+            "event_source": "mentra_bluetooth_sdk",
+            "sdk_platform": "ios",
+            "sdk_surface": configuration.surface,
+            "app_bundle_identifier": Bundle.main.bundleIdentifier ?? "",
+            "os_platform": "ios",
+            "os_version": ProcessInfo.processInfo.operatingSystemVersionString,
+        ]
+        if let sdkVersion = BluetoothSdkDefaults.sdkVersion {
+            properties["sdk_version"] = sdkVersion
+        }
+        return properties
+    }
+
+    private func distinctId() -> String {
+        let key = "mentra_bluetooth_sdk_analytics_distinct_id"
+        if let existing = UserDefaults.standard.string(forKey: key), !existing.isEmpty {
+            return existing
+        }
+        let generated = "mentra-bt-sdk-\(UUID().uuidString)"
+        UserDefaults.standard.set(generated, forKey: key)
+        return generated
+    }
+
+    private func captureURL() -> URL? {
+        let normalized = Self.defaultPostHogHost.trimmingCharacters(in: .whitespacesAndNewlines).trimmingCharacters(in: CharacterSet(charactersIn: "/"))
+        return URL(string: "\(normalized)/i/v0/e/")
+    }
+}
+
+private extension GlassesStatus {
+    var analyticsConnected: Bool {
+        connectionState.isConnected || connected || fullyBooted
+    }
+}
+
+private extension BluetoothSdkAnalyticsConfiguration {
+    func resolvedForApp() -> BluetoothSdkAnalyticsConfiguration {
+        let disabledByApp = Bundle.main.object(forInfoDictionaryKey: "MentraBluetoothSdkAnalyticsDisabled") as? Bool == true
+
+        return BluetoothSdkAnalyticsConfiguration(
+            enabled: enabled && !disabledByApp,
+            surface: surface
+        )
+    }
+}

package/ios/Source/sgcs/MentraLive.swift

@@ -2171,6 +2171,9 @@ class MentraLive: NSObject, SGCManager {
         case "video_recording_status":
             emitVideoRecordingStatus(json)
 
+        case "media_success", "media_error":
+            Bridge.sendMediaUploadEvent(type: type, values: json)
+
         case "photo_status":
             emitPhotoStatus(json)
 
@@ -5269,7 +5272,8 @@ extension MentraLive {
 
     func startVideoRecording(requestId: String, save: Bool, flash: Bool, sound: Bool) {
         startVideoRecording(
-            requestId: requestId, save: save, flash: flash, sound: sound, width: 0, height: 0, fps: 0
+            requestId: requestId, save: save, flash: flash, sound: sound, width: 0, height: 0, fps: 0,
+            maxRecordingTimeMinutes: 0
         )
     }
 
@@ -5280,10 +5284,11 @@ extension MentraLive {
     }
 
     func startVideoRecording(
-        requestId: String, save: Bool, flash: Bool, sound: Bool, width: Int, height: Int, fps: Int
+        requestId: String, save: Bool, flash: Bool, sound: Bool, width: Int, height: Int, fps: Int,
+        maxRecordingTimeMinutes: Int
     ) {
         Bridge.log(
-            "Starting video recording on glasses: requestId=\(requestId), save=\(save), flash=\(flash), sound=\(sound), resolution=\(width)x\(height)@\(fps)fps"
+            "Starting video recording on glasses: requestId=\(requestId), save=\(save), flash=\(flash), sound=\(sound), resolution=\(width)x\(height)@\(fps)fps, maxRecordingTimeMinutes=\(maxRecordingTimeMinutes)"
         )
 
         guard connectionState == ConnTypes.CONNECTED else {
@@ -5299,6 +5304,11 @@ extension MentraLive {
             "sound": sound,
         ]
 
+        // Auto-stop timer; only sent when set (> 0). 0 = record until stopped.
+        if maxRecordingTimeMinutes > 0 {
+            json["maxRecordingTimeMinutes"] = maxRecordingTimeMinutes
+        }
+
         // Add video settings when any field is overridden. Each field is sent
         // only when > 0; the glasses merge the missing fields onto their saved
         // button-video defaults, so a partial override (e.g. fps-only) still
@@ -5314,17 +5324,31 @@ extension MentraLive {
     }
 
     func stopVideoRecording(requestId: String) {
-        Bridge.log("Stopping video recording on glasses: requestId=\(requestId)")
+        stopVideoRecording(requestId: requestId, webhookUrl: nil, authToken: nil)
+    }
+
+    func stopVideoRecording(requestId: String, webhookUrl: String?, authToken: String?) {
+        Bridge.log(
+            "Stopping video recording on glasses: requestId=\(requestId), webhook=\((webhookUrl?.isEmpty ?? true) ? "none" : "set")"
+        )
 
         guard connectionState == ConnTypes.CONNECTED else {
             Bridge.log("Cannot stop video recording - not connected")
             return
         }
 
-        let json: [String: Any] = [
+        var json: [String: Any] = [
             "type": "stop_video_recording",
             "requestId": requestId,
         ]
+        // Webhook upload target, supplied at stop so the token is fresh.
+        // Only sent when present; empty webhook = keep video on device.
+        if let webhookUrl, !webhookUrl.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            json["webhookUrl"] = webhookUrl
+        }
+        if let authToken, !authToken.isEmpty {
+            json["authToken"] = authToken
+        }
         sendJson(json)
     }
 }