This base class is for audio decoders turning encoded data into raw audio samples.
GstAudioDecoder and subclass should cooperate as follows.
typeof (unichar2)typeof
(unichar2) 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 set_format). * GstAudioDecoder calls set_format 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.
typeof (unichar2)typeof
(unichar2) 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' handle_frame. * If codec
processing results in decoded data, subclass should call gst_audio_decoder_finish_frame to have decoded data pushed
downstream. * Just prior to actually pushing a buffer downstream, it is passed to pre_push. 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.
typeof (unichar2)typeof
(unichar2) 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' set_format
function, though it might be delayed until calling gst_audio_decoder_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 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
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 handle_frame and provide encoded results to gst_audio_decoder_finish_frame. If it is prepared
to perform PLC, it should also accept NULL data in handle_frame and provide for data for indicated duration.
- public Buffer allocate_output_buffer (size_t size)
Helper function that allocates a buffer to hold an 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? buf, int frames)
Collects decoded data and pushes it downstream.
- public FlowReturn finish_subframe (owned Buffer? buf)
Collects decoded data and pushes it downstream.
- public virtual void flush (bool hard)
- public void get_allocator (out Allocator allocator, out AllocationParams @params)
Lets Decoder sub-classes to know
the memory allocator used by the base class and its params.
- public unowned Info get_audio_info ()
- public int get_delay ()
- public bool get_drainable ()
Queries decoder drain handling.
- public int get_estimate_rate ()
- 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_max_errors ()
- public ClockTime get_min_latency ()
Queries decoder's latency aggregation.
- public bool get_needs_format ()
Queries decoder required format handling.
- public void get_parse_state (out bool sync, out bool eos)
Return current parsing (sync and eos) state.
- public bool get_plc ()
Queries decoder packet loss concealment handling.
- public int get_plc_aware ()
- 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 decoder tags and how they should be merged with any
upstream stream tags.
- public virtual bool negotiate ()
Negotiate with downstream elements to currently configured
Info.
- public virtual bool open ()
- public virtual FlowReturn parse (Adapter adapter, out int offset, out int length)
- 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 rate/channels/... combinations supported by downstream elements.
- 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 decoder drain handling.
- public void set_estimate_rate (bool enabled)
Allows baseclass to perform byte to time estimated conversion.
- public virtual bool set_format (Caps caps)
- public void set_latency (ClockTime min, ClockTime max)
Sets decoder latency.
- public void set_max_errors (int num)
Sets numbers of tolerated decoder errors, where a tolerated one is
then only warned about, but more than tolerated will lead to fatal error.
- public void set_min_latency (ClockTime num)
Sets decoder minimum aggregation latency.
- public void set_needs_format (bool enabled)
Configures decoder format needs.
- public bool set_output_caps (Caps caps)
Configure output caps on the srcpad of this
.
- public bool set_output_format (Info info)
Configure output info on the srcpad of this
.
- public void set_plc (bool enabled)
Enable or disable decoder packet loss concealment, provided subclass
and codec are capable and allow handling plc.
- public void set_plc_aware (bool plc)
Indicates whether or not subclass handles packet loss concealment
(plc).
- public void set_tolerance (ClockTime tolerance)
Configures decoder audio jitter tolerance threshold.
- public void set_use_default_pad_acceptcaps (bool use)
Lets Decoder sub-classes decide if
they want the sink pad to use the default pad query handler to reply to accept-caps queries.
- 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)