gstaudio.audio_encoder
Module for [AudioEncoder] class
Types 3
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 @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.
- 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' @handle_frame.
- If codec processing results in encoded data, subclass should call
[gstaudio.audio_encoder.AudioEncoder.finishFrame] to have encoded data pushed downstream. Alternatively, it might also call [gstaudio.audio_encoder.AudioEncoder.finishFrame] (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 @pre_push.
- 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' @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 #GstAudioEncoder: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 #GstAudioEncoder: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 #GstAudioEncoder: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.audio_encoder.AudioEncoder.finishFrame].
AudioEncoder self()Returns `this`, for use in `with` statements.AudioEncoderGidBuilder builder()Get builder for [gstaudio.audio_encoder.AudioEncoder] Returns: New builder objectbool hardResync() @propertyvoid hardResync(bool propval) @propertybool markGranule() @propertybool perfectTimestamp() @propertyvoid perfectTimestamp(bool propval) @propertylong tolerance() @propertyvoid tolerance(long propval) @propertygst.buffer.Buffer allocateOutputBuffer(size_t size)Helper function that allocates a buffer to hold an encoded audio frame for enc's current output format.gst.types.FlowReturn finishFrame(gst.buffer.Buffer buffer, int samples)Collects encoded data and pushes encoded data downstream. Source pad caps must be set when this is called.void getAllocator(out gst.allocator.Allocator allocator, out gst.allocation_params.AllocationParams params)Lets #GstAudioEncoder sub-classes to know the memory allocator used by the base class and its params.bool getDrainable()Queries encoder drain handling. Returns: TRUE if drainable handling is enabled.int getFrameMax()int getFrameSamplesMax()int getFrameSamplesMin()bool getHardMin()Queries encoder hard minimum handling. Returns: TRUE if hard minimum handling is enabled.bool getHardResync()void getLatency(out gst.types.ClockTime min, out gst.types.ClockTime max)Sets the variables pointed to by min and max to the currently configured latency.int getLookahead()bool getMarkGranule()Queries if the encoder will handle granule marking. Returns: TRUE if granule marking is enabled.bool getPerfectTimestamp()Queries encoder perfect timestamp behaviour. Returns: TRUE if perfect timestamp setting enabled.gst.types.ClockTime getTolerance()Queries current audio jitter tolerance threshold. Returns: encoder audio jitter tolerance threshold.void mergeTags(gst.tag_list.TagList tags, gst.types.TagMergeMode mode)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.audio_encoder.AudioEncoder.mergeTags].bool negotiate()Negotiate with downstream elements to currently configured #GstCaps. Unmark GSTPADFLAGNEEDRECONFIGURE in any case. But mark it again if negotiate fails. Returns: true if the negotiation succeeded, ...gst.caps.Caps proxyGetcaps(gst.caps.Caps caps = null, gst.caps.Caps filter = null)Returns caps that express caps (or sink template caps if caps == NULL) restricted to channel/rate combinations supported by downstream elements (e.g. muxers).void setAllocationCaps(gst.caps.Caps allocationCaps = null)Sets a caps in allocation query which are different from the set pad's caps. Use this function before calling [gstaudio.audio_encoder.AudioEncoder.negotiate]. Setting to null the allocation query w...void setDrainable(bool enabled)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 b...void setFrameMax(int num)Sets max number of frames accepted at once (assumed minimally 1). Requires framesamplesmin and framesamplesmax to be the equal.void setFrameSamplesMax(int num)Sets number of samples (per channel) subclass needs to be handed, at most or will be handed all available if 0.void setFrameSamplesMin(int num)Sets number of samples (per channel) subclass needs to be handed, at least or will be handed all available if 0.void setHardMin(bool enabled)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 s...void setHardResync(bool enabled)void setLatency(gst.types.ClockTime min, gst.types.ClockTime max)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.void setLookahead(int num)Sets encoder lookahead (in units of input rate samples)void setMarkGranule(bool enabled)Enable or disable encoder granule handling.bool setOutputFormat(gst.caps.Caps caps)Configure output caps on the srcpad of enc.void setPerfectTimestamp(bool enabled)Enable or disable encoder perfect output timestamp preference.void setTolerance(gst.types.ClockTime tolerance)Configures encoder audio jitter tolerance threshold.Fluent builder for [gstaudio.audio_encoder.AudioEncoder]