Использовать проецируемый контекст для доступа к оборудованию на аудио- и видеоочках

Поддерживаемые XR-устройства
Это руководство поможет вам создавать приложения для таких XR-устройств.
Аудио- и
видеоочки

После того как вы запросите и получите необходимые разрешения, ваше приложение сможет получить доступ к аппаратным компонентам аудио- или видеоочков. Чтобы получить доступ к аппаратным компонентам очков, а не телефона, нужно использовать проецируемый контекст.

Получить прогнозируемый контекст можно двумя основными способами в зависимости от того, где выполняется ваш код:

Получение контекста, если код выполняется в спроецированном действии

Если код приложения выполняется в рамках проецируемого действия, то контекст действия уже является проецируемым. В этом случае вызовы, сделанные в рамках этого действия, уже могут получить доступ к оборудованию очков.

Получение прогнозируемого контекста для кода, выполняемого в компоненте приложения "Телефон"

Если части приложения, не связанной с проецируемым действием (например, действию или сервису на телефоне), требуется доступ к аппаратным компонентам очков, она должна явным образом получить проецируемый контекст. Для этого используйте метод createProjectedDeviceContext:

@RequiresApi(Build.VERSION_CODES.BAKLAVA)
@OptIn(ExperimentalProjectedApi::class, ExperimentalCoroutinesApi::class)
fun monitorProjectedDeviceConnectivity(
    context: Context,
    onConnected: suspend (projectedContext: Context) -> (() -> Unit)?
) {
    val lifecycleScope = (context as? LifecycleOwner)?.lifecycleScope
        ?: CoroutineScope(Dispatchers.Main + SupervisorJob())

    lifecycleScope.launch {
        var cleanupAction: (() -> Unit)? = null

        try {
            // Before creating a projected context, verify that the projected device
            // is connected to the host device (phone).
            // While this flow collects true, the active projected context remains valid.
            ProjectedContext.isProjectedDeviceConnected(context, coroutineContext)
                .distinctUntilChanged()
                .collectLatest { isConnected ->
                    // Clean up any previous session resources prior to state transitions.
                    cleanupAction?.invoke()
                    cleanupAction = null

                    if (!isConnected) {
                        Log.i(TAG, "Projected device disconnected. Cleaning up hardware resources...")
                        return@collectLatest
                    }

                    // Inside a phone Activity or Service, create a projected context.
                    // Note: If you are already inside a projected Activity, the default context
                    // is already a projected context.
                    val projectedContext = runCatching {
                        ProjectedContext.createProjectedDeviceContext(context)
                    }.onFailure { e ->
                        Log.e(TAG, "Failed to create projected context", e)
                    }.getOrNull() ?: return@collectLatest

                    // Use the new, valid `projectedContext` to initialize system services (e.g., CameraManager).
                    Log.i(TAG, "Projected device connected. Initializing hardware...")
                    cleanupAction = onConnected(projectedContext)
                }
        } finally {
            // Guarantee final resource cleanup on Activity destruction or scope cancellation.
            cleanupAction?.invoke()
            cleanupAction = null
        }
    }
}

Проверка действительности

Оберните вызов createProjectedDeviceContext в ProjectedContext.isProjectedDeviceConnected. Хотя этот метод возвращает true, проецируемый контекст остается действительным для подключенного устройства, а действия или сервис приложения телефона (например, CameraManager) могут получить доступ к аппаратным средствам очков.

Очистка при отключении

Проецируемый контекст привязан к жизненному циклу подключенного устройства, поэтому он уничтожается при отключении устройства. Когда устройство отключается, ProjectedContext.isProjectedDeviceConnected возвращает false. Приложение должно отслеживать это изменение и очищать все системные службы (например, CameraManager) или ресурсы, созданные с использованием этого контекста.

Повторная инициализация при повторном подключении

Когда очки снова подключатся, приложение сможет получить другой экземпляр проецируемого контекста с помощью createProjectedDeviceContext, а затем повторно инициализировать системные сервисы или ресурсы, используя новый проецируемый контекст.

Записывать аудио с помощью микрофона очков

Вы можете записывать аудио с очков, используя профиль Bluetooth Hands-Free (HFP). В этом режиме очки подключаются к телефону с помощью стандартных профилей Headset и Advanced Audio Distribution Profile (A2DP) и работают как обычное периферийное устройство Bluetooth. Если ваше приложение уже поддерживает стандартную запись по Bluetooth, вы можете использовать этот метод для записи аудио с очков без дополнительной разработки.

Запись аудио с помощью Bluetooth HFP

Чтобы записать аудио с помощью Bluetooth HFP, сначала запросите необходимые динамические разрешения, а затем запишите аудио с помощью AudioManager API, как описано в следующих разделах.

Запросить разрешения

Как и в случае с любым стандартным аудиоустройством Bluetooth, разрешения RECORD_AUDIO, BLUETOOTH_CONNECT и другие связанные разрешения контролируются телефоном, а не подключенным устройством (например, аудио- или видеоочками).

Чтобы запросить разрешения, выполните следующие действия:

  1. Объявите следующие разрешения в файле манифеста приложения:

  2. Запросите разрешения RECORD_AUDIO и BLUETOOTH_CONNECT во время выполнения, используя стандартный процесс запроса разрешений Android.

Используйте AudioManager для маршрутизации аудио

После того как пользователь предоставит приложению необходимые динамические разрешения, используйте API AudioManager, чтобы задать устройство связи TYPE_BLUETOOTH_SCO для маршрутизации аудио через Bluetooth HFP. Это указывает системе, что аудио нужно получать с периферийного устройства Bluetooth.

val audioManager = context.getSystemService(AudioManager::class.java) ?: return
val hfpDevice = audioManager.availableCommunicationDevices
    .firstOrNull { it.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO } ?: return

// HFP input is limited to 16 kHz, with mono or stereo channel configurations.
val sampleRate = 16_000
val channelMask = AudioFormat.CHANNEL_IN_MONO
val encoding = AudioFormat.ENCODING_PCM_16BIT

// Use a small multiple of the minimum buffer size to keep chunks short for low latency.
val minBufferSize = AudioRecord.getMinBufferSize(sampleRate, channelMask, encoding)
if (minBufferSize <= 0) return

val audioRecord = AudioRecord.Builder()
    .setAudioSource(MediaRecorder.AudioSource.VOICE_COMMUNICATION)
    .setAudioFormat(
        AudioFormat.Builder()
            .setSampleRate(sampleRate)
            .setChannelMask(channelMask)
            .setEncoding(encoding)
            .build()
    )
    .setBufferSizeInBytes(minBufferSize * 2)
    .build()

try {
    // Route voice communication audio through the Bluetooth device.
    if (!audioManager.setCommunicationDevice(hfpDevice)) return
    audioRecord.startRecording()
    // Read audio with audioRecord.read() on a background thread.
} finally {
    // Stop and release when done.
    if (audioRecord.recordingState == AudioRecord.RECORDSTATE_RECORDING) audioRecord.stop()
    audioRecord.release()
    audioManager.clearCommunicationDevice()
}

Сделайте снимок с помощью камеры очков.

Чтобы сделать снимок с помощью камеры очков, отслеживайте подключение к monitorProjectedDeviceConnectivity, чтобы получить контекст проецируемого устройства, создайте изолированный LifecycleCameraProvider, привязанный к этому контексту, отслеживайте наличие камеры и привяжите вариант использования ImageCapture CameraX.

Сначала отслеживайте подключение устройства и инициализируйте LifecycleCameraProvider.createInstance с одним потоком CameraXConfig.Builder:

@OptIn(ExperimentalCameraProviderConfiguration::class)
@RequiresApi(Build.VERSION_CODES.BAKLAVA)
@SuppressLint("RestrictedApi")
fun setUpGlassesCamera(activity: ComponentActivity) {
    monitorProjectedDeviceConnectivity(activity) { projectedContext ->
        val cameraManager = projectedContext.getSystemService(CameraManager::class.java)
            ?: run {
                Log.e(TAG, "CameraManager not available on projected context")
                return@monitorProjectedDeviceConnectivity null
            }

        // `setRepeatingStreamForced()` is currently internal but will be public soon.
        val cameraConfig = CameraXConfig.Builder
            .fromConfig(Camera2Config.defaultConfig())
            .setRepeatingStreamForced(false)
            .build()

        val cameraProvider = try {
            // Acquire CameraX provider specifically bound to the projected context.
            // If the device disconnects while suspending, collectLatest cancels this coroutine.
            LifecycleCameraProvider.createInstance(projectedContext, cameraConfig)
        } catch (e: IllegalStateException) {
            Log.e(TAG, "Failed to initialize projected camera services", e)
            return@monitorProjectedDeviceConnectivity null
        }

        // Set up the listener to react to camera availability changes asynchronously.
        val availabilityCallback = registerAvailabilityListener(
            cameraManager = cameraManager,
            cameraProvider = cameraProvider,
            executor = ContextCompat.getMainExecutor(activity),
            onCameraAvailable = { cameraId ->
                // Delegate camera selection, resolution querying, and use-case binding.
                bindGlassesImageCapture(cameraProvider, cameraId, activity)
            }
        )

        // Return a clean-up closure invoked automatically by monitorProjectedDeviceConnectivity
        // on disconnect, coroutine cancellation, or Activity destruction.
        return@monitorProjectedDeviceConnectivity {
            Log.i(TAG, "Projected camera setup scope ended. Tearing down resources...")
            try {
                cameraManager.unregisterAvailabilityCallback(availabilityCallback)
            } finally {
                cameraProvider.unbindAll()
            }
        }
    }
}

В CameraX 1.6.0 и более поздних версиях зарегистрируйте CameraPresenceListener с помощью addCameraPresenceListener, чтобы реагировать на добавление или удаление камеры очков.

@OptIn(ExperimentalCameraProviderConfiguration::class)
fun registerAvailabilityListener(
    cameraManager: CameraManager,
    cameraProvider: LifecycleCameraProvider,
    executor: Executor,
    onCameraAvailable: (cameraId: String) -> Unit
): CameraManager.AvailabilityCallback {
    val callback = object : CameraManager.AvailabilityCallback() {
        override fun onCameraAvailable(cameraId: String) {
            super.onCameraAvailable(cameraId)
            Log.i(TAG, "Glasses camera available (ID: $cameraId). Binding use case...")
            // Fires only after the OS finishes re-registering the glasses' camera.
            // Pass the fresh cameraId directly—never cache it, as it may change when recreated.
            onCameraAvailable(cameraId)
        }

        override fun onCameraUnavailable(cameraId: String) {
            super.onCameraUnavailable(cameraId)
            Log.i(TAG, "Glasses camera unavailable (ID: $cameraId). Releasing resources...")
            // Gracefully release the pipeline when the projected camera becomes unavailable.
            cameraProvider.unbindAll()
        }
    }

    cameraManager.registerAvailabilityCallback(executor, callback)
    return callback
}

Затем выберите камеру очков из availableCameraInfos с помощью CameraIdentifier, предоставленного прослушивателем, и привяжите ImageCapture:

/**
 * Selects the projected camera matching dynamic [cameraId] from
 * [LifecycleCameraProvider.availableCameraInfos], verifies availability, and binds an
 * [ImageCapture] use case targeting a 16:9 resolution to [lifecycleOwner].
 *
 * Note: Depending on your application's needs, [ImageCapture] can be swapped out for other
 * standard CameraX use cases:
 * - Use [ImageAnalysis] for real-time streaming workloads (e.g., OCR, AI vision, or VPS).
 * - Use [VideoCapture] for video recording pipelines.
 */
@OptIn(ExperimentalCamera2Interop::class, ExperimentalCameraProviderConfiguration::class)
fun bindGlassesImageCapture(
    cameraProvider: LifecycleCameraProvider,
    cameraId: String,
    lifecycleOwner: LifecycleOwner,
    preferredResolution: Size = Size(1920, 1080)
): ImageCapture? {
    return try {
        // Discover available cameras dynamically via `availableCameraInfos`
        // Narrow it down by the dynamic `cameraId` because the projected camera's ID may
        // change when recreated
        val cameraInfo = cameraProvider.availableCameraInfos.firstOrNull { info ->
            Camera2CameraInfo.from(info).cameraId == cameraId
        }

        // Pre-binding check: Verify the selected camera is registered and available on the device.
        // The projected camera may be unavailable (for example, if the user took off the glasses).
        if (cameraInfo == null) {
            Log.w(TAG, "Glasses camera (ID: $cameraId) is not currently available.")
            return null
        }
        val cameraSelector = cameraInfo.cameraSelector

        val resolutionSelector = ResolutionSelector.Builder()
            .setAspectRatioStrategy(AspectRatioStrategy.RATIO_16_9_FALLBACK_AUTO_STRATEGY)
            .setResolutionStrategy(
                ResolutionStrategy(
                    preferredResolution,
                    ResolutionStrategy.FALLBACK_RULE_CLOSEST_LOWER
                )
            )
            .build()

        // Initialize the ImageCapture use case.
        val imageCapture = ImageCapture.Builder()
            .setResolutionSelector(resolutionSelector)
            .build()

        // Unbind any previously bound use cases before rebinding to the lifecycle owner.
        cameraProvider.unbindAll()

        // Bind the configured use case. You can swap `imageCapture` out for an `ImageAnalysis`
        // (e.g., from `setupCameraStreamingFps`) or `VideoCapture` instance here to match your use case.
        // `bindToLifecycle()` can throw IllegalArgumentException if use cases
        // are incompatible, or IllegalStateException if the LifecycleOwner is destroyed.
        cameraProvider.bindToLifecycle(
            lifecycleOwner,
            cameraSelector,
            imageCapture
        )
        Log.i(TAG, "ImageCapture successfully bound for camera ID $cameraId")
        imageCapture
    } catch (exc: CameraInfoUnavailableException) {
        Log.e(TAG, "Unable to access camera info for ID $cameraId", exc)
        null
    } catch (exc: IllegalArgumentException) {
        Log.e(TAG, "Invalid camera configuration or use case combination for ID $cameraId", exc)
        null
    } catch (exc: IllegalStateException) {
        Log.e(TAG, "Camera is already bound to another lifecycle or closed", exc)
        null
    }
}

Основные сведения о коде

  • Для каждого устройства LifecycleCameraProvider. Используйте LifecycleCameraProvider.createInstance, чтобы создать изолированного поставщика камеры, ограниченного активным контекстом проекции. Поскольку deviceId проецируемого контекста может меняться при отключении и повторном подключении очков, пока процесс приложения остается активным, создание поставщика для каждого устройства гарантирует, что CameraX привязывается к активному подключенному устройству.
  • Отслеживайте наличие камеры. В CameraX 1.6.0 и более поздних версиях зарегистрируйте CameraPresenceListener с помощью cameraProvider.addCameraPresenceListener вместо того, чтобы открывать камеру сразу после подключения очков. Асинхронная настройка между очками и хостом должна завершиться до того, как ОС закончит воссоздание камеры очков. Камера очков также может динамически исчезать во время подключения (например, во время снижения температуры).
    • Добавление камеры (onCamerasAdded). Срабатывает после того, как в availableCameraInfos добавляется камера. Это позволяет избежать состояния гонки во время настройки.
    • Удаление камеры (onCamerasRemoved). Отслеживает наличие камеры, а не ее состояние. Отмена привязки освобождает ресурсы, только когда камера очков удалена, а не когда ваше приложение открывает камеру.
  • Очистка при отключении. Замыкание очистки, возвращенное в monitorProjectedDeviceConnectivity, вызывает removeCameraPresenceListener и unbindAll(), когда очки отключаются или действие уничтожается.
  • Динамический выбор камеры. Сопоставляет CameraIdentifier, переданный в onCamerasAdded, с availableCameraInfos, используя isOf, чтобы динамически выбрать камеру очков.
  • Специальное разрешение. Создает ResolutionSelector с таргетингом на примерное соотношение сторон 16:9 и выбранное вами разрешение (с возвратом к ближайшему меньшему поддерживаемому размеру) для ImageCapture. Поддерживаемые соотношения сторон и разрешения зависят от устройства и режима (например, 4:3 и 16:9). Чтобы узнать точные размеры, отправьте запрос StreamConfigurationMap.
  • Привязка к жизненному циклу. Привязывает ImageCapture к LifecycleOwner, автоматически управляя открытием и закрытием камеры в соответствии с жизненным циклом объекта activity.
  • Настройка для оборудования с одним потоком. Конвейер камеры очков ограничен одним активным потоком за раз. Если привязать только ImageCapture, CameraX по умолчанию подключит внутренний повторяющийся поток (MeteringRepeating) для фокусировки и замера, что приведет к остановке конвейера с одним потоком. Передайте setRepeatingStreamForced(false) в CameraXConfig, который передается в LifecycleCameraProvider.createInstance, чтобы ImageCapture мог выполнить привязку без потока предварительного просмотра.

После настройки камеры очков вы можете сделать снимок с помощью класса ImageCapture библиотеки CameraX. Информацию о том, как использовать takePicture для съемки фотографий, можно найти в документации CameraX.

Записывайте трансляцию с помощью камеры очков

Чтобы записывать потоки, а не изображения, замените компонент ImageCapture из примера захвата изображения на компонент VideoCapture или ImageAnalysis и измените логику захвата.

Дополнительную информацию об этих API и о том, как их использовать, можно найти в документации по записи видео с помощью CameraX и анализу изображений с помощью CameraX.

Выберите разрешение и частоту кадров

Чтобы узнать, какие разрешения и соответствующие им максимальные частоты кадров поддерживаются устройством, отправьте запрос. В таблице ниже приведены примеры значений, которые вы можете увидеть в зависимости от того, как используется ваше приложение. Чтобы экономить заряд батареи и уменьшить нагрев очков, выберите минимальные разрешение и частоту кадров, которые подходят для ваших целей.

Пример использования Разрешение Частота кадров
Распознавание текста (OCR) или окружающего мира 1920 x 1080 пикс. 1 кадр/с
Потоковая передача видео с ИИ (мультимодальные помощники) 1024 x 768 1 кадр/с
Локализация и визуальное позиционирование (VPS) 640 x 360 или 640 x 480 10 кадров/с
Видеовызовы 640 x 360 или 640 x 480 24 кадра/с

Запрос максимальной частоты кадров для каждого разрешения

CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES сообщает общие границы частоты кадров устройства, которые могут быть выше, чем частота потоковой передачи, поддерживаемая данным разрешением. Чтобы получить фактический максимум для каждого разрешения на аудио- и видеоочках, прочитайте минимальную длительность кадра и преобразуйте ее в кадры в секунду с помощью StreamConfigurationMap.getOutputMinFrameDuration(format, size):

@androidx.annotation.OptIn(ExperimentalCamera2Interop::class)
fun getMaxFpsBySize(cameraInfo: CameraInfo, format: Int): Map<Size, Int> {
    val map = Camera2CameraInfo.from(cameraInfo).getCameraCharacteristic(
        CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP
    ) ?: return emptyMap()

    return map.getOutputSizes(format).associateWith { size ->
        val minFrameDurationNs = map.getOutputMinFrameDuration(format, size)
        if (minFrameDurationNs > 0) (1_000_000_000L / minFrameDurationNs).toInt() else 0
    }
}

Затем используйте это значение, чтобы рассчитать minFps и maxFps границы для целевого диапазона частоты кадров. Ограничьте нижнюю границу (minFps) максимальной частотой кадров для трансляции, рассчитанной на основе getOutputMinFrameDuration, и установите более высокую верхнюю границу (maxFps) в качестве окна догоняющего воспроизведения:

val maxFpsBySize = getMaxFpsBySize(cameraInfo, ImageFormat.YUV_420_888)
val maxSupportedFps = maxFpsBySize[size] ?: return ImageAnalysis.Builder().build()

// minFps is the target streaming frame rate and should be at most maxSupportedFps.
val minFps = minOf(desiredFps, maxSupportedFps)
// Set the upper bound to 2x minFps so the stream can catch up if frames are delayed.
val maxFps = minFps * 2

Основные сведения о коде

  • Выберите формат, который подходит для вашего случая. Для ImageAnalysis это YUV_420_888.
  • Для VideoCapture используйте перегрузки Class: getOutputSizes(MediaRecorder::class.java) и getOutputMinFrameDuration(MediaRecorder::class.java, size).
  • Укажите диапазон, в котором maxFps больше, чем minFps (например, minFps*2), а не задавайте для обеих границ одно и то же значение, например Range(minFps, minFps). Нижняя граница (minFps) задает целевую частоту кадров трансляции и должна быть не больше значения, рассчитанного на основе getOutputMinFrameDuration. Верхняя граница (maxFps) действует как окно догоняющего воспроизведения для задержанных кадров, чтобы предотвратить постоянную задержку. Например, [1,2] или [1,3] для потока с частотой 1 кадр/с и [24,30] или [24,48] для потока с частотой 24 кадра/с.

Как настроить частоту кадров

Чтобы настроить диапазон частоты кадров в зависимости от варианта использования CameraX, сделайте следующее:

// Create and return the ImageAnalysis builder with proper frame rate ranges
// ImageAnalysis: OCR, AI streaming, and VPS
val analysisBuilder = ImageAnalysis.Builder()
    .setResolutionSelector(resolutionSelector)

Camera2Interop.Extender(analysisBuilder)
    .setCaptureRequestOption(
        CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE,
        Range(minFps, maxFps)
    )
return analysisBuilder.build()

В этом примере показана настройка как для VideoCapture, так и для ImageAnalysis, но вы можете реализовать любые варианты использования, которые поддерживает ваше приложение.

Как работает поток

При работе с потоками захвата учитывайте следующее поведение системы:

  • Неподдерживаемые разрешения отклоняются. Если вы запрашиваете размер, которого нет в списке, Camera2 отклоняет конфигурацию до открытия потока.
  • Запрос частоты кадров выше максимальной. Если вы запрашиваете минимальную частоту кадров выше максимальной поддерживаемой для вашего разрешения, сеанс все равно открывается, но целевая частота кадров из очков ограничивается этим поддерживаемым максимумом, а верхняя граница продолжает действовать как ограничение частоты догоняющих кадров. Например, если запросить [30,60] при разрешении 640 x 480, целевая частота кадров будет ограничена до 24 кадров/с (как при [24,60]).
  • Троттлинг. Когда очки нагреваются, частота кадров снижается, но разрешение остается прежним. Разработайте приложение так, чтобы оно могло работать с более низкой или неравномерной частотой кадров, например проверяя временные метки кадров, а не предполагая фиксированную частоту.

Как получить доступ к аппаратным компонентам телефона из транслируемого действия

Проецируемое действие также может получить доступ к аппаратным компонентам телефона (например, камере или микрофону) с помощью createHostDeviceContext(context), чтобы получить контекст хост-устройства (телефона):

@OptIn(ExperimentalProjectedApi::class)
fun getHostDeviceContext(context: Context): Context {
    // Obtain the host device (phone) context.
    // The `context` argument passed in can be any context (projected, host, Service, or App).
    return ProjectedContext.createHostDeviceContext(context)
}

При обращении к оборудованию или ресурсам, относящимся к хост-устройству (телефону), в гибридном приложении (приложении, которое работает и на мобильном устройстве, и на очках) необходимо явно выбрать правильный контекст, чтобы обеспечить доступ приложения к нужному оборудованию:

  • Используйте контекст Activity из телефона Activity или ProjectedContext.createHostDeviceContext, чтобы получить контекст телефона.
  • Не используйте getApplicationContext, поскольку контекст приложения может неправильно возвращать контекст очков, если последним запущенным компонентом было проецируемое действие.