Difference between revisions of "Gstreamer cheat sheet"

Warning: Parameter 1 to Cite::clearState() expected to be a reference, value given in /storage/content/85/1005285/wiki.oz9aec.net/public_html/includes/Hooks.php on line 204 From MyLabWiki
Jump to: navigation, search
m (Encoding and Muxing)
(Encoding and Muxing)
Line 96: Line 96:
=== Multiple Streams ===
=== Multiple Streams ===
=== Adding Audio ===

Revision as of 18:23, 20 June 2010

This page contains various shortcuts to achieving specific functionality using Gstreamer. These functionalities are mostly related to my Digital Video Transmission experiments. There is no easy to read "user manual" for gstreamer but the online the plugin documentation[1] often contains command line examples in addition to the API docs. Other sources of documentation:

  • The manual page for gst-launch
  • The gst-inspect tool
  • Online tutorials

The Gstreamer documentation is also available in Devhelp.

Video Test Source

To generate a test video stream use videotestsrc[2]:

 gst-launch videotestsrc ! ximagesink

Use the pattern property to select a specific pattern:

 gst-launch videotestsrc pattern=snow ! ximagesink

pattern can be both numeric [0,16] and symbolic. Some patterns can be adjusted using additional parameters.

To generate a test pattern of a given size and at a given rate a "caps filter" can be used:

 gst-launch videotestsrc ! video/x-raw-rgb, framerate=25/1, width=640, height=360 ! ximagesink

TODO: I'd like to add more about "caps filter" but I can not find any comprehensive documentation.

Webcam Capture

In its simplest form a v4l2src[3] can be connected directly to a video display sink:

 gst-launch v4l2src ! xvimagesink

This will grab the images at the highest possible resolution, which for my Logitech QuickCam Pro 9000 is 1600x1200. Adding a "caps filter" in between we can select the size and the desired frametrate:

 gst-launch v4l2src ! video/x-raw-yuv,width=320,height=240,framerate=20/1 ! xvimagesink

If the supported framerates are not good use videorate[4] to either insert or drop frames. This can also be used to deliver a fixed framerate in case the framerate from the camera varies.

The "caps filter" is also used to select a specific pixel format. The Logitech QuickCam Pro 9000 supports MJPG, YUYV, RGB3, BGR3, YU12 and YV12. The pixel format in the "caps filter" can be specified using fourcc[5] labels:

 gst-launch v4l2src ! video/x-raw-yuv,format=\(fourcc\)YUY2,width=320,height=240 ! xvimagesink

YUY2 is the standard YUYV 4:2:2 pixel format and corresponds to the YUYV format on the Logitech QuickCam Pro 9000.

Resizing and Cropping


For quick cropping from 4:3 to 16:9, the aspectratiocrop[6] plugin can be used:

 gst-launch v4l2src ! video/x-raw-yuv,width=640,height=480,framerate=15/1 ! aspectratiocrop aspect-ratio=16/9 ! ffmpegcolorspace ! xvimagesink







Encoding and Muxing

Single Stream

Test Pattern

Encode video to H.264 using x264 and put it into MPEG-TS transport stream:

 gst-launch -e videotestsrc ! video/x-raw-yuv, framerate=25/1, width=640, height=360 ! x264enc ! flutsmux ! filesink location=test.ts

Note that it requires the Fluendo TS Muxer gst-fluendo-mpegmux for muxing and gst-fluendo-mpegdemux for demuxing. The -e option forces EOS on sources before shutting the pipeline down. This is useful when we write to files and want to shut down by killing gst-launch using CTRL+C or with the kill command[7].

We can use the playbin plugin to play the recorded video:

 gst-launch -v playbin uri=file:///path/to/test.ts

The -v option allows us to see which blocks gstreamer decides to use. In this case it will automatically select flutsdemux for demuxing the MPEG-TS and ffdec_h264 for decoding the H.264 video. Note that there appears to be no x264dec and no ffenc_h264.

By default x264enc will use 2048 kbps but this can be set to a different value:

gst-launch -e videotestsrc ! video/x-raw-yuv, framerate=20/1, width=640, height=480 ! x264enc bitrate=512 ! flutsmux ! filesink location=test.ts

bitrate is specified in kbps. Note that I've changed the size to 640x480. For H.264 (and most other modern codecs) it is advantageous to use width and height that is an integer multiple of 16. There are also many other options that can be used to optimize compression, quality and speed.

TODO: Find good settings for (1) high quality (2) fast compression (3) etc...

TODO: There is also the ffmux_mpegts but I can not make it work; it generates a 564 bytes long file.


If we want to encode the webcam we need to include the ffmpegcolorspace[8] converter block:

 gst-launch -e v4l2src ! video/x-raw-yuv, framerate=10/1, width=320, height=240 ! ffmpegcolorspace ! \
               x264enc bitrate=256 ! flutsmux ! filesink location=webcam.ts

Multiple Streams


Adding Audio


Decoding and Demuxing


Network Streaming


MPEG-TS can be streamed over UDP (TBC)

Raw videos, e.g. H.264, can be packed into RTP before sending over UDP (TBC)

 From man gst-launch:
 Network streaming
      Stream video using RTP and network elements.
      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= port=5000 sync=false
      Use this command on the receiver
      gst-launch  udpsrc  port=5000 ! application/x-rtp, clock-rate=90000,payload=96 ! rtph263pdepay queue-delay=0 !
      ffdec_h263 ! xvimagesink
      This command would be run on the transmitter


Picture in Picture



four videos combined into one video matrix

Text Overlay

The texoverlay[10] plugin can be used to add text to the video stream:

 gst-launch videotestsrc ! video/x-raw-yuv,width=640,height=480,framerate=15/1 ! textoverlay text="Hello" ! ffmpegcolorspace ! ximagesink

It has many options for text positioning and alignment. User can also specify font properties as a Pango font description string, e.g. "Sans Italic 24".

TODO: A few font description examples.

Time Overlay

Elapsed time can be added using the timeoverlay[11] plugin:

 gst-launch videotestsrc ! timeoverlay ! xvimagesink

Timeoverlay inherits the properties of textoverlay so the text properties can be set using the same properties:

 gst-launch videotestsrc ! timeoverlay halign=right valign=bottom text="Stream time:" shaded-background=true ! xvimagesink

Alternatively, cairotimeoverlay[12] can be used but it doesn't seem to have any properties:

 gst-launch videotestsrc ! cairotimeoverlay ! xvimagesink

Instead of elapsed time, the system date and time can be added using the clockoverlay[13] plugin:

 gst-launch videotestsrc ! clockoverlay ! xvimagesink

Clockloverlay also inherits the properties of textoverlay. In addition to that clockoverlay also allows setting the time format:

 gst-launch videotestsrc ! clockoverlay halign=right valign=bottom shaded-background=true time-format="%Y.%m.%D" ! ffmpegcolorspace ! ximagesink

Complete Examples



  1. Gstreamer documentation http://gstreamer.freedesktop.org/documentation/
  2. GStreamer Base Plugins 0.10 Plugins Reference Manual – videotestsrc
  3. GStreamer Good Plugins 0.10 Plugins Reference Manual – v4l2src
  4. GStreamer Base Plugins 0.10 Plugins Reference Manual – videorate
  5. FOURCC websiteYUV formats
  6. GStreamer Good Plugins 0.10 Plugins Reference Manual – aspectratiocrop
  7. Elphel Development Blog – Interfacing Elphel cameras with GStreamer, OpenCV, OpenGL/GLSL and python.
  8. GStreamer Base Plugins 0.10 Plugins Reference Manual – ffmpegcolorspace. The details are available via gst-inspect ffmpegcolorspace.
  9. GStreamer Good Plugins 0.10 Plugins Reference Manual – videomixer
  10. GStreamer Base Plugins 0.10 Plugins Reference Manual – textoverlay
  11. GStreamer Base Plugins 0.10 Plugins Reference Manual – timeoverlay
  12. GStreamer Good Plugins 0.10 Plugins Reference Manual – cairotimeoverlay
  13. GStreamer Base Plugins 0.10 Plugins Reference Manual - clockoverlay