GstAudioConverter: GStreamer Base Plugins 1.0 Library Reference Manual

## GstAudioConverter GstAudioConverter — Generic audio conversion |

## Functions

GstAudioConverter * | gst_audio_converter_new ()
void | gst_audio_converter_free ()
gboolean | gst_audio_converter_samples ()
gboolean | gst_audio_converter_convert ()
gsize | gst_audio_converter_get_in_frames ()
gsize | gst_audio_converter_get_max_latency ()
gsize | gst_audio_converter_get_out_frames ()
gboolean | gst_audio_converter_update_config ()
const GstStructure * | gst_audio_converter_get_config ()
void | gst_audio_converter_reset ()
gboolean | gst_audio_converter_supports_inplace ()
gboolean | gst_audio_converter_is_passthrough ()

## Types and Values

| GstAudioConverter
enum | GstAudioConverterFlags
#define | GST_AUDIO_CONVERTER_OPT_DITHER_METHOD
#define | GST_AUDIO_CONVERTER_OPT_NOISE_SHAPING_METHOD
#define | GST_AUDIO_CONVERTER_OPT_QUANTIZATION
#define | GST_AUDIO_CONVERTER_OPT_MIX_MATRIX
#define | GST_AUDIO_CONVERTER_OPT_RESAMPLER_METHOD

## Includes

    #include <gst/audio/audio.h>

## Description

This object is used to convert audio samples from one format to another. The object can perform conversion of:

- audio format with optional dithering and noise shaping

- audio samplerate

- audio channels and channel layout

## Functions

### gst_audio_converter_new ()

    GstAudioConverter *
    gst_audio_converter_new (GstAudioConverterFlags flags,
                             GstAudioInfo *in_info,
                             GstAudioInfo *out_info,
                             GstStructure *config);

Create a new GstAudioConverter that is able to convert between `in` and `out` audio formats.

`config` contains extra configuration options, see GST_AUDIO_CONVERTER_OPT_* parameters for details about the options and values.

#### Parameters

flags | extra GstAudioConverterFlags |
in_info | a source GstAudioInfo |
out_info | a destination GstAudioInfo |
config | a GstStructure with configuration options. | [transfer full][nullable]

#### Returns

a GstAudioConverter or `NULL` if conversion is not possible.

### gst_audio_converter_free ()

    void
    gst_audio_converter_free (GstAudioConverter *convert);

Free a previously allocated `convert` instance.

#### Parameters

convert | a GstAudioConverter |

### gst_audio_converter_samples ()

    gboolean
    gst_audio_converter_samples (GstAudioConverter *convert,
                                 GstAudioConverterFlags flags,
                                 gpointer in[],
                                 gsize in_frames,
                                 gpointer out[],
                                 gsize out_frames);

Perform the conversion with `in_frames` in `in` to `out_frames` in `out` using `convert` .

In case the samples are interleaved, `in` and `out` must point to an array with a single element pointing to a block of interleaved samples.

If non-interleaved samples are used, `in` and `out` must point to an array with pointers to memory blocks, one for each channel.

`in` may be `NULL`, in which case `in_frames` of silence samples are processed by the converter.

This function always produces `out_frames` of output and consumes `in_frames` of input. Use `gst_audio_converter_get_out_frames()` and `gst_audio_converter_get_in_frames()` to make sure `in_frames` and `out_frames` are matching and `in` and `out` point to enough memory.

#### Parameters

convert | a GstAudioConverter |
flags | extra GstAudioConverterFlags |
in | input frames |
in_frames | number of input frames |
out | output frames |
out_frames | number of output frames |

#### Returns

`TRUE` is the conversion could be performed.

### gst_audio_converter_convert ()

    gboolean
    gst_audio_converter_convert (GstAudioConverter *convert,
                                 GstAudioConverterFlags flags,
                                 gpointer in,
                                 gsize in_size,
                                 gpointer *out,
                                 gsize *out_size);

Convenience wrapper around `gst_audio_converter_samples()`, which will perform allocation of the output buffer based on the result from `gst_audio_converter_get_out_frames()`.

#### Parameters

convert | a GstAudioConverter |
flags | extra GstAudioConverterFlags |
in | input data. | [array length=in_size][element-type guint8]
in_size | size of `in` |
out | a pointer where the output data will be written. | [out][array length=out_size][element-type guint8]
out_size | a pointer where the size of `out` will be written. | [out]

#### Returns

`TRUE` is the conversion could be performed.

Since: 1.14

### gst_audio_converter_get_in_frames ()

    gsize
    gst_audio_converter_get_in_frames (GstAudioConverter *convert,
                                       gsize out_frames);

Calculate how many input frames are currently needed by `convert` to produce `out_frames` of output frames.

#### Parameters

convert | a GstAudioConverter |
out_frames | number of output frames |

#### Returns

the number of input frames

### gst_audio_converter_get_max_latency ()

    gsize
    gst_audio_converter_get_max_latency (GstAudioConverter *convert);

Get the maximum number of input frames that the converter would need before producing output.

#### Parameters

convert | a GstAudioConverter |

#### Returns

the latency of `convert` as expressed in the number of frames.

### gst_audio_converter_get_out_frames ()

    gsize
    gst_audio_converter_get_out_frames (GstAudioConverter *convert,
                                        gsize in_frames);

Calculate how many output frames can be produced when `in_frames` input frames are given to `convert` .

#### Parameters

convert | a GstAudioConverter |
in_frames | number of input frames |

#### Returns

the number of output frames

### gst_audio_converter_update_config ()

    gboolean
    gst_audio_converter_update_config (GstAudioConverter *convert,
                                       gint in_rate,
                                       gint out_rate,
                                       GstStructure *config);

Set `in_rate` , `out_rate` and `config` as extra configuration for `convert` .

`in_rate` and `out_rate` specify the new sample rates of input and output formats. A value of 0 leaves the sample rate unchanged.

`config` can be `NULL`, in which case, the current configuration is not changed.

If the parameters in `config` can not be set exactly, this function returns `FALSE` and will try to update as much state as possible. The new state can then be retrieved and refined with `gst_audio_converter_get_config()`.

Look at the GST_AUDIO_CONVERTER_OPT_* fields to check valid configuration option and values.

#### Parameters

convert | a GstAudioConverter |
in_rate | input rate |
out_rate | output rate |
config | a GstStructure or `NULL`. | [transfer full][allow-none]

#### Returns

`TRUE` when the new parameters could be set

### gst_audio_converter_get_config ()

    const GstStructure *
    gst_audio_converter_get_config (GstAudioConverter *convert,
                                    gint *in_rate,
                                    gint *out_rate);

Get the current configuration of `convert` .

#### Parameters

convert | a GstAudioConverter |
in_rate | result input rate. | [out][optional]
out_rate | result output rate. | [out][optional]

#### Returns

a GstStructure that remains valid for as long as `convert` is valid or until `gst_audio_converter_update_config()` is called.

[transfer none]

### gst_audio_converter_reset ()

    void
    gst_audio_converter_reset (GstAudioConverter *convert);

Reset `convert` to the state it was when it was first created, clearing any history it might currently have.

#### Parameters

convert | a GstAudioConverter |

### gst_audio_converter_supports_inplace ()

    gboolean
    gst_audio_converter_supports_inplace (GstAudioConverter *convert);

Returns whether the audio converter can perform the conversion in-place. The return value would be typically input to `gst_base_transform_set_in_place()`

#### Parameters

convert | a GstAudioConverter |

#### Returns

`TRUE` when the conversion can be done in place.

### gst_audio_converter_is_passthrough ()

    gboolean
    gst_audio_converter_is_passthrough (GstAudioConverter *convert);

Returns whether the audio converter will operate in passthrough mode. The return value would be typically input to `gst_base_transform_set_passthrough()`

#### Returns

`TRUE` when no conversion will actually occur.

Since: 1.16

## Types and Values

### GstAudioConverter

    typedef struct _GstAudioConverter GstAudioConverter;

### enum GstAudioConverterFlags

Extra flags passed to `gst_audio_converter_new()` and `gst_audio_converter_samples()`.

#### Members

GST_AUDIO_CONVERTER_FLAG_NONE | no flag |
GST_AUDIO_CONVERTER_FLAG_IN_WRITABLE | the input sample arrays are writable and can be used as temporary storage during conversion. |
GST_AUDIO_CONVERTER_FLAG_VARIABLE_RATE | allow arbitrary rate updates with `gst_audio_converter_update_config()`. |

### GST_AUDIO_CONVERTER_OPT_DITHER_METHOD

    #define GST_AUDIO_CONVERTER_OPT_DITHER_METHOD   "GstAudioConverter.dither-method"

GST_TYPE_AUDIO_DITHER_METHOD, The dither method to use when changing bit depth. Default is GST_AUDIO_DITHER_NONE.

### GST_AUDIO_CONVERTER_OPT_NOISE_SHAPING_METHOD

    #define GST_AUDIO_CONVERTER_OPT_NOISE_SHAPING_METHOD   "GstAudioConverter.noise-shaping-method"

GST_TYPE_AUDIO_NOISE_SHAPING_METHOD, The noise shaping method to use to mask noise from quantization errors. Default is GST_AUDIO_NOISE_SHAPING_NONE.

### GST_AUDIO_CONVERTER_OPT_QUANTIZATION

    #define GST_AUDIO_CONVERTER_OPT_QUANTIZATION   "GstAudioConverter.quantization"

G_TYPE_UINT, The quantization amount. Components will be quantized to multiples of this value. Default is 1

### GST_AUDIO_CONVERTER_OPT_MIX_MATRIX

    #define GST_AUDIO_CONVERTER_OPT_MIX_MATRIX   "GstAudioConverter.mix-matrix"

GST_TYPE_VALUE_LIST, The channel mapping matrix.

The matrix coefficients must be between -1 and 1: the number of rows is equal to the number of output channels and the number of columns is equal to the number of input channels.

#### Example matrix generation code

To generate the matrix using code:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    GValue v = G_VALUE_INIT;
    GValue v2 = G_VALUE_INIT;
    GValue v3 = G_VALUE_INIT;

    g_value_init (&v2, GST_TYPE_ARRAY);
    g_value_init (&v3, G_TYPE_DOUBLE);
    g_value_set_double (&v3, 1);
    gst_value_array_append_value (&v2, &v3);
    g_value_unset (&v3);
    [ Repeat for as many double as your input channels - unset and reinit v3 ]
    g_value_init (&v, GST_TYPE_ARRAY);
    gst_value_array_append_value (&v, &v2);
    g_value_unset (&v2);
    [ Repeat for as many v2's as your output channels - unset and reinit v2]
    g_object_set_property (G_OBJECT (audiomixmatrix), "matrix", &v);
    g_value_unset (&v);

### GST_AUDIO_CONVERTER_OPT_RESAMPLER_METHOD

    #define GST_AUDIO_CONVERTER_OPT_RESAMPLER_METHOD   "GstAudioConverter.resampler-method"

GST_TYPE_AUDIO_RESAMPLER_METHOD, The resampler method to use when changing sample rates. Default is GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL.