react-native-vision-camera
Best-practices guide for React Native VisionCamera v5 setup, migration, capture, controls, outputs, and basic frame processing. Use the separate react-native-vision-camera-realtime skill for production low-latency GPU, ML, CV, Skia or WebGPU pipelines and frame-coupled overlays.
margelo · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add margelo/react-native-skills --skill react-native-vision-camera技能说明
name: react-native-vision-camera description: Best-practices guide for React Native VisionCamera v5 setup, migration, capture, controls, outputs, and basic frame processing. Use the separate react-native-vision-camera-realtime skill for production low-latency GPU, ML, CV, Skia or WebGPU pipelines and frame-coupled overlays.
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.
When to load which reference
- Production low-latency GPU, ML, CV, or frame-coupled overlay work: use the separate
react-native-vision-camera-realtimeskill. Load the basic frame-processing reference too only when setup or API fundamentals are also needed. - 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)
- Porting a whole v4 screen — want a complete before/after file to transplant → references/migration-templates.md (full copy-paste templates: photo screen, video screen, frame-processor+ML, barcode scanner, pro camera)
- 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.
Non-negotiable rules for v5 code
These are the rules that catch people who "know" v4. Apply them without asking:
- Install the Nitro peers.
react-native-nitro-modulesandreact-native-nitro-imageare required peer deps. Frame processors additionally requirereact-native-vision-camera-workletsANDreact-native-worklets(Software Mansion's — not-core). Worklets - https://docs.swmansion.com/react-native-worklets/docs/ outputs={[...]}replacesphoto/video/frameProcessor/codeScannerprops. Create outputs withusePhotoOutput,useVideoOutput,useFrameOutput,useDepthOutput,useObjectOutput(oruseBarcodeScannerOutputfrom the barcode package) and pass them in an array. Capture methods (capturePhoto,createRecorder) live on the Output, not the Camera ref.- There is no
formatprop and nouseCameraFormat. Useconstraints={[...]}— 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. UsephotoOutput.capturePhoto(settings, callbacks)for in-memoryPhoto, orphotoOutput.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
FrameProcessorPluginbase class,VISION_EXPORT_SWIFT_FRAME_PROCESSORmacro, andVisionCameraProxy.addFrameProcessorPluginare gone. A v5 plugin is aHybridObjectwith a typed Nitro spec. See references/frame-processors.md. - Every
Frame(andDepth) MUST be.dispose()d. The buffer pool is bounded; leaking a frame stalls the pipeline. Wrap work intry { ... } finally { frame.dispose() }. When offloading viaasyncRunner.runAsync(...), dispose inside the async callback if it returnedtrue, and dispose immediately in theelsebranch when it returnedfalse. - CodeScanner is not in core.
react-native-vision-camera-barcode-scanneris a separate package, MLKit-based on both platforms. For iOS-only object detection (QR, faces, bodies via native AVFoundation metadata, no ML dep), useuseObjectOutputfrom core. - Keep the Camera mounted; toggle
isActive. Remounting tears down the session. Integrate withuseIsFocused()from react-navigation so the session goes Idle → Ready while not on screen, and keeps preferences warm for fast resume. - Frame output
pixelFormatdefaults to'native'(zero-copy), NOT'yuv'.'native'streams in the session's negotiatednativePixelFormatwith zero conversions (it may resolve to a YUV, RGB, RAW, or'private'format; verify the actual one viaframe.pixelFormat).'yuv'picks the YUV format closest to native and is the best general-purpose CPU-accessible choice (MLKit/OpenCV/Skia);'rgb'forces a YUV-to-RGB conversion with about 2.6 times more bandwidth, so use it only when a consumer hard-requires RGB.useDepthOutputhas nopixelFormatoption. For ML consumers that require CPU-visible RG