Usar um contexto projetado para acessar hardware em óculos de áudio e óculos de exibição

Dispositivos XR relevantes
Estas orientações ajudam você a criar experiências para esses tipos de dispositivos XR.
Óculos com áudio e
tela

Depois de solicitar e receber as permissões necessárias, seu app poderá acessar o hardware nos óculos com áudio ou com tela. Para acessar o hardware dos óculos (em vez do hardware do smartphone), use um contexto projetado.

Há duas maneiras principais de conseguir um contexto projetado, dependendo de onde o código está sendo executado:

Receber um contexto projetado se o código estiver sendo executado em uma atividade projetada

Se o código do app estiver sendo executado na atividade projetada, o contexto da atividade já será um contexto projetado. Nesse cenário, as chamadas feitas nessa atividade já podem acessar o hardware dos óculos.

Receber um contexto projetado para o código em execução em um componente de app Telefone

Se uma parte do app fora da atividade projetada (como uma atividade de smartphone ou um serviço) precisar acessar o hardware dos óculos, ela precisará receber explicitamente um contexto projetado. Para fazer isso, use o método 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
        }
    }
}

Verificar a validade

Una a chamada createProjectedDeviceContext ao ProjectedContext.isProjectedDeviceConnected. Enquanto esse método retornar true, o contexto projetado vai permanecer válido para o dispositivo conectado, e a atividade ou o serviço do app para smartphone (como um CameraManager) poderá acessar o hardware dos óculos.

Limpar ao desconectar

O contexto projetado está vinculado ao ciclo de vida do dispositivo conectado, então ele é destruído quando o dispositivo se desconecta. Quando o dispositivo se desconecta, ProjectedContext.isProjectedDeviceConnected retorna false. O app precisa detectar essa mudança e limpar todos os serviços do sistema (como um CameraManager) ou recursos que o app criou usando esse contexto projetado.

Reinicializar ao reconectar

Quando os óculos se reconectarem, o app poderá receber outra instância de contexto projetado usando createProjectedDeviceContext e, em seguida, reinicializar todos os serviços ou recursos do sistema usando o novo contexto projetado.

Gravar áudio com o microfone dos óculos

É possível gravar áudio dos óculos usando o perfil de viva-voz (HFP, na sigla em inglês) do Bluetooth. Nesse modo, os óculos se conectam ao smartphone usando os perfis padrão de fone de ouvido e perfil de distribuição de áudio avançado (A2DP), funcionando como um periférico Bluetooth comum. Se o app já foi projetado para gravação Bluetooth padrão, use esse método para gravar áudio dos óculos sem nenhum desenvolvimento adicional.

Gravar áudio usando o HFP do Bluetooth

Para gravar áudio usando o HFP do Bluetooth, primeiro solicite as permissões de execução necessárias e, em seguida, grave o áudio usando a API AudioManager, conforme descrito nas seções a seguir.

Solicitar permissões

Como em qualquer dispositivo de áudio Bluetooth padrão, as permissões RECORD_AUDIO, BLUETOOTH_CONNECT e outras relacionadas são controladas pelo smartphone, e não pelo dispositivo conectado (como óculos com áudio ou óculos com tela).

Siga estas etapas para solicitar as permissões:

  1. Declare as seguintes permissões no arquivo de manifesto do app:

  2. Solicite as permissões RECORD_AUDIO e BLUETOOTH_CONNECT no momento da execução usando o fluxo de permissões padrão do Android.

Usar o AudioManager para rotear áudio

Depois que o usuário conceder ao app as permissões de execução necessárias, use a API AudioManager para definir o dispositivo de comunicação como TYPE_BLUETOOTH_SCO para rotear o áudio pelo Bluetooth HFP. Isso direciona o sistema para recuperar o áudio do periférico 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()
}

Capturar uma imagem com a câmera dos óculos

Para capturar uma imagem com a câmera dos óculos, monitore a conectividade com monitorProjectedDeviceConnectivity para receber um contexto de dispositivo projetado, crie um LifecycleCameraProvider isolado vinculado a esse contexto, detecte a presença da câmera e vincule o caso de uso ImageCapture do CameraX.

Primeiro, monitore a conectividade do dispositivo e inicialize LifecycleCameraProvider.createInstance com um CameraXConfig.Builder de stream único:

@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()
            }
        }
    }
}

No CameraX 1.6.0 e versões mais recentes, registre um CameraPresenceListener usando addCameraPresenceListener para reagir quando a câmera dos óculos for adicionada ou removida:

@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
}

Em seguida, selecione a câmera dos óculos em availableCameraInfos usando o CameraIdentifier fornecido pelo listener e vincule 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
    }
}

Pontos principais sobre o código

  • Por dispositivo LifecycleCameraProvider: use LifecycleCameraProvider.createInstance para criar um provedor de câmera isolado com escopo para o contexto projetado ativo. Como o deviceId do contexto projetado pode mudar quando os óculos se desconectam e se reconectam enquanto o processo do app permanece ativo, a criação de um provedor por dispositivo garante que o CameraX se vincule ao dispositivo conectado ativo.
  • Detectar a presença da câmera: no CameraX 1.6.0 e versões mais recentes, registre um CameraPresenceListener usando cameraProvider.addCameraPresenceListener em vez de abrir a câmera imediatamente quando os óculos se conectarem. A configuração assíncrona entre os óculos e o host precisa ser concluída antes que o SO termine de recriar a câmera dos óculos, que também pode desaparecer dinamicamente enquanto estiver conectada (como durante a mitigação térmica).
    • Adição de câmera (onCamerasAdded): é acionado depois que availableCameraInfos é atualizado com a câmera adicionada, evitando concorrências de tempo durante a configuração.
    • Remoção da câmera (onCamerasRemoved): rastreia a presença da câmera em vez do estado em uso. Assim, a desvinculação libera recursos apenas quando a câmera dos óculos é removida, em vez de reagir quando seu próprio app abre a câmera.
  • Limpeza ao desconectar: o encerramento de limpeza retornado para monitorProjectedDeviceConnectivity chama removeCameraPresenceListener e unbindAll() quando os óculos são desconectados ou a atividade é destruída.
  • Seleção dinâmica de câmera: compara o CameraIdentifier transmitido para onCamerasAdded com availableCameraInfos usando isOf para selecionar a câmera dos óculos de forma dinâmica.
  • Resolução personalizada: cria um ResolutionSelector que segmenta um exemplo de proporção de 16:9 e sua resolução preferida (voltando para o tamanho mais próximo com suporte) para ImageCapture. As proporções e resoluções compatíveis variam de acordo com os dispositivos e modos de óculos (como 4:3 e 16:9). Portanto, consulte StreamConfigurationMap se precisar verificar os tamanhos exatos compatíveis.
  • Vinculação do ciclo de vida: vincula ImageCapture ao LifecycleOwner, gerenciando automaticamente as transições de abertura e fechamento da câmera com o ciclo de vida da atividade.
  • Configuração para hardware de stream único: o pipeline da câmera dos óculos é limitado a um único stream ativo por vez. Quando ImageCapture é vinculado sozinho, o CameraX anexa um stream de repetição interno (MeteringRepeating) para foco e medição por padrão, o que faz com que o pipeline de stream único seja interrompido. Transmita setRepeatingStreamForced(false) no CameraXConfig transmitido para LifecycleCameraProvider.createInstance para que ImageCapture possa se vincular sem um stream de visualização.

Depois que a câmera dos óculos estiver configurada, você poderá capturar uma imagem com a classe ImageCapture do CameraX. Consulte a documentação do CameraX para saber como usar takePicture para capturar uma imagem.

Capturar um stream com a câmera dos óculos

Para capturar streams em vez de uma imagem, substitua o componente ImageCapture do exemplo de captura de imagem pelos componentes VideoCapture ou ImageAnalysis e mude a lógica de captura.

Para mais informações sobre essas APIs e como usá-las, consulte a documentação sobre captura de vídeo da CameraX e análise de imagens da CameraX.

Escolha uma resolução e um frame rate

Consulte o dispositivo para encontrar as resoluções compatíveis e as taxas de frames máximas correspondentes. A tabela a seguir lista exemplos de valores que podem aparecer, dependendo do caso de uso do app. Para economizar bateria e reduzir o calor nos óculos, escolha a menor resolução e frame rate que funcionem para seu caso de uso.

Caso de uso Resolução Frame rate
Reconhecimento de texto (OCR) ou detecção de mundo 1920 x 1080 1 QPS
Streaming de vídeo de IA (assistentes multimodais) 1.024 x 768 1 QPS
Localização e posicionamento visual (VPS) 640 x 360 ou 640 x 480 10 QPS
Videochamadas 640 x 360 ou 640 x 480 24 QPS

Consultar o frame rate máximo para cada resolução

CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES informa os limites gerais de frame rate do dispositivo, que podem ser maiores do que a taxa de streaming que uma determinada resolução aceita. Para conseguir o máximo real de cada resolução em óculos de áudio e tela, leia a duração mínima do frame e converta-a em QPS com 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
    }
}

Em seguida, use esse valor para calcular os limites minFps e maxFps do intervalo de frame rate desejado. Limite o limite inferior (minFps) na taxa de frames de streaming máxima da resolução calculada com base em getOutputMinFrameDuration e defina um limite superior mais alto (maxFps) como uma janela de recuperação:

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

Pontos principais sobre o código

  • Use o formato que corresponde ao seu caso de uso. Para ImageAnalysis, isso é YUV_420_888.
  • Para VideoCapture, use as sobrecargas de Class: getOutputSizes(MediaRecorder::class.java) e getOutputMinFrameDuration(MediaRecorder::class.java, size).
  • Especifique um intervalo em que maxFps seja maior que minFps (como minFps*2) em vez de definir os dois limites com o mesmo valor, como Range(minFps, minFps). O limite inferior (minFps) define o frame rate de streaming desejado e precisa ser, no máximo, o valor calculado de getOutputMinFrameDuration, enquanto o limite superior (maxFps) atua como uma janela de compensação para frames atrasados para evitar latência persistente. Por exemplo, [1,2] ou [1,3] para um stream de 1 QPS e [24,30] ou [24,48] para um stream de 24 QPS.

Configurar o frame rate

Para configurar o intervalo de frame rate com base no caso de uso do 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()

Este exemplo mostra a configuração para VideoCapture e ImageAnalysis, mas é possível implementar qualquer caso de uso compatível com o app.

Entender como o stream se comporta

Lembre-se dos seguintes comportamentos do sistema ao trabalhar com streams de captura:

  • Resoluções incompatíveis são rejeitadas: se você solicitar um tamanho que não esteja na lista, a Camera2 vai rejeitar a configuração antes que o stream seja aberto.
  • Solicitação de frame rates acima do máximo: se você solicitar um frame rate mínimo acima do máximo aceito para sua resolução, a sessão ainda será aberta, mas o frame rate desejado dos óculos será limitado ao máximo aceito, enquanto o limite superior continuará atuando como o limite de taxa de compensação. Por exemplo, solicitar [30,60] a 640 x 480 limita o frame rate alvo a 24 QPS (comportando-se como [24,60]).
  • Limitação térmica: quando os óculos esquentam, o frame rate cai, mas a resolução permanece a mesma. Crie seu app para lidar com frame rates mais baixos ou irregulares, por exemplo, verificando os carimbos de data/hora dos frames em vez de assumir um frame rate fixo.

Acessar o hardware de um smartphone em uma atividade projetada

Uma atividade projetada também pode acessar o hardware do smartphone (como a câmera ou o microfone) usando createHostDeviceContext(context) para acessar o contexto do dispositivo host (smartphone):

@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)
}

Ao acessar hardware ou recursos específicos do dispositivo host (smartphone) em um app híbrido (um app que contém experiências para dispositivos móveis e óculos), é necessário selecionar explicitamente o contexto correto para garantir que o app possa acessar o hardware correto: