diff -r 9b2c3c7a1a9c -r 567bb019e3e3 gst_plugins_base/gst/playback/README
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gst_plugins_base/gst/playback/README	Tue Aug 31 15:30:33 2010 +0300
@@ -0,0 +1,91 @@
+decodebin:
+
+  A bin with a sinkpad that decodes the data into raw formats. It works by sending
+  the input data through a typefind element and then recursively autoplugs elements 
+  from the registry until a raw format is obtained. It will then create a new ghostpad
+  on itself to signal the app of the new pad. 
+
+  Decodebin will also remove pads when they are removed from the stream.
+
+  TODO
+   - reuse of decoderbin, cleanup in READY state
+   - threading after demuxing?
+   - new_media events should be handled.
+   - caching of elements.
+   - abstract more elements, pads (typefind, ...);
+
+   The autoplugging happens as follows:
+
+   1) typefind is added internally to the bin.
+   2) the have_type signal is connected to typefind.
+   3) in the have_type callback the close_pad_link function is called
+   4) close_pad_link checks the type on the pad, if it is raw, a ghostpad
+      is created and autoplugging for that pad stops.
+   5) if the type of the pad is not raw, a list of possible elements that
+      can connect to this type is generated in find_compatibles.
+   6) try_to_link_1 with the element list is called. The function will loop
+      over the element list and will try to connect one of the elements to
+      the pad. If the link works, a call is made to close_link.
+   7) close_link loops over all the source pads of the element and 
+      recursively calls 4) for any ALWAYS pad. For elements with
+      a SOMETIMES pad, a structure is set up and is passed to the callback
+      of the new_pad signal.
+   8) in the new_pad callback, 4) is called to try to autoplug the
+      new pad.
+
+
+playbasebin:
+
+  A bin with an uri property. It will find the right source element from the registry
+  and connect a decoderbin to it. When going to the PAUSED state, it will iterate the
+  decoderbin and listen for new pad signals from it. It will connect a queue to each
+  new pad and will iterate the decoderbin until one of the queues is filled. It is
+  assumed that by that time all the streams will be found so that when leaving the
+  PAUSED state, one can query the number of streams in the media file with the given
+  uri.
+
+  Playbasebin internally groups related streams together in a GstPlayBaseGroup. This
+  is particulary important for chained oggs. Initially, a new group is created in 
+  the 'building' state. All new streams will be added to the building group until
+  no-more-pads is signaled or one of the preroll queues overflows. When this happens,
+  the group is commited to a list of groups ready for playback. PlaybaseBin will then
+  attach a padprobe to each stream to figure out when it finished. It will remove
+  the current group and install the next playable group, then.
+
+  Before going to the PLAYING state, it is possible to connect a custom element to
+  each of the streams. To do that, you have to add the element to the bin and then
+  connect the pad(s) from the stream(s). You do not have to add the elements in
+  a thread, the bin will take care of then when it's needed. You are allowed to use
+  threads inside the elements, of course.
+  The bin tries to be smart and doesn't add a queue when there is only one possible 
+  stream.
+
+  
+  TODO
+  - reuse, cleanup in ready state
+  - when the first pad is closed, it's possible that another dynamic element is
+    added somewhere so that we need a queue for the first pad as well.
+
+
+playbin:
+  
+   Extends playbasebin, sets up default audiosink and videosink for first audio/video
+   stream detected. implements seeking and querying on the configured sinks.
+
+   It also waits for new notifications from playbasebin about any new groups that are
+   becomming active. It then disconnects the sinks and reconnects them to the new
+   pads in the group.
+
+   TODO
+   - reuse, refcounting, cleanup in READY state
+   - be smarter about replugging the sinks instead of removing them and readding them.
+   - Do not crap out when the audio device is in use.
+
+
+general
+
+   TODO
+   - playlist support. maybe use a playlist bin that streams the contents of the
+     playlist on a pad, interleaved with new_media events. Also add a tuner 
+     interface while we're at it.
+