Document playbin.
authorTim-Philipp Müller <tim@centricular.net>
Tue, 15 Aug 2006 17:21:33 +0000 (17:21 +0000)
committerTim-Philipp Müller <tim@centricular.net>
Tue, 15 Aug 2006 17:21:33 +0000 (17:21 +0000)
Original commit message from CVS:
* docs/plugins/gst-plugins-base-plugins-docs.sgml:
* docs/plugins/gst-plugins-base-plugins-sections.txt:
* docs/plugins/gst-plugins-base-plugins.args:
* gst/playback/gstplaybin.c:
Document playbin.
* docs/plugins/inspect/plugin-adder.xml:
* docs/plugins/inspect/plugin-alsa.xml:
* docs/plugins/inspect/plugin-audioconvert.xml:
* docs/plugins/inspect/plugin-audiorate.xml:
* docs/plugins/inspect/plugin-audioresample.xml:
* docs/plugins/inspect/plugin-audiotestsrc.xml:
* docs/plugins/inspect/plugin-cdparanoia.xml:
* docs/plugins/inspect/plugin-decodebin.xml:
* docs/plugins/inspect/plugin-ffmpegcolorspace.xml:
* docs/plugins/inspect/plugin-gnomevfs.xml:
* docs/plugins/inspect/plugin-ogg.xml:
* docs/plugins/inspect/plugin-pango.xml:
* docs/plugins/inspect/plugin-playbin.xml:
* docs/plugins/inspect/plugin-subparse.xml:
* docs/plugins/inspect/plugin-tcp.xml:
* docs/plugins/inspect/plugin-theora.xml:
* docs/plugins/inspect/plugin-typefindfunctions.xml:
* docs/plugins/inspect/plugin-video4linux.xml:
* docs/plugins/inspect/plugin-videorate.xml:
* docs/plugins/inspect/plugin-videoscale.xml:
* docs/plugins/inspect/plugin-videotestsrc.xml:
* docs/plugins/inspect/plugin-volume.xml:
* docs/plugins/inspect/plugin-vorbis.xml:
* docs/plugins/inspect/plugin-ximagesink.xml:
* docs/plugins/inspect/plugin-xvimagesink.xml:
Update to CVS version.

30 files changed:
ChangeLog
docs/plugins/gst-plugins-base-plugins-docs.sgml
docs/plugins/gst-plugins-base-plugins-sections.txt
docs/plugins/gst-plugins-base-plugins.args
docs/plugins/inspect/plugin-adder.xml
docs/plugins/inspect/plugin-alsa.xml
docs/plugins/inspect/plugin-audioconvert.xml
docs/plugins/inspect/plugin-audiorate.xml
docs/plugins/inspect/plugin-audioresample.xml
docs/plugins/inspect/plugin-audiotestsrc.xml
docs/plugins/inspect/plugin-cdparanoia.xml
docs/plugins/inspect/plugin-decodebin.xml
docs/plugins/inspect/plugin-ffmpegcolorspace.xml
docs/plugins/inspect/plugin-gnomevfs.xml
docs/plugins/inspect/plugin-ogg.xml
docs/plugins/inspect/plugin-pango.xml
docs/plugins/inspect/plugin-playbin.xml
docs/plugins/inspect/plugin-subparse.xml
docs/plugins/inspect/plugin-tcp.xml
docs/plugins/inspect/plugin-theora.xml
docs/plugins/inspect/plugin-typefindfunctions.xml
docs/plugins/inspect/plugin-video4linux.xml
docs/plugins/inspect/plugin-videorate.xml
docs/plugins/inspect/plugin-videoscale.xml
docs/plugins/inspect/plugin-videotestsrc.xml
docs/plugins/inspect/plugin-volume.xml
docs/plugins/inspect/plugin-vorbis.xml
docs/plugins/inspect/plugin-ximagesink.xml
docs/plugins/inspect/plugin-xvimagesink.xml
gst/playback/gstplaybin.c

index dc30423..844ada3 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,38 @@
+2006-08-15  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * docs/plugins/gst-plugins-base-plugins-docs.sgml:
+       * docs/plugins/gst-plugins-base-plugins-sections.txt:
+       * docs/plugins/gst-plugins-base-plugins.args:
+       * gst/playback/gstplaybin.c:
+         Document playbin.
+         
+       * docs/plugins/inspect/plugin-adder.xml:
+       * docs/plugins/inspect/plugin-alsa.xml:
+       * docs/plugins/inspect/plugin-audioconvert.xml:
+       * docs/plugins/inspect/plugin-audiorate.xml:
+       * docs/plugins/inspect/plugin-audioresample.xml:
+       * docs/plugins/inspect/plugin-audiotestsrc.xml:
+       * docs/plugins/inspect/plugin-cdparanoia.xml:
+       * docs/plugins/inspect/plugin-decodebin.xml:
+       * docs/plugins/inspect/plugin-ffmpegcolorspace.xml:
+       * docs/plugins/inspect/plugin-gnomevfs.xml:
+       * docs/plugins/inspect/plugin-ogg.xml:
+       * docs/plugins/inspect/plugin-pango.xml:
+       * docs/plugins/inspect/plugin-playbin.xml:
+       * docs/plugins/inspect/plugin-subparse.xml:
+       * docs/plugins/inspect/plugin-tcp.xml:
+       * docs/plugins/inspect/plugin-theora.xml:
+       * docs/plugins/inspect/plugin-typefindfunctions.xml:
+       * docs/plugins/inspect/plugin-video4linux.xml:
+       * docs/plugins/inspect/plugin-videorate.xml:
+       * docs/plugins/inspect/plugin-videoscale.xml:
+       * docs/plugins/inspect/plugin-videotestsrc.xml:
+       * docs/plugins/inspect/plugin-volume.xml:
+       * docs/plugins/inspect/plugin-vorbis.xml:
+       * docs/plugins/inspect/plugin-ximagesink.xml:
+       * docs/plugins/inspect/plugin-xvimagesink.xml:
+         Update to CVS version.
+
 2006-08-14  Tim-Philipp Müller  <tim at centricular dot net>
 
        * gst/playback/gstplaybin.c: (gst_play_bin_class_init),
index 199e726..dda9ba1 100644 (file)
@@ -25,6 +25,7 @@
     <xi:include href="xml/element-gnomevfssink.xml" />
     <xi:include href="xml/element-gnomevfssrc.xml" />
     <xi:include href="xml/element-multifdsink.xml" />
+    <xi:include href="xml/element-playbin.xml" />
     <xi:include href="xml/element-tcpserversink.xml" />
     <xi:include href="xml/element-theoradec.xml" />
     <xi:include href="xml/element-theoraenc.xml" />
index e86dbc3..9d21498 100644 (file)
@@ -200,6 +200,20 @@ gst_gnome_vfs_src_get_type
 </SECTION>
 
 <SECTION>
+<FILE>element-playbin</FILE>
+<TITLE>playbin</TITLE>
+GstPlayBin
+<SUBSECTION Standard>
+GST_PLAY_BIN
+GST_PLAY_BIN_CLASS
+GST_IS_GST_PLAY_BIN
+GST_IS_GST_PLAY_BIN_CLASS
+GST_TYPE_GST_PLAY_BIN
+GstPlayBinClass
+gst_play_bin_get_type
+</SECTION>
+
+<SECTION>
 <FILE>element-tcpserversink</FILE>
 <TITLE>tcpserversink</TITLE>
 GstTCPServerSink
index 9e3faa3..cfb535c 100644 (file)
 <ARG>
 <NAME>GstPlayBin::volume</NAME>
 <TYPE>gdouble</TYPE>
-<RANGE>[0,4]</RANGE>
+<RANGE>[0,10]</RANGE>
 <FLAGS>rw</FLAGS>
 <NICK>volume</NICK>
 <BLURB>volume.</BLURB>
 </ARG>
 
 <ARG>
+<NAME>GstPlayBin::connection-speed</NAME>
+<TYPE>guint</TYPE>
+<RANGE></RANGE>
+<FLAGS>rw</FLAGS>
+<NICK>Connection Speed</NICK>
+<BLURB>Network connection speed in kbps (0 = unknown).</BLURB>
+<DEFAULT>0</DEFAULT>
+</ARG>
+
+<ARG>
 <NAME>GstAudiorate::add</NAME>
 <TYPE>guint64</TYPE>
 <RANGE></RANGE>
 <DEFAULT>NULL</DEFAULT>
 </ARG>
 
+<ARG>
+<NAME>GstTheoraParse::synchronization-points</NAME>
+<TYPE>GValueArray</TYPE>
+<RANGE></RANGE>
+<FLAGS>rw</FLAGS>
+<NICK>Synchronization points</NICK>
+<BLURB>An array of (granuletime, buffertime) pairs.</BLURB>
+<DEFAULT></DEFAULT>
+</ARG>
+
index faf0564..d5d47cb 100644 (file)
@@ -3,10 +3,10 @@
   <description>Adds multiple streams</description>
   <filename>../../gst/adder/.libs/libgstadder.so</filename>
   <basename>libgstadder.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 51602e6..533a226 100644 (file)
@@ -3,10 +3,10 @@
   <description>ALSA plugin library</description>
   <filename>../../ext/alsa/.libs/libgstalsa.so</filename>
   <basename>libgstalsa.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 2e3dad8..db32468 100644 (file)
@@ -3,10 +3,10 @@
   <description>Convert audio to different formats</description>
   <filename>../../gst/audioconvert/.libs/libgstaudioconvert.so</filename>
   <basename>libgstaudioconvert.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index d2483ea..93f3cad 100644 (file)
@@ -3,10 +3,10 @@
   <description>Adjusts audio frames</description>
   <filename>../../gst/audiorate/.libs/libgstaudiorate.so</filename>
   <basename>libgstaudiorate.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index fc3ade1..ab0f440 100644 (file)
@@ -3,10 +3,10 @@
   <description>Resamples audio</description>
   <filename>../../gst/audioresample/.libs/libgstaudioresample.so</filename>
   <basename>libgstaudioresample.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index ddae94d..af302fd 100644 (file)
@@ -3,10 +3,10 @@
   <description>Creates audio test signals of given frequency and volume</description>
   <filename>../../gst/audiotestsrc/.libs/libgstaudiotestsrc.so</filename>
   <basename>libgstaudiotestsrc.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 747c0a2..f5c7eb1 100644 (file)
@@ -3,10 +3,10 @@
   <description>Read audio from CD in paranoid mode</description>
   <filename>../../ext/cdparanoia/.libs/libgstcdparanoia.so</filename>
   <basename>libgstcdparanoia.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>GPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index ee8c811..4a003f7 100644 (file)
@@ -3,10 +3,10 @@
   <description>decoder bin</description>
   <filename>../../gst/playback/.libs/libgstdecodebin.so</filename>
   <basename>libgstdecodebin.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 02d7962..321dcab 100644 (file)
@@ -3,7 +3,7 @@
   <description>colorspace conversion copied from FFMpeg 0.4.9-pre1</description>
   <filename>../../gst/ffmpegcolorspace/.libs/libgstffmpegcolorspace.so</filename>
   <basename>libgstffmpegcolorspace.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
   <package>FFMpeg</package>
index f2b12dd..509d116 100644 (file)
@@ -3,10 +3,10 @@
   <description>elements to read from and write to  Gnome-VFS uri's</description>
   <filename>../../ext/gnomevfs/.libs/libgstgnomevfs.so</filename>
   <basename>libgstgnomevfs.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 5e5337b..92d792c 100644 (file)
@@ -3,10 +3,10 @@
   <description>ogg stream manipulation (info about ogg: http://xiph.org)</description>
   <filename>../../ext/ogg/.libs/libgstogg.so</filename>
   <basename>libgstogg.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 74eaf96..6e38763 100644 (file)
@@ -3,10 +3,10 @@
   <description>Pango-based text rendering and overlay</description>
   <filename>../../ext/pango/.libs/libgstpango.so</filename>
   <basename>libgstpango.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 0411b16..116812c 100644 (file)
@@ -3,10 +3,10 @@
   <description>player bin</description>
   <filename>../../gst/playback/.libs/libgstplaybin.so</filename>
   <basename>libgstplaybin.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 18d35f2..bf77a8c 100644 (file)
@@ -3,10 +3,10 @@
   <description>Subtitle parsing</description>
   <filename>../../gst/subparse/.libs/libgstsubparse.so</filename>
   <basename>libgstsubparse.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 91f941f..199ff4b 100644 (file)
@@ -3,10 +3,10 @@
   <description>transfer data over the network via TCP</description>
   <filename>../../gst/tcp/.libs/libgsttcp.so</filename>
   <basename>libgsttcp.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 2191f32..694ac9e 100644 (file)
@@ -3,10 +3,10 @@
   <description>Theora plugin library</description>
   <filename>../../ext/theora/.libs/libgsttheora.so</filename>
   <basename>libgsttheora.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index ae04cbb..c4e40c5 100644 (file)
@@ -3,10 +3,10 @@
   <description>default typefind functions</description>
   <filename>../../gst/typefind/.libs/libgsttypefindfunctions.so</filename>
   <basename>libgsttypefindfunctions.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
 
index ee34cb7..26a4efe 100644 (file)
@@ -3,10 +3,10 @@
   <description>elements for Video 4 Linux</description>
   <filename>../../sys/v4l/.libs/libgstvideo4linux.so</filename>
   <basename>libgstvideo4linux.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 4c63a23..4d4b21a 100644 (file)
@@ -3,10 +3,10 @@
   <description>Adjusts video frames</description>
   <filename>../../gst/videorate/.libs/libgstvideorate.so</filename>
   <basename>libgstvideorate.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 2117c48..a4d70c7 100644 (file)
@@ -3,10 +3,10 @@
   <description>Resizes video</description>
   <filename>../../gst/videoscale/.libs/libgstvideoscale.so</filename>
   <basename>libgstvideoscale.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index a831279..8c51bc4 100644 (file)
@@ -3,10 +3,10 @@
   <description>Creates a test video stream</description>
   <filename>../../gst/videotestsrc/.libs/libgstvideotestsrc.so</filename>
   <basename>libgstvideotestsrc.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 843f58e..424dea5 100644 (file)
@@ -3,10 +3,10 @@
   <description>plugin for controlling audio volume</description>
   <filename>../../gst/volume/.libs/libgstvolume.so</filename>
   <basename>libgstvolume.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index a0138b7..c74053b 100644 (file)
@@ -3,10 +3,10 @@
   <description>Vorbis plugin library</description>
   <filename>../../ext/vorbis/.libs/libgstvorbis.so</filename>
   <basename>libgstvorbis.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 268a563..70b4fb6 100644 (file)
@@ -3,10 +3,10 @@
   <description>X11 video output element based on standard Xlib calls</description>
   <filename>../../sys/ximage/.libs/libgstximagesink.so</filename>
   <basename>libgstximagesink.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index 3f70cdc..882b7c4 100644 (file)
@@ -3,10 +3,10 @@
   <description>XFree86 video output plugin using Xv extension</description>
   <filename>../../sys/xvimage/.libs/libgstxvimagesink.so</filename>
   <basename>libgstxvimagesink.so</basename>
-  <version>0.10.9</version>
+  <version>0.10.9.1</version>
   <license>LGPL</license>
   <source>gst-plugins-base</source>
-  <package>GStreamer Base Plug-ins source release</package>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
index c80c092..a4af2ad 100644 (file)
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-playbin
+ *
+ * <refsect2>
+ * <para>
+ * Playbin provides a stand-alone everything-in-one abstraction for an
+ * audio and/or video player.
+ * </para>
+ * <para>
+ * It can handle both audio and video files and features 
+ * <itemizedlist>
+ * <listitem>
+ * automatic file type recognition and based on that automatic
+ * selection and usage of the right audio/video/subtitle demuxers/decoders
+ * </listitem>
+ * <listitem>
+ * visualisations for audio files
+ * </listitem>
+ * <listitem>
+ * subtitle support for video files
+ * </listitem>
+ * <listitem>
+ * stream selection between different audio/subtitles streams
+ * </listitem>
+ * <listitem>
+ * meta info (tag) extraction
+ * </listitem>
+ * <listitem>
+ * easy access to the last video frame
+ * </listitem>
+ * <listitem>
+ * buffering when playing streams over a network
+ * </listitem>
+ * <listitem>
+ * volume control
+ * </listitem>
+ * </itemizedlist>
+ * </para>
+ * <title>Usage</title>
+ * <para>
+ * A playbin element can be created just like any other element using
+ * gst_element_factory_make(). The file/URI to play should be set via the "uri"
+ * property. This must be an absolute URI, relative file paths are not allowed.
+ * Example URIs are file:///home/joe/movie.avi or http://www.joedoe.com/foo.ogg
+ * </para>
+ * <para>
+ * Playbin is a #GstPipeline. It will notify the application of everything
+ * that's happening (errors, end of stream, tags found, state changes, etc.)
+ * by posting messages on its #GstBus. The application needs to watch the
+ * bus.
+ * </para>
+ * <para>
+ * Playback can be initiated by setting the element to PLAYING state using
+ * gst_element_set_state(). Note that the state change will take place in
+ * the background in a separate thread, when the function returns playback
+ * is probably not happening yet and any errors might not have occured yet.
+ * Applications using playbin should ideally be written to deal with things
+ * completely asynchroneous.
+ * </para>
+ * <para>
+ * When playback has finished (an EOS message has been received on the bus)
+ * or an error has occured (an ERROR message has been received on the bus) or
+ * the user wants to play a different track, playbin should be set back to
+ * READY or NULL state, then the "uri" property should be set to the new
+ * location and then playbin be set to PLAYING state again.
+ * </para>
+ * <para>
+ * Seeking can be done using gst_element_seek_simple() or gst_element_seek()
+ * on the playbin element. Again, the seek will not be executed
+ * instantaneously, but will be done in a background thread. When the seek
+ * call returns the seek will most likely still be in process. An application
+ * may wait for the seek to finish (or fail) using gst_element_get_state() with
+ * -1 as the timeout, but this will block the user interface and is not
+ * recommended at all.
+ * </para>
+ * <para>
+ * Applications may query the current position and duration of the stream
+ * via gst_element_query_position() and gst_element_query_duration() and
+ * setting the format passed to GST_FORMAT_TIME. If the query was successful,
+ * the duration or position will have been returned in units of nanoseconds.
+ * </para>
+ * <title>Advanced Usage: specifying the audio and video sink</title>
+ * <para>
+ * By default, if no audio sink or video sink has been specified via the
+ * "audio-sink" or "video-sink" property, playbin will use the autoaudiosink
+ * and autovideosink elements to find the first-best available output method.
+ * This should work in most cases, but is not always desirable. Often either
+ * the user or application might want to specify more explicitly what to use
+ * for audio and video output.
+ * </para>
+ * <para>
+ * If the application wants more control over how audio or video should be
+ * output, it may create the audio/video sink elements itself (for example
+ * using gst_element_factory_make()) and provide them to playbin using the
+ * "audio-sink" or "video-sink" property.
+ * </para>
+ * <para>
+ * GNOME-based applications, for example, will usually want to create
+ * gconfaudiosink and gconfvideosink elements and make playbin use those,
+ * so that output happens to whatever the user has configured in the GNOME
+ * Multimedia System Selector confinguration dialog.
+ * </para>
+ * <para>
+ * The sink elements do not necessarily need to be ready-made sinks. It is
+ * possible to create container elements that look like a sink to playbin,
+ * but in reality contain a number of custom elements linked together. This
+ * can be achieved by creating a #GstBin and putting elements in there and
+ * linking them, and then creating a sink #GstGhostPad for the bin and pointing
+ * it to the sink pad of the first element within the bin. This can be used
+ * for a number of purposes, for example to force output to a particular
+ * format or to modify or observe the data before it is output.
+ * </para>
+ * <para>
+ * It is also possible to 'suppress' audio and/or video output by using
+ * 'fakesink' elements (or capture it from there using the fakesink element's
+ * "handoff" signal, which, nota bene, is fired from the streaming thread!).
+ * </para>
+ * <title>Retrieving Tags and Other Meta Data</title>
+ * <para>
+ * Most of the common meta data (artist, title, etc.) can be retrieved by
+ * watching for TAG messages on the pipeline's bus (see above).
+ * </para>
+ * <para>
+ * Other more specific meta information like width/height/framerate of video
+ * streams or samplerate/number of channels of audio streams can be obtained
+ * using the "stream-info" property, which will return a GList of stream info
+ * objects, one for each stream. These are opaque objects that can only be
+ * accessed via the standard GObject property interface, ie. g_object_get().
+ * Each stream info object has the following properties:
+ * <itemizedlist>
+ * <listitem>"object" (GstObject) (the decoder source pad usually)</listitem>
+ * <listitem>"type" (enum) (if this is an audio/video/subtitle stream)</listitem>
+ * <listitem>"decoder" (string) (name of decoder used to decode this stream)</listitem>
+ * <listitem>"mute" (boolean) (to mute or unmute this stream)</listitem>
+ * <listitem>"caps" (GstCaps) (caps of the decoded stream)</listitem>
+ * <listitem>"language-code" (string) (ISO-639 language code for this stream, mostly used for audio/subtitle streams)</listitem>
+ * <listitem>"codec" (string) (format this stream was encoded in)</listitem>
+ * </itemizedlist>
+ * Stream information from the stream-info properties is best queried once
+ * playbin has changed into PAUSED or PLAYING state (which can be detected
+ * via a state-changed message on the bus where old_state=READY and
+ * new_state=PAUSED), since before that the list might not be complete yet or
+ * not contain all available information (like language-codes).
+ * </para>
+ * <title>Embedding the video window in your application</title>
+ * <para>
+ * By default, playbin (or rather the video sinks used) will create their own
+ * window. Applications will usually want to force output to a window of their
+ * own, however. This can be done using the GstXOverlay interface, which most
+ * video sinks implement. See the documentation there for more details.
+ * </para>
+ * <title>Specifying which CD/DVD device to use</title>
+ * <para>
+ * The device to use for CDs/DVDs needs to be set on the source element
+ * playbin creates before it is opened. The only way to do this at the moment
+ * is to connect to playbin's "notify::source" signal, which will be emitted
+ * by playbin when it has created the source element for a particular URI.
+ * In the signal callback you can check if the source element has a "device"
+ * property and set it appropriately. In future ways might be added to specify
+ * the device as part of the URI, but at the time of writing this is not
+ * possible yet.
+ * </para>
+ * <title>Examples</title>
+ * <para>
+ * Here is a simple pipeline to play back a video or audio file:
+ * <programlisting>
+ * gst-launch -v playbin uri=file:///path/to/somefile.avi
+ * </programlisting>
+ * This will play back the given AVI video file, given that the video and
+ * audio decoders required to decode the content are installed. Since no
+ * special audio sink or video sink is supplied (not possible via gst-launch),
+ * playbin will try to find a suitable audio and video sink automatically
+ * using the autoaudiosink and autovideosink elements.
+ * </para>
+ * <para>
+ * Here is a another pipeline to play track 4 of an audio CD:
+ * <programlisting>
+ * gst-launch -v playbin uri=cdda://4
+ * </programlisting>
+ * This will play back track 4 on an audio CD in your disc drive (assuming
+ * the drive is detected automatically by the plugin).
+ * </para>
+ * <para>
+ * Here is a another pipeline to play title 1 of a DVD:
+ * <programlisting>
+ * gst-launch -v playbin uri=dvd://1
+ * </programlisting>
+ * This will play back title 1 of a DVD in your disc drive (assuming
+ * the drive is detected automatically by the plugin).
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif