Gst-nvstreammux New Alpha
=========================
The Gst-nvstreammux plugin forms a batch of frames from multiple input sources. When connecting a source to nvstreammux (the muxer), a new pad must be requested from the muxer using ``gst_element_get_request_pad()`` and the pad template ``sink_%u``. For more information, see ``link_element_to_streammux_sink_pad()`` in the DeepStream app source code.
The muxer forms a batched buffer of batch-size frames. (batch-size is specified using the gst object property.)
The muxer forwards the frames from that source as a part of the muxer’s output batched buffer. The frames are returned to the source when muxer gets back its output buffer. 
The muxer pushes the batch downstream when the batch is filled or the batch formation timeout calculated from the overall and stream specific “fps” control configuration keys in provided streammux config file is reached. The timeout starts running when the first buffer for a new batch is collected. The default overall max and min fps for batch generation are 120 and 5 respectively.
The muxer’s default batching  uses a round-robin algorithm to collect frames from the sources. It tries to collect an average of ( batch-size/num-source ) frames per batch from each source (if all sources are live and their frame rates are all the same). The number varies for each source, though, depending on the sources’ frame rates.
The muxer attaches an ``NvDsBatchMeta`` metadata structure to the output batched buffer. This meta contains information about the frames copied into the batch (e.g. source ID of the frame, original resolutions of the input frames, original buffer PTS of the input frames). The source connected to the ``Sink_N`` pad will have ``pad_index`` ``N`` in ``NvDsBatchMeta``.
The muxer supports addition and deletion of sources at run time. When the muxer receives a buffer from a new source, it sends a ``GST_NVEVENT_PAD_ADDED`` event. When a muxer sink pad is removed, the muxer sends a ``GST_NVEVENT_PAD_DELETED`` event. Both events contain the source ID of the source being added or removed (see ``sources/includes/gst-nvevent.h``). Downstream elements can reconfigure when they receive these events. Additionally, the muxer also sends a ``GST_NVEVENT_STREAM_EOS`` to indicate EOS from the source.
The muxer supports calculation of NTP timestamps for source frames. It supports two modes. In the system timestamp mode, the muxer attaches the current system time as NTP timestamp. In the RTCP timestamp mode, the muxer uses RTCP Sender Report to calculate NTP timestamp of the frame when the frame was generated at source. The NTP timestamp is set in ``ntp_timestamp`` field of ``NvDsFrameMeta``. The mode can be toggled by setting the ``attach-sys-ts`` property. For more details, refer to :doc: `\DS_NTP_Timestamp` section NTP Timestamp in DeepStream.

.. image:: ../content/DS_plugin_gst-nvstreammux2.png
         :align: center
         :alt: Gst-nvstreammux

.. note::
 New nvstreammux is being released as an alpha feature (limited support).
 Users will be able to use the new streammux by setting the environment variable ``export USE_NEW_NVSTREAMMUX=yes``. The existing nvsteammux shall be employed by default.

Inputs and Outputs
-----------------------

* Inputs

   * NV12/RGBA buffers from an arbitrary number of sources
   * mono S16LE audio buffers from an arbitrary number of sources

* Control Parameters

  *	batch-size
  *	config-file-path [config-keys detailed below]
  *	num-surfaces-per-frame
  *	attach-sys-ts

* Output

  *	NV12/RGBA batched video buffer ``NvBufSurface`` or batch audio buffer ``NvBufAudio``
  *	GstNvBatchMeta (meta containing information about individual frames in the batched buffer)

Features
----------
The following table summarizes the features of the plugin.

.. csv-table:: Gst-nvstreammux plugin features 
    :file: ../text/tables/Gst-nvstreammux tables/DS_Plugin_gst-nvstreammux2_features.csv
    :widths: 30, 30, 30
    :header-rows: 1

Gst Properties
------------------
The following table describes the Gst-nvstreammux plugin’s Gst properties.

.. csv-table:: Gst-nvstreammux gst-properties 
    :file: ../text/tables/Gst-nvstreammux tables/DS_Plugin_gst-nvstreammux2_gst-properties.csv
    :widths: 25, 25, 25, 25
    :header-rows: 1

Differences between default and new streammux with respect to the GStreamer plugin properties are discussed in the table below:

.. csv-table:: Gst-nvstreammux differences from default nvstreammux
    :file: ../text/tables/Gst-nvstreammux tables/DS_Plugin_gst-nvstreammux2_differences.csv
    :widths: 30, 30
    :header-rows: 1

Mux Config Properties
---------------------
Details on Streammux config-file groups and keys are summarized the following table.

.. csv-table:: Gst-nvstreammux config-file properties
    :file: ../text/tables/Gst-nvstreammux tables/DS_Plugin_gst-nvstreammux2_cfg-file-properties.csv
    :widths: 30, 30, 30
    :header-rows: 1