sdk-basic-tutorial-handy-elements.md

   1 # Basic tutorial 14: Handy elements
   2
   3 ## Goal
   4
   5 This tutorial gives a list of handy GStreamer elements that are worth
   6 knowing. They range from powerful all-in-one elements that allow you to
   7 build complex pipelines easily (like `playbin`), to little helper
   8 elements which are extremely useful when debugging.
   9
  10 For simplicity, the following examples are given using the
  11 `gst-launch-1.0` tool (Learn about it in
  12 [](sdk-basic-tutorial-gstreamer-tools.md)). Use the `-v` command line
  13 parameter if you want to see the Pad Caps that are being negotiated.
  14
  15 ## Bins
  16
  17 These are Bin elements which you treat as a single element and they take
  18 care of instantiating all the necessary internal pipeline to accomplish
  19 their task.
  20
  21 ### `playbin`
  22
  23 This element has been extensively used throughout the tutorials. It
  24 manages all aspects of media playback, from source to display, passing
  25 through demuxing and decoding. It is so flexible and has so many options
  26 that a whole set of tutorials are devoted to it. See the [](sdk-playback-tutorials.md) for more details.
  27
  28 ### `uridecodebin`
  29
  30 This element decodes data from a URI into raw media. It selects a source
  31 element that can handle the given URI scheme and connects it to
  32 a `decodebin` element. It acts like a demuxer, so it offers as many
  33 source pads as streams are found in the
  34 media.
  35
  36 ``` bash
  37 gst-launch-1.0 uridecodebin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! videoconvert ! autovideosink
  38 ```
  39
  40 ``` bash
  41 gst-launch-1.0 uridecodebin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! audioconvert ! autoaudiosink
  42 ```
  43
  44 ### `decodebin`
  45
  46 This element automatically constructs a decoding pipeline using
  47 available decoders and demuxers via auto-plugging until raw media is
  48 obtained.  It is used internally by `uridecodebin` which is often more
  49 convenient to use, as it creates a suitable source element as well. It
  50 replaces the old `decodebin` element. It acts like a demuxer, so it
  51 offers as many source pads as streams are found in the
  52 media.
  53
  54 ``` bash
  55 gst-launch-1.0 souphttpsrc location=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! decodebin ! autovideosink
  56 ```
  57
  58 ## File input/output
  59
  60 ### `filesrc`
  61
  62 This element reads a local file and produces media with `ANY` Caps. If
  63 you want to obtain the correct Caps for the media, explore the stream by
  64 using a `typefind` element or by setting the `typefind` property
  65 of `filesrc` to
  66 `TRUE`.
  67
  68 ``` c
  69 gst-launch-1.0 filesrc location=f:\\media\\sintel\\sintel_trailer-480p.webm ! decodebin ! autovideosink
  70 ```
  71
  72 ### `filesink`
  73
  74 This element writes to a file all the media it receives. Use the
  75 `location` property to specify the file
  76 name.
  77
  78 ```
  79 gst-launch-1.0 audiotestsrc ! vorbisenc ! oggmux ! filesink location=test.ogg
  80 ```
  81
  82 ## Network
  83
  84 ### `souphttpsrc`
  85
  86 This element receives data as a client over the network via HTTP using
  87 the [libsoup](https://wiki.gnome.org/Projects/libsoup) library. Set the URL to retrieve through the `location`
  88 property.
  89
  90 ``` bash
  91 gst-launch-1.0 souphttpsrc location=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! decodebin ! autovideosink
  92 ```
  93
  94 ## Test media generation
  95
  96 These elements are very useful to check if other parts of the pipeline
  97 are working, by replacing the source by one of these test sources which
  98 are “guaranteed” to work.
  99
 100 ### `videotestsrc`
 101
 102 This element produces a video pattern (selectable among many different
 103 options with the `pattern` property). Use it to test video pipelines.
 104
 105 ``` bash
 106 gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink
 107 ```
 108
 109 ### `audiotestsrc`
 110
 111 This element produces an audio wave (selectable among many different
 112 options with the `wave` property). Use it to test video pipelines.
 113
 114 ``` bash
 115 gst-launch-1.0 audiotestsrc ! audioconvert ! autoaudiosink
 116 ```
 117
 118 ## Video adapters
 119
 120 ### `videoconvert`
 121
 122 This element converts from one color space (e.g. RGB) to another one
 123 (e.g. YUV). It can also convert between different YUV formats (e.g.
 124 I420, NV12, YUY2 …) or RGB format arrangements (e.g. RGBA, ARGB, BGRA…).
 125
 126 This is normally your first choice when solving negotiation problems.
 127 When not needed, because its upstream and downstream elements can
 128 already understand each other, it acts in pass-through mode having
 129 minimal impact on the performance.
 130
 131 As a rule of thumb, always use `videoconvert` whenever you use
 132 elements whose Caps are unknown at design time, like `autovideosink`, or
 133 that can vary depending on external factors, like decoding a
 134 user-provided file.
 135
 136 ``` bash
 137 gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink
 138 ```
 139
 140 ### `videorate`
 141
 142 This element takes an incoming stream of time-stamped video frames and
 143 produces a stream that matches the source pad's frame rate. The
 144 correction is performed by dropping and duplicating frames, no fancy
 145 algorithm is used to interpolate frames.
 146
 147 This is useful to allow elements requiring different frame rates to
 148 link. As with the other adapters, if it is not needed (because there is
 149 a frame rate on which both Pads can agree), it acts in pass-through mode
 150 and does not impact performance.
 151
 152 It is therefore a good idea to always use it whenever the actual frame
 153 rate is unknown at design time, just in
 154 case.
 155
 156 ``` c
 157 gst-launch-1.0 videotestsrc ! video/x-raw,framerate=30/1 ! videorate ! video/x-raw,framerate=1/1 ! videoconvert ! autovideosink
 158 ```
 159
 160 ### `videoscale`
 161
 162 This element resizes video frames. By default the element tries to
 163 negotiate to the same size on the source and sink Pads so that no
 164 scaling is needed. It is therefore safe to insert this element in a
 165 pipeline to get more robust behavior without any cost if no scaling is
 166 needed.
 167
 168 This element supports a wide range of color spaces including various YUV
 169 and RGB formats and is therefore generally able to operate anywhere in a
 170 pipeline.
 171
 172 If the video is to be output to a window whose size is controlled by the
 173 user, it is a good idea to use a `videoscale` element, since not all
 174 video sinks are capable of performing scaling
 175 operations.
 176
 177 ``` bash
 178 gst-launch-1.0 uridecodebin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! videoscale ! video/x-raw,width=178,height=100 ! videoconvert ! autovideosink
 179 ```
 180
 181 ## Audio adapters
 182
 183 ### `audioconvert`
 184
 185 This element converts raw audio buffers between various possible
 186 formats. It supports integer to float conversion, width/depth
 187 conversion, signedness and endianness conversion and channel
 188 transformations.
 189
 190 Like `videoconvert` does for video, you use this to solve
 191 negotiation problems with audio, and it is generally safe to use it
 192 liberally, since this element does nothing if it is not needed.
 193
 194 ``` bash
 195 gst-launch-1.0 audiotestsrc ! audioconvert ! autoaudiosink
 196 ```
 197
 198 ### `audioresample`
 199
 200 This element resamples raw audio buffers to different sampling rates
 201 using a configurable windowing function to enhance quality
 202
 203 Again, use it to solve negotiation problems regarding sampling rates and
 204 do not fear to use it
 205 generously.
 206
 207 ``` bash
 208 gst-launch-1.0 uridecodebin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm ! audioresample ! audio/x-raw-float,rate=4000 ! audioconvert ! autoaudiosink
 209 ```
 210
 211 ### `audiorate`
 212
 213 This element takes an incoming stream of time-stamped raw audio frames
 214 and produces a perfect stream by inserting or dropping samples as
 215 needed. It does not allow the sample rate to be changed
 216 as `videorate` does, it just fills gaps and removes overlapped samples
 217 so the output stream is continuous and “clean”.
 218
 219 It is useful in situations where the timestamps are going to be lost
 220 (when storing into certain file formats, for example) and the receiver
 221 will require all samples to be present. It is cumbersome to exemplify
 222 this, so no example is given.
 223
 224 ![Warning](images/icons/emoticons/warning.png)
 225 Most of the time, `audiorate` is not what you want.
 226
 227 ## Multithreading
 228
 229 ### `queue`
 230
 231 Queues have been explained in [](sdk-basic-tutorial-multithreading-and-pad-availability.md). Basically, a queue performs two tasks:
 232
 233   - Data is queued until a selected limit is reached. Any attempt to
 234     push more buffers into the queue blocks the pushing thread until
 235     more space becomes available.
 236   - The queue creates a new thread on the source Pad to decouple the
 237     processing on sink and source Pads.
 238
 239 Additionally, `queue` triggers signals when it is about to become empty
 240 or full (according to some configurable thresholds), and can be
 241 instructed to drop buffers instead of blocking when it is full.
 242
 243 As a rule of thumb, prefer the simpler `queue` element
 244 over `queue2` whenever network buffering is not a concern to you.
 245 See [](sdk-basic-tutorial-multithreading-and-pad-availability.md)
 246 for an example.
 247
 248 ### `queue2`
 249
 250 This element is not an evolution of `queue`. It has the same design
 251 goals but follows a different implementation approach, which results in
 252 different features. Unfortunately, it is often not easy to tell which
 253 queue is the best choice.
 254
 255 `queue2` performs the two tasks listed above for `queue`, and,
 256 additionally, is able to store the received data (or part of it) on a
 257 disk file, for later retrieval. It also replaces the signals with the
 258 more general and convenient buffering messages described in
 259 [](sdk-basic-tutorial-streaming.md).
 260
 261 As a rule of thumb, prefer `queue2` over `queue` whenever network
 262 buffering is a concern to you. See [](sdk-basic-tutorial-streaming.md)
 263 for an example (`queue2` is hidden inside `playbin`).
 264
 265 ### `multiqueue`
 266
 267 This element provides queues for multiple streams simultaneously, and
 268 eases their management, by allowing some queues to grow if no data is
 269 being received on other streams, or by allowing some queues to drop data
 270 if they are not connected to anything (instead of returning an error, as
 271 a simpler queue would do). Additionally, it synchronizes the different
 272 streams, ensuring that none of them goes too far ahead of the others.
 273
 274 This is an advanced element. It is found inside `decodebin`, but you
 275 will rarely need to instantiate it yourself in a normal playback
 276 application.
 277
 278 ### `tee`
 279
 280 [](sdk-basic-tutorial-multithreading-and-pad-availability.md) already
 281 showed how to use a `tee` element, which splits data to multiple pads.
 282 Splitting the data flow is useful, for example, when capturing a video
 283 where the video is shown on the screen and also encoded and written to a
 284 file. Another example is playing music and hooking up a visualization
 285 module.
 286
 287 One needs to use separate `queue` elements in each branch to provide
 288 separate threads for each branch. Otherwise a blocked dataflow in one
 289 branch would stall the other
 290 branches.
 291
 292 ```
 293 gst-launch-1.0 audiotestsrc ! tee name=t ! queue ! audioconvert ! autoaudiosink t. ! queue ! wavescope ! videoconvert ! autovideosink
 294 ```
 295
 296 ## Capabilities
 297
 298 ### `capsfilter`
 299 [](sdk-basic-tutorial-gstreamer-tools.md) already
 300 explained how to use Caps filters with `gst-launch-1.0`. When building a
 301 pipeline programmatically, Caps filters are implemented with
 302 the `capsfilter` element. This element does not modify data as such,
 303 but enforces limitations on the data format.
 304
 305 ``` bash
 306 gst-launch-1.0 videotestsrc ! video/x-raw, format=GRAY8 ! videoconvert ! autovideosink
 307 ```
 308
 309 ### `typefind`
 310
 311 This element determines the type of media a stream contains. It applies
 312 typefind functions in the order of their rank. Once the type has been
 313 detected it sets its source Pad Caps to the found media type and emits
 314 the `have-type` signal.
 315
 316 It is instantiated internally by `decodebin`, and you can use it too to
 317 find the media type, although you can normally use the
 318 `GstDiscoverer` which provides more information (as seen in
 319 [](sdk-basic-tutorial-media-information-gathering.md)).
 320
 321 ## Debugging
 322
 323 ### `fakesink`
 324
 325 This sink element simply swallows any data fed to it. It is useful when
 326 debugging, to replace your normal sinks and rule them out of the
 327 equation. It can be very verbose when combined with the `-v` switch
 328 of `gst-launch-1.0`, so use the `silent` property to remove any unwanted
 329 noise.
 330
 331 ```
 332 gst-launch-1.0 audiotestsrc num-buffers=1000 ! fakesink sync=false
 333 ```
 334
 335 ### `identity`
 336
 337 This is a dummy element that passes incoming data through unmodified. It
 338 has several useful diagnostic functions, such as offset and timestamp
 339 checking, or buffer dropping. Read its documentation to learn all the
 340 things this seemingly harmless element can
 341 do.
 342
 343 ```
 344 gst-launch-1.0 audiotestsrc ! identity drop-probability=0.1 ! audioconvert ! autoaudiosink
 345 ```
 346
 347 ## Conclusion
 348
 349 This tutorial has listed a few elements which are worth knowing, due to
 350 their usefulness in the day-to-day work with GStreamer. Some are
 351 valuable for production pipelines, whereas others are only needed for
 352 debugging purposes.
 353
 354 It has been a pleasure having you here, and see you soon!