GI.GstAudio.Objects.AudioEncoder

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

GstAudioEncoder and subclass should cooperate as follows.

Configuration

• Initially, GstAudioEncoder calls start when the encoder element is activated, which allows subclass to perform any global setup.

• GstAudioEncoder calls setFormat to inform subclass of the format of input audio data that it is about to receive. Subclass should setup for encoding and configure various base class parameters appropriately, notably those directing desired input data handling. While unlikely, it might be called more than once, if changing input parameters require reconfiguration.
• GstAudioEncoder calls stop at end of all processing.

As of configuration stage, and throughout processing, GstAudioEncoder maintains various parameters that provide required context, e.g. describing the format of input audio data. Conversely, subclass can and should configure these context parameters to inform base class of its expectation w.r.t. buffer handling.

Data processing

• Base class gathers input sample data (as directed by the context's frame_samples and frame_max) and provides this to subclass' handleFrame.
• If codec processing results in encoded data, subclass should call audioEncoderFinishFrame to have encoded data pushed downstream. Alternatively, it might also call audioEncoderFinishFrame (with a NULL buffer and some number of dropped samples) to indicate dropped (non-encoded) samples.
• Just prior to actually pushing a buffer downstream, it is passed to prePush.
• During the parsing process GstAudioEncoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if event callback has been provided.

Shutdown phase

• GstAudioEncoder 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 gstAudioEncoderFinishFrame.

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 either favor tracking upstream timestamps (at the possible expense of jitter) or aim to arrange for a perfect stream of output timestamps, depending on AudioEncoder:perfectTimestamp. However, in the latter case, the input may not be so perfect or ideal, which is handled as follows. An input timestamp is compared with the expected timestamp as dictated by input sample stream and if the deviation is less than AudioEncoder:tolerance, the deviation is discarded. Otherwise, it is considered a discontuinity and subsequent output timestamp is resynced to the new position after performing configured discontinuity processing. In the non-perfect-timestamp case, an upstream variation exceeding tolerance only leads to marking DISCONT on subsequent outgoing (while timestamps are adjusted to upstream regardless of variation). While DISCONT is also marked in the perfect-timestamp case, this one optionally (see AudioEncoder:hardResync) performs some additional steps, such as clipping of (early) input samples or draining all currently remaining input data, depending on the direction of the discontuinity.

If perfect timestamps are arranged, it is also possible to request baseclass (usually set by subclass) to provide additional buffer metadata (in OFFSET and OFFSET_END) fields according to granule defined semantics currently needed by oggmux. Specifically, OFFSET is set to granulepos (= sample count including buffer) and OFFSET_END to corresponding timestamp (as determined by same sample count and sample rate).

Things that subclass need to take care of:

• Provide pad templates
• Set source pad caps when appropriate
• Inform base class of buffer processing needs using context's frame_samples and frame_bytes.
• Set user-configurable properties to sane defaults for format and implementing codec at hand, e.g. those controlling timestamp behaviour and discontinuity processing.
• Accept data in handleFrame and provide encoded results to audioEncoderFinishFrame.

Exported types

newtype AudioEncoder

Memory-managed wrapper type.

Constructors

AudioEncoder (ManagedPtr AudioEncoder)

Instances

Eq AudioEncoder

Defined in GI.GstAudio.Objects.AudioEncoder

Methods

(==) :: AudioEncoder -> AudioEncoder -> Bool

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

GObject AudioEncoder

Defined in GI.GstAudio.Objects.AudioEncoder

ManagedPtrNewtype AudioEncoder

Defined in GI.GstAudio.Objects.AudioEncoder

Methods

toManagedPtr :: AudioEncoder -> ManagedPtr AudioEncoder

TypedObject AudioEncoder

Defined in GI.GstAudio.Objects.AudioEncoder

Methods

glibType :: IO GType

HasParentTypes AudioEncoder

Defined in GI.GstAudio.Objects.AudioEncoder

IsGValue (Maybe AudioEncoder)

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

Defined in GI.GstAudio.Objects.AudioEncoder

Methods

gvalueGType_ :: IO GType

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

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

type ParentTypes AudioEncoder

Defined in GI.GstAudio.Objects.AudioEncoder

type ParentTypes AudioEncoder = '[Element, Object, Object, Preset]

class (GObject o, IsDescendantOf AudioEncoder o) => IsAudioEncoder o

Type class for types which can be safely cast to AudioEncoder, for instance with toAudioEncoder.

Instances

(GObject o, IsDescendantOf AudioEncoder o) => IsAudioEncoder o

Defined in GI.GstAudio.Objects.AudioEncoder

toAudioEncoder :: (MonadIO m, IsAudioEncoder o) => o -> m AudioEncoder

Cast to AudioEncoder, 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, defaultError, deletePreset, finishFrame, forceFloating, foreachPad, foreachSinkPad, foreachSrcPad, freezeNotify, getv, hasActiveControlBindings, hasAncestor, hasAsAncestor, hasAsParent, isEditable, isFloating, isLockedState, iteratePads, iterateSinkPads, iterateSrcPads, link, linkFiltered, linkPads, linkPadsFiltered, linkPadsFull, loadPreset, lostState, mergeTags, messageFull, messageFullWithDetails, negotiate, noMorePads, notify, notifyByPspec, postMessage, provideClock, proxyGetcaps, query, queryConvert, queryDuration, queryPosition, ref, refSink, releaseRequestPad, removeControlBinding, removePad, removePropertyNotifyWatch, renamePreset, requestPad, requestPadSimple, runDispose, savePreset, 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, getDrainable, getFactory, getFrameMax, getFrameSamplesMax, getFrameSamplesMin, getGValueArray, getHardMin, getHardResync, getLatency, getLookahead, getMarkGranule, getMeta, getMetadata, getName, getPadTemplate, getPadTemplateList, getParent, getPathString, getPerfectTimestamp, getPresetNames, getProperty, getPropertyNames, getQdata, getRequestPad, getStartTime, getState, getStaticPad, getTolerance, getValue.

Setters

setAllocationCaps, setBaseTime, setBus, setClock, setContext, setControlBindingDisabled, setControlBindingsDisabled, setControlRate, setData, setDataFull, setDrainable, setFrameMax, setFrameSamplesMax, setFrameSamplesMin, setHardMin, setHardResync, setHeaders, setLatency, setLockedState, setLookahead, setMarkGranule, setMeta, setName, setOutputFormat, setParent, setPerfectTimestamp, setProperty, setStartTime, setState, setTolerance.

allocateOutputBuffer

audioEncoderAllocateOutputBuffer

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Word64

size: size of the buffer

-> m Buffer

Returns: allocated buffer

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

finishFrame

audioEncoderFinishFrame

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Maybe Buffer

buffer: encoded data

-> Int32

samples: number of samples (per channel) represented by encoded data

-> m FlowReturn

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

Collects encoded data and pushes encoded data downstream. Source pad caps must be set when this is called.

If samples < 0, then best estimate is all samples provided to encoder (subclass) so far. buf may be NULL, in which case next number of samples are considered discarded, e.g. as a result of discontinuous transmission, and a discontinuity is marked.

Note that samples received in AudioEncoderClass.handle_frame() may be invalidated by a call to this function.

getAllocator

audioEncoderGetAllocator

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m (Maybe Allocator, AllocationParams)

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

Unref the allocator after use it.

getAudioInfo

audioEncoderGetAudioInfo

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m AudioInfo

Returns: a AudioInfo describing the input audio format

No description available in the introspection data.

getDrainable

audioEncoderGetDrainable

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Bool

Returns: TRUE if drainable handling is enabled.

MT safe.

Queries encoder drain handling.

getFrameMax

audioEncoderGetFrameMax

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Int32

Returns: currently configured maximum handled frames

No description available in the introspection data.

getFrameSamplesMax

audioEncoderGetFrameSamplesMax

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Int32

Returns: currently maximum requested samples per frame

No description available in the introspection data.

getFrameSamplesMin

audioEncoderGetFrameSamplesMin

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Int32

Returns: currently minimum requested samples per frame

No description available in the introspection data.

getHardMin

audioEncoderGetHardMin

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Bool

Returns: TRUE if hard minimum handling is enabled.

MT safe.

Queries encoder hard minimum handling.

getHardResync

audioEncoderGetHardResync :: (HasCallStack, MonadIO m, IsAudioEncoder a) => a -> m Bool

No description available in the introspection data.

getLatency

audioEncoderGetLatency

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m (Word64, Word64)

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

getLookahead

audioEncoderGetLookahead

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Int32

Returns: currently configured encoder lookahead

No description available in the introspection data.

getMarkGranule

audioEncoderGetMarkGranule

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Bool

Returns: TRUE if granule marking is enabled.

MT safe.

Queries if the encoder will handle granule marking.

getPerfectTimestamp

audioEncoderGetPerfectTimestamp

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Bool

Returns: TRUE if perfect timestamp setting enabled.

MT safe.

Queries encoder perfect timestamp behaviour.

getTolerance

audioEncoderGetTolerance

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Word64

Returns: encoder audio jitter tolerance threshold.

MT safe.

Queries current audio jitter tolerance threshold.

mergeTags

audioEncoderMergeTags

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Maybe TagList

tags: a TagList to merge, or NULL to unset previously-set tags

-> TagMergeMode

mode: the TagMergeMode to use, usually GST_TAG_MERGE_REPLACE

-> m ()

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

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.

MT safe.

negotiate

audioEncoderNegotiate

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> m Bool

Returns: True if the negotiation succeeded, else False.

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

proxyGetcaps

audioEncoderProxyGetcaps

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> 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 channel/rate combinations supported by downstream elements (e.g. muxers).

setAllocationCaps

audioEncoderSetAllocationCaps

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> 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 audioEncoderNegotiate. Setting to Nothing the allocation query will use the caps from the pad.

Since: 1.10

setDrainable

audioEncoderSetDrainable

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Bool

enabled: new state

-> m ()

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

MT safe.

setFrameMax

audioEncoderSetFrameMax

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Int32

num: number of frames

-> m ()

Sets max number of frames accepted at once (assumed minimally 1). Requires frameSamplesMin and frameSamplesMax to be the equal.

Note: This value will be reset to 0 every time before AudioEncoderClass.set_format() is called.

setFrameSamplesMax

audioEncoderSetFrameSamplesMax

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Int32

num: number of samples per frame

-> m ()

Sets number of samples (per channel) subclass needs to be handed, at most or will be handed all available if 0.

If an exact number of samples is required, audioEncoderSetFrameSamplesMin must be called with the same number.

Note: This value will be reset to 0 every time before AudioEncoderClass.set_format() is called.

setFrameSamplesMin

audioEncoderSetFrameSamplesMin

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Int32

num: number of samples per frame

-> m ()

Sets number of samples (per channel) subclass needs to be handed, at least or will be handed all available if 0.

If an exact number of samples is required, audioEncoderSetFrameSamplesMax must be called with the same number.

Note: This value will be reset to 0 every time before AudioEncoderClass.set_format() is called.

setHardMin

audioEncoderSetHardMin

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Bool

enabled: new state

-> m ()

Configures encoder hard minimum handling. If enabled, subclass will never be handed less samples than it configured, which otherwise might occur near end-of-data handling. Instead, the leftover samples will simply be discarded.

MT safe.

setHardResync

audioEncoderSetHardResync :: (HasCallStack, MonadIO m, IsAudioEncoder a) => a -> Bool -> m ()

No description available in the introspection data.

setHeaders

audioEncoderSetHeaders

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> [Buffer]

headers: a list of Buffer containing the codec header

-> m ()

Set the codec headers to be sent downstream whenever requested.

setLatency

audioEncoderSetLatency

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Word64

min: minimum latency

-> Word64

max: maximum latency

-> m ()

Sets encoder 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.

setLookahead

audioEncoderSetLookahead

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Int32

num: lookahead

-> m ()

Sets encoder lookahead (in units of input rate samples)

Note: This value will be reset to 0 every time before AudioEncoderClass.set_format() is called.

setMarkGranule

audioEncoderSetMarkGranule

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Bool

enabled: new state

-> m ()

Enable or disable encoder granule handling.

MT safe.

setOutputFormat

audioEncoderSetOutputFormat

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Caps

caps: Caps

-> m Bool

Returns: True on success.

Configure output caps on the srcpad of enc.

setPerfectTimestamp

audioEncoderSetPerfectTimestamp

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Bool

enabled: new state

-> m ()

Enable or disable encoder perfect output timestamp preference.

MT safe.

setTolerance

audioEncoderSetTolerance

Arguments

:: (HasCallStack, MonadIO m, IsAudioEncoder a)

=> a

enc: a AudioEncoder

-> Word64

tolerance: new tolerance

-> m ()

Configures encoder audio jitter tolerance threshold.

MT safe.

Properties

hardResync

No description available in the introspection data.

constructAudioEncoderHardResync :: (IsAudioEncoder o, MonadIO m) => Bool -> m (GValueConstruct o)

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

getAudioEncoderHardResync :: (MonadIO m, IsAudioEncoder o) => o -> m Bool

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

get audioEncoder #hardResync

setAudioEncoderHardResync :: (MonadIO m, IsAudioEncoder o) => o -> Bool -> m ()

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

set audioEncoder [ #hardResync := value ]

markGranule

No description available in the introspection data.

getAudioEncoderMarkGranule :: (MonadIO m, IsAudioEncoder o) => o -> m Bool

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

get audioEncoder #markGranule

perfectTimestamp

No description available in the introspection data.

constructAudioEncoderPerfectTimestamp :: (IsAudioEncoder o, MonadIO m) => Bool -> m (GValueConstruct o)

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

getAudioEncoderPerfectTimestamp :: (MonadIO m, IsAudioEncoder o) => o -> m Bool

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

get audioEncoder #perfectTimestamp

setAudioEncoderPerfectTimestamp :: (MonadIO m, IsAudioEncoder o) => o -> Bool -> m ()

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

set audioEncoder [ #perfectTimestamp := value ]

tolerance

No description available in the introspection data.

constructAudioEncoderTolerance :: (IsAudioEncoder 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.

getAudioEncoderTolerance :: (MonadIO m, IsAudioEncoder o) => o -> m Int64

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

get audioEncoder #tolerance

setAudioEncoderTolerance :: (MonadIO m, IsAudioEncoder o) => o -> Int64 -> m ()

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

set audioEncoder [ #tolerance := value ]