--- /dev/null
+GstParse
+========
+
+This document describes how GstParse works. GstParse is the infrastructure used
+to describe pipelines \(or parts thereof) as a string. This powerful yet easy
+language is for example by the gst-launch command-line utility or in the GConf
+keys that are used by various applications, such as Rhythmbox or Gst-Player.
+\(You can find these keys in /system/gstreamer/default in GConf)
+
+The following examples will show commands for gst-launch. Please note that some
+characters need to be escaped when the pipeline is written in the shell as
+gst-launch command.
+
+If you want to debug the GstParse part of an application, you can start it with
+the --gst-mask=0x10000 command line option.
+
+
+Basics
+======
+
+Elements
+--------
+The most basic thing you specify in a pipeline are elements. You add an element
+by the name of its type, so "filesrc" will add a file source and "identity" will
+add an identity element.
+Gstparse will put all these elements into a toplevel pipeline element.
+ example:#> gst-launch filesrc identity
+This adds a filesrc and an identity element to a pipeline. Of course this
+pipeline will not run, because the elements are not yet connected.
+
+Properties
+----------
+You can set element properties by specifying them directly after the element in
+the form name=value \(you need to escape here) or name="value" \(you only need to
+escape the " sign.
+ example:#> gst-launch filesrc name=source location="music.mp3"
+This adds a filesrc element with the name "source" pointing to the location
+music.mp3 to your pipeline. \(This pipeline doesn't work either.)
+It's a good idea to set the name property on important elements, because if they
+are referenced \(see below), they will be referenced by name and the name of an
+element is unspecified if it wasn't set before.
+Please note that not all properties can be set yet. You might get a warning like
+ property "myproperty" in element myelement cannot be set
+In that case, please file a feature request. We can't guess all properties in
+advance.
+
+Bins
+----
+If you want to add bins to your pipeline, you can do so by specifying
+ <bintype> . ( <properties> <elements> )
+in your pipeline. This adds a bin to your pipeline and puts all elements that
+are specified between the brackets inside this bin. You can specify properties
+of the bin directly after the opening bracket.
+There are to special bins: if you don't specify a bintype and no dot either, the
+type of the bin defaults to "bin". And you can use curly brackets { } to get a
+bin of type "thread".
+ example:#> gst-launch \( { fakesrc pipeline . \( fakesink \) } \)
+This will put a fakesrc element inside a thread inside a bin and a fakesink into
+a pipeline element inside the thread inside the bin.
+Please note that this pipeline would not work, even if the elements were
+connected properly, because the pipeline only specifies one top level element,
+the element is not put inside a pipeline but returned directly. So if you don't
+want your elements be put into a pipeline, just add a bin of whatever type you
+wish around the pipeline.
+
+Links
+-----
+What would a pipeline be without the ability to link the elements?
+Well it's very easy. Just put the link sign, an exclamation mark, between two
+elements and they will be linked.
+ example:#> gst-launch fakesrc ! fakesink
+This will put the two elements into a pipeline and connect the fakesrc to the
+fakesink. This is the first pipeline that should run - and run it will until you
+terminate it.
+You can't however control which pads are linked, you can reference the pad\(s)
+you want to connect by name with a dot before the name.
+ example:#> gst-launch fakesrc .src ! fakesink
+ example:#> gst-launch fakesrc ! .sink fakesink
+ example:#> gst-launch fakesrc .src ! .sink fakesink
+These examples will all do the exact same thing as the example before. You have
+however referenced the pads you wanted to connect in different ways.
+Another way to reference is to reference the element you want to connect, too.
+In this case you have to add the element name before the dot. You can even not
+reference the pad and only the element name, to connect any pad.
+ example:#> gst-launch fakesrc name=src fakesink name=sink src.src ! sink.sink
+ example:#> gst-launch fakesrc name=src ! sink.sink fakesink name=sink
+ example:#> gst-launch fakesrc name=src src. ! fakesink name=sink
+ example:#> gst-launch fakesrc name=src fakesink name=sink src. ! sink.
+These examples all do the same as the other ones. Please note that we specified
+the element name property to be sure to reference the right element.
+In these examples you may have noticed, that an omitted element name on a link
+automatically means the element directly in front of / after the link is used
+to create the link to save you some typing work and that not specifying a pad
+name will automatically create 1 connection between the two elements. If more
+than one connection was possible you might end up surprised.
+You may even specify pad lists to connect elements. They are seperated by
+commas.
+ example:#> gst-launch fakesrc ! tee name=tee1 .src0,src1 ! .sink0, sink1 aggregator ! fakesink
+ example:#> gst-launch fakesrc ! tee name=tee aggregator name=aggregator ! fakesink tee.src0,src1 ! aggregator.sink0, sink1
+ example:#> gst-launch fakesrc ! tee name=tee .src0 ! .sink0 aggregator name=aggregator ! fakesink tee.src1 ! aggregator.sink1
+These will all do the same. They will connect the tee twice to the aggregator.
+
+
+Examples
+========
+
+Audio playback
+--------------
+The most common audio pipeline for playing back an mp3 file is this:
+ example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! osssink
+
+You can however improve on this by adding visualization:
+ example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! tee name=tee ! osssink tee.src%d ! goom ! colorspace ! xvideosink
+Note that the reference of the tee element has a pad named "src%d". This is as
+used by printf and is a useful way to specify request pads where you don't know
+how this pad is named. Yes, the pad name could have been omitted anyway.
+
+If you have jerky playback you might want to use this pipeline threaded so audio
+and video have less chance of problems and you have a little buffer:
+ example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! tee name=tee ! { queue ! osssink } tee name=tee { ! queue ! osssink } { tee. ! queue ! goom ! colorspace ! xvideosink }
+Remember to put queues at thread boundaries or it will not work.
+
+Video playback
+--------------
+The basic pipeline to playback a standard mpeg video would be this:
+ example:#> gst-launch filesrc location=/path/to/file.mpeg ! mpegdemux name=demux ! mad ! osssink demux. ! mpeg2dec ! xvideosink
+
+Or using threads for better playback:
+ example:#> gst-launch filesrc location=/path/to/file.mpeg ! mpegdemux name=demux ! { queue ! mad ! osssink } demux. ! { queue ! mpeg2dec ! xvideosink }
+
+For a DivX avi, this might work:
+ example:#> gst-launch filesrc location=/path/to/file.avi ! avidemux name=demux ! { queue ! mad ! osssink } { demux. ! ffdec_msmpeg4 ! xvideosink }
+
+
+If these don't work the video might need different treatment. You should skip to
+the autoplugger part.
+Please be aware of the fact that the mpegdemux element uses pads that are not
+always available. GstParse will wait for them to become available and disable
+the elements that need to be connected by disabling their state until the link
+can be established.
+
+Autoplugging
+------------
+You can also use the spider element for autoplugging. This will take care of
+selecting the right elements for you. Just use this pipeline for all your needs:
+ example:#> gst-launch filesrc location=/path/to/anything ! spider name=spider ! { queue ! osssink } { spider. ! queue ! xvideosink }
+
+To throw you out
+----------------
+Finally the current experimental pipeline that powers the gst-player specified
+as a simple (ahem...) command line:
+ example:#> gst-launch pipeline. \( { filesrc location=/path/to/anything ! spider name=spider ! { queue ! volume ! \( tee name=tee ! { queue ! \( goom \) ! colorspace ! \( xvideosink \) } tee. ! { queue ! \( osssink \) } \) } spider. ! { queue ! colorspace \( xvideosink \) } } \)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
projects / platform / upstream / gstreamer.git / commitdiff