投影されたコンテキストを使用して、オーディオ グラスとディスプレイ グラスのハードウェアにアクセスする

該当する XR デバイス
このガイダンスは、次のようなタイプの XR デバイス向けのエクスペリエンスを構築する際に役立ちます。
オーディオ&
ディスプレイ グラス

必要な権限をリクエストして付与されると、アプリはオーディオ グラスまたはディスプレイ グラスのハードウェアにアクセスできるようになります。(スマートフォンのハードウェアではなく)グラスのハードウェアにアクセスするための鍵は、投影されたコンテキストを使用することです。

投影されたコンテキストを取得するには、コードの実行場所に応じて主に 2 つの方法があります。

コードが投影されたアクティビティで実行されている場合は、投影されたコンテキストを取得する

アプリのコードが投影されたアクティビティ内から実行されている場合、そのアクティビティ コンテキストはすでに投影されたコンテキストになっています。このシナリオでは、そのアクティビティ内で行われた呼び出しは、すでにグラスのハードウェアにアクセスできます。

スマートフォン アプリ コンポーネントで実行されているコードの投影コンテキストを取得する

投影されたアクティビティの外部にあるアプリの一部(電話アクティビティやサービスなど)がグラスのハードウェアにアクセスする必要がある場合は、投影されたコンテキストを明示的に取得する必要があります。これを行うには、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 ハンズフリー プロファイル(HFP)を使用して、グラスから音声を録音できます。このモードでは、グラスは標準のヘッドセット プロファイルと Advanced Audio Distribution Profile(A2DP)プロファイルを使用してスマートフォンに接続し、一般的な Bluetooth 周辺機器のように機能します。アプリがすでに標準の Bluetooth 録音用に設計されている場合は、この方法を使用することで、追加の開発なしでグラスから音声を録音できます。

Bluetooth HFP を使用して音声を録音する

Bluetooth HFP を使用して音声を録音するには、まず必要な実行時の権限をリクエストし、次に AudioManager API を使用して音声を録音します。詳しくは、以下のセクションをご覧ください。

権限をリクエスト

標準の Bluetooth オーディオ機器と同様に、RECORD_AUDIO、BLUETOOTH_CONNECT、その他の関連する権限は、コネクテッド デバイス(オーディオ グラスやディスプレイ グラスなど)ではなく、スマートフォンによって制御されます。

権限をリクエストする手順は次のとおりです。

  1. アプリのマニフェスト ファイルで次の権限を宣言します。

  2. 標準の Android 権限フローを使用して、実行時に RECORD_AUDIO 権限と BLUETOOTH_CONNECT 権限の両方をリクエストします。

AudioManager を使用して音声をルーティングする

ユーザーがアプリに必要な実行時の権限を付与したら、AudioManager API を使用して、通信デバイスを 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 を作成して、カメラの存在をリッスンし、CameraX の ImageCapture ユースケースをバインドします。

まず、デバイスの接続性をモニタリングし、単一ストリームの CameraXConfig.Builder を使用して LifecycleCameraProvider.createInstance を初期化します。

@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 以降では、addCameraPresenceListener を使用して CameraPresenceListener を登録し、メガネのカメラが追加または削除されたときに反応します。

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

次に、リスナーから提供された CameraIdentifier を使用して、availableCameraInfos からグラスのカメラを選択し、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 以降では、メガネが接続されたときにすぐにカメラを開くのではなく、cameraProvider.addCameraPresenceListener を使用して CameraPresenceListener を登録します。グラスとホスト間の非同期セットアップは、OS がグラスのカメラの再作成を完了する前に完了する必要があります。また、グラスのカメラは、接続中に動的に消えることもあります(熱軽減中など)。
    • カメラの追加(onCamerasAdded): 追加されたカメラで availableCameraInfos が更新された後に起動し、セットアップ中のタイミング競合を回避します。
    • カメラの取り外し(onCamerasRemoved): 使用状態ではなくカメラの有無を追跡します。そのため、ここでバインドを解除すると、アプリがカメラを開いたときではなく、グラスのカメラが取り外されたときにのみリソースが解放されます。
  • 切断時のクリーンアップ: monitorProjectedDeviceConnectivity に返されたクリーンアップ クロージャは、グラスが切断されたとき、またはアクティビティが破棄されたときに、removeCameraPresenceListener と unbindAll() を呼び出します。
  • 動的なカメラ選択: onCamerasAdded に渡された CameraIdentifier を isOf を使用して availableCameraInfos と照合し、グラスのカメラを動的に選択します。
  • カスタム解像度: ImageCapture の 16:9 のアスペクト比と、任意の解像度(サポートされている最も近いサイズにフォールバック)をターゲットとする ResolutionSelector をビルドします。サポートされているアスペクト比と解像度は、グラスデバイスとモード(4:3 や 16:9 など)によって異なります。サポートされている正確なサイズを確認する必要がある場合は、StreamConfigurationMap をクエリしてください。
  • ライフサイクル バインディング: ImageCapture を LifecycleOwner にバインドし、アクティビティのライフサイクルに応じてカメラの開閉を自動的に管理します。
  • シングルストリーム ハードウェアの構成: グラスのカメラ パイプラインは、一度に 1 つのアクティブなストリームに制限されます。ImageCapture が単独でバインドされている場合、CameraX はデフォルトでフォーカスと測光用の内部繰り返しストリーム(MeteringRepeating)をアタッチします。これにより、単一ストリーム パイプラインが停止します。LifecycleCameraProvider.createInstance に渡される CameraXConfig で setRepeatingStreamForced(false) を渡して、ImageCapture がプレビュー ストリームなしでバインドできるようにします。

グラスのカメラをセットアップしたら、CameraX の ImageCapture クラスを使用して画像をキャプチャできます。takePicture を使用して画像をキャプチャする方法については、CameraX のドキュメントをご覧ください。

グラスのカメラでストリームをキャプチャする

画像の代わりにストリームをキャプチャするには、画像キャプチャの例の ImageCapture コンポーネントを VideoCapture または ImageAnalysis コンポーネントに置き換え、キャプチャ ロジックを変更します。

これらの API とその使用方法について詳しくは、CameraX の動画キャプチャと CameraX の画像分析のドキュメントをご覧ください。

解像度とフレームレートを選択する

デバイスにクエリを実行して、サポートされている解像度とそれに対応する最大フレームレートを確認する必要があります。次の表に、アプリのユースケースに応じて表示される値の例を示します。バッテリー電力を節約し、グラスの熱を抑えるには、ユースケースに適した最低の解像度とフレームレートを選択します。

ユースケース 解決策 フレームレート
テキスト認識(OCR)または世界認識 1,920 x 1,080 1 FPS
AI 動画ストリーミング(マルチモーダル アシスタント) 1024 x 768 1 FPS
ローカライズとビジュアル ポジショニング(VPS) 640 x 360 または 640 x 480 10 FPS
ビデオ通話 640 x 360 または 640 x 480 24 fps

各解像度の最大フレームレートをクエリする

CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES は、デバイスの全体的なフレームレートの範囲を報告します。これは、特定の解像度がサポートするストリーミング レートよりも高くなる可能性があります。オーディオ グラスとディスプレイ グラスの各解像度の実際の最大値を取得するには、最小フレーム時間を読み取り、StreamConfigurationMap.getOutputMinFrameDuration(format, size) を使用して FPS に変換します。

@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))を使用します。
  • 両方の境界を Range(minFps, minFps) のように同じ値に設定するのではなく、maxFps が minFps より大きい範囲(minFps*2 など)を指定します。下限(minFps)は、ターゲット ストリーミング フレームレートを設定します。これは、getOutputMinFrameDuration から計算された値以下にする必要があります。一方、上限(maxFps)は、遅延フレームのキャッチアップ ウィンドウとして機能し、永続的なレイテンシを防ぎます。たとえば、1 FPS ストリームの場合は [1,2] または [1,3]、24 FPS ストリームの場合は [24,30] または [24,48] です。

フレームレートを構成する

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 はストリームが開く前に構成を拒否します。
  • 最大値を超えるフレームレートをリクエストする: 解像度でサポートされている最大値を超える最小フレームレートをリクエストした場合、セッションは開きますが、グラスからのターゲット フレームレートはそのサポートされている最大値に固定され、上限は引き続きキャッチアップ レート制限として機能します。たとえば、640 x 480 で [30,60] をリクエストすると、ターゲット フレームレートは 24 FPS に固定されます([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 は使用しないでください。投影されたアクティビティが最後に起動されたコンポーネントであった場合、アプリケーション コンテキストがグラスのコンテキストを誤って返す可能性があるためです。