XMA Examples for the AMD AMA Video SDK

The examples in the /opt/amd/ama/ma35/bin folder illustrate how C-based applications can natively interact with AMD AMA Video SDK devices using the XMA (Xilinx Media Accelerator) APIs. Source codes for decoder, encoder, scaler and transcoder can be found under /opt/amd/ama/ma35/examples/xma directory.

Detailed documentation on the AMD AMA Video SDK plugin interface and the XMA APIs can be found in the C API Programming Guide section of the documentation.

Requirements

  • The XMA applications has been built for and verified on a supported OS.

  • The XMA applications only work with elementary streams. Container formats such as mp4 are not supported.

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.

XMA Decoder App

Decoder Test Instructions

The XMA decoder application supports most of the decode options supported by FFmpeg. The XMA decoder application supports only elementary H.264, HEVC and AV1 encoded bitstreams.

Decoder Usage

Running the decoder app with the --help option will print the complete list of options:

ma35_decoder_app --help
encoded file and utilizes hardware acceleration to get the decoded
output.

Usage:
        ma35_decoder_app [options] -i <input-file> -c:v <codec-type>
        [codec_options] -o <output-file>

Arguments:
        --help                     Print this message and exit
        -log_level <value>         Specify the log level
        -log_location <value>      Log location. 0 for none,
                                   1 console (default), 2 syslog, 3 file
        -log_file <file>           Name and path of the log file. Default
                                   ma35_decoder_app.log
        -d <device_id>             Specify a device on which to run.
                                   Default: 0

Input Arguments:

        -stream_loop <loop-count>  Number of times to loop the input
                                   file
        -i <input-file>            Input file to be used

Codec Arguments:

        -c:v <codec>               Specify H264 or H265 decoding.
                                   (h264_ama, hevc_ama)
        -latency_logging           Enable latency logging
        -frames <frame-count>      Number of frames to be processed.
        -pix_fmt fmt               The output format (nv12, yuv420p,
                                   yuv420p10le, xv15) Default: nv12 8 bit,
                                   yuv420p10le 10 bit
        -o <file>                  File to which output is written.

Sample Decoder Command

Decode an hevc encoded file into raw N12 format:

ma35_decoder_app -c:v hevc_ama -i <INPUT> -frames 100 -pix_fmt nv12 -o out1.nv12

XMA Encoder App

Encoder Test Instructions

The encoder XMA application supports most of the encoder options supported by FFmpeg. The XMA application supports variety of input pixel formats, see -out_fmt, and can output H.264/HEVC/AV1 encoded elementary stream formats.

Encoder Usage

Running the encoder app with the --help option will print the complete list of options:

ma35_encoder_app --help
XMA Encoder App Usage:
     ./ma35_encoder_app [input options] -i input-file -c:v <codec-option>  [encoder options] -o <output-file>

Arguments:

     --help                     Print this message and exit.
     -log_level <value>         Log level settings, supported are 0 or
                                emergency, 1 or alert, 2 or critical, 3
                                or error, 4 or warning, 5 or notice, 6
                                or info, 7 or debug.
                                Default is 3/error
     -log_location <value>      Log location settings, supported are 0 or
                                none, 1 or console, 2 or syslog, 3
                                or file.
                                Default is 1/console
     -log_file <log-file>       Name and path of log file
                                Default is ma35_encoder_app.log
     -d <device-id>             Specify a device on which the
                                encoder to run.
                                Default is /dev/ama_transcoder0
     -frames <frame-count>      Number of frames to be processed.

Input options:

     -stream_loop <loop-count>  Number of times to loop the input
                                YUV file.
     -w <width>                 Width of YUV input.
     -h <height>                Height of YUV input.
     -pix_fmt <pixel-format>    Pixel format of the input file. It must be yuv420p,

     -i <input-file>            Name and path of input YUV file

Codec option:

     -c:v <codec>               Encoder codec to be used. Supported
                                are h264_ama, hevc_ama, av1_ama
     -device_type               When encoding to AV1, this sets which
                                AV1 encoder will be used. Supported
                                values are 1(Xilinx), 2(Vendor
                                supplied), or any

Encoder params:

     -b:v <bitrate>             Bitrate can be given in Kbps or Mbps
                                or bits i.e., 5000000, 5000K, 5M.
                                Default is 5Mbps
     -fps <fps>                 Input frame rate. Default is 30.
     -g <intraperiod>           Intra period. Default is 15.
     -qp <qp>                   QP. Supported are -1 to 51,
                                default is -1
     -min_qp <qp>               Minimum QP. Supported are 0 to 51,
                                default is 0.
     -max_qp <qp>               Maximum QP. Supported values are 0
                                to 51, default is 51.
     -spat_aq_gain <gain>       Spatial AQ gain. Supported values are
                                0 to 100 or 255, default is 255.
     -temp_aq_gain <gain>       Temporal AQ gain. Supported values are
                                0 to 100 or 255, default is 255.
     -temporal_aq <0/1>         Temporal AQ. Enable/Disable,
                                default is -1.
     -spatial_aq <0/1>          Spatial AQ. Enable/Disable,
                                default is -1.
     -qp_mode <qp>              QP Mode. Supported values 0, 1 and 2
                                default is 0.
     -control_rate <rc_mode>    Rate Control. Supported values -1, 0, 1, 2 and 3
                                default is -1.
     -bf <frames>               Number of B frames. Supported are -1
                                to 3, default is -1.
     -force_idr <0/1            Supported values are 0 and 1
     -preset <value>            Encoder preset. Supported: slow, medium and fast
                                are supported. Default: medium
     -profile <value>           Encoder profile.
                For AV1, supported -1 (auto) and 200 (main). Default: -1 (auto)
                For HEVC, supported -1 (auto), 100 (main), 101 (main10_intra), 102
                                (main10), 103 (main10_intra). Default: -1 (auto)
                For H264, supported -1 (auto), 0 (baseline), 1 (main), 2 (high),
                                3 (high10) 4 (high10_intra). Default: -1 (auto)
     -level <value>             Encoder level.
                For H264, supported are 0 (auto), 10, 11, 12, 13, 20, 21, 22, 30,
                                31, 32, 40, 41, 42, 50, 51, 52, 60, 61, 62. Default:
                                0 (auto)
                For HEVC, supported are 0 (auto), 10, 20, 21, 30, 31, 40, 41, 50,
                                51, 52, 60, 61, 62. Default: 0 (auto)
                For AV1, supported are 0 (auto), 20, 21, 30, 31, 40, 41, 50, 51,
                                52, 53, 60, 61, 62, 63. Default: 0 (auto)
     -tier <value>              HEVC tier, supported are -1 (auto), 0 (main), 1 (high).
                                Default: -1 (auto)
                                Default is -1/auto
     -crf <value>               CRF range: -1 - 63. Default is -1.
     -bufsize <value>           Size of VBV buffer (in bits). Default is -1. Strict
                                ULL = 0, Relaxed ULL > 0
     -dynamic_gop <value>       Dynamic GOP supported values are -1 (auto), 0 (disable)
                                and 1 (enable). Default: -1
     -tune_metrics <value>      Tunes encoder's video quality for objective metrics.
                                Supported values are vq or 1, psnr or 2, ssim or
                                3, vmaf or 4. Default: 1
     -lookahead_depth <value>   Lookahead depth. Supported [-1, 53]. Default: -1
     -latency_ms <value>        Lookahead depth specified in milliseconds. Supported
                                [-1, 60000]. Default: -1
     -no_bll <value>            No low latency b-frames. Supported [-1, 1]. Default:
                                -1
     -latency_logging <0/1>     Enable latency logging
     -expert_options <string>   Expert options
     -o <file>                  File to which output is written.
     -stats <file>              File to which csv statistics output is written.

Sample Encoder Commands

H.265 encoding, ultra low latency (Consult the Tuning Latency of Transcode Pipeline section for more details):

ma35_encoder_app -w 1920 -h 1080 -pix_fmt yuv420p -i <INPUT> -c:v hevc_ama -b:v 5M -lookahead_depth 0 -g 30 -o out0.265

XMA Scaler App

Scaler Test Instructions

The scaler XMA application supports most of the scaler options supported by FFmpeg. The XMA application supports -out_fmt pixel formats.

Scaler Usage

Running the scaler app with the --help option will print the complete list of options:

ma35_scaler_app --help
This program ingests an nv12, yuv420p, yuv420p10le, or xv15 input
file and utilizes hardware acceleration to scale to various resolutions.

Usage:
        ma35_scaler_app [options] -w <input-width> -h <input-height> -i
        <input-file> [scaler_options] -w <output-1-width> -h
        <output-1-height> -o <output-1-file> -w ...

Arguments:
        --help                     Print this message and exit
        -log <level>               Specify the log level
        -log_location <value>      Log location. 0 for none,
                                   1 console (default), 2 syslog, 3 file
        -log_file <file>           Name and path of the log file. Default
                                    ma35_scaler_app.log
        -d <device-id>             Specify a device on which to run.
                                   Default: 0

Input Arguments:

        -stream_loop <loop-count>  Number of times to loop the input
                                   file
        -w <width>                 Specify the input's width
        -h <height>                Specify the input's height
        -pix_fmt <pixel-format>    Pixel format of the input file (nv12,
                                   xv15, yuv420p10le). Default : nv12.
        -fps <frame-rate>          Frame rate. Used for scaler load
                                   calculation.
        -i <input-file>            Input file to be used

Output Arguments:
        -rate <half/full>          Set the rate to half. Half rate drops
                                   frames to reduce resource usage.
                                   Default: full.
        -latency_logging           Enable latency logging
        -w <width>                 Specify the output's width
        -h <height>                Specify the output's height
        -pix_fmt <pixel-format>    Pixel format of the output file (nv12,
                                   xv15, yuv420p10le). Default: input fmt
        -frames <frame-count>      Number of frames to be processed.
        -o <file>                  File to which output is written.

Sample Scaler Command

Scale 1080p nv12 to 720p, 480p, 360p, and 240p nv12:

ma35_scaler_app -pix_fmt nv12 -w 1920 -h 1080 -i <INPUT> \
-w 1280 -h 720  -pix_fmt nv12 -o out1.nv12 \
-w 848  -h 480  -pix_fmt nv12 -o out2.nv12 \
-w 640  -h 360  -pix_fmt nv12 -o out3.nv12 \
-w 288  -h 160  -pix_fmt nv12 -o out4.nv12

XMA Transcoder App

Transcoder Test Instructions

The transcoder XMA application supports most of the options supported by ffmpeg. The XMA application supports only elementary H.264, HEVC and AV1 encoded stream input and outputs H.264/HEVC/AV1 encoded elementary stream.

Transcoder Usage

Running the transcoder app with the --help option will print the complete list of options:

 ma35_transcoder_app --help
 XMA Transcoder App Usage:
        ./program [generic options] -c:v <decoder codec> [decoder options]  -i input-file -scaler_ma -outputs [num] [Scaler options]  -c:v <encoder codec> [encoder options] -o <output-file>  -c:v <encoder codec> [encoder options] -o <output-file>  -c:v <encoder codec> [encoder options] -o <output-file>.....

Arguments:

        --help                     Print this message and exit.
        -d <device-id>             Specify a device on which the
                                   transcoder to run. Default: 0
        -stream_loop <loop-count>  Number of times to loop the input file
        -frames <frame-count>      Number of input frames to be processed

Decoder options:

        -c:v <codec>               Decoder codec to be used. Supported
                                   are hevc_ama, h264_ama
        -latency_logging <0/1>     Latency logging for decoder. Default
                                   disabled
        -push-model <0/1>          Decoder streaming model (pull or push). Default
                                   is pull (can be faster than real-time)
        -i <input-file>            Name and path of input H.264/HEVC file

Scaler options:

        -scaler_ma                 Name of the ABR scaler filter
        -num-output <value>        Number of output files from scaler
        -out_1_width <width>       Width of the scaler output channel 1
        -out_1_height <height>     Height of the scaler output channel 1
        -out_1_rate <full/half>    Full of Half rate for output channel 1
        -out_2_width <width>       Width of the scaler output channel 2
        -out_2_height <height>     Height of the scaler output channel 2
        -out_2_rate <full/half>    Full of Half rate for output channel 2
        -out_3_width <width>       Width of the scaler output channel 3
        -out_3_height <height>     Height of the scaler output channel 3
        -out_3_rate <full/half>    Full of Half rate for output channel 3
        -out_4_width <width>       Width of the scaler output channel 4
        -out_4_height <height>     Height of the scaler output channel 4
        -out_4_rate <full/half>    Full of Half rate for output channel 4
        -out_5_width <width>       Width of the scaler output channel 5
        -out_5_height <height>     Height of the scaler output channel 5
        -out_5_rate <full/half>    Full of Half rate for output channel 5
        -out_6_width <width>       Width of the scaler output channel 6
        -out_6_height <height>     Height of the scaler output channel 6
        -out_6_rate <full/half>    Full of Half rate for output channel 6
        -out_7_width <width>       Width of the scaler output channel 7
        -out_7_height <height>     Height of the scaler output channel 7
        -out_7_rate <full/half>    Full of Half rate for output channel 7
        -out_8_width <width>       Width of the scaler output channel 8
        -out_8_height <height>     Height of the scaler output channel 8
        -out_8_rate <full/half>    Full of Half rate for output channel 8
        -latency_logging <0/1>     Latency logging for scaler. Default
                                   disabled
Encoder options:

        -c:v <codec>               Encoder codec to be used. Supported
                                   are hevc_ama, h264_ama, and av1_ama
        -device_type               When encoding to AV1, this sets which
                                   AV1 encoder will be used. Supported
                                   values are 1(Xilinx), 2(Vendor
                                   supplied), or any
        -b:v <bitrate>             Bitrate can be given in Kbps or Mbps
                                   or bits i.e., 5000000, 5000K, 5M.
                                   Default is 200kbps
        -fps <fps>                 Input frame rate. Default is 30.
        -g <intraperiod>           Intra period. Default is 12.
        -max-bitrate <bitrate>     Maximum bit rate. Supported are -1 to
                                   350000000, default is -1
        -min_qp <qp>               Minimum QP. Supported are 0 to 51,
                                   default is 0.
        -max_qp <qp>               Maximum QP. Supported values are 0
                                   to 51, default is 51.
        -spatial_aq_gain <gain>    Spatial AQ gain. Supported values are
                                   0 to 100 or 255, default is 255.
        -temporal_aq_gain <gain>   Temporal AQ gain. Supported values are
                                   0 to 100 or 255, default is 255.
        -bf <frames>               Number of B frames. Supported are 0
                                   to 7, default is 2.
        -force_idr <0/1            Supported values are 0 and 1
        -profile <value>           Encoder profile.
                   For HEVC, supported are 100 or main, 101 or main10_intra,
                                   102 or main10 , 103 or main10_intra
                                   or still.
                                   Default is 0/automatic
                                   ENC_HEVC_MAIN - 100 or main
                                   ENC_HEVC_MAIN_INTRA - 101 or main_intr
                                   ENC_HEVC_MAIN_10 - 102 or main10
                                   ENC_HEVC_MAIN10_INTRA - 103 or main10_intra             For H264, supported are auto or -1, 0 or baseline,
                                   1 or main, 2 or high, 3 or high10
                                   4 or high10_intra, Default is auto or -1
                                   ENC_H264_BASELINE - 0 or baseline.
                                   ENC_H264_MAIN - 1 or main.
                                   ENC_H264_HIGH - 2 or high.
                                   ENC_H264_HIGH_10 - 3 or high10.
                                   ENC_H264_HIGH_10_INTRA - 4 or high10_intra   -level <value>             Encoder level.
                                   For HEVC, supported are 10 to 52,
                                   default is 50.
                                   For H264, supported are 10 to 52,
                                   default is 50.
        -slices <value>            Number of slices per frame. Supported
                                   are 1 to 68, default is 1.
        -qp_mode <qp>              QP Mode. Supported values 0, 1 and 2
                                   default is 0.
        -control_rate <rc_mode>    Rate Control. Supported values -1 to 3
                                   default is -1.
        -aspect_ratio <value>      Aspect ratio. Supported values are 0
                                   to 3, default is 0.
        -lookahead_depth <value>   Lookahead depth. Supported are 0 to
                                   20, default is 0.
        -temporal_aq <0/1>         Temporal AQ. Enable/Disable,
                                   default is -1.
        -spatial_aq <0/1>          Spatial AQ. Enable/Disable,
                                   default is -1.
        -tune_metrics <value>      Tunes MPSoC H.264/HEVC encoder's video
                                   quality for objective metrics, default 1.
                                   Supported value from 1 to 4
        -tier <value>              HEVC tier, supported are -1 or auto, 0 or main,
                                   1 or high.
                                   Default is -1/auto
        -crf <value>               CRF supported values are 0 and 1 i.e. enable
                                   and disable
                                   Default is -1/auto
        -latency_logging           Enable latency logging
        -latency_mode <value>      0 normal latency (default), 1 low
                                   latency, or 2 ultra low latency      -o <file>                  File to which output is written.

Sample Transcoder Commands

H.264 to AV1 Transcoder:

ma35_transcoder_app -streams 1 -frames 2000 -c:v h264_ama \
-i <INPUT> \
-c:v av1_ama -b:v 10M  -o h264_av1_transcode.av1

H.264 to H264 ABR Transcoder:

ma35_transcoder_app -streams 1 -c:v h264_ama \
-i <INPUT> \
-scaler_ma -num-output 4 \
-out_1_width 1280 -out_1_height 720 -out_2_width 848 -out_2_height 480 \
-out_3_width 640 -out_3_height 360 -out_4_width 288 -out_4_height 160 \
-c:v h264_ama -b:v 4000K -o abr_ladder1.264 \
-c:v h264_ama -b:v 3000K -o abr_ladder2.264 \
-c:v h264_ama -b:v 2500K -o abr_ladder3.264 \
-c:v h264_ama -b:v 1250K -o abr_ladder4.264

H.264 to AV1 ULL Transcode

ma35_transcoder_app -streams 1 -frames 2000 -c:v h264_ama \
-i <INPUT>\
-c:v av1_ama  -b:v 10M -lookahead_depth 0 -o h264_av1_transcode.av1