gstnonstreamaudiodecoder

GstNonstreamAudioDecoder

GObject
    ╰──GInitiallyUnowned
        ╰──GstObject
            ╰──GstElement
                ╰──GstNonstreamAudioDecoder

Class structure

gst_nonstream_audio_decoder_allocate_output_buffer

GstBuffer *
gst_nonstream_audio_decoder_allocate_output_buffer (GstNonstreamAudioDecoder * dec,
                                                    gsize size)

Allocates an output buffer with the internally configured buffer pool.

This function may only be called from within load_from_buffer, load_from_custom, and decode.

gst_nonstream_audio_decoder_get_downstream_info

gst_nonstream_audio_decoder_get_downstream_info (GstNonstreamAudioDecoder * dec,
                                                 GstAudioFormat * format,
                                                 gint * sample_rate,
                                                 gint * num_channels)

Gets sample format, sample rate, channel count from the allowed srcpad caps.

This is useful for when the subclass wishes to adjust one or more output parameters to whatever downstream is supporting. For example, the output sample rate is often a freely adjustable value in module players.

This function tries to find a value inside the srcpad peer's caps for format, sample_rate, num_chnanels . Any of these can be NULL; they (and the corresponding downstream caps) are then skipped while retrieving information. Non-fixated caps are fixated first; the value closest to their present value is then chosen. For example, if the variables pointed to by the arguments are GST_AUDIO_FORMAT_16, 48000 Hz, and 2 channels, and the downstream caps are:

"audio/x-raw, format={S16LE,S32LE}, rate=[1,32000], channels=[1,MAX]"

Then format and channels stay the same, while sample_rate is set to 32000 Hz. This way, the initial values the the variables pointed to by the arguments are set to can be used as default output values. Note that if no downstream caps can be retrieved, then this function does nothing, therefore it is necessary to ensure that format, sample_rate, and channels have valid initial values.

Decoder lock is not held by this function, so it can be called from within any of the class vfuncs.

gst_nonstream_audio_decoder_handle_loop

gst_nonstream_audio_decoder_handle_loop (GstNonstreamAudioDecoder * dec,
                                         GstClockTime new_position)

Reports that a loop has been completed and creates a new appropriate segment for the next loop.

new_position exists because a loop may not start at the beginning.

This function is only useful for subclasses which can be in the GST_NONSTREAM_AUDIO_OUTPUT_MODE_LOOPING output mode, since in the GST_NONSTREAM_AUDIO_OUTPUT_MODE_STEADY output mode, this function does nothing. See GstNonstreamAudioOutputMode for more details.

The subclass calls this during playback when it loops. It produces a new segment with updated base time and internal time values, to allow for seamless looping. It does not check the number of elapsed loops; this is up the subclass.

Note that if this function is called, then it must be done after the last samples of the loop have been decoded and pushed downstream.

This function must be called with the decoder mutex lock held, since it is typically called from within decode (which in turn are called with the lock already held).

gst_nonstream_audio_decoder_set_output_format

gboolean
gst_nonstream_audio_decoder_set_output_format (GstNonstreamAudioDecoder * dec,
                                               const GstAudioInfo * audio_info)

Sets the output caps by means of a GstAudioInfo structure.

This must be called latest in the first decode call, to ensure src caps are set before decoded samples are sent downstream. Typically, this is called from inside load_from_buffer or load_from_custom.

This function must be called with the decoder mutex lock held, since it is typically called from within the aforementioned vfuncs (which in turn are called with the lock already held).

gst_nonstream_audio_decoder_set_output_format_simple

gboolean
gst_nonstream_audio_decoder_set_output_format_simple (GstNonstreamAudioDecoder * dec,
                                                      guint sample_rate,
                                                      GstAudioFormat sample_format,
                                                      guint num_channels)

Convenience function; sets the output caps by means of common parameters.

Internally, this fills a GstAudioInfo structure and calls gst_nonstream_audio_decoder_set_output_format.

current-subsong

“current-subsong” guint

Flags : Read / Write

num-loops

“num-loops” gint

Flags : Read / Write

output-mode

“output-mode” object*

Flags : Read / Write

subsong-mode

“subsong-mode” object*

Flags : Read / Write

decide_allocation

gboolean
decide_allocation (GstNonstreamAudioDecoder * dec,
                   GstQuery * query)

Optional. Sets up the allocation parameters for allocating output buffers. The passed in query contains the result of the downstream allocation query. Subclasses should chain up to the parent implementation to invoke the default handler.

decode

gboolean
decode (GstNonstreamAudioDecoder * dec,
        GstBuffer ** buffer,
        guint * num_samples)

Always required. Allocates an output buffer, fills it with decoded audio samples, and must be passed on to *buffer . The number of decoded samples must be passed on to *num_samples. If decoding finishes or the decoding is no longer possible (for example, due to an unrecoverable error), this function returns FALSE, otherwise TRUE.

get_current_subsong

guint
get_current_subsong (GstNonstreamAudioDecoder * dec)

Optional. Returns the current subsong. If the current subsong mode is not GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE, this function's return value is undefined. If this function is implemented by the subclass, get_num_subsongs should be implemented as well.

get_main_tags

GstTagList *
get_main_tags (GstNonstreamAudioDecoder * dec)

Optional. Returns a tag list containing the main song tags, or NULL if there are no such tags. Returned tags will be unref'd. Use this vfunc instead of manually pushing a tag event downstream to avoid edge cases where not yet pushed sticky tag events get overwritten before they are pushed (can for example happen with decodebin if tags are pushed downstream before the decodebin pads are linked).

get_num_loops

gint
get_num_loops (GstNonstreamAudioDecoder * dec)

Optional. Returns the number of loops for playback.

get_num_subsongs

guint
get_num_subsongs (GstNonstreamAudioDecoder * dec)

Optional. Returns the number of subsongs available. The return values 0 and 1 have a similar, but distinct, meaning. If this function returns 0, then this decoder does not support subsongs at all. get_current_subsong must then also always return 0. In other words, this function either never returns 0, or never returns anything else than 0. A return value of 1 means that the media contains either only one or no subsongs (the entire song is then considered to be one single subsong). 1 also means that only this very media has no or just one subsong, and the decoder itself can support multiple subsongs.

get_subsong_duration

GstClockTime
get_subsong_duration (GstNonstreamAudioDecoder * dec,
                      guint subsong)

Optional. Returns the duration of a subsong. Returns GST_CLOCK_TIME_NONE if duration is unknown.

get_subsong_tags

GstTagList *
get_subsong_tags (GstNonstreamAudioDecoder * dec,
                  guint subsong)

Optional. Returns tags for a subsong, or NULL if there are no tags. Returned tags will be unref'd.

get_supported_output_modes

guint
get_supported_output_modes (GstNonstreamAudioDecoder * dec)

Always required. Returns a bitmask containing the output modes the subclass supports. The mask is formed by a bitwise OR combination of integers, which can be calculated this way: 1 << GST_NONSTREAM_AUDIO_OUTPUT_MODE_ , where mode is either STEADY or LOOPING

load_from_buffer

gboolean
load_from_buffer (GstNonstreamAudioDecoder * dec,
                  GstBuffer * source_data,
                  guint initial_subsong,
                  GstNonstreamAudioSubsongMode initial_subsong_mode,
                  GstClockTime * initial_position,
                  GstNonstreamAudioOutputMode * initial_output_mode,
                  gint * initial_num_loops)

Required if loads_from_sinkpad is set to TRUE (the default value). Loads the media from the given buffer. The entire media is supplied at once, so after this call, loading should be finished. This function can also make use of a suggested initial subsong & subsong mode and initial playback position (but isn't required to). In case it chooses a different starting position, the function must pass this position to *initial_position. The subclass does not have to unref the input buffer; the base class does that already.

load_from_custom

gboolean
load_from_custom (GstNonstreamAudioDecoder * dec,
                  guint initial_subsong,
                  GstNonstreamAudioSubsongMode initial_subsong_mode,
                  GstClockTime * initial_position,
                  GstNonstreamAudioOutputMode * initial_output_mode,
                  gint * initial_num_loops)

Required if loads_from_sinkpad is set to FALSE. Loads the media in a way defined by the custom sink. Data is not supplied; the derived class has to handle this on its own. Otherwise, this function is identical to load_from_buffer.

negotiate

gboolean
negotiate (GstNonstreamAudioDecoder * dec)

propose_allocation

gboolean
propose_allocation (GstNonstreamAudioDecoder * dec,
                    GstQuery * query)

Optional. Proposes buffer allocation parameters for upstream elements. Subclasses should chain up to the parent implementation to invoke the default handler.

seek

gboolean
seek (GstNonstreamAudioDecoder * dec,
      GstClockTime * new_position)

Optional. Called when a seek event is received by the parent class. new_position is a pointer to a GstClockTime integer which contains a position relative to the current subsong. Minimum is 0, maximum is the subsong length. After this function finishes, new_position is set to the actual new position (which may differ from the request position, depending on the decoder).

set_current_subsong

gboolean
set_current_subsong (GstNonstreamAudioDecoder * dec,
                     guint subsong,
                     GstClockTime * initial_position)

Optional. Sets the current subsong. This function is allowed to switch to a different subsong than the required one, and can optionally make use of the suggested initial position. In case it chooses a different starting position, the function must pass this position to *initial_position. This function switches the subsong mode to GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE automatically. If this function is implemented by the subclass, get_current_subsong and get_num_subsongs should be implemented as well.

set_num_loops

gboolean
set_num_loops (GstNonstreamAudioDecoder * dec,
               gint num_loops)

Optional. Sets the number of loops for playback. If this is called during playback, the subclass must set any internal loop counters to zero. A loop value of -1 means infinite looping; 0 means no looping; and when the num_loops is greater than 0, playback should loop exactly num_loops times. If this function is implemented, get_num_loops should be implemented as well. The function can ignore the given values and choose another; however, get_num_loops should return this other value afterwards. It is up to the subclass to define where the loop starts and ends. It can mean that only a subset at the end or in the middle of a song is repeated, for example. If the current subsong mode is GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE, then the subsong is repeated this many times. If it is GST_NONSTREAM_AUDIO_SUBSONG_MODE_ALL, then all subsongs are repeated this many times. With GST_NONSTREAM_AUDIO_SUBSONG_MODE_DECODER_DEFAULT, the behavior is decoder specific.

set_output_mode

gboolean
set_output_mode (GstNonstreamAudioDecoder * dec,
                 GstNonstreamAudioOutputMode mode,
                 GstClockTime * current_position)

Optional. Sets the output mode the subclass has to use. Unlike with most other functions, the subclass cannot choose a different mode; it must use the requested one. If the output mode is set to LOOPING, gst_nonstream_audio_decoder_handle_loop must be called after playback moved back to the start of a loop.

set_subsong_mode

gboolean
set_subsong_mode (GstNonstreamAudioDecoder * dec,
                  GstNonstreamAudioSubsongMode mode,
                  GstClockTime * initial_position)

Optional. Sets the current subsong mode. Since this might influence the current playback position, this function must set the initial_position integer argument to a defined value. If the playback position is not affected at all, it must be set to GST_CLOCK_TIME_NONE. If the subsong is restarted after the mode switch, it is recommended to set the value to the position in the playback right after the switch (or 0 if the subsongs are always reset back to the beginning).

tell

GstClockTime
tell (GstNonstreamAudioDecoder * dec)

Optional. Called when a position query is received by the parent class. The position that this function returns must be relative to the current subsong. Thus, the minimum is 0, and the maximum is the subsong length.

GST_NONSTREAM_AUDIO_DECODER_CAST

#define GST_NONSTREAM_AUDIO_DECODER_CAST(obj)        ((GstNonstreamAudioDecoder *)(obj))

GST_NONSTREAM_AUDIO_DECODER_LOCK_MUTEX

#define GST_NONSTREAM_AUDIO_DECODER_LOCK_MUTEX(obj)      g_mutex_lock(&(((GstNonstreamAudioDecoder *)(obj))->mutex))

Locks the decoder mutex.

Internally, the mutex is locked before one of the class vfuncs are called, when position and duration queries are handled, and when properties are set/retrieved.

Derived classes should call lock during decoder related modifications (for example, setting/clearing filter banks), when at the same time audio might get decoded. An example are configuration changes that happen when properties are set. Properties might be set from another thread, so while the derived decoder is reconfigured, the mutex should be locked.

GST_NONSTREAM_AUDIO_DECODER_SINK_PAD

#define GST_NONSTREAM_AUDIO_DECODER_SINK_PAD(obj)        (((GstNonstreamAudioDecoder *) (obj))->sinkpad)

Gives the pointer to the sink GstPad object of the element.

GST_NONSTREAM_AUDIO_DECODER_SRC_PAD

#define GST_NONSTREAM_AUDIO_DECODER_SRC_PAD(obj)         (((GstNonstreamAudioDecoder *) (obj))->srcpad)

Gives the pointer to the source GstPad object of the element.

GST_NONSTREAM_AUDIO_DECODER_UNLOCK_MUTEX

#define GST_NONSTREAM_AUDIO_DECODER_UNLOCK_MUTEX(obj)    g_mutex_unlock(&(((GstNonstreamAudioDecoder *)(obj))->mutex))

GstNonstreamAudioOutputMode

The output mode defines how the output behaves with regards to looping. Either the playback position is moved back to the beginning of the loop, acting like a backwards seek, or it increases steadily, as if loop were "unrolled".

GstNonstreamAudioSubsongMode

The subsong mode defines how the decoder shall handle subsongs.

GST_NONSTREAM_AUDIO_DECODER_SINK_NAME

#define GST_NONSTREAM_AUDIO_DECODER_SINK_NAME    "sink"

The name of the template for the sink pad.

GST_NONSTREAM_AUDIO_DECODER_SRC_NAME

#define GST_NONSTREAM_AUDIO_DECODER_SRC_NAME     "src"

The name of the template for the source pad.