Używaj prognozowanego kontekstu, aby uzyskać dostęp do sprzętu na okularach audio i okularach z wyświetlaczem

Odpowiednie urządzenia z XR
Te wskazówki pomogą Ci tworzyć treści na te typy urządzeń z XR.
Okulary audio i z wyświetlaczem

Gdy poprosisz o niezbędne uprawnienia i je uzyskasz, Twoja aplikacja będzie mieć dostęp do hardware okularów audio lub okularów z wyświetlaczem. Kluczem do uzyskania dostępu do hardware okularów (zamiast hardware telefonu) jest użycie prognozowanego kontekstu.

Istnieją 2 główne sposoby uzyskiwania prognozowanego kontekstu, w zależności od tego, gdzie jest wykonywany kod:

Jak uzyskać prognozowany kontekst, jeśli kod jest uruchamiany w prognozowanej aktywności

Jeśli kod aplikacji jest uruchamiany w ramach prognozowanej aktywności, własny kontekst aktywności jest już prognozowanym kontekstem. W takim przypadku połączenia wykonywane w ramach tej aktywności mogą już korzystać z hardware okularów.

Jak uzyskać prognozowany kontekst dla kodu uruchamianego w komponencie aplikacji na telefon

Jeśli część aplikacji poza prognozowaną aktywnością (np. aktywność na telefonie lub usługa) musi mieć dostęp do hardware okularów, musi wyraźnie uzyskać prognozowany kontekst. Aby tak się stało, użyj metody createProjectedDeviceContext:

@RequiresApi(Build.VERSION_CODES.BAKLAVA)
@OptIn(ExperimentalProjectedApi::class, ExperimentalCoroutinesApi::class)
private fun monitorProjectedConnectivity(activity: ComponentActivity) {
    activity.lifecycleScope.launch {
        // Before creating a projected context, check to see if the projected device is connected.
        // While this method returns true, the projected context remains valid.
        ProjectedContext.isProjectedDeviceConnected(activity, coroutineContext)
            .collectLatest { isConnected ->
                if (isConnected) {
                    // From a phone Activity or Service, get a context for the audio and display glasses.
                    // Re-initialize on reconnect: Obtain another context instance.
                    val projectedContext = try {
                        ProjectedContext.createProjectedDeviceContext(activity)
                    } catch (e: IllegalStateException) {
                        Log.e(TAG, "Failed to create projected context", e)
                        return@collectLatest
                    }

                    // Use the projectedContext to initialize system services (e.g., CameraManager).
                    Log.i(TAG, "Projected device connected. Initializing hardware...")
                } else {
                    // The projected context is destroyed when the device disconnects.
                    // Clean up on disconnect: Listen for 'false' and release resources.
                    Log.i(TAG, "Projected device disconnected. Cleaning up hardware resources...")
                }
            }
    }
}

Sprawdzanie ważności

Umieść wywołanie createProjectedDeviceContext w ProjectedContext.isProjectedDeviceConnected. Chociaż ta metoda zwraca true, wyświetlany kontekst pozostaje ważny dla połączonego urządzenia, a aktywność lub usługa aplikacji na telefonie (np. CameraManager) może uzyskać dostęp do sprzętu okularów.

Czyszczenie po rozłączeniu

Wyświetlany kontekst jest powiązany z cyklem życia połączonego urządzenia, więc jest niszczony, gdy urządzenie się rozłączy. Gdy urządzenie się rozłączy, ProjectedContext.isProjectedDeviceConnected zwraca false. Aplikacja powinna nasłuchiwać tej zmiany i czyścić wszystkie usługi systemowe (takie jak CameraManager) lub zasoby utworzone przez aplikację przy użyciu tego kontekstu projekcji.

Ponownie zainicjuj po ponownym połączeniu

Gdy okulary ponownie się połączą, aplikacja może uzyskać kolejną instancję wyświetlanego kontekstu za pomocą metody createProjectedDeviceContext, a następnie ponownie zainicjować usługi systemowe lub zasoby przy użyciu nowego wyświetlanego kontekstu.

Nagrywanie dźwięku za pomocą mikrofonu okularów

Możesz nagrywać dźwięk z okularów za pomocą profilu głośnomówiącego Bluetooth (HFP). W tym trybie okulary łączą się z telefonem za pomocą standardowych profili zestawu słuchawkowego i A2DP (Advanced Audio Distribution Profile), działając jak typowe urządzenie peryferyjne Bluetooth. Jeśli Twoja aplikacja jest już zaprojektowana do nagrywania przez standardowy Bluetooth, możesz użyć tej metody do nagrywania dźwięku z okularów bez konieczności wprowadzania dodatkowych zmian.

Nagrywanie dźwięku za pomocą profilu Bluetooth HFP

Aby nagrywać dźwięk za pomocą profilu Bluetooth HFP, najpierw poproś o wymagane uprawnienia w czasie działania aplikacji, a następnie nagraj dźwięk za pomocą interfejsu API AudioManager, jak opisano w sekcjach poniżej.

Wyślij prośbę o uprawnienia

Podobnie jak w przypadku każdego standardowego urządzenia audio Bluetooth, uprawnienia RECORD_AUDIO, BLUETOOTH_CONNECT i inne powiązane uprawnienia są kontrolowane przez telefon, a nie połączone urządzenie (takie jak okulary audio lub okulary z wyświetlaczem).

Aby poprosić o uprawnienia, wykonaj te czynności:

  1. Zadeklaruj te uprawnienia w pliku manifestu aplikacji:

  2. Poproś o uprawnienia RECORD_AUDIO i BLUETOOTH_CONNECT w czasie działania aplikacji, korzystając ze standardowego procesu przyznawania uprawnień na Androidzie.

Używanie klasy AudioManager do kierowania dźwięku

Gdy użytkownik przyzna aplikacji niezbędne uprawnienia w czasie działania, użyj interfejsu API AudioManager, aby ustawić urządzenie komunikacyjne na TYPE_BLUETOOTH_SCO i przekierować dźwięk przez Bluetooth HFP. Spowoduje to, że system będzie pobierać dźwięk z urządzenia peryferyjnego 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()
}

Robienie zdjęć aparatem okularów

Aby zrobić zdjęcie aparatem okularów, skonfiguruj i powiąż przypadek użycia ImageCapture CameraX z aparatem okularów, używając kontekstu odpowiedniego dla aplikacji:

private fun setUpGlassesCamera(activity: ComponentActivity) {
    activity.lifecycleScope.launch {
        // Before creating a projected context, check to see if the projected device is connected.
        ProjectedContext.isProjectedDeviceConnected(activity, coroutineContext)
            .collectLatest { isConnected ->
                if (isConnected) {
                    // 1. Get the CameraProvider using the projected context.
                    // When using the projected context, DEFAULT_BACK_CAMERA maps to the audio and display glasses' camera.
                    val projectedContext = try {
                        ProjectedContext.createProjectedDeviceContext(activity)
                    } catch (e: IllegalStateException) {
                        Log.e(TAG, "Projected context could not be created", e)
                        return@collectLatest
                    }

                    val cameraProviderFuture = ProcessCameraProvider.getInstance(projectedContext)

                    cameraProviderFuture.addListener({
                        val cameraProvider: ProcessCameraProvider = cameraProviderFuture.get()
                        val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA

                        // 2. Check for the presence of a camera.
                        if (!cameraProvider.hasCamera(cameraSelector)) {
                            Log.w(TAG, "The selected camera is not available.")
                            return@addListener
                        }

                        // 3. Query supported streaming resolutions dynamically using Camera2 Interop.
                        val cameraInfo = cameraProvider.getCameraInfo(cameraSelector)
                        val map = Camera2CameraInfo.from(cameraInfo).getCameraCharacteristic(
                            CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP
                        )
                        val supportedResolutions = map?.getOutputSizes(ImageFormat.JPEG)?.toList() ?: emptyList()
                        Log.i(TAG, "Supported resolutions for JPEG: ${supportedResolutions.joinToString()}")

                        // 4. Dynamically select the best target resolution from the queried list.
                        val preferredResolution = Size(1920, 1080)
                        val dynamicTargetResolution = when {
                            // Case A: The preferred resolution is explicitly supported by the glasses.
                            supportedResolutions.contains(preferredResolution) -> preferredResolution

                            // Case B: Find the highest supported 16:9 resolution as a fallback.
                            else -> {
                                val targetAspectRatio = 16.0 / 9.0
                                val tolerance = 0.01
                                supportedResolutions
                                    .filter { abs((it.width.toDouble() / it.height) - targetAspectRatio) < tolerance }
                                    .maxByOrNull { it.width * it.height }
                                    // Case C: Absolute fallback if no 16:9 resolutions are found.
                                    ?: supportedResolutions.firstOrNull()
                                    ?: preferredResolution
                            }
                        }
                        Log.i(TAG, "Selected target resolution: $dynamicTargetResolution")

                        val resolutionStrategy = ResolutionStrategy(
                            dynamicTargetResolution,
                            ResolutionStrategy.FALLBACK_RULE_CLOSEST_LOWER
                        )
                        val resolutionSelector = ResolutionSelector.Builder()
                            .setResolutionStrategy(resolutionStrategy)
                            .build()

                        // 5. Initialize the ImageCapture use case with options.
                        val imageCapture = ImageCapture.Builder()
                            // Optional: Configure resolution, format, etc.
                            .setResolutionSelector(resolutionSelector)
                            .build()

                        try {
                            // Unbind use cases before rebinding.
                            cameraProvider.unbindAll()

                            // Bind use cases to camera using the Activity as the LifecycleOwner.
                            cameraProvider.bindToLifecycle(
                                activity,
                                cameraSelector,
                                imageCapture
                            )
                        } catch (exc: Exception) {
                            Log.e(TAG, "Use case binding failed", exc)
                        }
                    }, ContextCompat.getMainExecutor(activity))
                }
            }
    }
}

Najważniejsze informacje o kodzie

  • Pobiera instancję ProcessCameraProvider za pomocą prognozowanego kontekstu urządzenia.
  • W zakresie prognozowanego kontekstu główny aparat okularów skierowany na zewnątrz jest mapowany na DEFAULT_BACK_CAMERA podczas wybierania aparatu.
  • Sprawdzanie przed powiązaniem wykorzystuje cameraProvider.hasCamera(cameraSelector), aby zanim przejdziesz dalej, było wiadomo, czy wybrany aparat jest dostępny na urządzeniu.
  • Używa Camera2 Interop z Camera2CameraInfo do odczytywania podstawowej CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP, co może być przydatne w przypadku zaawansowanych kontroli obsługiwanych rozdzielczości.
  • Niestandardowy ResolutionSelector został utworzony, aby precyzyjnie kontrolować rozdzielczość obrazu wyjściowego dla ImageCapture.
  • Tworzy przypadek użycia ImageCapture skonfigurowany za pomocą niestandardowego ResolutionSelector.
  • Wiąże przypadek użycia ImageCapture z cyklem życia aktywności. Ta funkcja automatycznie zarządza otwieraniem i zamykaniem aparatu na podstawie stanu aktywności (np. zatrzymuje aparat, gdy aktywność jest wstrzymana).
  • Konfigurowanie sprzętu z jednym strumieniem: potok kamery okularów jest ograniczony do jednego aktywnego strumienia naraz. Gdy ImageCapture jest powiązany samodzielnie, CameraX domyślnie dołącza wewnętrzny strumień powtarzający się (MeteringRepeating) na potrzeby ustawiania ostrości i pomiaru, co powoduje zatrzymanie potoku strumieniowego pojedynczego strumienia. Aby powiązać ImageCapture bez strumienia podglądu, wyłącz wymuszony strumień powtarzający, ustawiając setRepeatingStreamForced(false) na CameraXConfig.Builder (na przykład przez zaimplementowanie CameraXConfig.Provider w klasie Application lub skonfigurowanie ProcessCameraProvider przed inicjalizacją).

Po skonfigurowaniu aparatu w okularach możesz zrobić zdjęcie za pomocą klasy ImageCapture CameraX. Więcej informacji o używaniu takePicture do robienia zdjęć znajdziesz w dokumentacji CameraX.

Nagrywanie transmisji aparatem okularów

Aby przechwytywać strumienie zamiast obrazu, zastąp komponent ImageCapture z przykładu przechwytywania obrazu komponentami VideoCapture lub ImageAnalysis i zmień logikę przechwytywania.

Więcej informacji o tych interfejsach API i sposobie ich używania znajdziesz w dokumentacji dotyczącej nagrywania filmów w CameraX i analizy obrazu w CameraX.

Wybieranie rozdzielczości i liczby klatek

Sprawdź urządzenie, aby dowiedzieć się, jakie rozdzielczości i odpowiadające im maksymalne liczby klatek obsługuje. W tabeli poniżej znajdziesz przykłady wartości, które mogą się wyświetlać w zależności od przypadku użycia aplikacji. Aby oszczędzać baterię i zmniejszyć nagrzewanie się okularów, wybierz najniższą rozdzielczość i liczbę klatek, które sprawdzą się w Twoim przypadku.

Przypadek użycia Rozdzielczość Liczba klatek
rozpoznawanie tekstu (OCR) lub wykrywanie otoczenia; 1920 x 1080 1 kl./s
Strumieniowe przesyłanie filmów przez AI (asystenci multimodalni) 1024 x 768 1 kl./s
Lokalizacja i system pozycjonowania wizualnego (VPS) 640 x 360 lub 640 x 480 10 kl./s
Rozmowy wideo 640 x 360 lub 640 x 480 24 kl./s

Sprawdzanie maksymalnej liczby klatek dla każdej rozdzielczości

CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES podaje ogólne limity liczby klatek na urządzeniu, które mogą być wyższe niż szybkość strumieniowania obsługiwana przez daną rozdzielczość. Aby uzyskać rzeczywistą maksymalną liczbę klatek na sekundę dla każdej rozdzielczości w przypadku okularów z wyświetlaczem i okularów audio, odczytaj minimalny czas trwania klatki i przekonwertuj go na klatki na sekundę za pomocą wzoru 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
    }
}

Następnie użyj tej wartości, aby obliczyć dolną granicę minFps i górną granicę maxFps docelowego zakresu liczby klatek. Ogranicz dolną granicę (minFps) do maksymalnej liczby klatek strumieniowania w danej rozdzielczości obliczonej na podstawie getOutputMinFrameDuration i ustaw wyższą górną granicę (maxFps) jako okno nadrabiania zaległości:

val maxFpsBySize = getMaxFpsBySize(cameraInfo, ImageFormat.YUV_420_888)
val maxSupportedFps = maxFpsBySize[Size(640, 480)] ?: 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

Najważniejsze informacje o kodzie

  • Użyj formatu, który pasuje do Twojego przypadku użycia. W przypadku ImageAnalysis jest to YUV_420_888.
  • W przypadku VideoCapture użyj przeciążeń Class: getOutputSizes(MediaRecorder::class.java) i getOutputMinFrameDuration(MediaRecorder::class.java, size).
  • Określ zakres, w którym maxFps jest większe niż minFps (np. minFps*2), zamiast ustawiać obie granice na tę samą wartość, np. Range(minFps, minFps). Dolna granica (minFps) określa docelową liczbę klatek strumieniowania i powinna być co najwyżej równa wartości obliczonej na podstawie getOutputMinFrameDuration, natomiast górna granica (maxFps) działa jako okno nadrabiania opóźnionych klatek, aby zapobiec utrzymującym się opóźnieniom. Na przykład [1,2] lub [1,3] w przypadku strumienia 1 kl./s oraz [24,30] lub [24,48] w przypadku strumienia 24 kl./s.

Konfigurowanie liczby klatek

Aby skonfigurować zakres liczby klatek na podstawie przypadku użycia CameraX:

// Configure Resolution Strategy for the stream
val resolutionStrategy = ResolutionStrategy(
    size,
    ResolutionStrategy.FALLBACK_RULE_CLOSEST_LOWER
)
val resolutionSelector = ResolutionSelector.Builder()
    .setResolutionStrategy(resolutionStrategy)
    .build()

// 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()

Ten przykład pokazuje konfigurację zarówno dla VideoCapture, jak i ImageAnalysis, ale możesz wdrożyć dowolne przypadki użycia obsługiwane przez Twoją aplikację.

Jak zachowuje się strumień

Podczas pracy ze strumieniami przechwytywania pamiętaj o tych zachowaniach systemu:

  • Nieobsługiwane rozdzielczości są odrzucane: jeśli poprosisz o rozmiar, którego nie ma na liście, Camera2 odrzuci konfigurację przed otwarciem strumienia.
  • Żądanie liczby klatek powyżej wartości maksymalnej: jeśli zażądasz minimalnej liczby klatek powyżej maksymalnej obsługiwanej dla danej rozdzielczości, sesja nadal zostanie otwarta, ale docelowa liczba klatek z okularów zostanie ograniczona do tej obsługiwanej wartości maksymalnej, a górna granica będzie nadal działać jako limit liczby klatek w trybie nadrabiania. Na przykład żądanie [30,60] przy 640 x 480 ogranicza docelową liczbę klatek do 24 kl./s (zachowując się jak [24,60]).
  • Ograniczanie termiczne: gdy okulary się nagrzewają, liczba klatek spada, ale rozdzielczość pozostaje taka sama. Zaprojektuj aplikację tak, aby obsługiwała niższą lub nierówną liczbę klatek, na przykład przez sprawdzanie sygnatur czasowych klatek, a nie zakładanie stałej liczby klatek.

Dostęp do sprzętu telefonu z poziomu wyświetlanej aktywności

Aktywność wyświetlana może też uzyskać dostęp do hardware telefonu (np. aparatu lub mikrofonu) za pomocą createHostDeviceContext(context), aby zdobyć kontekst urządzenia hosta (telefonu):

@OptIn(ExperimentalProjectedApi::class)
private fun getPhoneContext(activity: ComponentActivity): Context? {
    return try {
        // From a projected Activity, get a context for the phone.
        ProjectedContext.createHostDeviceContext(activity)
    } catch (e: IllegalStateException) {
        Log.e(TAG, "Failed to create host device context", e)
        null
    }
}

Gdy w aplikacji hybrydowej (zawierającej zarówno funkcje mobilne, jak i funkcje na okulary) uzyskujesz dostęp do hardware lub zasobów, które są specyficzne dla urządzenia hosta (telefonu), musisz wyraźnie wybrać odpowiedni kontekst, aby aplikacja mogła mieć dostęp do właściwego hardware: