gstaudio.audio_decoder

Module for [AudioDecoder] class

class AudioDecoder AudioDecoderGidBuilder AudioDecoderGidBuilderImpl

Types 3

classAudioDecoder : gst.element.Element

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

GstAudioDecoder and subclass should cooperate as follows.

Configuration

  • Initially, GstAudioDecoder 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).
  • GstAudioDecoder 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.
  • GstAudioDecoder calls @stop at end of all processing.

As of configuration stage, and throughout processing, GstAudioDecoder 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 GstAudioDecoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if @event callback has been provided.

Shutdown phase

  • GstAudioDecoder 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 #GstAudioDecoder: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 NULL data in @handle_frame and provide for data for indicated duration.
Methods
GType _getGType() static nothrow
GType _gType() @property nothrow
AudioDecoder self() nothrowReturns `this`, for use in `with` statements.
AudioDecoderGidBuilder builder() static nothrowGet builder for [gstaudio.audio_decoder.AudioDecoder] Returns: New builder object
int maxErrors() @property nothrowGet `maxErrors` property. Returns: Maximum number of tolerated consecutive decode errors. See [gstaudio.audio_decoder.AudioDecoder.setMaxErrors] for more details.
void maxErrors(int propval) @property nothrowSet `maxErrors` property. Params: propval = Maximum number of tolerated consecutive decode errors. See [gstaudio.audio_decoder.AudioDecoder.setMaxErrors] for more details.
long minLatency() @property nothrow
void minLatency(long propval) @property nothrow
bool plc() @property nothrow
void plc(bool propval) @property nothrow
long tolerance() @property nothrow
void tolerance(long propval) @property nothrow
gst.buffer.Buffer allocateOutputBuffer(size_t size) nothrowHelper function that allocates a buffer to hold an audio frame for dec's current output format.
gst.types.FlowReturn finishFrame(gst.buffer.Buffer buf, int frames) nothrowCollects decoded data and pushes it downstream.
gst.types.FlowReturn finishSubframe(gst.buffer.Buffer buf = null) nothrowCollects decoded data and pushes it downstream. This function may be called multiple times for a given input frame.
void getAllocator(out gst.allocator.Allocator allocator, out gst.allocation_params.AllocationParams params) nothrowLets #GstAudioDecoder sub-classes to know the memory allocator used by the base class and its params.
gstaudio.audio_info.AudioInfo getAudioInfo() nothrow
int getDelay() nothrow
bool getDrainable() nothrowQueries decoder drain handling. Returns: TRUE if drainable handling is enabled.
int getEstimateRate() nothrow
void getLatency(out gst.types.ClockTime min, out gst.types.ClockTime max) nothrowSets the variables pointed to by min and max to the currently configured latency.
int getMaxErrors() nothrow
gst.types.ClockTime getMinLatency() nothrowQueries decoder's latency aggregation. Returns: aggregation latency.
bool getNeedsFormat() nothrowQueries decoder required format handling. Returns: TRUE if required format handling is enabled.
void getParseState(out bool sync, out bool eos) nothrowReturn current parsing (sync and eos) state.
bool getPlc() nothrowQueries decoder packet loss concealment handling. Returns: TRUE if packet loss concealment is enabled.
int getPlcAware() nothrow
gst.types.ClockTime getTolerance() nothrowQueries current audio jitter tolerance threshold. Returns: decoder audio jitter tolerance threshold.
void mergeTags(gst.tag_list.TagList tags, gst.types.TagMergeMode mode) nothrowSets the audio decoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with [gstaudio.audio_decoder.AudioDecoder.mergeTags].
bool negotiate() nothrowNegotiate with downstream elements to currently configured #GstAudioInfo. Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if negotiate fails. Returns: true if the negotiation su...
gst.caps.Caps proxyGetcaps(gst.caps.Caps caps = null, gst.caps.Caps filter = null) nothrowReturns caps that express caps (or sink template caps if caps == NULL) restricted to rate/channels/... combinations supported by downstream elements.
void setAllocationCaps(gst.caps.Caps allocationCaps = null) nothrowSets a caps in allocation query which are different from the set pad's caps. Use this function before calling [gstaudio.audio_decoder.AudioDecoder.negotiate]. Setting to null the allocation query w...
void setDrainable(bool enabled) nothrowConfigures decoder drain handling. If drainable, subclass might be handed a NULL buffer to have it return any leftover decoded data. Otherwise, it is not considered so capable and will only ever b...
void setEstimateRate(bool enabled) nothrowAllows baseclass to perform byte to time estimated conversion.
void setLatency(gst.types.ClockTime min, gst.types.ClockTime max) nothrowSets 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.
void setMaxErrors(int num) nothrowSets 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...
void setMinLatency(gst.types.ClockTime num) nothrowSets decoder minimum aggregation latency.
void setNeedsFormat(bool enabled) nothrowConfigures 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. ...
bool setOutputCaps(gst.caps.Caps caps) nothrowConfigure output caps on the srcpad of dec. Similar to [gstaudio.audio_decoder.AudioDecoder.setOutputFormat], but allows subclasses to specify output caps that can't be expressed via #GstAudioInfo ...
bool setOutputFormat(gstaudio.audio_info.AudioInfo info) nothrowConfigure output info on the srcpad of dec.
void setPlc(bool enabled) nothrowEnable or disable decoder packet loss concealment, provided subclass and codec are capable and allow handling plc.
void setPlcAware(bool plc) nothrowIndicates whether or not subclass handles packet loss concealment (plc).
void setTolerance(gst.types.ClockTime tolerance) nothrowConfigures decoder audio jitter tolerance threshold.
void setUseDefaultPadAcceptcaps(bool use) nothrowLets #GstAudioDecoder sub-classes decide if they want the sink pad to use the default pad query handler to reply to accept-caps queries.
Constructors
this(void * ptr, Flag!"Take" take)
classAudioDecoderGidBuilderImpl(T) : gst.element.ElementGidBuilderImpl!T

Fluent builder implementation template for gstaudio.audio_decoder.AudioDecoder

Methods
T maxErrors(int propval) nothrowSet `maxErrors` property. Params: propval = Maximum number of tolerated consecutive decode errors. See [gstaudio.audio_decoder.AudioDecoder.setMaxErrors] for more details. Returns: Builder instance...
T minLatency(long propval) nothrow
T plc(bool propval) nothrow
T tolerance(long propval) nothrow
classAudioDecoderGidBuilder : AudioDecoderGidBuilderImpl!AudioDecoderGidBuilder

Fluent builder for gstaudio.audio_decoder.AudioDecoder

Methods
AudioDecoder build() nothrowCreate object from builder. Returns: New object