GstBadAudio.NonstreamAudioDecoder¶
- Subclasses:
None
Methods¶
- Inherited:
- Structs:
|
|
|
|
|
|
|
|
|
Virtual Methods¶
- Inherited:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Properties¶
- Inherited:
Name |
Type |
Flags |
Short Description |
|---|---|---|---|
r/w |
Subsong that is currently selected for playback |
||
r/w |
Number of times a playback loop shall be executed (special values: 0 = no looping; -1 = infinite loop) |
Signals¶
- Inherited:
Fields¶
- Inherited:
Name |
Type |
Access |
Description |
|---|---|---|---|
allocation_params |
r |
||
allocator |
r |
||
cur_pos_in_samples |
r |
||
cur_segment |
r |
||
current_subsong |
r |
||
discont |
r |
||
element |
r |
||
input_data_adapter |
r |
||
loaded_mode |
r |
||
mutex |
r |
||
num_decoded_samples |
r |
||
num_loops |
r |
||
output_audio_info |
r |
||
output_format_changed |
r |
||
output_mode |
r |
||
sinkpad |
r |
||
srcpad |
r |
||
subsong_duration |
r |
||
subsong_mode |
r |
||
toc |
r |
||
upstream_size |
r |
Class Details¶
- class GstBadAudio.NonstreamAudioDecoder(**kwargs)¶
- Bases:
- Abstract:
Yes
- Structure:
This base class is for decoders which do not operate on a streaming model. That is: they load the encoded media at once, as part of an initialization, and afterwards can decode samples (sometimes referred to as “rendering the samples”).
This sets it apart from
GstAudio.AudioDecoder, which is a base class for streaming audio decoders.The base class is conceptually a mix between decoder and parser. This is unavoidable, since virtually no format that isn’t streaming based has a clear distinction between parsing and decoding. As a result, this class also handles seeking.
Non-streaming audio formats tend to have some characteristics unknown to more “regular” bitstreams. These include subsongs and looping.
Subsongs are a set of songs-within-a-song. An analogy would be a multitrack recording, where each track is its own song. The first subsong is typically the “main” one. Subsongs were popular for video games to enable context- aware music; for example, subsong
#0would be the “main” song,#1would be an alternate song playing when a fight started,#2would be heard during conversations etc. The base class is designed to always have at least one subsong. If the subclass doesn’t provide any, the base class creates a “pseudo” subsong, which is actually the whole song. Downstream is informed about the subsong using a table of contents (TOC), but only if there are at least 2 subsongs.Looping refers to jumps within the song, typically backwards to the loop start (although bi-directional looping is possible). The loop is defined by a chronological start and end; once the playback position reaches the loop end, it jumps back to the loop start. Depending on the subclass, looping may not be possible at all, or it may only be possible to enable/disable it (that is, either no looping, or an infinite amount of loops), or it may allow for defining a finite number of times the loop is repeated. Looping can affect output in two ways. Either, the playback position is reset to the start of the loop, similar to what happens after a seek event. Or, it is not reset, so the pipeline sees playback steadily moving forwards, the playback position monotonically increasing. However, seeking must always happen within the confines of the defined subsong duration; for example, if a subsong is 2 minutes long, steady playback is at 5 minutes (because infinite looping is enabled), then seeking will still place the position within the 2 minute period. Loop count 0 means no looping. Loop count -1 means infinite looping. Nonzero positive values indicate how often a loop shall occur.
If the initial subsong and loop count are set to values the subclass does not support, the subclass has a chance to correct these values. get_property then reports the corrected versions.
The base class operates as follows:
Unloaded mode
Initial values are set. If a current subsong has already been defined (for example over the command line with gst-launch), then the subsong index is copied over to current_subsong . Same goes for the num-loops and output-mode properties. Media is NOT loaded yet.
Once the sinkpad is activated, the process continues. The sinkpad is activated in push mode, and the class accumulates the incoming media data in an adapter inside the sinkpad’s chain function until either an EOS event is received from upstream, or the number of bytes reported by upstream is reached. Then it loads the media, and starts the decoder output task.
If upstream cannot respond to the size query (in bytes) of load_from_buffer fails, an error is reported, and the pipeline stops.
If there are no errors, load_from_buffer is called to load the media. The subclass must at least call
GstBadAudio.NonstreamAudioDecoder.set_output_format() there, and is free to make use of the initial subsong, output mode, and position. If the actual output mode or position differs from the initial value,it must set the initial value to the actual one (for example, if the actual starting position is always 0, set *initial_position to 0). If loading is unsuccessful, an error is reported, and the pipeline stops. Otherwise, the base class calls get_current_subsong to retrieve the actual current subsong, get_subsong_duration to report the current subsong’s duration in a duration event and message, and get_subsong_tags to send tags downstream in an event (these functions are optional; if set toNone, the associated operation is skipped). Afterwards, the base class switches to loaded mode, and starts the decoder output task.
Loaded mode</title>
Inside the decoder output task, the base class repeatedly calls decode, which returns a buffer with decoded, ready-to-play samples. If the subclass reached the end of playback, decode returns
False, otherwiseTrue.Upon reaching a loop end, subclass either ignores that, or loops back to the beginning of the loop. In the latter case, if the output mode is set to LOOPING, the subclass must call
GstBadAudio.NonstreamAudioDecoder.handle_loop() *after* the playback position moved to the start of the loop. In STEADY mode, the subclass must *not* call this function. Since many decoders only provide a callback for when the looping occurs, and that looping occurs inside the decoding operation itself, the following mechanism for subclass is suggested: set a flag inside such a callback. Then, in the next decode call, before doing the decoding, check this flag. If it is set,GstBadAudio.NonstreamAudioDecoder.handle_loop() is called, and the flag is cleared. (This function call is necessary in LOOPING mode because it updates the current segment and makes sure the next buffer that is sent downstream has its DISCONT flag set.)When the current subsong is switched, set_current_subsong is called. If it fails, a warning is reported, and nothing else is done. Otherwise, it calls get_subsong_duration to get the new current subsongs’s duration, get_subsong_tags to get its tags, reports a new duration (i.e. it sends a duration event downstream and generates a duration message), updates the current segment, and sends the subsong’s tags in an event downstream. (If set_current_subsong has been set to
Noneby the subclass, attempts to set a current subsong are ignored; likewise, if get_subsong_duration isNone, no duration is reported, and if get_subsong_tags isNone, no tags are sent downstream.)When an attempt is made to switch the output mode, it is checked against the bitmask returned by get_supported_output_modes. If the proposed new output mode is supported, the current segment is updated (it is open-ended in STEADY mode, and covers the (sub)song length in LOOPING mode), and the subclass’ set_output_mode function is called unless it is set to
None. Subclasses should reset internal loop counters in this function.
The relationship between (sub)song duration, output mode, and number of loops is defined this way (this is all done by the base class automatically):
Segments have their duration and stop values set to
Gst.CLOCK_TIME_NONEin STEADY mode, and to the duration of the (sub)song in LOOPING mode.The duration that is returned to a DURATION query is always the duration of the (sub)song, regardless of number of loops or output mode. The same goes for DURATION messages and tags.
If the number of loops is >0 or -1, durations of TOC entries are set to the duration of the respective subsong in LOOPING mode and to
GObject.G_MAXINT64in STEADY mode. If the number of loops is 0, entry durations are set to the subsong duration regardless of the output mode.
- allocate_output_buffer(size)¶
- Parameters:
size (
int) – Size of the output buffer, in bytes- Returns:
Newly allocated output buffer, or
Noneif allocation failed- Return type:
Gst.BufferorNone
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.
- get_downstream_info(format, sample_rate, num_channels)¶
- Parameters:
format (
GstAudio.AudioFormat) –GstAudio.AudioFormatvalue to fill with a sample formatsample_rate (
int) – Integer to fill with a sample ratenum_channels (
int) – Integer to fill with a channel count
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
None; 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.
- handle_loop(new_position)¶
- Parameters:
new_position (
int) –
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
GstBadAudio.NonstreamAudioOutputMode.LOOPINGoutput mode, since in theGstBadAudio.NonstreamAudioOutputMode.STEADYoutput mode, this function does nothing. SeeGstBadAudio.NonstreamAudioOutputModefor 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).
- set_output_format(audio_info)¶
- Parameters:
audio_info (
GstAudio.AudioInfo) – Valid audio info structure containing the output format- Returns:
Trueif setting the output format succeeded,Falseotherwise- Return type:
Sets the output caps by means of a
GstAudio.AudioInfostructure.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).
- set_output_format_simple(sample_rate, sample_format, num_channels)¶
- Parameters:
sample_rate (
int) – Output sample rate to use, in Hzsample_format (
GstAudio.AudioFormat) – Output sample format to usenum_channels (
int) – Number of output channels to use
- Returns:
Trueif setting the output format succeeded,Falseotherwise- Return type:
Convenience function; sets the output caps by means of common parameters.
Internally, this fills a
GstAudio.AudioInfostructure and callsGstBadAudio.NonstreamAudioDecoder.set_output_format().
- do_decode(buffer, num_samples) virtual¶
- Parameters:
buffer (
Gst.Buffer) –num_samples (
int) –
- Return type:
- do_get_main_tags() virtual¶
- Return type:
- do_load_from_buffer(source_data, initial_subsong, initial_subsong_mode, initial_position, initial_output_mode, initial_num_loops) virtual¶
- Parameters:
source_data (
Gst.Buffer) –initial_subsong (
int) –initial_subsong_mode (
GstBadAudio.NonstreamAudioSubsongMode) –initial_position (
int) –initial_output_mode (
GstBadAudio.NonstreamAudioOutputMode) –initial_num_loops (
int) –
- Return type:
- do_load_from_custom(initial_subsong, initial_subsong_mode, initial_position, initial_output_mode, initial_num_loops) virtual¶
- Parameters:
initial_subsong (
int) –initial_subsong_mode (
GstBadAudio.NonstreamAudioSubsongMode) –initial_position (
int) –initial_output_mode (
GstBadAudio.NonstreamAudioOutputMode) –initial_num_loops (
int) –
- Return type:
- do_set_current_subsong(subsong, initial_position) virtual¶
- do_set_output_mode(mode, current_position) virtual¶
- Parameters:
mode (
GstBadAudio.NonstreamAudioOutputMode) –current_position (
int) –
- Return type:
Property Details¶
- GstBadAudio.NonstreamAudioDecoder.props.current_subsong¶
-
Subsong that is currently selected for playback