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