react-native-vision-camera

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

react-native-vision-camera (v5)

VisionCamera v5 is the maintained and latest version of

react-native-vision-camera

. It is a full Nitro Modules rewrite with a new Constraints API, Output-based architecture, in-memory
Photo
, and a hard break from the v4 format/prop model. Almost every v4 surface is gone or renamed — treat v5 as a new API, not an incremental upgrade.

This skill is a router. Read this file first, then load the reference that matches the task. Every reference is self-contained — do not load more than you need.

VisionCamera v5是

react-native-vision-camera

的最新维护版本。它基于Nitro Modules完全重写，拥有全新的Constraints API、基于输出的架构、内存中的
Photo
对象，并且彻底摒弃了v4的格式/属性模型。几乎所有v4的接口都已移除或重命名——请将v5视为全新API，而非增量升级。

本技能是一个导航工具。请先阅读本文档，再加载与任务匹配的参考文档。每个参考文档都是独立的——无需加载超出需求的内容。

When to load which reference

何时加载对应参考文档

New install, getting a Camera on screen, permissions, minimum boilerplate → references/quickstart-v5.md
Porting a v4 codebase, understanding what changed → references/migration-v4-to-v5.md (load this FIRST when the user mentions v4, takePhoto, useCameraFormat, format prop, photo/video boolean props, or CodeScanner in core)
Choosing/attaching outputs, fps/HDR/resolution via constraints, session lifecycle → references/outputs-and-constraints.md
Frame Processors, worklets, async frame work, pixel formats, writing a native plugin → references/frame-processors.md (load this when user says "frame processor", "worklet", "ML on frames", "Nitro plugin", "vision-camera-plugin-*")
Capturing photos (incl. callbacks, RAW, HDR, preview image), recording video, Recorder lifecycle, manual AE/AF/AWB, exposure bias, zoom, focus → references/capture-and-controls.md
Depth streaming, multi-cam, Skia preview, GPU resizer for ML, barcode scanner package, GPS location metadata, custom native outputs → references/advanced-features.md

When in doubt, load references/migration-v4-to-v5.md — it covers the shape of the new API by contrasting it with v4 and is the fastest orientation.

全新安装、在屏幕上显示相机、权限配置、最小化样板代码 → references/quickstart-v5.md
迁移v4代码库、了解版本变更 → references/migration-v4-to-v5.md（当用户提及v4、takePhoto、useCameraFormat、format属性、photo/video布尔属性或核心中的CodeScanner时，请优先加载此文档）
选择/附加输出、通过约束配置帧率/HDR/分辨率、会话生命周期 → references/outputs-and-constraints.md
帧处理器、worklets、异步帧处理、像素格式、编写原生插件 → references/frame-processors.md（当用户提到“frame processor”、“worklet”、“帧上运行ML”、“Nitro plugin”、“vision-camera-plugin-*”时加载此文档）
拍摄照片（包括回调、RAW、HDR、预览图像）、录制视频、Recorder生命周期、手动AE/AF/AWB、曝光补偿、缩放、对焦 → references/capture-and-controls.md
深度流、多相机、Skia预览、用于ML的GPU调整器、条码扫描器包、GPS位置元数据、自定义原生输出 → references/advanced-features.md

若不确定，加载references/migration-v4-to-v5.md即可——它通过与v4对比介绍新API的结构，是快速熟悉v5的最佳方式。

Non-negotiable rules for v5 code

v5代码的硬性规则

These are the rules that catch people who "know" v4. Apply them without asking:

Install the Nitro peers.
```
react-native-nitro-modules
```
and
```
react-native-nitro-image
```
are required peer deps. Frame processors additionally require
```
react-native-vision-camera-worklets
```
AND
```
react-native-worklets
```
(Software Mansion's — not
```
-core
```
). Worklets - https://docs.swmansion.com/react-native-worklets/docs/

outputs={[...]}
replaces
photo
/
video
/
frameProcessor
/
codeScanner
props. Create outputs with

usePhotoOutput

useVideoOutput

useFrameOutput

useDepthOutput

useObjectOutput

(or

useBarcodeScannerOutput

from the barcode package) and pass them in an array. Capture methods (

capturePhoto

createRecorder

) live on the Output, not the Camera ref.

There is no
format
prop and no
useCameraFormat
. Use
```
constraints={[...]}
```
— array order = priority, descending. The Camera negotiates the closest supported config automatically, so an impossible constraint like
```
{ fps: 99999 }
```
never throws.
takePhoto()
does not exist. Use
```
photoOutput.capturePhoto(settings, callbacks)
```
for in-memory
```
Photo
```
, or
```
photoOutput.capturePhotoToFile(...)
```
for a file path. The default path is in-memory — do not write temp files unless explicitly asked.
Frame Processor plugins must be Nitro Modules. The v4
```
FrameProcessorPlugin
```
base class,
```
VISION_EXPORT_SWIFT_FRAME_PROCESSOR
```
macro, and
```
VisionCameraProxy.addFrameProcessorPlugin
```
are gone. A v5 plugin is a
```
HybridObject
```
with a typed Nitro spec. See references/frame-processors.md.
Every
Frame
(and
Depth
) MUST be
.dispose()
d. The buffer pool is bounded; leaking a frame stalls the pipeline. Wrap work in
```
try { ... } finally { frame.dispose() }
```
. When offloading via
```
asyncRunner.runAsync(...)
```
, dispose inside the async callback if it returned
```
true
```
, and dispose immediately in the
```
else
```
branch when it returned
```
false
```
.
CodeScanner is not in core.
```
react-native-vision-camera-barcode-scanner
```
is a separate package, MLKit-based on both platforms. For iOS-only object detection (QR, faces, bodies via native AVFoundation metadata, no ML dep), use
```
useObjectOutput
```
from core.
Keep the Camera mounted; toggle
isActive
. Remounting tears down the session. Integrate with
```
useIsFocused()
```
from react-navigation so the session goes Idle → Ready while not on screen, and keeps preferences warm for fast resume.
Prefer YUV in Frame/Depth outputs.
```
pixelFormat: 'yuv'
```
is the native path and the default.
```
'rgb'
```
forces a YUV→RGB conversion; use only when a downstream consumer requires it. Use
```
react-native-vision-camera-resizer
```
for GPU-accelerated YUV→RGB resize into an ML tensor instead of paying that cost in the camera pipeline.
Do not hand-clamp FPS/resolution with
Math.min/Math.max
. That was a v4 workaround. In v5 the Constraints API negotiates internally — express intent and let the Camera pick.
Worklets mutate Reanimated SharedValues directly in v5. The worklets-core bridge is gone; no
```
runOnJS
```
round-trip required to update a Reanimated
```
SharedValue
```
from a frame processor.

这些规则针对熟悉v4的用户，需严格遵守：

安装Nitro依赖包。
```
react-native-nitro-modules
```
和
```
react-native-nitro-image
```
是必需的对等依赖。帧处理器还额外需要
```
react-native-vision-camera-worklets
```
和
```
react-native-worklets
```
（Software Mansion出品——注意不是
```
-core
```
版本）。Worklets文档：https://docs.swmansion.com/react-native-worklets/docs/
outputs={[...]}
替代
photo
/
video
/
frameProcessor
/
codeScanner
属性。使用
```
usePhotoOutput
```
、
```
useVideoOutput
```
、
```
useFrameOutput
```
、
```
useDepthOutput
```
、
```
useObjectOutput
```
（或条码包中的
```
useBarcodeScannerOutput
```
）创建输出，并将它们以数组形式传入。拍摄方法（
```
capturePhoto
```
、
```
createRecorder
```
）属于Output对象，而非Camera引用。
不存在
format
属性和
useCameraFormat
。使用
```
constraints={[...]}
```
——数组顺序代表优先级，降序排列。相机会自动协商最接近的支持配置，因此像
```
{ fps: 99999 }
```
这样不可能的约束不会抛出错误。
takePhoto()
已不存在。使用
```
photoOutput.capturePhoto(settings, callbacks)
```
获取内存中的
```
Photo
```
对象，或使用
```
photoOutput.capturePhotoToFile(...)
```
获取文件路径。默认路径是内存中——除非明确要求，否则不要写入临时文件。
帧处理器插件必须是Nitro Modules。v4的
```
FrameProcessorPlugin
```
基类、
```
VISION_EXPORT_SWIFT_FRAME_PROCESSOR
```
宏以及
```
VisionCameraProxy.addFrameProcessorPlugin
```
均已移除。v5插件是带有类型化Nitro规范的
```
HybridObject
```
。详见references/frame-processors.md。
每个
Frame
（和
Depth
）必须调用
.dispose()
。缓冲池是有界的；泄露帧会导致流水线停滞。将代码包裹在
```
try { ... } finally { frame.dispose() }
```
中。当通过
```
asyncRunner.runAsync(...)
```
卸载任务时，如果返回
```
true
```
，则在异步回调中释放；如果返回
```
false
```
，则在
```
else
```
分支中立即释放。
CodeScanner不在核心库中。
```
react-native-vision-camera-barcode-scanner
```
是独立包，双平台均基于MLKit。若仅需iOS平台的对象检测（QR码、人脸、人体，基于原生AVFoundation元数据，无ML依赖），请使用核心库中的
```
useObjectOutput
```
。
保持Camera挂载，切换
isActive
状态。重新挂载会销毁会话。结合react-navigation的
```
useIsFocused()
```
，使会话在不在屏幕上时进入Idle→Ready状态，并保留偏好设置以实现快速恢复。
Frame/Depth输出优先选择YUV格式。
```
pixelFormat: 'yuv'
```
是原生路径，也是默认值。
```
'rgb'
```
会强制进行YUV→RGB转换；仅当下游消费者需要时才使用。使用
```
react-native-vision-camera-resizer
```
进行GPU加速的YUV→RGB调整，转换为ML张量，而非在相机流水线中承担转换成本。
不要用
Math.min/Math.max
手动限制帧率/分辨率。这是v4的临时解决方案。v5的Constraints API会内部协商——只需表达需求，由相机选择即可。
Worklets在v5中直接修改Reanimated SharedValues。worklets-core桥已移除；从帧处理器更新Reanimated
```
SharedValue
```
无需
```
runOnJS
```
往返调用。

Operating rules for this skill

本技能的操作规则

Never invent v4→v5 API shapes. If a v4 API has no documented v5 equivalent in the references, say so and link to the v5 docs — do not guess.
Do not add documentation files (README, CHANGELOG) unless the user asks.
Assume the user is on v5 unless they show v4 code. If they show v4 code, load references/migration-v4-to-v5.md before writing anything.
When writing a new Camera example, default to the hook-based declarative form (
```
useCameraPermission
```
+
```
useCameraDevice
```
+
```
usePhotoOutput
```
+
```
<Camera />
```
). Use the imperative
```
VisionCamera.createCameraSession(...)
```
API only when the user asks for multi-cam or full programmatic control.
When the user asks for an ML / CV pipeline, recommend
```
react-native-vision-camera-resizer
```
(GPU, ~5× faster than CPU/SIMD) over
```
vision-camera-resize-plugin
```
(v4-era, CPU).
Verify peer dependency installs. A user reporting a native crash after install 95% of the time has missed
```
react-native-nitro-modules
```
,
```
react-native-nitro-image
```
, or (for frame processors)
```
react-native-worklets
```
+
```
react-native-vision-camera-worklets
```
.

切勿自行编造v4→v5的API映射。如果v4的API在参考文档中没有对应的v5实现，请告知用户并链接到v5文档——不要猜测。
除非用户要求，否则不要添加文档文件（README、CHANGELOG）。
除非用户展示v4代码，否则默认用户使用v5。如果用户展示v4代码，在编写任何内容前先加载references/migration-v4-to-v5.md。
编写新的Camera示例时，默认使用基于Hook的声明式形式（
```
useCameraPermission
```
+
```
useCameraDevice
```
+
```
usePhotoOutput
```
+
```
<Camera />
```
）。仅当用户要求多相机或完全程序化控制时，才使用命令式的
```
VisionCamera.createCameraSession(...)
```
API。
当用户询问ML/CV流水线时，推荐使用
```
react-native-vision-camera-resizer
```
（GPU加速，比CPU/SIMD快约5倍），而非
```
vision-camera-resize-plugin
```
（v4时代，CPU处理）。
验证对等依赖的安装情况。用户在安装后报告原生崩溃，95%的情况是遗漏了
```
react-native-nitro-modules
```
、
```
react-native-nitro-image
```
，或者（针对帧处理器）
```
react-native-worklets
```
+
```
react-native-vision-camera-worklets
```
。

Authoritative links

权威链接

Docs: https://visioncamera.margelo.com
```
llms.txt
```
index: https://visioncamera.margelo.com/llms.txt

V5 release notes (includes migration snippets):

gh api repos/mrousavy/react-native-vision-camera/releases/tags/v5.0.0

Blog announcement: https://blog.margelo.com/whats-new-in-visioncamera-v5
Main repo: https://github.com/mrousavy/react-native-vision-camera
V4 snapshot (archived docs): https://visioncamera4.margelo.com

文档：https://visioncamera.margelo.com
```
llms.txt
```
索引：https://visioncamera.margelo.com/llms.txt

V5发布说明（包含迁移代码片段）：

gh api repos/mrousavy/react-native-vision-camera/releases/tags/v5.0.0

博客公告：https://blog.margelo.com/whats-new-in-visioncamera-v5
主仓库：https://github.com/mrousavy/react-native-vision-camera
V4快照（归档文档）：https://visioncamera4.margelo.com