1GStreamer(1) General Commands Manual GStreamer(1)
2
6 gst-launch-1.0 - build and run a GStreamer pipeline
7
9 gst-launch-1.0 [OPTION...] PIPELINE-DESCRIPTION
10
12 gst-launch-1.0 is a tool that builds and runs basic GStreamer pipe‐
13 lines.
14 In simple form, a PIPELINE-DESCRIPTION is a list of elements separated
16 by exclamation marks (!). Properties may be appended to elements, in
17 the form property=value. A "preset" can also be set using the @pre‐
18 set=<preset name> synthax.
19 For a complete description of possible PIPELINE-DESCRIPTIONS see the
21 section pipeline description below or consult the GStreamer documenta‐
22 tion.
23 Please note that gst-launch-1.0 is primarily a debugging tool for
25 developers and users. You should not build applications on top of it.
26 For applications, use the gst_parse_launch() function of the GStreamer
27 API as an easy way to construct pipelines from pipeline descriptions.
28
30 gst-launch-1.0 accepts the following options:
31 --help Print help synopsis and available FLAGS
33 -v, --verbose
35 Output status information and property notifications
36 -q, --quiet
38 Do not print any progress information
39 -m, --messages
41 Output messages posted on the pipeline's bus
42 -t, --tags
44 Output tags (also known as metadata)
45 -e, --eos-on-shutdown
47 Force an EOS event on sources before shutting the pipeline
48 down. This is useful to make sure muxers create readable files
49 when a muxing pipeline is shut down forcefully via Control-C.
50 -i, --index
52 Gather and print index statistics. This is mostly useful for
53 playback or recording pipelines.
54 -f, --no-fault
56 Do not install a fault handler
57 -T, --trace
59 Print memory allocation traces. The feature must be enabled at
60 compile time to work.
61 --no-position
63 Do not print current position of pipeline. If this option is
64 unspecified, the position will be printed when stdout is a TTY.
65 To enable printing position when stdout is not a TTY, use
66 "force-position" option.
67 --force-position
69 Allow printing current position of pipeline even if stdout is
70 not a TTY. This option has no effect if the "no-position"
71 option is specified.
72 GSTREAMER OPTIONS
76 gst-launch-1.0 also accepts the following options that are com‐
77 mon to all GStreamer applications:
78 --gst-version
80 Prints the version string of the GStreamer core library.
81 --gst-fatal-warnings
83 Causes GStreamer to abort if a warning message occurs. This is
84 equivalent to setting the environment variable G_DEBUG to
85 'fatal_warnings' (see the section environment variables below
86 for further information).
87 --gst-debug=STRING
89 A comma separated list of category_name:level pairs to specify
90 debugging levels for each category. Level is in the range 0-9
91 where 0 will show no messages, and 9 will show all messages.
92 The wildcard * can be used to match category names. Note that
93 the order of categories and levels is important, wildcards at
94 the end may override levels set earlier. The log levels are:
95 1=ERROR, 2=WARNING, 3=FIXME, 4=INFO, 5=DEBUG, 6=LOG, 7=TRACE,
96 9=MEMDUMP. Since GStreamer 1.2 one can also use the debug level
97 names, e.g. --gst-debug=*sink:LOG. A full description of the
98 various debug levels can be found in the GStreamer core library
99 API documentation, in the "Running GStreamer Applications" sec‐
100 tion.
101 Use --gst-debug-help to show category names
103 Example: GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
105 --gst-debug-level=LEVEL
108 Sets the threshold for printing debugging messages. A higher
109 level will print more messages. The useful range is 0-9, with
110 the default being 0. Level 6 (LOG level) will show all informa‐
111 tion that is usually required for debugging purposes. Higher
112 levels are only useful in very specific cases. See above for
113 the full list of levels.
114 --gst-debug-no-color
116 GStreamer normally prints debugging messages so that the mes‐
117 sages are color-coded when printed to a terminal that handles
118 ANSI escape sequences. Using this option causes GStreamer to
119 print messages without color. Setting the GST_DEBUG_NO_COLOR
120 environment variable will achieve the same thing.
121 --gst-debug-color-mode
123 GStreamer normally prints debugging messages so that the mes‐
124 sages are color-coded when printed to a terminal that handles
125 ANSI escape sequences (on *nix), or uses W32 console API to
126 color the messages printed into a console (on W32). Using this
127 option causes GStreamer to print messages without color ('off'
128 or 'disable'), print messages with default colors ('on' or
129 'auto'), or print messages using ANSI escape sequences for col‐
130 oring ('unix'). Setting the GST_DEBUG_COLOR_MODE environment
131 variable will achieve the same thing.
132 --gst-debug-disable
134 Disables debugging.
135 --gst-debug-help
137 Prints a list of available debug categories and their default
138 debugging level.
139 --gst-plugin-spew
141 GStreamer info flags to set Enable printout of errors while
142 loading GStreamer plugins
143 --gst-plugin-path=PATH
145 Add directories separated with ':' to the plugin search path
146 --gst-plugin-load=PLUGINS
148 Preload plugins specified in a comma-separated list. Another
149 way to specify plugins to preload is to use the environment
150 variable GST_PLUGIN_PATH
151
154 A pipeline consists elements and links. Elements can be put into bins
155 of different sorts. Elements, links and bins can be specified in a
156 pipeline description in any order.
157 Elements
159 ELEMENTTYPE [PROPERTY1 ...]
161 Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
163 Properties
165 PROPERTY=VALUE ...
167 Sets the property to the specified value. You can use
169 gst-inspect-1.0(1) to find out about properties and allowed values of
170 different elements.
171 Enumeration properties can be set by name, nick or value.
172 Presets
174 @preset=<preset name> ...
176 Sets the preset on the element. you can use gst-inspect-1.0(1) to find
178 out what presets are available for a specific element.
179 Bins
181 [BINTYPE.] ( [PROPERTY1 ...] PIPELINE-DESCRIPTION )
183 Specifies that a bin of type BINTYPE is created and the given proper‐
185 ties are set. Every element between the braces is put into the bin.
186 Please note the dot that has to be used after the BINTYPE. You will
187 almost never need this functionality, it is only really useful for
188 applications using the gst_launch_parse() API with 'bin' as bintype.
189 That way it is possible to build partial pipelines instead of a full-
190 fledged top-level pipeline.
191 Links
193 [[SRCELEMENT].[PAD1,...]] ! [[SINKELEMENT].[PAD1,...]] [[SRCELE‐
195 MENT].[PAD1,...]] ! CAPS ! [[SINKELEMENT].[PAD1,...]] [[SRCELE‐
196 MENT].[PAD1,...]] : [[SINKELEMENT].[PAD1,...]] [[SRCELE‐
197 MENT].[PAD1,...]] : CAPS : [[SINKELEMENT].[PAD1,...]]
198 Links the element with name SRCELEMENT to the element with name
200 SINKELEMENT, using the caps specified in CAPS as a filter. Names can
201 be set on elements with the name property. If the name is omitted, the
202 element that was specified directly in front of or after the link is
203 used. This works across bins. If a padname is given, the link is done
204 with these pads. If no pad names are given all possibilities are tried
205 and a matching pad is used. If multiple padnames are given, both sides
206 must have the same number of pads specified and multiple links are done
207 in the given order.
208 So the simplest link is a simple exclamation mark, that links the ele‐
209 ment to the left of it to the element right of it.
210 Linking using the : operator attempts to link all possible pads between
211 the elements
212 Caps
214 MEDIATYPE [, PROPERTY[, PROPERTY ...]]] [; CAPS[; CAPS ...]]
216 Creates a capability with the given media type and optionally with
218 given properties. The media type can be escaped using " or '. If you
219 want to chain caps, you can add more caps in the same format after‐
220 wards.
221 Properties
223 NAME=[(TYPE)]VALUE
225 in lists and ranges: [(TYPE)]VALUE
226 Sets the requested property in capabilities. The name is an alphanu‐
228 meric value and the type can have the following case-insensitive val‐
229 ues:
230 - i or int for integer values or ranges
231 - f or float for float values or ranges
232 - b, bool or boolean for boolean values
233 - s, str or string for strings
234 - fraction for fractions (framerate, pixel-aspect-ratio)
235 - l or list for lists
236 If no type was given, the following order is tried: integer, float,
237 boolean, string.
238 Integer values must be parsable by strtol(), floats by strtod(). FOURCC
239 values may either be integers or strings. Boolean values are (case
240 insensitive) yes, no, true or false and may like strings be escaped
241 with " or '.
242 Ranges are in this format: [ VALUE, VALUE ]
243 Lists use this format: { VALUE [, VALUE ...] }
244
247 The examples below assume that you have the correct plug-ins available.
248 In general, "pulsesink" can be substituted with another audio output
249 plug-in such as "alsasink" or "osxaudiosink" Likewise, "xvimagesink"
250 can be substituted with "ximagesink", "glimagesink", or "osxvideosink".
251 Keep in mind though that different sinks might accept different formats
252 and even the same sink might accept different formats on different
253 machines, so you might need to add converter elements like audioconvert
254 and audioresample (for audio) or videoconvert (for video) in front of
255 the sink to make things work.
256 Audio playback
258 Play the mp3 music file "music.mp3" using a libmpg123-based plug-in and
260 output to an Pulseaudio device
261 gst-launch-1.0 filesrc location=music.mp3 ! mpegaudioparse !
262 mpg123audiodec ! audioconvert ! audioresample ! pulsesink
263 Play an Ogg Vorbis format file
265 gst-launch-1.0 filesrc location=music.ogg ! oggdemux ! vorbis‐
266 dec ! audioconvert ! audioresample ! pulsesink
267 Play an mp3 file or an http stream using GIO
269 gst-launch-1.0 giosrc location=music.mp3 ! mpegaudioparse !
270 mpg123audiodec ! audioconvert ! pulsesink
271 gst-launch-1.0 giosrc location=http://domain.com/music.mp3 !
272 mpegaudioparse ! mpg123audiodec ! audioconvert ! audioresample ! puls‐
273 esink
274 Use GIO to play an mp3 file located on an SMB server
276 gst-launch-1.0 giosrc location=smb://computer/music.mp3 ! mpe‐
277 gaudioparse ! mpg123audiodec ! audioconvert ! audioresample ! pulsesink
278 Format conversion
280 Convert an mp3 music file to an Ogg Vorbis file
282 gst-launch-1.0 filesrc location=music.mp3 ! mpegaudioparse !
283 mpg123audiodec ! audioconvert ! vorbisenc ! oggmux ! filesink loca‐
284 tion=music.ogg
285 Convert to the FLAC format
287 gst-launch-1.0 filesrc location=music.mp3 ! mpegaudioparse !
288 mpg123audiodec ! audioconvert ! flacenc ! filesink location=test.flac
289 Other
291 Plays a .WAV file that contains raw audio data (PCM).
293 gst-launch-1.0 filesrc location=music.wav ! wavparse ! audio‐
294 convert ! audioresample ! pulsesink
295 Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3
297 file
298 gst-launch-1.0 filesrc location=music.wav ! wavparse ! audio‐
299 convert ! vorbisenc ! oggmux ! filesink location=music.ogg
300 gst-launch-1.0 filesrc location=music.wav ! wavparse ! audio‐
301 convert ! lamemp3enc ! filesink location=music.mp3
302 Rips all tracks from compact disc and convert them into a single mp3
304 file
305 gst-launch-1.0 cdparanoiasrc mode=continuous ! audioconvert !
306 lamemp3enc ! mpegaudioparse ! id3v2mux ! filesink location=cd.mp3
307 Rips track 5 from the CD and converts it into a single mp3 file
309 gst-launch-1.0 cdparanoiasrc track=5 ! audioconvert !
310 lamemp3enc ! mpegaudioparse ! id3v2mux ! filesink location=track5.mp3
311 Using gst-inspect-1.0(1), it is possible to discover settings like the
313 above for cdparanoiasrc that will tell it to rip the entire cd or only
314 tracks of it. Alternatively, you can use an URI and gst-launch-1.0
315 will find an element (such as cdparanoia) that supports that protocol
316 for you, e.g.:
317 gst-launch-1.0 cdda://5 ! lamemp3enc vbr=new vbr-quality=6 !
318 filesink location=track5.mp3
319 Records sound from your audio input and encodes it into an ogg file
321 gst-launch-1.0 pulsesrc ! audioconvert ! vorbisenc ! oggmux !
322 filesink location=input.ogg
323 Video
325 Display only the video portion of an MPEG-1 video file, outputting to
327 an X display window
328 gst-launch-1.0 filesrc location=JB_FF9_TheGravityOfLove.mpg !
329 dvddemux ! mpegvideoparse ! mpeg2dec ! xvimagesink
330 Display the video portion of a .vob file (used on DVDs), outputting to
332 an SDL window
333 gst-launch-1.0 filesrc location=/flflfj.vob ! dvddemux !
334 mpegvideoparse ! mpeg2dec ! sdlvideosink
335 Play both video and audio portions of an MPEG movie
337 gst-launch-1.0 filesrc location=movie.mpg ! dvddemux
338 name=demuxer demuxer. ! queue ! mpegvideoparse ! mpeg2dec !
339 sdlvideosink demuxer. ! queue ! mpegaudioparse ! mpg123audiodec !
340 audioconvert ! audioresample ! pulsesink
341 Play an AVI movie with an external text subtitle stream
343 gst-launch-1.0 filesrc location=movie.mpg ! mpegdemux
344 name=demuxer demuxer. ! queue ! mpegvideoparse ! mpeg2dec ! videocon‐
345 vert ! sdlvideosink demuxer. ! queue ! mpegaudioparse !
346 mpg123audiodec ! audioconvert ! audioresample ! pulsesink
347 This example also shows how to refer to specific pads by name if an
349 element (here: textoverlay) has multiple sink or source pads.
350 gst-launch-1.0 textoverlay name=overlay ! videoconvert !
351 videoscale ! autovideosink filesrc location=movie.avi ! decodebin !
352 videoconvert ! overlay.video_sink filesrc location=movie.srt ! sub‐
353 parse ! overlay.text_sink
354 Play an AVI movie with an external text subtitle stream using playbin
356 gst-launch-1.0 playbin uri=file:///path/to/movie.avi sub‐
357 uri=file:///path/to/movie.srt
358 Network streaming
360 Stream video using RTP and network elements.
362 This command would be run on the transmitter
364 gst-launch-1.0 v4l2src ! video/x-raw,width=128,height=96,for‐
365 mat=UYVY ! videoconvert ! ffenc_h263 ! video/x-h263 ! rtph263ppay pt=96
366 ! udpsink host=192.168.1.1 port=5000
367 Use this command on the receiver
369 gst-launch-1.0 udpsrc port=5000 ! application/x-rtp,
370 clock-rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec_h263
371 ! xvimagesink
372 Diagnostic
374 Generate a null stream and ignore it (and print out details).
376 gst-launch-1.0 -v fakesrc num-buffers=16 ! fakesink
377 Generate a pure sine tone to test the audio output
379 gst-launch-1.0 audiotestsrc ! audioconvert ! audioresample !
380 pulsesink
381 Generate a familiar test pattern to test the video output
383 gst-launch-1.0 videotestsrc ! xvimagesink
384 gst-launch-1.0 videotestsrc ! ximagesink
385 Automatic linking
387 You can use the decodebin element to automatically select the right
389 elements to get a working pipeline.
390 Play any supported audio format
392 gst-launch-1.0 filesrc location=musicfile ! decodebin ! audio‐
393 convert ! audioresample ! pulsesink
394 Play any supported video format with video and audio output. Threads
396 are used automatically. To make this even easier, you can use the play‐
397 bin element:
398 gst-launch-1.0 filesrc location=videofile ! decodebin
399 name=decoder decoder. ! queue ! audioconvert ! audioresample ! puls‐
400 esink decoder. ! videoconvert ! xvimagesink
401 gst-launch-1.0 playbin uri=file:///home/joe/foo.avi
402 Filtered connections
405 These examples show you how to use filtered caps.
407 Show a test image and use the YUY2 or YV12 video format for this.
409 gst-launch-1.0 videotestsrc ! 'video/x-raw,for‐
410 mat=YUY2;video/x-raw,format=YV12' ! xvimagesink
411 Record audio and write it to a .wav file. Force usage of signed 16 to
413 32 bit samples and a sample rate between 32kHz and 64KHz.
414 gst-launch-1.0 pulsesrc ! 'audio/x-raw,rate=[32000,64000],for‐
415 mat={S16LE,S24LE,S32LE}' ! wavenc ! filesink location=recording.wav
416
420 GST_DEBUG
421 Comma-separated list of debug categories and levels (e.g.
422 GST_DEBUG=totem:4,typefind:5). '*' is allowed as a wildcard as
423 part of debug category names (e.g. GST_DEBUG=*sink:6,*audio*:6).
424 Since 1.2.0 it is also possible to specify the log level by name
425 (1=ERROR, 2=WARN, 3=FIXME, 4=INFO, 5=DEBUG, 6=LOG, 7=TRACE,
426 9=MEMDUMP) (e.g. GST_DEBUG=*audio*:LOG)
427 GST_DEBUG_NO_COLOR
429 When this environment variable is set, coloured debug output is
430 disabled.
431 GST_DEBUG_DUMP_DOT_DIR
433 When set to a filesystem path, store 'dot' files of pipeline
434 graphs there. These can then later be converted into an image
435 using the 'dot' utility from the graphviz set of tools, like
436 this: dot foo.dot -Tsvg -o foo.svg (png or jpg are also possible
437 as output format). There is also a utility called 'xdot' which
438 allows you to view the .dot file directly without converting it
439 first.
440 When the pipeline changes state through NULL to PLAYING and back
441 to NULL, a dot file is generated on each state change. To write
442 a snapshot of the pipeline state, send a SIGHUP to the process.
443 GST_REGISTRY
445 Path of the plugin registry file. Default is
446 ~/.cache/gstreamer-1.0/registry-CPU.bin where CPU is the
447 machine/cpu type GStreamer was compiled for, e.g. 'i486',
448 'i686', 'x86-64', 'ppc', etc. (check the output of "uname -i"
449 and "uname -m" for details).
450 GST_REGISTRY_UPDATE
452 Set to "no" to force GStreamer to assume that no plugins have
453 changed, been added or been removed. This will make GStreamer
454 skip the initial check whether a rebuild of the registry cache
455 is required or not. This may be useful in embedded environments
456 where the installed plugins never change. Do not use this option
457 in any other setup.
458 GST_PLUGIN_PATH
460 Specifies a list of directories to scan for additional plugins.
461 These take precedence over the system plugins.
462 GST_PLUGIN_SYSTEM_PATH
464 Specifies a list of plugins that are always loaded by default.
465 If not set, this defaults to the system-installed path, and the
466 plugins installed in the user's home directory
467 GST_DEBUG_FILE
469 Set this variable to a file path to redirect all GStreamer debug
470 messages to this file. If left unset, debug messages with be
471 output unto the standard error.
472 ORC_CODE
474 Useful Orc environment variable. Set ORC_CODE=debug to enable
475 debuggers such as gdb to create useful backtraces from Orc-gen‐
476 erated code. Set ORC_CODE=backup or ORC_CODE=emulate if you
477 suspect Orc's SIMD code generator is producing incorrect code.
478 (Quite a few important GStreamer plugins like videotestsrc,
479 audioconvert or audioresample use Orc).
480 G_DEBUG
482 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to
483 make GStreamer programs abort when a critical warning such as an
484 assertion failure occurs. This is useful if you want to find out
485 which part of the code caused that warning to be triggered and
486 under what circumstances. Simply set G_DEBUG as mentioned above
487 and run the program in gdb (or let it core dump). Then get a
488 stack trace in the usual way.
489
491 ~/.cache/gstreamer-1.0/registry-*.bin
492 The plugin cache; can be deleted at any time, will be re-cre‐
493 ated automatically when it does not exist yet or plugins
494 change. Based on XDG_CACHE_DIR, so may be in a different loca‐
495 tion than the one suggested.
496
498 gst-inspect-1.0(1), gst-launch-1.0(1),
499
501 The GStreamer team at http://gstreamer.freedesktop.org/
502 May 2007 GStreamer(1)