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