1GStreamer(1) General Commands Manual GStreamer(1)
2
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 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 For a complete description of possible PIPELINE-DESCRIPTIONS see the
19 section pipeline description below or consult the GStreamer documenta‐
20 tion.
21 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 --help Print help synopsis and available FLAGS
31 -v, --verbose
33 Output status information and property notifications
34 -q, --quiet
36 Do not print any progress information
37 -m, --messages
39 Output messages posted on the pipeline's bus
40 -t, --tags
42 Output tags (also known as metadata)
43 -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 -i, --index
50 Gather and print index statistics. This is mostly useful for
51 playback or recording pipelines.
52 -f, --no-fault
54 Do not install a fault handler
55 -T, --trace
57 Print memory allocation traces. The feature must be enabled at
58 compile time to work.
59 GSTREAMER OPTIONS
63 gst-launch also accepts the following options that are common to
64 all GStreamer applications:
65 --gst-version
67 Prints the version string of the GStreamer core library.
68 --gst-fatal-warnings
70 Causes GStreamer to abort if a warning message occurs. This is
71 equivalent to setting the environment variable G_DEBUG to
72 'fatal_warnings' (see the section environment variables below
73 for further information).
74 --gst-debug=STRING
76 A comma separated list of category_name:level pairs to specify
77 debugging levels for each category. Level is in the range 0-9
78 where 0 will show no messages, and 9 will show all messages.
79 The wildcard * can be used to match category names. Note that
80 the order of categories and levels is important, wildcards at
81 the end may override levels set earlier. The log levels are:
82 1=ERROR, 2=WARNING, 3=FIXME, 4=INFO, 5=DEBUG, 6=LOG, 7=TRACE,
83 9=MEMDUMP. Since GStreamer 1.2 one can also use the debug level
84 names, e.g. --gst-debug=*sink:LOG. A full description of the
85 various debug levels can be found in the GStreamer core library
86 API documentation, in the "Running GStreamer Applications" sec‐
87 tion.
88 Use --gst-debug-help to show category names
90 Example: GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
92 --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-9, with
97 the default being 0. Level 6 (LOG level) will show all informa‐
98 tion that is usually required for debugging purposes. Higher
99 levels are only useful in very specific cases. See above for
100 the full list of levels.
101 --gst-debug-no-color
103 GStreamer normally prints debugging messages so that the mes‐
104 sages are color-coded when printed to a terminal that handles
105 ANSI escape sequences. Using this option causes GStreamer to
106 print messages without color. Setting the GST_DEBUG_NO_COLOR
107 environment variable will achieve the same thing.
108 --gst-debug-color-mode
110 GStreamer normally prints debugging messages so that the mes‐
111 sages are color-coded when printed to a terminal that handles
112 ANSI escape sequences (on *nix), or uses W32 console API to
113 color the messages printed into a console (on W32). Using this
114 option causes GStreamer to print messages without color ('off'
115 or 'disable'), print messages with default colors ('on' or
116 'auto'), or print messages using ANSI escape sequences for col‐
117 oring ('unix'). Setting the GST_DEBUG_COLOR_MODE environment
118 variable will achieve the same thing.
119 --gst-debug-disable
121 Disables debugging.
122 --gst-debug-help
124 Prints a list of available debug categories and their default
125 debugging level.
126 --gst-plugin-spew
128 GStreamer info flags to set Enable printout of errors while
129 loading GStreamer plugins
130 --gst-plugin-path=PATH
132 Add directories separated with ':' to the plugin search path
133 --gst-plugin-load=PLUGINS
135 Preload plugins specified in a comma-separated list. Another
136 way to specify plugins to preload is to use the environment
137 variable GST_PLUGIN_PATH
138
141 A pipeline consists elements and links. Elements can be put into bins
142 of different sorts. Elements, links and bins can be specified in a
143 pipeline description in any order.
144 Elements
146 ELEMENTTYPE [PROPERTY1 ...]
148 Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
150 Properties
152 PROPERTY=VALUE ...
154 Sets the property to the specified value. You can use gst-inspect(1) to
156 find out about properties and allowed values of different elements.
157 Enumeration properties can be set by name, nick or value.
158 Bins
160 [BINTYPE.] ( [PROPERTY1 ...] PIPELINE-DESCRIPTION )
162 Specifies that a bin of type BINTYPE is created and the given proper‐
164 ties are set. Every element between the braces is put into the bin.
165 Please note the dot that has to be used after the BINTYPE. You will
166 almost never need this functionality, it is only really useful for
167 applications using the gst_launch_parse() API with 'bin' as bintype.
168 That way it is possible to build partial pipelines instead of a full-
169 fledged top-level pipeline.
170 Links
172 [[SRCELEMENT].[PAD1,...]] ! [[SINKELEMENT].[PAD1,...]] [[SRCELE‐
174 MENT].[PAD1,...]] ! CAPS ! [[SINKELEMENT].[PAD1,...]]
175 Links the element with name SRCELEMENT to the element with name
177 SINKELEMENT, using the caps specified in CAPS as a filter. Names can
178 be set on elements with the name property. If the name is omitted, the
179 element that was specified directly in front of or after the link is
180 used. This works across bins. If a padname is given, the link is done
181 with these pads. If no pad names are given all possibilities are tried
182 and a matching pad is used. If multiple padnames are given, both sides
183 must have the same number of pads specified and multiple links are done
184 in the given order.
185 So the simplest link is a simple exclamation mark, that links the ele‐
186 ment to the left of it to the element right of it.
187 Caps
189 MEDIATYPE [, PROPERTY[, PROPERTY ...]]] [; CAPS[; CAPS ...]]
191 Creates a capability with the given media type and optionally with
193 given properties. The media type can be escaped using " or '. If you
194 want to chain caps, you can add more caps in the same format after‐
195 wards.
196 Properties
198 NAME=[(TYPE)]VALUE
200 in lists and ranges: [(TYPE)]VALUE
201 Sets the requested property in capabilities. The name is an alphanu‐
203 meric value and the type can have the following case-insensitive val‐
204 ues:
205 - i or int for integer values or ranges
206 - f or float for float values or ranges
207 - b, bool or boolean for boolean values
208 - s, str or string for strings
209 - fraction for fractions (framerate, pixel-aspect-ratio)
210 - l or list for lists
211 If no type was given, the following order is tried: integer, float,
212 boolean, string.
213 Integer values must be parsable by strtol(), floats by strtod(). FOURCC
214 values may either be integers or strings. Boolean values are (case
215 insensitive) yes, no, true or false and may like strings be escaped
216 with " or '.
217 Ranges are in this format: [ VALUE, VALUE ]
218 Lists use this format: { VALUE [, VALUE ...] }
219
222 The examples below assume that you have the correct plug-ins available.
223 In general, "pulsesink" can be substituted with another audio output
224 plug-in such as "alsasink" or "osxaudiosink" Likewise, "xvimagesink"
225 can be substituted with "ximagesink", "glimagesink", or "osxvideosink".
226 Keep in mind though that different sinks might accept different formats
227 and even the same sink might accept different formats on different
228 machines, so you might need to add converter elements like audioconvert
229 and audioresample (for audio) or videoconvert (for video) in front of
230 the sink to make things work.
231 Audio playback
233 gst-launch filesrc location=music.mp3 ! mad ! audioconvert !
235 audioresample ! pulsesink
236 Play the mp3 music file "music.mp3" using a libmad-based plug-in and
237 output to an Pulseaudio device
238 gst-launch filesrc location=music.ogg ! oggdemux ! vorbisdec !
240 audioconvert ! audioresample ! pulsesink
241 Play an Ogg Vorbis format file
242 gst-launch giosrc location=music.mp3 ! mpegaudioparse ! mad !
244 pulsesink
245 gst-launch giosrc location=http://domain.com/music.mp3 ! mpe‐
246 gaudioparse ! mad ! audioconvert ! audioresample ! pulsesink
247 Play an mp3 file or an http stream using GIO
248 gst-launch giosrc location=smb://computer/music.mp3 ! mpegau‐
250 dioparse ! mad ! audioconvert ! audioresample ! pulsesink
251 Use GIO to play an mp3 file located on an SMB server
252 Format conversion
254 gst-launch filesrc location=music.mp3 ! mpegaudioparse ! mad !
256 audioconvert ! vorbisenc ! oggmux ! filesink location=music.ogg
257 Convert an mp3 music file to an Ogg Vorbis file
258 gst-launch filesrc location=music.mp3 ! mpegaudioparse ! mad !
260 audioconvert ! flacenc ! filesink location=test.flac
261 Convert to the FLAC format
262 Other
264 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
266 ! audioresample ! pulsesink
267 Plays a .WAV file that contains raw audio data (PCM).
268 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
270 ! vorbisenc ! oggmux ! filesink location=music.ogg
271 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
272 ! lame ! filesink location=music.mp3
273 Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3
274 file
275 gst-launch cdparanoiasrc mode=continuous ! audioconvert ! lame
277 ! mpegaudioparse ! id3v2mux ! filesink location=cd.mp3
278 rips all tracks from compact disc and convert them into a single mp3
279 file
280 gst-launch cdparanoiasrc track=5 ! audioconvert ! lame ! mpe‐
282 gaudioparse ! id3v2mux ! filesink location=track5.mp3
283 rips track 5 from the CD and converts it into a single mp3 file
284 Using gst-inspect(1), it is possible to discover settings like the
286 above for cdparanoiasrc that will tell it to rip the entire cd or only
287 tracks of it. Alternatively, you can use an URI and gst-launch-1.0
288 will find an element (such as cdparanoia) that supports that protocol
289 for you, e.g.:
290 gst-launch cdda://5 ! lame vbr=new vbr-quality=6 ! filesink
291 location=track5.mp3
292 gst-launch pulsesrc ! audioconvert ! vorbisenc ! oggmux !
294 filesink location=input.ogg
295 records sound from your audio input and encodes it into an ogg file
296 Video
298 gst-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! dvd‐
300 demux ! mpegvideoparse ! mpeg2dec ! xvimagesink
301 Display only the video portion of an MPEG-1 video file, outputting to
302 an X display window
303 gst-launch filesrc location=/flflfj.vob ! dvddemux !
305 mpegvideoparse ! mpeg2dec ! sdlvideosink
306 Display the video portion of a .vob file (used on DVDs), outputting to
307 an SDL window
308 gst-launch filesrc location=movie.mpg ! dvddemux name=demuxer
310 demuxer. ! queue ! mpegvideoparse ! mpeg2dec ! sdlvideosink demuxer. !
311 queue ! mpegaudioparse ! mad ! audioconvert ! audioresample ! pulsesink
312 Play both video and audio portions of an MPEG movie
313 gst-launch filesrc location=movie.mpg ! mpegdemux name=demuxer
315 demuxer. ! queue ! mpegvideoparse ! mpeg2dec ! videoconvert !
316 sdlvideosink demuxer. ! queue ! mpegaudioparse ! mad ! audioconvert !
317 audioresample ! pulsesink
318 Play an AVI movie with an external text subtitle stream
319 This example also shows how to refer to specific pads by name if an
321 element (here: textoverlay) has multiple sink or source pads.
322 gst-launch textoverlay name=overlay ! videoconvert ! videoscale
324 ! autovideosink filesrc location=movie.avi ! decodebin ! videocon‐
325 vert ! overlay.video_sink filesrc location=movie.srt ! subparse !
326 overlay.text_sink
327 Play an AVI movie with an external text subtitle stream using playbin
329 gst-launch playbin uri=file:///path/to/movie.avi sub‐
331 uri=file:///path/to/movie.srt
332 Network streaming
334 Stream video using RTP and network elements.
336 gst-launch v4l2src ! video/x-raw,width=128,height=96,for‐
338 mat=UYVY ! videoconvert ! ffenc_h263 ! video/x-h263 ! rtph263ppay pt=96
339 ! udpsink host=192.168.1.1 port=5000
340 This command would be run on the transmitter
341 gst-launch udpsrc port=5000 ! application/x-rtp, clock-
343 rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec_h263 !
344 xvimagesink
345 Use this command on the receiver
346 Diagnostic
348 gst-launch -v fakesrc num-buffers=16 ! fakesink
350 Generate a null stream and ignore it (and print out details).
351 gst-launch audiotestsrc ! audioconvert ! audioresample ! puls‐
353 esink
354 Generate a pure sine tone to test the audio output
355 gst-launch videotestsrc ! xvimagesink
357 gst-launch videotestsrc ! ximagesink
358 Generate a familiar test pattern to test the video output
359 Automatic linking
361 You can use the decodebin element to automatically select the right
363 elements to get a working pipeline.
364 gst-launch filesrc location=musicfile ! decodebin ! audiocon‐
366 vert ! audioresample ! pulsesink
367 Play any supported audio format
368 gst-launch filesrc location=videofile ! decodebin name=decoder
370 decoder. ! queue ! audioconvert ! audioresample ! pulsesink decoder.
371 ! videoconvert ! xvimagesink
372 Play any supported video format with video and audio output. Threads
373 are used automatically. To make this even easier, you can use the play‐
374 bin element:
375 gst-launch playbin uri=file:///home/joe/foo.avi
377 Filtered connections
380 These examples show you how to use filtered caps.
382 gst-launch videotestsrc ! 'video/x-raw,format=YUY2;video/x-
384 raw,format=YV12' ! xvimagesink
385 Show a test image and use the YUY2 or YV12 video format for this.
386 gst-launch pulsesrc ! 'audio/x-raw,rate=[32000,64000],for‐
388 mat={S16LE,S24LE,S32LE}' ! wavenc ! filesink location=recording.wav
389 record audio and write it to a .wav file. Force usage of signed 16 to
390 32 bit samples and a sample rate between 32kHz and 64KHz.
391
395 GST_DEBUG
396 Comma-separated list of debug categories and levels (e.g.
397 GST_DEBUG=totem:4,typefind:5). '*' is allowed as a wildcard as
398 part of debug category names (e.g. GST_DEBUG=*sink:6,*audio*:6).
399 Since 1.2.0 it is also possible to specify the log level by name
400 (1=ERROR, 2=WARN, 3=FIXME, 4=INFO, 5=DEBUG, 6=LOG, 7=TRACE,
401 9=MEMDUMP) (e.g. GST_DEBUG=*audio*:LOG)
402 GST_DEBUG_NO_COLOR
404 When this environment variable is set, coloured debug output is
405 disabled.
406 GST_DEBUG_DUMP_DOT_DIR
408 When set to a filesystem path, store 'dot' files of pipeline
409 graphs there. These can then later be converted into an image
410 using the 'dot' utility from the graphviz set of tools, like
411 this: dot foo.dot -Tsvg -o foo.svg (png or jpg are also possible
412 as output format). There is also a utility called 'xdot' which
413 allows you to view the .dot file directly without converting it
414 first.
415 GST_REGISTRY
417 Path of the plugin registry file. Default is
418 ~/.cache/gstreamer-1.0/registry-CPU.bin where CPU is the
419 machine/cpu type GStreamer was compiled for, e.g. 'i486',
420 'i686', 'x86-64',
421 GST_REGISTRY_UPDATE
423 Set to "no" to force GStreamer to assume that no plugins have
424 changed, been added or been removed. This will make GStreamer
425 skip the initial check whether a rebuild of the registry cache
426 is required or not. This may be useful in embedded environments
427 where the installed plugins never change. Do not use this option
428 in any other setup.
429 GST_PLUGIN_PATH
431 Specifies a list of directories to scan for additional plugins.
432 These take precedence over the system plugins.
433 GST_PLUGIN_SYSTEM_PATH
435 Specifies a list of plugins that are always loaded by default.
436 If not set, this defaults to the system-installed path, and the
437 plugins installed in the user's home directory
438 GST_DEBUG_FILE
440 Set this variable to a file path to redirect all GStreamer debug
441 messages to this file. If left unset, debug messages with be
442 output unto the standard error.
443 ORC_CODE
445 Useful Orc environment variable. Set ORC_CODE=debug to enable
446 debuggers such as gdb to create useful backtraces from Orc-gen‐
447 erated code. Set ORC_CODE=backup or ORC_CODE=emulate if you
448 suspect Orc's SIMD code generator is producing incorrect code.
449 (Quite a few important GStreamer plugins like videotestsrc,
450 audioconvert or audioresample use Orc).
451 G_DEBUG
453 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to
454 make GStreamer programs abort when a critical warning such as an
455 assertion failure occurs. This is useful if you want to find out
456 which part of the code caused that warning to be triggered and
457 under what circumstances. Simply set G_DEBUG as mentioned above
458 and run the program in gdb (or let it core dump). Then get a
459 stack trace in the usual way.
460
462 ~/.cache/gstreamer-1.0/registry-*.bin
463 The plugin cache; can be deleted at any time, will be re-cre‐
464 ated automatically when it does not exist yet or plugins
465 change. Based on XDG_CACHE_DIR, so may be in a different loca‐
466 tion than the one suggested.
467
469 gst-inspect-1.0(1), gst-launch-1.0(1),
470
472 The GStreamer team at http://gstreamer.freedesktop.org/
473 May 2007 GStreamer(1)