Split out documentation into subfolders.
[platform/upstream/gstreamer.git] / markdown / manual / appendix / programs.md
1 ---
2 title: Programs
3 ...
4
5 # Programs
6
7 ## `gst-launch`
8
9 This is a tool that will construct pipelines based on a command-line
10 syntax.
11
12 A simple commandline looks like:
13
14 ```
15 gst-launch filesrc location=hello.mp3 ! mad ! audioresample ! osssink
16
17 ```
18
19 A more complex pipeline looks like:
20
21 ```
22 gst-launch filesrc location=redpill.vob ! dvddemux name=demux \
23  demux.audio_00 ! queue ! a52dec ! audioconvert ! audioresample ! osssink \
24  demux.video_00 ! queue ! mpeg2dec ! videoconvert ! xvimagesink
25
26 ```
27
28 You can also use the parser in you own code. GStreamer provides a
29 function gst\_parse\_launch () that you can use to construct a pipeline.
30 The following program lets you create an MP3 pipeline using the
31 gst\_parse\_launch () function:
32
33 ``` c
34 #include <gst/gst.h>
35
36 int
37 main (int argc, char *argv[])
38 {
39   GstElement *pipeline;
40   GstElement *filesrc;
41   GstMessage *msg;
42   GstBus *bus;
43   GError *error = NULL;
44
45   gst_init (&argc, &argv);
46
47   if (argc != 2) {
48     g_print ("usage: %s <filename>\n", argv[0]);
49     return -1;
50   }
51
52   pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &error);
53   if (!pipeline) {
54     g_print ("Parse error: %s\n", error->message);
55     exit (1);
56   }
57
58   filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
59   g_object_set (filesrc, "location", argv[1], NULL);
60   g_object_unref (filesrc);
61
62   gst_element_set_state (pipeline, GST_STATE_PLAYING);
63
64   bus = gst_element_get_bus (pipeline);
65
66   /* wait until we either get an EOS or an ERROR message. Note that in a real
67    * program you would probably not use gst_bus_poll(), but rather set up an
68    * async signal watch on the bus and run a main loop and connect to the
69    * bus's signals to catch certain messages or all messages */
70   msg = gst_bus_poll (bus, GST_MESSAGE_EOS | GST_MESSAGE_ERROR, -1);
71
72   switch (GST_MESSAGE_TYPE (msg)) {
73     case GST_MESSAGE_EOS: {
74       g_print ("EOS\n");
75       break;
76     }
77     case GST_MESSAGE_ERROR: {
78       GError *err = NULL; /* error to show to users                 */
79       gchar *dbg = NULL;  /* additional debug string for developers */
80
81       gst_message_parse_error (msg, &err, &dbg);
82       if (err) {
83         g_printerr ("ERROR: %s\n", err->message);
84         g_error_free (err);
85       }
86       if (dbg) {
87         g_printerr ("[Debug details: %s]\n", dbg);
88         g_free (dbg);
89       }
90     }
91     default:
92       g_printerr ("Unexpected message of type %d", GST_MESSAGE_TYPE (msg));
93       break;
94   }
95   gst_message_unref (msg);
96
97   gst_element_set_state (pipeline, GST_STATE_NULL);
98   gst_object_unref (pipeline);
99   gst_object_unref (bus);
100
101   return 0;
102 }
103
104 ```
105
106 Note how we can retrieve the filesrc element from the constructed bin
107 using the element name.
108
109 ### Grammar Reference
110
111 The `gst-launch` syntax is processed by a flex/bison parser. This
112 section is intended to provide a full specification of the grammar; any
113 deviations from this specification is considered a bug.
114
115 #### Elements
116
117 ```
118           ... mad ...
119
120 ```
121
122 A bare identifier (a string beginning with a letter and containing only
123 letters, numbers, dashes, underscores, percent signs, or colons) will
124 create an element from a given element factory. In this example, an
125 instance of the "mad" MP3 decoding plugin will be created.
126
127 #### Links
128
129 ```
130           ... !sink ...
131
132 ```
133
134 An exclamation point, optionally having a qualified pad name (an the
135 name of the pad, optionally preceded by the name of the element) on both
136 sides, will link two pads. If the source pad is not specified, a source
137 pad from the immediately preceding element will be automatically chosen.
138 If the sink pad is not specified, a sink pad from the next element to be
139 constructed will be chosen. An attempt will be made to find compatible
140 pads. Pad names may be preceded by an element name, as in
141 `my_element_name.sink_pad`.
142
143 #### Properties
144
145 ```
146           ... location="http://gstreamer.net" ...
147
148 ```
149
150 The name of a property, optionally qualified with an element name, and a
151 value, separated by an equals sign, will set a property on an element.
152 If the element is not specified, the previous element is assumed.
153 Strings can optionally be enclosed in quotation marks. Characters in
154 strings may be escaped with the backtick (`\`). If the right-hand side
155 is all digits, it is considered to be an integer. If it is all digits
156 and a decimal point, it is a double. If it is "true", "false", "TRUE",
157 or "FALSE" it is considered to be boolean. Otherwise, it is parsed as a
158 string. The type of the property is determined later on in the parsing,
159 and the value is converted to the target type. This conversion is not
160 guaranteed to work, it relies on the g\_value\_convert routines. No
161 error message will be displayed on an invalid conversion, due to
162 limitations in the value convert API.
163
164 #### Bins, Threads, and Pipelines
165
166 ```
167           ( ... )
168
169 ```
170
171 A pipeline description between parentheses is placed into a bin. The
172 open paren may be preceded by a type name, as in `jackbin.( ... )` to
173 make a bin of a specified type. Square brackets make pipelines, and
174 curly braces make threads. The default toplevel bin type is a pipeline,
175 although putting the whole description within parentheses or braces can
176 override this default.
177
178 ## `gst-inspect`
179
180 This is a tool to query a plugin or an element about its properties.
181
182 To query the information about the element mad, you would specify:
183
184 ```
185 gst-inspect mad
186
187 ```
188
189 Below is the output of a query for the osssink element:
190
191 ```
192
193 Factory Details:
194   Rank:         secondary (128)
195   Long-name:            Audio Sink (OSS)
196   Klass:                Sink/Audio
197   Description:          Output to a sound card via OSS
198   Author:               Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim.taymans@chello.be>
199
200 Plugin Details:
201   Name:                 ossaudio
202   Description:          OSS (Open Sound System) support for GStreamer
203   Filename:             /home/wim/gst/head/gst-plugins-good/sys/oss/.libs/libgstossaudio.so
204   Version:              1.0.0.1
205   License:              LGPL
206   Source module:        gst-plugins-good
207   Source release date:  2012-09-25 12:52 (UTC)
208   Binary package:       GStreamer Good Plug-ins git
209   Origin URL:           Unknown package origin
210
211 GObject
212  +----GInitiallyUnowned
213        +----GstObject
214              +----GstElement
215                    +----GstBaseSink
216                          +----GstAudioBaseSink
217                                +----GstAudioSink
218                                      +----GstOssSink
219
220 Pad Templates:
221   SINK template: 'sink'
222     Availability: Always
223     Capabilities:
224       audio/x-raw
225                  format: { S16LE, U16LE, S8, U8 }
226                  layout: interleaved
227                    rate: [ 1, 2147483647 ]
228                channels: 1
229       audio/x-raw
230                  format: { S16LE, U16LE, S8, U8 }
231                  layout: interleaved
232                    rate: [ 1, 2147483647 ]
233                channels: 2
234            channel-mask: 0x0000000000000003
235
236
237 Element Flags:
238   no flags set
239
240 Element Implementation:
241   Has change_state() function: gst_audio_base_sink_change_state
242
243 Clocking Interaction:
244   element is supposed to provide a clock but returned NULL
245
246 Element has no indexing capabilities.
247 Element has no URI handling capabilities.
248
249 Pads:
250   SINK: 'sink'
251     Implementation:
252       Has chainfunc(): gst_base_sink_chain
253       Has custom eventfunc(): gst_base_sink_event
254       Has custom queryfunc(): gst_base_sink_sink_query
255       Has custom iterintlinkfunc(): gst_pad_iterate_internal_links_default
256     Pad Template: 'sink'
257
258 Element Properties:
259   name                : The name of the object
260                         flags: readable, writable
261                         String. Default: "osssink0"
262   parent              : The parent of the object
263                         flags: readable, writable
264                         Object of type "GstObject"
265   sync                : Sync on the clock
266                         flags: readable, writable
267                         Boolean. Default: true
268   max-lateness        : Maximum number of nanoseconds that a buffer can be late before it is dropped (-1 unlimited)
269                         flags: readable, writable
270                         Integer64. Range: -1 - 9223372036854775807 Default: -1
271   qos                 : Generate Quality-of-Service events upstream
272                         flags: readable, writable
273                         Boolean. Default: false
274   async               : Go asynchronously to PAUSED
275                         flags: readable, writable
276                         Boolean. Default: true
277   ts-offset           : Timestamp offset in nanoseconds
278                         flags: readable, writable
279                         Integer64. Range: -9223372036854775808 - 9223372036854775807 Default: 0
280   enable-last-sample  : Enable the last-sample property
281                         flags: readable, writable
282                         Boolean. Default: false
283   last-sample         : The last sample received in the sink
284                         flags: readable
285                         Boxed pointer of type "GstSample"
286   blocksize           : Size in bytes to pull per buffer (0 = default)
287                         flags: readable, writable
288                         Unsigned Integer. Range: 0 - 4294967295 Default: 4096
289   render-delay        : Additional render delay of the sink in nanoseconds
290                         flags: readable, writable
291                         Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
292   throttle-time       : The time to keep between rendered buffers
293                         flags: readable, writable
294                         Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
295   buffer-time         : Size of audio buffer in microseconds, this is the minimum latency that the sink reports
296                         flags: readable, writable
297                         Integer64. Range: 1 - 9223372036854775807 Default: 200000
298   latency-time        : The minimum amount of data to write in each iteration in microseconds
299                         flags: readable, writable
300                         Integer64. Range: 1 - 9223372036854775807 Default: 10000
301   provide-clock       : Provide a clock to be used as the global pipeline clock
302                         flags: readable, writable
303                         Boolean. Default: true
304   slave-method        : Algorithm to use to match the rate of the masterclock
305                         flags: readable, writable
306                         Enum "GstAudioBaseSinkSlaveMethod" Default: 1, "skew"
307                            (0): resample         - GST_AUDIO_BASE_SINK_SLAVE_RESAMPLE
308                            (1): skew             - GST_AUDIO_BASE_SINK_SLAVE_SKEW
309                            (2): none             - GST_AUDIO_BASE_SINK_SLAVE_NONE
310   can-activate-pull   : Allow pull-based scheduling
311                         flags: readable, writable
312                         Boolean. Default: false
313   alignment-threshold : Timestamp alignment threshold in nanoseconds
314                         flags: readable, writable
315                         Unsigned Integer64. Range: 1 - 18446744073709551614 Default: 40000000
316   drift-tolerance     : Tolerance for clock drift in microseconds
317                         flags: readable, writable
318                         Integer64. Range: 1 - 9223372036854775807 Default: 40000
319   discont-wait        : Window of time in nanoseconds to wait before creating a discontinuity
320                         flags: readable, writable
321                         Unsigned Integer64. Range: 0 - 18446744073709551614 Default: 1000000000
322   device              : OSS device (usually /dev/dspN)
323                         flags: readable, writable
324                         String. Default: "/dev/dsp"
325
326
327 ```
328
329 To query the information about a plugin, you would do:
330
331 ```
332 gst-inspect gstelements
333
334 ```