react-native-vision-camera

react-native-vision-camera (v5)

VisionCamera v5 は、メンテナンスが継続されている react-native-vision-camera の最新バージョンです。新しい Constraints API、Output ベースのアーキテクチャ、メモリ内 Photo を備えた、Nitro Modules による全面的な書き換え版であり、v4 のフォーマット／プロパティモデルとは互換性がありません。v4 の機能のほとんどは削除または名称変更されています。v5 は段階的なアップグレードではなく、新しい API として扱ってください。

このスキルはルーターです。まずこのファイルを読み、次にタスクに合ったリファレンスを読み込んでください。各リファレンスは単独で完結しています。必要以上に読み込まないでください。

どのリファレンスを読み込むか

• 本番環境での低レイテンシな GPU、ML、CV、またはフレーム連動オーバーレイの作業： 専用の react-native-vision-camera-realtime スキルを使用してください。セットアップや API の基本も必要な場合に限り、基本的なフレーム処理のリファレンスも読み込んでください。
• 新規インストール、画面への Camera の表示、権限、最小限のボイラープレート → references/quickstart-v5.md
• v4 のコードベースの移行、変更点の確認 → references/migration-v4-to-v5.md（ユーザーが v4、takePhoto、useCameraFormat、format プロパティ、photo/video のブール値プロパティ、または core の CodeScanner に言及した場合は、最初に読み込んでください）
• v4 の画面全体の移行 — 移植できる完全な変更前／変更後のファイルが必要な場合 → references/migration-templates.md（写真画面、動画画面、フレームプロセッサー＋ML、バーコードスキャナー、プロ向けカメラのコピー＆ペースト可能な完全なテンプレート）
• 出力の選択／アタッチ、制約による fps／HDR／解像度の設定、セッションのライフサイクル → references/outputs-and-constraints.md
• フレームプロセッサー、worklet、非同期フレーム処理、ピクセル形式、ネイティブプラグインの作成 → references/frame-processors.md（ユーザーが「frame processor」「worklet」「ML on frames」「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 コードで譲れないルール

これらは、v4 を「知っている」人が見落としやすいルールです。確認を求めずに適用してください。

1. 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/

2. outputs={[...]} は photo ／ video ／ frameProcessor ／ codeScanner プロパティに置き換わります。 usePhotoOutput、useVideoOutput、useFrameOutput、useDepthOutput、useObjectOutput（またはバーコードパッケージの useBarcodeScannerOutput）で出力を作成し、配列で渡してください。キャプチャメソッド（capturePhoto、createRecorder）は Camera の ref ではなく、Output にあります。

3. format プロパティも useCameraFormat もありません。 constraints={[...]} を使用してください。配列の順序が優先度を表し、先頭ほど優先されます。Camera は最も近い対応設定を自動でネゴシエートするため、{ fps: 99999 } のような実現不可能な制約を指定しても、エラーにはなりません。

4. takePhoto() はありません。 メモリー上の Photo を取得するには photoOutput.capturePhoto(settings, callbacks) を、ファイルパスを取得するには photoOutput.capturePhotoToFile(...) を使用してください。デフォルトはメモリー上への保存です。明示的に求められない限り、一時ファイルを書き込まないでください。

5. フレームプロセッサのプラグインは Nitro Modules である必要があります。 v4 の FrameProcessorPlugin 基底クラス、VISION_EXPORT_SWIFT_FRAME_PROCESSOR マクロ、VisionCameraProxy.addFrameProcessorPlugin は廃止されています。v5 のプラグインは、型付きの Nitro 仕様を持つ HybridObject です。references/frame-processors.md を参照してください。

6. すべての Frame（および Depth）で必ず .dispose() を呼び出してください。 バッファプールには上限があるため、フレームを解放し忘れるとパイプラインが停止します。処理は try { ... } finally { frame.dispose() } で囲んでください。asyncRunner.runAsync(...) で処理をオフロードする場合、戻り値が true なら非同期コールバック内で破棄し、false なら else 分岐で直ちに破棄してください。

7. CodeScanner はコアに含まれていません。 react-native-vision-camera-barcode-scanner は独立したパッケージで、両プラットフォームで MLKit を使用します。ML 依存なしで、ネイティブの AVFoundation メタデータを使った iOS 専用の物体検出（QR、顔、人体）には、コアの useObjectOutput を使用してください。

8. Camera はマウントしたままにして、isActive を切り替えてください。 再マウントするとセッションが破棄されます。react-navigation の useIsFocused() と連携し、画面に表示されていない間はセッションを Idle → Ready に移行させ、すぐに再開できるよう設定を維持してください。

9. フレーム出力の pixelFormat のデフォルトは 'native'（ゼロコピー）であり、'yuv' ではありません。 'native' は、セッションでネゴシエートされた nativePixelFormat を変換なしでストリーミングします（YUV、RGB、RAW、または 'private' 形式になる場合があります。実際の形式は frame.pixelFormat で確認してください）。'yuv' はネイティブ形式に最も近い YUV 形式を選び、CPU で利用できる一般的な用途に最適です（MLKit／OpenCV／Skia）。'rgb' は YUV から RGB への変換を強制し、帯域幅が約 2.6 倍になるため、利用側で RGB が必須の場合にのみ使用してください。useDepthOutput に pixelFormat オプションはありません。CPU からアクセスできる RGB またはテンソル入力を必要とする ML 利用側には、Camera パイプラインでフレームごとの RGB 変換コストを負担するより、react-native-vision-camera-resizer を優先してください。

10. Math.min/Math.max で FPS や解像度を手動で制限しないでください。 これは v4 の回避策でした。v5 では Constraints API が内部でネゴシエートするため、意図を指定して Camera に選択を任せてください。

11. v5 では Worklets が Reanimated SharedValues を直接変更します。 通常の非同期 UI やアニメーションの状態には適しています。フレームに同期したオーバーレイには、別途リアルタイム向けのスキルを使用し、同じフレームから Skia または WebGPU で描画してください。

このスキルの運用ルール

• v4→v5 の API 形式を決して捏造しないでください。v4 API に対応する v5 の仕様がリファレンスに記載されていない場合は、その旨を伝えて v5 のドキュメントへのリンクを示し、推測しないでください。

• ユーザーから依頼されない限り、ドキュメントファイル（README、CHANGELOG）を追加しないでください。

• ユーザーが v4 のコードを提示していない限り、v5 を使用しているものとします。v4 のコードが提示された場合は、何かを書く前に references/migration-v4-to-v5.md を読み込んでください。

• Camera の新しいサンプルを書く場合は、フックベースの宣言的な形式（useCameraPermission + useCameraDevice + usePhotoOutput + <Camera />）をデフォルトにしてください。命令型の VisionCamera.createCameraSession(...) API を使用するのは、ユーザーがマルチカメラや完全なプログラム制御を求めた場合に限ります。

• CPU から参照できる入力を必要とする基本的な ML パスには、v4 時代の vision-camera-resize-plugin ではなく react-native-vision-camera-resizer を推奨してください。レイテンシーが重要な ML、GPU 推論、ライブオーバーレイには、Resizer を一律に指定せず、react-native-vision-camera-realtime を案内してください。

• ピア依存関係のインストールを確認してください。インストール後にネイティブクラッシュが発生したという報告の 95% は、react-native-nitro-modules、react-native-nitro-image、または（フレームプロセッサーの場合）react-native-worklets と react-native-vision-camera-worklets のインストール漏れが原因です。

信頼できるリンク

• ドキュメント：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