1GStreamer(1) General Commands Manual GStreamer(1)
2
3
4
6 gst-launch - build and run a GStreamer pipeline
7
9 gst-launch [OPTION...] PIPELINE-DESCRIPTION
10
12 gst-launch is a tool that builds and runs basic GStreamer pipelines.
13
14 In simple form, a PIPELINE-DESCRIPTION is a list of elements separated
15 by exclamation marks (!). Properties may be appended to elements, in
16 the form property=value.
17
18 For a complete description of possible PIPELINE-DESCRIPTIONS see the
19 section pipeline description below or consult the GStreamer documenta‐
20 tion.
21
22 Please note that gst-launch is primarily a debugging tool for develop‐
23 ers and users. You should not build applications on top of it. For
24 applications, use the gst_parse_launch() function of the GStreamer API
25 as an easy way to construct pipelines from pipeline descriptions.
26
28 gst-launch accepts the following options:
29
30 --help Print help synopsis and available FLAGS
31
32 -v, --verbose
33 Output status information and property notifications
34
35 -q, --quiet
36 Do not print any progress information
37
38 -m, --messages
39 Output messages posted on the pipeline's bus
40
41 -t, --tags
42 Output tags (also known as metadata)
43
44 -e, --eos-on-shutdown
45 Force an EOS event on sources before shutting the pipeline
46 down. This is useful to make sure muxers create readable files
47 when a muxing pipeline is shut down forcefully via Control-C.
48
49 -i, --index
50 Gather and print index statistics. This is mostly useful for
51 playback or recording pipelines.
52
53 -o FILE, --output=FILE
54 Save XML representation of pipeline to FILE and exit (DEPRE‐
55 CATED, DO NOT USE)
56
57 -f, --no-fault
58 Do not install a fault handler
59
60 --no-sigusr-handler
61 Do not install signal handlers for SIGUSR1 (play) and SIGUSR2
62 (stop)
63
64 -T, --trace
65 Print memory allocation traces. The feature must be enabled at
66 compile time to work.
67
68
69
70 GSTREAMER OPTIONS
71 gst-launch also accepts the following options that are common to
72 all GStreamer applications:
73
74 --gst-version
75 Prints the version string of the GStreamer core library.
76
77 --gst-fatal-warnings
78 Causes GStreamer to abort if a warning message occurs. This is
79 equivalent to setting the environment variable G_DEBUG to
80 'fatal_warnings' (see the section environment variables below
81 for further information).
82
83 --gst-debug=STRING
84 A comma separated list of category_name:level pairs to specify
85 debugging levels for each category. Level is in the range 0-5
86 where 0 will show no messages, and 5 will show all messages.
87 The wildcard * can be used to match category names.
88
89 Use --gst-debug-help to show category names
90
91 Example: GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
92
93
94 --gst-debug-level=LEVEL
95 Sets the threshold for printing debugging messages. A higher
96 level will print more messages. The useful range is 0-5, with
97 the default being 0.
98
99 --gst-debug-no-color
100 GStreamer normally prints debugging messages so that the mes‐
101 sages are color-coded when printed to a terminal that handles
102 ANSI escape sequences. Using this option causes GStreamer to
103 print messages without color. Setting the GST_DEBUG_NO_COLOR
104 environment variable will achieve the same thing.
105
106 --gst-debug-disable
107 Disables debugging.
108
109 --gst-debug-help
110 Prints a list of available debug categories and their default
111 debugging level.
112
113 --gst-plugin-spew
114 GStreamer info flags to set Enable printout of errors while
115 loading GStreamer plugins
116
117 --gst-plugin-path=PATH
118 Add directories separated with ':' to the plugin search path
119
120 --gst-plugin-load=PLUGINS
121 Preload plugins specified in a comma-separated list. Another
122 way to specify plugins to preload is to use the environment
123 variable GST_PLUGIN_PATH
124
125
127 A pipeline consists elements and links. Elements can be put into bins
128 of different sorts. Elements, links and bins can be specified in a
129 pipeline description in any order.
130
131 Elements
132
133 ELEMENTTYPE [PROPERTY1 ...]
134
135 Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
136
137 Properties
138
139 PROPERTY=VALUE ...
140
141 Sets the property to the specified value. You can use gst-inspect(1) to
142 find out about properties and allowed values of different elements.
143 Enumeration properties can be set by name, nick or value.
144
145 Bins
146
147 [BINTYPE.] ( [PROPERTY1 ...] PIPELINE-DESCRIPTION )
148
149 Specifies that a bin of type BINTYPE is created and the given proper‐
150 ties are set. Every element between the braces is put into the bin.
151 Please note the dot that has to be used after the BINTYPE. You will
152 almost never need this functionality, it is only really useful for
153 applications using the gst_launch_parse() API with 'bin' as bintype.
154 That way it is possible to build partial pipelines instead of a full-
155 fledged top-level pipeline.
156
157 Links
158
159 [[SRCELEMENT].[PAD1,...]] ! [[SINKELEMENT].[PAD1,...]] [[SRCELE‐
160 MENT].[PAD1,...]] ! CAPS ! [[SINKELEMENT].[PAD1,...]]
161
162 Links the element with name SRCELEMENT to the element with name
163 SINKELEMENT, using the caps specified in CAPS as a filter. Names can
164 be set on elements with the name property. If the name is omitted, the
165 element that was specified directly in front of or after the link is
166 used. This works across bins. If a padname is given, the link is done
167 with these pads. If no pad names are given all possibilities are tried
168 and a matching pad is used. If multiple padnames are given, both sides
169 must have the same number of pads specified and multiple links are done
170 in the given order.
171 So the simplest link is a simple exclamation mark, that links the ele‐
172 ment to the left of it to the element right of it.
173
174 Caps
175
176 MIMETYPE [, PROPERTY[, PROPERTY ...]]] [; CAPS[; CAPS ...]]
177
178 Creates a capability with the given mimetype and optionally with given
179 properties. The mimetype can be escaped using " or '. If you want to
180 chain caps, you can add more caps in the same format afterwards.
181
182 Properties
183
184 NAME=[(TYPE)]VALUE
185 in lists and ranges: [(TYPE)]VALUE
186
187 Sets the requested property in capabilities. The name is an alphanu‐
188 meric value and the type can have the following case-insensitive val‐
189 ues:
190 - i or int for integer values or ranges
191 - f or float for float values or ranges
192 - 4 or fourcc for FOURCC values
193 - b, bool or boolean for boolean values
194 - s, str or string for strings
195 - fraction for fractions (framerate, pixel-aspect-ratio)
196 - l or list for lists
197 If no type was given, the following order is tried: integer, float,
198 boolean, string.
199 Integer values must be parsable by strtol(), floats by strtod(). FOURCC
200 values may either be integers or strings. Boolean values are (case
201 insensitive) yes, no, true or false and may like strings be escaped
202 with " or '.
203 Ranges are in this format: [ VALUE, VALUE ]
204 Lists use this format: ( VALUE [, VALUE ...] )
205
206
208 A pipeline can be controlled by signals. SIGUSR2 will stop the pipeline
209 (GST_STATE_NULL); SIGUSR1 will put it back to play (GST_STATE_PLAYING).
210 By default, the pipeline will start in the playing state.
211 There are currently no signals defined to go into the ready or pause
212 (GST_STATE_READY and GST_STATE_PAUSED) state explicitly.
213
214
216 The examples below assume that you have the correct plug-ins available.
217 In general, "osssink" can be substituted with another audio output
218 plug-in such as "esdsink", "alsasink", "osxaudiosink", or "artsdsink".
219 Likewise, "xvimagesink" can be substituted with "ximagesink",
220 "sdlvideosink", "osxvideosink", or "aasink". Keep in mind though that
221 different sinks might accept different formats and even the same sink
222 might accept different formats on different machines, so you might need
223 to add converter elements like audioconvert and audioresample (for
224 audio) or ffmpegcolorspace (for video) in front of the sink to make
225 things work.
226
227 Audio playback
228
229 gst-launch filesrc location=music.mp3 ! mad ! audioconvert !
230 audioresample ! osssink
231 Play the mp3 music file "music.mp3" using a libmad-based plug-in and
232 output to an OSS device
233
234 gst-launch filesrc location=music.ogg ! oggdemux ! vorbisdec !
235 audioconvert ! audioresample ! osssink
236 Play an Ogg Vorbis format file
237
238 gst-launch gnomevfssrc location=music.mp3 ! mad ! osssink
239 gst-launch gnomevfssrc location=http://domain.com/music.mp3 !
240 mad ! audioconvert ! audioresample ! osssink
241 Play an mp3 file or an http stream using GNOME-VFS
242
243 gst-launch gnomevfssrc location=smb://computer/music.mp3 ! mad
244 ! audioconvert ! audioresample ! osssink
245 Use GNOME-VFS to play an mp3 file located on an SMB server
246
247 Format conversion
248
249 gst-launch filesrc location=music.mp3 ! mad ! audioconvert !
250 vorbisenc ! oggmux ! filesink location=music.ogg
251 Convert an mp3 music file to an Ogg Vorbis file
252
253 gst-launch filesrc location=music.mp3 ! mad ! audioconvert !
254 flacenc ! filesink location=test.flac
255 Convert to the FLAC format
256
257 Other
258
259 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
260 ! audioresample ! osssink
261 Plays a .WAV file that contains raw audio data (PCM).
262
263 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
264 ! vorbisenc ! oggmux ! filesink location=music.ogg
265 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
266 ! lame ! filesink location=music.mp3
267 Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3
268 file
269
270 gst-launch cdparanoiasrc mode=continuous ! audioconvert ! lame
271 ! id3v2mux ! filesink location=cd.mp3
272 rips all tracks from compact disc and convert them into a single mp3
273 file
274
275 gst-launch cdparanoiasrc track=5 ! audioconvert ! lame !
276 id3v2mux ! filesink location=track5.mp3
277 rips track 5 from the CD and converts it into a single mp3 file
278
279 Using gst-inspect(1), it is possible to discover settings like the
280 above for cdparanoiasrc that will tell it to rip the entire cd or only
281 tracks of it. Alternatively, you can use an URI and gst-launch-0.10
282 will find an element (such as cdparanoia) that supports that protocol
283 for you, e.g.:
284 gst-launch cdda://5 ! lame vbr=new vbr-quality=6 ! filesink
285 location=track5.mp3
286
287 gst-launch osssrc ! audioconvert ! vorbisenc ! oggmux !
288 filesink location=input.ogg
289 records sound from your audio input and encodes it into an ogg file
290
291 Video
292
293 gst-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! dvd‐
294 demux ! mpeg2dec ! xvimagesink
295 Display only the video portion of an MPEG-1 video file, outputting to
296 an X display window
297
298 gst-launch filesrc location=/flflfj.vob ! dvddemux ! mpeg2dec !
299 sdlvideosink
300 Display the video portion of a .vob file (used on DVDs), outputting to
301 an SDL window
302
303 gst-launch filesrc location=movie.mpg ! dvddemux name=demuxer
304 demuxer. ! queue ! mpeg2dec ! sdlvideosink demuxer. ! queue ! mad !
305 audioconvert ! audioresample ! osssink
306 Play both video and audio portions of an MPEG movie
307
308 gst-launch filesrc location=movie.mpg ! mpegdemux name=demuxer
309 demuxer. ! queue ! mpeg2dec ! ffmpegcolorspace ! sdlvideosink
310 demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
311 Play an AVI movie with an external text subtitle stream
312
313 This example also shows how to refer to specific pads by name if an
314 element (here: textoverlay) has multiple sink or source pads.
315
316 gst-launch textoverlay name=overlay ! ffmpegcolorspace !
317 videoscale ! autovideosink filesrc location=movie.avi ! decodebin2 !
318 ffmpegcolorspace ! overlay.video_sink filesrc location=movie.srt !
319 subparse ! overlay.text_sink
320
321 Play an AVI movie with an external text subtitle stream using playbin2
322
323 gst-launch playbin2 uri=file:///path/to/movie.avi sub‐
324 uri=file:///path/to/movie.srt
325
326 Network streaming
327
328 Stream video using RTP and network elements.
329
330 gst-launch v4l2src ! video/x-raw-yuv,width=128,height=96,for‐
331 mat='(fourcc)'UYVY ! ffmpegcolorspace ! ffenc_h263 ! video/x-h263 !
332 rtph263ppay pt=96 ! udpsink host=192.168.1.1 port=5000 sync=false
333 This command would be run on the transmitter
334
335 gst-launch udpsrc port=5000 ! application/x-rtp, clock-
336 rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec_h263 !
337 xvimagesink
338 Use this command on the receiver
339
340 Diagnostic
341
342 gst-launch -v fakesrc num-buffers=16 ! fakesink
343 Generate a null stream and ignore it (and print out details).
344
345 gst-launch audiotestsrc ! audioconvert ! audioresample !
346 osssink
347 Generate a pure sine tone to test the audio output
348
349 gst-launch videotestsrc ! xvimagesink
350 gst-launch videotestsrc ! ximagesink
351 Generate a familiar test pattern to test the video output
352
353 Automatic linking
354
355 You can use the decodebin element to automatically select the right
356 elements to get a working pipeline.
357
358 gst-launch filesrc location=musicfile ! decodebin ! audiocon‐
359 vert ! audioresample ! osssink
360 Play any supported audio format
361
362 gst-launch filesrc location=videofile ! decodebin name=decoder
363 decoder. ! queue ! audioconvert ! audioresample ! osssink decoder. !
364 ffmpegcolorspace ! xvimagesink
365 Play any supported video format with video and audio output. Threads
366 are used automatically. To make this even easier, you can use the play‐
367 bin element:
368
369 gst-launch playbin uri=file:///home/joe/foo.avi
370
371
372 Filtered connections
373
374 These examples show you how to use filtered caps.
375
376 gst-launch videotestsrc ! 'video/x-raw-yuv,for‐
377 mat=(fourcc)YUY2;video/x-raw-yuv,format=(fourcc)YV12' ! xvimagesink
378 Show a test image and use the YUY2 or YV12 video format for this.
379
380 gst-launch osssrc ! 'audio/x-raw-
381 int,rate=[32000,64000],width=[16,32],depth={16,24,32},signed=(bool‐
382 ean)true' ! wavenc ! filesink location=recording.wav
383 record audio and write it to a .wav file. Force usage of signed 16 to
384 32 bit samples and a sample rate between 32kHz and 64KHz.
385
386
387
389 GST_DEBUG
390 Comma-separated list of debug categories and levels, e.g.
391 GST_DEBUG=totem:4,typefind:5
392
393 GST_DEBUG_NO_COLOR
394 When this environment variable is set, coloured debug output is
395 disabled.
396
397 GST_DEBUG_DUMP_DOT_DIR
398 When set to a filesystem path, store dot files of pipeline
399 graphs there.
400
401 GST_REGISTRY
402 Path of the plugin registry file. Default is
403 ~/.gstreamer-0.10/registry-CPU.xml where CPU is the machine/cpu
404 type GStreamer was compiled for, e.g. 'i486', 'i686', 'x86-64',
405 'ppc', etc. (check the output of "uname -i" and "uname -m" for
406 details).
407
408 GST_REGISTRY_UPDATE
409 Set to "no" to force GStreamer to assume that no plugins have
410 changed, been added or been removed. This will make GStreamer
411 skip the initial check whether a rebuild of the registry cache
412 is required or not. This may be useful in embedded environments
413 where the installed plugins never change. Do not use this option
414 in any other setup.
415
416 GST_PLUGIN_PATH
417 Specifies a list of directories to scan for additional plugins.
418 These take precedence over the system plugins.
419
420 GST_PLUGIN_SYSTEM_PATH
421 Specifies a list of plugins that are always loaded by default.
422 If not set, this defaults to the system-installed path, and the
423 plugins installed in the user's home directory
424
425 ORC_CODE
426 Useful Orc environment variable. Set ORC_CODE=debug to enable
427 debuggers such as gdb to create useful backtraces from Orc-gen‐
428 erated code. Set ORC_CODE=backup or ORC_CODE=emulate if you
429 suspect Orc's SIMD code generator is producing incorrect code.
430 (Quite a few important GStreamer plugins like videotestsrc,
431 audioconvert or audioresample use Orc).
432
433 G_DEBUG
434 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to
435 make GStreamer programs abort when a critical warning such as an
436 assertion failure occurs. This is useful if you want to find out
437 which part of the code caused that warning to be triggered and
438 under what circumstances. Simply set G_DEBUG as mentioned above
439 and run the program in gdb (or let it core dump). Then get a
440 stack trace in the usual way.
441
443 ~/.gstreamer-0.10/registry-*.xml
444 The xml plugin database; can be deleted at any time, will be
445 re-created automatically when it does not exist yet or plugins
446 change.
447
449 gst-feedback(1), gst-inspect(1), gst-typefind(1)
450
452 The GStreamer team at http://gstreamer.freedesktop.org/
453
454
455
456 May 2007 GStreamer(1)