camerax

このスキルでは、CameraX（Camera2Interop ユーティリティや Media3 との統合を含む）に重点を置き、Android でカメラアプリを構築するための手順と標準的なパターンを紹介します。

主なワークフロー

不変な API パターンへの対応

Android のカメラおよびメディア API の多く、特に CameraX の VideoCapture は、メソッドが新しいインスタンスを返す流暢な不変ビルダー風パターンを使用しています。結果を再代入しないと、オーディオなどの設定が無視されます。

パターン：再代入が必要です

// WRONG
run {
  val pending = recorder.prepareRecording(context, opts)
  pending.withAudioEnabled() // This returns a new instance which is ignored
  val active = pending.start(exec, listener)
}

// CORRECT
run {
  val pending = recorder.prepareRecording(context, opts)
      .withAudioEnabled() // Chaining works
  val active = pending.start(exec, listener)
}

// ALSO CORRECT
run {
  var pending = recorder.prepareRecording(context, opts)
  pending = pending.withAudioEnabled() // Reassignment
  val active = pending.start(exec, listener)
}

対象となるクラスの一覧については、不変性を参照してください。

CameraX への移行

従来のカメラコードベースを CameraX Jetpack ライブラリに移行する場合：

• Camera1 から CameraX へ：従来の android.hardware.Camera の実装、サーフェスの処理、手動のライフサイクル管理から移行する方法については、Camera1 移行ガイドを参照してください。
• Camera2 から CameraX へ：より新しいものの冗長な android.hardware.camera2 の実装、セッション状態コールバック、相互運用パターンから移行する方法については、Camera2 移行ガイドを参照してください。

包括的な機能の設計

複数のファイルとハードウェアレベルの接続を伴う複数ステップの機能では、システムタイムアウトを回避するため、構造的な設計のアプローチに従ってください。このような複雑な機能には、次のものがあります。

• 手動コントロール：ViewModel の状態、コントローラーレイヤー、セッション内の Camera2Interop 接続に分けてください。
• RAW 撮影：JPEG と RAW の出力設定を、個別のビルド手順に分けてください。
• カスタムエフェクト：絶対的なパフォーマンスが必要な場合を除き、手動の OpenGL パイプラインより Media3Effect または SurfaceProcessor を優先してください。
• 低照度：ナイトモードと LLB に関するガイダンスは、低照度を参照してください。
• 折りたたみ式デバイス：姿勢やヒンジの状態の変化への対応については、折りたたみ式デバイスを参照してください。
• XR、AR、VR：空間トラッキング、パススルーの同期、レイテンシーに関するガードレールについては、xrを参照してください。
• 温度と電力：StreamUseCase の最適化と PowerManager の温度状態の管理については、温度を参照してください。
• テストとモック：FakeCameraConfig の使用、非同期ライフサイクルの処理、分析パイプラインの検証については、テストを参照してください。
• ML Kit の空間分析：座標マッピング、回転ロジック、ミラーリングされたレンズの処理については、mlkit-spatialを参照してください。
• Wear OS のリモートカメラ：円形 UI の制約、Data Layer API の同期、リモートトリガーロジックについては、wear-osを参照してください。

手順ごとのガイドについては、expert-blueprintsを参照してください。

API の調査

低レベルの手動接続ではなく、常に高レベルの抽象化を使用してください。

• 分析：手動の ImageAnalysis.Analyzer ではなく、MlKitAnalyzer を使用してください。
• フィルターとエフェクト：標準的な後処理には Media3Effect を使用してください。
• マルチカメラ：デュアルストリームの構成には ConcurrentCamera API を使用してください。

最新の推奨事項については、最新の APIを参照してください。

コード品質とアーキテクチャのルール

カメラの実装を構築する際は、Android エコシステムの次の標準パターンに従ってください。

• テストではモックよりフェイクを使用：特に ImageProxy のような複数のステップを伴う CameraX インターフェースでは、Mockito のようなモックライブラリの使用を避けてください。信頼性の低い実装の詳細ではなく、状態を検証するための「フェイク」を作成してください。
• Google Truth によるアサーション：可読性を高めるため、assertEquals のような標準の JUnit アサーションではなく、assertThat を使用してください。
• テストランナーの明示：CI 環境でテストが正しく実行されるよう、テストクラスには必ず明示的な @RunWith を定義してください。
• セマンティックな UI の統合：Compose で Icon と Text を含むボタンなどのカスタムカメラコントロールを作成する場合は、スクリーンリーダーがそれらを単一の一貫した要素として読み上げるよう、semantics { mergeDescendants = true } を使用してください。

ハードウェアとデバイスの多様性

カメラアプリは、スマートフォンや折りたたみ式デバイスからタブレット、ノートパソコン、さらにはスマート家電に至るまで、さまざまなハードウェアで動作します。アプリが動作するハードウェアの特性を考慮してください。

• フォームファクター：折りたたみ式デバイスやタブレットでの画面サイズや画面の向きの変化に対応してください。
• マルチカメラアレイ：背面カメラと前面カメラを備えたデバイスもあれば、広角レンズや望遠レンズなど、複数の背面カメラを備えたデバイスもあります。
• 機能の同等性：フラッシュやオートフォーカスなどの機能は、ハードウェアによって動作が異なります。たとえば、CameraX は物理フラッシュ（背面）と画面フラッシュ（前面）の両方に対応しているため、フラッシュ機能を実装する際はどちらも考慮する必要があります。

よくある落とし穴

• 非同期ライフサイクル：停止または一時停止を試みる前に、isRecording の状態を確認してください。初期呼び出しだけでなく、UI の状態を更新するために VideoRecordEvent.Start を処理してください。
• スレッドセーフ：カメラのコールバックは、バックグラウンドエグゼキューターで実行されることがよくあります。UI の更新はメインスレッドにディスパッチしてください。
• 権限の処理：CAMERA 権限を確認してください。VideoCapture で音声を有効にする場合は、RECORD_AUDIO も個別に確認してください。