GstAudio.AudioDecoder¶

Subclasses:: None

Methods¶

Inherited:: Gst.Element (82), Gst.Object (27), GObject.Object (37)
Structs:: Gst.ElementClass (10), GObject.ObjectClass (5)

	`allocate_output_buffer` (size)
	`finish_frame` (buf, frames)
	`finish_subframe` (buf)
	`get_allocator` ()
	`get_audio_info` ()
	`get_delay` ()
	`get_drainable` ()
	`get_estimate_rate` ()
	`get_latency` ()
	`get_max_errors` ()
	`get_min_latency` ()
	`get_needs_format` ()
	`get_parse_state` ()
	`get_plc` ()
	`get_plc_aware` ()
	`get_tolerance` ()
	`merge_tags` (tags, mode)
	`negotiate` ()
	`proxy_getcaps` (caps, filter)
	`set_allocation_caps` (allocation_caps)
	`set_drainable` (enabled)
	`set_estimate_rate` (enabled)
	`set_latency` (min, max)
	`set_max_errors` (num)
	`set_min_latency` (num)
	`set_needs_format` (enabled)
	`set_output_caps` (caps)
	`set_output_format` (info)
	`set_plc` (enabled)
	`set_plc_aware` (plc)
	`set_tolerance` (tolerance)
	`set_use_default_pad_acceptcaps` (use)

Virtual Methods¶

Inherited:: Gst.Element (16), Gst.Object (1), GObject.Object (7)

	`do_close` ()
	`do_decide_allocation` (query)
	`do_flush` (hard)
	`do_getcaps` (filter)
	`do_handle_frame` (buffer)
	`do_negotiate` ()
	`do_open` ()
	`do_parse` (adapter)
	`do_pre_push` (buffer)
	`do_propose_allocation` (query)
	`do_set_format` (caps)
	`do_sink_event` (event)
	`do_sink_query` (query)
	`do_src_event` (event)
	`do_src_query` (query)
	`do_start` ()
	`do_stop` ()
	`do_transform_meta` (outbuf, meta, inbuf)

Properties¶

Inherited:: Gst.Object (2)

Name	Type	Flags	Short Description
`max-errors`	`int`	r/w	Max consecutive decoder errors before returning flow error
`min-latency`	`int`	r/w	Aggregate output data to a minimum of latency time (ns)
`plc`	`bool`	r/w	Perform packet loss concealment (if supported)
`tolerance`	`int`	r/w	Perfect ts while timestamp jitter/imperfection within tolerance (ns)

Signals¶

Inherited:: Gst.Element (3), Gst.Object (1), GObject.Object (1)

Fields¶

Inherited:: Gst.Element (3), Gst.Object (1), GObject.Object (1)

Name	Type	Access
element	`Gst.Element`	r
input_segment	`Gst.Segment`	r
output_segment	`Gst.Segment`	r
sinkpad	`Gst.Pad`	r
srcpad	`Gst.Pad`	r
stream_lock	`GLib.RecMutex`	r

Class Details¶

class GstAudio.AudioDecoder(**kwargs)¶

Bases:: Gst.Element
Abstract:: Yes
Structure:: GstAudio.AudioDecoderClass

This base class is for audio decoders turning encoded data into raw audio samples.

GstAudio.AudioDecoder and subclass should cooperate as follows.

Configuration

Initially, GstAudio.AudioDecoder calls start when the decoder element is activated, which allows subclass to perform any global setup. Base class (context) parameters can already be set according to subclass capabilities (or possibly upon receive more information in subsequent set_format).
GstAudio.AudioDecoder calls set_format to inform subclass of the format of input audio data that it is about to receive. While unlikely, it might be called more than once, if changing input parameters require reconfiguration.
GstAudio.AudioDecoder calls stop at end of all processing.

As of configuration stage, and throughout processing, GstAudio.AudioDecoder provides various (context) parameters, e.g. describing the format of output audio data (valid when output caps have been set) or current parsing state. Conversely, subclass can and should configure context to inform base class of its expectation w.r.t. buffer handling.

Data processing

Base class gathers input data, and optionally allows subclass to parse this into subsequently manageable (as defined by subclass) chunks. Such chunks are subsequently referred to as ‘frames’, though they may or may not correspond to 1 (or more) audio format frame.
- Input frame is provided to subclass’ handle_frame.
- If codec processing results in decoded data, subclass should call gst_audio_decoder_finish_frame to have decoded data pushed downstream.
- Just prior to actually pushing a buffer downstream, it is passed to pre_push. Subclass should either use this callback to arrange for additional downstream pushing or otherwise ensure such custom pushing occurs after at least a method call has finished since setting src pad caps.
- During the parsing process GstAudio.AudioDecoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if event callback has been provided.

Shutdown phase

GstAudio.AudioDecoder class calls stop to inform the subclass that data parsing will be stopped.

Subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named “sink” and “src”. It also needs to set the fixed caps on srcpad, when the format is ensured. This is typically when base class calls subclass’ set_format function, though it might be delayed until calling gst_audio_decoder_finish_frame.

In summary, above process should have subclass concentrating on codec data processing while leaving other matters to base class, such as most notably timestamp handling. While it may exert more control in this area (see e.g. pre_push), it is very much not recommended.

In particular, base class will try to arrange for perfect output timestamps as much as possible while tracking upstream timestamps. To this end, if deviation between the next ideal expected perfect timestamp and upstream exceeds GstAudio.AudioDecoder :tolerance, then resync to upstream occurs (which would happen always if the tolerance mechanism is disabled).

In non-live pipelines, baseclass can also (configurably) arrange for output buffer aggregation which may help to redue large(r) numbers of small(er) buffers being pushed and processed downstream. Note that this feature is only available if the buffer layout is interleaved. For planar buffers, the decoder implementation is fully responsible for the output buffer size.

On the other hand, it should be noted that baseclass only provides limited seeking support (upon explicit subclass request), as full-fledged support should rather be left to upstream demuxer, parser or alike. This simple approach caters for seeking and duration reporting using estimated input bitrates.

Things that subclass need to take care of:

Provide pad templates
Set source pad caps when appropriate
Set user-configurable properties to sane defaults for format and implementing codec at hand, and convey some subclass capabilities and expectations in context.
Accept data in handle_frame and provide encoded results to gst_audio_decoder_finish_frame. If it is prepared to perform PLC, it should also accept None data in handle_frame and provide for data for indicated duration.

allocate_output_buffer(size)[source]¶

Parameters:: size (int) – size of the buffer
Returns:: allocated buffer
Return type:: Gst.Buffer

Helper function that allocates a buffer to hold an audio frame for self's current output format.

finish_frame(buf, frames)[source]¶

Parameters:

buf (Gst.Buffer or None) – decoded data
frames (int) – number of decoded frames represented by decoded data

Returns:

a Gst.FlowReturn that should be escalated to caller (of caller)

Return type:

Gst.FlowReturn

Collects decoded data and pushes it downstream.

buf may be None in which case the indicated number of frames are discarded and considered to have produced no output (e.g. lead-in or setup frames). Otherwise, source pad caps must be set when it is called with valid data in buf.

Note that a frame received in GstAudio.AudioDecoder.do_handle_frame() may be invalidated by a call to this function.

finish_subframe(buf)[source]¶

Parameters:: buf (Gst.Buffer or None) – decoded data
Returns:: a Gst.FlowReturn that should be escalated to caller (of caller)
Return type:: Gst.FlowReturn

Collects decoded data and pushes it downstream. This function may be called multiple times for a given input frame.

buf may be None in which case it is assumed that the current input frame is finished. This is equivalent to calling GstAudio.AudioDecoder.finish_subframe() with a None buffer and frames=1 after having pushed out all decoded audio subframes using this function.

When called with valid data in buf the source pad caps must have been set already.

Note that a frame received in GstAudio.AudioDecoder.do_handle_frame() may be invalidated by a call to this function.

New in version 1.16.

get_allocator()[source]¶

Returns:

allocator:: the Gst.Allocator used
params:: the Gst.AllocationParams of allocator

Return type:

(allocator: Gst.Allocator or None, params: Gst.AllocationParams)

Lets GstAudio.AudioDecoder sub-classes to know the memory allocator used by the base class and its params.

Unref the allocator after use it.

get_audio_info()[source]¶

Returns:: a GstAudio.AudioInfo describing the input audio format
Return type:: GstAudio.AudioInfo

get_delay()[source]¶

Returns:: currently configured decoder delay
Return type:: int

get_drainable()[source]¶

Returns:

True if drainable handling is enabled.

MT safe.

Return type:

bool

Queries decoder drain handling.

get_estimate_rate()[source]¶

Returns:: currently configured byte to time conversion setting
Return type:: int

get_latency()[source]¶

Returns:

min:: a pointer to storage to hold minimum latency
max:: a pointer to storage to hold maximum latency

Return type:

(min: int, max: int)

Sets the variables pointed to by min and max to the currently configured latency.

get_max_errors()[source]¶

Returns:: currently configured decoder tolerated error count.
Return type:: int

get_min_latency()[source]¶

Returns:

aggregation latency.

MT safe.

Return type:

int

Queries decoder’s latency aggregation.

get_needs_format()[source]¶

Returns:

True if required format handling is enabled.

MT safe.

Return type:

bool

Queries decoder required format handling.

get_parse_state()[source]¶

Returns:

sync:: a pointer to a variable to hold the current sync state
eos:: a pointer to a variable to hold the current eos state

Return type:

(sync: bool, eos: bool)

Return current parsing (sync and eos) state.

get_plc()[source]¶

Returns:

True if packet loss concealment is enabled.

MT safe.

Return type:

bool

Queries decoder packet loss concealment handling.

get_plc_aware()[source]¶

Returns:: currently configured plc handling
Return type:: int

get_tolerance()[source]¶

Returns:

decoder audio jitter tolerance threshold.

MT safe.

Return type:

int

Queries current audio jitter tolerance threshold.

merge_tags(tags, mode)[source]¶

Parameters:

tags (Gst.TagList or None) – a Gst.TagList to merge, or None
mode (Gst.TagMergeMode) – the Gst.TagMergeMode to use, usually Gst.TagMergeMode.REPLACE

Sets the audio decoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with GstAudio.AudioDecoder.merge_tags().

Note that this is provided for convenience, and the subclass is not required to use this and can still do tag handling on its own.

negotiate()[source]¶

Returns:: True if the negotiation succeeded, else False.
Return type:: bool

Negotiate with downstream elements to currently configured GstAudio.AudioInfo. Unmark Gst.PadFlags.NEED_RECONFIGURE in any case. But mark it again if negotiate fails.

proxy_getcaps(caps, filter)[source]¶

Parameters:

caps (Gst.Caps or None) – initial caps
filter (Gst.Caps or None) – filter caps

Returns:

a Gst.Caps owned by caller

Return type:

Gst.Caps

Returns caps that express caps (or sink template caps if caps == None) restricted to rate/channels/… combinations supported by downstream elements.

New in version 1.6.

set_allocation_caps(allocation_caps)[source]¶

Parameters:: allocation_caps (Gst.Caps or None) – a Gst.Caps or None

Sets a caps in allocation query which are different from the set pad’s caps. Use this function before calling GstAudio.AudioDecoder.negotiate(). Setting to None the allocation query will use the caps from the pad.

New in version 1.10.

set_drainable(enabled)[source]¶

Parameters:: enabled (bool) – new state

Configures decoder drain handling. If drainable, subclass might be handed a None buffer to have it return any leftover decoded data. Otherwise, it is not considered so capable and will only ever be passed real data.

MT safe.

set_estimate_rate(enabled)[source]¶

Parameters:: enabled (bool) – whether to enable byte to time conversion

Allows baseclass to perform byte to time estimated conversion.

set_latency(min, max)[source]¶

Parameters:

min (int) – minimum latency
max (int) – maximum latency

Sets decoder latency. If the provided values changed from previously provided ones, this will also post a LATENCY message on the bus so the pipeline can reconfigure its global latency.

set_max_errors(num)[source]¶

Parameters:: num (int) – max tolerated errors

Sets numbers of tolerated decoder errors, where a tolerated one is then only warned about, but more than tolerated will lead to fatal error. You can set -1 for never returning fatal errors. Default is set to GstAudio.AUDIO_DECODER_MAX_ERRORS.

set_min_latency(num)[source]¶

Parameters:: num (int) – new minimum latency

Sets decoder minimum aggregation latency.

MT safe.

set_needs_format(enabled)[source]¶

Parameters:: enabled (bool) – new state

Configures decoder format needs. If enabled, subclass needs to be negotiated with format caps before it can process any data. It will then never be handed any data before it has been configured. Otherwise, it might be handed data without having been configured and is then expected being able to do so either by default or based on the input data.

MT safe.

set_output_caps(caps)[source]¶

Parameters:: caps (Gst.Caps) – (fixed) Gst.Caps
Returns:: True on success.
Return type:: bool

Configure output caps on the srcpad of self. Similar to GstAudio.AudioDecoder.set_output_format(), but allows subclasses to specify output caps that can’t be expressed via GstAudio.AudioInfo e.g. caps that have caps features.

New in version 1.16.

set_output_format(info)[source]¶

Parameters:: info (GstAudio.AudioInfo) – GstAudio.AudioInfo
Returns:: True on success.
Return type:: bool

Configure output info on the srcpad of self.

set_plc(enabled)[source]¶

Parameters:: enabled (bool) – new state

Enable or disable decoder packet loss concealment, provided subclass and codec are capable and allow handling plc.

MT safe.

set_plc_aware(plc)[source]¶

Parameters:: plc (bool) – new plc state

Indicates whether or not subclass handles packet loss concealment (plc).

set_tolerance(tolerance)[source]¶

Parameters:: tolerance (int) – new tolerance

Configures decoder audio jitter tolerance threshold.

MT safe.

set_use_default_pad_acceptcaps(use)[source]¶

Parameters:: use (bool) – if the default pad accept-caps query handling should be used

Lets GstAudio.AudioDecoder sub-classes decide if they want the sink pad to use the default pad query handler to reply to accept-caps queries.

By setting this to true it is possible to further customize the default handler with %GST_PAD_SET_ACCEPT_INTERSECT and %GST_PAD_SET_ACCEPT_TEMPLATE

New in version 1.6.

do_close() virtual¶

Return type:: bool

Optional. Called when the element changes to Gst.State.NULL. Allows closing external resources.

do_decide_allocation(query) virtual¶

Parameters:: query (Gst.Query) –
Return type:: bool

Optional. Setup 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.

do_flush(hard) virtual¶

Parameters:: hard (bool) –

Optional. Instructs subclass to clear any codec caches and discard any pending samples and not yet returned decoded data. hard indicates whether a FLUSH is being processed, or otherwise a DISCONT (or conceptually similar).

do_getcaps(filter) virtual¶

Parameters:: filter (Gst.Caps) –
Return type:: Gst.Caps

Optional. Allows for a custom sink getcaps implementation. If not implemented, default returns GstAudio.AudioDecoder.proxy_getcaps applied to sink template caps.

do_handle_frame(buffer) virtual¶

Parameters:: buffer (Gst.Buffer) –
Return type:: Gst.FlowReturn

Provides input data (or None to clear any remaining data) to subclass. Input data ref management is performed by base class, subclass should not care or intervene, and input data is only valid until next call to base class, most notably a call to GstAudio.AudioDecoder.finish_frame().

do_negotiate() virtual¶

Returns:: True if the negotiation succeeded, else False.
Return type:: bool

Negotiate with downstream elements to currently configured GstAudio.AudioInfo. Unmark Gst.PadFlags.NEED_RECONFIGURE in any case. But mark it again if negotiate fails.

do_open() virtual¶

Return type:: bool

Optional. Called when the element changes to Gst.State.READY. Allows opening external resources.

do_parse(adapter) virtual¶

Parameters:: adapter (GstBase.Adapter) –
Return type:: (Gst.FlowReturn, offset: int, length: int)

do_pre_push(buffer) virtual¶

Parameters:: buffer (Gst.Buffer) –
Return type:: Gst.FlowReturn

Optional. Called just prior to pushing (encoded data) buffer downstream. Subclass has full discretionary access to buffer, and a not OK flow return will abort downstream pushing.

do_propose_allocation(query) virtual¶

Parameters:: query (Gst.Query) –
Return type:: bool

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

do_set_format(caps) virtual¶

Parameters:: caps (Gst.Caps) –
Return type:: bool

Notifies subclass of incoming data format (caps).

do_sink_event(event) virtual¶

Parameters:: event (Gst.Event) –
Return type:: bool

Optional. Event handler on the sink pad. Subclasses should chain up to the parent implementation to invoke the default handler.

do_sink_query(query) virtual¶

Parameters:: query (Gst.Query) –
Return type:: bool

Optional. Query handler on the sink pad. This function should return True if the query could be performed. Subclasses should chain up to the parent implementation to invoke the default handler.

New in version 1.6.

do_src_event(event) virtual¶

Parameters:: event (Gst.Event) –
Return type:: bool

Optional. Event handler on the src pad. Subclasses should chain up to the parent implementation to invoke the default handler.

do_src_query(query) virtual¶

Parameters:: query (Gst.Query) –
Return type:: bool

Optional. Query handler on the source pad. This function should return True if the query could be performed. Subclasses should chain up to the parent implementation to invoke the default handler.

New in version 1.6.

do_start() virtual¶

Return type:: bool

Optional. Called when the element starts processing. Allows opening external resources.

do_stop() virtual¶

Return type:: bool

Optional. Called when the element stops processing. Allows closing external resources.

do_transform_meta(outbuf, meta, inbuf) virtual¶

Parameters:

outbuf (Gst.Buffer) –
meta (Gst.Meta) –
inbuf (Gst.Buffer) –

Return type:

bool

Optional. Transform the metadata on the input buffer to the output buffer. By default this method copies all meta without tags and meta with only the “audio” tag. subclasses can implement this method and return True if the metadata is to be copied.

New in version 1.6.

Property Details¶

GstAudio.AudioDecoder.props.max_errors¶

Name:: max-errors
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE

Maximum number of tolerated consecutive decode errors. See GstAudio.AudioDecoder.set_max_errors() for more details.

New in version 1.18.

GstAudio.AudioDecoder.props.min_latency¶

Name:: min-latency
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

Aggregate output data to a minimum of latency time (ns)

GstAudio.AudioDecoder.props.plc¶

Name:: plc
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Perform packet loss concealment (if supported)

GstAudio.AudioDecoder.props.tolerance¶

Name:: tolerance
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

Perfect ts while timestamp jitter/imperfection within tolerance (ns)