docs/random/company/gstparse - imx-gstreamer - Git at Google

 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 \) } } \)
	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 \) } } \)