Configuration

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

Shutdown phase

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:

GST_AUDIO_ENCODER_SINK_PAD()

#define GST_AUDIO_ENCODER_SINK_PAD(obj) (GST_AUDIO_ENCODER_CAST (obj)->sinkpad)

Gives the pointer to the sink GstPad object of the element.

GST_AUDIO_ENCODER_SRC_PAD()

#define GST_AUDIO_ENCODER_SRC_PAD(obj) (GST_AUDIO_ENCODER_CAST (obj)->srcpad)

Gives the pointer to the source GstPad object of the element.

GST_AUDIO_ENCODER_INPUT_SEGMENT()

#define GST_AUDIO_ENCODER_INPUT_SEGMENT(obj)     (GST_AUDIO_ENCODER_CAST (obj)->input_segment)

Gives the input segment of the element.

GST_AUDIO_ENCODER_OUTPUT_SEGMENT()

#define GST_AUDIO_ENCODER_OUTPUT_SEGMENT(obj)     (GST_AUDIO_ENCODER_CAST (obj)->output_segment)

Gives the output segment of the element.

GST_AUDIO_ENCODER_STREAM_LOCK()

#define GST_AUDIO_ENCODER_STREAM_LOCK(enc)   g_rec_mutex_lock (&GST_AUDIO_ENCODER (enc)->stream_lock)

GST_AUDIO_ENCODER_STREAM_UNLOCK()

#define GST_AUDIO_ENCODER_STREAM_UNLOCK(enc) g_rec_mutex_unlock (&GST_AUDIO_ENCODER (enc)->stream_lock)

gst_audio_encoder_finish_frame ()

GstFlowReturn
gst_audio_encoder_finish_frame (GstAudioEncoder *enc,
                                GstBuffer *buffer,
                                gint samples);

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 gst_audio_encoder_handle_frame() may be invalidated by a call to this function.

gst_audio_encoder_allocate_output_buffer ()

GstBuffer *
gst_audio_encoder_allocate_output_buffer
                               (GstAudioEncoder *enc,
                                gsize size);

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

gst_audio_encoder_get_allocator ()

void
gst_audio_encoder_get_allocator (GstAudioEncoder *enc,
                                 GstAllocator **allocator,
                                 GstAllocationParams *params);

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

Unref the allocator after use it.

gst_audio_encoder_set_output_format ()

gboolean
gst_audio_encoder_set_output_format (GstAudioEncoder *enc,
                                     GstCaps *caps);

Configure output caps on the srcpad of enc .

gst_audio_encoder_negotiate ()

gboolean
gst_audio_encoder_negotiate (GstAudioEncoder *enc);

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

gst_audio_encoder_get_audio_info ()

GstAudioInfo *
gst_audio_encoder_get_audio_info (GstAudioEncoder *enc);

gst_audio_encoder_get_drainable ()

gboolean
gst_audio_encoder_get_drainable (GstAudioEncoder *enc);

Queries encoder drain handling.

gst_audio_encoder_get_frame_max ()

gint
gst_audio_encoder_get_frame_max (GstAudioEncoder *enc);

gst_audio_encoder_get_frame_samples_min ()

gint
gst_audio_encoder_get_frame_samples_min
                               (GstAudioEncoder *enc);

gst_audio_encoder_get_frame_samples_max ()

gint
gst_audio_encoder_get_frame_samples_max
                               (GstAudioEncoder *enc);

gst_audio_encoder_get_hard_min ()

gboolean
gst_audio_encoder_get_hard_min (GstAudioEncoder *enc);

Queries encoder hard minimum handling.

gst_audio_encoder_get_hard_resync ()

gboolean
gst_audio_encoder_get_hard_resync (GstAudioEncoder *enc);

gst_audio_encoder_get_latency ()

void
gst_audio_encoder_get_latency (GstAudioEncoder *enc,
                               GstClockTime *min,
                               GstClockTime *max);

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

gst_audio_encoder_get_lookahead ()

gint
gst_audio_encoder_get_lookahead (GstAudioEncoder *enc);

gst_audio_encoder_get_mark_granule ()

gboolean
gst_audio_encoder_get_mark_granule (GstAudioEncoder *enc);

Queries if the encoder will handle granule marking.

gst_audio_encoder_get_perfect_timestamp ()

gboolean
gst_audio_encoder_get_perfect_timestamp
                               (GstAudioEncoder *enc);

Queries encoder perfect timestamp behaviour.

gst_audio_encoder_get_tolerance ()

GstClockTime
gst_audio_encoder_get_tolerance (GstAudioEncoder *enc);

Queries current audio jitter tolerance threshold.

gst_audio_encoder_proxy_getcaps ()

GstCaps *
gst_audio_encoder_proxy_getcaps (GstAudioEncoder *enc,
                                 GstCaps *caps,
                                 GstCaps *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).

gst_audio_encoder_set_drainable ()

void
gst_audio_encoder_set_drainable (GstAudioEncoder *enc,
                                 gboolean 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 be passed real data.

MT safe.

gst_audio_encoder_set_frame_max ()

void
gst_audio_encoder_set_frame_max (GstAudioEncoder *enc,
                                 gint num);

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 GstAudioEncoder::set_format() is called.

gst_audio_encoder_set_frame_samples_min ()

void
gst_audio_encoder_set_frame_samples_min
                               (GstAudioEncoder *enc,
                                gint num);

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

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

gst_audio_encoder_set_frame_samples_max ()

void
gst_audio_encoder_set_frame_samples_max
                               (GstAudioEncoder *enc,
                                gint num);

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

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

gst_audio_encoder_set_hard_min ()

void
gst_audio_encoder_set_hard_min (GstAudioEncoder *enc,
                                gboolean 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 samples will simply be discarded.

MT safe.

gst_audio_encoder_set_hard_resync ()

void
gst_audio_encoder_set_hard_resync (GstAudioEncoder *enc,
                                   gboolean enabled);

gst_audio_encoder_set_headers ()

void
gst_audio_encoder_set_headers (GstAudioEncoder *enc,
                               GList *headers);

Set the codec headers to be sent downstream whenever requested.

gst_audio_encoder_set_latency ()

void
gst_audio_encoder_set_latency (GstAudioEncoder *enc,
                               GstClockTime min,
                               GstClockTime max);

Sets encoder latency.

gst_audio_encoder_set_lookahead ()

void
gst_audio_encoder_set_lookahead (GstAudioEncoder *enc,
                                 gint num);

Sets encoder lookahead (in units of input rate samples)

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

gst_audio_encoder_set_mark_granule ()

void
gst_audio_encoder_set_mark_granule (GstAudioEncoder *enc,
                                    gboolean enabled);

Enable or disable encoder granule handling.

MT safe.

gst_audio_encoder_set_perfect_timestamp ()

void
gst_audio_encoder_set_perfect_timestamp
                               (GstAudioEncoder *enc,
                                gboolean enabled);

Enable or disable encoder perfect output timestamp preference.

MT safe.

gst_audio_encoder_set_tolerance ()

void
gst_audio_encoder_set_tolerance (GstAudioEncoder *enc,
                                 GstClockTime tolerance);

Configures encoder audio jitter tolerance threshold.

MT safe.

gst_audio_encoder_set_allocation_caps ()

void
gst_audio_encoder_set_allocation_caps (GstAudioEncoder *enc,
                                       GstCaps *allocation_caps);

Sets a caps in allocation query which are different from the set pad's caps. Use this function before calling gst_audio_encoder_negotiate(). Setting to NULL the allocation query will use the caps from the pad.

Since: 1.10

gst_audio_encoder_merge_tags ()

void
gst_audio_encoder_merge_tags (GstAudioEncoder *enc,
                              const GstTagList *tags,
                              GstTagMergeMode 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 gst_audio_encoder_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.

struct GstAudioEncoder

struct GstAudioEncoder;

The opaque GstAudioEncoder data structure.

struct GstAudioEncoderClass

struct GstAudioEncoderClass {
  GstElementClass element_class;

  /* virtual methods for subclasses */

  gboolean      (*start)              (GstAudioEncoder *enc);

  gboolean      (*stop)               (GstAudioEncoder *enc);

  gboolean      (*set_format)         (GstAudioEncoder *enc,
                                       GstAudioInfo        *info);

  GstFlowReturn (*handle_frame)       (GstAudioEncoder *enc,
                                       GstBuffer *buffer);

  void          (*flush)              (GstAudioEncoder *enc);

  GstFlowReturn (*pre_push)           (GstAudioEncoder *enc,
                                       GstBuffer **buffer);

  gboolean      (*sink_event)         (GstAudioEncoder *enc,
                                       GstEvent *event);

  gboolean      (*src_event)          (GstAudioEncoder *enc,
                                       GstEvent *event);

  GstCaps *     (*getcaps)            (GstAudioEncoder *enc, GstCaps *filter);

  gboolean      (*open)               (GstAudioEncoder *enc);

  gboolean      (*close)              (GstAudioEncoder *enc);

  gboolean      (*negotiate)          (GstAudioEncoder *enc);

  gboolean      (*decide_allocation)  (GstAudioEncoder *enc, GstQuery *query);

  gboolean      (*propose_allocation) (GstAudioEncoder * enc,
                                       GstQuery * query);

  gboolean      (*transform_meta)     (GstAudioEncoder *enc, GstBuffer *outbuf,
                                       GstMeta *meta, GstBuffer *inbuf);

  gboolean      (*sink_query)         (GstAudioEncoder *encoder,
				       GstQuery *query);

  gboolean      (*src_query)          (GstAudioEncoder *encoder,
				       GstQuery *query);
};

Subclasses can override any of the available virtual methods or not, as needed. At minimum set_format and handle_frame needs to be overridden.

GST_AUDIO_ENCODER_SINK_NAME

#define GST_AUDIO_ENCODER_SINK_NAME "sink"

the name of the templates for the sink pad

GST_AUDIO_ENCODER_SRC_NAME

#define GST_AUDIO_ENCODER_SRC_NAME	        "src"

the name of the templates for the source pad

The “hard-resync” property

  “hard-resync”              gboolean

Perform clipping and sample flushing upon discontinuity.

Flags: Read / Write

Default value: FALSE

The “mark-granule” property

  “mark-granule”             gboolean

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

Flags: Read

Default value: FALSE

The “perfect-timestamp” property

  “perfect-timestamp”        gboolean

Favour perfect timestamps over tracking upstream timestamps.

Flags: Read / Write

Default value: FALSE

The “tolerance” property

  “tolerance”                gint64

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

Flags: Read / Write

Allowed values: >= 0

Default value: 40000000