tools/gst-launch.1.in

   1 .TH "GStreamer" "1" "May 2007"
   2 .SH "NAME"
   3 gst\-launch \- build and run a GStreamer pipeline
   4 .SH "SYNOPSIS"
   5 \fBgst\-launch\fR \fI[OPTION...]\fR PIPELINE\-DESCRIPTION
   6 .SH "DESCRIPTION"
   7 .LP
   8 \fIgst\-launch\fP is a tool that builds and runs basic
   9 \fIGStreamer\fP pipelines.
  10
  11 In simple form, a PIPELINE\-DESCRIPTION is a list of
  12 elements separated by exclamation marks (!). Properties may be appended to
  13 elements, in the form \fIproperty=value\fR.
  14
  15 For a complete description of possible PIPELINE-DESCRIPTIONS see the section
  16 \fIpipeline description\fR below or consult the GStreamer documentation.
  17
  18 Please note that \fIgst\-launch\fP is primarily a debugging tool for
  19 developers and users. You should not build applications on top of it. For
  20 applications, use the gst_parse_launch() function of the GStreamer API as an
  21 easy way to construct pipelines from pipeline descriptions.
  22 .
  23 .SH "OPTIONS"
  24 .l
  25 \fIgst\-launch\fP accepts the following options:
  26 .TP 8
  27 .B  \-\-help
  28 Print help synopsis and available FLAGS
  29 .TP 8
  30 .B  \-v, \-\-verbose
  31 Output status information and property notifications
  32 .TP 8
  33 .B  \-q, \-\-quiet
  34 Do not print any progress information
  35 .TP 8
  36 .B  \-m, \-\-messages
  37 Output messages posted on the pipeline's bus
  38 .TP 8
  39 .B  \-t, \-\-tags
  40 Output tags (also known as metadata)
  41 .TP 8
  42 .B  \-e, \-\-eos\-on\-shutdown
  43 Force an EOS event on sources before shutting the pipeline down. This is
  44 useful to make sure muxers create readable files when a muxing pipeline is
  45 shut down forcefully via Control-C.
  46 .TP 8
  47 .B  \-i, \-\-index
  48 Gather and print index statistics. This is mostly useful for playback or
  49 recording pipelines.
  50 .TP 8
  51 .B  \-o FILE, \-\-output=FILE
  52 Save XML representation of pipeline to FILE and exit (DEPRECATED, DO NOT USE)
  53 .TP 8
  54 .B  \-f, \-\-no\-fault
  55 Do not install a fault handler
  56 .TP 8
  57 .B  \-T, \-\-trace
  58 Print memory allocation traces. The feature must be enabled at compile time to
  59 work.
  60 .TP 8
  61
  62 .
  63 .SH "GSTREAMER OPTIONS"
  64 .l
  65 \fIgst\-launch\fP also accepts the following options that are common
  66 to all GStreamer applications:
  67 .TP 8
  68 .B  \-\-gst\-version
  69 Prints the version string of the \fIGStreamer\fP core library.
  70 .TP 8
  71 .B  \-\-gst\-fatal\-warnings
  72 Causes \fIGStreamer\fP to abort if a warning message occurs. This is equivalent
  73 to setting the environment variable G_DEBUG to 'fatal_warnings' (see the
  74 section \fIenvironment variables\fR below for further information).
  75 .TP 8
  76 .B  \-\-gst\-debug=STRING
  77 A comma separated list of category_name:level pairs to specify debugging levels
  78 for each category. Level is in the range 0-5 where 0 will show no messages, and
  79 5 will show all messages. The wildcard * can be used to match category names.
  80
  81 Use \-\-gst\-debug\-help to show category names
  82
  83 Example:
  84 GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
  85
  86 .TP 8
  87 .B  \-\-gst\-debug\-level=LEVEL
  88 Sets the threshold for printing debugging messages.  A higher level
  89 will print more messages.  The useful range is 0-5, with the default
  90 being 0.
  91 .TP 8
  92 .B  \-\-gst\-debug\-no\-color
  93 \fIGStreamer\fP normally prints debugging messages so that the
  94 messages are color-coded when printed to a terminal that handles
  95 ANSI escape sequences.  Using this option causes \fIGStreamer\fP
  96 to print messages without color. Setting the \fBGST_DEBUG_NO_COLOR\fR
  97 environment variable will achieve the same thing.
  98 .TP 8
  99 .B  \-\-gst\-debug\-disable
 100 Disables debugging.
 101 .TP 8
 102 .B  \-\-gst\-debug\-help
 103 Prints a list of available debug categories and their default debugging level.
 104 .TP 8
 105 .B  \-\-gst\-plugin\-spew
 106 \fIGStreamer\fP info flags to set
 107 Enable printout of errors while loading \fIGStreamer\fP plugins
 108 .TP 8
 109 .B  \-\-gst\-plugin\-path=PATH
 110 Add directories separated with ':' to the plugin search path
 111 .TP 8
 112 .B  \-\-gst\-plugin\-load=PLUGINS
 113 Preload plugins specified in a comma-separated list. Another way to specify
 114 plugins to preload is to use the environment variable GST_PLUGIN_PATH
 115
 116 .SH "PIPELINE DESCRIPTION"
 117
 118 A pipeline consists \fIelements\fR and \fIlinks\fR. \fIElements\fR can be put
 119 into \fIbins\fR of different sorts. \fIElements\fR, \fIlinks\fR and \fIbins\fR
 120 can be specified in a pipeline description in any order.
 121
 122 .B Elements
 123
 124 ELEMENTTYPE \fI[PROPERTY1 ...]\fR
 125
 126 Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
 127
 128 .B Properties
 129
 130 PROPERTY=VALUE ...
 131
 132 Sets the property to the specified value. You can use \fBgst\-inspect\fR(1) to
 133 find out about properties and allowed values of different elements.
 134 .br
 135 Enumeration properties can be set by name, nick or value.
 136
 137 .B Bins
 138
 139 \fI[BINTYPE.]\fR ( \fI[PROPERTY1 ...]\fR PIPELINE-DESCRIPTION )
 140 .br
 141
 142 Specifies that a bin of type BINTYPE is created and the given properties are
 143 set. Every element between the braces is put into the bin. Please note the dot
 144 that has to be used after the BINTYPE. You will almost never need this
 145 functionality, it is only really useful for applications using the
 146 gst_launch_parse() API with 'bin' as bintype. That way it is possible to build
 147 partial pipelines instead of a full-fledged top-level pipeline.
 148
 149 .B Links
 150
 151 \fI[[SRCELEMENT].[PAD1,...]]\fR ! \fI[[SINKELEMENT].[PAD1,...]]\fR
 152 \fI[[SRCELEMENT].[PAD1,...]]\fR ! CAPS ! \fI[[SINKELEMENT].[PAD1,...]]\fR
 153
 154 Links the element with name SRCELEMENT to the element with name SINKELEMENT,
 155 using the caps specified in CAPS as a filter.
 156 Names can be set on elements with the name property. If the name is omitted, the
 157 element that was specified directly in front of or after the link is used. This
 158 works across bins. If a padname is given, the link is done with these pads. If
 159 no pad names are given all possibilities are tried and a matching pad is used.
 160 If multiple padnames are given, both sides must have the same number of pads
 161 specified and multiple links are done in the given order.
 162 .br
 163 So the simplest link is a simple exclamation mark, that links the element to
 164 the left of it to the element right of it.
 165 .br
 166
 167 .B Caps
 168
 169 MIMETYPE \fI[, PROPERTY[, PROPERTY ...]]]\fR \fI[; CAPS[; CAPS ...]]\fR
 170
 171 Creates a capability with the given mimetype and optionally with given
 172 properties. The mimetype can be escaped using " or '.
 173 If you want to chain caps, you can add more caps in the same format afterwards.
 174
 175 .B Properties
 176
 177 NAME=\fI[(TYPE)]\fRVALUE
 178 .br
 179 in lists and ranges: \fI[(TYPE)]\fRVALUE
 180
 181 Sets the requested property in capabilities. The name is an alphanumeric value
 182 and the type can have the following case-insensitive values:
 183 .br
 184 - \fBi\fR or \fBint\fR for integer values or ranges
 185 .br
 186 - \fBf\fR or \fBfloat\fR for float values or ranges
 187 .br
 188 - \fB4\fR or \fBfourcc\fR for FOURCC values
 189 .br
 190 - \fBb\fR, \fBbool\fR or \fBboolean\fR for boolean values
 191 .br
 192 - \fBs\fR, \fBstr\fR or \fBstring\fR for strings
 193 .br
 194 - \fBfraction\fR for fractions (framerate, pixel-aspect-ratio)
 195 .br
 196 - \fBl\fR or \fBlist\fR for lists
 197 .br
 198 If no type was given, the following order is tried: integer, float, boolean,
 199 string.
 200 .br
 201 Integer values must be parsable by \fBstrtol()\fP, floats by \fBstrtod()\fP. FOURCC values may
 202 either be integers or strings. Boolean values are (case insensitive) \fIyes\fR,
 203 \fIno\fR, \fItrue\fR or \fIfalse\fR and may like strings be escaped with " or '.
 204 .br
 205 Ranges are in this format:  [ VALUE, VALUE ]
 206 .br
 207 Lists use this format:      ( VALUE \fI[, VALUE ...]\fR )
 208
 209 .SH "PIPELINE EXAMPLES"
 210
 211 The examples below assume that you have the correct plug-ins available.
 212 In general, "osssink" can be substituted with another audio output
 213 plug-in such as "esdsink", "alsasink", "osxaudiosink", or "artsdsink".
 214 Likewise, "xvimagesink" can be substituted with "ximagesink", "sdlvideosink",
 215 "osxvideosink", or "aasink". Keep in mind though that different sinks might
 216 accept different formats and even the same sink might accept different formats
 217 on different machines, so you might need to add converter elements like
 218 audioconvert and audioresample (for audio) or ffmpegcolorspace (for video)
 219 in front of the sink to make things work.
 220
 221 .B Audio playback
 222
 223 .B
 224         gst\-launch filesrc location=music.mp3 ! mad ! audioconvert ! audioresample ! osssink
 225 .br
 226 Play the mp3 music file "music.mp3" using a libmad-based plug-in and
 227 output to an OSS device
 228
 229 .B
 230         gst\-launch filesrc location=music.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! osssink
 231 .br
 232 Play an Ogg Vorbis format file
 233
 234 .B
 235         gst\-launch gnomevfssrc location=music.mp3 ! mad ! osssink
 236 .br
 237 .B
 238         gst\-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! audioconvert ! audioresample ! osssink
 239 .br
 240 Play an mp3 file or an http stream using GNOME\-VFS
 241
 242 .B
 243         gst\-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! audioconvert ! audioresample ! osssink
 244 .br
 245 Use GNOME\-VFS to play an mp3 file located on an SMB server
 246
 247 .B Format conversion
 248
 249 .B
 250         gst\-launch filesrc location=music.mp3 ! mad ! audioconvert ! vorbisenc ! oggmux ! filesink location=music.ogg
 251 .br
 252 Convert an mp3 music file to an Ogg Vorbis file
 253
 254 .B
 255         gst\-launch filesrc location=music.mp3 ! mad ! audioconvert ! flacenc ! filesink location=test.flac
 256 .br
 257 Convert to the FLAC format
 258
 259 .B Other
 260
 261 .B
 262         gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! audioresample ! osssink
 263 .br
 264 Plays a .WAV file that contains raw audio data (PCM).
 265
 266 .B
 267         gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! vorbisenc ! oggmux ! filesink location=music.ogg
 268 .br
 269 .B
 270         gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! lame ! filesink location=music.mp3
 271 .br
 272 Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3 file
 273
 274 .B
 275         gst\-launch cdparanoiasrc mode=continuous ! audioconvert ! lame ! id3v2mux ! filesink location=cd.mp3
 276 .br
 277 rips all tracks from compact disc and convert them into a single mp3 file
 278
 279 .B
 280         gst\-launch cdparanoiasrc track=5 ! audioconvert ! lame ! id3v2mux ! filesink location=track5.mp3
 281 .br
 282 rips track 5 from the CD and converts it into a single mp3 file
 283
 284 Using \fBgst\-inspect\fR(1), it is possible to discover settings like the above
 285 for cdparanoiasrc that will tell it to rip the entire cd or only tracks of it.
 286 Alternatively, you can use an URI and gst-launch will find an element (such as
 287 cdparanoia) that supports that protocol for you, e.g.:
 288 .B
 289        gst\-launch cdda://5 ! lame vbr=new vbr-quality=6 ! filesink location=track5.mp3
 290
 291 .B
 292         gst\-launch osssrc ! audioconvert ! vorbisenc ! oggmux ! filesink location=input.ogg
 293 .br
 294 records sound from your audio input and encodes it into an ogg file
 295
 296 .B Video
 297
 298 .B
 299         gst\-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! dvddemux ! mpeg2dec ! xvimagesink
 300 .br
 301 Display only the video portion of an MPEG-1 video file, outputting to
 302 an X display window
 303
 304 .B
 305         gst\-launch filesrc location=/flflfj.vob ! dvddemux ! mpeg2dec ! sdlvideosink
 306 .br
 307 Display the video portion of a .vob file (used on DVDs), outputting to
 308 an SDL window
 309
 310 .B
 311         gst\-launch filesrc location=movie.mpg ! dvddemux name=demuxer  demuxer. ! queue ! mpeg2dec ! sdlvideosink  demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
 312 .br
 313 Play both video and audio portions of an MPEG movie
 314
 315 .B
 316         gst\-launch filesrc location=movie.mpg ! mpegdemux name=demuxer  demuxer. ! queue ! mpeg2dec ! ffmpegcolorspace ! sdlvideosink   demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
 317 .br
 318 Play an AVI movie with an external text subtitle stream
 319
 320 This example also shows how to refer to specific pads by name if an element
 321 (here: textoverlay) has multiple sink or source pads.
 322
 323 .B
 324         gst\-launch textoverlay name=overlay ! ffmpegcolorspace ! videoscale ! autovideosink   filesrc location=movie.avi ! decodebin2 ! ffmpegcolorspace ! overlay.video_sink   filesrc location=movie.srt ! subparse ! overlay.text_sink
 325
 326 .br
 327 Play an AVI movie with an external text subtitle stream using playbin2
 328
 329 .B
 330         gst\-launch playbin2 uri=file:///path/to/movie.avi suburi=file:///path/to/movie.srt
 331
 332 .B Network streaming
 333
 334 Stream video using RTP and network elements.
 335
 336 .B
 337         gst\-launch v4l2src ! video/x-raw-yuv,width=128,height=96,format='(fourcc)'UYVY ! ffmpegcolorspace ! ffenc_h263 ! video/x-h263 ! rtph263ppay pt=96 ! udpsink host=192.168.1.1 port=5000 sync=false
 338 .br
 339 This command would be run on the transmitter
 340
 341 .B
 342         gst\-launch udpsrc port=5000 ! application/x-rtp, clock-rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec_h263 ! xvimagesink
 343 .br
 344 Use this command on the receiver
 345
 346 .B Diagnostic
 347
 348 .B
 349         gst\-launch -v fakesrc num-buffers=16 ! fakesink
 350 .br
 351 Generate a null stream and ignore it (and print out details).
 352
 353 .B
 354         gst\-launch audiotestsrc ! audioconvert ! audioresample ! osssink
 355 .br
 356 Generate a pure sine tone to test the audio output
 357
 358 .B
 359         gst\-launch videotestsrc ! xvimagesink
 360 .br
 361 .B
 362         gst\-launch videotestsrc ! ximagesink
 363 .br
 364 Generate a familiar test pattern to test the video output
 365
 366 .B Automatic linking
 367
 368 You can use the decodebin element to automatically select the right elements
 369 to get a working pipeline.
 370
 371 .B
 372         gst\-launch filesrc location=musicfile ! decodebin ! audioconvert ! audioresample ! osssink
 373 .br
 374 Play any supported audio format
 375
 376 .B
 377         gst\-launch filesrc location=videofile ! decodebin name=decoder  decoder. ! queue ! audioconvert ! audioresample ! osssink   decoder. ! ffmpegcolorspace ! xvimagesink
 378 .br
 379 Play any supported video format with video and audio output. Threads are used
 380 automatically. To make this even easier, you can use the playbin element:
 381
 382 .B
 383         gst\-launch playbin uri=file:///home/joe/foo.avi
 384 .br
 385
 386
 387 .B Filtered connections
 388
 389 These examples show you how to use filtered caps.
 390
 391 .B
 392         gst\-launch videotestsrc ! 'video/x-raw-yuv,format=(fourcc)YUY2;video/x-raw-yuv,format=(fourcc)YV12' ! xvimagesink
 393 .br
 394 Show a test image and use the YUY2 or YV12 video format for this.
 395
 396 .B
 397         gst\-launch osssrc ! 'audio/x-raw-int,rate=[32000,64000],width=[16,32],depth={16,24,32},signed=(boolean)true' ! wavenc ! filesink location=recording.wav
 398 .br
 399 record audio and write it to a .wav file. Force usage of signed 16 to 32 bit
 400 samples and a sample rate between 32kHz and 64KHz.
 401
 402
 403 .SH "ENVIRONMENT VARIABLES"
 404 .TP
 405 \fBGST_DEBUG\fR
 406 Comma-separated list of debug categories and levels, e.g.
 407 GST_DEBUG=totem:4,typefind:5
 408 .TP
 409 \fBGST_DEBUG_NO_COLOR\fR
 410 When this environment variable is set, coloured debug output is disabled.
 411 .TP
 412 \fBGST_DEBUG_DUMP_DOT_DIR\fR
 413 When set to a filesystem path, store dot files of pipeline graphs there.
 414 .TP
 415 \fBGST_REGISTRY\fR
 416 Path of the plugin registry file. Default is
 417 ~/.gstreamer-GST_MAJORMINOR/registry-CPU.xml where CPU is the machine/cpu type
 418 GStreamer was compiled for, e.g. 'i486', 'i686', 'x86-64', 'ppc', etc. (check
 419 the output of "uname -i" and "uname -m" for details).
 420 .TP
 421 \fBGST_REGISTRY_UPDATE\fR
 422 Set to "no" to force GStreamer to assume that no plugins have changed,
 423 been added or been removed. This will make GStreamer skip the initial check
 424 whether a rebuild of the registry cache is required or not. This may be useful
 425 in embedded environments where the installed plugins never change. Do not
 426 use this option in any other setup.
 427 .TP
 428 \fBGST_PLUGIN_PATH\fR
 429 Specifies a list of directories to scan for additional plugins.
 430 These take precedence over the system plugins.
 431 .TP
 432 \fBGST_PLUGIN_SYSTEM_PATH\fR
 433 Specifies a list of plugins that are always loaded by default.  If not set,
 434 this defaults to the system-installed path, and the plugins installed in the
 435 user's home directory
 436 .TP
 437 \fBORC_CODE\fR
 438 Useful Orc environment variable. Set ORC_CODE=debug to enable debuggers
 439 such as gdb to create useful backtraces from Orc-generated code.  Set
 440 ORC_CODE=backup or ORC_CODE=emulate if you suspect Orc's SIMD code
 441 generator is producing incorrect code.  (Quite a few important
 442 GStreamer plugins like videotestsrc, audioconvert or audioresample use Orc).
 443 .TP
 444 \fBG_DEBUG\fR
 445 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to make
 446 GStreamer programs abort when a critical warning such as an assertion failure
 447 occurs. This is useful if you want to find out which part of the code caused
 448 that warning to be triggered and under what circumstances. Simply set G_DEBUG
 449 as mentioned above and run the program in gdb (or let it core dump). Then get
 450 a stack trace in the usual way.
 451 .
 452 .SH FILES
 453 .TP 8
 454 ~/.gstreamer-GST_MAJORMINOR/registry-*.xml
 455 The xml plugin database; can be deleted at any time, will be re-created
 456 automatically when it does not exist yet or plugins change.
 457 .
 458 .SH "SEE ALSO"
 459 .BR gst\-feedback (1),
 460 .BR gst\-inspect (1),
 461 .BR gst\-typefind (1)
 462 .SH "AUTHOR"
 463 The GStreamer team at http://gstreamer.freedesktop.org/