queue: GStreamer Core Plugins 1.0 Plugins Reference Manual

## queue queue |

## Properties

guint | current-level-buffers | Read
guint | current-level-bytes | Read
guint64 | current-level-time | Read
gboolean | flush-on-eos | Read / Write
GstQueueLeaky | leaky | Read / Write
guint | max-size-buffers | Read / Write
guint | max-size-bytes | Read / Write
guint64 | max-size-time | Read / Write
guint | min-threshold-buffers | Read / Write
guint | min-threshold-bytes | Read / Write
guint64 | min-threshold-time | Read / Write
gboolean | silent | Read / Write

## Signals

void | overrun | Run First
void | pushing | Run First
void | running | Run First
void | underrun | Run First

## Types and Values

struct | GstQueue
enum | GstQueueLeaky

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstQueue

## Description

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.

The queue will create a new thread on the source pad to decouple the processing on sink and source pad.

You can query how many buffers are queued by reading the “current-level-buffers” property. You can track changes by connecting to the notify::current-level-buffers signal (which like all signals will be emitted from the streaming thread). The same applies to the “current-level-time” and “current-level-bytes” properties.

The default queue size limits are 200 buffers, 10MB of data, or one second worth of data, whichever is reached first.

As said earlier, the queue blocks by default when one of the specified maximums (bytes, time, buffers) has been reached. You can set the “leaky” property to specify that instead of blocking it should leak (drop) new or old buffers.

The “underrun” signal is emitted when the queue has less data than the specified minimum thresholds require (by default: when the queue is empty). The “overrun” signal is emitted when the queue is filled up. Both signals are emitted from the context of the streaming thread.

## Synopsis

### Element Information

plugin | coreelements
author | Erik Walthinsen <omega@cse.ogi.edu>
class | Generic

### Element Pads

name | sink
direction | sink
presence | always
details | ANY

name | src
direction | source
presence | always
details | ANY

## Functions

## Types and Values

### struct GstQueue

    struct GstQueue;

Opaque GstQueue structure.

### enum GstQueueLeaky

Buffer dropping scheme to avoid the queue to block when full.

#### Members

GST_QUEUE_NO_LEAK | Not Leaky |
GST_QUEUE_LEAK_UPSTREAM | Leaky on upstream (new buffers) |
GST_QUEUE_LEAK_DOWNSTREAM | Leaky on downstream (old buffers) |

## Property Details

### The `“current-level-buffers”` property

      “current-level-buffers”    guint

Current number of buffers in the queue.

Flags: Read

Default value: 0

### The `“current-level-bytes”` property

      “current-level-bytes”      guint

Current amount of data in the queue (bytes).

Flags: Read

Default value: 0

### The `“current-level-time”` property

      “current-level-time”       guint64

Current amount of data in the queue (in ns).

Flags: Read

Default value: 0

### The `“flush-on-eos”` property

      “flush-on-eos”             gboolean

Discard all data in the queue when an EOS event is received, and pass on the EOS event as soon as possible (instead of waiting until all buffers in the queue have been processed, which is the default behaviour).

Flushing the queue on EOS might be useful when capturing and encoding from a live source, to finish up the recording quickly in cases when the encoder is slow. Note that this might mean some data from the end of the recording data might be lost though (never more than the configured max. sizes though).

Flags: Read / Write

Default value: FALSE

Since: 1.2

### The `“leaky”` property

      “leaky”                    GstQueueLeaky

Where the queue leaks, if at all.

Flags: Read / Write

Default value: Not Leaky

### The `“max-size-buffers”` property

      “max-size-buffers”         guint

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

Flags: Read / Write

Default value: 200

### 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: 1000000000

### The `“min-threshold-buffers”` property

      “min-threshold-buffers”    guint

Min. number of buffers in the queue to allow reading (0=disable).

Flags: Read / Write

Default value: 0

### The `“min-threshold-bytes”` property

      “min-threshold-bytes”      guint

Min. amount of data in the queue to allow reading (bytes, 0=disable).

Flags: Read / Write

Default value: 0

### The `“min-threshold-time”` property

      “min-threshold-time”       guint64

Min. amount of data in the queue to allow reading (in ns, 0=disable).

Flags: Read / Write

Default value: 0

### The `“silent”` property

      “silent”                   gboolean

Don't emit queue signals. Makes queues more lightweight if no signals are needed.

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“overrun”` signal

    void
    user_function (GstQueue *queue,
                   gpointer  user_data)

Reports that the buffer became full (overrun). A buffer 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.

#### Parameters

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

Flags: Run First

### The `“pushing”` signal

    void
    user_function (GstQueue *queue,
                   gpointer  user_data)

Reports when the queue has enough data to start pushing data again on the source pad.

#### Parameters

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

Flags: Run First

### The `“running”` signal

    void
    user_function (GstQueue *queue,
                   gpointer  user_data)

Reports that enough (min-threshold) data is in the queue. Use this signal together with the underrun signal to pause the pipeline on underrun and wait for the queue to fill-up before resume playback.

#### Parameters

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

Flags: Run First

### The `“underrun”` signal

    void
    user_function (GstQueue *queue,
                   gpointer  user_data)

Reports that the buffer became empty (underrun). A buffer is empty if the total amount of data inside it (num-buffers, time, size) is lower than the boundary values which can be set through the GObject properties.

#### Parameters

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

Flags: Run First