# flyskywhy/react-native-uvc-camera architecture

> Architecture diagram of the GitHub repository flyskywhy/react-native-uvc-camera, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flyskywhy/react-native-uvc-camera
- Repository: https://github.com/flyskywhy/react-native-uvc-camera

## Overview

##### Project type and purpose
- This is an open-source React Native plugin module (“react-native-uvc-camera”) targeting Android.
- Its purpose is to expose UVC (USB Video Class) camera capture and recording functionality to a React Native app by wrapping native Android/NDK libraries (UVCCamera, libuvccamera, libusb, libuvc, libjpeg-turbo, RapidJSON) behind the React Native bridge.

##### Top-level components (modules)
- JS Layer (src/*.js, index.js) – the React Native component and API surface.
- Android Java Module (“android”) – React Package, CameraViewManager, RCTCameraModule, UVC camera support (Camera1, Camera2, CameraUvc).
- Shared Java helper library (“usbCameraCommon”) – media encoders, muxers, UVCCamera handlers, view widgets.
- Native C/C++ Library (“libuvccamera”) – JNI wrappers, UVCCamera pipelines, integration of libusb/libuvc/libjpeg-turbo/RapidJSON.
- Example/Test Apps (usbCameraTest*, usbCameraTest0…usbCameraTest8) – sample Android apps illustrating use cases and test harnesses.

##### Key interactions and data flow
a. React Native JS Component
- Calls native methods via React Native Bridge (RCTBridgeModule).
b. Android Java Module
- Exposes methods & events (takePicture, startPreview, onBarCodeRead, etc.) to JS.
- Manages lifecycle of CameraView (CameraViewManager, RNCameraView).
- Delegates camera startup/stop to UVCCamera APIs.
c. Shared Java Library (usbCameraCommon)
- Handles USB device enumeration, permission requests, UVC camera control (UVCCameraHandler).
- Manages media encoding (MediaVideoEncoder, MediaAudioEncoder) and muxing (MediaMuxerWrapper).
d. JNI / Native Layer (libuvccamera)
- Provides native entrypoints (ndkBuild) to compile UVCCamera & its dependencies.
- Implements buffered pipelines (PreviewPipeline, CallbackPipeline, SQLiteBufferedPipeline) for frame processing.
- Integrates libusb for device communication, libuvc for UVC protocols, libjpeg-turbo for JPEG encoding, RapidJSON for JSON config/diagnostics.
e. Android USB Stack & Hardware
- The Android OS USB manager grants access to UVC device nodes.
- libusb communicates with USB endpoints; libuvc implements UVC control & streaming.
- Frames pass through C++ pipelines back to Java via JNI callbacks, then to JS events.

##### Architectural patterns & design principles
- Layered architecture: UI (JS) → Bridge → Java API → JNI → Native C/C++ → OS/Hardware.
- Separation of concerns:
- JS layer purely UI & API calls, no native details.
- Java layer handles Android lifecycle, permissions, basic camera control.
- Shared library isolates encoding & view abstractions.
- Native C/C++ layer focuses on device protocols & high-performance pipeline.
- Plugin pattern: Gradle multi-project with Android modules plugged into host application.
- JNI boundary clearly defined: thin Java wrappers invoking ndkBuild-compiled libs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% React Native JS Layer
    subgraph "React Native JS Layer"
        direction TB
        JS_Index["index.js"]:::js
        JS_Uvc["UvcCamera.js"]:::js
        JS_Face["FaceDetector.js"]:::js
        JS_Perm["handlePermissions.js"]:::js
    end

    %% Bridge
    RCTBridge["RCTBridge (React Native Bridge)"]:::bridge

    %% Android Java Module
    subgraph "Android Java Module"
        direction TB
        Cam_Module["CameraModule.java"]:::java
        Cam_ViewMgr["CameraViewManager.java"]:::java
        RN_Package["RNCameraPackage.java"]:::java
        RCT_Module["RCTCameraModule.java"]:::java
        RCT_ViewMgr["RCTCameraViewManager.java"]:::java
        Cam_UVC["CameraUvc.java"]:::java
    end

    %% Shared Java Helper Library
    subgraph "usbCameraCommon Library"
        direction TB
        UVCC_Handler["UVCCameraHandler.java"]:::sharedjava
        Vid_Encoder["MediaVideoEncoder.java"]:::sharedjava
        Aud_Encoder["MediaAudioEncoder.java"]:::sharedjava
        Muxer["MediaMuxerWrapper.java"]:::sharedjava
        Texture_View["UVCCameraTextureView.java"]:::sharedjava
    end

    %% Native C/C++ Library
    subgraph "libuvccamera Native Layer"
        direction TB
        UVCCpp["UVCCamera.cpp"]:::native
        OnLoad["_onload.cpp"]:::native
        Preview_PP["PreviewPipeline.cpp"]:::native
        Callback_PP["CallbackPipeline.cpp"]:::native
        SQ_PP["SQLiteBufferedPipeline.cpp"]:::native
        subgraph "Native Dependencies"
            direction TB
            Libusb["libusb"]:::deps
            Libuvc["libuvc"]:::deps
            JPEG["libjpeg-turbo-1.5.0"]:::deps
            RapidJSON["rapidjson"]:::deps
        end
    end

    %% OS/Hardware
    OS_HW["Android OS USB Stack\n& Hardware"]:::hardware

    %% Example/Test Apps
    subgraph "Example/Test Apps"
        direction TB
        classDef example stroke-dasharray: 5 5
        Test0["usbCameraTest"]:::example
        Test1["usbCameraTest0"]:::example
        Test2["usbCameraTest2"]:::example
        Test3["usbCameraTest3"]:::example
        Test4["usbCameraTest4"]:::example
        Test5["usbCameraTest5"]:::example
        Test6["usbCameraTest6"]:::example
        Test7["usbCameraTest7"]:::example
        Test8["usbCameraTest8"]:::example
    end

    %% Connections: Control Flow
    JS_Index -->|calls API| RCTBridge
    JS_Uvc -->|calls API| RCTBridge
    JS_Face -->|calls API| RCTBridge
    JS_Perm -->|calls API| RCTBridge

    RCTBridge -->|invokes| Cam_Module
    RCTBridge -->|invokes| Cam_ViewMgr
    RCTBridge -->|invokes| RN_Package
    RCTBridge -->|invokes| RCT_Module
    RCTBridge -->|invokes| RCT_ViewMgr
    RCTBridge -->|invokes| Cam_UVC

    %% Java to Shared Java
    Cam_UVC -->|uses| UVCC_Handler
    Cam_Module -->|encodes/decodes| Vid_Encoder
    Cam_Module -->|encodes/decodes| Aud_Encoder
    Cam_Module -->|muxes| Muxer
    Cam_ViewMgr -->|renders| Texture_View

    %% Shared Java to Native
    UVCC_Handler -->|JNI calls| UVCCpp
    UVCC_Handler -->|JNI calls| OnLoad
    Vid_Encoder -->|pipeline| Preview_PP
    Aud_Encoder -->|pipeline| Callback_PP
    Muxer -->|pipeline| SQ_PP

    %% Native to Dependencies
    Preview_PP -->|streams| Libusb
    Preview_PP -->|streams| Libuvc
    Callback_PP -->|encodes| JPEG
    SQ_PP -->|parses| RapidJSON

    %% Dependencies to OS
    Libusb -->|communicates| OS_HW
    Libuvc -->|controls| OS_HW
    JPEG -->|encodes| OS_HW
    RapidJSON -->|config| OS_HW

    %% Data Flow Back Up
    OS_HW -->|frames| Libusb
    Libusb --> Preview_PP
    Preview_PP --> UVCCpp
    UVCCpp --> UVCC_Handler
    UVCC_Handler --> Cam_UVC
    Cam_UVC --> RCTBridge
    RCTBridge --> JS_Uvc

    %% Example Apps use plugin
    Test0 -->|depends on| Cam_Module
    Test1 -->|depends on| UVCC_Handler
    Test2 -->|depends on| UVCCpp

    %% Click Events
    click JS_Index "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/src/index.js"
    click JS_Uvc "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/src/UvcCamera.js"
    click JS_Face "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/src/FaceDetector.js"
    click JS_Perm "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/src/handlePermissions.js"
    click Cam_Module "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/android/src/main/java/org/reactnative/camera/CameraModule.java"
    click Cam_ViewMgr "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/android/src/main/java/org/reactnative/camera/CameraViewManager.java"
    click RN_Package "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/android/src/main/java/org/reactnative/camera/RNCameraPackage.java"
    click RCT_Module "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/android/src/main/java/com/lwansbrough/RCTCamera/RCTCameraModule.java"
    click RCT_ViewMgr "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/android/src/main/java/com/lwansbrough/RCTCamera/RCTCameraViewManager.java"
    click Cam_UVC "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/android/src/main/java/com/google/android/cameraview/CameraUvc.java"
    click UVCC_Handler "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/usbCameraCommon/src/main/java/com/serenegiant/usbcameracommon/UVCCameraHandler.java"
    click Vid_Encoder "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/usbCameraCommon/src/main/java/com/serenegiant/encoder/MediaVideoEncoder.java"
    click Aud_Encoder "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/usbCameraCommon/src/main/java/com/serenegiant/encoder/MediaAudioEncoder.java"
    click Muxer "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/usbCameraCommon/src/main/java/com/serenegiant/encoder/MediaMuxerWrapper.java"
    click Texture_View "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/usbCameraCommon/src/main/java/com/serenegiant/widget/UVCCameraTextureView.java"
    click UVCCpp "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/libuvccamera/src/main/jni/UVCCamera/UVCCamera.cpp"
    click OnLoad "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/libuvccamera/src/main/jni/UVCCamera/_onload.cpp"
    click Preview_PP "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/libuvccamera/src/main/jni/UVCCamera/pipeline/PreviewPipeline.cpp"
    click Callback_PP "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/libuvccamera/src/main/jni/UVCCamera/pipeline/CallbackPipeline.cpp"
    click SQ_PP "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/libuvccamera/src/main/jni/UVCCamera/pipeline/SQLiteBufferedPipeline.cpp"
    click Libusb "https://github.com/flyskywhy/react-native-uvc-camera/tree/master/libuvccamera/src/main/jni/libusb"
    click Libuvc "https://github.com/flyskywhy/react-native-uvc-camera/tree/master/libuvccamera/src/main/jni/libuvc"
    click JPEG "https://github.com/flyskywhy/react-native-uvc-camera/blob/master/libuvccamera/src/main/jni/libjpeg-turbo-1.5.0"
    click RapidJSON "https://github.com/flyskywhy/react-native-uvc-camera/tree/master/libuvccamera/src/main/jni/rapidjson"

    %% Styles
    classDef js fill:#008080,stroke:#000,color:#fff
    classDef bridge fill:#ADD8E6,stroke:#000,color:#000
    classDef java fill:#00A000,stroke:#000,color:#fff
    classDef sharedjava fill:#BFFF00,stroke:#000,color:#000
    classDef native fill:#FFA500,stroke:#000,color:#000
    classDef deps fill:#FFFF00,stroke:#000,color:#000
    classDef hardware fill:#D3D3D3,stroke:#000,color:#000
    classDef example stroke:#000,stroke-dasharray:5 5,color:#000
```
