Class AppSink

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.freedesktop.gstreamer.gst.GstObject
org.freedesktop.gstreamer.gst.Element
org.freedesktop.gstreamer.base.BaseSink
org.freedesktop.gstreamer.app.AppSink
All Implemented Interfaces:
URIHandler, Proxy
@Generated("org.javagi.JavaGI") public class AppSink extends BaseSink implements URIHandler

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.

appsink can be used by linking to the gstappsink.h header file to access the methods or by using the appsink action signals and properties.

The normal way of retrieving samples from appsink is by using the gst_app_sink_pull_sample() and gst_app_sink_pull_preroll() methods. These methods block until a sample becomes available in the sink or when the sink is shut down or reaches EOS. There are also timed variants of these methods, gst_app_sink_try_pull_sample() and gst_app_sink_try_pull_preroll(), which accept a timeout parameter to limit the amount of time to wait.

Appsink will internally use a queue to collect buffers from the streaming thread. If the application is not pulling samples fast enough, this queue will consume a lot of memory over time. The "max-buffers", "max-time" and "max-bytes" properties can be used to limit the queue size. The "drop" property controls whether the streaming thread blocks or if older buffers are dropped when the maximum queue size is reached. Note that blocking the streaming thread can negatively affect real-time performance and should be avoided.

If a blocking behaviour is not desirable, setting the "emit-signals" property to true will make appsink emit the "new-sample" and "new-preroll" signals when a sample can be pulled without blocking.

The "caps" property on appsink can be used to control the formats that appsink can receive. This property can contain non-fixed caps, the format of the pulled samples can be obtained by getting the sample caps.

If one of the pull-preroll or pull-sample methods return null, the appsink is stopped or in the EOS state. You can check for the EOS state with the "eos" property or with the gst_app_sink_is_eos() method.

The eos signal can also be used to be informed when the EOS state is reached to avoid polling.

  • Constructor Details

    • AppSink

      public AppSink(MemorySegment address)
      Create a AppSink instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • AppSink

      public AppSink()
      Create a new AppSink.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the AppSink class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected AppSink asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class BaseSink
      Returns:
      the instance as if it were its parent type

    • getBufferListSupport

      public boolean getBufferListSupport()
      Check if this AppSink supports buffer lists.
      Returns:
      true if this AppSink supports buffer lists.
      Since:
      1.12

    • getCaps

      public @Nullable Caps getCaps()
      Get the configured caps on appsink.
      Returns:
      the GstCaps accepted by the sink. gst_caps_unref() after usage.

    • getDrop

      public boolean getDrop()
      Check if this AppSink will drop old buffers when the maximum amount of queued data is reached (meaning max buffers, time or bytes limit, whichever is hit first).
      Returns:
      true if this AppSink is dropping old buffers when the queue is filled.

    • getEmitSignals

      public boolean getEmitSignals()
      Check if appsink will emit the "new-preroll" and "new-sample" signals.
      Returns:
      true if this AppSink is emitting the "new-preroll" and "new-sample" signals.

    • getMaxBuffers

      public int getMaxBuffers()
      Get the maximum amount of buffers that can be queued in appsink.
      Returns:
      The maximum amount of buffers that can be queued.

    • getMaxBytes

      public long getMaxBytes()
      Get the maximum total size, in bytes, that can be queued in appsink.
      Returns:
      The maximum amount of bytes that can be queued
      Since:
      1.24

    • getMaxTime

      public ClockTime getMaxTime()
      Get the maximum total duration that can be queued in appsink.
      Returns:
      The maximum total duration that can be queued.
      Since:
      1.24

    • getWaitOnEos

      public boolean getWaitOnEos()
      Check if this AppSink will wait for all buffers to be consumed when an EOS is received.
      Returns:
      true if this AppSink will wait for all buffers to be consumed when an EOS is received.

    • isEos

      public boolean isEos()

      Check if this AppSink is EOS, which is when no more samples can be pulled because an EOS event was received.

      This function also returns true when the appsink is not in the PAUSED or PLAYING state.

      Returns:
      true if no more samples can be pulled and the appsink is EOS.

    • pullObject

      public @Nullable MiniObject pullObject()

      This function blocks until a sample or an event 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 buffers and events will be put in a queue so that the application can pull them at its own rate. Note that when the application does not pull samples fast enough, the queued buffers could consume a lot of memory, especially when dealing with raw video frames. Events can be pulled when the appsink is in the READY, PAUSED or PLAYING state.

      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 method is a variant of gst_app_sink_pull_sample() that can be used to handle incoming events 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.

      Returns:
      a GstSample, or a GstEvent or NULL when the appsink is stopped or EOS. Call gst_mini_object_unref() after usage.
      Since:
      1.20

    • pullPreroll

      public @Nullable Sample pullPreroll()

      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().

      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.

      Returns:
      a GstSample or NULL when the appsink is stopped or EOS. Call gst_sample_unref() after usage.

    • pullSample

      public @Nullable Sample pullSample()

      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 buffers 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 buffers could consume a lot of memory, especially when dealing with raw video frames.

      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.

      Returns:
      a GstSample or NULL when the appsink is stopped or EOS. Call gst_sample_unref() after usage.

    • setBufferListSupport

      public void setBufferListSupport(boolean enableLists)

      Instruct this AppSink to enable or disable buffer list support.

      For backwards-compatibility reasons applications need to opt in to indicate that they will be able to handle buffer lists.

      Parameters:
      enableLists - enable or disable buffer list support
      Since:
      1.12

    • setCallbacks

      public void setCallbacks(AppSinkCallbacks callbacks, @Nullable MemorySegment userData)

      Set callbacks which will be executed for each new preroll, new sample and eos. This is an alternative to using the signals, it has lower overhead and is thus less expensive, but also less flexible.

      If callbacks are installed, no signals will be emitted for performance reasons.

      Before 1.16.3 it was not possible to change the callbacks in a thread-safe way.

      Parameters:
      callbacks - the callbacks
      userData - a user_data argument for the callbacks

    • setCapabilities

      public void setCapabilities(@Nullable Caps caps)
      Set the capabilities on the appsink element. This function takes a copy of the caps structure. After calling this method, the sink will only accept caps that match caps. If caps is non-fixed, or incomplete, you must check the caps on the samples to get the actual used caps.
      Parameters:
      caps - caps to set

    • setDrop

      public void setDrop(boolean drop)
      Instruct this AppSink to drop old buffers when the maximum amount of queued data is reached, that is, when any configured limit is hit (max-buffers, max-time or max-bytes).
      Parameters:
      drop - the new state

    • setEmitSignals

      public void setEmitSignals(boolean emit)
      Make appsink emit the "new-preroll" and "new-sample" signals. This option is by default disabled because signal emission is expensive and unneeded when the application prefers to operate in pull mode.
      Parameters:
      emit - the new state

    • setMaxBuffers

      public void setMaxBuffers(int max)
      Set the maximum amount of buffers that can be queued in appsink. After this amount of buffers are queued in appsink, any more buffers will block upstream elements until a sample is pulled from appsink, unless 'drop' is set, in which case new buffers will be discarded.
      Parameters:
      max - the maximum number of buffers to queue

    • setMaxBytes

      public void setMaxBytes(long max)
      Set the maximum total size that can be queued in appsink. After this amount of buffers are queued in appsink, any more buffers will block upstream elements until a sample is pulled from appsink, unless 'drop' is set, in which case new buffers will be discarded.
      Parameters:
      max - the maximum total size of buffers to queue, in bytes
      Since:
      1.24

    • setMaxTime

      public void setMaxTime(ClockTime max)
      Set the maximum total duration that can be queued in appsink. After this amount of buffers are queued in appsink, any more buffers will block upstream elements until a sample is pulled from appsink, unless 'drop' is set, in which case new buffers will be discarded.
      Parameters:
      max - the maximum total duration to queue
      Since:
      1.24

    • setWaitOnEos

      public void setWaitOnEos(boolean wait_)
      Instruct this AppSink to wait for all buffers to be consumed when an EOS is received.
      Parameters:
      wait_ - the new state

    • tryPullObject

      public @Nullable MiniObject tryPullObject(ClockTime timeout)

      This function blocks until a sample or an event 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 buffers and events will be put in a queue so that the application can pull them at its own rate. Note that when the application does not pull samples fast enough, the queued buffers could consume a lot of memory, especially when dealing with raw video frames. Events can be pulled when the appsink is in the READY, PAUSED or PLAYING state.

      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 method is a variant of gst_app_sink_try_pull_sample() that can be used to handle incoming events 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:
      timeout - the maximum amount of time to wait for a sample
      Returns:
      a GstSample, or GstEvent or NULL when the appsink is stopped or EOS or the timeout expires. Call gst_mini_object_unref() after usage.
      Since:
      1.20

    • tryPullPreroll

      public @Nullable Sample tryPullPreroll(ClockTime 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().

      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:
      timeout - the maximum amount of time to wait for the preroll sample
      Returns:
      a GstSample or NULL when the appsink is stopped or EOS or the timeout expires. Call gst_sample_unref() after usage.
      Since:
      1.10

    • tryPullSample

      public @Nullable Sample tryPullSample(ClockTime 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 buffers 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 buffers could consume a lot of memory, especially when dealing with raw video frames.

      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:
      timeout - the maximum amount of time to wait for a sample
      Returns:
      a GstSample or NULL when the appsink is stopped or EOS or the timeout expires. Call gst_sample_unref() after usage.
      Since:
      1.10

    • eos

      protected void eos()

    • newPreroll

      protected FlowReturn newPreroll()

    • newSample

      protected FlowReturn newSample()

    • onEos

      public SignalConnection<AppSink.EosCallback> onEos(AppSink.EosCallback handler)
      Signal that the end-of-stream has been reached. This signal is emitted from the streaming thread.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitEos

      public void emitEos()
      Emits the "eos" signal. See onEos(AppSink.EosCallback).

    • onNewPreroll

      public SignalConnection<AppSink.NewPrerollCallback> onNewPreroll(AppSink.NewPrerollCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitNewPreroll

      public FlowReturn emitNewPreroll()
      Emits the "new-preroll" signal. See onNewPreroll(AppSink.NewPrerollCallback).

    • onNewSample

      public SignalConnection<AppSink.NewSampleCallback> onNewSample(AppSink.NewSampleCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitNewSample

      public FlowReturn emitNewSample()
      Emits the "new-sample" signal. See onNewSample(AppSink.NewSampleCallback).

    • onNewSerializedEvent

      public SignalConnection<AppSink.NewSerializedEventCallback> onNewSerializedEvent(AppSink.NewSerializedEventCallback handler)

      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 GstAppSink::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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.20
      See Also:

    • emitNewSerializedEvent

      public boolean emitNewSerializedEvent()
      Emits the "new-serialized-event" signal. See onNewSerializedEvent(AppSink.NewSerializedEventCallback).

    • onProposeAllocation

      public SignalConnection<AppSink.ProposeAllocationCallback> onProposeAllocation(AppSink.ProposeAllocationCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.24
      See Also:

    • emitProposeAllocation

      public boolean emitProposeAllocation(@Nullable Query query)
      Emits the "propose-allocation" signal. See onProposeAllocation(AppSink.ProposeAllocationCallback).

    • onPullPreroll

      public SignalConnection<AppSink.PullPrerollCallback> onPullPreroll(AppSink.PullPrerollCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitPullPreroll

      public Sample emitPullPreroll()
      Emits the "pull-preroll" signal. See onPullPreroll(AppSink.PullPrerollCallback).

    • onPullSample

      public SignalConnection<AppSink.PullSampleCallback> onPullSample(AppSink.PullSampleCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitPullSample

      public Sample emitPullSample()
      Emits the "pull-sample" signal. See onPullSample(AppSink.PullSampleCallback).

    • onTryPullPreroll

      public SignalConnection<AppSink.TryPullPrerollCallback> onTryPullPreroll(AppSink.TryPullPrerollCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.10
      See Also:

    • emitTryPullPreroll

      public Sample emitTryPullPreroll(long timeout)
      Emits the "try-pull-preroll" signal. See onTryPullPreroll(AppSink.TryPullPrerollCallback).

    • onTryPullSample

      public SignalConnection<AppSink.TryPullSampleCallback> onTryPullSample(AppSink.TryPullSampleCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.10
      See Also:

    • emitTryPullSample

      public Sample emitTryPullSample(long timeout)
      Emits the "try-pull-sample" signal. See onTryPullSample(AppSink.TryPullSampleCallback).

    • builder

      public static AppSink.Builder<? extends AppSink.Builder> builder()
      A AppSink.Builder object constructs a AppSink with the specified properties. Use the various set...() methods to set properties, and finish construction with AppSink.Builder.build().
      Returns:
      the builder object