GI.GstAudio.Objects.AudioDecoder

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 setFormat).
• GstAudioDecoder calls setFormat 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' handleFrame.
• If codec processing results in decoded data, subclass should call gstAudioDecoderFinishFrame to have decoded data pushed downstream.
• Just prior to actually pushing a buffer downstream, it is passed to prePush. 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' setFormat function, though it might be delayed until calling gstAudioDecoderFinishFrame.

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. prePush), 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 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 handleFrame and provide encoded results to gstAudioDecoderFinishFrame. If it is prepared to perform PLC, it should also accept NULL data in handleFrame and provide for data for indicated duration.

Exported types

newtype AudioDecoder

Memory-managed wrapper type.

Constructors

AudioDecoder (ManagedPtr AudioDecoder)

Instances

Eq AudioDecoder

Defined in GI.GstAudio.Objects.AudioDecoder

Methods

(==) :: AudioDecoder -> AudioDecoder -> Bool

(/=) :: AudioDecoder -> AudioDecoder -> Bool

GObject AudioDecoder

Defined in GI.GstAudio.Objects.AudioDecoder

ManagedPtrNewtype AudioDecoder

Defined in GI.GstAudio.Objects.AudioDecoder

Methods

toManagedPtr :: AudioDecoder -> ManagedPtr AudioDecoder

TypedObject AudioDecoder

Defined in GI.GstAudio.Objects.AudioDecoder

Methods

glibType :: IO GType

HasParentTypes AudioDecoder

Defined in GI.GstAudio.Objects.AudioDecoder

IsGValue (Maybe AudioDecoder)

Convert AudioDecoder to and from GValue. See toGValue and fromGValue.

Defined in GI.GstAudio.Objects.AudioDecoder

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe AudioDecoder -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe AudioDecoder)

type ParentTypes AudioDecoder

Defined in GI.GstAudio.Objects.AudioDecoder

type ParentTypes AudioDecoder = '[Element, Object, Object]

class (GObject o, IsDescendantOf AudioDecoder o) => IsAudioDecoder o

Type class for types which can be safely cast to AudioDecoder, for instance with toAudioDecoder.

Instances

(GObject o, IsDescendantOf AudioDecoder o) => IsAudioDecoder o

Defined in GI.GstAudio.Objects.AudioDecoder

toAudioDecoder :: (MonadIO m, IsAudioDecoder o) => o -> m AudioDecoder

Cast to AudioDecoder, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

abortState, addControlBinding, addPad, addPropertyDeepNotifyWatch, addPropertyNotifyWatch, allocateOutputBuffer, bindProperty, bindPropertyFull, callAsync, changeState, continueState, createAllPads, decorateStreamId, defaultError, finishFrame, finishSubframe, forceFloating, foreachPad, foreachSinkPad, foreachSrcPad, freezeNotify, getv, hasActiveControlBindings, hasAncestor, hasAsAncestor, hasAsParent, isFloating, isLockedState, iteratePads, iterateSinkPads, iterateSrcPads, link, linkFiltered, linkPads, linkPadsFiltered, linkPadsFull, lostState, mergeTags, messageFull, messageFullWithDetails, negotiate, noMorePads, notify, notifyByPspec, postMessage, provideClock, proxyGetcaps, query, queryConvert, queryDuration, queryPosition, ref, refSink, releaseRequestPad, removeControlBinding, removePad, removePropertyNotifyWatch, requestPad, requestPadSimple, runDispose, seek, seekSimple, sendEvent, stealData, stealQdata, suggestNextSync, syncStateWithParent, syncValues, thawNotify, unlink, unlinkPads, unparent, unref, watchClosure.

Getters

getAllocator, getAudioInfo, getBaseTime, getBus, getClock, getCompatiblePad, getCompatiblePadTemplate, getContext, getContextUnlocked, getContexts, getControlBinding, getControlRate, getCurrentClockTime, getCurrentRunningTime, getData, getDelay, getDrainable, getEstimateRate, getFactory, getGValueArray, getLatency, getMaxErrors, getMetadata, getMinLatency, getName, getNeedsFormat, getPadTemplate, getPadTemplateList, getParent, getParseState, getPathString, getPlc, getPlcAware, getProperty, getQdata, getRequestPad, getStartTime, getState, getStaticPad, getTolerance, getValue.

Setters

setAllocationCaps, setBaseTime, setBus, setClock, setContext, setControlBindingDisabled, setControlBindingsDisabled, setControlRate, setData, setDataFull, setDrainable, setEstimateRate, setLatency, setLockedState, setMaxErrors, setMinLatency, setName, setNeedsFormat, setOutputCaps, setOutputFormat, setParent, setPlc, setPlcAware, setProperty, setStartTime, setState, setTolerance, setUseDefaultPadAcceptcaps.

allocateOutputBuffer

audioDecoderAllocateOutputBuffer

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> CSize

size: size of the buffer

-> m Buffer

Returns: allocated buffer

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

finishFrame

audioDecoderFinishFrame

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Maybe Buffer

buf: decoded data

-> Int32

frames: number of decoded frames represented by decoded data

-> m FlowReturn

Returns: a FlowReturn that should be escalated to caller (of caller)

Collects decoded data and pushes it downstream.

buf may be NULL 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 AudioDecoderClass.handle_frame() may be invalidated by a call to this function.

finishSubframe

audioDecoderFinishSubframe

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Maybe Buffer

buf: decoded data

-> m FlowReturn

Returns: a FlowReturn that should be escalated to caller (of caller)

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

buf may be NULL in which case it is assumed that the current input frame is finished. This is equivalent to calling audioDecoderFinishSubframe with a NULL 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 AudioDecoderClass.handle_frame() may be invalidated by a call to this function.

Since: 1.16

getAllocator

audioDecoderGetAllocator

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m (Maybe Allocator, AllocationParams)

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

Unref the allocator after use it.

getAudioInfo

audioDecoderGetAudioInfo

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m AudioInfo

Returns: a AudioInfo describing the input audio format

No description available in the introspection data.

getDelay

audioDecoderGetDelay

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Int32

Returns: currently configured decoder delay

No description available in the introspection data.

getDrainable

audioDecoderGetDrainable

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Bool

Returns: TRUE if drainable handling is enabled.

MT safe.

Queries decoder drain handling.

getEstimateRate

audioDecoderGetEstimateRate

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Int32

Returns: currently configured byte to time conversion setting

No description available in the introspection data.

getLatency

audioDecoderGetLatency

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m (Word64, Word64)

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

getMaxErrors

audioDecoderGetMaxErrors

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Int32

Returns: currently configured decoder tolerated error count.

No description available in the introspection data.

getMinLatency

audioDecoderGetMinLatency

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Word64

Returns: aggregation latency.

MT safe.

Queries decoder's latency aggregation.

getNeedsFormat

audioDecoderGetNeedsFormat

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Bool

Returns: TRUE if required format handling is enabled.

MT safe.

Queries decoder required format handling.

getParseState

audioDecoderGetParseState

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m (Bool, Bool)

Return current parsing (sync and eos) state.

getPlc

audioDecoderGetPlc

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Bool

Returns: TRUE if packet loss concealment is enabled.

MT safe.

Queries decoder packet loss concealment handling.

getPlcAware

audioDecoderGetPlcAware

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Int32

Returns: currently configured plc handling

No description available in the introspection data.

getTolerance

audioDecoderGetTolerance

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Word64

Returns: decoder audio jitter tolerance threshold.

MT safe.

Queries current audio jitter tolerance threshold.

mergeTags

audioDecoderMergeTags

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Maybe TagList

tags: a TagList to merge, or NULL

-> TagMergeMode

mode: the TagMergeMode to use, usually GST_TAG_MERGE_REPLACE

-> m ()

Sets the audio decoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with audioDecoderMergeTags.

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

audioDecoderNegotiate

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> m Bool

Returns: True if the negotiation succeeded, else False.

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

proxyGetcaps

audioDecoderProxyGetcaps

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

decoder: a AudioDecoder

-> Maybe Caps

caps: initial caps

-> Maybe Caps

filter: filter caps

-> m Caps

Returns: a Caps owned by caller

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

Since: 1.6

setAllocationCaps

audioDecoderSetAllocationCaps

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Maybe Caps

allocationCaps: a Caps or Nothing

-> m ()

Sets a caps in allocation query which are different from the set pad's caps. Use this function before calling audioDecoderNegotiate. Setting to Nothing the allocation query will use the caps from the pad.

Since: 1.10

setDrainable

audioDecoderSetDrainable

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Bool

enabled: new state

-> m ()

Configures 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 be passed real data.

MT safe.

setEstimateRate

audioDecoderSetEstimateRate

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Bool

enabled: whether to enable byte to time conversion

-> m ()

Allows baseclass to perform byte to time estimated conversion.

setLatency

audioDecoderSetLatency

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Word64

min: minimum latency

-> Word64

max: maximum latency

-> m ()

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.

setMaxErrors

audioDecoderSetMaxErrors

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Int32

num: max tolerated errors

-> m ()

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 GST_AUDIO_DECODER_MAX_ERRORS.

setMinLatency

audioDecoderSetMinLatency

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Word64

num: new minimum latency

-> m ()

Sets decoder minimum aggregation latency.

MT safe.

setNeedsFormat

audioDecoderSetNeedsFormat

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Bool

enabled: new state

-> m ()

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.

setOutputCaps

audioDecoderSetOutputCaps

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Caps

caps: (fixed) Caps

-> m Bool

Returns: True on success.

Configure output caps on the srcpad of dec. Similar to audioDecoderSetOutputFormat, but allows subclasses to specify output caps that can't be expressed via AudioInfo e.g. caps that have caps features.

Since: 1.16

setOutputFormat

audioDecoderSetOutputFormat

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> AudioInfo

info: AudioInfo

-> m Bool

Returns: True on success.

Configure output info on the srcpad of dec.

setPlc

audioDecoderSetPlc

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Bool

enabled: new state

-> m ()

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

MT safe.

setPlcAware

audioDecoderSetPlcAware

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Bool

plc: new plc state

-> m ()

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

setTolerance

audioDecoderSetTolerance

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

dec: a AudioDecoder

-> Word64

tolerance: new tolerance

-> m ()

Configures decoder audio jitter tolerance threshold.

MT safe.

setUseDefaultPadAcceptcaps

audioDecoderSetUseDefaultPadAcceptcaps

Arguments

:: (HasCallStack, MonadIO m, IsAudioDecoder a)

=> a

decoder: a AudioDecoder

-> Bool

use: if the default pad accept-caps query handling should be used

-> m ()

Lets 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

Since: 1.6

Properties

maxErrors

Maximum number of tolerated consecutive decode errors. See audioDecoderSetMaxErrors for more details.

Since: 1.18

constructAudioDecoderMaxErrors :: (IsAudioDecoder o, MonadIO m) => Int32 -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “max-errors” property. This is rarely needed directly, but it is used by new.

getAudioDecoderMaxErrors :: (MonadIO m, IsAudioDecoder o) => o -> m Int32

Get the value of the “max-errors” property. When overloading is enabled, this is equivalent to

get audioDecoder #maxErrors

setAudioDecoderMaxErrors :: (MonadIO m, IsAudioDecoder o) => o -> Int32 -> m ()

Set the value of the “max-errors” property. When overloading is enabled, this is equivalent to

set audioDecoder [ #maxErrors := value ]

minLatency

No description available in the introspection data.

constructAudioDecoderMinLatency :: (IsAudioDecoder o, MonadIO m) => Int64 -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “min-latency” property. This is rarely needed directly, but it is used by new.

getAudioDecoderMinLatency :: (MonadIO m, IsAudioDecoder o) => o -> m Int64

Get the value of the “min-latency” property. When overloading is enabled, this is equivalent to

get audioDecoder #minLatency

setAudioDecoderMinLatency :: (MonadIO m, IsAudioDecoder o) => o -> Int64 -> m ()

Set the value of the “min-latency” property. When overloading is enabled, this is equivalent to

set audioDecoder [ #minLatency := value ]

plc

No description available in the introspection data.

constructAudioDecoderPlc :: (IsAudioDecoder o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “plc” property. This is rarely needed directly, but it is used by new.

getAudioDecoderPlc :: (MonadIO m, IsAudioDecoder o) => o -> m Bool

Get the value of the “plc” property. When overloading is enabled, this is equivalent to

get audioDecoder #plc

setAudioDecoderPlc :: (MonadIO m, IsAudioDecoder o) => o -> Bool -> m ()

Set the value of the “plc” property. When overloading is enabled, this is equivalent to

set audioDecoder [ #plc := value ]

tolerance

No description available in the introspection data.

constructAudioDecoderTolerance :: (IsAudioDecoder o, MonadIO m) => Int64 -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “tolerance” property. This is rarely needed directly, but it is used by new.

getAudioDecoderTolerance :: (MonadIO m, IsAudioDecoder o) => o -> m Int64

Get the value of the “tolerance” property. When overloading is enabled, this is equivalent to

get audioDecoder #tolerance

setAudioDecoderTolerance :: (MonadIO m, IsAudioDecoder o) => o -> Int64 -> m ()

Set the value of the “tolerance” property. When overloading is enabled, this is equivalent to

set audioDecoder [ #tolerance := value ]