# appsink

Appsink is a sink plugin that supports many different methods for making the application get a handle on the GStreamer data in a pipeline. Unlike most GStreamer elements, Appsink provides external API functions.

For the documentation of the API, please see the

libgstapp section in the GStreamer Plugins Base Libraries documentation.

## Hierarchy

    GObject
        ╰──GInitiallyUnowned
            ╰──GstObject
                ╰──GstElement
                    ╰──GstBaseSink
                        ╰──appsink

## Implemented interfaces

    GstURIHandler

## Factory details

Authors: – David Schleef , Wim Taymans

Classification: – `Generic/Sink`

Rank – none

Plugin – app

Package – GStreamer Base Plug-ins

## Pad Templates

### `sink`

    ANY

Presence – always

Direction – sink

Object type – GstPad

## Signals

### eos

    eos_callback (GstElement * appsink,
                  gpointer udata)

    def eos_callback (appsink, udata):
        #python callback for the 'eos' signal

    function eos_callback(appsink: GstElement * appsink, udata: gpointer udata): {
        // javascript callback for the 'eos' signal
    }

Signal that the end-of-stream has been reached. This signal is emitted from the streaming thread.

Parameters:

`appsink` –

the appsink element that emitted the signal

`udata` –
No description available

Flags: Run Last

### new-preroll

    GstFlowReturn *
    new_preroll_callback (GstElement * appsink,
                          gpointer udata)

    def new_preroll_callback (appsink, udata):
        #python callback for the 'new-preroll' signal

    function new_preroll_callback(appsink: GstElement * appsink, udata: gpointer udata): {
        // javascript callback for the 'new-preroll' signal
    }

Signal that a new preroll sample is available.

This signal is emitted from the streaming thread and only when the "emit-signals" property is TRUE.

The new preroll sample can be retrieved with the "pull-preroll" action signal or gst_app_sink_pull_preroll either from this signal callback or from any other thread.

Note that this signal is only emitted when the "emit-signals" property is set to TRUE, which it is not by default for performance reasons.

Parameters:

`appsink` –

the appsink element that emitted the signal

`udata` –
No description available
Returns (GstFlowReturn *) –
No description available

Flags: Run Last

### new-sample

    GstFlowReturn *
    new_sample_callback (GstElement * appsink,
                         gpointer udata)

    def new_sample_callback (appsink, udata):
        #python callback for the 'new-sample' signal

    function new_sample_callback(appsink: GstElement * appsink, udata: gpointer udata): {
        // javascript callback for the 'new-sample' signal
    }

Signal that a new sample is available.

This signal is emitted from the streaming thread and only when the "emit-signals" property is TRUE.

The new sample can be retrieved with the "pull-sample" action signal or gst_app_sink_pull_sample either from this signal callback or from any other thread.

Note that this signal is only emitted when the "emit-signals" property is set to TRUE, which it is not by default for performance reasons.

Parameters:

`appsink` –

the appsink element that emitted the signal

`udata` –
No description available
Returns (GstFlowReturn *) –
No description available

Flags: Run Last

### new-serialized-event

    gboolean
    new_serialized_event_callback (GstElement * appsink,
                                   gpointer udata)

    def new_serialized_event_callback (appsink, udata):
        #python callback for the 'new-serialized-event' signal

    function new_serialized_event_callback(appsink: GstElement * appsink, udata: gpointer udata): {
        // javascript callback for the 'new-serialized-event' signal
    }

Signal that a new downstream serialized event is available.

This signal is emitted from the streaming thread and only when the "emit-signals" property is TRUE.

The new event can be retrieved with the "try-pull-object" action signal or gst_app_sink_pull_object either from this signal callback or from any other thread.

EOS will not be notified using this signal, use eos instead. EOS cannot be pulled either, use gst_app_sink_is_eos to check for it.

Note that this signal is only emitted when the "emit-signals" property is set to TRUE, which it is not by default for performance reasons.

The callback should return TRUE if the event has been handled, which will skip basesink handling of the event, FALSE otherwise.

Parameters:

`appsink` –

the appsink element that emitted the signal

`udata` –
No description available
Returns (gboolean) –
No description available

Flags: Run Last

Since : 1.20

### propose-allocation

    gboolean
    propose_allocation_callback (GstElement * appsink,
                                 GstQuery * query,
                                 gpointer udata)

    def propose_allocation_callback (appsink, query, udata):
        #python callback for the 'propose-allocation' signal

    function propose_allocation_callback(appsink: GstElement * appsink, query: GstQuery * query, udata: gpointer udata): {
        // javascript callback for the 'propose-allocation' signal
    }

Signal that a new propose_allocation query is available.

This signal is emitted from the streaming thread and only when the "emit-signals" property is TRUE.

Parameters:

`appsink` –

the appsink element that emitted the signal

`query` –

the allocation query

`udata` –
No description available
Returns (gboolean) –
No description available

Flags: Run Last

Since : 1.24

## Action Signals

### pull-preroll

    g_signal_emit_by_name (appsink, "pull-preroll", &ret);

    ret = appsink.emit ("pull-preroll")

    let ret = appsink.emit ("pull-preroll");

Get the last preroll sample in appsink. This was the sample that caused the appsink to preroll in the PAUSED state.

This function is typically used when dealing with a pipeline in the PAUSED state. Calling this function after doing a seek will give the sample right after the seek position.

Calling this function will clear the internal reference to the preroll buffer.

Note that the preroll sample will also be returned as the first sample when calling gst_app_sink_pull_sample or the "pull-sample" action signal.

If an EOS event was received before any buffers, this function returns NULL. Use gst_app_sink_is_eos () to check for the EOS condition.

This function blocks until a preroll sample or EOS is received or the appsink element is set to the READY/NULL state.

Parameters:

`appsink` (GstElement *) –

the appsink element to emit this signal on

Returns (GstSample *) –

a GstSample or NULL when the appsink is stopped or EOS.

Flags: Run Last / Action

### pull-sample

    g_signal_emit_by_name (appsink, "pull-sample", &ret);

    ret = appsink.emit ("pull-sample")

    let ret = appsink.emit ("pull-sample");

This function blocks until a sample or EOS becomes available or the appsink element is set to the READY/NULL state.

This function will only return samples when the appsink is in the PLAYING state. All rendered samples will be put in a queue so that the application can pull samples at its own rate.

Note that when the application does not pull samples fast enough, the queued samples could consume a lot of memory, especially when dealing with raw video frames. It's possible to control the behaviour of the queue with the "drop" and "max-buffers" / "max-bytes" / "max-time" set of properties.

If an EOS event was received before any buffers, this function returns NULL. Use gst_app_sink_is_eos () to check for the EOS condition.

Parameters:

`appsink` (GstElement *) –

the appsink element to emit this signal on

Returns (GstSample *) –

a GstSample or NULL when the appsink is stopped or EOS.

Flags: Run Last / Action

### try-pull-object

    g_signal_emit_by_name (appsink, "try-pull-object", timeout, &ret);

    ret = appsink.emit ("try-pull-object", timeout)

    let ret = appsink.emit ("try-pull-object", timeout);

This function blocks until a sample or an event becomes available or the appsink element is set to the READY/NULL state or the timeout expires.

This function will only return samples when the appsink is in the PLAYING state. All rendered samples and events will be put in a queue so that the application can pull them at its own rate. Events can be pulled when the appsink is in the READY, PAUSED or PLAYING state.

Note that when the application does not pull samples fast enough, the queued samples could consume a lot of memory, especially when dealing with raw video frames. It's possible to control the behaviour of the queue with the "drop" and "max-buffers" / "max-bytes" / "max-time" set of properties.

This function will only pull serialized events, excluding the EOS event for which this functions returns NULL. Use gst_app_sink_is_eos to check for the EOS condition.

This signal is a variant of try-pull-sample: that can be used to handle incoming events as well as samples.

Note that future releases may extend this API to return other object types so make sure that your code is checking for the actual type it is handling.

Parameters:

`appsink` (GstElement *) –

the appsink element to emit this signal on

`timeout` (guint64) –

the maximum amount of time to wait for a sample

Returns (GstMiniObject *) –

a GstSample or a GstEvent or NULL when the appsink is stopped or EOS or the timeout expires.

Flags: Run Last / Action

Since : 1.20

### try-pull-preroll

    g_signal_emit_by_name (appsink, "try-pull-preroll", timeout, &ret);

    ret = appsink.emit ("try-pull-preroll", timeout)

    let ret = appsink.emit ("try-pull-preroll", timeout);

Get the last preroll sample in appsink. This was the sample that caused the appsink to preroll in the PAUSED state.

This function is typically used when dealing with a pipeline in the PAUSED state. Calling this function after doing a seek will give the sample right after the seek position.

Calling this function will clear the internal reference to the preroll buffer.

Note that the preroll sample will also be returned as the first sample when calling gst_app_sink_pull_sample or the "pull-sample" action signal.

If an EOS event was received before any buffers or the timeout expires, this function returns NULL. Use gst_app_sink_is_eos () to check for the EOS condition.

This function blocks until a preroll sample or EOS is received, the appsink element is set to the READY/NULL state, or the timeout expires.

Parameters:

`appsink` (GstElement *) –

the appsink element to emit this signal on

`timeout` (guint64) –

the maximum amount of time to wait for the preroll sample

Returns (GstSample *) –

a GstSample or NULL when the appsink is stopped or EOS or the timeout expires.

Flags: Run Last / Action

Since : 1.10

### try-pull-sample

    g_signal_emit_by_name (appsink, "try-pull-sample", timeout, &ret);

    ret = appsink.emit ("try-pull-sample", timeout)

    let ret = appsink.emit ("try-pull-sample", timeout);

This function blocks until a sample or EOS becomes available or the appsink element is set to the READY/NULL state or the timeout expires.

This function will only return samples when the appsink is in the PLAYING state. All rendered samples will be put in a queue so that the application can pull samples at its own rate.

Note that when the application does not pull samples fast enough, the queued samples could consume a lot of memory, especially when dealing with raw video frames. It's possible to control the behaviour of the queue with the "drop" and "max-buffers" / "max-bytes" / "max-time" set of properties.

If an EOS event was received before any buffers or the timeout expires, this function returns NULL. Use gst_app_sink_is_eos () to check for the EOS condition.

Parameters:

`appsink` (GstElement *) –

the appsink element to emit this signal on

`timeout` (guint64) –

the maximum amount of time to wait for a sample

Returns (GstSample *) –

a GstSample or NULL when the appsink is stopped or EOS or the timeout expires.

Flags: Run Last / Action

Since : 1.10

## Properties

### buffer-list

    “buffer-list” gboolean

Use buffer lists

Flags : Read / Write

Default value : false

### caps

    “caps” GstCaps *

The allowed caps for the sink pad

Flags : Read / Write

### drop

    “drop” gboolean

Drop old buffers when the buffer queue is filled

Flags : Read / Write

Default value : false

### emit-signals

    “emit-signals” gboolean

Emit new-preroll and new-sample signals

Flags : Read / Write

Default value : false

### eos

    “eos” gboolean

Check if the sink is EOS or not started

Flags : Read

Default value : true

### max-buffers

    “max-buffers” guint

Maximum amount of buffers in the queue (0 = unlimited).

Flags : Read / Write

Default value : 0

### max-bytes

    “max-bytes” guint64

Maximum amount of bytes in the queue (0 = unlimited)

Flags : Read / Write

Default value : 0

Since : 1.24

### max-time

    “max-time” guint64

Maximum total duration of data in the queue (0 = unlimited)

Flags : Read / Write

Default value : 0

Since : 1.24

### wait-on-eos

    “wait-on-eos” gboolean

Wait for all buffers to be processed after receiving an EOS.

In cases where it is uncertain if an appsink will have a consumer for its buffers when it receives an EOS, set to FALSE to ensure that the appsink will not hang.

Flags : Read / Write

Default value : true

Since : 1.8

The results of the search are