gstaudiochannels

gstaudiochannels — Support library for audio channel handling

Synopsis

#include <gst/audio/audio.h>

enum                GstAudioChannelPosition;
#define             GST_AUDIO_CHANNEL_POSITION_MASK     (pos)
gboolean            gst_audio_channel_positions_to_mask (const GstAudioChannelPosition *position,
                                                         gint channels,
                                                         gboolean force_order,
                                                         guint64 *channel_mask);
gboolean            gst_audio_channel_positions_from_mask
                                                        (gint channels,
                                                         guint64 channel_mask,
                                                         GstAudioChannelPosition *position);
gboolean            gst_audio_channel_positions_to_valid_order
                                                        (GstAudioChannelPosition *position,
                                                         gint channels);
guint64             gst_audio_channel_get_fallback_mask (gint channels);
gboolean            gst_audio_check_valid_channel_positions
                                                        (const GstAudioChannelPosition *position,
                                                         gint channels,
                                                         gboolean force_order);
gboolean            gst_audio_buffer_reorder_channels   (GstBuffer *buffer,
                                                         GstAudioFormat format,
                                                         gint channels,
                                                         const GstAudioChannelPosition *from,
                                                         const GstAudioChannelPosition *to);
gboolean            gst_audio_reorder_channels          (gpointer data,
                                                         gsize size,
                                                         GstAudioFormat format,
                                                         gint channels,
                                                         const GstAudioChannelPosition *from,
                                                         const GstAudioChannelPosition *to);
gboolean            gst_audio_get_channel_reorder_map   (gint channels,
                                                         const GstAudioChannelPosition *from,
                                                         const GstAudioChannelPosition *to,
                                                         gint *reorder_map);
                    GstAudioChannelMixer;
enum                GstAudioChannelMixerFlags;
GstAudioChannelMixer * gst_audio_channel_mixer_new      (GstAudioChannelMixerFlags flags,
                                                         GstAudioFormat format,
                                                         gint in_channels,
                                                         GstAudioChannelPosition *in_position,
                                                         gint out_channels,
                                                         GstAudioChannelPosition *out_position);
void                gst_audio_channel_mixer_free        (GstAudioChannelMixer *mix);
gboolean            gst_audio_channel_mixer_is_passthrough
                                                        (GstAudioChannelMixer *mix);
void                gst_audio_channel_mixer_samples     (GstAudioChannelMixer *mix,
                                                         const gpointer in[],
                                                         gpointer out[],
                                                         gint samples);

Description

This library contains some helper functions for multichannel audio.

Details

enum GstAudioChannelPosition

typedef enum {
  /* These get negative indices to allow to use
   * the enum values of the normal cases for the
   * bit-mask position */
  GST_AUDIO_CHANNEL_POSITION_NONE = -3,
  GST_AUDIO_CHANNEL_POSITION_MONO = -2,
  GST_AUDIO_CHANNEL_POSITION_INVALID = -1,

  /* Normal cases */
  GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT = 0,
  GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_FRONT_CENTER,
  GST_AUDIO_CHANNEL_POSITION_LFE1,
  GST_AUDIO_CHANNEL_POSITION_REAR_LEFT,
  GST_AUDIO_CHANNEL_POSITION_REAR_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
  GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,
  GST_AUDIO_CHANNEL_POSITION_REAR_CENTER,
  GST_AUDIO_CHANNEL_POSITION_LFE2,
  GST_AUDIO_CHANNEL_POSITION_SIDE_LEFT,
  GST_AUDIO_CHANNEL_POSITION_SIDE_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_LEFT,
  GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_CENTER,
  GST_AUDIO_CHANNEL_POSITION_TOP_CENTER,
  GST_AUDIO_CHANNEL_POSITION_TOP_REAR_LEFT,
  GST_AUDIO_CHANNEL_POSITION_TOP_REAR_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_TOP_SIDE_LEFT,
  GST_AUDIO_CHANNEL_POSITION_TOP_SIDE_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_TOP_REAR_CENTER,
  GST_AUDIO_CHANNEL_POSITION_BOTTOM_FRONT_CENTER,
  GST_AUDIO_CHANNEL_POSITION_BOTTOM_FRONT_LEFT,
  GST_AUDIO_CHANNEL_POSITION_BOTTOM_FRONT_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_WIDE_LEFT,
  GST_AUDIO_CHANNEL_POSITION_WIDE_RIGHT,
  GST_AUDIO_CHANNEL_POSITION_SURROUND_LEFT,
  GST_AUDIO_CHANNEL_POSITION_SURROUND_RIGHT
} 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.

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)

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.

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. [array]

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.

channels :

The number of channels

channel_mask :

The input channel_mask

position :

The GstAudioChannelPositions. [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.

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.

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.

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.

buffer :

The buffer to reorder.

format :

The GstAudioFormat of the buffer.

channels :

The number of channels.

from :

The channel positions in the buffer. [array]

to :

The channel positions to convert to. [array]

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.

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]

to :

The channel positions to convert to. [array]

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.

channels :

The number of channels.

from :

The channel positions to reorder from. [array]

to :

The channel positions to reorder to. [array]

reorder_map :

Pointer to the reorder map. [array]

Returns :

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

GstAudioChannelMixer

typedef struct _GstAudioChannelMixer GstAudioChannelMixer;

enum GstAudioChannelMixerFlags

typedef enum {
  GST_AUDIO_CHANNEL_MIXER_FLAGS_NONE                = 0,
  GST_AUDIO_CHANNEL_MIXER_FLAGS_NON_INTERLEAVED_IN  = (1 << 0),
  GST_AUDIO_CHANNEL_MIXER_FLAGS_NON_INTERLEAVED_OUT = (1 << 1),
  GST_AUDIO_CHANNEL_MIXER_FLAGS_UNPOSITIONED_IN     = (1 << 2),
  GST_AUDIO_CHANNEL_MIXER_FLAGS_UNPOSITIONED_OUT    = (1 << 3)
} GstAudioChannelMixerFlags;

Flags passed to gst_audio_channel_mixer_new()

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

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_free ()

void                gst_audio_channel_mixer_free        (GstAudioChannelMixer *mix);

Free memory allocated by mix.


gst_audio_channel_mixer_is_passthrough ()

gboolean            gst_audio_channel_mixer_is_passthrough
                                                        (GstAudioChannelMixer *mix);

Check if mix is in passthrough.

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.

mix :

a GstAudioChannelMixer

in :

input samples

out :

output samples

samples :

number of samples