This base class is for audio encoders turning raw audio samples into encoded audio data.
GstAudioEncoder and subclass should cooperate as follows.
typeof (unichar2)typeof
(unichar2) 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.
typeof (unichar2)typeof
(unichar2) 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
finish_frame to have encoded data pushed downstream. Alternatively, it
might also call finish_frame (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.
typeof (unichar2)typeof
(unichar2) 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 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
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 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
finish_frame.
- public Buffer allocate_output_buffer (size_t size)
Helper function that allocates a buffer to hold an encoded audio frame
for this's current output format.
- public virtual bool close ()
- public virtual bool decide_allocation (Query query)
- public FlowReturn finish_frame (owned Buffer? buffer, int samples)
Collects encoded data and pushes encoded data downstream.
- public virtual void flush ()
- public void get_allocator (out Allocator allocator, out AllocationParams @params)
Lets Encoder sub-classes to know
the memory allocator used by the base class and its params.
- public unowned Info get_audio_info ()
- public bool get_drainable ()
Queries encoder drain handling.
- public int get_frame_max ()
- public int get_frame_samples_max ()
- public int get_frame_samples_min ()
- public bool get_hard_min ()
Queries encoder hard minimum handling.
- public bool get_hard_resync ()
- public void get_latency (out ClockTime min, out ClockTime max)
Sets the variables pointed to by min and max
to the currently configured latency.
- public int get_lookahead ()
- public bool get_mark_granule ()
Queries if the encoder will handle granule marking.
- public bool get_perfect_timestamp ()
Queries encoder perfect timestamp behaviour.
- public ClockTime get_tolerance ()
Queries current audio jitter tolerance threshold.
- public virtual Caps getcaps (Caps filter)
- public virtual FlowReturn handle_frame (Buffer buffer)
- public void merge_tags (TagList? tags, TagMergeMode mode)
Sets the audio encoder tags and how they should be merged with any
upstream stream tags.
- public virtual bool negotiate ()
Negotiate with downstream elements to currently configured
Caps.
- public virtual bool open ()
- public virtual FlowReturn pre_push (Buffer buffer)
- public virtual bool propose_allocation (Query query)
- public Caps proxy_getcaps (Caps? caps, Caps? filter)
Returns caps that express caps (or sink template caps if
caps == NULL) restricted to channel/rate combinations supported by downstream elements (e.g. muxers).
- public void set_allocation_caps (Caps? allocation_caps)
Sets a caps in allocation query which are different from the set pad's
caps.
- public void set_drainable (bool enabled)
Configures encoder drain handling.
- public virtual bool set_format (Info info)
- public void set_frame_max (int num)
Sets max number of frames accepted at once (assumed minimally 1).
- public void set_frame_samples_max (int num)
Sets number of samples (per channel) subclass needs to be handed, at
most or will be handed all available if 0.
- public void set_frame_samples_min (int num)
Sets number of samples (per channel) subclass needs to be handed, at
least or will be handed all available if 0.
- public void set_hard_min (bool enabled)
Configures encoder hard minimum handling.
- public void set_hard_resync (bool enabled)
- public void set_headers (owned List<Buffer> headers)
Set the codec headers to be sent downstream whenever requested.
- public void set_latency (ClockTime min, ClockTime max)
Sets encoder latency.
- public void set_lookahead (int num)
Sets encoder lookahead (in units of input rate samples)
- public void set_mark_granule (bool enabled)
Enable or disable encoder granule handling.
- public bool set_output_format (Caps caps)
Configure output caps on the srcpad of this
.
- public void set_perfect_timestamp (bool enabled)
Enable or disable encoder perfect output timestamp preference.
- public void set_tolerance (ClockTime tolerance)
Configures encoder audio jitter tolerance threshold.
- public virtual bool sink_event (Event event)
- public virtual bool sink_query (Query query)
- public virtual bool src_event (Event event)
- public virtual bool src_query (Query query)
- public virtual bool start ()
- public virtual bool stop ()
- public virtual bool transform_meta (Buffer outbuf, Meta meta, Buffer inbuf)