GstBadAudio.NonstreamAudioDecoderClass

Fields

Name	Type	Access	Description
decide_allocation	object	r	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	object	r	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.
element_class	Gst.ElementClass	r	The parent class structure
get_current_subsong	object	r	Optional. Returns the current subsong. If the current subsong mode is not GstBadAudio.NonstreamAudioSubsongMode.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	object	r	Optional. Returns a tag list containing the main song tags, or None 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	object	r	Optional. Returns the number of loops for playback.
get_num_subsongs	object	r	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	object	r	Optional. Returns the duration of a subsong. Returns Gst.CLOCK_TIME_NONE if duration is unknown.
get_subsong_tags	object	r	Optional. Returns tags for a subsong, or None if there are no tags. Returned tags will be unref’d.
get_supported_output_modes	object	r	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_<mode> , where mode is either STEADY or LOOPING
load_from_buffer	object	r	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	object	r	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.
loads_from_sinkpad	bool	r
negotiate	object	r
propose_allocation	object	r	Optional. Proposes buffer allocation parameters for upstream elements. Subclasses should chain up to the parent implementation to invoke the default handler.
seek	object	r	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	object	r	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 GstBadAudio.NonstreamAudioSubsongMode.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	object	r	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 GstBadAudio.NonstreamAudioSubsongMode.SINGLE, then the subsong is repeated this many times. If it is GstBadAudio.NonstreamAudioSubsongMode.ALL, then all subsongs are repeated this many times. With GstBadAudio.NonstreamAudioSubsongMode.DECODER_DEFAULT, the behavior is decoder specific.
set_output_mode	object	r	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	object	r	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	object	r	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.

Methods

None

Details

class GstBadAudio.NonstreamAudioDecoderClass

Subclasses can override any of the available optional virtual methods or not, as needed. At minimum, load_from_buffer (or load_from_custom), get_supported_output_modes, and decode need to be overridden.

All functions are called with a locked decoder mutex.

If GST_ELEMENT_ERROR, GST_ELEMENT_WARNING, or GST_ELEMENT_INFO are called from inside one of these functions, it is strongly recommended to unlock the decoder mutex before and re-lock it after these macros to prevent potential deadlocks in case the application does something with the element when it receives an ERROR/WARNING/INFO message. Same goes for Gst.Element.post_message() calls and non-serialized events.

By default, this class works by reading media data from the sinkpad, and then commencing playback. Some decoders cannot be given data from a memory block, so the usual way of reading all upstream data and passing it to load_from_buffer doesn’t work then. In this case, set the value of loads_from_sinkpad to False. This changes the way this class operates; it does not require a sinkpad to exist anymore, and will call load_from_custom instead. One example of a decoder where this makes sense is UADE (Unix Amiga Delitracker Emulator). For some formats (such as TFMX), it needs to do the file loading by itself. Since most decoders can read input data from a memory block, the default value of loads_from_sinkpad is True.