gvastreamdemux#

Routes a single muxed stream back to per-source output pads based on GstAnalyticsBatchMeta attached upstream by gvastreammux. The element is the companion to gvastreammux and must be paired with it; it cannot work standalone.

Overview#

gvastreamdemux reads the GstAnalyticsBatchMeta attached by gvastreammux and routes each source’s buffer to src_<index>. This enables the common multi-stream pattern:

N sources → gvastreammux → shared inference → gvastreamdemux → N independent outputs

It transparently handles both of the mux’s output modes:

  • PASSTHROUGH input (plain video buffers): each buffer carries a single-stream meta; the demux forwards it to src_<streams[0].index> as-is.

  • CONTAINER input (caps multistream/x-analytics-batch): each buffer is a container holding n_streams sources. The demux unpacks every streams[i], recovers that source’s original caps from its GST_EVENT_CAPS sticky event, forwards those caps to src_<index> (lazily, once per pad), and pushes the source’s buffer (objects[0]). This is how heterogeneous video + lidar batches are split back into a video/x-raw branch and an application/x-lidar branch.

Key design points:

  • Metadata-driven routing — buffers are forwarded based on stream index. Buffers without a usable GstAnalyticsBatchMeta cause a pipeline error.

  • Per-pad caps in CONTAINER mode — each src_* pad emits its own stream’s caps, so different pads can carry different media types (e.g. src_0 video, src_2 lidar).

  • No frame dropping — every source buffer is pushed to its target pad.

  • Independent branches — the flow returns of the individual src_* pads are combined, so a branch that is unlinked or has already finished does not stop the sources that are still running. Only when every branch reports the same non-OK result is it passed upstream.

  • Sparse src indices — names like demux.src_5 work even if src_0..src_4 were never created, mirroring the mux side. Indices must be in [0, 256). Request a pad without a name to be given the lowest free index; releasing a pad frees its index for reuse.

  • No strict count match — the upstream n_streams and the number of requested src_* pads do not have to match, in either output mode. A source with no matching src_* pad is dropped with a GST_WARNING and the remaining sources are still delivered, so you can request only the branches you care about, and you can add or remove branches while the pipeline runs. Match the indices to the mux indices to receive every frame.

Important: as with gvastreammux, downstream gvadetect should keep inference-interval=1 (default). Higher values would skip whole batches in arrival order, meaning some source ids consistently miss inference results.

How It Works#

  1. The pipeline requests source pads (src_0, src_1, …) — typically one per upstream sink pad. Pad index is parsed from the requested name; sparse indices are allowed up to 255.

  2. On the sink CAPS event the demux detects whether the input is plain video (PASSTHROUGH) or the multistream/x-analytics-batch container (CONTAINER). In CONTAINER mode it does not forward the container caps downstream — per-stream caps come from the buffers instead.

  3. When a buffer arrives:

    • PASSTHROUGH: read streams[0].index and push the buffer to src_<index>.

    • CONTAINER: for each streams[i], forward that stream’s caps to src_<index> the first time the pad is used, then push objects[0] (the source’s buffer) to that pad. If no matching src_<index> pad exists, that stream is dropped with a GST_WARNING and the others are delivered as usual. The warning is issued once per source; later drops are logged at debug level, since an unrouted source arrives at its full frame rate.

  4. EOS on the sink pad is forwarded to all source pads.

Each branch needs its own queue. The demuxer pushes to every branch from the sink pad’s streaming thread, so without one the branches cannot reach the paused state independently and the pipeline stalls. Every example below follows that rule.

Properties#

Property

Type

Default

Description

max-fps

Double

0

Output rate cap applied to each source independently (0 = unlimited), so N sources run at up to N × max-fps buffers per second in total. The wait is interrupted by a flush, so a seek does not have to sit it out. Only set for local file sources; setting on RTSP/live sources can stall the pipeline.

Pipeline Examples#

Local files with per-source FPS counters#

gst-launch-1.0 \
  gvastreammux name=mux max-fps=30 \
  ! queue \
  ! gvadetect model=model.xml device=GPU \
    pre-process-backend=va-surface-sharing \
  ! gvastreamdemux name=demux \
  demux.src_0 ! queue ! gvafpscounter ! fakesink \
  demux.src_1 ! queue ! gvafpscounter ! fakesink \
  filesrc location=video0.h265 ! h265parse ! vah265dec ! mux.sink_0 \
  filesrc location=video1.h265 ! h265parse ! vah265dec ! mux.sink_1

RTSP sources#

gst-launch-1.0 \
  gvastreammux name=mux \
  ! queue \
  ! gvadetect model=model.xml device=GPU \
    pre-process-backend=va-surface-sharing \
  ! gvastreamdemux name=demux \
  demux.src_0 ! queue ! gvafpscounter ! fakesink \
  demux.src_1 ! queue ! gvafpscounter ! fakesink \
  rtspsrc location=rtsp://host:8554/stream latency=200 \
  ! rtph265depay ! h265parse ! vah265dec ! mux.sink_0 \
  rtspsrc location=rtsp://host:8555/stream latency=200 \
  ! rtph265depay ! h265parse ! vah265dec ! mux.sink_1

Per-source watermark and display#

gst-launch-1.0 \
  gvastreammux name=mux \
  ! queue \
  ! gvadetect model=model.xml device=GPU \
    pre-process-backend=va-surface-sharing \
  ! gvastreamdemux name=demux \
  demux.src_0 ! queue ! gvawatermark ! videoconvert ! autovideosink \
  demux.src_1 ! queue ! gvawatermark ! videoconvert ! autovideosink \
  rtspsrc location=rtsp://host:8554/stream latency=200 \
  ! rtph265depay ! h265parse ! vah265dec ! mux.sink_0 \
  rtspsrc location=rtsp://host:8555/stream latency=200 \
  ! rtph265depay ! h265parse ! vah265dec ! mux.sink_1

Heterogeneous video + lidar (CONTAINER input)#

When the mux runs in CONTAINER mode, gvastreamdemux unpacks each batch back into per-source pads, restoring each source’s own caps. Note there is no gvadetect between the mux and the demux (a container buffer is not raw video). Per-stream inference (gvadetect for video, g3dinference for lidar) would attach after the corresponding demux branch; here each branch ends in fakesink:

gst-launch-1.0 -e \
  gvastreammux name=mux sync-mode=first-pts \
  ! queue \
  ! gvastreamdemux name=demux \
  demux.src_0 ! queue ! gvafpscounter ! fakesink \
  demux.src_1 ! queue ! gvafpscounter ! fakesink \
  demux.src_2 ! queue ! fakesink \
  filesrc location=video0.h265 ! h265parse ! vah265dec ! mux.sink_0 \
  filesrc location=video1.h265 ! h265parse ! vah265dec ! mux.sink_1 \
  multifilesrc location=velodyne/%06d.bin start-index=0 caps=application/octet-stream \
  ! g3dlidarparse frame-rate=10 ! mux.sink_2

Here src_0 and src_1 emit video/x-raw, while src_2 emits application/x-lidar.

Required Metadata#

gvastreamdemux requires a usable GstAnalyticsBatchMeta on every incoming buffer. The fields it reads depend on the input mode:

PASSTHROUGH input:

Field

Type

Description

streams[0].index

guint

Source pad index this buffer originated from.

n_streams

gsize

Number of contributing pads in the batch.

CONTAINER input:

Field

Type

Description

n_streams

gsize

Number of sources packed in this container.

streams[i].index

guint

Destination src_* pad for the i-th stream.

streams[i].objects[0]

GstBuffer

The buffer pushed to that pad.

streams[i].sticky_events

GstEvent

The source caps (GST_EVENT_CAPS) set on that pad.

Error Conditions#

Condition

Behavior

Buffer missing GstAnalyticsBatchMeta

GST_FLOW_ERROR (pipeline stops).

No src_<index> pad created

That source’s buffers are dropped with a GST_WARNING; every other source keeps flowing. Add the missing pad to receive its frames. Identical in both output modes.

Every branch unlinked or finished

The combined flow return goes upstream. A single such branch does not.

Pad index ≥ 256 on request, or an index already in use

request_new_pad returns NULL (rejected by the element).

Element Details (gst-inspect-1.0)#

Factory Details:
  Long-name                GVA Stream Demuxer
  Klass                    Video/Demuxer
  Description              Demuxes a single stream into multiple output pads based on
                           GstAnalyticsBatchMeta streams[0].index. Must be used with
                           gvastreammux.
  Author                   Intel Corporation

Pad Templates:
  SINK template: 'sink'    (Always, video/x-raw, video/x-raw(memory:VAMemory) NV12,
                             video/x-raw(memory:DMABuf) DMA_DRM,
                             multistream/x-analytics-batch(meta:GstAnalyticsBatchMeta);
                             on Windows video/x-raw(memory:D3D11Memory) and
                             video/x-raw(memory:D3D12Memory) NV12/BGRA instead of
                             VAMemory and DMABuf)
  SRC template:  'src_%u'  (On request, the video caps above OR application/x-lidar)

Element Properties:
  max-fps  Double, range 0-Inf, default 0

Run gst-inspect-1.0 gvastreamdemux against your installation for the authoritative output.