markdown/tools/gst-launch.md

   1 # gst-launch-1.0
   2
   3 > ![information] This is the Linux man page for
   4 > the `gst-inspect-1.0` tool. As such, it is very Linux-centric
   5 > regarding path specification and plugin names. Please be patient while
   6 > it is rewritten to be more generic.
   7
   8 ## Name
   9
  10 gst-launch-1.0 - build and run a GStreamer pipeline
  11
  12 ## Synopsis
  13
  14 **gst-launch-1.0** *\[OPTION...\]* PIPELINE-DESCRIPTION
  15
  16 ## Description
  17
  18 *gst-launch-1.0* is a tool that builds and runs
  19 basic *GStreamer* pipelines.
  20
  21 In simple form, a PIPELINE-DESCRIPTION is a list of elements separated
  22 by exclamation marks (!). Properties may be appended to elements, in the
  23 form*property=value*.
  24
  25 For a complete description of possible PIPELINE-DESCRIPTIONS see the
  26 section*pipeline description* below or consult the GStreamer
  27 documentation.
  28
  29 Please note that *gst-launch-1.0* is primarily a debugging tool for
  30 developers and users. You should not build applications on top of it.
  31 For applications, use the gst\_parse\_launch() function of the GStreamer
  32 API as an easy way to construct pipelines from pipeline descriptions.
  33
  34 ## Options
  35
  36 *gst-launch-1.0* accepts the following options:
  37
  38 **--help**
  39
  40 Print help synopsis and available FLAGS
  41
  42 **-v, --verbose**
  43
  44 Output status information and property notifications
  45
  46 **-q, --quiet**
  47
  48 Do not print any progress information
  49
  50 **-m, --messages**
  51
  52 Output messages posted on the pipeline's bus
  53
  54 **-t, --tags**
  55
  56 Output tags (also known as metadata)
  57
  58 **-o FILE, --output=FILE**
  59
  60 Save XML representation of pipeline to FILE and exit
  61
  62 **-f, --no\_fault**
  63
  64 Do not install a fault handler
  65
  66 **-T, --trace**
  67
  68 Print memory allocation traces. The feature must be enabled at compile
  69 time to work.
  70
  71
  72
  73 ## Gstreamer Options
  74
  75 *gst-launch-1.0* also accepts the following options that are common to
  76 all GStreamer applications:
  77
  78 ## Pipeline Description
  79
  80 A pipeline consists *elements* and *links*. *Elements* can be put
  81 into *bins* of different sorts. *Elements*, *links* and *bins* can be
  82 specified in a pipeline description in any order.
  83
  84 **Elements**
  85
  86 ELEMENTTYPE *\[PROPERTY1 ...\]*
  87
  88 Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
  89
  90 **Properties**
  91
  92 PROPERTY=VALUE ...
  93
  94 Sets the property to the specified value. You can
  95 use **gst-inspect-1.0**(1) to find out about properties and allowed
  96 values of different elements. Enumeration properties can be set by name,
  97 nick or value.
  98
  99 **Bins**
 100
 101 *\[BINTYPE.\]* ( *\[PROPERTY1 ...\]* PIPELINE-DESCRIPTION )
 102
 103 Specifies that a bin of type BINTYPE is created and the given properties
 104 are set. Every element between the braces is put into the bin. Please
 105 note the dot that has to be used after the BINTYPE. You will almost
 106 never need this functionality, it is only really useful for applications
 107 using the gst\_launch\_parse() API with 'bin' as bintype. That way it is
 108 possible to build partial pipelines instead of a full-fledged top-level
 109 pipeline.
 110
 111 **Links**
 112
 113 *\[\[SRCELEMENT\].\[PAD1,...\]\]* ! *\[\[SINKELEMENT\].\[PAD1,...\]\]
 114 \[\[SRCELEMENT\].\[PAD1,...\]\]* ! CAPS
 115 ! *\[\[SINKELEMENT\].\[PAD1,...\]\]*
 116
 117 Links the element with name SRCELEMENT to the element with name
 118 SINKELEMENT, using the caps specified in CAPS as a filter. Names can be
 119 set on elements with the name property. If the name is omitted, the
 120 element that was specified directly in front of or after the link is
 121 used. This works across bins. If a padname is given, the link is done
 122 with these pads. If no pad names are given all possibilities are tried
 123 and a matching pad is used. If multiple padnames are given, both sides
 124 must have the same number of pads specified and multiple links are done
 125 in the given order. So the simplest link is a simple exclamation mark,
 126 that links the element to the left of it to the element right of it.
 127
 128 **Caps**
 129
 130 MIMETYPE *\[, PROPERTY\[, PROPERTY ...\]\]\] \[; CAPS\[; CAPS ...\]\]*
 131
 132 Creates a capability with the given mimetype and optionally with given
 133 properties. The mimetype can be escaped using " or '. If you want to
 134 chain caps, you can add more caps in the same format afterwards.
 135
 136 **Properties**
 137
 138 NAME=*\[(TYPE)\]*VALUE in lists and ranges: *\[(TYPE)\]*VALUE
 139
 140 Sets the requested property in capabilities. The name is an alphanumeric
 141 value and the type can have the following case-insensitive values:
 142 - **i** or **int** for integer values or ranges - **f** or **float** for
 143 float values or ranges - **4** or **fourcc** for FOURCC values
 144 - **b**, **bool** or **boolean** for boolean values
 145 - **s**, **str** or **string** for strings - **fraction** for fractions
 146 (framerate, pixel-aspect-ratio) - **l** or **list** for lists If no type
 147 was given, the following order is tried: integer, float, boolean,
 148 string. Integer values must be parsable by **strtol()**, floats
 149 by **strtod()**. FOURCC values may either be integers or strings.
 150 Boolean values are (case insensitive) *yes*, *no*, *true* or *false* and
 151 may like strings be escaped with " or '. Ranges are in this format: \[
 152 VALUE, VALUE \] Lists use this format: ( VALUE *\[, VALUE ...\]* )
 153
 154 ## Pipeline Control
 155
 156 A pipeline can be controlled by signals. SIGUSR2 will stop the pipeline
 157 (GST\_STATE\_NULL); SIGUSR1 will put it back to play
 158 (GST\_STATE\_PLAYING). By default, the pipeline will start in the
 159 playing state. There are currently no signals defined to go into the
 160 ready or pause (GST\_STATE\_READY and GST\_STATE\_PAUSED) state
 161 explicitely.
 162
 163 ## Pipeline Examples
 164
 165 The examples below assume that you have the correct plug-ins available.
 166 In general, "osssink" can be substituted with another audio output
 167 plug-in such as "directsoundsink", "esdsink", "alsasink",
 168 "osxaudiosink", or "artsdsink". Likewise, "xvimagesink" can be
 169 substituted with "d3dvideosink", "ximagesink", "sdlvideosink",
 170 "osxvideosink", or "aasink". Keep in mind though that different sinks
 171 might accept different formats and even the same sink might accept
 172 different formats on different machines, so you might need to add
 173 converter elements like audioconvert and audioresample (for audio) or
 174 videoconvert (for video) in front of the sink to make things work.
 175
 176 **Audio playback**
 177
 178 `gst-launch-1.0 filesrc location=music.mp3 ! mad ! audioconvert !
 179 audioresample ! osssink` Play the mp3 music file "music.mp3" using a
 180 libmad-based plug-in and output to an OSS device
 181
 182 `gst-launch-1.0 filesrc location=music.ogg ! oggdemux ! vorbisdec !
 183 audioconvert ! audioresample ! osssink` Play an Ogg Vorbis format file
 184
 185 `gst-launch-1.0 gnomevfssrc location=music.mp3 ! mad ! osssink
 186 gst-launch-1.0 gnomevfssrc location=<http://domain.com/music.mp3> ! mad
 187 ! audioconvert ! audioresample ! osssink` Play an mp3 file or an http
 188 stream using GNOME-VFS
 189
 190 `gst-launch-1.0 gnomevfssrc location=<smb://computer/music.mp3> ! mad !
 191 audioconvert ! audioresample ! osssink` Use GNOME-VFS to play an mp3
 192 file located on an SMB server
 193
 194 **Format conversion**
 195
 196 `gst-launch-1.0 filesrc location=music.mp3 ! mad ! audioconvert !
 197 vorbisenc ! oggmux ! filesink location=music.ogg` Convert an mp3 music
 198 file to an Ogg Vorbis file
 199
 200 `gst-launch-1.0 filesrc location=music.mp3 ! mad ! audioconvert !
 201 flacenc ! filesink location=test.flac` Convert to the FLAC format
 202
 203 **Other**
 204
 205 `gst-launch-1.0 filesrc location=music.wav ! wavparse ! audioconvert !
 206 audioresample ! osssink` Plays a .WAV file that contains raw audio data
 207 (PCM).
 208
 209 `gst-launch-1.0 filesrc location=music.wav ! wavparse ! audioconvert !
 210 vorbisenc ! oggmux ! filesink location=music.ogg gst-launch-1.0 filesrc
 211 location=music.wav ! wavparse ! audioconvert ! lame ! filesink
 212 location=music.mp3` Convert a .WAV file containing raw audio data into
 213 an Ogg Vorbis or mp3 file
 214
 215 `gst-launch-1.0 cdparanoiasrc mode=continuous ! audioconvert ! lame !
 216 id3v2mux ! filesink location=cd.mp3` rips all tracks from compact disc
 217 and convert them into a single mp3 file
 218
 219 `gst-launch-1.0 cdparanoiasrc track=5 ! audioconvert ! lame ! id3v2mux
 220 ! filesink location=track5.mp3` rips track 5 from the CD and converts
 221 it into a single mp3 file
 222
 223 Using **gst-inspect-1.0**(1), it is possible to discover settings like
 224 the above for cdparanoiasrc that will tell it to rip the entire cd or
 225 only tracks of it. Alternatively, you can use an URI and gst-launch-1.0
 226 will find an element (such as cdparanoia) that supports that protocol
 227 for you, e.g.: `gst-launch-1.0 \[cdda://5\] ! lame vbr=new
 228 vbr-quality=6 ! filesink location=track5.mp3`
 229
 230 `gst-launch-1.0 osssrc ! audioconvert ! vorbisenc ! oggmux ! filesink
 231 location=input.ogg` records sound from your audio input and encodes it
 232 into an ogg file
 233
 234 **Video**
 235
 236 `gst-launch-1.0 filesrc location=JB\_FF9\_TheGravityOfLove.mpg !
 237 dvddemux ! mpeg2dec ! xvimagesink` Display only the video portion of an
 238 MPEG-1 video file, outputting to an X display window
 239
 240 `gst-launch-1.0 filesrc location=/flflfj.vob ! dvddemux ! mpeg2dec !
 241 sdlvideosink` Display the video portion of a .vob file (used on DVDs),
 242 outputting to an SDL window
 243
 244 `gst-launch-1.0 filesrc location=movie.mpg ! dvddemux name=demuxer
 245 demuxer. ! queue ! mpeg2dec ! sdlvideosink demuxer. ! queue ! mad !
 246 audioconvert ! audioresample ! osssink` Play both video and audio
 247 portions of an MPEG movie
 248
 249 `gst-launch-1.0 filesrc location=movie.mpg ! mpegdemux name=demuxer
 250 demuxer. ! queue ! mpeg2dec ! videoconvert ! sdlvideosink demuxer. !
 251 queue ! mad ! audioconvert ! audioresample ! osssink` Play an AVI movie
 252 with an external text subtitle stream
 253
 254 This example also shows how to refer to specific pads by name if an
 255 element (here: textoverlay) has multiple sink or source pads.
 256
 257 `gst-launch-1.0 textoverlay name=overlay ! videoconvert !
 258 videoscale ! autovideosink filesrc location=movie.avi ! decodebin2 !
 259 videoconvert ! overlay.video\_sink filesrc location=movie.srt !
 260 subparse ! overlay.text\_sink`
 261
 262 Play an AVI movie with an external text subtitle stream using playbin
 263
 264 `gst-launch-1.0 playbin uri=<file:///path/to/movie.avi>
 265 suburi=<file:///path/to/movie.srt>`
 266
 267 **Network streaming**
 268
 269 Stream video using RTP and network elements.
 270
 271 `gst-launch-1.0 v4l2src !
 272 video/x-raw-yuv,width=128,height=96,format='(fourcc)'UYVY !
 273 videoconvert ! ffenc\_h263 ! video/x-h263 ! rtph263ppay pt=96 !
 274 udpsink host=192.168.1.1 port=5000 sync=false` Use this command on the
 275 receiver
 276
 277 `gst-launch-1.0 udpsrc port=5000 ! application/x-rtp,
 278 clock-rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec\_h263
 279 ! xvimagesink` This command would be run on the transmitter
 280
 281 **Diagnostic**
 282
 283 `gst-launch-1.0 -v fakesrc num-buffers=16 ! fakesink` Generate a null
 284 stream and ignore it (and print out details).
 285
 286 `gst-launch-1.0 audiotestsrc ! audioconvert ! audioresample ! osssink`
 287 Generate a pure sine tone to test the audio output
 288
 289 `gst-launch-1.0 videotestsrc ! xvimagesink gst-launch-1.0 videotestsrc
 290 ! ximagesink` Generate a familiar test pattern to test the video output
 291
 292 **Automatic linking**
 293
 294 You can use the decodebin element to automatically select the right
 295 elements to get a working pipeline.
 296
 297 `gst-launch-1.0 filesrc location=musicfile ! decodebin ! audioconvert !
 298 audioresample ! osssink` Play any supported audio format
 299
 300 `gst-launch-1.0 filesrc location=videofile ! decodebin name=decoder
 301 decoder. ! queue ! audioconvert ! audioresample ! osssink decoder. !
 302 videoconvert ! xvimagesink` Play any supported video format with
 303 video and audio output. Threads are used automatically. To make this
 304 even easier, you can use the playbin element:
 305
 306 `gst-launch-1.0 playbin uri=<file:///home/joe/foo.avi>`
 307
 308 **Filtered connections**
 309
 310 These examples show you how to use filtered caps.
 311
 312 `gst-launch-1.0 videotestsrc !
 313 'video/x-raw-yuv,format=(fourcc)YUY2;video/x-raw-yuv,format=(fourcc)YV12'
 314 ! xvimagesink` Show a test image and use the YUY2 or YV12 video format
 315 for this.
 316
 317 `gst-launch-1.0 osssrc !
 318 'audio/x-raw-int,rate=\[32000,64000\],width=\[16,32\],depth={16,24,32},signed=(boolean)true'
 319 ! wavenc ! filesink location=recording.wav` record audio and write it
 320 to a .wav file. Force usage of signed 16 to 32 bit samples and a sample
 321 rate between 32kHz and 64KHz.
 322
 323 ## Environment Variables
 324
 325 `GST\_DEBUG`: Comma-separated list of debug categories and levels,
 326 e.g. GST\_DEBUG= totem:4,typefind:5
 327
 328 `GST\_DEBUG\_NO\_COLOR`: When this environment variable is set,
 329 coloured debug output is disabled.
 330
 331 `GST\_DEBUG\_DUMP\_DOT\_DIR`: When set to a filesystem path, store dot
 332 files of pipeline graphs there.
 333
 334 `GST\_REGISTRY`: Path of the plugin registry file. Default is
 335 \~/.gstreamer-1.0/registry-CPU.xml where CPU is the machine/cpu type
 336 GStreamer was compiled for, e.g. 'i486', 'i686', 'x86-64', 'ppc', etc.
 337 (check the output of "uname -i" and "uname -m" for details).
 338
 339 `GST\_REGISTRY\_UPDATE`: Set to "no" to force GStreamer to assume that
 340 no plugins have changed, been added or been removed. This will make
 341 GStreamer skip the initial check whether a rebuild of the registry cache
 342 is required or not. This may be useful in embedded environments where
 343 the installed plugins never change. Do not use this option in any other
 344 setup.
 345
 346 `GST\_PLUGIN\_PATH`: Specifies a list of directories to scan for
 347 additional plugins. These take precedence over the system plugins.
 348
 349 `GST\_PLUGIN\_SYSTEM\_PATH`: Specifies a list of plugins that are
 350 always loaded by default. If not set, this defaults to the
 351 system-installed path, and the plugins installed in the user's home
 352 directory
 353
 354 `OIL\_CPU\_FLAGS`: Useful liboil environment variable. Set
 355 OIL\_CPU\_FLAGS=0 when valgrind or other debugging tools trip over
 356 liboil's CPU detection (quite a few important GStreamer plugins like
 357 videotestsrc, audioconvert or audioresample use liboil).
 358
 359 `G\_DEBUG`: Useful GLib environment variable. Set
 360 G\_DEBUG=fatal\_warnings to make GStreamer programs abort when a
 361 critical warning such as an assertion failure occurs. This is useful if
 362 you want to find out which part of the code caused that warning to be
 363 triggered and under what circumstances. Simply set G\_DEBUG as mentioned
 364 above and run the program in gdb (or let it core dump). Then get a stack
 365 trace in the usual way
 366
 367   [information]: images/icons/emoticons/information.png