## appsink

appsink — Allow the application to get access to raw buffer

## Synopsis

                        GstAppSink;

## Object Hierarchy

      GObject
       +----GstObject
             +----GstElement
                   +----GstBaseSink
                         +----GstAppSink

## Implemented Interfaces

GstAppSink implements GstURIHandler.

## Properties

      "caps"                     GstCaps*              : Read / Write
      "drop"                     gboolean              : Read / Write
      "emit-signals"             gboolean              : Read / Write
      "eos"                      gboolean              : Read
      "max-buffers"              guint                 : Read / Write

## Signals

      "eos"                                            : Run Last
      "new-buffer"                                     : Run Last
      "new-preroll"                                    : Run Last
      "pull-buffer"                                    : Run Last / Action
      "pull-preroll"                                   : Run Last / Action
      "new-buffer-list"                                : Run Last
      "pull-buffer-list"                               : Run Last / Action

## Description

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.

## Details

### GstAppSink

    typedef struct _GstAppSink GstAppSink;

## Property Details

### The `"caps"` property

      "caps"                     GstCaps*              : Read / Write

The allowed caps for the sink pad.

### The `"drop"` property

      "drop"                     gboolean              : Read / Write

Drop old buffers when the buffer queue is filled.

Default value: FALSE

### The `"emit-signals"` property

      "emit-signals"             gboolean              : Read / Write

Emit new-preroll and new-buffer signals.

Default value: FALSE

### The `"eos"` property

      "eos"                      gboolean              : Read

Check if the sink is EOS or not started.

Default value: TRUE

### The `"max-buffers"` property

      "max-buffers"              guint                 : Read / Write

The maximum number of buffers to queue internally (0 = unlimited).

Default value: 0

## Signal Details

### The `"eos"` signal

    void                user_function                      (GstAppSink *appsink,
                                                            gpointer    user_data)      : Run Last

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

`appsink` : | the appsink element that emited the signal
`user_data` : | user data set when the signal handler was connected.

### The `"new-buffer"` signal

    void                user_function                      (GstAppSink *appsink,
                                                            gpointer    user_data)      : Run Last

Signal that a new buffer is available.

This signal is emited from the steaming thread and only when the "emit-signals" property is `TRUE`.

The new buffer can be retrieved with the "pull-buffer" action signal or `gst_app_sink_pull_buffer()` either from this signal callback or from any other thread.

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

`appsink` : | the appsink element that emited the signal
`user_data` : | user data set when the signal handler was connected.

### The `"new-preroll"` signal

    void                user_function                      (GstAppSink *appsink,
                                                            gpointer    user_data)      : Run Last

Signal that a new preroll buffer is available.

This signal is emited from the steaming thread and only when the "emit-signals" property is `TRUE`.

The new preroll buffer 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 emited when the "emit-signals" property is set to `TRUE`, which it is not by default for performance reasons.

`appsink` : | the appsink element that emited the signal
`user_data` : | user data set when the signal handler was connected.

### The `"pull-buffer"` signal

    GstBuffer*          user_function                      (GstAppSink *appsink,
                                                            gpointer    user_data)      : Run Last / Action

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

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

Note that when the application does not pull buffers fast enough, the queued buffers 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" 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.

`appsink` : | the appsink element to emit this signal on
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstBuffer or NULL when the appsink is stopped or EOS.

### The `"pull-preroll"` signal

    GstBuffer*          user_function                      (GstAppSink *appsink,
                                                            gpointer    user_data)      : Run Last / Action

Get the last preroll buffer in `appsink`. This was the buffer that caused the appsink to preroll in the PAUSED state. This buffer can be pulled many times and remains available to the application even after EOS.

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

Note that the preroll buffer will also be returned as the first buffer when calling `gst_app_sink_pull_buffer()` or the "pull-buffer" 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 buffer or EOS is received or the appsink element is set to the READY/NULL state.

`appsink` : | the appsink element to emit this signal on
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstBuffer or NULL when the appsink is stopped or EOS.

### The `"new-buffer-list"` signal

    void                user_function                      (GstAppSink *appsink,
                                                            gpointer    user_data)      : Run Last

Signal that a new bufferlist is available.

This signal is emited from the steaming thread and only when the "emit-signals" property is `TRUE`.

The new buffer can be retrieved with the "pull-buffer-list" action signal or `gst_app_sink_pull_buffer_list()` either from this signal callback or from any other thread.

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

`appsink` : | the appsink element that emited the signal
`user_data` : | user data set when the signal handler was connected.

### The `"pull-buffer-list"` signal

    GstBufferList*      user_function                      (GstAppSink *appsink,
                                                            gpointer    user_data)      : Run Last / Action

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

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

Note that when the application does not pull bufferlists fast enough, the queued bufferlists 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" 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.

`appsink` : | the appsink element to emit this signal on
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstBufferList or NULL when the appsink is stopped or EOS.