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

The mix matrix can also be passed through a custom upstream event:

 GstStructure *s = gst_structure_new("GstRequestAudioMixMatrix", "matrix", GST_TYPE_ARRAY, &v, NULL);
 GstEvent *event = gst_event_new_custom (GST_EVENT_CUSTOM_UPSTREAM, s);
 GstPad *srcpad = gst_element_get_static_pad(audioconvert, "src");
 gst_pad_send_event (srcpad, event);
 gst_object_unref (pad);

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.