ros2_gst_video_bridge

ros2_gst_video_bridge

Overview

ros2_gst_video_bridge is a ROS 2 node that subscribes to raw image streams (sensor_msgs/Image) and forwards frames through configurable GStreamer pipelines for flexible video transport and codec handling. It supports multiple output protocols (SRT, RTSP, RTP/UDP, file), codec selection with automatic hardware acceleration fallback, and production-grade resilience features (reconnection, backpressure handling, adaptation).

Architecture at a Glance

flowchart LR
  subgraph Ingest[Image Ingest]
    Cam[ROS 2 Camera Node\nsensor_msgs/Image]
  end

  subgraph BridgeCore[Bridge Core]
    Bridge[ros2_gst_video_bridge Node]
    Runtime[Runtime Controller\nreconnect + adaptation + fallback]
    Engine[Stream Engine\nappsrc + push + backpressure]
    Config[Config Resolver\nprofiles + params + validation]
  end

  subgraph Delivery[Media Delivery]
    Gst[GStreamer Pipeline\nencoder + mux/payloader + sink]
    Out[Receiver / File / Network Consumer]
  end

  subgraph OpsPlane[Control and Observability]
    Ops[Operator / CI]
    Obs[Runtime Status and Events\nmetrics + alarms + diagnostics]
  end

  Cam --> Bridge
  Config --> Bridge
  Bridge --> Runtime
  Runtime --> Engine
  Engine --> Gst --> Out

  Ops -. launch args / params / service calls .-> Bridge
  Bridge -. runtime_status / runtime_events .-> Obs

  classDef ingest fill:#E8F1FF,stroke:#2D6CDF,stroke-width:1.5px,color:#0F1A2A;
  classDef core fill:#E9FBF1,stroke:#1B8A5A,stroke-width:1.5px,color:#0F1A2A;
  classDef delivery fill:#FFF4E6,stroke:#D97A00,stroke-width:1.5px,color:#0F1A2A;
  classDef ops fill:#F3E8FF,stroke:#7A3DB8,stroke-width:1.5px,color:#0F1A2A;

  class Cam ingest;
  class Bridge,Runtime,Engine,Config core;
  class Gst,Out delivery;
  class Ops,Obs ops;

For deeper internals and runtime behavior, see docs/ARCHITECTURE.md.

Key Features

• Transport agnostic: SRT, RTSP, RTP/UDP, file, and custom GStreamer sinks
• Smart codec selection: Auto-detection of hardware and software encoders with fallback
• Resilient streaming: Automatic reconnection, backpressure handling, and adaptive bitrate control
• Jetson-optimized: NVIDIA hardware encoder support with graceful CPU fallback
• Runtime diagnostics: Rich observability via typed ROS topics and services
• Profile-based configuration: Curated presets for Jetson, x86, and Raspberry Pi

Quick Start

1. Install Dependencies

sudo apt-get update && sudo apt-get install -y \
  gstreamer1.0-tools \
  gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad \
  gstreamer1.0-libav \
  libgstreamer1.0-dev \
  libgstreamer-plugins-base1.0-dev

2. Build

cd ~/ros2_ws/src
git clone <repo-url> ros2_gst_video_bridge
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-up-to ros2_gst_video_bridge
source install/setup.bash

3. Run

Minimal SRT streaming with automatic codec selection:

```bash

File truncated at 100 lines see the full file

Contributing

Requirements

• ROS 2 Humble (Ubuntu 22.04 or Jetson JetPack 5.x)
• GStreamer 1.20+ with gstreamer1.0-plugins-{base,good,bad} and gstreamer1.0-libav
• libgstreamer1.0-dev and libgstreamer-plugins-base1.0-dev
• clang-format-15 (optional but required to pass CI)

Development Setup

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
git clone git@github.com:mkassimi98/ros2_gst_video_bridge.git
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
source /opt/ros/humble/setup.bash
colcon build --packages-up-to ros2_gst_video_bridge ros2_gst_video_bridge_msgs
source install/setup.bash

Running Tests

# Build with tests enabled (default)
colcon build --packages-up-to ros2_gst_video_bridge \
  --cmake-args \
    -DROS2_GST_VIDEO_BRIDGE_ENABLE_CLANG_FORMAT_CHECK=OFF

# Run all tests and show results
colcon test --packages-select ros2_gst_video_bridge
colcon test-result --all --verbose

All 11 CTest entries must pass before opening a PR. If you add functionality, add a test for it.

Code Style

This repository uses clang-format-15 (LLVM base, 100-column limit, 2-space indent).

Format check before every commit:

# Dry-run — prints diffs without modifying files
find ros2_gst_video_bridge/include ros2_gst_video_bridge/src \
  \( -name '*.hpp' -o -name '*.cc' \) | \
  xargs clang-format-15 --dry-run --Werror

Auto-fix formatting:

find ros2_gst_video_bridge/include ros2_gst_video_bridge/src \
  \( -name '*.hpp' -o -name '*.cc' \) | \
  xargs clang-format-15 -i

Style rules (summary):

• All source code and comments in English.
• Keep files under ~300 lines; split by responsibility if they grow.
• Prefer small, testable, pure functions in include/ros2_gst_video_bridge/detail/ headers.
• Keep runtime behaviour deterministic under overload.
• Do not remove backward-compatible parameters without a documented migration path and a deprecation warning at runtime.
• Avoid using namespace at file scope.
• noexcept on leaf functions that cannot throw.

Branch Naming

Use lowercase, hyphens as word separators (e.g. ft/adaptation-profiles).

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <imperative summary, ≤72 chars>

[optional body — what and why, not how]

[optional footer: BREAKING CHANGE, Closes #N]

Types: feat, fix, docs, test, ci, refactor, perf, chore
Scopes: node, runtime, config, pipeline, metrics, ci, docs

Examples:

``` feat(runtime): add three-level adaptive bitrate/fps loop fix(runtime): avoid busLoop holding pipeline mutex during blocking poll test(detail): add adaptation scaling and SW encoder selection coverage

File truncated at 100 lines see the full file