# belabox/belacoder architecture

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

- Interactive diagram: https://gitdiagram.com/belabox/belacoder
- Repository: https://github.com/belabox/belacoder

## Overview

##### Project Type and Purpose
- belacoder is a video encoding application for live streaming.
- Its core functionality is to select and execute a GStreamer pipeline (whose definitions are organized in the extensive “pipeline” directory) while dynamically controlling the video bitrate based on available network throughput.
- It interacts with external hardware (video capture devices, HDMI capture cards) and streaming endpoints through the SRT protocol.

##### File Structure
- At the root, the file names (Makefile, belacoder.c, README, LICENSE) indicate a C-based application with a Makefile build system.
- The “pipeline” directory is organized into several subdirectories (generic, jetson, rk3588) that host pre-built pipeline scripts. Each subdirectory represents platform-specific GStreamer pipelines configured for various encoding scenarios (different codecs, resolutions, and framerates).
- The presence of configuration files (like .github/FUNDING.yml) and build scripts affirm the project’s open-source nature and provide instructions for building and integration.

##### Key Components
a. Input Module:
- Video capture sources from devices (e.g., Cam Link 4K, USB2.0 MJPEG capture cards).
- Physical capture hardware and its interface with the encoding framework.

b. GStreamer Pipeline:
- The core flow of data from capture to encoding, where each pipeline corresponds to a unique arrangement of GStreamer elements.
- Elements such as:
- Encoder element (e.g., h265 or h264 encoders, or x264 in software) with “name=venc_bps” or “name=venc_kbps” to allow runtime bitrate updates.
- Delay and synchronization elements (using “identity name=a_delay” and “identity name=v_delay”).
- Optional textoverlay element (named “overlay”) for dynamic on-screen bitrate display.
- The sink element which is an “appsink name=appsink”, responsible for streaming to the SRT target.

c. Dynamic Bitrate Control:
- A module that monitors network conditions and responds to system signals (SIGHUP) to adjust the bitrate by reading from a bitrate settings file.
- Dependency on external triggers (SIGHUP) and the real-time property updates of the video encoder.

d. SRT Integration:

e. Command-line Interface and Configuration:
- The input parameters include the pipeline file, SRT address, port number, and optional arguments (delay, stream ID, bitrate file) which influence how the pipeline is executed.
- This interface as a control plane that configures the encoding session.

##### Relationships and Interactions Between Components
- Start from the Command-line Input → the Application (belacoder.c) which parses arguments.
- The application loads a specific pipeline file from the “pipeline” folder; the file chosen represents the hardware setup and desired encoding configuration.
- The GStreamer pipeline then is constructed by chaining elements: capture source (from the physical device) → processing (sync/delay identities) → encoder (with dynamic bitrate properties) → optional overlay → appsink.
- Dynamic bitrate control feeds back into the encoder element based on periodic SIGHUP signals and updated bitrate settings.
- Finally, the appsink delivers the processed stream to an SRT-based streaming connector that handles transmission over the network.

##### Architectural Patterns and Design Principles
- Dataflow Architecture: Emphasize the linear flow of video and audio data through a series of processing elements in the GStreamer pipeline.
- Modular & Configurable: The use of external pipeline scripts and a bitrate settings file shows how the application is designed for flexibility and reusability.
- Real-time Processing with Feedback: Note the dynamic bitrate control mechanism that exemplifies adaptivity to changing network conditions.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Subgraph: Control and Configuration
    subgraph "Control and Config"
        cli["Command-Line Input / Input Parser"]:::control
        config["Configuration Loader (Bitrate Settings)"]:::control
        loader["Pipeline Loader"]:::control
        cli --> config
        config --> loader
    end

    %% Subgraph: Platform Pipelines
    subgraph "Platform Pipelines"
        generic["Generic Pipeline"]:::pipeline
        jetson["Jetson Pipeline"]:::pipeline
        rk3588["rk3588 Pipeline"]:::pipeline
        %% Multiple choices from Pipeline Loader
        loader --> generic
        loader --> jetson
        loader --> rk3588
    end

    %% Subgraph: GStreamer Pipeline
    subgraph "GStreamer Pipeline"
        capture["Video Capture Source"]:::hardware
        delayA["Identity (a_delay)"]:::pipeline
        delayV["Identity (v_delay)"]:::pipeline
        encoder["Encoder (venc_bps/venc_kbps)"]:::pipeline
        overlay["Text Overlay (Optional)"]:::pipeline
        appsink["Appsink (Output to SRT)"]:::pipeline
        %% Arrows showing pipeline flow
        generic --> capture
        jetson --> capture
        rk3588 --> capture
        capture --> delayA
        delayA --> delayV
        delayV --> encoder
        encoder --> overlay
        overlay --> appsink
    end

    %% Subgraph: Dynamic Bitrate Control
    subgraph "Dynamic Bitrate Control"
        bitrate["Dynamic Bitrate Control (SIGHUP Trigger)"]:::control
    end

    %% Subgraph: Network Streaming
    subgraph "Network Streaming"
        srt["SRT Streaming Module"]:::network
        appsink --> srt
    end

    %% Feedback Loop from Bitrate Control to Encoder
    bitrate -.->|"SIGHUP_update"| encoder

    %% Click Events
    click cli "https://github.com/belabox/belacoder/blob/debug_overlay/belacoder.c"
    click loader "https://github.com/belabox/belacoder/tree/debug_overlay/pipeline/"
    click generic "https://github.com/belabox/belacoder/tree/debug_overlay/pipeline/generic"
    click jetson "https://github.com/belabox/belacoder/tree/debug_overlay/pipeline/jetson"
    click rk3588 "https://github.com/belabox/belacoder/tree/debug_overlay/pipeline/rk3588"
    click bitrate "https://github.com/belabox/belacoder/blob/debug_overlay/belacoder.c"
    click capture "https://github.com/belabox/belacoder/tree/debug_overlay/camlink_workaround"
    click srt "https://github.com/belabox/belacoder/blob/debug_overlay/belacoder.c"

    %% Styles
    classDef control fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef hardware fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef pipeline fill:#ABEBC6,stroke:#239B56,stroke-width:2px;
    classDef network fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
