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