camerax

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本技能为Android平台相机应用开发提供流程指导与标准范式，重点围绕CameraX（包括其

Camera2Interop

工具）及Media3集成展开。

Core workflows

核心工作流

Handling immutable API patterns

处理不可变API范式

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

<br />

kotlin

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

<br />

See immutability for a list of affected classes.

各类Android相机与媒体API，尤其是CameraX的

VideoCapture

，采用流畅的不可变构建器式范式，即方法会返回新实例。若不重新赋值这些返回结果，音频等设置将被忽略。

范式：必须重新赋值

<br />

kotlin

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

<br />

受影响的类列表请参见不可变性。

Migrating to CameraX

迁移至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.

将旧版相机代码库迁移至CameraX Jetpack库时：

Camera1转CameraX：如需迁移旧版
```
android.hardware.Camera
```
实现、Surface处理及手动生命周期相关代码，请查看Camera1迁移指南。
Camera2转CameraX：如需迁移较新但繁琐的
```
android.hardware.camera2
```
实现、会话状态回调及互操作范式，请查看Camera2迁移指南。

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.

对于涉及多文件及硬件级连接的多步骤功能，请遵循结构化蓝图设计方法以避免系统超时。这类复杂功能包括：

手动控制：拆分为
```
ViewModel
```
状态、控制器层及会话中的
```
Camera2Interop
```
连接逻辑。
RAW格式拍摄：将JPEG与RAW输出配置拆分为独立的构建步骤。
自定义特效：除非对性能有绝对要求，否则优先使用
```
Media3Effect
```
或
```
SurfaceProcessor
```
，而非手动OpenGL管线。
低光场景：夜间模式及LLB相关指导请参见低光处理。
折叠屏设备：动态姿态与铰链状态处理请参见折叠屏适配。
XR、AR与VR：空间追踪、透视同步及延迟管控请参见XR开发。
散热与功耗：
```
StreamUseCase
```
优化及
```
PowerManager
```
热状态管理请参见散热处理。
测试与模拟：
```
FakeCameraConfig
```
使用、异步生命周期处理及分析管线验证请参见测试指南。
ML Kit空间分析：坐标映射、旋转逻辑及镜像镜头处理请参见ML Kit空间分析。
Wear OS相机远程控制：圆形UI约束、Data Layer API同步及远程触发逻辑请参见Wear OS适配。

分步指南请参见专家蓝图。

API discovery

API选型建议

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.

优先使用高层抽象而非底层手动连接：

图像分析：使用
```
MlKitAnalyzer
```
而非手动实现
```
ImageAnalysis.Analyzer
```
。
滤镜与特效：使用
```
Media3Effect
```
进行标准后期处理。
多相机：使用
```
ConcurrentCamera
```
API实现双流配置。

当前推荐选型请参见现代API。

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.

构建相机实现时，请遵循以下Android生态系统标准范式：

测试：使用Fake而非Mock：避免使用Mockito等Mock库，尤其是针对CameraX的多步骤接口（如
```
ImageProxy
```
）。构建"Fake"实例以验证状态，而非依赖不可靠的实现细节。
Google Truth断言：为提升可读性，使用
```
assertThat
```
替代
```
assertEquals
```
等标准JUnit断言。
显式测试运行器：始终为测试类定义显式的
```
@RunWith
```
注解，确保CI环境能正确执行测试。
语义UI合并：在Compose中构建自定义相机控件（如包含
```
Icon
```
与
```
Text
```
的按钮）时，使用
```
semantics { mergeDescendants = true }
```
确保屏幕阅读器将其识别为单个连贯单元。

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.

相机应用运行在各类硬件设备上，从手机、折叠屏到平板、笔记本，甚至智能家电。需考虑应用运行的具体硬件特性：

形态因素：适配折叠屏与平板的屏幕尺寸及方向变化。
多相机阵列：部分设备配备后置与前置相机，还有些设备拥有多个后置相机（如广角与长焦镜头）。
功能一致性：闪光灯、自动对焦等功能在不同硬件上表现各异。例如，CameraX同时支持物理闪光灯（后置）与屏幕闪光灯（前置），实现闪光灯功能时需兼顾两者。

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
```
.

异步生命周期：尝试停止或暂停录制前需检查
```
isRecording
```
状态。UI状态更新需处理
```
VideoRecordEvent.Start
```
事件，而非仅依赖初始调用。
线程安全：相机回调通常在后台执行器上运行，需将UI更新调度至主线程。
权限处理：检查
```
CAMERA
```
权限；当在
```
VideoCapture
```
中启用音频时，需专门检查
```
RECORD_AUDIO
```
权限。