1GStreamer(1)                General Commands Manual               GStreamer(1)
2
3
4

NAME

6       gst-launch - build and run a GStreamer pipeline
7

SYNOPSIS

9       gst-launch [OPTION...] PIPELINE-DESCRIPTION
10

DESCRIPTION

12       gst-launch is a tool that builds and runs basic GStreamer pipelines.
13
14       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
18       For  a  complete  description of possible PIPELINE-DESCRIPTIONS see the
19       section pipeline description below or consult the GStreamer  documenta‐
20       tion.
21
22       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

OPTIONS

28       gst-launch accepts the following options:
29
30       --help  Print help synopsis and available FLAGS
31
32       -v, --verbose
33               Output status information and property notifications
34
35       -q, --quiet
36               Do not print any progress information
37
38       -m, --messages
39               Output messages posted on the pipeline's bus
40
41       -t, --tags
42               Output tags (also known as metadata)
43
44       -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
49       -i, --index
50               Gather and print index statistics. This is  mostly  useful  for
51               playback or recording pipelines.
52
53       -o FILE, --output=FILE
54               Save  XML  representation  of pipeline to FILE and exit (DEPRE‐
55               CATED, DO NOT USE)
56
57       -f, --no-fault
58               Do not install a fault handler
59
60       --no-sigusr-handler
61               Do not install signal handlers for SIGUSR1 (play)  and  SIGUSR2
62               (stop)
63
64       -T, --trace
65               Print  memory allocation traces. The feature must be enabled at
66               compile time to work.
67
68
69
70       GSTREAMER OPTIONS
71              gst-launch also accepts the following options that are common to
72              all GStreamer applications:
73
74       --gst-version
75               Prints the version string of the GStreamer core library.
76
77       --gst-fatal-warnings
78               Causes  GStreamer to abort if a warning message occurs. This is
79               equivalent to  setting  the  environment  variable  G_DEBUG  to
80               'fatal_warnings'  (see  the section environment variables below
81               for further information).
82
83       --gst-debug=STRING
84               A comma separated list of category_name:level pairs to  specify
85               debugging  levels  for each category. Level is in the range 0-5
86               where 0 will show no messages, and 5 will  show  all  messages.
87               The wildcard * can be used to match category names.
88
89               Use --gst-debug-help to show category names
90
91               Example: GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
92
93
94       --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-5,  with
97               the default being 0.
98
99       --gst-debug-no-color
100               GStreamer  normally  prints debugging messages so that the mes‐
101               sages are color-coded when printed to a terminal  that  handles
102               ANSI  escape  sequences.  Using this option causes GStreamer to
103               print messages without color.  Setting  the  GST_DEBUG_NO_COLOR
104               environment variable will achieve the same thing.
105
106       --gst-debug-disable
107               Disables debugging.
108
109       --gst-debug-help
110               Prints  a  list of available debug categories and their default
111               debugging level.
112
113       --gst-plugin-spew
114               GStreamer info flags to set Enable  printout  of  errors  while
115               loading GStreamer plugins
116
117       --gst-plugin-path=PATH
118               Add directories separated with ':' to the plugin search path
119
120       --gst-plugin-load=PLUGINS
121               Preload  plugins  specified  in a comma-separated list. Another
122               way to specify plugins to preload is  to  use  the  environment
123               variable GST_PLUGIN_PATH
124
125

PIPELINE DESCRIPTION

127       A  pipeline  consists elements and links. Elements can be put into bins
128       of different sorts. Elements, links and bins  can  be  specified  in  a
129       pipeline description in any order.
130
131       Elements
132
133       ELEMENTTYPE [PROPERTY1 ...]
134
135       Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
136
137       Properties
138
139       PROPERTY=VALUE ...
140
141       Sets the property to the specified value. You can use gst-inspect(1) to
142       find out about properties and allowed values of different elements.
143       Enumeration properties can be set by name, nick or value.
144
145       Bins
146
147       [BINTYPE.] ( [PROPERTY1 ...] PIPELINE-DESCRIPTION )
148
149       Specifies that a bin of type BINTYPE is created and the  given  proper‐
150       ties  are  set.  Every  element between the braces is put into the bin.
151       Please note the dot that has to be used after  the  BINTYPE.  You  will
152       almost  never  need  this  functionality,  it is only really useful for
153       applications using the gst_launch_parse() API with  'bin'  as  bintype.
154       That  way  it is possible to build partial pipelines instead of a full-
155       fledged top-level pipeline.
156
157       Links
158
159       [[SRCELEMENT].[PAD1,...]]   !   [[SINKELEMENT].[PAD1,...]]    [[SRCELE‐
160       MENT].[PAD1,...]] ! CAPS ! [[SINKELEMENT].[PAD1,...]]
161
162       Links  the  element  with  name  SRCELEMENT  to  the  element with name
163       SINKELEMENT, using the caps specified in CAPS as a filter.   Names  can
164       be  set on elements with the name property. If the name is omitted, the
165       element that was specified directly in front of or after  the  link  is
166       used.  This  works across bins. If a padname is given, the link is done
167       with these pads. If no pad names are given all possibilities are  tried
168       and a matching pad is used.  If multiple padnames are given, both sides
169       must have the same number of pads specified and multiple links are done
170       in the given order.
171       So  the simplest link is a simple exclamation mark, that links the ele‐
172       ment to the left of it to the element right of it.
173
174       Caps
175
176       MIMETYPE [, PROPERTY[, PROPERTY ...]]] [; CAPS[; CAPS ...]]
177
178       Creates a capability with the given mimetype and optionally with  given
179       properties.  The  mimetype can be escaped using " or '.  If you want to
180       chain caps, you can add more caps in the same format afterwards.
181
182       Properties
183
184       NAME=[(TYPE)]VALUE
185       in lists and ranges: [(TYPE)]VALUE
186
187       Sets the requested property in capabilities. The name  is  an  alphanu‐
188       meric  value  and the type can have the following case-insensitive val‐
189       ues:
190       - i or int for integer values or ranges
191       - f or float for float values or ranges
192       - 4 or fourcc for FOURCC values
193       - b, bool or boolean for boolean values
194       - s, str or string for strings
195       - fraction for fractions (framerate, pixel-aspect-ratio)
196       - l or list for lists
197       If no type was given, the following order  is  tried:  integer,  float,
198       boolean, string.
199       Integer values must be parsable by strtol(), floats by strtod(). FOURCC
200       values may either be integers or  strings.  Boolean  values  are  (case
201       insensitive)  yes,  no,  true  or false and may like strings be escaped
202       with " or '.
203       Ranges are in this format:  [ VALUE, VALUE ]
204       Lists use this format:      ( VALUE [, VALUE ...] )
205
206

PIPELINE CONTROL

208       A pipeline can be controlled by signals. SIGUSR2 will stop the pipeline
209       (GST_STATE_NULL); SIGUSR1 will put it back to play (GST_STATE_PLAYING).
210       By default, the pipeline will start in the playing state.
211       There are currently no signals defined to go into the  ready  or  pause
212       (GST_STATE_READY and GST_STATE_PAUSED) state explicitly.
213
214

PIPELINE EXAMPLES

216       The examples below assume that you have the correct plug-ins available.
217       In general, "osssink" can be  substituted  with  another  audio  output
218       plug-in  such as "esdsink", "alsasink", "osxaudiosink", or "artsdsink".
219       Likewise,  "xvimagesink"  can   be   substituted   with   "ximagesink",
220       "sdlvideosink",  "osxvideosink",  or "aasink". Keep in mind though that
221       different sinks might accept different formats and even the  same  sink
222       might accept different formats on different machines, so you might need
223       to add converter elements  like  audioconvert  and  audioresample  (for
224       audio)  or  ffmpegcolorspace  (for  video) in front of the sink to make
225       things work.
226
227       Audio playback
228
229               gst-launch filesrc location=music.mp3 ! mad  !  audioconvert  !
230       audioresample ! osssink
231       Play  the  mp3  music file "music.mp3" using a libmad-based plug-in and
232       output to an OSS device
233
234               gst-launch filesrc location=music.ogg ! oggdemux ! vorbisdec  !
235       audioconvert ! audioresample ! osssink
236       Play an Ogg Vorbis format file
237
238               gst-launch gnomevfssrc location=music.mp3 ! mad ! osssink
239               gst-launch  gnomevfssrc  location=http://domain.com/music.mp3 !
240       mad ! audioconvert ! audioresample ! osssink
241       Play an mp3 file or an http stream using GNOME-VFS
242
243               gst-launch gnomevfssrc location=smb://computer/music.mp3 !  mad
244       ! audioconvert ! audioresample ! osssink
245       Use GNOME-VFS to play an mp3 file located on an SMB server
246
247       Format conversion
248
249               gst-launch  filesrc  location=music.mp3  ! mad ! audioconvert !
250       vorbisenc ! oggmux ! filesink location=music.ogg
251       Convert an mp3 music file to an Ogg Vorbis file
252
253               gst-launch filesrc location=music.mp3 ! mad  !  audioconvert  !
254       flacenc ! filesink location=test.flac
255       Convert to the FLAC format
256
257       Other
258
259               gst-launch filesrc location=music.wav ! wavparse ! audioconvert
260       ! audioresample ! osssink
261       Plays a .WAV file that contains raw audio data (PCM).
262
263               gst-launch filesrc location=music.wav ! wavparse ! audioconvert
264       ! vorbisenc ! oggmux ! filesink location=music.ogg
265               gst-launch filesrc location=music.wav ! wavparse ! audioconvert
266       ! lame ! filesink location=music.mp3
267       Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3
268       file
269
270               gst-launch  cdparanoiasrc mode=continuous ! audioconvert ! lame
271       ! id3v2mux ! filesink location=cd.mp3
272       rips all tracks from compact disc and convert them into  a  single  mp3
273       file
274
275               gst-launch  cdparanoiasrc  track=5  !  audioconvert  !  lame  !
276       id3v2mux ! filesink location=track5.mp3
277       rips track 5 from the CD and converts it into a single mp3 file
278
279       Using gst-inspect(1), it is possible  to  discover  settings  like  the
280       above  for cdparanoiasrc that will tell it to rip the entire cd or only
281       tracks of it.  Alternatively, you can use an  URI  and  gst-launch-0.10
282       will  find  an element (such as cdparanoia) that supports that protocol
283       for you, e.g.:
284              gst-launch cdda://5 !  lame  vbr=new  vbr-quality=6  !  filesink
285       location=track5.mp3
286
287               gst-launch  osssrc  !  audioconvert  !  vorbisenc  !  oggmux  !
288       filesink location=input.ogg
289       records sound from your audio input and encodes it into an ogg file
290
291       Video
292
293               gst-launch filesrc location=JB_FF9_TheGravityOfLove.mpg !  dvd‐
294       demux ! mpeg2dec ! xvimagesink
295       Display  only  the video portion of an MPEG-1 video file, outputting to
296       an X display window
297
298               gst-launch filesrc location=/flflfj.vob ! dvddemux ! mpeg2dec !
299       sdlvideosink
300       Display  the video portion of a .vob file (used on DVDs), outputting to
301       an SDL window
302
303               gst-launch filesrc location=movie.mpg !  dvddemux  name=demuxer
304       demuxer.  !  queue  ! mpeg2dec ! sdlvideosink  demuxer. ! queue ! mad !
305       audioconvert ! audioresample ! osssink
306       Play both video and audio portions of an MPEG movie
307
308               gst-launch filesrc location=movie.mpg ! mpegdemux  name=demuxer
309       demuxer.   !   queue  !  mpeg2dec  !  ffmpegcolorspace  !  sdlvideosink
310       demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
311       Play an AVI movie with an external text subtitle stream
312
313       This example also shows how to refer to specific pads  by  name  if  an
314       element (here: textoverlay) has multiple sink or source pads.
315
316               gst-launch   textoverlay   name=overlay  !  ffmpegcolorspace  !
317       videoscale ! autovideosink   filesrc location=movie.avi ! decodebin2  !
318       ffmpegcolorspace  !  overlay.video_sink    filesrc location=movie.srt !
319       subparse ! overlay.text_sink
320
321       Play an AVI movie with an external text subtitle stream using playbin2
322
323               gst-launch    playbin2    uri=file:///path/to/movie.avi    sub‐
324       uri=file:///path/to/movie.srt
325
326       Network streaming
327
328       Stream video using RTP and network elements.
329
330               gst-launch  v4l2src  ! video/x-raw-yuv,width=128,height=96,for‐
331       mat='(fourcc)'UYVY ! ffmpegcolorspace !  ffenc_h263  !  video/x-h263  !
332       rtph263ppay pt=96 ! udpsink host=192.168.1.1 port=5000 sync=false
333       This command would be run on the transmitter
334
335               gst-launch   udpsrc   port=5000   !  application/x-rtp,  clock-
336       rate=90000,payload=96 !  rtph263pdepay  queue-delay=0  !  ffdec_h263  !
337       xvimagesink
338       Use this command on the receiver
339
340       Diagnostic
341
342               gst-launch -v fakesrc num-buffers=16 ! fakesink
343       Generate a null stream and ignore it (and print out details).
344
345               gst-launch   audiotestsrc  !  audioconvert  !  audioresample  !
346       osssink
347       Generate a pure sine tone to test the audio output
348
349               gst-launch videotestsrc ! xvimagesink
350               gst-launch videotestsrc ! ximagesink
351       Generate a familiar test pattern to test the video output
352
353       Automatic linking
354
355       You can use the decodebin element to  automatically  select  the  right
356       elements to get a working pipeline.
357
358               gst-launch  filesrc  location=musicfile ! decodebin ! audiocon‐
359       vert ! audioresample ! osssink
360       Play any supported audio format
361
362               gst-launch filesrc location=videofile ! decodebin  name=decoder
363       decoder.  ! queue ! audioconvert ! audioresample ! osssink   decoder. !
364       ffmpegcolorspace ! xvimagesink
365       Play any supported video format with video and  audio  output.  Threads
366       are used automatically. To make this even easier, you can use the play‐
367       bin element:
368
369               gst-launch playbin uri=file:///home/joe/foo.avi
370
371
372       Filtered connections
373
374       These examples show you how to use filtered caps.
375
376               gst-launch      videotestsrc      !       'video/x-raw-yuv,for‐
377       mat=(fourcc)YUY2;video/x-raw-yuv,format=(fourcc)YV12' ! xvimagesink
378       Show a test image and use the YUY2 or YV12 video format for this.
379
380               gst-launch           osssrc           !           'audio/x-raw-
381       int,rate=[32000,64000],width=[16,32],depth={16,24,32},signed=(bool‐
382       ean)true' ! wavenc ! filesink location=recording.wav
383       record  audio  and write it to a .wav file. Force usage of signed 16 to
384       32 bit samples and a sample rate between 32kHz and 64KHz.
385
386
387

ENVIRONMENT VARIABLES

389       GST_DEBUG
390              Comma-separated  list  of  debug  categories  and  levels,  e.g.
391              GST_DEBUG=totem:4,typefind:5
392
393       GST_DEBUG_NO_COLOR
394              When  this environment variable is set, coloured debug output is
395              disabled.
396
397       GST_DEBUG_DUMP_DOT_DIR
398              When set to a filesystem  path,  store  dot  files  of  pipeline
399              graphs there.
400
401       GST_REGISTRY
402              Path    of    the    plugin    registry    file.    Default   is
403              ~/.gstreamer-0.10/registry-CPU.xml where CPU is the  machine/cpu
404              type  GStreamer was compiled for, e.g. 'i486', 'i686', 'x86-64',
405              'ppc', etc. (check the output of "uname -i" and "uname  -m"  for
406              details).
407
408       GST_REGISTRY_UPDATE
409              Set  to  "no"  to force GStreamer to assume that no plugins have
410              changed, been added or been removed. This  will  make  GStreamer
411              skip  the  initial check whether a rebuild of the registry cache
412              is required or not. This may be useful in embedded  environments
413              where the installed plugins never change. Do not use this option
414              in any other setup.
415
416       GST_PLUGIN_PATH
417              Specifies a list of directories to scan for additional  plugins.
418              These take precedence over the system plugins.
419
420       GST_PLUGIN_SYSTEM_PATH
421              Specifies  a  list of plugins that are always loaded by default.
422              If not set, this defaults to the system-installed path, and  the
423              plugins installed in the user's home directory
424
425       ORC_CODE
426              Useful  Orc  environment  variable. Set ORC_CODE=debug to enable
427              debuggers such as gdb to create useful backtraces from  Orc-gen‐
428              erated  code.   Set  ORC_CODE=backup  or ORC_CODE=emulate if you
429              suspect Orc's SIMD code generator is producing  incorrect  code.
430              (Quite  a  few  important  GStreamer  plugins like videotestsrc,
431              audioconvert or audioresample use Orc).
432
433       G_DEBUG
434              Useful GLib environment variable. Set G_DEBUG=fatal_warnings  to
435              make GStreamer programs abort when a critical warning such as an
436              assertion failure occurs. This is useful if you want to find out
437              which  part  of the code caused that warning to be triggered and
438              under what circumstances. Simply set G_DEBUG as mentioned  above
439              and  run  the  program  in gdb (or let it core dump). Then get a
440              stack trace in the usual way.
441

FILES

443       ~/.gstreamer-0.10/registry-*.xml
444               The xml plugin database; can be deleted at any  time,  will  be
445               re-created  automatically when it does not exist yet or plugins
446               change.
447

SEE ALSO

449       gst-feedback(1), gst-inspect(1), gst-typefind(1)
450

AUTHOR

452       The GStreamer team at http://gstreamer.freedesktop.org/
453
454
455
456                                   May 2007                       GStreamer(1)
Impressum