How belabox/belacoder works
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.