Add APE tag demuxer (#325649).

Original commit message from CVS:
* configure.ac:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-good-plugins-docs.sgml:
* docs/plugins/gst-plugins-good-plugins-sections.txt:
* docs/plugins/gst-plugins-good-plugins.hierarchy:
* docs/plugins/inspect/plugin-apetag.xml:
* gst/apetag/Makefile.am:
* gst/apetag/gstapedemux.c:
* gst/apetag/gstapedemux.h:
* gst/apetag/gsttagdemux.c:
* gst/apetag/gsttagdemux.h:
Add APE tag demuxer (#325649).

ChangeLog

@@ -1,3 +1,18 @@
+2006-02-06  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* configure.ac:
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-good-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-good-plugins-sections.txt:
+	* docs/plugins/gst-plugins-good-plugins.hierarchy:
+	* docs/plugins/inspect/plugin-apetag.xml:
+	* gst/apetag/Makefile.am:
+	* gst/apetag/gstapedemux.c:
+	* gst/apetag/gstapedemux.h:
+	* gst/apetag/gsttagdemux.c:
+	* gst/apetag/gsttagdemux.h:
+	  Add APE tag demuxer (#325649).
+
 2006-02-05  Jan Schmidt  <thaytan@mad.scientist.com>
 
 	* ext/gconf/gconf.c: (gst_gconf_get_default_audio_sink),

configure.ac

@@ -71,6 +71,7 @@ dnl videofilter is at the top because others depend on it
 GST_PLUGINS_ALL="\
 		videofilter \
 		alpha \
+		apetag \
 		auparse \
 		autodetect \
 		avi \
@@ -583,6 +584,7 @@ AC_CONFIG_FILES(
 Makefile
 gst/Makefile
 gst/alpha/Makefile
+gst/apetag/Makefile
 gst/auparse/Makefile
 gst/autodetect/Makefile
 gst/avi/Makefile

docs/plugins/Makefile.am

@@ -74,6 +74,7 @@ IGNORE_CFILES =
 # the registry won't have the element
 
 EXTRA_HFILES = \
+	$(top_srcdir)/gst/apetag/gstapedemux.h \
 	$(top_srcdir)/gst/autodetect/gstautoaudiosink.h \
 	$(top_srcdir)/gst/autodetect/gstautovideosink.h \
 	$(top_srcdir)/gst/level/gstlevel.h \

docs/plugins/gst-plugins-good-plugins-docs.sgml

@@ -12,6 +12,7 @@
 
   <chapter>
     <title>gst-plugins-good Elements</title>
+    <xi:include href="xml/element-apedemux.xml" />
     <xi:include href="xml/element-autoaudiosink.xml" />
     <xi:include href="xml/element-autovideosink.xml" />
     <xi:include href="xml/element-cairotimeoverlay.xml" />
@@ -34,6 +35,7 @@
     <xi:include href="xml/plugin-alaw.xml" />
     <xi:include href="xml/plugin-alpha.xml" />
     <xi:include href="xml/plugin-alphacolor.xml" />
+    <xi:include href="xml/plugin-apetag.xml" />
     <xi:include href="xml/plugin-autodetect.xml" />
     <xi:include href="xml/plugin-avi.xml" />
     <xi:include href="xml/plugin-cacasink.xml" />

docs/plugins/gst-plugins-good-plugins-sections.txt

@@ -1,3 +1,11 @@
+<SECTION>
+<FILE>element-apedemux</FILE>
+GstApeDemux
+<TITLE>apedemux</TITLE>
+<SUBSECTION Standard>
+GstApeDemuxClass
+</SECTION>
+
 <SECTION>
 <FILE>element-autoaudiosink</FILE>
 GstAutoAudioSink

docs/plugins/gst-plugins-good-plugins.hierarchy

@@ -104,6 +104,8 @@ GObject
       GstAviDemux
       GstAuParse
       GstAlpha
+      GstTagDemux
+        GstApeDemux
     GstPlugin
     GstRegistry
     GstPadTemplate

docs/plugins/inspect/plugin-apetag.xml

@@ -0,0 +1,20 @@
+<plugin>
+  <name>apetag</name>
+  <description>APEv1/2 tag reader</description>
+  <filename>../../gst/apedemux/.libs/libgstapetag.so</filename>
+  <basename>libgstapetag.so</basename>
+  <version>0.10.1.1</version>
+  <license>LGPL</license>
+  <source>gst-plugins-good</source>
+  <package>GStreamer Good Plug-ins CVS/prerelease</package>
+  <origin>Unknown package origin</origin>
+  <elements>
+    <element>
+      <name>apedemux</name>
+      <longname>APE tag demuxer</longname>
+      <class>Codec/Demuxer/Metadata</class>
+      <description>Read and output APE tags while demuxing the contents</description>
+      <author>Ronald Bultje &lt;rbultje@ronald.bitfreak.net&gt;, Tim-Philipp Müller &lt;tim centricular net&gt;</author>
+    </element>
+  </elements>
+</plugin>

gst/apetag/Makefile.am

@@ -0,0 +1,11 @@
+plugin_LTLIBRARIES = libgstapetag.la
+
+libgstapetag_la_SOURCES = gstapedemux.c gsttagdemux.c
+libgstapetag_la_CFLAGS = \
+	-I$(top_srcdir)/gst-libs \
+	$(GST_CFLAGS)
+libgstapetag_la_LIBADD = \
+	$(GST_LIBS)
+libgstapetag_la_LDFLAGS = $(GST_PLUGIN_LDFLAGS)
+
+noinst_HEADERS = gstapedemux.h gsttagdemux.h

gst/apetag/gstapedemux.c

@@ -0,0 +1,356 @@
+/* GStreamer APEv1/2 tag reader
+ * Copyright (C) 2004 Ronald Bultje <rbultje@ronald.bitfreak.net>
+ * Copyright (C) 2006 Tim-Philipp Müller <tim centricular 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.
+ */
+
+/**
+ * SECTION:element-apedemux
+ * @short_description: reads tag information from APE tag data blocks and
+ * outputs them as GStreamer tag messages and events.
+ *
+ * <refsect2>
+ * <para>
+ * apedemux accepts data streams with APE tags at the start or at the end
+ * (or both). The mime type of the data between the tag blocks is detected
+ * using typefind functions, and the appropriate output mime type set on
+ * outgoing buffers. 
+ * </para>
+ * <para>
+ * The element is only able to read APE tags at the end of a stream from
+ * a seekable stream, ie. when get_range mode is supported by the upstream
+ * elements. If get_range operation is available, apedemux makes it available
+ * downstream. This means that elements which require get_range mode, such as
+ * wavparse or musepackdec, can operate on files containing APE tag
+ * information.
+ * </para>
+ * <title>Example launch line</title>
+ * <para>
+ * <programlisting>
+ * gst-launch -t filesrc location=file.mpc ! apedemux ! fakesink
+ * </programlisting>
+ * This pipeline should read any available APE tag information and output it.
+ * The contents of the file inside the APE tag regions should be detected, and
+ * the appropriate mime type set on buffers produced from apedemux.
+ * </para>
+ * </refsect2>
+ */
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <gst/gst.h>
+#include <gst/gst-i18n-plugin.h>
+
+#include "gstapedemux.h"
+
+#include <string.h>
+
+#define APE_VERSION_MAJOR(ver)  ((ver)/1000)
+
+GST_DEBUG_CATEGORY (apedemux_debug);
+#define GST_CAT_DEFAULT (apedemux_debug)
+
+static GstElementDetails gst_ape_demux_details =
+GST_ELEMENT_DETAILS ("APE tag demuxer",
+    "Codec/Demuxer/Metadata",
+    "Read and output APE tags while demuxing the contents",
+    "Ronald Bultje <rbultje@ronald.bitfreak.net>, "
+    "Tim-Philipp Müller <tim centricular net>");
+
+static GstStaticPadTemplate sink_factory = GST_STATIC_PAD_TEMPLATE ("sink",
+    GST_PAD_SINK,
+    GST_PAD_ALWAYS,
+    GST_STATIC_CAPS ("application/x-apetag")
+    );
+
+static gboolean gst_ape_demux_identify_tag (GstTagDemux * demux,
+    GstBuffer * buffer, gboolean start_tag, guint * tag_size);
+static GstTagDemuxResult gst_ape_demux_parse_tag (GstTagDemux * demux,
+    GstBuffer * buffer, gboolean start_tag, guint * tag_size,
+    GstTagList ** tags);
+
+GST_BOILERPLATE (GstApeDemux, gst_ape_demux, GstTagDemux, GST_TYPE_TAG_DEMUX)
+
+     static void gst_ape_demux_base_init (gpointer klass)
+{
+  GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
+
+  gst_element_class_add_pad_template (element_class,
+      gst_static_pad_template_get (&sink_factory));
+
+  gst_element_class_set_details (element_class, &gst_ape_demux_details);
+
+  GST_DEBUG_CATEGORY_INIT (apedemux_debug, "apedemux", 0,
+      "GStreamer APE tag demuxer");
+}
+
+static void
+gst_ape_demux_class_init (GstApeDemuxClass * klass)
+{
+  GstTagDemuxClass *tagdemux_class;
+
+  tagdemux_class = GST_TAG_DEMUX_CLASS (klass);
+
+  tagdemux_class->identify_tag = GST_DEBUG_FUNCPTR (gst_ape_demux_identify_tag);
+  tagdemux_class->parse_tag = GST_DEBUG_FUNCPTR (gst_ape_demux_parse_tag);
+}
+
+static void
+gst_ape_demux_init (GstApeDemux * apedemux, GstApeDemuxClass * gclass)
+{
+  GstTagDemux *tagdemux = GST_TAG_DEMUX (apedemux);
+
+  tagdemux->min_start_size = 32;
+  tagdemux->min_end_size = 32;
+
+  tagdemux->prefer_start_tag = TRUE;
+}
+
+static const struct _GstApeDemuxTagTableEntry
+{
+  const gchar *ape_tag;
+  const gchar *gst_tag;
+} tag_table[] = {
+  {
+  "replaygain_track_gain", GST_TAG_TRACK_GAIN}, {
+  "replaygain_track_peak", GST_TAG_TRACK_PEAK}, {
+  "replaygain_album_gain", GST_TAG_ALBUM_GAIN}, {
+  "replaygain_album_peak", GST_TAG_ALBUM_PEAK}, {
+  "title", GST_TAG_TITLE}, {
+  "artist", GST_TAG_ARTIST}, {
+  "album", GST_TAG_ALBUM}, {
+  "comment", GST_TAG_COMMENT}, {
+  "comments", GST_TAG_COMMENT}, {
+  "copyright", GST_TAG_COPYRIGHT}, {
+  "genre", GST_TAG_GENRE}, {
+  "isrc", GST_TAG_ISRC}, {
+  "track", GST_TAG_TRACK_NUMBER}, {
+  "year", GST_TAG_DATE}
+};
+
+static gboolean
+ape_demux_get_gst_tag_from_tag (const gchar * ape_tag,
+    const gchar ** gst_tag, GType * gst_tag_type)
+{
+  gint i;
+
+  for (i = 0; i < G_N_ELEMENTS (tag_table); ++i) {
+    if (g_ascii_strcasecmp (tag_table[i].ape_tag, ape_tag) == 0) {
+      *gst_tag = tag_table[i].gst_tag;
+      *gst_tag_type = gst_tag_get_type (tag_table[i].gst_tag);
+      return TRUE;
+    }
+  }
+
+  GST_WARNING ("Could not map APE tag '%s' to a GStreamer tag", ape_tag);
+  return FALSE;
+}
+
+static GstTagList *
+ape_demux_parse_tags (const guint8 * data, gint size)
+{
+  GstTagList *taglist = gst_tag_list_new ();
+  gboolean have_tag = FALSE;
+
+  GST_LOG ("Reading tags from chunk of size %u bytes", size);
+
+  /* get rid of header/footer */
+  if (size >= 32 && memcmp (data, "APETAGEX", 8) == 0) {
+    data += 32;
+    size -= 32;
+  }
+  if (size > 32 && memcmp (data + size - 32, "APETAGEX", 8) == 0) {
+    size -= 32;
+  }
+
+  /* read actual tags - at least 10 bytes for tag header */
+  while (size >= 10) {
+    guint len, n = 8;
+    gchar *tag, *val;
+    const gchar *gst_tag;
+    GType gst_tag_type;
+
+    /* find tag type and size */
+    len = GST_READ_UINT32_LE (data);
+    while (n < size && data[n] != 0x0)
+      n++;
+    if (n == size)
+      break;
+    g_assert (data[n] == 0x0);
+    n++;
+    if (size - n < len)
+      break;
+
+    /* read */
+    tag = g_strndup ((gchar *) data + 8, n - 9);
+    val = g_strndup ((gchar *) data + n, len);
+
+    if (ape_demux_get_gst_tag_from_tag (tag, &gst_tag, &gst_tag_type)) {
+      GValue v = { 0, };
+
+      switch (gst_tag_type) {
+        case G_TYPE_INT:
+          g_value_init (&v, G_TYPE_INT);
+          g_value_set_int (&v, atoi (val));
+          break;
+        case G_TYPE_UINT:
+          g_value_init (&v, G_TYPE_UINT);
+          g_value_set_uint (&v, (guint) atof (val));    /* hmmm */
+          break;
+        case G_TYPE_STRING:
+          g_value_init (&v, G_TYPE_STRING);
+          g_value_set_string (&v, val);
+          break;
+        case G_TYPE_DOUBLE:
+          g_value_init (&v, G_TYPE_DOUBLE);
+          g_value_set_double (&v, atof (val));
+          break;
+        default:{
+          if (gst_tag_type == GST_TYPE_DATE) {
+            GDate *date = g_date_new_dmy (1, 1, atoi (val));
+
+            g_value_init (&v, GST_TYPE_DATE);
+            gst_value_set_date (&v, date);
+            g_date_free (date);
+          } else {
+            GST_WARNING ("Unhandled tag type '%s' for tag '%s'",
+                g_type_name (gst_tag_type), gst_tag);
+          }
+          break;
+        }
+      }
+      if (G_VALUE_TYPE (&v) != 0) {
+        gst_tag_list_add_values (taglist, GST_TAG_MERGE_APPEND,
+            gst_tag, &v, NULL);
+        g_value_unset (&v);
+        have_tag = TRUE;
+      }
+    }
+    GST_DEBUG ("Read tag %s: %s", tag, val);
+    g_free (tag);
+    g_free (val);
+
+    /* move data pointer */
+    size -= len + n;
+    data += len + n;
+  }
+
+  GST_DEBUG ("Taglist: %" GST_PTR_FORMAT, taglist);
+  return taglist;
+}
+
+static gboolean
+gst_ape_demux_identify_tag (GstTagDemux * demux, GstBuffer * buffer,
+    gboolean start_tag, guint * tag_size)
+{
+  if (memcmp (GST_BUFFER_DATA (buffer), "APETAGEX", 8) != 0) {
+    GST_DEBUG_OBJECT (demux, "No APETAGEX marker at %s - not an APE file",
+        (start_tag) ? "start" : "end");
+    return FALSE;
+  }
+
+  *tag_size = GST_READ_UINT32_LE (GST_BUFFER_DATA (buffer) + 12);
+
+  /* size is without header, so add 32 to account for that */
+  *tag_size += 32;
+
+  return TRUE;
+}
+
+static GstTagDemuxResult
+gst_ape_demux_parse_tag (GstTagDemux * demux, GstBuffer * buffer,
+    gboolean start_tag, guint * tag_size, GstTagList ** tags)
+{
+  const guint8 *data;
+  const guint8 *footer;
+  gboolean have_header;
+  gboolean end_tag = !start_tag;
+  guint version, footer_size;
+
+  GST_LOG_OBJECT (demux, "Parsing buffer of size %u", GST_BUFFER_SIZE (buffer));
+
+  data = GST_BUFFER_DATA (buffer);
+  footer = GST_BUFFER_DATA (buffer) + GST_BUFFER_SIZE (buffer) - 32;
+
+  GST_LOG_OBJECT (demux, "Checking for footer at offset 0x%04x",
+      (guint) (footer - data));
+  if (footer > data && memcmp (footer, "APETAGEX", 8) == 0) {
+    GST_DEBUG_OBJECT (demux, "Found footer");
+    footer_size = 32;
+  } else {
+    GST_DEBUG_OBJECT (demux, "No footer");
+    footer_size = 0;
+  }
+
+  /* APE tags at the end must have a footer */
+  if (end_tag && footer_size == 0) {
+    GST_WARNING_OBJECT (demux, "Tag at end of file without footer!");
+    return GST_TAG_DEMUX_RESULT_BROKEN_TAG;
+  }
+
+  /* don't trust the header/footer flags, better detect them ourselves */
+  have_header = (memcmp (data, "APETAGEX", 8) == 0);
+
+  if (start_tag && !have_header) {
+    GST_DEBUG_OBJECT (demux, "Tag at beginning of file without header!");
+    return GST_TAG_DEMUX_RESULT_BROKEN_TAG;
+  }
+
+  if (end_tag && !have_header) {
+    GST_DEBUG_OBJECT (demux, "Tag at end of file has no header (APEv1)");
+    *tag_size -= 32;            /* adjust tag size */
+  }
+
+  if (have_header) {
+    version = GST_READ_UINT32_LE (data + 8);
+  } else {
+    version = GST_READ_UINT32_LE (footer + 8);
+  }
+
+  /* skip header */
+  if (have_header) {
+    data += 32;
+  }
+
+  GST_DEBUG_OBJECT (demux, "APE tag with version %u, size %u at offset 0x%08"
+      G_GINT64_MODIFIER "x", version, *tag_size,
+      GST_BUFFER_OFFSET (buffer) + ((have_header) ? 0 : 32));
+
+  if (APE_VERSION_MAJOR (version) != 1 && APE_VERSION_MAJOR (version) != 2) {
+    GST_WARNING ("APE tag is version %u.%03u, but decoder only supports "
+        "v1 or v2. Ignoring.", APE_VERSION_MAJOR (version), version % 1000);
+    return GST_TAG_DEMUX_RESULT_OK;
+  }
+
+  *tags = ape_demux_parse_tags (data, *tag_size - footer_size);
+
+  return GST_TAG_DEMUX_RESULT_OK;
+}
+
+static gboolean
+plugin_init (GstPlugin * plugin)
+{
+  return gst_element_register (plugin, "apedemux",
+      GST_RANK_PRIMARY, GST_TYPE_APE_DEMUX);
+}
+
+GST_PLUGIN_DEFINE (GST_VERSION_MAJOR,
+    GST_VERSION_MINOR,
+    "apetag",
+    "APEv1/2 tag reader",
+    plugin_init, VERSION, "LGPL", GST_PACKAGE_NAME, GST_PACKAGE_ORIGIN)

gst/apetag/gstapedemux.h

@@ -0,0 +1,51 @@
+/* GStreamer APEv1/2 tag reader
+ * Copyright (C) 2004 Ronald Bultje <rbultje@ronald.bitfreak.net>
+ * Copyright (C) 2006 Tim-Philipp Müller <tim centricular 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_APE_DEMUX_H__
+#define __GST_APE_DEMUX_H__
+
+#include <gst/tag/gsttagdemux.h>
+
+G_BEGIN_DECLS
+
+#define GST_TYPE_APE_DEMUX             (gst_ape_demux_get_type())
+#define GST_APE_DEMUX(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_APE_DEMUX,GstApeDemux))
+#define GST_APE_DEMUX_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_APE_DEMUX,GstApeDemuxClass))
+#define GST_IS_APE_DEMUX(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_APE_DEMUX))
+#define GST_IS_APE_DEMUX_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_APE_DEMUX))
+
+typedef struct _GstApeDemux      GstApeDemux;
+typedef struct _GstApeDemuxClass GstApeDemuxClass;
+
+struct _GstApeDemux
+{
+  GstTagDemux tagdemux;
+};
+
+struct _GstApeDemuxClass 
+{
+  GstTagDemuxClass parent_class;
+};
+
+GType gst_ape_demux_get_type (void);
+
+G_END_DECLS
+
+#endif /* __GST_APE_DEMUX_H__ */

gst/apetag/gsttagdemux.h

@@ -0,0 +1,105 @@
+/* GStreamer Base Class for Tag Demuxing
+ * Copyright (C) 2005  Jan Schmidt <thaytan@mad.scientist.com>
+ * Copyright (C) 2006  Tim-Philipp Müller <tim centricular 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_TAG_DEMUX_H__
+#define __GST_TAG_DEMUX_H__
+
+#include <gst/gst.h>
+
+G_BEGIN_DECLS
+
+#define GST_TYPE_TAG_DEMUX            (gst_tag_demux_get_type())
+#define GST_TAG_DEMUX(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_TAG_DEMUX,GstTagDemux))
+#define GST_TAG_DEMUX_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_TAG_DEMUX,GstTagDemuxClass))
+#define GST_IS_TAG_DEMUX(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_TAG_DEMUX))
+#define GST_IS_TAG_DEMUX_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_TAG_DEMUX))
+
+typedef struct _GstTagDemux        GstTagDemux;
+typedef struct _GstTagDemuxClass   GstTagDemuxClass;
+typedef struct _GstTagDemuxPrivate GstTagDemuxPrivate;
+
+/**
+ * GstTagDemuxResult:
+ * @GST_TAG_DEMUX_RESULT_BROKEN_TAG: cannot parse tag, just skip it
+ * @GST_TAG_DEMUX_RESULT_AGAIN     : call again with less or more data
+ * @GST_TAG_DEMUX_RESULT_OK	   : parsed tag successfully
+ *
+ * Result values from the parse_tag virtual function.
+ */
+typedef enum {
+  GST_TAG_DEMUX_RESULT_BROKEN_TAG,
+  GST_TAG_DEMUX_RESULT_AGAIN,
+  GST_TAG_DEMUX_RESULT_OK
+} GstTagDemuxResult;
+
+struct _GstTagDemux
+{
+  GstElement element;
+
+  /* Minimum size required to identify a tag at the start and
+   * determine its total size (0 = not interested in start) */
+  guint         min_start_size;
+
+  /* Minimum size required to identify a tag at the end and
+   * determine its total size (0 = not interested in end) */
+  guint         min_end_size;
+
+  /* Prefer start tags over end tags (default: yes) */
+  gboolean      prefer_start_tag;
+
+  /*< private >*/
+  gpointer      reserved[GST_PADDING];
+  GstTagDemuxPrivate *priv;
+};
+
+/* Note: subclass must also add a sink pad template in its base_init */
+struct _GstTagDemuxClass 
+{
+  GstElementClass parent_class;
+
+  /* vtable */
+
+  /* Identify tag and determine the size required to parse the tag. Buffer
+   * may be larger than the specified minimum size. */
+  gboolean               (*identify_tag)  (GstTagDemux * demux,
+                                           GstBuffer   * buffer,
+                                           gboolean      start_tag,
+                                           guint       * tag_size);
+
+  /* Parse the tag. Buffer should be exactly the size determined by
+   * identify_tag() before. parse_tag() may change tag_size and return
+   * GST_TAG_DEMUX_RESULT_AGAIN to request a larger or smaller buffer.
+   * parse_tag() is also permitted to adjust tag_size to a smaller value
+   * and return GST_TAG_DEMUX_RESULT_OK. */
+  GstTagDemuxResult      (*parse_tag)     (GstTagDemux * demux,
+                                           GstBuffer   * buffer,
+                                           gboolean      start_tag,
+                                           guint       * tag_size,
+                                           GstTagList ** tags);
+
+  /*< private >*/
+  gpointer   reserved[GST_PADDING];
+};
+
+GType gst_tag_demux_get_type (void);
+
+G_END_DECLS
+
+#endif /* __GST_TAG_DEMUX_H__ */