Debian Codegraph @

docs/random/company/gstparse

raw
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