markdown/tutorials/basic/gstreamer-tools.md

   1 # Basic tutorial 10: GStreamer tools
   2
   3 ## Goal
   4
   5 GStreamer comes with a set of tools which range from handy to
   6 absolutely essential. There is no code in this tutorial, just sit back
   7 and relax, and we will teach you:
   8
   9   - How to build and run GStreamer pipelines from the command line,
  10     without using C at all!
  11   - How to find out what GStreamer elements you have available and their
  12     capabilities.
  13   - How to discover the internal structure of media files.
  14
  15 ## Introduction
  16
  17 These tools are available in the bin directory of the GStreamer
  18 binaries. You need to move to this directory to execute them, because
  19 it is not added to the system’s `PATH` environment variable (to avoid
  20 polluting it too much).
  21
  22 Just open a terminal (or console window) and go to the `bin` directory
  23 of your GStreamer installation (Read again the [Installing
  24 GStreamer](installing/index.md) section to find our where this is),
  25 and you are ready to start typing the commands given in this tutorial.
  26
  27
  28 > ![Information](images/icons/emoticons/information.png)
  29 >
  30 > On Linux, you should use the GStreamer version installed with your
  31 > distribution, the tools should be installed with a package named `gstreamer1`
  32 > on Fedora style distributions, or `gstreamer1.0-tools` on Debian/Ubuntu style
  33 > distributions.
  34
  35 In order to allow for multiple versions of GStreamer to coexists in the
  36 same system, these tools are versioned, this is, a GStreamer version
  37 number is appended to their name. This version is based on
  38 GStreamer 1.0, so the tools are called `gst-launch-1.0`,
  39 `gst-inspect-1.0` and `gst-discoverer-1.0`
  40
  41 ## `gst-launch-1.0`
  42
  43 This tool accepts a textual description of a pipeline, instantiates it,
  44 and sets it to the PLAYING state. It allows you to quickly check if a
  45 given pipeline works, before going through the actual implementation
  46 using GStreamer API calls.
  47
  48 Bear in mind that it can only create simple pipelines. In particular, it
  49 can only simulate the interaction of the pipeline with the application
  50 up to a certain level. In any case, it is extremely handy to test
  51 pipelines quickly, and is used by GStreamer developers around the world
  52 on a daily basis.
  53
  54 Please note that `gst-launch-1.0` is primarily a debugging tool for
  55 developers. You should not build applications on top of it. Instead, use
  56 the `gst_parse_launch()` function of the GStreamer API as an easy way to
  57 construct pipelines from pipeline descriptions.
  58
  59 Although the rules to construct pipeline descriptions are very simple,
  60 the concatenation of multiple elements can quickly make such
  61 descriptions resemble black magic. Fear not, for everyone learns the
  62 `gst-launch-1.0` syntax, eventually.
  63
  64 The command line for gst-launch-1.0 consists of a list of options followed
  65 by a PIPELINE-DESCRIPTION. Some simplified instructions are given next,
  66 se the complete documentation at [the reference page](tools/gst-launch.md)
  67 for `gst-launch-1.0`.
  68
  69 ### Elements
  70
  71 In simple form, a PIPELINE-DESCRIPTION is a list of element types
  72 separated by exclamation marks (!). Go ahead and type in the following
  73 command:
  74
  75 ```
  76 gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink
  77 ```
  78
  79 You should see a windows with an animated video pattern. Use CTRL+C on
  80 the terminal to stop the program.
  81
  82 This instantiates a new element of type `videotestsrc` (an element which
  83 generates a sample video pattern), an `videoconvert` (an element
  84 which does raw video format conversion, making sure other elements can
  85 understand each other), and an `autovideosink` (a window to which video
  86 is rendered). Then, GStreamer tries to link the output of each element
  87 to the input of the element appearing on its right in the description.
  88 If more than one input or output Pad is available, the Pad Caps are used
  89 to find two compatible Pads.
  90
  91 ### Properties
  92
  93 Properties may be appended to elements, in the form
  94 *property=value *(multiple properties can be specified, separated by
  95 spaces). Use the `gst-inspect-1.0` tool (explained next) to find out the
  96 available properties for an
  97 element.
  98
  99 ```
 100 gst-launch-1.0 videotestsrc pattern=11 ! videoconvert ! autovideosink
 101 ```
 102
 103 You should see a static video pattern, made of circles.
 104
 105 ### Named elements
 106
 107 Elements can be named using the `name` property, in this way complex
 108 pipelines involving branches can be created. Names allow linking to
 109 elements created previously in the description, and are indispensable to
 110 use elements with multiple output pads, like demuxers or tees, for
 111 example.
 112
 113 Named elements are referred to using their name followed by a
 114 dot.
 115
 116 ```
 117 gst-launch-1.0 videotestsrc ! videoconvert ! tee name=t ! queue ! autovideosink t. ! queue ! autovideosink
 118 ```
 119
 120 You should see two video windows, showing the same sample video pattern.
 121 If you see only one, try to move it, since it is probably on top of the
 122 second window.
 123
 124 This example instantiates a `videotestsrc`, linked to a
 125 `videoconvert`, linked to a `tee` (Remember from [](tutorials/basic/multithreading-and-pad-availability.md) that
 126 a `tee` copies to each of its output pads everything coming through its
 127 input pad). The `tee` is named simply ‘t’ (using the `name` property)
 128 and then linked to a `queue` and an `autovideosink`. The same `tee` is
 129 referred to using ‘t.’ (mind the dot) and then linked to a second
 130 `queue` and a second `autovideosink`.
 131
 132 To learn why the queues are necessary read [](tutorials/basic/multithreading-and-pad-availability.md).
 133
 134 ### Pads
 135
 136 Instead of letting GStreamer choose which Pad to use when linking two
 137 elements, you may want to specify the Pads directly. You can do this by
 138 adding a dot plus the Pad name after the name of the element (it must be
 139 a named element). Learn the names of the Pads of an element by using
 140 the `gst-inspect-1.0` tool.
 141
 142 This is useful, for example, when you want to retrieve one particular
 143 stream out of a
 144 demuxer:
 145
 146 ```
 147 gst-launch-1.0 souphttpsrc location=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! matroskademux name=d d.video_00 ! matroskamux ! filesink location=sintel_video.mkv
 148 ```
 149
 150 This fetches a media file from the internet using `souphttpsrc`, which
 151 is in webm format (a special kind of Matroska container, see [](tutorials/basic/concepts.md)). We
 152 then open the container using `matroskademux`. This media contains both
 153 audio and video, so `matroskademux` will create two output Pads, named
 154 `video_00` and `audio_00`. We link `video_00` to a `matroskamux` element
 155 to re-pack the video stream into a new container, and finally link it to
 156 a `filesink`, which will write the stream into a file named
 157 "sintel\_video.mkv" (the `location` property specifies the name of the
 158 file).
 159
 160 All in all, we took a webm file, stripped it of audio, and generated a
 161 new matroska file with the video. If we wanted to keep only the
 162 audio:
 163
 164 ```
 165 gst-launch-1.0 souphttpsrc location=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! matroskademux name=d d.audio_00 ! vorbisparse ! matroskamux ! filesink location=sintel_audio.mka
 166 ```
 167
 168 The `vorbisparse` element is required to extract some information from
 169 the stream and put it in the Pad Caps, so the next element,
 170 `matroskamux`, knows how to deal with the stream. In the case of video
 171 this was not necessary, because `matroskademux` already extracted this
 172 information and added it to the Caps.
 173
 174 Note that in the above two examples no media has been decoded or played.
 175 We have just moved from one container to another (demultiplexing and
 176 re-multiplexing again).
 177
 178 ### Caps filters
 179
 180 When an element has more than one output pad, it might happen that the
 181 link to the next element is ambiguous: the next element may have more
 182 than one compatible input pad, or its input pad may be compatible with
 183 the Pad Caps of all the output pads. In these cases GStreamer will link
 184 using the first pad that is available, which pretty much amounts to
 185 saying that GStreamer will choose one output pad at random.
 186
 187 Consider the following
 188 pipeline:
 189
 190 ```
 191 gst-launch-1.0 souphttpsrc location=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! matroskademux ! filesink location=test
 192 ```
 193
 194 This is the same media file and demuxer as in the previous example. The
 195 input Pad Caps of `filesink` are `ANY`, meaning that it can accept any
 196 kind of media. Which one of the two output pads of `matroskademux` will
 197 be linked against the filesink? `video_00` or `audio_00`? You cannot
 198 know.
 199
 200 You can remove this ambiguity, though, by using named pads, as in the
 201 previous sub-section, or by using **Caps
 202 Filters**:
 203
 204 ```
 205 gst-launch-1.0 souphttpsrc location=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! matroskademux ! video/x-vp8 ! matroskamux ! filesink location=sintel_video.mkv
 206 ```
 207
 208 A Caps Filter behaves like a pass-through element which does nothing and
 209 only accepts media with the given Caps, effectively resolving the
 210 ambiguity. In this example, between `matroskademux` and `matroskamux` we
 211 added a `video/x-vp8` Caps Filter to specify that we are interested in
 212 the output pad of `matroskademux` which can produce this kind of video.
 213
 214 To find out the Caps an element accepts and produces, use the
 215 `gst-inspect-1.0` tool. To find out the Caps contained in a particular file,
 216 use the `gst-discoverer-1.0` tool. To find out the Caps an element is
 217 producing for a particular pipeline, run `gst-launch-1.0` as usual, with the
 218 `–v` option to print Caps information.
 219
 220 ### Examples
 221
 222 Play a media file using `playbin` (as in [](tutorials/basic/hello-world.md)):
 223
 224 ```
 225 gst-launch-1.0 playbin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm
 226 ```
 227
 228 A fully operation playback pipeline, with audio and video (more or less
 229 the same pipeline that `playbin` will create
 230 internally):
 231
 232 ```
 233 gst-launch-1.0 souphttpsrc location=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! matroskademux name=d ! queue ! vp8dec ! videoconvert ! autovideosink d. ! queue ! vorbisdec ! audioconvert ! audioresample ! autoaudiosink
 234 ```
 235
 236 A transcoding pipeline, which opens the webm container and decodes both
 237 streams (via uridecodebin), then re-encodes the audio and video branches
 238 with a different codec, and puts them back together in an Ogg container
 239 (just for the sake of
 240 it).
 241
 242 ```
 243 gst-launch-1.0 uridecodebin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm name=d ! queue ! theoraenc ! oggmux name=m ! filesink location=sintel.ogg d. ! queue ! audioconvert ! audioresample ! flacenc ! m.
 244 ```
 245
 246 A rescaling pipeline. The `videoscale` element performs a rescaling
 247 operation whenever the frame size is different in the input and the
 248 output caps. The output caps are set by the Caps Filter to
 249 320x200.
 250
 251 ```
 252 gst-launch-1.0 uridecodebin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! queue ! videoscale ! video/x-raw-yuv,width=320,height=200 ! videoconvert ! autovideosink
 253 ```
 254
 255 This short description of `gst-launch-1.0` should be enough to get you
 256 started. Remember that you have the [complete documentation available
 257 here](tools/gst-launch.md).
 258
 259 ## `gst-inspect-1.0`
 260
 261 This tool has three modes of operation:
 262
 263   - Without arguments, it lists all available elements types, this is,
 264     the types you can use to instantiate new elements.
 265   - With a file name as an argument, it treats the file as a GStreamer
 266     plugin, tries to open it, and lists all the elements described
 267     inside.
 268   - With a GStreamer element name as an argument, it lists all
 269     information regarding that element.
 270
 271 Let's see an example of the third mode:
 272
 273 ```
 274 gst-inspect-1.0 vp8dec
 275
 276 Factory Details:
 277   Rank                     primary (256)
 278   Long-name                On2 VP8 Decoder
 279   Klass                    Codec/Decoder/Video
 280   Description              Decode VP8 video streams
 281   Author                   David Schleef <ds@entropywave.com>, Sebastian Dröge <sebastian.droege@collabora.co.uk>
 282
 283 Plugin Details:
 284   Name                     vpx
 285   Description              VP8 plugin
 286   Filename                 /usr/lib64/gstreamer-1.0/libgstvpx.so
 287   Version                  1.6.4
 288   License                  LGPL
 289   Source module            gst-plugins-good
 290   Source release date      2016-04-14
 291   Binary package           Fedora GStreamer-plugins-good package
 292   Origin URL               http://download.fedoraproject.org
 293
 294 GObject
 295  +----GInitiallyUnowned
 296        +----GstObject
 297              +----GstElement
 298                    +----GstVideoDecoder
 299                          +----GstVP8Dec
 300
 301 Pad Templates:
 302   SINK template: 'sink'
 303     Availability: Always
 304     Capabilities:
 305       video/x-vp8
 306
 307   SRC template: 'src'
 308     Availability: Always
 309     Capabilities:
 310       video/x-raw
 311                  format: I420
 312                   width: [ 1, 2147483647 ]
 313                  height: [ 1, 2147483647 ]
 314               framerate: [ 0/1, 2147483647/1 ]
 315
 316
 317 Element Flags:
 318   no flags set
 319
 320 Element Implementation:
 321   Has change_state() function: gst_video_decoder_change_state
 322
 323 Element has no clocking capabilities.
 324 Element has no URI handling capabilities.
 325
 326 Pads:
 327   SINK: 'sink'
 328     Pad Template: 'sink'
 329   SRC: 'src'
 330     Pad Template: 'src'
 331
 332 Element Properties:
 333   name                : The name of the object
 334                         flags: readable, writable
 335                         String. Default: "vp8dec0"
 336   parent              : The parent of the object
 337                         flags: readable, writable
 338                         Object of type "GstObject"
 339   post-processing     : Enable post processing
 340                         flags: readable, writable
 341                         Boolean. Default: false
 342   post-processing-flags: Flags to control post processing
 343                         flags: readable, writable
 344                         Flags "GstVP8DecPostProcessingFlags" Default: 0x00000403, "mfqe+demacroblock+deblock"
 345                            (0x00000001): deblock          - Deblock
 346                            (0x00000002): demacroblock     - Demacroblock
 347                            (0x00000004): addnoise         - Add noise
 348                            (0x00000400): mfqe             - Multi-frame quality enhancement
 349   deblocking-level    : Deblocking level
 350                         flags: readable, writable
 351                         Unsigned Integer. Range: 0 - 16 Default: 4
 352   noise-level         : Noise level
 353                         flags: readable, writable
 354                         Unsigned Integer. Range: 0 - 16 Default: 0
 355   threads             : Maximum number of decoding threads
 356                         flags: readable, writable
 357                         Unsigned Integer. Range: 1 - 16 Default: 0
 358 ```
 359
 360 The most relevant sections are:
 361
 362   - Pad Templates: This lists all the kinds of Pads this
 363     element can have, along with their capabilities. This is where you
 364     look to find out if an element can link with another one. In this
 365     case, it has only one sink pad template, accepting only
 366     `video/x-vp8` (encoded video data in VP8 format) and only one source
 367     pad template, producing `video/x-raw` (decoded video data).
 368   - Element Properties: This lists the properties of the
 369     element, along with their type and accepted values.
 370
 371 For more information, you can check the [documentation
 372 page](tools/gst-inspect.md) of `gst-inspect-1.0`.
 373
 374 ## `gst-discoverer-1.0`
 375
 376 This tool is a wrapper around the `GstDiscoverer` object shown in [](tutorials/basic/media-information-gathering.md).
 377 It accepts a URI from the command line and prints all information
 378 regarding the media that GStreamer can extract. It is useful to find out
 379 what container and codecs have been used to produce the media, and
 380 therefore what elements you need to put in a pipeline to play it.
 381
 382 Use `gst-discoverer-1.0 --help` to obtain the list of available options,
 383 which basically control the amount of verbosity of the output.
 384
 385 Let's see an
 386 example:
 387
 388 ```
 389 gst-discoverer-1.0 https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm -v
 390
 391 Analyzing https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm
 392 Done discovering https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm
 393 Topology:
 394   container: video/webm
 395     audio: audio/x-vorbis, channels=(int)2, rate=(int)48000
 396       Codec:
 397         audio/x-vorbis, channels=(int)2, rate=(int)48000
 398       Additional info:
 399         None
 400       Language: en
 401       Channels: 2
 402       Sample rate: 48000
 403       Depth: 0
 404       Bitrate: 80000
 405       Max bitrate: 0
 406       Tags:
 407         taglist, language-code=(string)en, container-format=(string)Matroska, audio-codec=(string)Vorbis, application-name=(string)ffmpeg2theora-0.24, encoder=(string)"Xiph.Org\ libVorbis\ I\ 20090709", encoder-version=(uint)0, nominal-bitrate=(uint)80000, bitrate=(uint)80000;
 408     video: video/x-vp8, width=(int)854, height=(int)480, framerate=(fraction)25/1
 409       Codec:
 410         video/x-vp8, width=(int)854, height=(int)480, framerate=(fraction)25/1
 411       Additional info:
 412         None
 413       Width: 854
 414       Height: 480
 415       Depth: 0
 416       Frame rate: 25/1
 417       Pixel aspect ratio: 1/1
 418       Interlaced: false
 419       Bitrate: 0
 420       Max bitrate: 0
 421       Tags:
 422         taglist, video-codec=(string)"VP8\ video", container-format=(string)Matroska;
 423
 424 Properties:
 425   Duration: 0:00:52.250000000
 426   Seekable: yes
 427   Tags:
 428       video codec: VP8 video
 429       language code: en
 430       container format: Matroska
 431       application name: ffmpeg2theora-0.24
 432       encoder: Xiph.Org libVorbis I 20090709
 433       encoder version: 0
 434       audio codec: Vorbis
 435       nominal bitrate: 80000
 436       bitrate: 80000
 437 ```
 438
 439 ## Conclusion
 440
 441 This tutorial has shown:
 442
 443   - How to build and run GStreamer pipelines from the command line using
 444     the `gst-launch-1.0` tool.
 445   - How to find out what GStreamer elements you have available and their
 446     capabilities, using the `gst-inspect-1.0` tool.
 447   - How to discover the internal structure of media files, using
 448     `gst-discoverer-1.0`.
 449
 450 It has been a pleasure having you here, and see you soon!