Gst-nvmultiurisrcbin (Alpha)


The DeepStream 6.2 introduces nvmultiurisrcbin with REST API support for dynamic sensor add/remove capability. This is an Alpha feature.

This bin integrates three major DeepStream components viz. nvds_rest_server, nvurisrcbin, and nvstreammux (Gst-nvstreammux New / Gst-nvstreammux) into a single GstBin. For more details on nvurisrcbin, please run gst-inspect-1.0 nvurisrcbin on a machine/docker container with DeepStream installed.

The bin allows users to create simple gstreamer pipelines for AI multimedia analytics. Users can add or remove sensors over REST API calls made to a HTTP endpoint. A sensor is defined as a streaming entity with a valid unique Sensor ID, and URI.

The below High Level Overview diagram and table illustrate how nvmultiurisrcbin integrates nvds_rest_server, nvurisrcbin, and nvstreammux.

Gst-nvmultiurisrcbin High Level Overview
Gst-nvmultiurisrcbin High Level Overview of integrated components

Component Name

Source path in DeepStreamSDK Package for more info

  1. REST API Server; nvds_rest_server


  1. Bin Manipulation API Library


  1. nvmultiurisrcbin


  1. deepstream-test5-app Demonstrating usage of nvmultiurisrcbin with nvmsgconv and nvmsgbroker


  1. nvurisrcbin

Source not available. For more info please run gst-inspect-1.0 nvurisrcbin on a machine/docker container with DeepStream installed.

  1. nvstreammux

Source not available. For more info please run gst-inspect-1.0 nvstreammux OR for new nvstreammux USE_NEW_NVSTREAMMUX=yes gst-inspect-1.0 nvstreammux

1. Introduction

This GstBin is a GStreamer source bin. The bin exposes only one source pad that provide batched buffers from an nvstreammux instance.

Users can add/remove streams to the bin for batching over the REST APIs defined in the Section REST API Payload definitions.

Users can also provide a static list of streams and their sensor IDs to start the pipeline with. This can be done using the Gst properties uri-list and sensor-id-list described below.

The nvmultiurisrcbin component output batched buffers from an nvstreammux instance.

Users can set environment variable USE_NEW_NVSTREAMMUX=yes to load the Gst-nvstreammux New instead of the default Gst-nvstreammux.

2. Features

The following table summarizes the features of the bin.

Gst-nvmultiurisrcbin features




nvmultiurisrcbin integrating REST API Server, nvurisrcbin, and nvstreammux

Introducing nvmultiurisrcbin

DS 6.2

REST API to add and remove sensors runtime

Dynamically add/remove sensors

DS 6.2

3. How to use nvmultiurisrcbin in a pipeline

Below pipeline is a sample gstreamer pipeline which is configured to accept upto 10 input sources and the pipline starts up with two sources:

gst-launch-1.0 nvmultiurisrcbin \
port=9000 ip=localhost \
batched-push-timeout=33333 max-batch-size=10 \
drop-pipeline-eos=1 live-source=1 \
uri-list=file:///opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4,file:///opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4 width=1920 height=1080 \
! nvmultistreamtiler ! nveglglessink

Below diagram illustrates a similar pipeline (with different plugins like nvinfer, nvmsgconv, and nvmsgbroker downstream).

Gst-nvmultiurisrcbin sample video pipeline

3.1 REST API payload definitions and sample curl commands for reference


Currently only few fields from the JSON schema described below are used/mandatory. The remaining fields are optional and ignored.

List of mandatory (and used) fields are:

  • value/camera_id

  • value/camera_url

  • value/change

3.1.1 ADD a new stream to a DeepStream pipeline

Payload definition and the sample curl command:

curl -XPOST 'http://localhost:9000/stream/add' -d '{
    "key": "sensor",
    "value": {
        "camera_id": "uniqueSensorID1",
        "camera_name": "front_door",
        "camera_url": "file:///opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4",
        "change": "camera_add",
        "metadata": {
            "resolution": "1920 x1080",
            "codec": "h264",
            "framerate": 30
    "headers": {
        "source": "vst",
        "created_at": "2021-06-01T14:34:13.417Z"

3.1.2 REMOVE a new stream to a DeepStream pipeline

Payload definition and the sample curl command:

curl -XPOST 'http://localhost:9000/stream/remove' -d '{
    "key": "sensor",
    "value": {
        "camera_id": "uniqueSensorID1",
        "camera_name": "front_door",
        "camera_url": "file:///opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4",
        "change": "camera_remove",
        "metadata": {
            "resolution": "1920 x1080",
            "codec": "h264",
            "framerate": 30
    "headers": {
        "source": "vst",
        "created_at": "2021-06-01T14:34:13.417Z"

4. Gst Properties

4.1 Gst Properties directly configuring nvmultiurisrcbin

Gst-nvmultiurisrcbin gstreamer properties directly configuring the bin



Type and Range

Example Notes


comma separated URI list of sources; URI of the file or rtsp source




comma separated list of source sensor IDs; this vector is one to one mapped with the uri-list




Video-only or Audio-only modes available

0: for video-only 1: for audio-only

mode=0 (default)




ip-address=localhost (default)


Set REST API HTTP Port number; Note: User may pass 0 to disable REST API Server


port=9000 (default)


Set the maximum batch size to be used for nvstreammux; Maximum number of sources to be supported with this instance of nvmultiurisrcbin

Integer, 1 to 4,294,967,295

max-batch-size=30 (default)

4.2 Gst Properties to configure each instance of nvurisrcbin created inside this bin

Gst-nvmultiurisrcbin nvurisrcbin specific properties



Type and Range

Example Notes


Set extra decoder surfaces; Number of surfaces in addition to minimum decode surfaces given by the decoder

Integer, 1 to 4,294,967,295

num-extra-surfaces=1 (default)


Set GPU Device ID used by nvurisrcbin components like decoder (nvv4l2decoder) and nvvideoconvert

Integer, 1 to 4,294,967,295

gpu-id=0 (default)


Memory type for cuda decoder buffers, Memory type for CUDA decoder buffers. Represented internally by enum CudaDecMemType. 0 (memtype_device): Device 1 (memtype_pinned): Host Pinned 2 (memtype_unified): Unified

Integer, 0, 1, or 2

cudadec-memtype=2 (default)


Interval to drop the frames, e.g. a value of 5 means the decoder outputs every fifth frame, and others are dropped.

Integer, 1 to 30

Default: 0, dGPU / Jetson


Type of frames to skip during decoding. Represented internally by enum SkipFrame. 0 (decode_all): decode all frames 1 (decode_non_ref): skips non-ref frames (Applicable only on Jetson platform) 2 (decode_key): decode key frames

Integer, 0, 1, or 2

skip-frames=0 Default: 0 ,dGPU / Jetson


Transport Protocol to use for RTP

Enum RtpProtocol Default: 0, rtp-multi (0): rtp-multi - UDP + UDP Multicast + TCP (4): rtp-tcp - TCP Only

select-rtp-protocol=0 (default)


Loop file sources after EOS. Src type must be source-type-uri and uri starting with ‘file:/


file-loop=false (default)


Timeout in seconds to wait since last data was received from an RTSP source before forcing a reconnection. 0=disable timeout

Integer, 1 to 4,294,967,295



Jitterbuffer size in milliseconds; applicable only for RTSP streams.

Integer, 1 to 4,294,967,295

latency=100 (default)


UDP Buffer Size in bytes; applicable only for RTSP streams.

Integer, 1 to 4,294,967,295

udp-buffer-size=524288 (default)


Enable Smart Record and choose the type of events to respond to. Sources must be of type source-type-rtsp

(0):smart-rec-disable - Disable Smart Record (1):smart-rec-cloud  - Trigger Smart Record through cloud messages only (2):smart-rec-multi  - Trigger Smart Record through cloud and local events

smart-record=0 (default)


Path of directory to save the recorded file.


Absolute or relative path


By default, Smart_Record is the prefix. For unique file names every source must be provided with a unique prefix


Absolute or relative path


Size of video cache in seconds. DEPRECATED: Use ‘smart-rec-cache’ instead

Integer, 1 to 4,294,967,295

smart-rec-video-cache=0 (default)


Size of cache in seconds, applies to both audio and video cache

Integer, 1 to 4,294,967,295

smart-rec-cache=0 (default)


Container format of recorded video. MP4 and MKV containers are supported. Sources must be of type source-type-rtsp

(0): smart-rec-mp4 - MP4 container (1): smart-rec-mkv - MKV container

smart-rec-container=0 (default)


Smart record mode

(0):smart-rec-mode-av - Record audio and video if available (1):smart-rec-mode-video - Record video only if available (2):smart-rec-mode-audio - Record audio only if available

smart-rec-mode=0 (default)


In case a Stop event is not generated. This parameter will ensure the recording is stopped after a predefined default duration.

Integer, 1 to 4,294,967,295

smart-rec-default-duration=20 (default)

4.3 Gst Properties to configure the instance of nvstreammux created inside this bin

All properties except “batch-size” can be configured using the same property names as defined for nvstreammux here and new nvstreammux2 here.

5. Important Notes

5.1 nvmultiurisrcbin config recommendations and notes on expected behavior

Gst-nvmultiurisrcbin recommendations


Expected Behavior and Recommendation


nvstreammux, live-source property. live-source=1 live-source need to be turned ON to allow batching of available buffers when number of sources is < max-batch-size configuration.


REST API stream/add or stream/remove payload value of the change key must contain substring add or remove respectively. Expected Behavior: If ‘add’ is in the change field value, the sensorId and uri will be used to create a new stream. If ‘remove’ is in the change field value, the sensorId and uri will be used to find and remove the matching running stream.


Boolean property to inform muxer to skip sending EOS downstream is recommended to be set to 1. When using nvmultiurisrcbin drop-pipeline-eos=1 is preferred default to allow pipeline to stay alive for new sensor add requests after the last added sensor EOS. drop-pipeline-eos=1

6. Known Issues

Gst-nvmultiurisrcbin known issues


Known issues


Usage of new nvstreammux for video and audio usecases are not supported at this time and might not work.