| 1 |
GstParse |
| 2 |
======== |
| 3 |
|
| 4 |
This document describes how GstParse works. GstParse is the infrastructure used |
| 5 |
to describe pipelines \(or parts thereof) as a string. This powerful yet easy |
| 6 |
language is for example by the gst-launch command-line utility or in the GConf |
| 7 |
keys that are used by various applications, such as Rhythmbox or Gst-Player. |
| 8 |
\(You can find these keys in /system/gstreamer/default in GConf) |
| 9 |
|
| 10 |
The following examples will show commands for gst-launch. Please note that some |
| 11 |
characters need to be escaped when the pipeline is written in the shell as |
| 12 |
gst-launch command. |
| 13 |
|
| 14 |
If you want to debug the GstParse part of an application, you can start it with |
| 15 |
the --gst-mask=0x10000 command line option. |
| 16 |
|
| 17 |
|
| 18 |
Basics |
| 19 |
====== |
| 20 |
|
| 21 |
Elements |
| 22 |
-------- |
| 23 |
The most basic thing you specify in a pipeline are elements. You add an element |
| 24 |
by the name of its type, so "filesrc" will add a file source and "identity" will |
| 25 |
add an identity element. |
| 26 |
Gstparse will put all these elements into a toplevel pipeline element. |
| 27 |
example:#> gst-launch filesrc identity |
| 28 |
This adds a filesrc and an identity element to a pipeline. Of course this |
| 29 |
pipeline will not run, because the elements are not yet connected. |
| 30 |
|
| 31 |
Properties |
| 32 |
---------- |
| 33 |
You can set element properties by specifying them directly after the element in |
| 34 |
the form name=value \(you need to escape here) or name="value" \(you only need to |
| 35 |
escape the " sign. |
| 36 |
example:#> gst-launch filesrc name=source location="music.mp3" |
| 37 |
This adds a filesrc element with the name "source" pointing to the location |
| 38 |
music.mp3 to your pipeline. \(This pipeline doesn't work either.) |
| 39 |
It's a good idea to set the name property on important elements, because if they |
| 40 |
are referenced \(see below), they will be referenced by name and the name of an |
| 41 |
element is unspecified if it wasn't set before. |
| 42 |
Please note that not all properties can be set yet. You might get a warning like |
| 43 |
property "myproperty" in element myelement cannot be set |
| 44 |
In that case, please file a feature request. We can't guess all properties in |
| 45 |
advance. |
| 46 |
|
| 47 |
Bins |
| 48 |
---- |
| 49 |
If you want to add bins to your pipeline, you can do so by specifying |
| 50 |
<bintype> . ( <properties> <elements> ) |
| 51 |
in your pipeline. This adds a bin to your pipeline and puts all elements that |
| 52 |
are specified between the brackets inside this bin. You can specify properties |
| 53 |
of the bin directly after the opening bracket. |
| 54 |
There are to special bins: if you don't specify a bintype and no dot either, the |
| 55 |
type of the bin defaults to "bin". And you can use curly brackets { } to get a |
| 56 |
bin of type "thread". |
| 57 |
example:#> gst-launch \( { fakesrc pipeline . \( fakesink \) } \) |
| 58 |
This will put a fakesrc element inside a thread inside a bin and a fakesink into |
| 59 |
a pipeline element inside the thread inside the bin. |
| 60 |
Please note that this pipeline would not work, even if the elements were |
| 61 |
connected properly, because the pipeline only specifies one top level element, |
| 62 |
the element is not put inside a pipeline but returned directly. So if you don't |
| 63 |
want your elements be put into a pipeline, just add a bin of whatever type you |
| 64 |
wish around the pipeline. |
| 65 |
|
| 66 |
Links |
| 67 |
----- |
| 68 |
What would a pipeline be without the ability to link the elements? |
| 69 |
Well it's very easy. Just put the link sign, an exclamation mark, between two |
| 70 |
elements and they will be linked. |
| 71 |
example:#> gst-launch fakesrc ! fakesink |
| 72 |
This will put the two elements into a pipeline and connect the fakesrc to the |
| 73 |
fakesink. This is the first pipeline that should run - and run it will until you |
| 74 |
terminate it. |
| 75 |
You can't however control which pads are linked, you can reference the pad\(s) |
| 76 |
you want to connect by name with a dot before the name. |
| 77 |
example:#> gst-launch fakesrc .src ! fakesink |
| 78 |
example:#> gst-launch fakesrc ! .sink fakesink |
| 79 |
example:#> gst-launch fakesrc .src ! .sink fakesink |
| 80 |
These examples will all do the exact same thing as the example before. You have |
| 81 |
however referenced the pads you wanted to connect in different ways. |
| 82 |
Another way to reference is to reference the element you want to connect, too. |
| 83 |
In this case you have to add the element name before the dot. You can even not |
| 84 |
reference the pad and only the element name, to connect any pad. |
| 85 |
example:#> gst-launch fakesrc name=src fakesink name=sink src.src ! sink.sink |
| 86 |
example:#> gst-launch fakesrc name=src ! sink.sink fakesink name=sink |
| 87 |
example:#> gst-launch fakesrc name=src src. ! fakesink name=sink |
| 88 |
example:#> gst-launch fakesrc name=src fakesink name=sink src. ! sink. |
| 89 |
These examples all do the same as the other ones. Please note that we specified |
| 90 |
the element name property to be sure to reference the right element. |
| 91 |
In these examples you may have noticed, that an omitted element name on a link |
| 92 |
automatically means the element directly in front of / after the link is used |
| 93 |
to create the link to save you some typing work and that not specifying a pad |
| 94 |
name will automatically create 1 connection between the two elements. If more |
| 95 |
than one connection was possible you might end up surprised. |
| 96 |
You may even specify pad lists to connect elements. They are separated by |
| 97 |
commas. |
| 98 |
example:#> gst-launch fakesrc ! tee name=tee1 .src0,src1 ! .sink0, sink1 aggregator ! fakesink |
| 99 |
example:#> gst-launch fakesrc ! tee name=tee aggregator name=aggregator ! fakesink tee.src0,src1 ! aggregator.sink0, sink1 |
| 100 |
example:#> gst-launch fakesrc ! tee name=tee .src0 ! .sink0 aggregator name=aggregator ! fakesink tee.src1 ! aggregator.sink1 |
| 101 |
These will all do the same. They will connect the tee twice to the aggregator. |
| 102 |
|
| 103 |
|
| 104 |
Examples |
| 105 |
======== |
| 106 |
|
| 107 |
Audio playback |
| 108 |
-------------- |
| 109 |
The most common audio pipeline for playing back an mp3 file is this: |
| 110 |
example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! osssink |
| 111 |
|
| 112 |
You can however improve on this by adding visualization: |
| 113 |
example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! tee name=tee ! osssink tee.src%d ! goom ! colorspace ! xvideosink |
| 114 |
Note that the reference of the tee element has a pad named "src%d". This is as |
| 115 |
used by printf and is a useful way to specify request pads where you don't know |
| 116 |
how this pad is named. Yes, the pad name could have been omitted anyway. |
| 117 |
|
| 118 |
If you have jerky playback you might want to use this pipeline threaded so audio |
| 119 |
and video have less chance of problems and you have a little buffer: |
| 120 |
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 } |
| 121 |
Remember to put queues at thread boundaries or it will not work. |
| 122 |
|
| 123 |
Video playback |
| 124 |
-------------- |
| 125 |
The basic pipeline to playback a standard mpeg video would be this: |
| 126 |
example:#> gst-launch filesrc location=/path/to/file.mpeg ! mpegdemux name=demux ! mad ! osssink demux. ! mpeg2dec ! xvideosink |
| 127 |
|
| 128 |
Or using threads for better playback: |
| 129 |
example:#> gst-launch filesrc location=/path/to/file.mpeg ! mpegdemux name=demux ! { queue ! mad ! osssink } demux. ! { queue ! mpeg2dec ! xvideosink } |
| 130 |
|
| 131 |
For a DivX avi, this might work: |
| 132 |
example:#> gst-launch filesrc location=/path/to/file.avi ! avidemux name=demux ! { queue ! mad ! osssink } { demux. ! ffdec_msmpeg4 ! xvideosink } |
| 133 |
|
| 134 |
|
| 135 |
If these don't work the video might need different treatment. You should skip to |
| 136 |
the autoplugger part. |
| 137 |
Please be aware of the fact that the mpegdemux element uses pads that are not |
| 138 |
always available. GstParse will wait for them to become available and disable |
| 139 |
the elements that need to be connected by disabling their state until the link |
| 140 |
can be established. |
| 141 |
|
| 142 |
Autoplugging |
| 143 |
------------ |
| 144 |
You can also use the spider element for autoplugging. This will take care of |
| 145 |
selecting the right elements for you. Just use this pipeline for all your needs: |
| 146 |
example:#> gst-launch filesrc location=/path/to/anything ! spider name=spider ! { queue ! osssink } { spider. ! queue ! xvideosink } |
| 147 |
|
| 148 |
To throw you out |
| 149 |
---------------- |
| 150 |
Finally the current experimental pipeline that powers the gst-player specified |
| 151 |
as a simple (ahem...) command line: |
| 152 |
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 \) } } \) |
| 153 |
|
| 154 |
|
| 155 |
|
| 156 |
|
| 157 |
|
| 158 |
|
| 159 |
|
| 160 |
|
| 161 |
|
| 162 |
|
| 163 |
|
| 164 |
|
| 165 |
|
| 166 |
|