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

NAME

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

SYNOPSIS

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

DESCRIPTION

12       gst-launch-1.0  is  a  tool  that builds and runs basic GStreamer pipe‐
13       lines.
14
15       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. A "preset" can also be  set  using  the  @pre‐
18       set=<preset name> synthax.
19
20       For  a  complete  description of possible PIPELINE-DESCRIPTIONS see the
21       section pipeline description below or consult the GStreamer  documenta‐
22       tion.
23
24       Please  note  that  gst-launch-1.0  is  primarily  a debugging tool for
25       developers and users. You should not build applications on top  of  it.
26       For  applications, use the gst_parse_launch() function of the GStreamer
27       API as an easy way to construct pipelines from pipeline descriptions.
28

OPTIONS

30       gst-launch-1.0 accepts the following options:
31
32       --help  Print help synopsis and available FLAGS
33
34       -v, --verbose
35               Output status information and property notifications
36
37       -q, --quiet
38               Do not print any progress information
39
40       -m, --messages
41               Output messages posted on the pipeline's bus
42
43       -t, --tags
44               Output tags (also known as metadata)
45
46       -e, --eos-on-shutdown
47               Force an EOS event on  sources  before  shutting  the  pipeline
48               down.  This is useful to make sure muxers create readable files
49               when a muxing pipeline is shut down forcefully via Control-C.
50
51       -i, --index
52               Gather and print index statistics. This is  mostly  useful  for
53               playback or recording pipelines.
54
55       -f, --no-fault
56               Do not install a fault handler
57
58       -T, --trace
59               Print  memory allocation traces. The feature must be enabled at
60               compile time to work.
61
62       --no-position
63               Do not print current position of pipeline.  If this  option  is
64               unspecified, the position will be printed when stdout is a TTY.
65               To enable printing position when  stdout  is  not  a  TTY,  use
66               "force-position" option.
67
68       --force-position
69               Allow  printing  current position of pipeline even if stdout is
70               not a TTY.  This option has  no  effect  if  the  "no-position"
71               option is specified.
72
73
74
75       GSTREAMER OPTIONS
76              gst-launch-1.0  also accepts the following options that are com‐
77              mon to all GStreamer applications:
78
79       --gst-version
80               Prints the version string of the GStreamer core library.
81
82       --gst-fatal-warnings
83               Causes GStreamer to abort if a warning message occurs. This  is
84               equivalent  to  setting  the  environment  variable  G_DEBUG to
85               'fatal_warnings' (see the section environment  variables  below
86               for further information).
87
88       --gst-debug=STRING
89               A  comma separated list of category_name:level pairs to specify
90               debugging levels for each category. Level is in the  range  0-9
91               where  0  will  show no messages, and 9 will show all messages.
92               The wildcard * can be used to match category names.  Note  that
93               the  order  of categories and levels is important, wildcards at
94               the end may override levels set earlier. The  log  levels  are:
95               1=ERROR,  2=WARNING,  3=FIXME, 4=INFO, 5=DEBUG, 6=LOG, 7=TRACE,
96               9=MEMDUMP. Since GStreamer 1.2 one can also use the debug level
97               names,  e.g.  --gst-debug=*sink:LOG.  A full description of the
98               various debug levels can be found in the GStreamer core library
99               API documentation, in the "Running GStreamer Applications" sec‐
100               tion.
101
102               Use --gst-debug-help to show category names
103
104               Example: GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
105
106
107       --gst-debug-level=LEVEL
108               Sets the threshold for printing debugging messages.   A  higher
109               level  will print more messages.  The useful range is 0-9, with
110               the default being 0. Level 6 (LOG level) will show all informa‐
111               tion  that  is  usually required for debugging purposes. Higher
112               levels are only useful in very specific cases.  See  above  for
113               the full list of levels.
114
115       --gst-debug-no-color
116               GStreamer  normally  prints debugging messages so that the mes‐
117               sages are color-coded when printed to a terminal  that  handles
118               ANSI  escape  sequences.  Using this option causes GStreamer to
119               print messages without color.  Setting  the  GST_DEBUG_NO_COLOR
120               environment variable will achieve the same thing.
121
122       --gst-debug-color-mode
123               GStreamer  normally  prints debugging messages so that the mes‐
124               sages are color-coded when printed to a terminal  that  handles
125               ANSI  escape  sequences  (on  *nix), or uses W32 console API to
126               color the messages printed into a console (on W32). Using  this
127               option  causes GStreamer to print messages without color ('off'
128               or 'disable'), print messages  with  default  colors  ('on'  or
129               'auto'), or print messages using ANSI escape sequences for col‐
130               oring ('unix'). Setting  the  GST_DEBUG_COLOR_MODE  environment
131               variable will achieve the same thing.
132
133       --gst-debug-disable
134               Disables debugging.
135
136       --gst-debug-help
137               Prints  a  list of available debug categories and their default
138               debugging level.
139
140       --gst-plugin-spew
141               GStreamer info flags to set Enable  printout  of  errors  while
142               loading GStreamer plugins
143
144       --gst-plugin-path=PATH
145               Add directories separated with ':' to the plugin search path
146
147       --gst-plugin-load=PLUGINS
148               Preload  plugins  specified  in a comma-separated list. Another
149               way to specify plugins to preload is  to  use  the  environment
150               variable GST_PLUGIN_PATH
151
152

PIPELINE DESCRIPTION

154       A  pipeline  consists elements and links. Elements can be put into bins
155       of different sorts. Elements, links and bins  can  be  specified  in  a
156       pipeline description in any order.
157
158       Elements
159
160       ELEMENTTYPE [PROPERTY1 ...]
161
162       Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
163
164       Properties
165
166       PROPERTY=VALUE ...
167
168       Sets   the   property   to   the   specified   value.   You   can   use
169       gst-inspect-1.0(1) to find out about properties and allowed  values  of
170       different elements.
171       Enumeration properties can be set by name, nick or value.
172
173       Presets
174
175       @preset=<preset name> ...
176
177       Sets  the preset on the element. you can use gst-inspect-1.0(1) to find
178       out what presets are available for a specific element.
179
180       Bins
181
182       [BINTYPE.] ( [PROPERTY1 ...] PIPELINE-DESCRIPTION )
183
184       Specifies that a bin of type BINTYPE is created and the  given  proper‐
185       ties  are  set.  Every  element between the braces is put into the bin.
186       Please note the dot that has to be used after  the  BINTYPE.  You  will
187       almost  never  need  this  functionality,  it is only really useful for
188       applications using the gst_launch_parse() API with  'bin'  as  bintype.
189       That  way  it is possible to build partial pipelines instead of a full-
190       fledged top-level pipeline.
191
192       Links
193
194       [[SRCELEMENT].[PAD1,...]]   !   [[SINKELEMENT].[PAD1,...]]    [[SRCELE‐
195       MENT].[PAD1,...]]   !   CAPS  !  [[SINKELEMENT].[PAD1,...]]   [[SRCELE‐
196       MENT].[PAD1,...]]     :      [[SINKELEMENT].[PAD1,...]]       [[SRCELE‐
197       MENT].[PAD1,...]] : CAPS : [[SINKELEMENT].[PAD1,...]]
198
199       Links  the  element  with  name  SRCELEMENT  to  the  element with name
200       SINKELEMENT, using the caps specified in CAPS as a filter.   Names  can
201       be  set on elements with the name property. If the name is omitted, the
202       element that was specified directly in front of or after  the  link  is
203       used.  This  works across bins. If a padname is given, the link is done
204       with these pads. If no pad names are given all possibilities are  tried
205       and a matching pad is used.  If multiple padnames are given, both sides
206       must have the same number of pads specified and multiple links are done
207       in the given order.
208       So  the simplest link is a simple exclamation mark, that links the ele‐
209       ment to the left of it to the element right of it.
210       Linking using the : operator attempts to link all possible pads between
211       the elements
212
213       Caps
214
215       MEDIATYPE [, PROPERTY[, PROPERTY ...]]] [; CAPS[; CAPS ...]]
216
217       Creates  a  capability  with  the  given media type and optionally with
218       given properties. The media type can be escaped using " or '.   If  you
219       want  to  chain  caps,  you can add more caps in the same format after‐
220       wards.
221
222       Properties
223
224       NAME=[(TYPE)]VALUE
225       in lists and ranges: [(TYPE)]VALUE
226
227       Sets the requested property in capabilities. The name  is  an  alphanu‐
228       meric  value  and the type can have the following case-insensitive val‐
229       ues:
230       - i or int for integer values or ranges
231       - f or float for float values or ranges
232       - b, bool or boolean for boolean values
233       - s, str or string for strings
234       - fraction for fractions (framerate, pixel-aspect-ratio)
235       - l or list for lists
236       If no type was given, the following order  is  tried:  integer,  float,
237       boolean, string.
238       Integer values must be parsable by strtol(), floats by strtod(). FOURCC
239       values may either be integers or  strings.  Boolean  values  are  (case
240       insensitive)  yes,  no,  true  or false and may like strings be escaped
241       with " or '.
242       Ranges are in this format:  [ VALUE, VALUE ]
243       Lists use this format:      { VALUE [, VALUE ...] }
244
245

PIPELINE EXAMPLES

247       The examples below assume that you have the correct plug-ins available.
248       In  general,  "pulsesink"  can be substituted with another audio output
249       plug-in such as "alsasink" or  "osxaudiosink"  Likewise,  "xvimagesink"
250       can be substituted with "ximagesink", "glimagesink", or "osxvideosink".
251       Keep in mind though that different sinks might accept different formats
252       and  even  the  same  sink  might accept different formats on different
253       machines, so you might need to add converter elements like audioconvert
254       and  audioresample  (for audio) or videoconvert (for video) in front of
255       the sink to make things work.
256
257       Audio playback
258
259       Play the mp3 music file "music.mp3" using a libmpg123-based plug-in and
260       output to an Pulseaudio device
261               gst-launch-1.0  filesrc  location=music.mp3  ! mpegaudioparse !
262       mpg123audiodec ! audioconvert ! audioresample ! pulsesink
263
264       Play an Ogg Vorbis format file
265               gst-launch-1.0 filesrc location=music.ogg ! oggdemux !  vorbis‐
266       dec ! audioconvert ! audioresample ! pulsesink
267
268       Play an mp3 file or an http stream using GIO
269               gst-launch-1.0  giosrc  location=music.mp3  !  mpegaudioparse !
270       mpg123audiodec ! audioconvert ! pulsesink
271               gst-launch-1.0  giosrc  location=http://domain.com/music.mp3  !
272       mpegaudioparse  ! mpg123audiodec ! audioconvert ! audioresample ! puls‐
273       esink
274
275       Use GIO to play an mp3 file located on an SMB server
276               gst-launch-1.0 giosrc location=smb://computer/music.mp3 !  mpe‐
277       gaudioparse ! mpg123audiodec ! audioconvert ! audioresample ! pulsesink
278
279       Format conversion
280
281       Convert an mp3 music file to an Ogg Vorbis file
282               gst-launch-1.0  filesrc  location=music.mp3  ! mpegaudioparse !
283       mpg123audiodec ! audioconvert ! vorbisenc !  oggmux  !  filesink  loca‐
284       tion=music.ogg
285
286       Convert to the FLAC format
287               gst-launch-1.0  filesrc  location=music.mp3  ! mpegaudioparse !
288       mpg123audiodec ! audioconvert ! flacenc ! filesink location=test.flac
289
290       Other
291
292       Plays a .WAV file that contains raw audio data (PCM).
293               gst-launch-1.0 filesrc location=music.wav ! wavparse  !  audio‐
294       convert ! audioresample ! pulsesink
295
296       Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3
297       file
298               gst-launch-1.0 filesrc location=music.wav ! wavparse  !  audio‐
299       convert ! vorbisenc ! oggmux ! filesink location=music.ogg
300               gst-launch-1.0  filesrc  location=music.wav ! wavparse ! audio‐
301       convert ! lamemp3enc ! filesink location=music.mp3
302
303       Rips all tracks from compact disc and convert them into  a  single  mp3
304       file
305               gst-launch-1.0  cdparanoiasrc  mode=continuous ! audioconvert !
306       lamemp3enc ! mpegaudioparse ! id3v2mux ! filesink location=cd.mp3
307
308       Rips track 5 from the CD and converts it into a single mp3 file
309               gst-launch-1.0   cdparanoiasrc   track=5   !   audioconvert   !
310       lamemp3enc ! mpegaudioparse ! id3v2mux ! filesink location=track5.mp3
311
312       Using  gst-inspect-1.0(1), it is possible to discover settings like the
313       above for cdparanoiasrc that will tell it to rip the entire cd or  only
314       tracks  of  it.   Alternatively,  you can use an URI and gst-launch-1.0
315       will find an element (such as cdparanoia) that supports  that  protocol
316       for you, e.g.:
317              gst-launch-1.0  cdda://5  !  lamemp3enc  vbr=new vbr-quality=6 !
318       filesink location=track5.mp3
319
320       Records sound from your audio input and encodes it into an ogg file
321               gst-launch-1.0 pulsesrc ! audioconvert ! vorbisenc !  oggmux  !
322       filesink location=input.ogg
323
324       Video
325
326       Display  only  the video portion of an MPEG-1 video file, outputting to
327       an X display window
328               gst-launch-1.0 filesrc  location=JB_FF9_TheGravityOfLove.mpg  !
329       dvddemux ! mpegvideoparse ! mpeg2dec ! xvimagesink
330
331       Display  the video portion of a .vob file (used on DVDs), outputting to
332       an SDL window
333               gst-launch-1.0  filesrc  location=/flflfj.vob  !   dvddemux   !
334       mpegvideoparse ! mpeg2dec ! sdlvideosink
335
336       Play both video and audio portions of an MPEG movie
337               gst-launch-1.0    filesrc    location=movie.mpg    !   dvddemux
338       name=demuxer   demuxer.  !  queue  !  mpegvideoparse   !   mpeg2dec   !
339       sdlvideosink   demuxer.  !  queue  !  mpegaudioparse ! mpg123audiodec !
340       audioconvert ! audioresample ! pulsesink
341
342       Play an AVI movie with an external text subtitle stream
343               gst-launch-1.0   filesrc   location=movie.mpg    !    mpegdemux
344       name=demuxer  demuxer.  ! queue ! mpegvideoparse ! mpeg2dec ! videocon‐
345       vert  !  sdlvideosink     demuxer.   !   queue   !   mpegaudioparse   !
346       mpg123audiodec ! audioconvert ! audioresample ! pulsesink
347
348       This  example  also  shows  how to refer to specific pads by name if an
349       element (here: textoverlay) has multiple sink or source pads.
350               gst-launch-1.0  textoverlay  name=overlay  !   videoconvert   !
351       videoscale  !  autovideosink   filesrc location=movie.avi ! decodebin !
352       videoconvert ! overlay.video_sink   filesrc location=movie.srt  !  sub‐
353       parse ! overlay.text_sink
354
355       Play an AVI movie with an external text subtitle stream using playbin
356               gst-launch-1.0   playbin   uri=file:///path/to/movie.avi   sub‐
357       uri=file:///path/to/movie.srt
358
359       Network streaming
360
361       Stream video using RTP and network elements.
362
363       This command would be run on the transmitter
364               gst-launch-1.0 v4l2src  !  video/x-raw,width=128,height=96,for‐
365       mat=UYVY ! videoconvert ! ffenc_h263 ! video/x-h263 ! rtph263ppay pt=96
366       ! udpsink host=192.168.1.1 port=5000
367
368       Use this command on the receiver
369               gst-launch-1.0   udpsrc    port=5000    !    application/x-rtp,
370       clock-rate=90000,payload=96  ! rtph263pdepay queue-delay=0 ! ffdec_h263
371       ! xvimagesink
372
373       Diagnostic
374
375       Generate a null stream and ignore it (and print out details).
376               gst-launch-1.0 -v fakesrc num-buffers=16 ! fakesink
377
378       Generate a pure sine tone to test the audio output
379               gst-launch-1.0 audiotestsrc ! audioconvert  !  audioresample  !
380       pulsesink
381
382       Generate a familiar test pattern to test the video output
383               gst-launch-1.0 videotestsrc ! xvimagesink
384               gst-launch-1.0 videotestsrc ! ximagesink
385
386       Automatic linking
387
388       You  can  use  the  decodebin element to automatically select the right
389       elements to get a working pipeline.
390
391       Play any supported audio format
392               gst-launch-1.0 filesrc location=musicfile ! decodebin !  audio‐
393       convert ! audioresample ! pulsesink
394
395       Play  any  supported  video format with video and audio output. Threads
396       are used automatically. To make this even easier, you can use the play‐
397       bin element:
398               gst-launch-1.0    filesrc    location=videofile   !   decodebin
399       name=decoder decoder. ! queue ! audioconvert !  audioresample  !  puls‐
400       esink   decoder. !  videoconvert ! xvimagesink
401               gst-launch-1.0 playbin uri=file:///home/joe/foo.avi
402
403
404       Filtered connections
405
406       These examples show you how to use filtered caps.
407
408       Show a test image and use the YUY2 or YV12 video format for this.
409               gst-launch-1.0       videotestsrc      !      'video/x-raw,for‐
410       mat=YUY2;video/x-raw,format=YV12' ! xvimagesink
411
412       Record audio and write it to a .wav file. Force usage of signed  16  to
413       32 bit samples and a sample rate between 32kHz and 64KHz.
414               gst-launch-1.0 pulsesrc !  'audio/x-raw,rate=[32000,64000],for‐
415       mat={S16LE,S24LE,S32LE}' ! wavenc ! filesink location=recording.wav
416
417
418

ENVIRONMENT VARIABLES

420       GST_DEBUG
421              Comma-separated  list  of  debug  categories  and  levels  (e.g.
422              GST_DEBUG=totem:4,typefind:5).  '*'  is allowed as a wildcard as
423              part of debug category names (e.g. GST_DEBUG=*sink:6,*audio*:6).
424              Since 1.2.0 it is also possible to specify the log level by name
425              (1=ERROR, 2=WARN,  3=FIXME,  4=INFO,  5=DEBUG,  6=LOG,  7=TRACE,
426              9=MEMDUMP) (e.g. GST_DEBUG=*audio*:LOG)
427
428       GST_DEBUG_NO_COLOR
429              When  this environment variable is set, coloured debug output is
430              disabled.
431
432       GST_DEBUG_DUMP_DOT_DIR
433              When set to a filesystem path, store  'dot'  files  of  pipeline
434              graphs  there.   These can then later be converted into an image
435              using the 'dot' utility from the graphviz  set  of  tools,  like
436              this: dot foo.dot -Tsvg -o foo.svg (png or jpg are also possible
437              as output format). There is also a utility called  'xdot'  which
438              allows  you to view the .dot file directly without converting it
439              first.
440              When the pipeline changes state through NULL to PLAYING and back
441              to  NULL, a dot file is generated on each state change. To write
442              a snapshot of the pipeline state, send a SIGHUP to the process.
443
444       GST_REGISTRY
445              Path   of    the    plugin    registry    file.    Default    is
446              ~/.cache/gstreamer-1.0/registry-CPU.bin   where   CPU   is   the
447              machine/cpu  type  GStreamer  was  compiled  for,  e.g.  'i486',
448              'i686',  'x86-64',  'ppc',  etc. (check the output of "uname -i"
449              and "uname -m" for details).
450
451       GST_REGISTRY_UPDATE
452              Set to "no" to force GStreamer to assume that  no  plugins  have
453              changed,  been  added  or been removed. This will make GStreamer
454              skip the initial check whether a rebuild of the  registry  cache
455              is  required or not. This may be useful in embedded environments
456              where the installed plugins never change. Do not use this option
457              in any other setup.
458
459       GST_PLUGIN_PATH
460              Specifies  a list of directories to scan for additional plugins.
461              These take precedence over the system plugins.
462
463       GST_PLUGIN_SYSTEM_PATH
464              Specifies a list of plugins that are always loaded  by  default.
465              If  not set, this defaults to the system-installed path, and the
466              plugins installed in the user's home directory
467
468       GST_DEBUG_FILE
469              Set this variable to a file path to redirect all GStreamer debug
470              messages  to  this  file.  If left unset, debug messages with be
471              output unto the standard error.
472
473       ORC_CODE
474              Useful Orc environment variable. Set  ORC_CODE=debug  to  enable
475              debuggers  such as gdb to create useful backtraces from Orc-gen‐
476              erated code.  Set ORC_CODE=backup  or  ORC_CODE=emulate  if  you
477              suspect  Orc's  SIMD code generator is producing incorrect code.
478              (Quite a few  important  GStreamer  plugins  like  videotestsrc,
479              audioconvert or audioresample use Orc).
480
481       G_DEBUG
482              Useful  GLib environment variable. Set G_DEBUG=fatal_warnings to
483              make GStreamer programs abort when a critical warning such as an
484              assertion failure occurs. This is useful if you want to find out
485              which part of the code caused that warning to be  triggered  and
486              under  what circumstances. Simply set G_DEBUG as mentioned above
487              and run the program in gdb (or let it core  dump).  Then  get  a
488              stack trace in the usual way.
489

FILES

491       ~/.cache/gstreamer-1.0/registry-*.bin
492               The  plugin  cache; can be deleted at any time, will be re-cre‐
493               ated automatically when  it  does  not  exist  yet  or  plugins
494               change.  Based on XDG_CACHE_DIR, so may be in a different loca‐
495               tion than the one suggested.
496

SEE ALSO

498       gst-inspect-1.0(1), gst-launch-1.0(1),
499

AUTHOR

501       The GStreamer team at http://gstreamer.freedesktop.org/
502
503
504
505                                   May 2007                       GStreamer(1)
Impressum