# codingspirit/v4l2capturer architecture

> Architecture diagram of the GitHub repository codingspirit/v4l2capturer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codingspirit/v4l2capturer
- Repository: https://github.com/codingspirit/v4l2capturer

## Overview

##### Project Type and Purpose
- This is a small, native C library (V4l2Capturer) that wraps Video4Linux2 (v4l2) calls and libv4l helper APIs to provide a simple interface for capturing H.264 and YUYV frames from a V4L2-compatible device (e.g., a USB webcam or hardware encoder).
- The sample directory contains a minimal demo application that links against the library to show its usage.

##### High-Level Components
a. V4l2Capturer Library
- Core C source (src/V4l2Capturer.c) implementing open/configure/read/close operations.
- Public header (include/V4l2Capturer.h) exposing an API for clients.
- Build configuration (CMakeLists.txt) to produce a shared library (.so).
b. Client Application (Sample)
- sample/V4l2CapturerSample.cpp shows how to initialize the library, pull frames, and handle them.
c. External Dependencies
- libv4l (userspace helper library for v4l2)
- Linux kernel V4L2 subsystem (device driver)
d. Operating System / Hardware
- Camera device node (e.g., /dev/video0) provided by the kernel driver.

##### Relationships and Data Flow
- The Sample app links to V4l2Capturer → calls init, startCapture, readFrame → V4l2Capturer invokes libv4l APIs → those call kernel V4L2 driver → driver reads from hardware → frame buffers are mmap’d or copied back → V4l2Capturer returns raw frames (H.264 or YUYV) to the sample.
- CMake orchestrates build dependencies (linking libv4l and creating the shared library).

##### Architectural Patterns & Design Principles
- Layered approach:
- Application layer (sample)
- Library abstraction (V4l2Capturer)
- Third-party helper (libv4l)
- Kernel driver/hardware
- Single responsibility: library focuses solely on capture; it does not do encoding, display, or storage.
- Minimal external interface: one header, a few core functions.

##### What to Label & Include
- Component Names (e.g., “V4l2Capturer.so”, “libv4l.so”, “/dev/video0”).
- Function boundaries (init, start, readFrame, stop, close).
- Build step: “cmake → make → libv4l-dev link”.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        Sample["V4l2CapturerSample.cpp"]:::app
    end

    %% Library Layer
    subgraph "Library Layer"
        Header["V4l2Capturer.h"]:::config
        LibImpl["V4l2Capturer.so"]:::lib
    end

    %% External Dependencies
    subgraph "External Dependencies"
        LibV4l["libv4l.so"]:::external
    end

    %% Kernel Layer
    subgraph "Kernel Layer"
        Kernel["V4L2 Kernel Driver"]:::kernel
    end

    %% Hardware
    subgraph "Hardware"
        Camera["/dev/video0 (Camera Device)"]:::hw
    end

    %% Build & Config
    subgraph "Build & Config"
        CMake["CMakeLists.txt"]:::config
        License["LICENSE"]:::config
        Readme["README.md"]:::config
        Clang[".clang-format"]:::config
    end

    %% Data Flow
    Sample -->|"include V4l2Capturer.h"| Header
    Sample -->|"init(), startCapture(), readFrame()"| LibImpl
    Header -->|"public API"| LibImpl
    LibImpl -->|"calls libv4l APIs"| LibV4l
    LibV4l -->|"ioctl(), read(), mmap()"| Kernel
    Kernel -->|"frame buffers"| LibV4l
    LibV4l -->|"returns H.264/YUYV buffer"| LibImpl
    LibImpl -->|"returns frames"| Sample
    LibImpl -->|"linked via CMake"| CMake
    Sample -->|"linked via CMake"| CMake
    Kernel -->|"interacts with device node"| Camera
    Camera -->|"video frames"| Kernel

    %% Click Events
    click LibImpl "https://github.com/codingspirit/v4l2capturer/blob/master/src/V4l2Capturer.c"
    click Header "https://github.com/codingspirit/v4l2capturer/blob/master/include/V4l2Capturer.h"
    click CMake "https://github.com/codingspirit/v4l2capturer/blob/master/CMakeLists.txt"
    click Sample "https://github.com/codingspirit/v4l2capturer/blob/master/sample/V4l2CapturerSample.cpp"
    click License "https://github.com/codingspirit/v4l2capturer/tree/master/LICENSE"
    click Readme "https://github.com/codingspirit/v4l2capturer/blob/master/README.md"
    click Clang "https://github.com/codingspirit/v4l2capturer/blob/master/.clang-format"

    %% Styles
    classDef app fill:#add8e6,stroke:#0000ff,stroke-width:1px;
    classDef lib fill:#98fb98,stroke:#008000,stroke-width:1px;
    classDef external fill:#ffa500,stroke:#ff8c00,stroke-width:1px;
    classDef kernel fill:#ff7f7f,stroke:#ff0000,stroke-width:1px;
    classDef hw fill:#d3d3d3,stroke:#696969,stroke-width:1px;
    classDef config fill:#e0ffff,stroke:#20b2aa,stroke-width:1px;
```
