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