flacparse: add documentation

docs/plugins/Makefile.am

@@ -126,6 +126,7 @@ EXTRA_HFILES = \
 	$(top_srcdir)/gst/aiff/aiffmux.h \
 	$(top_srcdir)/gst/audioparsers/gstaacparse.h \
 	$(top_srcdir)/gst/audioparsers/gstamrparse.h \
+	$(top_srcdir)/gst/audioparsers/gstflacparse.h \
 	$(top_srcdir)/gst/autoconvert/gstautoconvert.h \
 	$(top_srcdir)/gst/camerabin/gstcamerabin.h \
 	$(top_srcdir)/gst/dccp/gstdccpclientsink.h \

docs/plugins/gst-plugins-bad-plugins-docs.sgml

@@ -42,6 +42,7 @@
     <xi:include href="xml/element-dvdspu.xml" />
     <xi:include href="xml/element-faac.xml" />
     <xi:include href="xml/element-festival.xml" />
+    <xi:include href="xml/element-flacparse.xml" />
     <xi:include href="xml/element-fpsdisplaysink.xml" />
     <xi:include href="xml/element-input-selector.xml" />
     <xi:include href="xml/element-ivorbisdec.xml" />

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

@@ -407,6 +407,20 @@ FESTIVAL_DEFAULT_SERVER_PORT
 FESTIVAL_DEFAULT_TEXT_MODE
 </SECTION>
 
+<SECTION>
+<FILE>element-flacparse</FILE>
+<TITLE>flacparse</TITLE>
+GstFlacParse
+<SUBSECTION Standard>
+GstFlacParseClass
+GST_FLAC_PARSE
+GST_FLAC_PARSE_CLASS
+GST_IS_FLAC_PARSE
+GST_IS_FLAC_PARSE_CLASS
+GST_TYPE_FLAC_PARSE
+gst_flac_parse_get_type
+</SECTION>
+
 <SECTION>
 <FILE>element-fpsdisplaysink</FILE>
 <TITLE>fpsdisplaysink</TITLE>

gst/audioparsers/gstflacparse.c

@@ -1,6 +1,9 @@
 /* GStreamer
  *
  * Copyright (C) 2008 Sebastian Dröge <sebastian.droege@collabora.co.uk>.
+ * Copyright (C) 2009 Mark Nauwelaerts <mark.nauwelaerts@collabora.co.uk>
+ * Copyright (C) 2009 Nokia Corporation. All rights reserved.
+ *   Contact: Stefan Kost <stefan.kost@nokia.com>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -18,6 +21,34 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-flacparse
+ * @see_also: flacdec, oggdemux, vorbisparse
+ *
+ * The flacparse element will parse the header packets of the FLAC
+ * stream and put them as the streamheader in the caps. This is used in the
+ * multifdsink case where you want to stream live FLAC streams to multiple
+ * clients, each client has to receive the streamheaders first before they can
+ * consume the FLAC packets.
+ *
+ * This element also makes sure that the buffers that it pushes out are properly
+ * timestamped and that their offset and offset_end are set. The buffers that
+ * flacparse outputs have all of the metadata that oggmux expects to receive,
+ * which allows you to (for example) remux an ogg/flac or convert a native FLAC
+ * format file to an ogg bitstream.
+ *
+ * <refsect2>
+ * <title>Example pipelines</title>
+ * |[
+ * gst-launch -v filesrc location=sine.flac ! flacparse ! identity \
+ *            ! oggmux ! filesink location=sine-remuxed.ogg
+ * ]| This pipeline converts a native FLAC format file to an ogg bitstream.
+ * It also illustrates that the streamheader is set in the caps, and that each
+ * buffer has the timestamp, duration, offset, and offset_end set.
+ * </refsect2>
+ *
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

gst/audioparsers/gstflacparse.h

@@ -1,6 +1,9 @@
 /* GStreamer
  *
  * Copyright (C) 2008 Sebastian Dröge <sebastian.droege@collabora.co.uk>.
+ * Copyright (C) 2009 Mark Nauwelaerts <mark.nauwelaerts@collabora.co.uk>
+ * Copyright (C) 2009 Nokia Corporation. All rights reserved.
+ *   Contact: Stefan Kost <stefan.kost@nokia.com>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public