/mobile-camera-vision-camera

name: mobile-camera-vision-camera
description: VisionCamera v4+ - photo/video capture, QR/barcode scanning, real-time frame processors, zoom/focus/exposure, HDR, location metadata, format selection

VisionCamera Patterns

> **Quick Guide:** Use VisionCamera for high-performance camera features in React Native. Control the camera lifecycle with `isActive` (never unmount/remount). Use `useCameraDevice` to select back/front cameras, `useCameraPermission` for permissions. Capture photos with `takePhoto()`, record video with `startRecording()`/`stopRecording()`, scan codes with `useCodeScanner`, and process frames in real time with `useFrameProcessor` worklets. Frame processors run on a parallel JS thread via JSI -- keep them fast or use `runAsync`/`runAtTargetFps` to avoid blocking the pipeline.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST set `isActive` based on screen focus AND app state -- camera must pause when backgrounded or navigated away)**

**(You MUST request permissions before rendering the Camera -- `useCameraPermission` returns `hasPermission` and `requestPermission`)**

**(You MUST include the `'worklet'` directive as the first line of every frame processor function body)**

**(You MUST enable only the pipelines you need (`photo`, `video`, `codeScanner`, `frameProcessor`) -- unused pipelines waste resources)**

**(You MUST use `useSharedValue` (not `useState`) for data shared between frame processors and the React thread)**

</critical_requirements>

---

**Auto-detection:** VisionCamera, react-native-vision-camera, useCameraDevice, useCameraDevices, useCameraPermission, useMicrophonePermission, useCodeScanner, useFrameProcessor, useSkiaFrameProcessor, useCameraFormat, takePhoto, takeSnapshot, startRecording, stopRecording, Camera component, frame processor, worklet, codeScanner, photoQualityBalance, enableLocation, videoHdr, photoHdr

**When to use:**

• Capturing photos or recording video in a React Native app
• Scanning QR codes or barcodes (EAN-13, Code-128, etc.)
• Real-time frame processing for ML, object detection, or image analysis
• Implementing zoom, focus, exposure, or HDR controls
• Embedding GPS location metadata in captured media
• Selecting specific camera devices (ultra-wide, telephoto, front/back)

**When NOT to use:**

• Picking images from the device gallery (use an image picker)
• Simple static image display (use standard Image component)
• Web-only camera access (use browser MediaDevices API)

**Key patterns covered:**

• Camera lifecycle management with `isActive` and screen/app state
• Permission handling with hooks (`useCameraPermission`, `useMicrophonePermission`)
• Photo capture (`takePhoto`, `takeSnapshot`) and video recording
• QR/barcode scanning with `useCodeScanner`
• Frame processors with worklets, `runAsync`, and `runAtTargetFps`
• Device selection, format selection, zoom, focus, exposure, HDR
• Location metadata embedding
• Performance optimization (pipeline selection, buffer compression, pixel format)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Camera setup, permissions, lifecycle, photo capture, video recording
• [examples/scanning-and-processing.md](examples/scanning-and-processing.md) - Code scanning, frame processors, worklet patterns
• [reference.md](reference.md) - Decision frameworks, device/format selection, performance checklist

---

<philosophy>

Philosophy

VisionCamera provides direct, high-performance camera access in React Native via JSI (JavaScript Interface). It bypasses the legacy bridge entirely, giving synchronous control over native camera hardware from JavaScript.

**Core principles:**

1. **Lifecycle-driven** -- the `isActive` prop controls the camera session. Toggle it instead of mounting/unmounting. Resuming is much faster than re-mounting. 2. **Pipeline-based** -- enable only what you need (`photo`, `video`, `codeScanner`, frame processor). Each pipeline allocates resources. 3. **Worklet-powered** -- frame processors run on a parallel JS thread via `react-native-worklets-core`. They execute synchronously in the video pipeline, so they must be fast. 4. **Device/format-aware** -- different physical cameras and formats have different capabilities. Always check device and format properties before enabling features like HDR or high FPS.

**When to use VisionCamera:**

• You need camera preview with capture, scanning, or real-time processing
• You need fine-grained control over device, format, zoom, focus, exposure
• You need frame-level access for ML inference or custom image processing

**When NOT to use:**

• Gallery/file picking (different concern entirely)
• Screenshot or screen recording (not camera-related)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Camera Lifecycle and Permissions

The camera must be activated only when the screen is focused AND the app is in the foreground. Always check permissions before rendering.

import { useCameraDevice, useCameraPermission, Camera } from "react-native-vision-camera";
import { StyleSheet } from "react-native";

export function CameraScreen() {
  const device = useCameraDevice("back");
  const { hasPermission, requestPermission } = useCameraPermission();

  // Request permission on mount if not granted
  // Render permission UI or Camera based on hasPermission

  if (!hasPermission) return <PermissionRequest onRequest={requestPermission} />;
  if (device == null) return <NoCameraDeviceError />;

  return <Camera style={StyleSheet.absoluteFill} device={device} isActive={isActive} />;
}

**Why good:** permission checked before render, device null-checked, isActive controls lifecycle without unmounting

The `isActive` prop should combine screen focus and app state:

const isFocused = useIsFocused(); // from navigation
const appState = useAppState(); // from community hooks
const isActive = isFocused && appState === "active";

See [examples/core.md](exa