audioconvert

Audioconvert converts raw audio buffers between various possible formats. It supports integer to float conversion, width/depth conversion, signedness and endianness conversion and channel transformations (ie. upmixing and downmixing), as well as dithering and noise-shaping.

Example launch line

 gst-launch-1.0 -v -m audiotestsrc ! audioconvert ! audio/x-raw,format=S8,channels=2 ! level ! fakesink silent=TRUE

This pipeline converts audio to 8-bit. The level element shows that the output levels still match the one for a sine wave.

 gst-launch-1.0 -v -m uridecodebin uri=file:///path/to/audio.flac ! audioconvert ! vorbisenc ! oggmux ! filesink location=audio.ogg

The vorbis encoder takes float audio data instead of the integer data output by most other audio elements. This pipeline decodes a FLAC audio file (or any other audio file for which decoders are installed) and re-encodes it into an Ogg/Vorbis audio file.

A mix matrix can be passed to audioconvert, that will govern the remapping of input to output channels. This is required if the input channels are unpositioned and no standard layout can be determined. If an empty mix matrix is specified, a (potentially truncated) identity matrix will be generated.

Example matrix generation code

To generate the matrix using code:

 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_FLOAT);
 g_value_set_float (&v3, 1);
 gst_value_array_append_value (&v2, &v3);
 g_value_unset (&v3);
 [ Repeat for as many float 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 (audioconvert), "mix-matrix", &v);
 g_value_unset (&v);

Example launch line

 gst-launch-1.0 audiotestsrc ! audio/x-raw, channels=4 ! audioconvert mix-matrix="<<(float)1.0, (float)0.0, (float)0.0, (float)0.0>, <(float)0.0, (float)1.0, (float)0.0, (float)0.0>>" ! audio/x-raw,channels=2 ! autoaudiosink

Example empty matrix generation code

 GValue v = G_VALUE_INIT;

 g_value_init (&v, GST_TYPE_ARRAY);
 g_object_set_property (G_OBJECT (audioconvert), "mix-matrix", &v);
 g_value_unset (&v);

Example empty matrix launch line

 gst-launch-1.0 -v audiotestsrc ! audio/x-raw,channels=8 ! audioconvert mix-matrix="<>" ! audio/x-raw,channels=16,channel-mask=\(bitmask\)0x0000000000000000 ! fakesink

If input channels are unpositioned but follow a standard layout, they can be automatically positioned according to their index using one of the reorder configurations.

Example with unpositioned input channels reordering

 gst-launch-1.0 -v audiotestsrc ! audio/x-raw,channels=6,channel-mask=\(bitmask\)0x0000000000000000 ! audioconvert input-channels-reorder-mode=unpositioned input-channels-reorder=smpte ! fakesink

In this case the input channels will be automatically positioned to the SMPTE order (left, right, center, lfe, rear-left and rear-right).

The input channels reorder configurations can also be used to force the repositioning of the input channels when needed, for example when channels' positions are not correctly identified in an encoded file.

Example with the forced reordering of input channels wrongly positioned

 gst-launch-1.0 -v audiotestsrc ! audio/x-raw,channels=3,channel-mask=\(bitmask\)0x0000000000000034 ! audioconvert input-channels-reorder-mode=force input-channels-reorder=aac ! fakesink

In this case the input channels are positioned upstream as center, rear-left and rear-right in this order. Using the "force" reorder mode and the "aac" order, the input channels are going to be repositioned to left, right and lfe, ignoring the actual value of the channel-mask in the input caps.

Hierarchy

GObject
    ╰──GInitiallyUnowned
        ╰──GstObject
            ╰──GstElement
                ╰──GstBaseTransform
                    ╰──audioconvert

Factory details

Authors: – Benjamin Otte

Classification: – Filter/Converter/Audio

Rank – primary

Plugin – audioconvert

Package – GStreamer Base Plug-ins

Pad Templates

`sink`

audio/x-raw:
         format: { F64LE, F64BE, F32LE, F32BE, S32LE, S32BE, U32LE, U32BE, S24_32LE, S24_32BE, U24_32LE, U24_32BE, S24LE, S24BE, U24LE, U24BE, S20LE, S20BE, U20LE, U20BE, S18LE, S18BE, U18LE, U18BE, S16LE, S16BE, U16LE, U16BE, S8, U8 }
           rate: [ 1, 2147483647 ]
       channels: [ 1, 2147483647 ]
         layout: { (string)interleaved, (string)non-interleaved }

Presence – always

Direction – sink

Object type – GstPad

`src`

audio/x-raw:
         format: { F64LE, F64BE, F32LE, F32BE, S32LE, S32BE, U32LE, U32BE, S24_32LE, S24_32BE, U24_32LE, U24_32BE, S24LE, S24BE, U24LE, U24BE, S20LE, S20BE, U20LE, U20BE, S18LE, S18BE, U18LE, U18BE, S16LE, S16BE, U16LE, U16BE, S8, U8 }
           rate: [ 1, 2147483647 ]
       channels: [ 1, 2147483647 ]
         layout: { (string)interleaved, (string)non-interleaved }

Presence – always

Direction – src

Object type – GstPad

Properties

dithering

“dithering” GstAudioDitherMethod *

Selects between different dithering methods.

Flags : Read / Write

Default value : tpdf (2)

dithering-threshold

“dithering-threshold” guint

Threshold for the output bit depth at/below which to apply dithering.

Flags : Read / Write

Default value : 20

Since : 1.22

input-channels-reorder

“input-channels-reorder” GstAudioConvertInputChannelsReorder *

The positions configuration to use to reorder the input channels consecutively according to their index. If a mix-matrix is specified, this configuration is ignored.

When the input channels reordering is activated (because the input-channels-reorder-mode property is GST_AUDIO_CONVERT_INPUT_CHANNELS_REORDER_MODE_FORCE or the input channels are unpositioned and the reorder mode is GST_AUDIO_CONVERT_INPUT_CHANNELS_REORDER_MODE_UNPOSITIONED), input channels will be reordered consecutively according to their index independently of the channel-mask value in the sink pad audio caps.

Flags : Read / Write

Default value : gst (0)

Since : 1.26

input-channels-reorder-mode

“input-channels-reorder-mode” GstAudioConvertInputChannelsReorderMode *

The input channels reordering mode used to apply the selected positions configuration.

Flags : Read / Write

Default value : none (0)

Since : 1.26

mix-matrix

“mix-matrix” GstValueArray *

Transformation matrix for input/output channels. Required if the input channels are unpositioned and no standard layout can be determined. Setting an empty matrix like "< >" will generate an identity matrix."

Flags : Read / Write

noise-shaping

“noise-shaping” GstAudioNoiseShapingMethod *

Selects between different noise shaping methods.

Flags : Read / Write

Default value : none (0)

Named constants

GstAudioConvertInputChannelsReorder

Input audio channels reordering configurations.

It defines different ways of reordering input audio channels when they are not positioned by GStreamer. As a general matter, channels are always ordered in the GST_AUDIO_CONVERT_INPUT_CHANNELS_REORDER_GST order and the channel-mask field in the audio caps allows specifying which channels are active.

Depending on the selected mode (see: GST_AUDIO_CONVERT_INPUT_CHANNELS_REORDER_MODE_UNPOSITIONED), input channels can be automatically positioned when the channel-mask is not specified or equals 0. In this case, all input channels will be positioned according to the selected reordering configuration and the index of each input channel. This can be useful when importing audio from an array of independent microphones for example.

The reordering configuration can also be forced (see: GST_AUDIO_CONVERT_INPUT_CHANNELS_REORDER_MODE_FORCE) to reposition all input channels according to each channel index. In this case the channel-mask will be totally ignored and input channels will be reordered just like if they were unpositioned. This can be useful when importing multi-channels audio with errors in the channels positioning.

For any of the former configurations, when the reordering is applied (input channels are unpositioned or the "force" mode is active):

When there is only one input channel available, it is positioned to MONO always, independently of the selected configuration.
When there are 2 input channels available, they are positioned to FRONT_LEFT and FRONT_RIGHT (except for the GST_AUDIO_CONVERT_INPUT_CHANNELS_REORDER_MONO configuration where all input channels are positioned to MONO).

Members

gst (0) – Reorder the input channels using the default GStreamer order

smpte (1) – Reorder the input channels using the SMPTE order

cine (2) – Reorder the input channels using the CINE order

ac3 (3) – Reorder the input channels using the AC3 order

aac (4) – Reorder the input channels using the AAC order

mono (5) – Reorder and mix all input channels to a single mono channel

alternate (6) – Reorder and mix all input channels to a single left and a single right stereo channels alternately

Since : 1.26

GstAudioConvertInputChannelsReorderMode

The different usage modes of the input channels reordering configuration.

Independently of the selected mode, the explicit definition of a mix matrix takes precedence over the reorder configuration. In this case, the provided mix matrix will override the reorder configuration.

Members

none (0) – Never reorder the input channels

unpositioned (1) – Reorder the input channels only if they are unpositioned

force (2) – Always reorder the input channels according to the selected configuration

Since : 1.26

The results of the search are