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¶
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
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