camerax

name	camerax
description	提供使用 CameraX 进行 Android 相机开发的技术指导。当实现相机功能、处理异步录制生命周期、使用 CameraX 进行底层硬件互操作，或集成 ML Kit 或 Media3 特效时使用。
license	Complete terms in LICENSE.txt
metadata	{"author":"Google LLC","last-updated":"2026-07-07","keywords":["recipe","Android","Camera","Camera1","Camera2","CameraX","migration","Compose","guide","dependencies","PreviewView","CameraXViewfinder","ImageCapture","VideoCapture","ImageAnalysis."]}

This skill provides procedural guidance and standard patterns for building camera applications on Android, with a focus on CameraX, including its Camera2Interop utilities, and Media3 integrations.

Core workflows

Handling immutable API patterns

Various Android camera and media APIs, especially CameraX VideoCapture, use a fluent, immutable builder-like pattern where methods return a new instance. Failing to reassign these results in settings, such as audio, being ignored.

Pattern: Reassignment is required

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

See immutability for a list of affected classes.

Migrating to CameraX

When migrating legacy camera codebases to the CameraX Jetpack library:

• Camera1 to CameraX : For migrating legacy android.hardware.Camera implementations, surface handling, and manual lifecycles, see the Camera1 migration guide.
• Camera2 to CameraX : For migrating more recent but verbose android.hardware.camera2 implementations, session state callbacks, and interop patterns, see the Camera2 migration guide.

Comprehensive feature blueprinting

For multi-step features that involve multiple files and hardware-level wiring, follow the Structural Blueprinting approach to avoid system timeouts. Such complex features include:

• Manual controls : Break down into the ViewModel state, the controller layer, and the Camera2Interop wiring in the session.
• RAW capture: Separate JPEG and RAW output configurations into discrete build steps.
• Custom effects : Prefer Media3Effect or SurfaceProcessor over manual OpenGL pipelines unless absolute performance is required.
• Low-light : See low-light for Night Mode and LLB guidance.
• Foldables : See foldables for handling dynamic postures and hinge states.
• XR, AR, and VR : See xr for spatial tracking, passthrough synchronization, and latency guardrails.
• Thermals and power : See thermals for managing StreamUseCase optimizations and PowerManager thermal states.
• Testing and mocking : See testing for using FakeCameraConfig, handling asynchronous lifecycles, and validating analysis pipelines.
• ML Kit spatial analysis : See mlkit-spatial for coordinate mapping, rotation logic, and mirrored lens handling.
• Wear OS camera remote : See wear-os for circular UI constraints, Data Layer API syncing, and remote trigger logic.

See expert-blueprints for step-by-step guides.

API discovery

Always use higher-level abstractions instead of low-level manual wiring:

• Analysis : Use MlKitAnalyzer instead of manual ImageAnalysis.Analyzer.
• Filters and effects : Use Media3Effect for standard post-processing.
• Multi-camera : Use ConcurrentCamera APIs for dual-stream setups.

See modern-apis for current recommendations.

Code quality and architectural rules

Adhere to the following Android ecosystem standard patterns when building your camera implementations:

• Testing, fakes over mocks : Avoid mocking libraries like Mockito, especially for multi-step CameraX interfaces like ImageProxy. Build "Fakes" to verify state rather than unreliable implementation details.
• Google Truth assertions : Use assertThat over standard JUnit assertions like assertEquals for improved readability.
• Explicit test runners : Always define an explicit @RunWith for test classes to ensure the CI environment executes them correctly.
• Semantic UI merging : When building custom camera controls in Compose, such as a button with an Icon and Text, use semantics { mergeDescendants = true } to ensure screen readers announce them as a single, coherent unit.

Hardware and device diversity

Camera apps run on a wide variety of hardware, from mobile phones and foldables to tablets, laptops, and even smart appliances. Have consideration for the specific hardware the app is running on.

• Form factors: Account for screen size and orientation changes on foldables and tablets.
• Multi-camera arrays: Some devices have a rear-facing camera and a front-facing camera. Other devices have multiple rear-facing cameras, such as wide-angle and telephoto lenses.
• Feature parity: Features like flash or auto-focus behave differently across hardware. For example, CameraX handles both physical flash, back, and screen-based flash, front, and both must be considered when implementing flash functionality.

Common pitfalls

• Asynchronous lifecycles : Check isRecording state before attempting to stop or pause. Handle VideoRecordEvent.Start for UI state updates, not just the initial call.
• Thread safety: Camera callbacks often run on background executors. Dispatch UI updates on the main thread.
• Permission handling : Check CAMERA permission; check for RECORD_AUDIO specifically when enabling audio in VideoCapture.