gstaudiobasesink

gstaudiobasesink — Base class for audio sinks

Synopsis

#include <gst/audio/gstaudiobasesink.h>

struct              GstAudioBaseSink;
struct              GstAudioBaseSinkClass;
enum                GstAudioBaseSinkSlaveMethod;
enum                GstAudioBaseSinkDiscontReason;
void                (*GstAudioBaseSinkCustomSlavingCallback)
                                                        (GstAudioBaseSink *sink,
                                                         GstClockTime etime,
                                                         GstClockTime itime,
                                                         GstClockTimeDiff *requested_skew,
                                                         GstAudioBaseSinkDiscontReason discont_reason,
                                                         gpointer user_data);
#define             GST_AUDIO_BASE_SINK_CLOCK           (obj)
#define             GST_AUDIO_BASE_SINK_PAD             (obj)
GstAudioRingBuffer * gst_audio_base_sink_create_ringbuffer
                                                        (GstAudioBaseSink *sink);
void                gst_audio_base_sink_set_provide_clock
                                                        (GstAudioBaseSink *sink,
                                                         gboolean provide);
gboolean            gst_audio_base_sink_get_provide_clock
                                                        (GstAudioBaseSink *sink);
void                gst_audio_base_sink_set_slave_method
                                                        (GstAudioBaseSink *sink,
                                                         GstAudioBaseSinkSlaveMethod method);
GstAudioBaseSinkSlaveMethod gst_audio_base_sink_get_slave_method
                                                        (GstAudioBaseSink *sink);
void                gst_audio_base_sink_set_drift_tolerance
                                                        (GstAudioBaseSink *sink,
                                                         gint64 drift_tolerance);
gint64              gst_audio_base_sink_get_drift_tolerance
                                                        (GstAudioBaseSink *sink);
void                gst_audio_base_sink_set_alignment_threshold
                                                        (GstAudioBaseSink *sink,
                                                         GstClockTime alignment_threshold);
GstClockTime        gst_audio_base_sink_get_alignment_threshold
                                                        (GstAudioBaseSink *sink);
void                gst_audio_base_sink_set_discont_wait
                                                        (GstAudioBaseSink *sink,
                                                         GstClockTime discont_wait);
GstClockTime        gst_audio_base_sink_get_discont_wait
                                                        (GstAudioBaseSink *sink);
void                gst_audio_base_sink_set_custom_slaving_callback
                                                        (GstAudioBaseSink *sink,
                                                         GstAudioBaseSinkCustomSlavingCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                gst_audio_base_sink_report_device_failure
                                                        (GstAudioBaseSink *sink);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GstObject
               +----GstElement
                     +----GstBaseSink
                           +----GstAudioBaseSink
                                 +----GstAudioSink

Properties

  "alignment-threshold"      guint64               : Read / Write
  "buffer-time"              gint64                : Read / Write
  "can-activate-pull"        gboolean              : Read / Write
  "discont-wait"             guint64               : Read / Write
  "drift-tolerance"          gint64                : Read / Write
  "latency-time"             gint64                : Read / Write
  "provide-clock"            gboolean              : Read / Write
  "slave-method"             GstAudioBaseSinkSlaveMethod  : Read / Write

Description

This is the base class for audio sinks. Subclasses need to implement the ::create_ringbuffer vmethod. This base class will then take care of writing samples to the ringbuffer, synchronisation, clipping and flushing.

Details

struct GstAudioBaseSink

struct GstAudioBaseSink;

Opaque GstAudioBaseSink.


struct GstAudioBaseSinkClass

struct GstAudioBaseSinkClass {
  GstBaseSinkClass     parent_class;

  /* subclass ringbuffer allocation */
  GstAudioRingBuffer* (*create_ringbuffer)  (GstAudioBaseSink *sink);

  /* subclass payloader */
  GstBuffer*          (*payload)            (GstAudioBaseSink *sink,
                                             GstBuffer        *buffer);
};

GstAudioBaseSink class. Override the vmethod to implement functionality.

GstBaseSinkClass parent_class;

the parent class.

create_ringbuffer ()

create and return a GstAudioRingBuffer to write to.

payload ()

payload data in a format suitable to write to the sink. If no payloading is required, returns a reffed copy of the original buffer, else returns the payloaded buffer with all other metadata copied.

enum GstAudioBaseSinkSlaveMethod

typedef enum {
  GST_AUDIO_BASE_SINK_SLAVE_RESAMPLE,
  GST_AUDIO_BASE_SINK_SLAVE_SKEW,
  GST_AUDIO_BASE_SINK_SLAVE_NONE,
  GST_AUDIO_BASE_SINK_SLAVE_CUSTOM
} GstAudioBaseSinkSlaveMethod;

Different possible clock slaving algorithms used when the internal audio clock is not selected as the pipeline master clock.

GST_AUDIO_BASE_SINK_SLAVE_RESAMPLE

Resample to match the master clock

GST_AUDIO_BASE_SINK_SLAVE_SKEW

Adjust playout pointer when master clock drifts too much.

GST_AUDIO_BASE_SINK_SLAVE_NONE

No adjustment is done.

GST_AUDIO_BASE_SINK_SLAVE_CUSTOM

Use custom clock slaving algorithm (Since: 1.6)

enum GstAudioBaseSinkDiscontReason

typedef enum {
  GST_AUDIO_BASE_SINK_DISCONT_REASON_NO_DISCONT,
  GST_AUDIO_BASE_SINK_DISCONT_REASON_NEW_CAPS,
  GST_AUDIO_BASE_SINK_DISCONT_REASON_FLUSH,
  GST_AUDIO_BASE_SINK_DISCONT_REASON_SYNC_LATENCY,
  GST_AUDIO_BASE_SINK_DISCONT_REASON_ALIGNMENT,
  GST_AUDIO_BASE_SINK_DISCONT_REASON_DEVICE_FAILURE
} GstAudioBaseSinkDiscontReason;

Different possible reasons for discontinuities. This enum is useful for the custom slave method.

GST_AUDIO_BASE_SINK_DISCONT_REASON_NO_DISCONT

No discontinuity occurred

GST_AUDIO_BASE_SINK_DISCONT_REASON_NEW_CAPS

New caps are set, causing renegotiotion

GST_AUDIO_BASE_SINK_DISCONT_REASON_FLUSH

Samples have been flushed

GST_AUDIO_BASE_SINK_DISCONT_REASON_SYNC_LATENCY

Sink was synchronized to the estimated latency (occurs during initialization)

GST_AUDIO_BASE_SINK_DISCONT_REASON_ALIGNMENT

Aligning buffers failed because the timestamps are too discontinuous

GST_AUDIO_BASE_SINK_DISCONT_REASON_DEVICE_FAILURE

Audio output device experienced and recovered from an error but introduced latency in the process (see also gst_audio_base_sink_report_device_failure())

Since 1.6


GstAudioBaseSinkCustomSlavingCallback ()

void                (*GstAudioBaseSinkCustomSlavingCallback)
                                                        (GstAudioBaseSink *sink,
                                                         GstClockTime etime,
                                                         GstClockTime itime,
                                                         GstClockTimeDiff *requested_skew,
                                                         GstAudioBaseSinkDiscontReason discont_reason,
                                                         gpointer user_data);

This function is set with gst_audio_base_sink_set_custom_slaving_callback() and is called during playback. It receives the current time of external and internal clocks, which the callback can then use to apply any custom slaving/synchronization schemes.

The external clock is the sink's element clock, the internal one is the internal audio clock. The internal audio clock's calibration is applied to the timestamps before they are passed to the callback. The difference between etime and itime is the skew; how much internal and external clock lie apart from each other. A skew of 0 means both clocks are perfectly in sync. itime > etime means the external clock is going slower, while itime < etime means it is going faster than the internal clock. etime and itime are always valid timestamps, except for when a discontinuity happens.

requested_skew is an output value the callback can write to. It informs the sink of whether or not it should move the playout pointer, and if so, by how much. This pointer is only NULL if a discontinuity occurs; otherwise, it is safe to write to *requested_skew. The default skew is 0.

The sink may experience discontinuities. If one happens, discont is TRUE, itime, etime are set to GST_CLOCK_TIME_NONE, and requested_skew is NULL. This makes it possible to reset custom clock slaving algorithms when a discontinuity happens.

sink :

a GstAudioBaseSink

etime :

external clock time

itime :

internal clock time

requested_skew :

skew amount requested by the callback

discont_reason :

reason for discontinuity (if any)

user_data :

user data

Since 1.6


GST_AUDIO_BASE_SINK_CLOCK()

#define GST_AUDIO_BASE_SINK_CLOCK(obj)   (GST_AUDIO_BASE_SINK (obj)->clock)

Get the GstClock of obj.

obj :

a GstAudioBaseSink

GST_AUDIO_BASE_SINK_PAD()

#define GST_AUDIO_BASE_SINK_PAD(obj)     (GST_BASE_SINK (obj)->sinkpad)

Get the sink GstPad of obj.

obj :

a GstAudioBaseSink

gst_audio_base_sink_create_ringbuffer ()

GstAudioRingBuffer * gst_audio_base_sink_create_ringbuffer
                                                        (GstAudioBaseSink *sink);

Create and return the GstAudioRingBuffer for sink. This function will call the ::create_ringbuffer vmethod and will set sink as the parent of the returned buffer (see gst_object_set_parent()).

sink :

a GstAudioBaseSink.

Returns :

The new ringbuffer of sink. [transfer none]

gst_audio_base_sink_set_provide_clock ()

void                gst_audio_base_sink_set_provide_clock
                                                        (GstAudioBaseSink *sink,
                                                         gboolean provide);

Controls whether sink will provide a clock or not. If provide is TRUE, gst_element_provide_clock() will return a clock that reflects the datarate of sink. If provide is FALSE, gst_element_provide_clock() will return NULL.

sink :

a GstAudioBaseSink

provide :

new state

gst_audio_base_sink_get_provide_clock ()

gboolean            gst_audio_base_sink_get_provide_clock
                                                        (GstAudioBaseSink *sink);

Queries whether sink will provide a clock or not. See also gst_audio_base_sink_set_provide_clock.

sink :

a GstAudioBaseSink

Returns :

TRUE if sink will provide a clock.

gst_audio_base_sink_set_slave_method ()

void                gst_audio_base_sink_set_slave_method
                                                        (GstAudioBaseSink *sink,
                                                         GstAudioBaseSinkSlaveMethod method);

Controls how clock slaving will be performed in sink.

sink :

a GstAudioBaseSink

method :

the new slave method

gst_audio_base_sink_get_slave_method ()

GstAudioBaseSinkSlaveMethod gst_audio_base_sink_get_slave_method
                                                        (GstAudioBaseSink *sink);

Get the current slave method used by sink.

sink :

a GstAudioBaseSink

Returns :

The current slave method used by sink.

gst_audio_base_sink_set_drift_tolerance ()

void                gst_audio_base_sink_set_drift_tolerance
                                                        (GstAudioBaseSink *sink,
                                                         gint64 drift_tolerance);

Controls the sink's drift tolerance.

sink :

a GstAudioBaseSink

drift_tolerance :

the new drift tolerance in microseconds

gst_audio_base_sink_get_drift_tolerance ()

gint64              gst_audio_base_sink_get_drift_tolerance
                                                        (GstAudioBaseSink *sink);

Get the current drift tolerance, in microseconds, used by sink.

sink :

a GstAudioBaseSink

Returns :

The current drift tolerance used by sink.

gst_audio_base_sink_set_alignment_threshold ()

void                gst_audio_base_sink_set_alignment_threshold
                                                        (GstAudioBaseSink *sink,
                                                         GstClockTime alignment_threshold);

Controls the sink's alignment threshold.

sink :

a GstAudioBaseSink

alignment_threshold :

the new alignment threshold in nanoseconds

gst_audio_base_sink_get_alignment_threshold ()

GstClockTime        gst_audio_base_sink_get_alignment_threshold
                                                        (GstAudioBaseSink *sink);

Get the current alignment threshold, in nanoseconds, used by sink.

sink :

a GstAudioBaseSink

Returns :

The current alignment threshold used by sink.

gst_audio_base_sink_set_discont_wait ()

void                gst_audio_base_sink_set_discont_wait
                                                        (GstAudioBaseSink *sink,
                                                         GstClockTime discont_wait);

Controls how long the sink will wait before creating a discontinuity.

sink :

a GstAudioBaseSink

discont_wait :

the new discont wait in nanoseconds

gst_audio_base_sink_get_discont_wait ()

GstClockTime        gst_audio_base_sink_get_discont_wait
                                                        (GstAudioBaseSink *sink);

Get the current discont wait, in nanoseconds, used by sink.

sink :

a GstAudioBaseSink

Returns :

The current discont wait used by sink.

gst_audio_base_sink_set_custom_slaving_callback ()

void                gst_audio_base_sink_set_custom_slaving_callback
                                                        (GstAudioBaseSink *sink,
                                                         GstAudioBaseSinkCustomSlavingCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Sets the custom slaving callback. This callback will be invoked if the slave-method property is set to GST_AUDIO_BASE_SINK_SLAVE_CUSTOM and the audio sink receives and plays samples.

Setting the callback to NULL causes the sink to behave as if the GST_AUDIO_BASE_SINK_SLAVE_NONE method were used.

sink :

a GstAudioBaseSink

callback :

a GstAudioBaseSinkCustomSlavingCallback

user_data :

user data passed to the callback

notify :

called when user_data becomes unused

Since 1.6


gst_audio_base_sink_report_device_failure ()

void                gst_audio_base_sink_report_device_failure
                                                        (GstAudioBaseSink *sink);

Informs this base class that the audio output device has failed for some reason, causing a discontinuity (for example, because the device recovered from the error, but lost all contents of its ring buffer). This function is typically called by derived classes, and is useful for the custom slave method.

sink :

a GstAudioBaseSink

Since 1.6

Property Details

The "alignment-threshold" property

  "alignment-threshold"      guint64               : Read / Write

Timestamp alignment threshold in nanoseconds.

Allowed values: [1,18446744073709551614]

Default value: 40000000


The "buffer-time" property

  "buffer-time"              gint64                : Read / Write

Size of audio buffer in microseconds, this is the minimum latency that the sink reports.

Allowed values: >= 1

Default value: 200000


The "can-activate-pull" property

  "can-activate-pull"        gboolean              : Read / Write

Allow pull-based scheduling.

Default value: FALSE


The "discont-wait" property

  "discont-wait"             guint64               : Read / Write

A window of time in nanoseconds to wait before creating a discontinuity as a result of breaching the drift-tolerance.

Allowed values: <= 18446744073709551614

Default value: 1000000000


The "drift-tolerance" property

  "drift-tolerance"          gint64                : Read / Write

Controls the amount of time in microseconds that clocks are allowed to drift before resynchronisation happens.

Allowed values: >= 1

Default value: 40000


The "latency-time" property

  "latency-time"             gint64                : Read / Write

The minimum amount of data to write in each iteration in microseconds.

Allowed values: >= 1

Default value: 10000


The "provide-clock" property

  "provide-clock"            gboolean              : Read / Write

Provide a clock to be used as the global pipeline clock.

Default value: TRUE


The "slave-method" property

  "slave-method"             GstAudioBaseSinkSlaveMethod  : Read / Write

Algorithm used to match the rate of the masterclock.

Default value: GST_AUDIO_BASE_SINK_SLAVE_SKEW

See Also

GstAudioSink, GstAudioRingBuffer.