Audio-channels: GStreamer Base Plugins Library Reference Manual

## Audio-channels Audio-channels — Support library for audio channel handling |

## Functions

#define | GST_AUDIO_CHANNEL_POSITION_MASK()
gboolean | gst_audio_channel_positions_to_mask ()
gboolean | gst_audio_channel_positions_from_mask ()
gboolean | gst_audio_channel_positions_to_valid_order ()
guint64 | gst_audio_channel_get_fallback_mask ()
gboolean | gst_audio_check_valid_channel_positions ()
gboolean | gst_audio_buffer_reorder_channels ()
gboolean | gst_audio_reorder_channels ()
gboolean | gst_audio_get_channel_reorder_map ()
gchar * | gst_audio_channel_positions_to_string ()
GstAudioChannelMixer * | gst_audio_channel_mixer_new ()
GstAudioChannelMixer * | gst_audio_channel_mixer_new_with_matrix ()
void | gst_audio_channel_mixer_free ()
gboolean | gst_audio_channel_mixer_is_passthrough ()
void | gst_audio_channel_mixer_samples ()

## Types and Values

enum | GstAudioChannelPosition
| GstAudioChannelMixer
enum | GstAudioChannelMixerFlags

## Includes

    #include <gst/audio/audio.h>

## Description

This library contains some helper functions for multichannel audio.

## Functions

### GST_AUDIO_CHANNEL_POSITION_MASK()

    #define GST_AUDIO_CHANNEL_POSITION_MASK(pos) (G_GUINT64_CONSTANT(1)<< GST_AUDIO_CHANNEL_POSITION_ ## pos)

### gst_audio_channel_positions_to_mask ()

    gboolean
    gst_audio_channel_positions_to_mask (const GstAudioChannelPosition *position,
                                         gint channels,
                                         gboolean force_order,
                                         guint64 *channel_mask);

Convert the `position` array of `channels` channels to a bitmask.

If `force_order` is `TRUE` it additionally checks if the channels are in the order required by GStreamer.

#### Parameters

position | The `GstAudioChannelPositions`. | [array length=channels]
channels | The number of channels. |
force_order | Only consider the GStreamer channel order. |
channel_mask | the output channel mask. | [out]

#### Returns

`TRUE` if the channel positions are valid and could be converted.

### gst_audio_channel_positions_from_mask ()

    gboolean
    gst_audio_channel_positions_from_mask (gint channels,
                                           guint64 channel_mask,
                                           GstAudioChannelPosition *position);

Convert the `channels` present in `channel_mask` to a `position` array (which should have at least `channels` entries ensured by caller). If `channel_mask` is set to 0, it is considered as 'not present' for purpose of conversion. A partially valid `channel_mask` with less bits set than the number of channels is considered valid.

#### Parameters

channels | The number of channels |
channel_mask | The input channel_mask |
position | The `GstAudioChannelPosition`s. | [array length=channels]

#### Returns

`TRUE` if channel and channel mask are valid and could be converted

### gst_audio_channel_positions_to_valid_order ()

    gboolean
    gst_audio_channel_positions_to_valid_order
                                   (GstAudioChannelPosition *position,
                                    gint channels);

Reorders the channel positions in `position` from any order to the GStreamer channel order.

#### Parameters

position | The channel positions to reorder to. | [array length=channels]
channels | The number of channels. |

#### Returns

`TRUE` if the channel positions are valid and reordering was successful.

### gst_audio_channel_get_fallback_mask ()

    guint64
    gst_audio_channel_get_fallback_mask (gint channels);

Get the fallback channel-mask for the given number of channels.

This function returns a reasonable fallback channel-mask and should be called as a last resort when the specific channel map is unknown.

#### Parameters

channels | the number of channels |

#### Returns

a fallback channel-mask for `channels` or 0 when there is no mask and mono.

Since: 1.8

### gst_audio_check_valid_channel_positions ()

    gboolean
    gst_audio_check_valid_channel_positions
                                   (const GstAudioChannelPosition *position,
                                    gint channels,
                                    gboolean force_order);

Checks if `position` contains valid channel positions for `channels` channels. If `force_order` is `TRUE` it additionally checks if the channels are in the order required by GStreamer.

#### Parameters

position | The `GstAudioChannelPositions` to check. | [array length=channels]
channels | The number of channels. |
force_order | Only consider the GStreamer channel order. |

#### Returns

`TRUE` if the channel positions are valid.

### gst_audio_buffer_reorder_channels ()

    gboolean
    gst_audio_buffer_reorder_channels (GstBuffer *buffer,
                                       GstAudioFormat format,
                                       gint channels,
                                       const GstAudioChannelPosition *from,
                                       const GstAudioChannelPosition *to);

Reorders `buffer` from the channel positions `from` to the channel positions `to` . `from` and `to` must contain the same number of positions and the same positions, only in a different order. `buffer` must be writable.

#### Parameters

buffer | The buffer to reorder. |
format | The `GstAudioFormat` of the buffer. |
channels | The number of channels. |
from | The channel positions in the buffer. | [array length=channels]
to | The channel positions to convert to. | [array length=channels]

#### Returns

`TRUE` if the reordering was possible.

### gst_audio_reorder_channels ()

    gboolean
    gst_audio_reorder_channels (gpointer data,
                                gsize size,
                                GstAudioFormat format,
                                gint channels,
                                const GstAudioChannelPosition *from,
                                const GstAudioChannelPosition *to);

Reorders `data` from the channel positions `from` to the channel positions `to` . `from` and `to` must contain the same number of positions and the same positions, only in a different order.

Note: this function assumes the audio data is in interleaved layout

#### Parameters

data | The pointer to the memory. | [array length=size][element-type guint8]
size | The size of the memory. |
format | The `GstAudioFormat` of the buffer. |
channels | The number of channels. |
from | The channel positions in the buffer. | [array length=channels]
to | The channel positions to convert to. | [array length=channels]

#### Returns

`TRUE` if the reordering was possible.

### gst_audio_get_channel_reorder_map ()

    gboolean
    gst_audio_get_channel_reorder_map (gint channels,
                                       const GstAudioChannelPosition *from,
                                       const GstAudioChannelPosition *to,
                                       gint *reorder_map);

Returns a reorder map for `from` to `to` that can be used in custom channel reordering code, e.g. to convert from or to the GStreamer channel order. `from` and `to` must contain the same number of positions and the same positions, only in a different order.

The resulting `reorder_map` can be used for reordering by assigning channel i of the input to channel reorder_map[i] of the output.

#### Parameters

channels | The number of channels. |
from | The channel positions to reorder from. | [array length=channels]
to | The channel positions to reorder to. | [array length=channels]
reorder_map | Pointer to the reorder map. | [array length=channels]

#### Returns

`TRUE` if the channel positions are valid and reordering is possible.

### gst_audio_channel_positions_to_string ()

    gchar *
    gst_audio_channel_positions_to_string (const GstAudioChannelPosition *position,
                                           gint channels);

Converts `position` to a human-readable string representation for debugging purposes.

#### Parameters

position | The `GstAudioChannelPositions` to convert. | [array length=channels]
channels | The number of channels. |

#### Returns

a newly allocated string representing `position` .

[transfer full]

Since: 1.10

### gst_audio_channel_mixer_new ()

    GstAudioChannelMixer *
    gst_audio_channel_mixer_new (GstAudioChannelMixerFlags flags,
                                 GstAudioFormat format,
                                 gint in_channels,
                                 GstAudioChannelPosition *in_position,
                                 gint out_channels,
                                 GstAudioChannelPosition *out_position);

### gst_audio_channel_mixer_new_with_matrix ()

    GstAudioChannelMixer *
    gst_audio_channel_mixer_new_with_matrix
                                   (GstAudioChannelMixerFlags flags,
                                    GstAudioFormat format,
                                    gint in_channels,
                                    gint out_channels,
                                    gfloat **matrix);

### gst_audio_channel_mixer_free ()

    void
    gst_audio_channel_mixer_free (GstAudioChannelMixer *mix);

Free memory allocated by `mix` .

#### Parameters

mix | a GstAudioChannelMixer |

### gst_audio_channel_mixer_is_passthrough ()

    gboolean
    gst_audio_channel_mixer_is_passthrough
                                   (GstAudioChannelMixer *mix);

Check if `mix` is in passthrough.

Only N x N mix identity matrices are considered passthrough, this is determined by comparing the contents of the matrix with 0.0 and 1.0.

As this is floating point comparisons, if the values have been generated, they should be rounded up or down by explicit assignment of 0.0 or 1.0 to values within a user-defined epsilon, this code doesn't make assumptions as to what may constitute an appropriate epsilon.

#### Parameters

mix | a GstAudioChannelMixer |

#### Returns

`TRUE` is `mix` is passthrough.

### gst_audio_channel_mixer_samples ()

    void
    gst_audio_channel_mixer_samples (GstAudioChannelMixer *mix,
                                     const gpointer in[],
                                     gpointer out[],
                                     gint samples);

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.

Perform channel mixing on `in_data` and write the result to `out_data` . `in_data` and `out_data` need to be in `format` and `layout` .

#### Parameters

mix | a GstAudioChannelMixer |
in | input samples |
out | output samples |
samples | number of samples |

## Types and Values

### enum GstAudioChannelPosition

Audio channel positions.

These are the channels defined in SMPTE 2036-2-2008 Table 1 for 22.2 audio systems with the Surround and Wide channels from DTS Coherent Acoustics (v.1.3.1) and 10.2 and 7.1 layouts. In the caps the actual channel layout is expressed with a channel count and a channel mask, which describes the existing channels. The positions in the bit mask correspond to the enum values. For negotiation it is allowed to have more bits set in the channel mask than the number of channels to specify the allowed channel positions but this is not allowed in negotiated caps. It is not allowed in any situation other than the one mentioned below to have less bits set in the channel mask than the number of channels.

`GST_AUDIO_CHANNEL_POSITION_MONO` can only be used with a single mono channel that has no direction information and would be mixed into all directional channels. This is expressed in caps by having a single channel and no channel mask.

`GST_AUDIO_CHANNEL_POSITION_NONE` can only be used if all channels have this position. This is expressed in caps by having a channel mask with no bits set.

As another special case it is allowed to have two channels without a channel mask. This implicitely means that this is a stereo stream with a front left and front right channel.

#### Members

GST_AUDIO_CHANNEL_POSITION_NONE | used for position-less channels, e.g. from a sound card that records 1024 channels; mutually exclusive with any other channel position |
GST_AUDIO_CHANNEL_POSITION_MONO | Mono without direction; can only be used with 1 channel |
GST_AUDIO_CHANNEL_POSITION_INVALID | invalid position |
GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT | Front left |
GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT | Front right |
GST_AUDIO_CHANNEL_POSITION_FRONT_CENTER | Front center |
GST_AUDIO_CHANNEL_POSITION_LFE1 | Low-frequency effects 1 (subwoofer) |
GST_AUDIO_CHANNEL_POSITION_REAR_LEFT | Rear left |
GST_AUDIO_CHANNEL_POSITION_REAR_RIGHT | Rear right |
GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER | Front left of center |
GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER | Front right of center |
GST_AUDIO_CHANNEL_POSITION_REAR_CENTER | Rear center |
GST_AUDIO_CHANNEL_POSITION_LFE2 | Low-frequency effects 2 (subwoofer) |
GST_AUDIO_CHANNEL_POSITION_SIDE_LEFT | Side left |
GST_AUDIO_CHANNEL_POSITION_SIDE_RIGHT | Side right |
GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_LEFT | Top front left |
GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_RIGHT | Top front right |
GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_CENTER | Top front center |
GST_AUDIO_CHANNEL_POSITION_TOP_CENTER | Top center |
GST_AUDIO_CHANNEL_POSITION_TOP_REAR_LEFT | Top rear left |
GST_AUDIO_CHANNEL_POSITION_TOP_REAR_RIGHT | Top rear right |
GST_AUDIO_CHANNEL_POSITION_TOP_SIDE_LEFT | Top side right |
GST_AUDIO_CHANNEL_POSITION_TOP_SIDE_RIGHT | Top rear right |
GST_AUDIO_CHANNEL_POSITION_TOP_REAR_CENTER | Top rear center |
GST_AUDIO_CHANNEL_POSITION_BOTTOM_FRONT_CENTER | Bottom front center |
GST_AUDIO_CHANNEL_POSITION_BOTTOM_FRONT_LEFT | Bottom front left |
GST_AUDIO_CHANNEL_POSITION_BOTTOM_FRONT_RIGHT | Bottom front right |
GST_AUDIO_CHANNEL_POSITION_WIDE_LEFT | Wide left (between front left and side left) |
GST_AUDIO_CHANNEL_POSITION_WIDE_RIGHT | Wide right (between front right and side right) |
GST_AUDIO_CHANNEL_POSITION_SURROUND_LEFT | Surround left (between rear left and side left) |
GST_AUDIO_CHANNEL_POSITION_SURROUND_RIGHT | Surround right (between rear right and side right) |

### GstAudioChannelMixer

    typedef struct _GstAudioChannelMixer GstAudioChannelMixer;

### enum GstAudioChannelMixerFlags

Flags passed to `gst_audio_channel_mixer_new()`

#### Members

GST_AUDIO_CHANNEL_MIXER_FLAGS_NONE | no flag |
GST_AUDIO_CHANNEL_MIXER_FLAGS_NON_INTERLEAVED_IN | input channels are not interleaved |
GST_AUDIO_CHANNEL_MIXER_FLAGS_NON_INTERLEAVED_OUT | output channels are not interleaved |
GST_AUDIO_CHANNEL_MIXER_FLAGS_UNPOSITIONED_IN | input channels are explicitly unpositioned |
GST_AUDIO_CHANNEL_MIXER_FLAGS_UNPOSITIONED_OUT | output channels are explicitly unpositioned |