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
34 -m, --messages
36 Output messages posted on the pipeline's bus
37 -t, --tags
39 Output tags (also known as metadata)
40 -o FILE, --output=FILE
42 Save XML representation of pipeline to FILE and exit
43 -f, --no_fault
45 Do not install a fault handler
46 -T, --trace
48 Print memory allocation traces. The feature must be enabled at
49 compile time to work.
50 GSTREAMER OPTIONS
54 gst-launch also accepts the following options that are common to
55 all GStreamer applications:
56 --gst-version
58 Prints the version string of the GStreamer core library.
59 --gst-fatal-warnings
61 Causes GStreamer to abort if a warning message occurs. This is
62 equivalent to setting the environment variable G_DEBUG to
63 'fatal_warnings' (see the section environment variables below
64 for further information).
65 --gst-debug=STRING
67 A comma separated list of category_name:level pairs to specify
68 debugging levels for each category. Level is in the range 0-5
69 where 0 will show no messages, and 5 will show all messages.
70 The wildcard * can be used to match category names.
71 Use --gst-debug-help to show category names
73 Example: GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
75 --gst-debug-level=LEVEL
78 Sets the threshold for printing debugging messages. A higher
79 level will print more messages. The useful range is 0-5, with
80 the default being 0.
81 --gst-debug-no-color
83 GStreamer normally prints debugging messages so that the mes‐
84 sages are color-coded when printed to a terminal that handles
85 ANSI escape sequences. Using this option causes GStreamer to
86 print messages without color. Setting the GST_DEBUG_NO_COLOR
87 environment variable will achieve the same thing.
88 --gst-disable-debug
90 Disables debugging.
91 --gst-debug-help
93 Prints a list of available debug categories and their default
94 debugging level.
95 --gst-plugin-spew
97 GStreamer info flags to set Enable printout of errors while
98 loading GStreamer plugins
99 --gst-plugin-path=PATH
101 Add directories separated with ':' to the plugin search path
102 --gst-plugin-load=PLUGINS
104 Preload plugins specified in a comma-separated list. Another
105 way to specify plugins to preload is to use the environment
106 variable GST_PLUGIN_PATH
107
110 A pipeline consists elements and links. Elements can be put into bins
111 of different sorts. Elements, links and bins can be specified in a
112 pipeline description in any order.
113 Elements
115 ELEMENTTYPE [PROPERTY1 ...]
117 Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
119 Properties
121 PROPERTY=VALUE ...
123 Sets the property to the specified value. You can use gst-inspect(1) to
125 find out about properties and allowed values of different elements.
126 Enumeration properties can be set by name, nick or value.
127 Bins
129 [BINTYPE.] ( [PROPERTY1 ...] PIPELINE-DESCRIPTION )
131 Specifies that a bin of type BINTYPE is created and the given proper‐
133 ties are set. Every element between the braces is put into the bin.
134 Please note the dot that has to be used after the BINTYPE. You will
135 almost never need this functionality, it is only really useful for
136 applications using the gst_launch_parse() API with 'bin' as bintype.
137 That way it is possible to build partial pipelines instead of a full-
138 fledged top-level pipeline.
139 Links
141 [[SRCELEMENT].[PAD1,...]] ! [[SINKELEMENT].[PAD1,...]] [[SRCELE‐
143 MENT].[PAD1,...]] ! CAPS ! [[SINKELEMENT].[PAD1,...]]
144 Links the element with name SRCELEMENT to the element with name
146 SINKELEMENT, using the caps specified in CAPS as a filter. Names can
147 be set on elements with the name property. If the name is omitted, the
148 element that was specified directly in front of or after the link is
149 used. This works across bins. If a padname is given, the link is done
150 with these pads. If no pad names are given all possibilities are tried
151 and a matching pad is used. If multiple padnames are given, both sides
152 must have the same number of pads specified and multiple links are done
153 in the given order.
154 So the simplest link is a simple exclamation mark, that links the ele‐
155 ment to the left of it to the element right of it.
156 Caps
158 MIMETYPE [, PROPERTY[, PROPERTY ...]]] [; CAPS[; CAPS ...]]
160 Creates a capability with the given mimetype and optionally with given
162 properties. The mimetype can be escaped using " or '. If you want to
163 chain caps, you can add more caps in the same format afterwards.
164 Properties
166 NAME[:TYPE]=VALUE
168 in lists and ranges: [TYPE=]VALUE
169 Sets the requested property in capabilities. The name is an alphanu‐
171 meric value and the type can have the following case-insensitive val‐
172 ues:
173 - i or int for integer values or ranges
174 - f or float for float values or ranges
175 - 4 or fourcc for FOURCC values
176 - b, bool or boolean for boolean values
177 - s, str or string for strings
178 - fraction for fractions (framerate, pixel-aspect-ratio)
179 - l or list for lists
180 If no type was given, the following order is tried: integer, float,
181 boolean, string.
182 Integer values must be parsable by strtol(), floats by strtod(). FOURCC
183 values may either be integers or strings. Boolean values are (case
184 insensitive) yes, no, true or false and may like strings be escaped
185 with " or '.
186 Ranges are in this format: [ PROPERTY, PROPERTY ]
187 Lists use this format: ( PROPERTY [, PROPERTY ...] )
188
191 A pipeline can be controlled by signals. SIGUSR2 will stop the pipeline
192 (GST_STATE_NULL); SIGUSR1 will put it back to play (GST_STATE_PLAYING).
193 By default, the pipeline will start in the playing state.
194 There are currently no signals defined to go into the ready or pause
195 (GST_STATE_READY and GST_STATE_PAUSED) state explicitely.
196
199 The examples below assume that you have the correct plug-ins available.
200 In general, "osssink" can be substituted with another audio output
201 plug-in such as "esdsink", "alsasink", "osxaudiosink", or "artsdsink".
202 Likewise, "xvimagesink" can be substituted with "ximagesink",
203 "sdlvideosink", "osxvideosink", or "aasink". Keep in mind though that
204 different sinks might accept different formats and even the same sink
205 might accept different formats on different machines, so you might need
206 to add converter elements like audioconvert and audioresample (for
207 audio) or ffmpegcolorspace (for video) in front of the sink to make
208 things work.
209 Audio playback
211 gst-launch filesrc location=music.mp3 ! mad ! audioconvert !
213 audioresample ! osssink
214 Play the mp3 music file "music.mp3" using a libmad-based plug-in and
215 output to an OSS device
216 gst-launch filesrc location=music.ogg ! oggdemux ! vorbisdec !
218 audioconvert ! audioresample ! osssink
219 Play an Ogg Vorbis format file
220 gst-launch gnomevfssrc location=music.mp3 ! mad ! osssink
222 gst-launch gnomevfssrc location=http://domain.com/music.mp3 !
223 mad ! audioconvert ! audioresample ! osssink
224 Play an mp3 file or an http stream using GNOME-VFS
225 gst-launch gnomevfssrc location=smb://computer/music.mp3 ! mad
227 ! audioconvert ! audioresample ! osssink
228 Use GNOME-VFS to play an mp3 file located on an SMB server
229 Format conversion
231 gst-launch filesrc location=music.mp3 ! mad ! audioconvert !
233 vorbisenc ! oggmux ! filesink location=music.ogg
234 Convert an mp3 music file to an Ogg Vorbis file
235 gst-launch filesrc location=music.mp3 ! mad ! audioconvert !
237 flacenc ! filesink location=test.flac
238 Convert to the FLAC format
239 Other
241 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
243 ! audioresample ! osssink
244 Plays a .WAV file that contains raw audio data (PCM).
245 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
247 ! vorbisenc ! oggmux ! filesink location=music.ogg
248 gst-launch filesrc location=music.wav ! wavparse ! audioconvert
249 ! lame ! filesink location=music.mp3
250 Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3
251 file
252 gst-launch cdparanoia ! lame ! filesink location=cd.mp3
254 rips all tracks from compact disc and convert them into a single mp3
255 file
256 Using gst-inspect(1), it is possible to discover settings for cdpara‐
258 noia that will tell it to rip individual tracks. Alternatively, you can
259 use an URI and gst-launch-0.10 will find an element (such as cdpara‐
260 noia) that supports that protocol for you, e.g.:
261 gst-launch cdda://5 ! lame vbr=new vbr-quality=6 ! filesink
262 location=track5.mp3
263 gst-launch osssrc ! audioconvert ! vorbisenc ! oggmux !
265 filesink location=input.ogg
266 records sound from your audio input and encodes it into an ogg file
267 Video
269 gst-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! dvd‐
271 demux ! mpeg2dec ! xvimagesink
272 Display only the video portion of an MPEG-1 video file, outputting to
273 an X display window
274 gst-launch filesrc location=/flflfj.vob ! dvddemux ! mpeg2dec !
276 sdlvideosink
277 Display the video portion of a .vob file (used on DVDs), outputting to
278 an SDL window
279 gst-launch filesrc location=movie.mpg ! dvddemux name=demuxer
281 demuxer. ! queue ! mpeg2dec ! sdlvideosink demuxer. ! queue ! mad !
282 audioconvert ! audioresample ! osssink
283 Play both video and audio portions of an MPEG movie
284 gst-launch filesrc location=movie.mpg ! mpegdemux name=demuxer
286 demuxer. ! queue ! mpeg2dec ! ffmpegcolorspace ! sdlvideosink
287 demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
288 Play an AVI movie
289 Network streaming
291 Stream video using RTP and network elements.
293 gst-launch v4l2src ! video/x-raw-yuv,width=128,height=96,for‐
295 mat='(fourcc)'UYVY ! ffenc_h263 ! video/x-h263 ! rtph263ppay pt=96 !
296 udpsink host=192.168.1.1 port=5000 sync=false
297 Use this command on the receiver
298 gst-launch udpsrc port=5000 ! application/x-rtp, clock-
300 rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec_h263 !
301 xvimagesink
302 This command would be run on the transmitter
303 Diagnostic
305 gst-launch -v fakesrc num-buffers=16 ! fakesink
307 Generate a null stream and ignore it (and print out details).
308 gst-launch audiotestsrc ! audioconvert ! audioresample !
310 osssink
311 Generate a pure sine tone to test the audio output
312 gst-launch videotestsrc ! xvimagesink
314 gst-launch videotestsrc ! ximagesink
315 Generate a familiar test pattern to test the video output
316 Automatic linking
318 You can use the decodebin element to automatically select the right
320 elements to get a working pipeline.
321 gst-launch filesrc location=musicfile ! decodebin ! audiocon‐
323 vert ! audioresample ! osssink
324 Play any supported audio format
325 gst-launch filesrc location=videofile ! decodebin name=decoder
327 decoder. ! queue ! audioconvert ! audioresample ! osssink decoder. !
328 ffmpegcolorspace ! xvimagesink
329 Play any supported video format with video and audio output. Threads
330 are used automatically. To make this even easier, you can use the play‐
331 bin element:
332 gst-launch playbin uri=file:///home/joe/foo.avi
334 Filtered connections
337 These examples show you how to use filtered caps.
339 gst-launch videotestsrc ! 'video/x-raw-yuv,for‐
341 mat=(fourcc)YUY2;video/x-raw-yuv,format=(fourcc)YV12' ! xvimagesink
342 Show a test image and use the YUY2 or YV12 video format for this.
343 gst-launch osssrc ! 'audio/x-raw-
345 int,rate=[32000,64000],width=[16,32],depth={16,24,32},signed=(bool‐
346 ean)true' ! wavenc ! filesink location=recording.wav
347 record audio and write it to a .wav file. Force usage of signed 16 to
348 32 bit samples and a sample rate between 32kHz and 64KHz.
349
353 GST_DEBUG
354 Comma-separated list of debug categories and levels, e.g.
355 GST_DEBUG=totem:4,typefind:5
356 GST_DEBUG_NO_COLOR
358 When this environment variable is set, coloured debug output is
359 disabled.
360 GST_REGISTRY
362 Path of the plugin registry file. Default is
363 ~/.gstreamer-0.10/registry-CPU.xml where CPU is the machine/cpu
364 type GStreamer was compiled for, e.g. 'i486', 'i686', 'x86-64',
365 'ppc', etc. (check the output of "uname -i" and "uname -m" for
366 details).
367 GST_PLUGIN_PATH
369 Specifies a list of directories to scan for additional plugins.
370 These take precedence over the system plugins.
371 GST_PLUGIN_SYSTEM_PATH
373 Specifies a list of plugins that are always loaded by default.
374 If not set, this defaults to the system-installed path, and the
375 plugins installed in the user's home directory
376 OIL_CPU_FLAGS
378 Useful liboil environment variable. Set OIL_CPU_FLAGS=0 when
379 valgrind or other debugging tools trip over liboil's CPU detec‐
380 tion (quite a few important GStreamer plugins like videotestsrc,
381 audioconvert or audioresample use liboil).
382 G_DEBUG
384 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to
385 make GStreamer programs abort when a critical warning such as an
386 assertion failure occurs. This is useful if you want to find out
387 which part of the code caused that warning to be triggered and
388 under what circumstances. Simply set G_DEBUG as mentioned above
389 and run the program in gdb (or let it core dump). Then get a
390 stack trace in the usual way.
391
393 ~/.gstreamer-0.10/registry-*.xml
394 The xml plugin database; can be deleted at any time, will be
395 re-created automatically when it does not exist yet or plugins
396 change.
397
399 gst-feedback(1), gst-inspect(1), gst-typefind(1)
400
402 The GStreamer team at http://gstreamer.freedesktop.org/
403 May 2007 GStreamer(1)