GStreamer Introductory Tutorials

This page provides tutorials on how to use GStreamer with the AMD AMA Video SDK. The complete reference guide for the GStreamer version included in the AMD AMA Video SDK can be found here.

Device Selection

As noted in Video Codec Unit section, each card is made of 2 devices, and by default all processing tasks are delegated to the first device in the systems. (See mautil to find out how many devices are available, in a runtime environment.) To override this behavior, default and non-default devices must be set, explicitly. See Working with Multiple Devices for more explanation, and Multidevice Transcode for sample usage.

Environment Setup

  1. The AMD AMA Video SDK version of FFmpeg, Gstreamer and XMA applications can be found in the /opt/amd/ama/ma35/bin folder of your system. If this folder is not present, install the required packages:

    See On Premises

  2. Configure the environment to use the AMD AMA Video SDK. This a mandatory step for all applications:

    source /opt/amd/ama/ma35/scripts/setup.sh

The setup script exports important environment variables and ensures proper execution environment for AMD AMA Video SDK.

Sourcing the setup script should be performed each time you open a new terminal on your system. This is required for the environment to be correctly configured.

Simple GStreamer Examples

By default, all the example scripts use the filesink plug-in and write the output files into the /tmp directory.

Some of the examples read or write RAW files from disk (encode-only or decode-only pipelines). There is a chance that due to the massive bandwidth required for operating on these RAW files, you will notice a drop in FPS; this is not due to the AMD AMA Video SDK but the disk speeds. We recommend reading/writing from /dev/shm which is a RAM disk.

Most of the scripts allow to use the fakesink plug-in which only displays performance numbers and will not write outputs to disk. This is done by setting the “fakesink” argument to 1.

Each script contains error checks before passing arguments to GStreamer pipeline command to help users avoid giving incorrect arguments.

Most of the example scripts included in this directory take H.264 input streams. To use H.265 input streams, update the scripts to use the h265parse GStreamer plug-in instead of h264parse.

For brevity purposes, explanations of the GStreamer element properties are not repeated after they have been explained once. The detailed explanation of the each GStreamer pipeline element property can be obtained by using gst-inspect-1.0 <element name> (e.g. gst-inspect-1.0 ama_av1enc).

Decode only

Command Line:

gst-launch-1.0 filesrc location=<INPUT> ! parsebin ! h264parse ! ama_h264dec ! capsfilter 'caps=video/x-raw(memory:AMAMemory),format=NV12,width=<WIDTH>,height=<HEIGHT>' !  ama_download ! filesink location=<OUTPUT>

Explanation of the pipeline elements and their properties:

  • gst-launch-1.0

    • The GStreamer application, which is provided by AMD, and moved to the top of the PATH when you sourced the setup.sh script

  • filesrc location

    • Location of the file h.264 to read

  • parsebin

    • Unpacks the container to elementary stream

  • h264parse

    • Parses H.264 streams

  • ama_h264dec

    • GStreamer plug-in that provides functionality to decode H.264 encoded streams. This plug-in accepts input encoded stream in byte-stream/NALU format only and produces NV12 frames.

  • capsfilter

    • Specifies the capabilities of the streams. Note that keyword capsfilter is optional.

In the above cli, <WIDTH> and <HEIGHT> are optional parameters that describe the desired resolution of the decoded stream. It should be noted that resizing is done on the decoder and as such does not impose any cost on the host CPU or the accelerated scaler Scaler Plugin.

Downscaling in decoder

Command Line:

gst-launch-1.0 filesrc location=<INPUT> ! parsebin ! h264parse ! ama_h264dec allow-downscaling=true ! capsfilter 'caps=video/x-raw(memory:AMAMemory),format=NV12,width=<WIDTH>,height=<HEIGHT>' !  ama_download ! filesink location=<OUTPUT>

Explanation of the pipeline elements and their properties:

  • allow-downscaling

    • Option to inform the downstream capfilter that downscaling will be performed though decoder.

Encode only

Command Line:

gst-launch-1.0 filesrc location=<INPUT> ! rawvideoparse width=1920 height=1080 format=i420 framerate=60/1 ! ama_upload ! ama_h264enc bitrate=6000000 ! h264parse ! filesink location=/tmp/out.h264

Explanation of the pipeline elements and their properties:

  • ama_h264enc

    • GStreamer plug-in that provides functionality to encode raw bit streams into AVC byte-stream.

  • rawvideoparse

    • This element converts unformatted data streams into timestamped raw video frames, with specified resolution, frame rate and pixel format.

  • ama_upload

    • This plugin transfer raw video file content from host to the device

Transcode with Multiple-Resolution outputs

Command Line:

gst-launch-1.0 filesrc location=<INPUT> ! parsebin ! \
h264parse ! ama_h264dec ! identity eos-after=1200 ! ama_scaler name=s \
s.src_0 ! 'video/x-raw(memory:AMAMemory),width=1920,height=1080' ! ama_h265enc bitrate=6000000 ! queue ! filesink location=/tmp/hevc_1080p.hevc \
s.src_1 ! 'video/x-raw(memory:AMAMemory),width=1280,height=720' ! ama_av1enc bitrate=2000000 ! queue ! filesink location=/tmp/av1_720p.av1 \
s.src_2 ! 'video/x-raw(memory:AMAMemory),width=720,height=480' ! ama_h264enc bitrate=1000000 ! queue ! filesink location=/tmp/h264_480p.h264 \
s.src_3 ! 'video/x-raw(memory:AMAMemory),width=360,height=240' ! ama_av1enc bitrate=1000000 ! queue ! filesink location=/tmp/av1_240p.av1

Explanation of the pipeline elements and their properties:

  • queue

    • The queue will create a new thread on the source pad to decouple the processing on sink and source pad.

  • identity

    • In this usage, forces the insertion of EOS after 1200 buffers.

For more comprehensive sets of examples refer to /opt/amd/ama/ma35/examples/gstreamer/ama_pipeline_scripts/tutorials folder.

Multidevice Transcode

This example demonstrates AMA SDK's DMA plugins capabilities to execute any of transcode operations, on a given device.

Command Line:

gst-launch-1.0 filesrc location=<INPUT> ! qtdemux ! h264parse ! ama_h264dec device=X ! "video/x-raw(memory:AMAMemory),format=I420" ! ama_download ! ama_upload device=Y ! ama_h264enc  bitrate=6000000 ! h264parse ! mp4mux ! filesink location=<OUTPUT>

, where X and Y are device indices for decode and encode operations, respectively.

2D Filters

This following examples demonstrate AMA SDK's 2D plugins capabilities.

Subsampling:

gst-launch-1.0 -v \
  filesrc location=<4:2:2 YUV> ! rawvideoparse format=uyvy width=1920 height=1080 framerate=30/1 \
    ! ama_upload ! ama_videoconvert ! ama_download ! video/x-raw,format=I420 ! filesink location=<4:2:0 YUV>

Color space conversion:

gst-launch-1.0 -v \
 filesrc location=<4:2:0 YUV> ! rawvideoparse format=i420 width=1920 height=1080 framerate=24/1 \
 ! ama_upload ! ama_videoconvert ! ama_download ! video/x-raw,format=BGRA ! filesink location=<RGB>

Rotate:

gst-launch-1.0 -v videotestsrc num-buffers=300 ! video/x-raw,format=I420 ! ama_upload ! ama_rotate angle=rotate-90 !  ama_h264enc bitrate=1000000 ! filesink location=rotate.h264

Padding:

gst-launch-1.0 -v filesrc location=<4:2:0 YUV> ! rawvideoparse format=i420 width=1920 height=1080 framerate=24/1 ! \
 ama_upload ! ama_videopad top=150 right=30 left=30 bottom=10 color=0x00FFAA00 ! ama_h264enc bitrate=1000000 ! filesink location=pad.h264

Crop:

gst-launch-1.0 -v filesrc location=<4:2:0 YUV> ! rawvideoparse format=i420 width=1920 height=1080 framerate=24/1 ! \
 ama_upload ! ama_videocrop top=150 right=30 left=30 bottom=10 ! ama_h264enc bitrate=1000000 ! filesink location=pad.h264

Blend:

gst-launch-1.0 -v ama_blend name=b ! ama_videoconvert ! "video/x-raw(memory:AMAMemory),format=I420, framerate=30/1 " ! ama_h264enc bitrate=1000000 ! h264parse ! mp4mux ! filesink location=blend.mp4 \
filesrc location=<BGRA Foreground> ! rawvideoparse width=384 height=240 framerate=30/1 format=bgra ! ama_upload ! ama_videoconvert ! b.foreground \
filesrc location=<BGRA Mask> ! rawvideoparse width=384 height=240 framerate=30/1 format=bgra ! ama_upload ! ama_videoconvert ! b.mask \
filesrc location=<BGRA Background> ! rawvideoparse width=384 height=240 framerate=30/1 format=bgra ! ama_upload ! ama_videoconvert ! b.background

, where all input files are assumed to be of size 384x240, and BGRA format.

Tile:

gst-launch-1.0 -v \
 ama_tile name=tile grid_x=2 grid_y=2 \
 ! 'video/x-raw(memory:AMAMemory)' ! ama_h264enc bitrate=1000000 ! filesink location=tile.h264 \
 filesrc location=<INPUT 1> ! qtdemux ! h264parse ! ama_h264dec ! tile.sink_0 \
 filesrc location=<INPUT 2> ! qtdemux ! h264parse ! ama_h264dec ! tile.sink_1 \
 filesrc location=<INPUT 3> ! qtdemux ! h264parse ! ama_h264dec ! tile.sink_2 \
 filesrc location=<INPUT 4> ! qtdemux ! h264parse ! ama_h264dec ! tile.sink_3

Overlay:

gst-launch-1.0 -v  ama_overlay name=overlay offset-x=50 offset-y=100 !  'video/x-raw(memory:AMAMemory)' ! ama_h264enc bitrate=1000000 ! filesink location=overlay.h264  \
 filesrc location=<Background Video> ! qtdemux ! h264parse ! ama_h264dec ! 'video/x-raw(memory:AMAMemory),format=I420' ! overlay.video \
 videotestsrc pattern=checkers-8 num-buffers=300 ! video/x-raw,format=I420,framerate=60/1 ! ama_upload ! overlay.overlay

Drawbox:

gst-launch-1.0 -v \
 filesrc location=<INPUT> ! qtdemux ! h264parse ! ama_h264dec \
 ! ama_drawbox top=10 left=20 width=200 height=400 thickness=10 color=0x00FFFF00 \
 ! ama_h264enc bitrate=1000000 ! filesink location=drawbox.h264

Composition:

gst-launch-1.0  -v ama_compositor name=comp params-file=./dynamic_params.txt \
 sink_0::width=200 sink_0::height=100 sink_0::xpos=0 sink_0::ypos=0 sink_0::border-inner-width=2 sink_0::border-color=0x00FF0000 \
 sink_1::width=200 sink_1::height=100 sink_1::xpos=0 sink_1::ypos=108 sink_1::border-inner-width=2 sink_1::border-color=0x00FF0000 \
 ! 'video/x-raw(memory:AMAMemory),format=I420' ! ama_h264enc bitrate=5000000 ! h264parse ! mp4mux ! filesink location=comp.mp4 \
 filesrc location=<INPUT 1> ! qtdemux ! h264parse ! ama_h264dec ! comp.sink_0 \
 filesrc location=<INPUT 2> ! qtdemux ! h264parse ! ama_h264dec ! comp.sink_1

, where parameter file contains:

00:00:01.000 compositor_ama 'background=pink';
00:00:03.000 compositor_ama 'background=green:input=1:border_inner_size=4:border_outer_size=2:border_color=blue';
00:00:06.000 compositor_ama 'input=1:border_inner_size=4:border_outer_size=2:border_color=brown:input=0:border_inner_size=10:border_outer_size=10';
00:00:08.000 compositor_ama 'background=0x0000FF00';
00:00:10.000 compositor_ama 'input=1:flip=hv';