gstaudioencoder

## gstaudioencoder gstaudioencoder — Base class for audio encoders |

## Synopsis

    #include <gst/audio/gstaudioencoder.h>

    struct              GstAudioEncoder;
    struct              GstAudioEncoderClass;
    #define             GST_AUDIO_ENCODER_SINK_NAME
    #define             GST_AUDIO_ENCODER_SINK_PAD          (obj)
    #define             GST_AUDIO_ENCODER_SRC_NAME
    #define             GST_AUDIO_ENCODER_SRC_PAD           (obj)
    GstFlowReturn       gst_audio_encoder_finish_frame      (GstAudioEncoder *enc,
                                                             GstBuffer *buffer,
                                                             gint samples);
    GstBuffer *         gst_audio_encoder_allocate_output_buffer
                                                            (GstAudioEncoder *enc,
                                                             gsize size);
    void                gst_audio_encoder_get_allocator     (GstAudioEncoder *enc,
                                                             GstAllocator **allocator,
                                                             GstAllocationParams *params);
    gboolean            gst_audio_encoder_set_output_format (GstAudioEncoder *enc,
                                                             GstCaps *caps);
    gboolean            gst_audio_encoder_negotiate         (GstAudioEncoder *enc);
    GstAudioInfo *      gst_audio_encoder_get_audio_info    (GstAudioEncoder *enc);
    gboolean            gst_audio_encoder_get_drainable     (GstAudioEncoder *enc);
    gint                gst_audio_encoder_get_frame_max     (GstAudioEncoder *enc);
    gint                gst_audio_encoder_get_frame_samples_min
                                                            (GstAudioEncoder *enc);
    gint                gst_audio_encoder_get_frame_samples_max
                                                            (GstAudioEncoder *enc);
    gboolean            gst_audio_encoder_get_hard_min      (GstAudioEncoder *enc);
    gboolean            gst_audio_encoder_get_hard_resync   (GstAudioEncoder *enc);
    void                gst_audio_encoder_get_latency       (GstAudioEncoder *enc,
                                                             GstClockTime *min,
                                                             GstClockTime *max);
    gint                gst_audio_encoder_get_lookahead     (GstAudioEncoder *enc);
    gboolean            gst_audio_encoder_get_mark_granule  (GstAudioEncoder *enc);
    gboolean            gst_audio_encoder_get_perfect_timestamp
                                                            (GstAudioEncoder *enc);
    GstClockTime        gst_audio_encoder_get_tolerance     (GstAudioEncoder *enc);
    GstCaps *           gst_audio_encoder_proxy_getcaps     (GstAudioEncoder *enc,
                                                             GstCaps *caps,
                                                             GstCaps *filter);
    void                gst_audio_encoder_set_drainable     (GstAudioEncoder *enc,
                                                             gboolean enabled);
    void                gst_audio_encoder_set_frame_max     (GstAudioEncoder *enc,
                                                             gint num);
    void                gst_audio_encoder_set_frame_samples_min
                                                            (GstAudioEncoder *enc,
                                                             gint num);
    void                gst_audio_encoder_set_frame_samples_max
                                                            (GstAudioEncoder *enc,
                                                             gint num);
    void                gst_audio_encoder_set_hard_min      (GstAudioEncoder *enc,
                                                             gboolean enabled);
    void                gst_audio_encoder_set_hard_resync   (GstAudioEncoder *enc,
                                                             gboolean enabled);
    void                gst_audio_encoder_set_headers       (GstAudioEncoder *enc,
                                                             GList *headers);
    void                gst_audio_encoder_set_latency       (GstAudioEncoder *enc,
                                                             GstClockTime min,
                                                             GstClockTime max);
    void                gst_audio_encoder_set_lookahead     (GstAudioEncoder *enc,
                                                             gint num);
    void                gst_audio_encoder_set_mark_granule  (GstAudioEncoder *enc,
                                                             gboolean enabled);
    void                gst_audio_encoder_set_perfect_timestamp
                                                            (GstAudioEncoder *enc,
                                                             gboolean enabled);
    void                gst_audio_encoder_set_tolerance     (GstAudioEncoder *enc,
                                                             GstClockTime tolerance);
    void                gst_audio_encoder_merge_tags        (GstAudioEncoder *enc,
                                                             const GstTagList *tags,
                                                             GstTagMergeMode mode);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GstObject
                   +----GstElement
                         +----GstAudioEncoder

## Implemented Interfaces

GstAudioEncoder implements GstPreset.

## Properties

      "hard-resync"              gboolean              : Read / Write
      "mark-granule"             gboolean              : Read
      "perfect-timestamp"        gboolean              : Read / Write
      "tolerance"                gint64                : Read / Write

## Description

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

GstAudioEncoder and subclass should cooperate as follows.

1. 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.

2. 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 `gst_audio_encoder_finish_frame` to have encoded data pushed downstream. Alternatively, it might also call 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.

3. 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 `gst_audio_encoder_finish_frame`.

## Details

### 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);
    };

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

GstElementClass `element_class`; | The parent class structure
`start` () | Optional. Called when the element starts processing. Allows opening external resources.
`stop` () | Optional. Called when the element stops processing. Allows closing external resources.
`set_format` () | Notifies subclass of incoming data format. GstAudioInfo contains the format according to provided caps.
`handle_frame` () | Provides input samples (or NULL 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 `gst_audio_encoder_finish_frame()`.
`flush` () | Optional. Instructs subclass to clear any codec caches and discard any pending samples and not yet returned encoded data.
`pre_push` () | 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.
`sink_event` () | Optional. Event handler on the sink pad. Subclasses should chain up to the parent implementation to invoke the default handler.
`src_event` () | Optional. Event handler on the src pad. Subclasses should chain up to the parent implementation to invoke the default handler.
`getcaps` () | Optional. Allows for a custom sink getcaps implementation (e.g. for multichannel input specification). If not implemented, default returns gst_audio_encoder_proxy_getcaps applied to sink template caps.
`open` () | Optional. Called when the element changes to GST_STATE_READY. Allows opening external resources.
`close` () | Optional. Called when the element changes to GST_STATE_NULL. Allows closing external resources.
`negotiate` () | Optional. Negotiate with downstream and configure buffer pools, etc. Subclasses should chain up to the parent implementation to invoke the default handler.
`decide_allocation` () | 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.
`propose_allocation` () | Optional. Propose buffer allocation parameters for upstream elements. Subclasses should chain up to the parent implementation to invoke the default handler.

### GST_AUDIO_ENCODER_SINK_NAME

    #define GST_AUDIO_ENCODER_SINK_NAME "sink"

the name of the templates for the sink pad

### 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.

`obj` : | audio encoder instance

### GST_AUDIO_ENCODER_SRC_NAME

    #define GST_AUDIO_ENCODER_SRC_NAME	        "src"

the name of the templates for the source pad

### 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.

`obj` : | audio encoder instance

### 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.

`enc` : | a GstAudioEncoder
`buffer` : | encoded data
`samples` : | number of samples (per channel) represented by encoded data
Returns : | a GstFlowReturn that should be escalated to caller (of caller)

### 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.

`enc` : | a GstAudioEncoder
`size` : | size of the buffer
Returns : | allocated buffer. [transfer full]

### 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.

`enc` : | a GstAudioEncoder
`allocator` : | the GstAllocator used. [out][allow-none][transfer full]
`params` : | the GstAllocatorParams of `allocator`. [out][allow-none][transfer full]

### gst_audio_encoder_set_output_format ()

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

### gst_audio_encoder_negotiate ()

    gboolean            gst_audio_encoder_negotiate         (GstAudioEncoder *enc);

Negotiate with downstreame elements to currently configured GstCaps.

`enc` : | a GstAudioEncoder
Returns : | TRUE if the negotiation succeeded, else FALSE.

### gst_audio_encoder_get_audio_info ()

    GstAudioInfo *      gst_audio_encoder_get_audio_info    (GstAudioEncoder *enc);

`enc` : | a GstAudioEncoder
Returns : | a GstAudioInfo describing the input audio format

### gst_audio_encoder_get_drainable ()

    gboolean            gst_audio_encoder_get_drainable     (GstAudioEncoder *enc);

Queries encoder drain handling.

`enc` : | a GstAudioEncoder
Returns : | TRUE if drainable handling is enabled. MT safe.

### gst_audio_encoder_get_frame_max ()

    gint                gst_audio_encoder_get_frame_max     (GstAudioEncoder *enc);

`enc` : | a GstAudioEncoder
Returns : | currently configured maximum handled frames

### gst_audio_encoder_get_frame_samples_min ()

    gint                gst_audio_encoder_get_frame_samples_min
                                                            (GstAudioEncoder *enc);

`enc` : | a GstAudioEncoder
Returns : | currently minimum requested samples per frame

### gst_audio_encoder_get_frame_samples_max ()

    gint                gst_audio_encoder_get_frame_samples_max
                                                            (GstAudioEncoder *enc);

`enc` : | a GstAudioEncoder
Returns : | currently maximum requested samples per frame

### gst_audio_encoder_get_hard_min ()

    gboolean            gst_audio_encoder_get_hard_min      (GstAudioEncoder *enc);

Queries encoder hard minimum handling.

`enc` : | a GstAudioEncoder
Returns : | TRUE if hard minimum handling is enabled. MT safe.

### 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.

`enc` : | a GstAudioEncoder
`min` : | a pointer to storage to hold minimum latency. [out][allow-none]
`max` : | a pointer to storage to hold maximum latency. [out][allow-none]

### gst_audio_encoder_get_lookahead ()

    gint                gst_audio_encoder_get_lookahead     (GstAudioEncoder *enc);

`enc` : | a GstAudioEncoder
Returns : | currently configured encoder lookahead

### gst_audio_encoder_get_mark_granule ()

    gboolean            gst_audio_encoder_get_mark_granule  (GstAudioEncoder *enc);

Queries if the encoder will handle granule marking.

`enc` : | a GstAudioEncoder
Returns : | TRUE if granule marking is enabled. MT safe.

### gst_audio_encoder_get_perfect_timestamp ()

    gboolean            gst_audio_encoder_get_perfect_timestamp
                                                            (GstAudioEncoder *enc);

Queries encoder perfect timestamp behaviour.

`enc` : | a GstAudioEncoder
Returns : | TRUE if perfect timestamp setting enabled. MT safe.

### gst_audio_encoder_get_tolerance ()

    GstClockTime        gst_audio_encoder_get_tolerance     (GstAudioEncoder *enc);

Queries current audio jitter tolerance threshold.

`enc` : | a GstAudioEncoder
Returns : | encoder audio jitter tolerance threshold. MT safe.

### 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).

`enc` : | a GstAudioEncoder
`caps` : | initial caps
`filter` : | filter caps
Returns : | a GstCaps owned by caller

### 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.

`enc` : | a GstAudioEncoder
`enabled` : | new state

### 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.

`enc` : | a GstAudioEncoder
`num` : | number of frames

### 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.

`enc` : | a GstAudioEncoder
`num` : | number of samples per frame

### 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.

`enc` : | a GstAudioEncoder
`num` : | number of samples per frame

### 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.

`enc` : | a GstAudioEncoder
`enabled` : | new state

### 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.

`enc` : | a GstAudioEncoder
`headers` : | a list of GstBuffer containing the codec header. [transfer full][element-type Gst.Buffer]

### gst_audio_encoder_set_latency ()

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

Sets encoder latency.

`enc` : | a GstAudioEncoder
`min` : | minimum latency
`max` : | maximum 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)

`enc` : | a GstAudioEncoder
`num` : | lookahead

### 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.

`enc` : | a GstAudioEncoder
`enabled` : | new state

### 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.

`enc` : | a GstAudioEncoder
`enabled` : | new state

### gst_audio_encoder_set_tolerance ()

    void                gst_audio_encoder_set_tolerance     (GstAudioEncoder *enc,
                                                             GstClockTime tolerance);

Configures encoder audio jitter tolerance threshold.

MT safe.

`enc` : | a GstAudioEncoder
`tolerance` : | new tolerance

### gst_audio_encoder_merge_tags ()

    void                gst_audio_encoder_merge_tags        (GstAudioEncoder *enc,
                                                             const GstTagList *tags,
                                                             GstTagMergeMode mode);

Adds tags to so-called pending tags, which will be processed before pushing out data downstream.

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, although it should be aware that baseclass already takes care of the usual CODEC/AUDIO_CODEC tags.

MT safe.

`enc` : | a GstAudioEncoder
`tags` : | a GstTagList to merge
`mode` : | the GstTagMergeMode to use

## Property Details

### The `"hard-resync"` property

      "hard-resync"              gboolean              : Read / Write

Perform clipping and sample flushing upon discontinuity.

Default value: FALSE

### The `"mark-granule"` property

      "mark-granule"             gboolean              : Read

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

Default value: FALSE

### The `"perfect-timestamp"` property

      "perfect-timestamp"        gboolean              : Read / Write

Favour perfect timestamps over tracking upstream timestamps.

Default value: FALSE

### The `"tolerance"` property

      "tolerance"                gint64                : Read / Write

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

Allowed values: >= 0

Default value: 40000000

## See Also

GstBaseTransform