Attention

This version of the SDK has been superseded by the latest release of the SDK.

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.

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' !  ama_download ! filesink location=/tmp/h264.nv12

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.

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 ! 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.