Surround sound support.

Original commit message from CVS:
* ext/a52dec/gsta52dec.c: (gst_a52dec_channels), (gst_a52dec_push),
(gst_a52dec_reneg), (gst_a52dec_loop), (plugin_init):
* ext/alsa/gstalsa.c: (gst_alsa_get_caps):
* ext/alsa/gstalsaplugin.c: (plugin_init):
* ext/dts/gstdtsdec.c: (gst_dtsdec_channels),
(gst_dtsdec_renegotiate), (gst_dtsdec_loop), (plugin_init):
* ext/faad/gstfaad.c: (gst_faad_init), (gst_faad_chanpos_from_gst),
(gst_faad_chanpos_to_gst), (gst_faad_sinkconnect),
(gst_faad_srcgetcaps), (gst_faad_srcconnect), (gst_faad_chain),
(gst_faad_change_state), (plugin_init):
* ext/faad/gstfaad.h:
* ext/vorbis/vorbis.c: (plugin_init):
* ext/vorbis/vorbisdec.c: (vorbis_dec_chain):
* gst-libs/gst/audio/Makefile.am:
* gst-libs/gst/audio/audio.c: (plugin_init):
* gst-libs/gst/audio/multichannel.c:
(gst_audio_check_channel_positions),
(gst_audio_get_channel_positions),
(gst_audio_set_channel_positions),
(gst_audio_set_structure_channel_positions_list),
(add_list_to_struct), (gst_audio_set_caps_channel_positions_list),
(gst_audio_fixate_channel_positions):
* gst-libs/gst/audio/multichannel.h:
* gst-libs/gst/audio/testchannels.c: (main):
* gst/audioconvert/gstaudioconvert.c:
(gst_audio_convert_class_init), (gst_audio_convert_init),
(gst_audio_convert_dispose), (gst_audio_convert_getcaps),
(gst_audio_convert_parse_caps), (gst_audio_convert_link),
(gst_audio_convert_fixate), (gst_audio_convert_channels):
* gst/audioconvert/plugin.c: (plugin_init):
Surround sound support.

5 files changed, 805 insertions, 3 deletions

diff --git a/gst-libs/gst/audio/Makefile.am b/gst-libs/gst/audio/Makefile.am
index be353e36..99089947 100644
--- a/gst-libs/gst/audio/Makefile.am
+++ b/gst-libs/gst/audio/Makefile.am
@@ -1,15 +1,32 @@
+# variables used for enum/marshal generation
+glib_enum_headers=multichannel.h
+glib_enum_define=GST_AUDIO
+glib_enum_prefix=gst_audio
+
+built_sources = multichannel-enumtypes.c
+built_headers = multichannel-enumtypes.h
+BUILT_SOURCES = $(built_sources) $(built_headers)
+
 librarydir = $(libdir)/gstreamer-@GST_MAJORMINOR@
 
 library_LTLIBRARIES = libgstaudio.la libgstaudiofilter.la
 noinst_LTLIBRARIES = libgstaudiofilterexample.la
 
 EXTRA_DIST = gstaudiofiltertemplate.c make_filter
-CLEANFILES = gstaudiofilterexample.c
+CLEANFILES = gstaudiofilterexample.c \
+	$(BUILT_SOURCES)
 
-libgstaudio_la_SOURCES = audio.c audioclock.c
+libgstaudio_la_SOURCES = audio.c audioclock.c \
+	multichannel.c
+nodist_libgstaudio_la_SOURCES = $(built_sources)
 
 libgstaudioincludedir = $(includedir)/gstreamer-@GST_MAJORMINOR@/gst/audio
-libgstaudioinclude_HEADERS = audio.h audioclock.h gstaudiofilter.h
+libgstaudioinclude_HEADERS = \
+	audio.h \
+	audioclock.h \
+	gstaudiofilter.h \
+	multichannel.h \
+	multichannel-enumtypes.h
 
 libgstaudio_la_LIBADD =
 libgstaudio_la_CFLAGS = $(GST_CFLAGS)
@@ -25,3 +42,10 @@ libgstaudiofilterexample_la_LDFLAGS = $(GST_PLUGIN_LDFLAGS)
 
 gstaudiofilterexample.c: $(srcdir)/make_filter $(srcdir)/gstaudiofiltertemplate.c
 	$(srcdir)/make_filter AudiofilterExample $(srcdir)/gstaudiofiltertemplate.c
+
+noinst_PROGRAMS = testchannels
+testchannels_SOURCES = testchannels.c
+testchannels_CFLAGS = $(GST_CFLAGS)
+testchannels_LDFLAGS = $(GST_LIBS)
+
+include $(top_srcdir)/common/glib-gen.mak
diff --git a/gst-libs/gst/audio/audio.c b/gst-libs/gst/audio/audio.c
index ae0571fa..b6a1edb5 100644
--- a/gst-libs/gst/audio/audio.c
+++ b/gst-libs/gst/audio/audio.c
@@ -22,6 +22,7 @@
 #endif
 
 #include "audio.h"
+#include "multichannel-enumtypes.h"
 
 #include <gst/gststructure.h>
 
@@ -267,6 +268,8 @@ gst_audio_structure_set_int (GstStructure * structure, GstAudioFieldFlag flag)
 static gboolean
 plugin_init (GstPlugin * plugin)
 {
+  gst_audio_channel_position_get_type ();
+
   return TRUE;
 }
 
diff --git a/gst-libs/gst/audio/multichannel.c b/gst-libs/gst/audio/multichannel.c
new file mode 100644
index 00000000..67c055d9
--- /dev/null
+++ b/gst-libs/gst/audio/multichannel.c
@@ -0,0 +1,634 @@
+/* GStreamer Multichannel-Audio helper functions
+ * (c) 2004 Ronald Bultje <rbultje@ronald.bitfreak.net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include "multichannel.h"
+
+#define GST_AUDIO_CHANNEL_POSITIONS_PROPERTY_NAME "channel-positions"
+
+/*
+ * This function checks if basic assumptions apply:
+ *  - does each position occur at most once?
+ *  - do conflicting positions occur?
+ *     + front_mono vs. front_left/right
+ *     + front_center vs. front_left/right_of_center
+ *     + rear_center vs. rear_left/right
+ * It also adds some hacks that 0.8.x needs for compatibility:
+ *  - if channels == 1, are we really mono?
+ *  - if channels == 2, are we really stereo?
+ */
+
+static gboolean
+gst_audio_check_channel_positions (const GstAudioChannelPosition * pos,
+    gint channels)
+{
+  gint i, n;
+  struct
+  {
+    GstAudioChannelPosition pos1[2];
+    GstAudioChannelPosition pos2[1];
+  } conf[] = {
+    /* front: mono <-> stereo */
+    { {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT,
+            GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT}, {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_MONO}},
+        /* front center: 2 <-> 1 */
+    { {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
+            GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER}, {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_CENTER}},
+        /* rear: 2 <-> 1 */
+    { {
+    GST_AUDIO_CHANNEL_POSITION_REAR_LEFT,
+            GST_AUDIO_CHANNEL_POSITION_REAR_RIGHT}, {
+    GST_AUDIO_CHANNEL_POSITION_REAR_CENTER}}, { {
+    GST_AUDIO_CHANNEL_POSITION_INVALID}}
+  };
+
+  /* check for invalid channel positions */
+  for (n = 0; n < channels; n++) {
+    if (pos[n] == GST_AUDIO_CHANNEL_POSITION_INVALID) {
+      g_warning ("Position %d is invalid, not allowed", n);
+      return FALSE;
+    }
+  }
+
+  /* check for multiple position occurrences */
+  for (i = GST_AUDIO_CHANNEL_POSITION_INVALID + 1;
+      i < GST_AUDIO_CHANNEL_POSITION_NUM; i++) {
+    gint count = 0;
+
+    for (n = 0; n < channels; n++) {
+      if (pos[n] == i)
+        count++;
+    }
+
+    if (count > 1) {
+      g_warning ("Channel position %d occurred %d times, not allowed",
+          i, count);
+      return FALSE;
+    }
+  }
+
+  /* check for position conflicts */
+  for (i = 0; conf[i].pos1[0] != GST_AUDIO_CHANNEL_POSITION_INVALID; i++) {
+    gboolean found1 = FALSE, found2 = FALSE;
+
+    for (n = 0; n < channels; n++) {
+      if (pos[n] == conf[i].pos1[0] || pos[n] == conf[i].pos1[1])
+        found1 = TRUE;
+      else if (pos[n] == conf[i].pos2[0])
+        found2 = TRUE;
+    }
+
+    if (found1 && found2) {
+      g_warning ("Found conflicting channel positions %d/%d and %d",
+          conf[i].pos1[0], conf[i].pos1[1], conf[i].pos2[0]);
+      return FALSE;
+    }
+  }
+
+  /* 0.8.x evilry */
+  if ((channels == 1 && pos[0] != GST_AUDIO_CHANNEL_POSITION_FRONT_MONO) ||
+      (channels == 2 && (pos[0] != GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT ||
+              pos[1] != GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT))) {
+    g_warning ("0.8.x: channels=1 implies mono; channels=2 implies stereo");
+    return FALSE;
+  }
+
+  return TRUE;
+}
+
+/**
+ * gst_audio_get_channel_positions:
+ * @str: A #GstStructure to retrieve channel positions from.
+ *
+ * Retrieves a number of (fixed!) audio channel positions from
+ * the provided #GstStructure and returns it as a newly allocated
+ * array. The caller should g_free () this array. The caller
+ * should also check that the members in this #GstStructure are
+ * indeed "fixed" before calling this function.
+ *
+ * Returns: a newly allocated array containing the channel
+ * positions as provided in the given #GstStructure. Returns
+ * NULL on error.
+ */
+
+GstAudioChannelPosition *
+gst_audio_get_channel_positions (GstStructure * str)
+{
+  GstAudioChannelPosition *pos;
+  gint channels, n;
+  const GValue *pos_val_arr, *pos_val_entry;
+  gboolean res;
+  GType t;
+
+  /* get number of channels, general type checkups */
+  g_return_val_if_fail (str != NULL, NULL);
+  res = gst_structure_get_int (str, "channels", &channels);
+  g_return_val_if_fail (res, NULL);
+  g_return_val_if_fail (channels > 0, NULL);
+  pos_val_arr = gst_structure_get_value (str,
+      GST_AUDIO_CHANNEL_POSITIONS_PROPERTY_NAME);
+
+  /* The following checks are here to retain compatibility for plugins not
+   * implementing this property. They expect that channels=1 implies mono
+   * and channels=2 implies stereo, so we follow that.
+   * This might be removed during 0.9.x. */
+  if (!pos_val_arr && (channels == 1 || channels == 2)) {
+    pos = g_new (GstAudioChannelPosition, channels);
+    if (channels == 1) {
+      pos[0] = GST_AUDIO_CHANNEL_POSITION_FRONT_MONO;
+    } else {
+      pos[0] = GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT;
+      pos[1] = GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT;
+    }
+    return pos;
+  }
+  g_return_val_if_fail (pos_val_arr != NULL, NULL);
+  g_return_val_if_fail (gst_value_list_get_size (pos_val_arr) == channels,
+      NULL);
+  for (n = 0; n < channels; n++) {
+    t = G_VALUE_TYPE (gst_value_list_get_value (pos_val_arr, n));
+    g_return_val_if_fail (t == GST_TYPE_AUDIO_CHANNEL_POSITION, NULL);
+  }
+
+  /* ... and fill array */
+  pos = g_new (GstAudioChannelPosition, channels);
+  for (n = 0; n < channels; n++) {
+    pos_val_entry = gst_value_list_get_value (pos_val_arr, n);
+    pos[n] = g_value_get_enum (pos_val_entry);
+  }
+
+  if (!gst_audio_check_channel_positions (pos, channels)) {
+    g_free (pos);
+    return NULL;
+  }
+
+  return pos;
+}
+
+/**
+ * gst_audio_set_channel_positions:
+ * @str: A #GstStructure to retrieve channel positions from.
+ * @pos: an array of channel positions. The number of members
+ *       in this array should be equal to the (fixed!) number
+ *       of the "channels" property in the given #GstStructure.
+ *
+ * Adds a "channel-positions" property to the given #GstStructure,
+ * which will represent the channel positions as given in the
+ * provided #GstAudioChannelPosition array.
+ */
+
+void
+gst_audio_set_channel_positions (GstStructure * str,
+    const GstAudioChannelPosition * pos)
+{
+  GValue pos_val_arr = { 0 }, pos_val_entry = {
+  0};
+  gint channels, n;
+  gboolean res;
+
+  /* get number of channels, checkups */
+  g_return_if_fail (str != NULL);
+  g_return_if_fail (pos != NULL);
+  res = gst_structure_get_int (str, "channels", &channels);
+  g_return_if_fail (res);
+  g_return_if_fail (channels > 0);
+  if (!gst_audio_check_channel_positions (pos, channels))
+    return;
+
+  /* build gvaluearray from positions */
+  g_value_init (&pos_val_entry, GST_TYPE_AUDIO_CHANNEL_POSITION);
+  g_value_init (&pos_val_arr, GST_TYPE_FIXED_LIST);
+  for (n = 0; n < channels; n++) {
+    g_value_set_enum (&pos_val_entry, pos[n]);
+    gst_value_list_append_value (&pos_val_arr, &pos_val_entry);
+  }
+  g_value_unset (&pos_val_entry);
+
+  /* add to structure */
+  gst_structure_set_value (str,
+      GST_AUDIO_CHANNEL_POSITIONS_PROPERTY_NAME, &pos_val_arr);
+  g_value_unset (&pos_val_arr);
+}
+
+/**
+ * gst_audio_set_structure_channel_positions_list:
+ * @str: #GstStructure to set the list of channel positions
+ *       on.
+ * @pos: the array containing one or more possible audio
+ *       channel positions that we should add in each value
+ *       of the array in the given structure.
+ * @num_positions: the number of values in pos.
+ *
+ * Sets a (possibly non-fixed) list of possible audio channel
+ * positions (given in pos) on the given structure. The
+ * structure, after this function has been called, will contain
+ * a "channel-positions" property with an array of the size of
+ * the "channels" property value in the given structure (note
+ * that this means that the channels property in the provided
+ * structure should be fixed!). Each value in the array will
+ * contain each of the values given in the pos array.
+ */
+
+void
+gst_audio_set_structure_channel_positions_list (GstStructure * str,
+    const GstAudioChannelPosition * pos, gint num_positions)
+{
+  gint channels, n, c;
+  GValue pos_val_arr = { 0 }, pos_val_list = {
+  0}, pos_val_entry = {
+  0};
+  gboolean res;
+
+  /* get number of channels, general type checkups */
+  g_return_if_fail (str != NULL);
+  g_return_if_fail (num_positions > 0);
+  g_return_if_fail (pos != NULL);
+  res = gst_structure_get_int (str, "channels", &channels);
+  g_return_if_fail (res);
+  g_return_if_fail (channels > 0);
+
+  /* 0.8.x: channels=1 or channels=2 is mono/stereo, no positions needed
+   * there (we discard them anyway) */
+  if (channels == 1 || channels == 2)
+    return;
+
+  /* create the array of lists */
+  g_value_init (&pos_val_arr, GST_TYPE_FIXED_LIST);
+  g_value_init (&pos_val_entry, GST_TYPE_AUDIO_CHANNEL_POSITION);
+  for (n = 0; n < channels; n++) {
+    g_value_init (&pos_val_list, GST_TYPE_LIST);
+    for (c = 0; c < num_positions; c++) {
+      g_value_set_enum (&pos_val_entry, pos[c]);
+      gst_value_list_append_value (&pos_val_list, &pos_val_entry);
+    }
+    gst_value_list_append_value (&pos_val_arr, &pos_val_list);
+    g_value_unset (&pos_val_list);
+  }
+  g_value_unset (&pos_val_entry);
+  gst_structure_set_value (str, GST_AUDIO_CHANNEL_POSITIONS_PROPERTY_NAME,
+      &pos_val_arr);
+  g_value_unset (&pos_val_arr);
+}
+
+/*
+ * Helper function for below. The structure will be conserved,
+ * but might be cut down. Any additional structures that were
+ * created will be stored in the returned caps.
+ */
+
+static GstCaps *
+add_list_to_struct (GstStructure * str,
+    const GstAudioChannelPosition * pos, gint num_positions)
+{
+  GstCaps *caps = gst_caps_new_empty ();
+  const GValue *chan_val;
+
+  chan_val = gst_structure_get_value (str, "channels");
+  if (G_VALUE_TYPE (chan_val) == G_TYPE_INT) {
+    gst_audio_set_structure_channel_positions_list (str, pos, num_positions);
+  } else if (G_VALUE_TYPE (chan_val) == GST_TYPE_LIST) {
+    gint size;
+    const GValue *sub_val;
+
+    size = gst_value_list_get_size (chan_val);
+    sub_val = gst_value_list_get_value (chan_val, 0);
+    gst_structure_set_value (str, "channels", sub_val);
+    gst_caps_append (caps, add_list_to_struct (str, pos, num_positions));
+    while (--size > 0) {
+      str = gst_structure_copy (str);
+      sub_val = gst_value_list_get_value (chan_val, size);
+      gst_structure_set_value (str, "channels", sub_val);
+      gst_caps_append (caps, add_list_to_struct (str, pos, num_positions));
+      gst_caps_append_structure (caps, str);
+    }
+  } else if (G_VALUE_TYPE (chan_val) == GST_TYPE_INT_RANGE) {
+    gint min, max;
+
+    min = gst_value_get_int_range_min (chan_val);
+    max = gst_value_get_int_range_max (chan_val);
+
+    gst_structure_set (str, "channels", G_TYPE_INT, min, NULL);
+    gst_audio_set_structure_channel_positions_list (str, pos, num_positions);
+    for (++min; min < max; min++) {
+      str = gst_structure_copy (str);
+      gst_structure_set (str, "channels", G_TYPE_INT, min, NULL);
+      gst_audio_set_structure_channel_positions_list (str, pos, num_positions);
+      gst_caps_append_structure (caps, str);
+    }
+  } else {
+    g_warning ("Unknown value type for channels property");
+  }
+
+  return caps;
+}
+
+/**
+ * gst_audio_set_caps_channel_positions_list:
+ * @caps: #GstCaps to set the list of channel positions on.
+ * @pos: the array containing one or more possible audio
+ *       channel positions that we should add in each value
+ *       of the array in the given structure.
+ * @num_positions: the number of values in pos.
+ *
+ * Sets a (possibly non-fixed) list of possible audio channel
+ * positions (given in pos) on the given caps. Each of the
+ * structures of the caps, after this function has been called,
+ * will contain a "channel-positions" property with an array.
+ * Each value in the array will contain each of the values given
+ * in the pos array. Note that the size of the caps might be
+ * increased by this, since each structure with a "channel-
+ * positions" property needs to have a fixed "channels" property.
+ * The input caps is not required to have this.
+ */
+
+void
+gst_audio_set_caps_channel_positions_list (GstCaps * caps,
+    const GstAudioChannelPosition * pos, gint num_positions)
+{
+  gint size, n;
+
+  /* get number of channels, general type checkups */
+  g_return_if_fail (caps != NULL);
+  g_return_if_fail (num_positions > 0);
+  g_return_if_fail (pos != NULL);
+
+  size = gst_caps_get_size (caps);
+  for (n = 0; n < size; n++) {
+    gst_caps_append (caps, add_list_to_struct (gst_caps_get_structure (caps,
+                n), pos, num_positions));
+  }
+}
+
+/**
+ * gst_audio_fixate_channel_positions:
+ * @str: a #GstStructure containing a (possibly unfixed)
+ *       "channel-positions" property.
+ *
+ * Custom fixate function. Elements that implement some sort of
+ * channel conversion algorhithm should use this function for
+ * fixating on GstAudioChannelPosition properties. It will take
+ * care of equal channel positioning (left/right). Caller g_free()s
+ * the return value. The input properties may be (and are supposed
+ * to be) unfixed.
+ * Note that this function is mostly a hack because we currently
+ * have no way to add default fixation functions for new GTypes.
+ *
+ * Returns: fixed values that the caller could use as a fixed
+ * set of #GstAudioChannelPosition values.
+ */
+
+GstAudioChannelPosition *
+gst_audio_fixate_channel_positions (GstStructure * str)
+{
+  GstAudioChannelPosition *pos;
+  gint channels, n, num_unfixed = 0, i, c;
+  const GValue *pos_val_arr, *pos_val_entry, *pos_val;
+  gboolean res, is_stereo = TRUE;
+  GType t;
+
+  /*
+   * We're going to do this cluelessly. We'll make an array of values that
+   * conflict with each other and, for each iteration in this array, pick
+   * either one until all unknown values are filled. This might not work in
+   * corner cases but should work OK for the general case.
+   */
+  struct
+  {
+    GstAudioChannelPosition pos1[2];
+    GstAudioChannelPosition pos2[1];
+  } conf[] = {
+    /* front: mono <-> stereo */
+    { {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT,
+            GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT}, {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_MONO}},
+        /* front center: 2 <-> 1 */
+    { {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
+            GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER}, {
+    GST_AUDIO_CHANNEL_POSITION_FRONT_CENTER}},
+        /* rear: 2 <-> 1 */
+    { {
+    GST_AUDIO_CHANNEL_POSITION_REAR_LEFT,
+            GST_AUDIO_CHANNEL_POSITION_REAR_RIGHT}, {
+    GST_AUDIO_CHANNEL_POSITION_REAR_CENTER}}, { {
+    GST_AUDIO_CHANNEL_POSITION_INVALID, GST_AUDIO_CHANNEL_POSITION_INVALID}, {
+    GST_AUDIO_CHANNEL_POSITION_LFE}}, { {
+    GST_AUDIO_CHANNEL_POSITION_SIDE_LEFT,
+            GST_AUDIO_CHANNEL_POSITION_SIDE_RIGHT}, {
+    GST_AUDIO_CHANNEL_POSITION_INVALID}}, { {
+    GST_AUDIO_CHANNEL_POSITION_INVALID, GST_AUDIO_CHANNEL_POSITION_INVALID}, {
+    GST_AUDIO_CHANNEL_POSITION_INVALID}}
+  };
+  struct
+  {
+    gint num_opt[3];
+    guint num_opts[3];
+    gboolean is_fixed[3];
+    gint choice;                /* -1 is none, 0 is the two, 1 is the one */
+  } opt;
+
+  /* get number of channels, general type checkups */
+  g_return_val_if_fail (str != NULL, NULL);
+  res = gst_structure_get_int (str, "channels", &channels);
+  g_return_val_if_fail (res, NULL);
+  g_return_val_if_fail (channels > 0, NULL);
+
+  /* 0.8.x mono/stereo checks */
+  pos_val_arr = gst_structure_get_value (str,
+      GST_AUDIO_CHANNEL_POSITIONS_PROPERTY_NAME);
+  if (!pos_val_arr && (channels == 1 || channels == 2)) {
+    pos = g_new (GstAudioChannelPosition, channels);
+    if (channels == 1) {
+      pos[0] = GST_AUDIO_CHANNEL_POSITION_FRONT_MONO;
+    } else {
+      pos[0] = GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT;
+      pos[1] = GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT;
+    }
+    return pos;
+  }
+  g_return_val_if_fail (pos_val_arr != NULL, NULL);
+  g_return_val_if_fail (gst_value_list_get_size (pos_val_arr) == channels,
+      NULL);
+  for (n = 0; n < channels; n++) {
+    t = G_VALUE_TYPE (gst_value_list_get_value (pos_val_arr, n));
+    g_return_val_if_fail (t == GST_TYPE_LIST ||
+        t == GST_TYPE_AUDIO_CHANNEL_POSITION, NULL);
+  }
+
+  /* all unknown, to start with */
+  pos = g_new (GstAudioChannelPosition, channels);
+  for (n = 0; n < channels; n++)
+    pos[n] = GST_AUDIO_CHANNEL_POSITION_INVALID;
+  num_unfixed = channels;
+
+  /* Iterate the array of conflicting values */
+  for (i = 0; conf[i].pos1[0] != GST_AUDIO_CHANNEL_POSITION_INVALID ||
+      conf[i].pos2[0] != GST_AUDIO_CHANNEL_POSITION_INVALID; i++) {
+    /* front/center only important if not mono (obviously) */
+    if (conf[i].pos1[0] == GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER &&
+        !is_stereo)
+      continue;
+
+    /* init values */
+    for (n = 0; n < 3; n++) {
+      opt.num_opt[n] = -1;
+      opt.num_opts[n] = -1;
+      opt.is_fixed[n] = FALSE;
+    }
+
+    /* Now, we'll see for each channel if it allows for any of the values in
+     * the set of conflicting audio channel positions and keep scores. */
+    for (n = 0; n < channels; n++) {
+      /* if the channel is already taken, don't bother */
+      if (pos[n] != GST_AUDIO_CHANNEL_POSITION_INVALID)
+        continue;
+
+      pos_val_entry = gst_value_list_get_value (pos_val_arr, n);
+      t = G_VALUE_TYPE (pos_val_entry);
+      if (t == GST_TYPE_LIST) {
+        /* This algorhythm is suboptimal. */
+        for (c = 0; c < gst_value_list_get_size (pos_val_entry); c++) {
+          pos_val = gst_value_list_get_value (pos_val_entry, c);
+          if (g_value_get_enum (pos_val) == conf[i].pos1[0] &&
+              opt.num_opts[0] > gst_value_list_get_size (pos_val_entry) &&
+              !opt.is_fixed[0]) {
+            /* Now test if the old position of num_opt[0] also allows for
+             * the other channel (which was skipped previously). If so,
+             * keep score. */
+            if (opt.num_opt[0] != -1) {
+              gint c1;
+
+              pos_val_entry = gst_value_list_get_value (pos_val_arr,
+                  opt.num_opt[0]);
+              if (G_VALUE_TYPE (pos_val_entry) == GST_TYPE_LIST) {
+                for (c1 = 0; c1 < gst_value_list_get_size (pos_val_entry); c1++) {
+                  pos_val = gst_value_list_get_value (pos_val_entry, c1);
+                  if (g_value_get_enum (pos_val) == conf[i].pos1[1] &&
+                      opt.num_opts[1] > opt.num_opts[0] && !opt.is_fixed[1]) {
+                    opt.num_opts[1] = opt.num_opts[0];
+                    opt.num_opt[1] = opt.num_opt[0];
+                  }
+                }
+                pos_val = gst_value_list_get_value (pos_val_entry, c);
+              }
+              pos_val_entry = gst_value_list_get_value (pos_val_arr, n);
+            }
+
+            /* and save values */
+            opt.num_opts[0] = gst_value_list_get_size (pos_val_entry);
+            opt.num_opt[0] = n;
+          } else if (g_value_get_enum (pos_val) == conf[i].pos1[1] &&
+              opt.num_opts[1] > gst_value_list_get_size (pos_val_entry) &&
+              !opt.is_fixed[1] && n != opt.num_opt[0]) {
+            opt.num_opts[1] = gst_value_list_get_size (pos_val_entry);
+            opt.num_opt[1] = n;
+          }
+
+          /* 2 goes separately, because 0/1 vs. 2 are separate */
+          if (g_value_get_enum (pos_val) == conf[i].pos2[0] &&
+              opt.num_opts[2] > gst_value_list_get_size (pos_val_entry) &&
+              !opt.is_fixed[2]) {
+            opt.num_opts[2] = gst_value_list_get_size (pos_val_entry);
+            opt.num_opt[2] = n;
+          }
+        }
+      } else {
+        if (g_value_get_enum (pos_val_entry) == conf[i].pos1[0]) {
+          opt.num_opt[0] = n;
+          opt.is_fixed[0] = TRUE;
+        } else if (g_value_get_enum (pos_val_entry) == conf[i].pos1[1]) {
+          opt.num_opt[1] = n;
+          opt.is_fixed[1] = TRUE;
+        } else if (g_value_get_enum (pos_val_entry) == conf[i].pos2[0]) {
+          opt.num_opt[2] = n;
+          opt.is_fixed[2] = TRUE;
+        }
+      }
+    }
+
+    /* check our results and choose either one */
+    if ((opt.is_fixed[0] || opt.is_fixed[1]) && opt.is_fixed[2]) {
+      g_warning ("Pre-fixated on both %d/%d and %d - conflict!",
+          conf[i].pos1[0], conf[i].pos1[1], conf[i].pos2[0]);
+      g_free (pos);
+      return NULL;
+    } else if ((opt.is_fixed[0] && opt.num_opt[1] == -1) ||
+        (opt.is_fixed[1] && opt.num_opt[0] == -1)) {
+      g_warning ("Pre-fixated one side, but other side n/a of %d/%d",
+          conf[i].pos1[0], conf[i].pos1[1]);
+      g_free (pos);
+      return NULL;
+    } else if (opt.is_fixed[0] || opt.is_fixed[1]) {
+      opt.choice = 0;
+    } else if (opt.is_fixed[2]) {
+      opt.choice = 1;
+    } else if (opt.num_opt[0] != -1 && opt.num_opt[1] != -1) {
+      opt.choice = 0;
+    } else if (opt.num_opt[2] != -1) {
+      opt.choice = 1;
+    } else {
+      opt.choice = -1;
+    }
+
+    /* stereo? Note that we keep is_stereo to TRUE if we didn't decide on
+     * any arrangement. The mono/stereo channels might be handled elsewhere
+     * which is clearly outside the scope of this element, so we cannot
+     * know and expect the application to handle that then. */
+    if (conf[i].pos2[0] == GST_AUDIO_CHANNEL_POSITION_FRONT_MONO &&
+        opt.choice == 1) {
+      is_stereo = FALSE;
+    }
+
+    /* now actually decide what we'll do and fixate on that */
+    if (opt.choice == 0) {
+      g_assert (conf[i].pos1[0] != GST_AUDIO_CHANNEL_POSITION_INVALID &&
+          conf[i].pos1[1] != GST_AUDIO_CHANNEL_POSITION_INVALID);
+      pos[opt.num_opt[0]] = conf[i].pos1[0];
+      pos[opt.num_opt[1]] = conf[i].pos1[1];
+      num_unfixed -= 2;
+    } else if (opt.choice == 1) {
+      g_assert (conf[i].pos2[0] != GST_AUDIO_CHANNEL_POSITION_INVALID);
+      pos[opt.num_opt[2]] = conf[i].pos2[0];
+      num_unfixed--;
+    }
+  }
+
+  /* safety check */
+  if (num_unfixed > 0) {
+    g_warning ("%d unfixed channel positions left after fixation!",
+        num_unfixed);
+    g_free (pos);
+    return NULL;
+  }
+
+  if (!gst_audio_check_channel_positions (pos, channels)) {
+    g_free (pos);
+    return NULL;
+  }
+
+  return pos;
+}
diff --git a/gst-libs/gst/audio/multichannel.h b/gst-libs/gst/audio/multichannel.h
new file mode 100644
index 00000000..5194fffa
--- /dev/null
+++ b/gst-libs/gst/audio/multichannel.h
@@ -0,0 +1,86 @@
+/* GStreamer Multichannel-Audio helper functions
+ * (c) 2004 Ronald Bultje <rbultje@ronald.bitfreak.net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifndef __GST_AUDIO_MULTICHANNEL_H__
+#define __GST_AUDIO_MULTICHANNEL_H__
+
+#include <gst/audio/audio.h>
+#include <gst/audio/multichannel-enumtypes.h>
+
+typedef enum {
+  GST_AUDIO_CHANNEL_POSITION_INVALID = -1,
+
+  /* Main front speakers. Mono and left/right are mututally exclusive! */
+  GST_AUDIO_CHANNEL_POSITION_FRONT_MONO,
+  GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT,
+  GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT,
+
+  /* rear. Left/right and center are mututally exclusive! */
+  GST_AUDIO_CHANNEL_POSITION_REAR_CENTER,
+  GST_AUDIO_CHANNEL_POSITION_REAR_LEFT,
+  GST_AUDIO_CHANNEL_POSITION_REAR_RIGHT,
+
+  /* subwoofer/low-frequency */
+  GST_AUDIO_CHANNEL_POSITION_LFE,
+
+  /* Center front speakers. Center and left/right_of_center cannot be
+   * used together! */
+  GST_AUDIO_CHANNEL_POSITION_FRONT_CENTER,
+  GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
+  GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,
+
+  /* sides */
+  GST_AUDIO_CHANNEL_POSITION_SIDE_LEFT,
+  GST_AUDIO_CHANNEL_POSITION_SIDE_RIGHT,
+
+  /* don't use - counter */
+  GST_AUDIO_CHANNEL_POSITION_NUM
+} GstAudioChannelPosition;
+
+/* Retrieves or sets the positions from/to a GstStructure. Only
+ * works with fixed caps, caller should check for that! Caller
+ * g_free()s result of the getter. */
+GstAudioChannelPosition *
+	gst_audio_get_channel_positions	(GstStructure *str);
+void	gst_audio_set_channel_positions	(GstStructure *str,
+					 const GstAudioChannelPosition *pos);
+
+/* Sets a (non-fixed) list of possible audio channel positions
+ * on a structure (this requires the "channels" property to
+ * be fixed!) or on a caps (here, the "channels" property may be
+ * unfixed and the caps may even contain multiple structures). */
+void	gst_audio_set_structure_channel_positions_list
+					(GstStructure *str,
+					 const GstAudioChannelPosition *pos,
+					 gint          num_positions);
+void	gst_audio_set_caps_channel_positions_list
+					(GstCaps      *caps,
+					 const GstAudioChannelPosition *pos,
+					 gint          num_positions);
+
+/* Custom fixate function. Elements that implement some sort of
+ * channel conversion algorhithm should use this function for
+ * fixating on GstAudioChannelPosition properties. It will take
+ * care of equal channel positioning (left/right). Caller g_free()s
+ * the return value. The input properties may be (and are supposed
+ * to be) unfixed. */
+GstAudioChannelPosition *
+	gst_audio_fixate_channel_positions (GstStructure *str);
+
+#endif /* __GST_AUDIO_MULTICHANNEL_H__ */
diff --git a/gst-libs/gst/audio/testchannels.c b/gst-libs/gst/audio/testchannels.c
new file mode 100644
index 00000000..b886c820
--- /dev/null
+++ b/gst-libs/gst/audio/testchannels.c
@@ -0,0 +1,55 @@
+/* GStreamer Multichannel Test
+ * (c) 2004 Ronald Bultje <rbultje@ronald.bitfreak.net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <gst/gst.h>
+
+#include <multichannel.c>
+#include <multichannel-enumtypes.c>
+
+gint
+main (gint argc, gchar * argv[])
+{
+  gchar *str;
+  GstCaps *caps;
+  GstAudioChannelPosition pos[2] = { GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT,
+    GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT
+  };
+
+  /* register multichannel type */
+  gst_init (&argc, &argv);
+  gst_audio_channel_position_get_type ();
+
+  /* test some caps-string conversions */
+  caps = gst_caps_new_simple ("audio/x-raw-int",
+      "channels", G_TYPE_INT, 2, NULL);
+  str = gst_caps_to_string (caps);
+  g_print ("Test caps #1: %s\n", str);
+  g_free (str);
+  gst_audio_set_channel_positions (gst_caps_get_structure (caps, 0), pos);
+  str = gst_caps_to_string (caps);
+  g_print ("Test caps #2: %s\n", str);
+  g_free (str);
+  gst_caps_free (caps);
+
+  return 0;
+}