multiqueue: GStreamer Core Plugins 1.0 Plugins Reference Manual

multiqueue

Properties

guint	extra-size-buffers	Read / Write
guint	extra-size-bytes	Read / Write
guint64	extra-size-time	Read / Write
gint	high-percent	Read / Write
gint	low-percent	Read / Write
guint	max-size-buffers	Read / Write
guint	max-size-bytes	Read / Write
guint64	max-size-time	Read / Write
gboolean	sync-by-running-time	Read / Write
gboolean	use-buffering	Read / Write
guint64	unlinked-cache-time	Read / Write
gboolean	use-interleave	Read / Write
gdouble	high-watermark	Read / Write
gdouble	low-watermark	Read / Write

Signals

void	overrun	Run First
void	underrun	Run First

Types and Values

struct

GstMultiQueue

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GstObject
            ╰── GstElement
                ╰── GstMultiQueue

Description

Multiqueue is similar to a normal GstQueue with the following additional features:

Multiple streamhandling
- The element handles queueing data on more than one stream at once. To achieve such a feature it has request sink pads (sinku) and 'sometimes' src pads (srcu).
  
  When requesting a given sinkpad with gst_element_request_pad(), the associated srcpad for that stream will be created. Example: requesting sink1 will generate src1.
Non-starvation on multiple streams
- If more than one stream is used with the element, the streams' queues will be dynamically grown (up to a limit), in order to ensure that no stream is risking data starvation. This guarantees that at any given time there are at least N bytes queued and available for each individual stream.
  
  If an EOS event comes through a srcpad, the associated queue will be considered as 'not-empty' in the queue-size-growing algorithm.
Non-linked srcpads graceful handling
- In order to better support dynamic switching between streams, the multiqueue (unlike the current GStreamer queue) continues to push buffers on non-linked pads rather than shutting down.
  
  In addition, to prevent a non-linked stream from very quickly consuming all available buffers and thus 'racing ahead' of the other streams, the element must ensure that buffers and inlined events for a non-linked stream are pushed in the same order as they were received, relative to the other streams controlled by the element. This means that a buffer cannot be pushed to a non-linked pad any sooner than buffers in any other stream which were received before it.

Data is queued until one of the limits specified by the “max-size-buffers”, “max-size-bytes” and/or “max-size-time” properties has been reached. Any attempt to push more buffers into the queue will block the pushing thread until more space becomes available. “extra-size-buffers”,

“extra-size-bytes” and “extra-size-time” are currently unused.

The default queue size limits are 5 buffers, 10MB of data, or two second worth of data, whichever is reached first. Note that the number of buffers will dynamically grow depending on the fill level of other queues.

The “underrun” signal is emitted when all of the queues are empty. The “overrun” signal is emitted when one of the queues is filled. Both signals are emitted from the context of the streaming thread.

When using “sync-by-running-time” the unlinked streams will be throttled by the highest running-time of linked streams. This allows further relinking of those unlinked streams without them being in the future (i.e. to achieve gapless playback). When dealing with streams which have got different consumption requirements downstream (ex: video decoders which will consume more buffer (in time) than audio decoders), it is recommended to group streams of the same type by using the pad "group-id" property. This will further throttle streams in time within that group.

Synopsis

Element Information

plugin	coreelements
author	Edward Hervey <edward@fluendo.com>
class	Generic

Element Pads

name	sink_%u
direction	sink
presence	request
details	ANY

name	src_%u
direction	source
presence	sometimes
details	ANY

Functions

Types and Values

struct GstMultiQueue

struct GstMultiQueue;

Opaque GstMultiQueue structure.

Property Details

The `“extra-size-buffers”` property

  “extra-size-buffers”       guint

Amount of buffers the queues can grow if one of them is empty (0=disable) (NOT IMPLEMENTED).

Flags: Read / Write

Default value: 5

The `“extra-size-bytes”` property

  “extra-size-bytes”         guint

Amount of data the queues can grow if one of them is empty (bytes, 0=disable) (NOT IMPLEMENTED).

Flags: Read / Write

Default value: 10485760

The `“extra-size-time”` property

  “extra-size-time”          guint64

Amount of time the queues can grow if one of them is empty (in ns, 0=disable) (NOT IMPLEMENTED).

Flags: Read / Write

Default value: 3000000000

The `“high-percent”` property

  “high-percent”             gint

High threshold percent for buffering to finish.

Flags: Read / Write

Allowed values: [0,100]

Default value: 99

The `“low-percent”` property

  “low-percent”              gint

Low threshold percent for buffering to start.

Flags: Read / Write

Allowed values: [0,100]

Default value: 1

The `“max-size-buffers”` property

  “max-size-buffers”         guint

Max. number of buffers in the queue (0=disable).

Flags: Read / Write

Default value: 5

The `“max-size-bytes”` property

  “max-size-bytes”           guint

Max. amount of data in the queue (bytes, 0=disable).

Flags: Read / Write

Default value: 10485760

The `“max-size-time”` property

  “max-size-time”            guint64

Max. amount of data in the queue (in ns, 0=disable).

Flags: Read / Write

Default value: 2000000000

The `“sync-by-running-time”` property

  “sync-by-running-time”     gboolean

If enabled multiqueue will synchronize deactivated or not-linked streams to the activated and linked streams by taking the running time. Otherwise multiqueue will synchronize the deactivated or not-linked streams by keeping the order in which buffers and events arrived compared to active and linked streams.

Flags: Read / Write

Default value: FALSE

The `“use-buffering”` property

  “use-buffering”            gboolean

Enable the buffering option in multiqueue so that BUFFERING messages are emitted based on low-/high-percent thresholds.

Flags: Read / Write

Default value: FALSE

The `“unlinked-cache-time”` property

  “unlinked-cache-time”      guint64

Extra buffering in time for unlinked streams (if 'sync-by-running-time').

Flags: Read / Write

Default value: 250000000

The `“use-interleave”` property

  “use-interleave”           gboolean

Adjust time limits based on input interleave.

Flags: Read / Write

Default value: FALSE

The `“high-watermark”` property

  “high-watermark”           gdouble

High threshold watermark for buffering to finish.

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.99

Since: 1.10

The `“low-watermark”` property

  “low-watermark”            gdouble

Low threshold watermark for buffering to start.

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.01

Since: 1.10

Signal Details

The `“overrun”` signal

void
user_function (GstMultiQueue *multiqueue,
               gpointer       user_data)

Reports that one of the queues in the multiqueue is full (overrun). A queue is full if the total amount of data inside it (num-buffers, time, size) is higher than the boundary values which can be set through the GObject properties.

This can be used as an indicator of pre-roll.

Parameters

multiqueue	the multiqueue instance
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“underrun”` signal

void
user_function (GstMultiQueue *multiqueue,
               gpointer       user_data)

This signal is emitted from the streaming thread when there is no data in any of the queues inside the multiqueue instance (underrun).

This indicates either starvation or EOS from the upstream data sources.

Parameters

multiqueue	the multiqueue instance
user_data	user data set when the signal handler was connected.

Flags: Run First

multiqueue

Properties

Signals

Types and Values

Object Hierarchy

Description

Synopsis

Element Information

Element Pads

Functions

Types and Values

struct GstMultiQueue

Property Details

The “extra-size-buffers” property

The “extra-size-bytes” property

The “extra-size-time” property

The “high-percent” property

The “low-percent” property

The “max-size-buffers” property

The “max-size-bytes” property

The “max-size-time” property

The “sync-by-running-time” property

The “use-buffering” property

The “unlinked-cache-time” property

The “use-interleave” property

The “high-watermark” property

The “low-watermark” property

Signal Details

The “overrun” signal

Parameters

The “underrun” signal

Parameters

See Also

The `“extra-size-buffers”` property

The `“extra-size-bytes”` property

The `“extra-size-time”` property

The `“high-percent”` property

The `“low-percent”` property

The `“max-size-buffers”` property

The `“max-size-bytes”` property

The `“max-size-time”` property

The `“sync-by-running-time”` property

The `“use-buffering”` property

The `“unlinked-cache-time”` property

The `“use-interleave”` property

The `“high-watermark”` property

The `“low-watermark”` property

The `“overrun”` signal

The `“underrun”` signal