# facebookresearch/spdl architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/spdl
- Repository: https://github.com/facebookresearch/spdl

## Overview

##### Main Components

a. Core Library Components (src/libspdl/core):
- Demuxing System
- Decoding System
- Encoding System
- Buffer Management
- Storage Management (CPU/CUDA)
- Frame/Packet Handling

b. Python Interface Layer (src/spdl):
- IO Module
- DataLoader Module
- Pipeline Module
- Utils Module

c. Hardware Acceleration Components:
- NVIDIA Components (NVDEC, NVJPEG, NPP)
- CPU Processing Pipeline
- CUDA Integration

##### Architectural Layers (from bottom to top)

Layer 1 - Hardware Interface:
- Memory management systems
- CUDA runtime integration

Layer 2 - Core Native Library:
- FFmpeg integration
- NVIDIA codec implementations
- Buffer management system
- Frame/packet processing

Layer 3 - C++/Python Binding Layer:
- Nanobind interface
- Type conversion systems
- Memory management bridges

Layer 4 - Python API:
- DataLoader implementation
- Pipeline management
- I/O operations
- Utility functions

##### Key Relationships to Highlight

- Data Flow:
- Parallel processing paths
- Memory transfer between CPU and GPU

- Control Flow:
- Thread management paths
- Scheduling and synchronization points
- Pipeline stage connections

##### Additional Elements

- Version compatibility information
- Optional components (CUDA vs CPU-only)
- Scaling capabilities

##### Implementation Notes

- Numbered annotations for complex interactions

- Thread-based parallelism
- Hardware acceleration capabilities
- Efficient memory management
- Scalable pipeline architecture

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef python fill:#3572A5,color:white
    classDef core fill:#2B7489,color:white
    classDef hardware fill:#F1502F,color:white
    classDef memory fill:#9B4F96,color:white
    classDef external fill:#808080,color:white
    
    %% Hardware Layer
    subgraph Hardware
        CPU[CPU Processing]:::hardware
        GPU[NVIDIA GPU]:::hardware
        CUDA[CUDA Runtime]:::hardware
    end

    %% Core Native Library Layer
    subgraph CoreLib[Core Native Library]
        FFmpeg[FFmpeg Integration]:::external
        
        subgraph CoreComponents[Core Components]
            Demux[Demuxing System]:::core
            Decode[Decoding System]:::core
            Encode[Encoding System]:::core
            Buffer[Buffer Management]:::core
            Storage[Storage Management]:::core
            Frames[Frame/Packet Handler]:::core
        end
        
        subgraph NVCodecs[NVIDIA Codecs]
            NVDEC[NVDEC]:::hardware
            NVJPEG[NVJPEG]:::hardware
            NPP[NPP]:::hardware
        end
    end

    %% Binding Layer
    subgraph Binding[C++/Python Binding]
        NanoBind[Nanobind Interface]:::core
        TypeConv[Type Conversion]:::core
        MemBridge[Memory Bridge]:::memory
    end

    %% Python API Layer
    subgraph PythonAPI[Python API]
        DataLoader[DataLoader]:::python
        Pipeline[Pipeline]:::python
        IO[IO Operations]:::python
        Utils[Utils]:::python
    end

    %% Relationships
    CPU --> CoreLib
    GPU --> CUDA
    CUDA --> NVCodecs
    
    FFmpeg --> CoreComponents
    NVCodecs --> CoreComponents
    
    CoreComponents --> Binding
    Binding --> PythonAPI
    
    %% Click Events
    click Demux "https://github.com/facebookresearch/spdl/blob/main/src/libspdl/core/demuxing.h"
    click Decode "https://github.com/facebookresearch/spdl/blob/main/src/libspdl/core/decoding.h"
    click Encode "https://github.com/facebookresearch/spdl/blob/main/src/libspdl/core/encoding.h"
    click Buffer "https://github.com/facebookresearch/spdl/tree/main/src/libspdl/core/buffer/"
    click Storage "https://github.com/facebookresearch/spdl/tree/main/src/libspdl/core/storage/"
    click Frames "https://github.com/facebookresearch/spdl/blob/main/src/libspdl/core/frames.h"
    click IO "https://github.com/facebookresearch/spdl/tree/main/src/spdl/io/"
    click DataLoader "https://github.com/facebookresearch/spdl/tree/main/src/spdl/dataloader/"
    click Pipeline "https://github.com/facebookresearch/spdl/tree/main/src/spdl/pipeline/"
    click Utils "https://github.com/facebookresearch/spdl/tree/main/src/spdl/utils/"
    click NVDEC "https://github.com/facebookresearch/spdl/tree/main/src/libspdl/core/detail/nvdec/"
    click NVJPEG "https://github.com/facebookresearch/spdl/tree/main/src/libspdl/core/detail/nvjpeg/"
    click NPP "https://github.com/facebookresearch/spdl/tree/main/src/libspdl/core/detail/npp/"
    click CUDA "https://github.com/facebookresearch/spdl/blob/main/src/libspdl/core/detail/cuda.h"
    click FFmpeg "https://github.com/facebookresearch/spdl/tree/main/src/libspdl/core/detail/ffmpeg/"
    click Binding "https://github.com/facebookresearch/spdl/tree/main/src/spdl/lib/"

    %% Legend
    subgraph Legend
        Python[Python Components]:::python
        CoreNative[Core Native Components]:::core
        HardwareAccel[Hardware Acceleration]:::hardware
        MemoryMgmt[Memory Management]:::memory
        ExternalDep[External Dependencies]:::external
    end
```
