GstAudio.AudioEncoder¶

Subclasses:: None

Methods¶

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

	`allocate_output_buffer` (size)
	`finish_frame` (buffer, samples)
	`get_allocator` ()
	`get_audio_info` ()
	`get_drainable` ()
	`get_frame_max` ()
	`get_frame_samples_max` ()
	`get_frame_samples_min` ()
	`get_hard_min` ()
	`get_hard_resync` ()
	`get_latency` ()
	`get_lookahead` ()
	`get_mark_granule` ()
	`get_perfect_timestamp` ()
	`get_tolerance` ()
	`merge_tags` (tags, mode)
	`negotiate` ()
	`proxy_getcaps` (caps, filter)
	`set_allocation_caps` (allocation_caps)
	`set_drainable` (enabled)
	`set_frame_max` (num)
	`set_frame_samples_max` (num)
	`set_frame_samples_min` (num)
	`set_hard_min` (enabled)
	`set_hard_resync` (enabled)
	`set_headers` (headers)
	`set_latency` (min, max)
	`set_lookahead` (num)
	`set_mark_granule` (enabled)
	`set_output_format` (caps)
	`set_perfect_timestamp` (enabled)
	`set_tolerance` (tolerance)

Virtual Methods¶

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

	`do_close` ()
	`do_decide_allocation` (query)
	`do_flush` ()
	`do_getcaps` (filter)
	`do_handle_frame` (buffer)
	`do_negotiate` ()
	`do_open` ()
	`do_pre_push` (buffer)
	`do_propose_allocation` (query)
	`do_set_format` (info)
	`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
`hard-resync`	`bool`	r/w	Perform clipping and sample flushing upon discontinuity
`mark-granule`	`bool`	r	Apply granule semantics to buffer metadata (implies perfect-timestamp)
`perfect-timestamp`	`bool`	r/w	Favour perfect timestamps over tracking upstream timestamps
`tolerance`	`int`	r/w	Consider discontinuity if timestamp jitter/imperfection exceeds 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.AudioEncoder(**kwargs)¶

Bases:: Gst.Element, Gst.Preset
Abstract:: Yes
Structure:: GstAudio.AudioEncoderClass

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

GstAudio.AudioEncoder and subclass should cooperate as follows.

Configuration

Initially, GstAudio.AudioEncoder calls start when the encoder element is activated, which allows subclass to perform any global setup.
GstAudio.AudioEncoder calls set_format 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.
GstAudio.AudioEncoder calls stop at end of all processing.

As of configuration stage, and throughout processing, GstAudio.AudioEncoder 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’ handle_frame.
- If codec processing results in encoded data, subclass should call GstAudio.AudioEncoder.finish_frame() to have encoded data pushed downstream. Alternatively, it might also call GstAudio.AudioEncoder.finish_frame() (with a None 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 pre_push.
- During the parsing process GstAudio.AudioEncoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if event callback has been provided.

Shutdown phase

GstAudio.AudioEncoder 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_encoder_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 either favor tracking upstream timestamps (at the possible expense of jitter) or aim to arrange for a perfect stream of output timestamps, depending on GstAudio.AudioEncoder :perfect-timestamp. 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 GstAudio.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 GstAudio.AudioEncoder :hard-resync) 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 handle_frame and provide encoded results to GstAudio.AudioEncoder.finish_frame().

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 encoded audio frame for self's current output format.

finish_frame(buffer, samples)[source]¶

Parameters:

buffer (Gst.Buffer or None) – encoded data
samples (int) – number of samples (per channel) represented by encoded data

Returns:

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

Return type:

Gst.FlowReturn

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 None, 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 GstAudio.AudioEncoder.do_handle_frame() may be invalidated by a call to this function.

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.AudioEncoder 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_drainable()[source]¶

Returns:

True if drainable handling is enabled.

MT safe.

Return type:

bool

Queries encoder drain handling.

get_frame_max()[source]¶

Returns:: currently configured maximum handled frames
Return type:: int

get_frame_samples_max()[source]¶

Returns:: currently maximum requested samples per frame
Return type:: int

get_frame_samples_min()[source]¶

Returns:: currently minimum requested samples per frame
Return type:: int

get_hard_min()[source]¶

Returns:

True if hard minimum handling is enabled.

MT safe.

Return type:

bool

Queries encoder hard minimum handling.

get_hard_resync()[source]¶

Return type:: bool

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_lookahead()[source]¶

Returns:: currently configured encoder lookahead
Return type:: int

get_mark_granule()[source]¶

Returns:

True if granule marking is enabled.

MT safe.

Return type:

bool

Queries if the encoder will handle granule marking.

get_perfect_timestamp()[source]¶

Returns:

True if perfect timestamp setting enabled.

MT safe.

Return type:

bool

Queries encoder perfect timestamp behaviour.

get_tolerance()[source]¶

Returns:

encoder 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 to unset previously-set tags
mode (Gst.TagMergeMode) – the Gst.TagMergeMode to use, usually Gst.TagMergeMode.REPLACE

Sets the audio encoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with GstAudio.AudioEncoder.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.

MT safe.

negotiate()[source]¶

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

Negotiate with downstream elements to currently configured Gst.Caps. 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 channel/rate combinations supported by downstream elements (e.g. muxers).

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.AudioEncoder.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 encoder drain handling. If drainable, subclass might be handed a None 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.

set_frame_max(num)[source]¶

Parameters:: num (int) – number of frames

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

Note: This value will be reset to 0 every time before GstAudio.AudioEncoder.do_set_format() is called.

set_frame_samples_max(num)[source]¶

Parameters:: num (int) – number of samples per frame

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, GstAudio.AudioEncoder.set_frame_samples_min() must be called with the same number.

Note: This value will be reset to 0 every time before GstAudio.AudioEncoder.do_set_format() is called.

set_frame_samples_min(num)[source]¶

Parameters:: num (int) – number of samples per frame

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, GstAudio.AudioEncoder.set_frame_samples_max() must be called with the same number.

Note: This value will be reset to 0 every time before GstAudio.AudioEncoder.do_set_format() is called.

set_hard_min(enabled)[source]¶

Parameters:: enabled (bool) – new state

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.

set_hard_resync(enabled)[source]¶

Parameters:: enabled (bool) –

set_headers(headers)[source]¶

Parameters:: headers ([Gst.Buffer]) – a list of Gst.Buffer containing the codec header

Set the codec headers to be sent downstream whenever requested.

set_latency(min, max)[source]¶

Parameters:

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

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.

set_lookahead(num)[source]¶

Parameters:: num (int) – lookahead

Sets encoder lookahead (in units of input rate samples)

Note: This value will be reset to 0 every time before GstAudio.AudioEncoder.do_set_format() is called.

set_mark_granule(enabled)[source]¶

Parameters:: enabled (bool) – new state

Enable or disable encoder granule handling.

MT safe.

set_output_format(caps)[source]¶

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

Configure output caps on the srcpad of self.

set_perfect_timestamp(enabled)[source]¶

Parameters:: enabled (bool) – new state

Enable or disable encoder perfect output timestamp preference.

MT safe.

set_tolerance(tolerance)[source]¶

Parameters:: tolerance (int) – new tolerance

Configures encoder audio jitter tolerance threshold.

MT safe.

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() virtual¶: Optional. Instructs subclass to clear any codec caches and discard any pending samples and not yet returned encoded data.

do_getcaps(filter) virtual¶

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

Optional. Allows for a custom sink getcaps implementation (e.g. for multichannel input specification). If not implemented, default returns GstAudio.AudioEncoder.proxy_getcaps applied to sink template caps.

do_handle_frame(buffer) virtual¶

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

Provides input samples (or None to clear any remaining data) according to directions as configured by the subclass using the API. 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.AudioEncoder.finish_frame().

do_negotiate() virtual¶

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

Negotiate with downstream elements to currently configured Gst.Caps. 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_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(info) virtual¶

Parameters:: info (GstAudio.AudioInfo) –
Return type:: bool

Notifies subclass of incoming data format. GstAudio.AudioInfo contains the format according to provided 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.AudioEncoder.props.hard_resync¶

Name:: hard-resync
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Perform clipping and sample flushing upon discontinuity

GstAudio.AudioEncoder.props.mark_granule¶

Name:: mark-granule
Type:: bool
Default Value:: False
Flags:: READABLE

Apply granule semantics to buffer metadata (implies perfect-timestamp)

GstAudio.AudioEncoder.props.perfect_timestamp¶

Name:: perfect-timestamp
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Favour perfect timestamps over tracking upstream timestamps

GstAudio.AudioEncoder.props.tolerance¶

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

Consider discontinuity if timestamp jitter/imperfection exceeds tolerance (ns)