# openstream

**Repository Path**: xdltek/openstream

## Basic Information

- **Project Name**: openstream
- **Description**: OpenStream demos and configs for XDL SDK inference verification.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenStream RPP Inference Demo

![XDL logo](docs/logo/logo_color_horizontal.png)

This repository is a C++ / GStreamer demo framework for building streaming inference pipelines on RPP accelerator hardware. It provides ready-to-run examples for camera / file input, hardware or CPU decode, RPP inference, tracking, OSD rendering, appsink output, and custom GStreamer plugin integration.

## Table Of Contents

- [Quick Start](#quick-start)
- [Code Execution Workflow](#code-execution-workflow)
- [Demo Guides](#demo-guides)
- [Prerequisites](#prerequisites)
- [How to Build](#how-to-build)
- [How to Run](#how-to-run)
- [Configuration Overview](#configuration-overview)
- [How to Adapt This Demo](#how-to-adapt-this-demo)

## Quick Start

Build and install OpenStream from the repository root:

```bash
rm -rf build
mkdir -p build
cd build
cmake ..
make -j8
sudo make install
```

Run a YOLOv5 local-video inference pipeline:

```bash
cd build/app/openstream-infer-yolov5
./openstream-infer-yolov5 ./configs/config_app.yaml
```

Run a YOLOv8 local-video inference pipeline:

```bash
cd build/app/openstream-infer-yolov8
./openstream-infer-yolov8 ./configs/config_app.yaml
```

The default YAML configs use `docs/videos/sample_720p.mp4` as the local video source. Successful execution should initialize the GStreamer pipeline, create the RPP inference engine, receive frames from the configured source, and print runtime logs. If `perf_monitor` is enabled in `config_pipeline.yaml`, performance reports are written to `monitor_log/`.

## Code Execution Workflow

```text
+-----------------------------+
| Parse config_app.yaml       |
| and logging settings        |
+-----------------------------+
              |
              v
+-----------------------------+
| Load pipeline config files  |
| and create pipeline objects |
+-----------------------------+
              |
              v
+-----------------------------+
| Build GStreamer pipeline:   |
| source -> decode -> infer   |
| -> tracker -> OSD -> output |
+-----------------------------+
              |
              v
+-----------------------------+
| aeosinfer initializes model |
| preprocess, RPP engine, and |
| postprocess configuration   |
+-----------------------------+
              |
              v
+-----------------------------+
| Stream frames through VE /  |
| CPU decode and RPP infer    |
+-----------------------------+
              |
              v
+-----------------------------+
| Write logs, optional monitor|
| reports, display or sink    |
| output, then cleanup        |
+-----------------------------+
```

## Demo Guides

Main application demos include:

- `openstream-infer-yolov5`: local video / stream inference with YOLOv5.
- `openstream-infer-yolov8`: local video / stream inference with YOLOv8.
- `openstream-infer-resnet50`: image classification pipeline.
- `openstream-multi-infer`: multi-stream inference and tracking.
- `openstream-infer-streammux-appsink`: streammux + inference + appsink example.
- `openstream-appsink`: appsink output example.
- `openstream-file`: file input with hardware decode.
- `openstream-file-soft-decode`: file input with CPU decode.
- `openstream-custom-plugin`: custom plugin integration example.
- `one-frame-infer`: one-frame inference example.

Each app reads one top-level `config_app.yaml`, which points to one or more `config_pipeline*.yaml` files.

## Prerequisites

Before building this demo, make sure the following dependencies are available:

- Linux development environment
- CMake compatible with this project
- A compiler with C++ support
- GStreamer development libraries and runtime plugins
- OpenCV development headers and libraries
- RppRT / RPP SDK installed under `/usr/local/rpp`
- Runtime libraries required by the target RPP accelerator card environment
- RPP kernel driver loaded and RPP runtime server available when running hardware pipelines

Common Ubuntu dependencies include GStreamer base / good / bad / ugly plugins, OpenCV, FFmpeg, GLib, yaml-cpp, and related development packages.

## How to Build

Run the following commands from the repository root:

```bash
rm -rf build
mkdir -p build
cd build
cmake ..
make -j8
```

If VE is not used CPU-decoded source, configure CPU decode support:

```bash
rm -rf build
mkdir -p build
cd build
cmake .. -Dgstcpudecode=1
make -j8
```

Build outputs are grouped under:

```text
build/app/              application executables and copied configs
build/commons/          common OpenStream libraries
build/gst-plugins/      GStreamer plugin build outputs
build/python/           Python binding build outputs
```

Installed GStreamer plugin libraries are typically placed under:

```text
/usr/local/lib/x86_64-linux-gnu/gstreamer-1.0/
/usr/local/lib/aarch64-linux-gnu/gstreamer-1.0/
```

The exact install path depends on the target architecture and CMake install configuration.

## How to Run

Run demos from their build output directories after building and installing the project.

YOLOv5:

```bash
cd build/app/openstream-infer-yolov5
./openstream-infer-yolov5 ./configs/config_app.yaml
```

YOLOv8:

```bash
cd build/app/openstream-infer-yolov8
./openstream-infer-yolov8 ./configs/config_app.yaml
```

Generic infer demo:

```bash
cd build/app/openstream-infer
./openstream-infer ./configs/config_app.yaml
```

Multi-stream infer demo:

```bash
cd build/app/openstream-multi-infer
./openstream-multi-infer ./configs/config_app.yaml
```

Before running, make sure `config_pipeline.yaml` points to a valid local file source and the model path in the model config points to a valid ONNX file under `weights/`. RTSP can be used by replacing the commented example in the YAML.

Daily log output can be redirected with:

```bash
export DAEOS_FILE_PATH=<log_file_path>
```

## Configuration Overview

`config_app.yaml` controls global log level and pipeline count:

```yaml
log_info:
    spdlog_level: 2
    gstlog_level: 4
    spdlog_flush_level: 4
    spdlog_flush_time: 1

pipeline_info:
    pipeline_num: 1
    pipeline_config1: ./configs/config_pipeline.yaml
```

`config_pipeline.yaml` controls one pipeline:

```yaml
common:
    show_image:  True
    perf_monitor: ./configs/config_monitor.yaml
    replay: False
    cpu_decoder: False

source:
    factory: uridecodebin3
    video: file://../../../docs/videos/sample_720p.mp4
    # rtsp example: rtsp://admin:password@192.168.1.100:554/stream

infer1:
    factory: aeosinfer
    config_file: ./configs/config_fall_yolov5s.yaml

tracker:
    factory: aeostracker
    config_file: ./configs/config_fall_tracker.yaml

OSD:
    factory: aeososd
    config_file: ./configs/config_fall_osd.yaml

output:
    factory: fakesink
    config_file: NONE
```

Important fields:

- `show_image`: enables or disables display output.
- `perf_monitor`: enables performance report output when the monitor config is valid.
- `cpu_decoder`: selects CPU decode when enabled; otherwise VE / hardware decode is used when available.
- `source.video`: input local file path by default; replace it with the commented RTSP example when using a network camera.
- `infer1.config_file`: model preprocess / infer / postprocess config.
- `tracker.config_file`: tracking configuration.
- `OSD.config_file`: OSD drawing configuration.

`config_monitor.yaml` controls performance reporting:

```yaml
monitor:
    enable_pm: True
    log_name: perfermance_report
    pm_interval_time: 10
```

YOLO model config files such as `config_fall_yolov5s.yaml` and `config_yolov8.yaml` control:

- input frame dimensions
- resize and color conversion
- model input / output names
- ONNX model path
- engine cache path
- postprocess type and thresholds
- label file path

## How to Adapt This Demo

1. Keep `source.video` on the shared local file, or replace it with the commented RTSP example for a camera source.
2. Replace the ONNX model path in the model config, such as `config_fall_yolov5s.yaml` or `config_yolov8.yaml`.
3. Update input dimensions in `pre_process.input_width` and `pre_process.input_height` to match the decoded stream.
4. Update `resize.output_dims`, model input names, and output names to match the model.
5. Update `labels_file`, object threshold, NMS threshold, and custom postprocess library when using a different dataset or model family.
6. Use `pipeline_num` and `pipeline_configN` in `config_app.yaml` to run multiple streams.
7. Use `show_image: False` for headless performance tests, or enable it when visual display is required.
8. Enable `perf_monitor` to collect per-stage timing reports under `monitor_log/`.

For automated validation, use this repository together with external scripts that rewrite runtime configs, start demos, collect app logs, collect CPU / memory usage, and capture `ae-smi` CSV during the run.