Sử dụng bối cảnh được chiếu để truy cập vào phần cứng trên kính âm thanh và kính hiển thị

Các thiết bị XR được hỗ trợ
Hướng dẫn này giúp bạn xây dựng các trải nghiệm cho những loại thiết bị XR sau.
Kính có màn hình
và âm thanh

Sau khi bạn yêu cầu và được cấp các quyền cần thiết, ứng dụng của bạn có thể truy cập vào phần cứng trên kính phát âm thanh hoặc kính có màn hình. Chìa khoá để truy cập vào phần cứng của kính (thay vì phần cứng của điện thoại) là sử dụng bối cảnh dự kiến.

Có hai cách chính để lấy bối cảnh dự kiến, tuỳ thuộc vào nơi mã của bạn đang thực thi:

Nhận bối cảnh dự kiến nếu mã của bạn đang chạy trong một hoạt động dự kiến

Nếu mã của ứng dụng đang chạy trong hoạt động được chiếu, thì ngữ cảnh hoạt động của chính ứng dụng đó đã là ngữ cảnh được chiếu. Trong trường hợp này, các cuộc gọi được thực hiện trong hoạt động đó đã có thể truy cập vào phần cứng của kính.

Nhận bối cảnh dự kiến cho mã chạy trong thành phần ứng dụng điện thoại

Nếu một phần của ứng dụng bên ngoài hoạt động được chiếu (chẳng hạn như hoạt động trên điện thoại hoặc dịch vụ) cần truy cập vào phần cứng của kính, thì phần đó phải lấy bối cảnh được chiếu một cách rõ ràng. Để thực hiện việc này, hãy sử dụng phương thức 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...")
                }
            }
    }
}

Kiểm tra tính hợp lệ

Gói lệnh gọi createProjectedDeviceContext trong ProjectedContext.isProjectedDeviceConnected. Mặc dù phương thức này trả về true, nhưng bối cảnh được chiếu vẫn hợp lệ với thiết bị thông minh, và hoạt động trong ứng dụng hoặc dịch vụ của ứng dụng điện thoại (chẳng hạn như CameraManager) có thể truy cập vào phần cứng của mắt kính.

Dọn dẹp khi ngắt kết nối

Bối cảnh dự kiến được liên kết với vòng đời của thiết bị thông minh, vì vậy, bối cảnh này sẽ bị hủy bỏ khi thiết bị ngắt kết nối. Khi thiết bị ngắt kết nối, ProjectedContext.isProjectedDeviceConnected sẽ trả về false. Ứng dụng của bạn nên theo dõi thay đổi này và dọn dẹp mọi dịch vụ hệ thống (chẳng hạn như CameraManager) hoặc tài nguyên mà ứng dụng đã tạo bằng bối cảnh được chiếu đó.

Khởi động lại khi kết nối lại

Khi kính kết nối lại, ứng dụng của bạn có thể lấy một thực thể bối cảnh được chiếu khác bằng cách sử dụng createProjectedDeviceContext, sau đó khởi chạy lại mọi dịch vụ hoặc tài nguyên hệ thống bằng bối cảnh được chiếu mới.

Ghi âm bằng micrô của kính

Bạn có thể ghi âm bằng kính thông qua Cấu hình rảnh tay (HFP) của Bluetooth. Ở chế độ này, kính kết nối với điện thoại bằng cấu hình Tai nghe và Cấu hình phân phối âm thanh nâng cao (A2DP) tiêu chuẩn, hoạt động như một thiết bị ngoại vi Bluetooth thông thường. Nếu ứng dụng của bạn đã được thiết kế để ghi âm qua Bluetooth tiêu chuẩn, thì bạn có thể dùng phương thức này để ghi âm từ kính mà không cần phát triển thêm.

Ghi âm bằng Bluetooth HFP

Để ghi âm bằng Bluetooth HFP, trước tiên, hãy yêu cầu các quyền khi bắt đầu chạy cần thiết, sau đó ghi âm bằng API AudioManager, như mô tả trong các phần sau.

Yêu cầu cấp quyền

Giống như mọi thiết bị âm thanh Bluetooth tiêu chuẩn, quyền RECORD_AUDIO, BLUETOOTH_CONNECT và các quyền khác có liên quan đều do điện thoại kiểm soát chứ không phải thiết bị thông minh được kết nối (chẳng hạn như kính phát âm thanh hoặc kính có màn hình).

Hãy làm theo các bước sau để yêu cầu cấp quyền:

  1. Khai báo các quyền sau trong tệp kê khai của ứng dụng:

  2. Yêu cầu cả quyền RECORD_AUDIO và BLUETOOTH_CONNECT trong thời gian chạy bằng quy trình cấp quyền tiêu chuẩn của Android.

Sử dụng AudioManager để định tuyến âm thanh

Sau khi người dùng cấp cho ứng dụng của bạn các quyền khi bắt đầu chạy cần thiết, hãy sử dụng API AudioManager để đặt thiết bị liên lạc thành TYPE_BLUETOOTH_SCO nhằm định tuyến âm thanh qua Bluetooth HFP. Thao tác này sẽ hướng dẫn hệ thống truy xuất âm thanh từ thiết bị ngoại vi 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()
}

Chụp ảnh bằng camera của mắt kính

Để chụp ảnh bằng camera của kính, hãy thiết lập và liên kết trường hợp sử dụng ImageCapture của CameraX với camera của kính bằng cách sử dụng bối cảnh chính xác cho ứng dụng của bạn:

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

Các điểm chính về mã

  • Lấy một thực thể của ProcessCameraProvider bằng cách sử dụng bối cảnh thiết bị dự kiến.
  • Trong phạm vi của bối cảnh được chiếu, camera chính hướng ra ngoài của kính sẽ liên kết với DEFAULT_BACK_CAMERA khi chọn camera.
  • Quá trình kiểm tra trước khi liên kết sử dụng cameraProvider.hasCamera(cameraSelector) để xác minh rằng camera đã chọn có sẵn trên thiết bị trước khi tiếp tục.
  • Sử dụng Camera2 Interop với Camera2CameraInfo để đọc CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP cơ bản, có thể hữu ích cho việc kiểm tra nâng cao về độ phân giải được hỗ trợ.
  • ResolutionSelector tuỳ chỉnh được xây dựng để kiểm soát chính xác độ phân giải hình ảnh đầu ra cho ImageCapture.
  • Tạo một trường hợp sử dụng ImageCapture được định cấu hình bằng ResolutionSelector tuỳ chỉnh.
  • Liên kết trường hợp sử dụng ImageCapture với vòng đời của hoạt động. Thao tác này sẽ tự động quản lý việc mở và đóng camera dựa trên trạng thái của hoạt động (ví dụ: dừng camera khi hoạt động bị tạm dừng).
  • Định cấu hình cho phần cứng một luồng: Quy trình camera của kính bị giới hạn ở một luồng hoạt động tại một thời điểm. Khi ImageCapture được liên kết riêng, CameraX sẽ đính kèm một luồng lặp lại nội bộ (MeteringRepeating) để lấy nét và đo sáng theo mặc định, khiến quy trình một luồng bị đình trệ. Để tự liên kết ImageCapture mà không cần luồng xem trước, hãy tắt luồng lặp lại bắt buộc bằng cách đặt setRepeatingStreamForced(false) trên CameraXConfig.Builder (ví dụ: bằng cách triển khai CameraXConfig.Provider trong lớp Application hoặc định cấu hình ProcessCameraProvider trước khi khởi chạy).

Sau khi thiết lập camera của kính, bạn có thể chụp ảnh bằng lớp ImageCapture của CameraX. Tham khảo tài liệu về CameraX để tìm hiểu cách sử dụng takePicture để chụp ảnh.

Quay video bằng camera của kính

Để chụp luồng thay vì hình ảnh, hãy thay thế thành phần ImageCapture trong ví dụ về hình ảnh chụp bằng thành phần VideoCapture hoặc ImageAnalysis và thay đổi logic chụp.

Để biết thêm thông tin về các API này và cách sử dụng, hãy xem tài liệu về quay video bằng CameraX và phân tích hình ảnh bằng CameraX.

Chọn độ phân giải và tốc độ khung hình

Bạn nên truy vấn thiết bị để tìm độ phân giải được hỗ trợ và tốc độ khung hình tối đa tương ứng. Bảng sau đây liệt kê các ví dụ về giá trị mà bạn có thể thấy, tuỳ thuộc vào trường hợp sử dụng của ứng dụng. Để tiết kiệm pin và giảm nhiệt cho kính, hãy chọn độ phân giải và tốc độ khung hình thấp nhất phù hợp với trường hợp sử dụng của bạn.

Trường hợp sử dụng Độ phân giải Tốc độ khung hình
Nhận dạng văn bản (OCR) hoặc cảm nhận thế giới 1920 x 1080 1 khung hình/giây
Phát trực tuyến video bằng AI (trợ lý đa phương thức) 1024 x 768 1 khung hình/giây
Bản địa hoá và định vị trực quan (VPS) 640 x 360 hoặc 640 x 480 10 khung hình/giây
Gọi video 640 x 360 hoặc 640 x 480 24 khung hình/giây

Truy vấn tốc độ khung hình tối đa cho mỗi độ phân giải

CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES báo cáo giới hạn tốc độ khung hình tổng thể của thiết bị, có thể cao hơn tốc độ truyền trực tuyến mà một độ phân giải nhất định hỗ trợ. Để biết tốc độ khung hình tối đa thực tế cho từng độ phân giải trên kính âm thanh và kính có màn hình, hãy đọc thời lượng khung hình tối thiểu rồi chuyển đổi thành FPS bằng 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
    }
}

Tiếp theo, hãy sử dụng giá trị đó để tính toán giới hạn minFps và maxFps cho phạm vi tốc độ khung hình mục tiêu. Giới hạn cận dưới (minFps) ở tốc độ khung hình tối đa của độ phân giải khi phát trực tuyến, được tính từ getOutputMinFrameDuration, và đặt cận trên cao hơn (maxFps) làm cửa sổ bắt kịp:

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

Các điểm chính về mã

  • Sử dụng định dạng phù hợp với trường hợp sử dụng của bạn. Đối với ImageAnalysis, đó là YUV_420_888.
  • Đối với VideoCapture, hãy sử dụng các phương thức nạp chồng Class: getOutputSizes(MediaRecorder::class.java) và getOutputMinFrameDuration(MediaRecorder::class.java, size).
  • Chỉ định một dải ô trong đó maxFps lớn hơn minFps (chẳng hạn như minFps*2) thay vì đặt cả hai ranh giới thành cùng một giá trị như Range(minFps, minFps). Giới hạn dưới (minFps) đặt tốc độ khung hình truyền trực tuyến mục tiêu và tối đa phải bằng giá trị được tính từ getOutputMinFrameDuration, trong khi giới hạn trên (maxFps) đóng vai trò là khoảng thời gian bù cho các khung hình bị trễ để ngăn độ trễ kéo dài. Ví dụ: [1,2] hoặc [1,3] cho luồng 1 FPS và [24,30] hoặc [24,48] cho luồng 24 FPS.

Định cấu hình tốc độ khung hình

Cách định cấu hình dải tốc độ khung hình dựa trên trường hợp sử dụng 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()

Ví dụ này cho thấy cấu hình cho cả VideoCapture và ImageAnalysis, nhưng bạn có thể triển khai bất kỳ trường hợp sử dụng nào mà ứng dụng của bạn hỗ trợ.

Tìm hiểu cách hoạt động của luồng

Hãy lưu ý các hành vi sau đây của hệ thống khi làm việc với luồng thu nạp:

  • Độ phân giải không được hỗ trợ sẽ bị từ chối: Nếu bạn yêu cầu một kích thước không có trong danh sách, Camera2 sẽ từ chối cấu hình trước khi luồng mở ra.
  • Yêu cầu tốc độ khung hình cao hơn mức tối đa: Nếu bạn yêu cầu tốc độ khung hình tối thiểu cao hơn mức tối đa được hỗ trợ cho độ phân giải của bạn, thì phiên vẫn mở, nhưng tốc độ khung hình mục tiêu từ kính sẽ được giới hạn ở mức tối đa được hỗ trợ đó, trong khi giới hạn trên tiếp tục đóng vai trò là giới hạn tốc độ bắt kịp. Ví dụ: việc yêu cầu [30,60] ở độ phân giải 640 x 480 sẽ giới hạn tốc độ khung hình mục tiêu ở mức 24 khung hình/giây (hoạt động như [24,60]).
  • Điều tiết nhiệt: Khi kính nóng lên, tốc độ khung hình sẽ giảm nhưng độ phân giải vẫn giữ nguyên. Tạo ứng dụng để xử lý tốc độ khung hình thấp hơn hoặc không đồng đều, ví dụ: bằng cách kiểm tra dấu thời gian của khung hình thay vì giả định tốc độ cố định.

Truy cập vào phần cứng của điện thoại từ một hoạt động được chiếu

Hoạt động được chiếu cũng có thể truy cập vào phần cứng của điện thoại (chẳng hạn như camera hoặc micrô) bằng cách sử dụng createHostDeviceContext(context) để lấy bối cảnh của thiết bị lưu trữ (điện thoại):

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

Khi truy cập vào phần cứng hoặc tài nguyên dành riêng cho thiết bị lưu trữ (điện thoại) trong một ứng dụng kết hợp (ứng dụng có cả trải nghiệm trên thiết bị di động và kính), bạn phải chọn rõ ràng bối cảnh chính xác để đảm bảo ứng dụng có thể truy cập vào đúng phần cứng:

  • Sử dụng bối cảnh Activity từ điện thoại Activity hoặc ProjectedContext.createHostDeviceContext để lấy bối cảnh của điện thoại.
  • Đừng sử dụng getApplicationContext vì ngữ cảnh ứng dụng có thể trả về không chính xác ngữ cảnh của kính nếu hoạt động được chiếu là thành phần được khởi chạy gần đây nhất.