Using FFmpeg

This page documents how to use FFmpeg with the AMD AMA Video SDK.

Introduction

FFmpeg is an industry standard, open source, widely used utility for handling video. FFmpeg has many capabilities, including encoding and decoding of all video compression formats, encoding and decoding of audio, encapsulating, and extracting audio, and video from transport streams, and many more. The AMD AMA Video SDK includes an enhanced version of FFmpeg, version 7.1, which communicates with the hardware accelerated transcode pipeline.

It is not within the scope of this document to provide an exhaustive guide on the usage of FFmpeg. Various resources can be found online, for example:

• https://www.ffmpeg.org/documentation.html

• http://howto-pages.org/ffmpeg/

The following sections describe the options used with FFmpeg to configure the various hardware accelerators available on an MA35 device.

Example Commands

To obtain the FFmpeg version used in this SDK, issue the following command:

ffmpeg -version

A simple FFmpeg command for accelerated transcoding with the AMD AMA Video SDK will look like the following:

ffmpeg -hwaccel ama -hwaccel_device /dev/ama_transcoder0 -c:v h264_ama -i infile.mp4 -c:v hevc_ama -b:v 1000K -r 60 -f mp4 -y transcoded.mp4

There are many other ways in which FFmpeg can be used to leverage the video transcoding features of an MA35 device. Examples illustrating how to run FFmpeg for encoding, decoding, and transcoding with or without ABR scaling are included in FFmpeg tutorials.

General FFmpeg Options

General FFmpeg Options

Options	Descriptions
-i	Input video URI.
-c:v	Specify video or image codec This option must be set for any input processed on an MA35 device. Valid video decode values are vp9_ama, h264_ama, hevc_ama, and av1_ama for VP9, H.264, HEVC, and AV1, respectively. Valid video encode values are h264_ama, hevc_ama, and av1_ama for H.264, HEVC, and AV1, respectively. Valid image decode value is jpeg_ama for JPEG images. Valid image encode values are jpeg_ama, ljpeg_ama, and av1_ama for JPEG, lossless JPEG and AV1 images. See Image Encoding Options for details.
-s	The frame size (WidthxHeight). For example 1920x1080 or 3840x2160.
-f	The container format.
-r	The frame rate in fps (Hz).
-filter_complex	Used for frame filtering operation.
-hwaccel	Global option used to specify on which MA35 device the FFmpeg job should run. Consult Using Explicit Device IDs for more details on how to use this option. Valid values are positive integers in [0..N-1] range. Default is device 0.
-vf	Used for simple filtering operations, e.g., hwdownload_ama and hwupload_ama, for DMA transfer of data to and from the host, respectively. Note that transaction directions are with respect to the host.

Note

Detailed help for encoder, decoder and scaler is obtained through FFmpeg extended help, e.g. ffmpeg -h encoder=h264_ama, ffmpeg -h decoder=hevc_ama or ffmpeg -h filter=scaler_ama.

Note

Using -stream_loop option along with jpeg_ama, results in the following benign error message:

[ERROR] AMA.VPI.DEC.jpeg_ama@0x5555b71aa980:{492302} Can't find valid pts info

The following conventions are used in the following tables:

1. When parameters can be specified as both numerical and string values, they are noted as:

   (<number>) <string>
   

   Conversely, when this is not the case, options are noted with Roman numerals as:

   <Roman numeral>) <option>
   

2. auto or -1 note that values are selected by the SDK to optimally meet the specified constraints.

Video Decoding

For the complete list of features and capabilities of the AMD AMA Video SDK decoder, refer to Release Notes chapter of the documentation.

The table below describes all the options for the AMD AMA Video SDK decoder.

Video Decoding Options

Options	Descriptions
-resize	Decoder down scaler Valid global values are of the for WidthxHeight. Note that this parameter must be specified before the intended input.
-out_fmt	Decoder output pixel format Valid global values for pixel format: nv12, p010le, packed10, rgbp, yuv420p, and yuv420p10le. Note that an identical pixel format must be specified as value to format option, within -vf. See Decode Only for an example.
-low_latency	Enable/Disable single frame level decode When enabled, the decoding latency of streams not containing any B frames is reduced. This option has no impact on streams that include B frames. Valid values: 0 or 1. (default is 0) (0) disable - default (1) enable

Video Encoding

For the complete list of features and capabilities of the AMD AMA Video SDK encoder, refer to Release Notes chapter of the documentation.

The table below describes all the options for the AMD AMA Video SDK encoder.

Video Encoding Options

Options	Descriptions
-b:v	Specify the video bitrate You can specify this in Mb or Kb. For example -b:v 1M or -b:v 1000K.
-max_bitrate	Maximum bitrate Valid values: 0 to 3.5e+10 You may want to use this to limit encoding bitrate if you have not specified a -b:v bitrate Default value -1 implies unspecified.
-g	GOP size Valid values: 0 to UINT32_MAX Default value is -1, implying 2[s] gop duration, i.e., twice the frame rate
-level	Encoding level restriction Valid values for H.264: 1, 1.1, 1.2, 1.3, 2, 2.1, 2.2, 3, 3.1, 3.2, 4, 4.1, 4.2, 5, 5.1, 5.2 6, 6.1, 6.2 Valid values for HEVC: 1, 2, 2.1, 3, 3.1, 4, 4.1, 5, 5.1,5.2, 6, 6.1, 6.2 Valid values for AV1: 2, 2.1, 3, 4, 4.1, 5, 5.1, 5.2, 5.3 6, 6.1, 6.2, 6.3 Default value is auto.
-profile	Set the encoding profile Valid values for H.264: baseline, main, high Valid values for HEVC: main, main-intra, main-10 and main-10-intra Valid values for AV1: main Default value is auto.
-tier	Set the encoding tier (AV1 and HEVC only) Valid values: -1, 0, 1 (-1) auto (0) main (1) high Default value is auto
-bufsize	Rate control buffer size flag Valid values: 0, or non-zero (default is 1) (0) Disable relaxed ULL (non-zero) Enable relaxed ULL This option is ignored unless: 1) lookahead_depth is 0 (ULL) 2) control_rate is CBR Value 0 implies strict ULL, whereas, other values imply relaxed ULL. See Latency Adjustment.
-crf	Constant Rate Factor Valid values: -1 to 63 (-1) default Note that this option is only compatible with -max_qp and -max_bitrate options.
-qp	Quantization Parameter Valid values 0-63 Default value -1 implies not used. Note that if this option is used, it implies Constant QP for -control_rate option. Also, the encoded stream will have its QP in 0-51 range. Furthermore, this option is not applicable to JPEG.
-bf	Number of B frames Valid values for H.264, HEVC and type-2 AV1: 0-3, with default 3. Valid values for type-1 AV1: 0-7, with default 7 for FPS greater than 30, and 3 otherwise. Default auto selection value is -1.
-lookahead_depth	Number of frames to lookahead for qp maps Valid values: -1 to 47+Maximum number of B frames -bf Lookahead depth of 0 implies ULL mode Default auto selection value, based on frame rate, is -1.
-spatial_aq	Enable spatial AQ Valid values: auto, disable or enable (-1) auto (0) disable (1) enable Default value is auto. When qp_mode is uniform, this parameter is ignored and treated as disable.
-spatial_aq_gain	Scale for spatial AQ gain Valid values: 0 to 255 (255) For auto selection Default value for H264, HEVC and AV1 is 64 Default value for type-1 AV1 is 72
-temporal_aq	Enable temporal AQ Valid values: auto, disable or enable (-1) auto (0) disable (1) enable Default value is auto. When qp_mode is uniform, this parameter is ignored and treated as disable.
-temporal_aq_gain	Scale for temporal AQ gain Valid values: 0 to 255 (255) For auto selection Default value for H264, HEVC and AV1 is 80 Default value for type-1 AV1 is 0
-qp_mode	QP control mode Valid values: auto, relative_load and uniform. (0) auto for best VQ (1) relative_load implying both spatial and temporal AQ (2) uniform meaning no AQ Default value is auto.
-control_rate	Set the rate control mode Valid values: -1 to 6 (-1) auto (0) const_qp for Constant QP (1) cbr for Constant Bit Rate (2) vbr for Variable Bit Rate (3) cvbr for Capped Variable Bit Rate (4) cabr DEPRECATED Content Adaptive Bit Rate (5) crf RESERVED See RC Mode Table for details. Default value is auto.
-cabr	CABR parameters Valid values: i) enable ii) disbale iii) auto - The same as disable iv) vq_offset =x, where x is in -63 - 63 range. If not specified, vq_offset =0. See CABR for details.
-min_qp	Minimum QP value allowed for rate control Valid values 0-63 Default auto selection value is -1. This option has no effect when -control_rate is set to Constant QP (0).
-max_qp	Maximum QP value allowed for rate control Valid values 0-63 Default auto selection value is -1.
-qp_i_offset	QP Offset for I Frames Valid values: -51 to 51 Auto selection mode is -1. Default 0.
-qp_b_offset	QP Offset for B Frames Valid values: -51 to 51 Auto selection mode is -1. Default 0. This option has no effect when -control_rate is set to Constant QP (0).
-forced_idr	Force insertion of IDR frames Valid values: 0, 1 (default is 1) (0) disable (1) enable - default Encodes all the intra frames as IDR
-slice	Select a slice to run an encode job Valid values if xrmd is not used are: 0, 1 (default is 0). If xrmd is active and this option is not set, xrmd will make the slice selection.
-tune_metrics	Enable tuning video quality for the best objective metrics This option optimizes the encoder for the selected tuning metric. See Tuning Video Quality for details. Valid values: 1 to 4 (default is 1) (1) vq - default (2) psnr (3) ssim (4) vmaf
-type	Applicable to AV1 encoders only Valid values: 1 or 2. i) 1 - default ii) 2 Default value is 1. Consult the AV1 Selection section for more details on how to use this option.
-preset	Encoder VQ-Density preset Valid values: fast, medium or slow. (default is medium) (fast) Allows for increase in total throughput from 4kp60 to 4kp75 , when 2 or more channels are used. Does not apply to AV1 -type 1 encoding. Not applicable under ULL setting. Note lower VQ than medium preset is to be expected. (medium) Full density with medium VQ - default (slow) High VQ at lower density. (For AV1 Type 1, improvements are observed in 10 bit contents only.) Note that presets have no impact on AV1 Type 2. Consult the Tuning Video Quality section for more details on how to use this option.
-dynamic_gop	Enable dynamic change in the number of B frames Valid values: -1, 0 or 1. (-1) auto (0) disabled (1) enable Default value auto is enabled. When this option is enabled, the number of B frames is always less or equal to default or user-specified one. See -bf.
-dynamic_params_file	Dynamic configuration file Path to dynamic file location (default is empty) Consult the Dynamic Encoder Parameters section for more details on how to use this option.
-cores	AV1 Type 1 Cores Valid values: 1 or 2 i) 1 - default, with minimum resolution of 176x144 or 144x176, and aggregate rate of 4kp60 ii) 2 - minimum resolution of 720x720, with with aggregate rate of 4kp120
-latency_ms	Look ahead depth in milliseconds Valid values: 0 to 60000 Default auto selection value, based on frame rate, is -1.
-no_bll	Disable low latency B frames Valid value: 1 Value 1 ensures that the generated GOP has a homogeneous structure. See GOP Composition.
-encode_mdcv_metadata	Mastering Display Color Volume SEI Valid value: disable, enable, auto, or custom values in G(x,y)B(x,y)R(x,y)WP(x,y)L(max,min) format (default is auto=enable) In custom format: G(x,y) is the green channel of the mastering display B(x,y) is the blue channel of the mastering display R(x,y) is the red channel of the mastering display WP(x,y) is the white point of the mastering display L(max,min) is the light level of the mastering display The x and y values are coordinates from 0.0 to 1.0, as specified in CIE 1931 while the min,max values can be floating point values representing candelas per square meter, or nits. For the max,min values, they are generally specified in the range of 0.0 to 1.0, but there are no constraints on the provided values. Invalid values will be clipped accordingly.
-encode_cll_metadata	Content Light Level SEI Valid value: disable, enable, auto, or max_cll,max_fall (default is auto=enable) disable = ignore CLL – omitted from video ES enable = encode CLL in video ES if encoder received CLL SEI message on first frame max_cll,max_fall where both values are integers clipped into a range of 0 to 65535.
-encode_atc_metadata	Alternative Transfer Characteristic SEI Valid value: disable, enable, auto, or a number between 0-255 (default is auto=enable) disable = ignore ATC – omitted from video ES enable = encode ATC in video ES if encoder received ATC SEI message on first frame <number> = ignore ATC received - add an ATC SEI to the video ES with a specific value
-encode_hdr10plus_metadata	HRD10+ T.35 Valid value: disable, enable, or auto (default is auto=enable) disable = ignore HDR10+ T.35s – omitted from video ES enable = encode HDR10+ T.35s in video ES Has no effect if encoder does not receive HDR10+ T.35 messages
-encode_closed_caption_metadata	CC T.35 Valid value: disable, enable, or auto (default is auto=enable) disable = ignore CC T.35s – omitted from video ES enable = encode CC T.35s in video ES

The following table describes relevant parameters that are applicable to each RC mode

RC Mode Options

RC Mode	Allowed Options
const_qp	Constant QP -qp <QP>
cbr	Constant Bit Rate -b:v <Bit Rate> [-bufsize X] (Averaged over span of IDRs)
vbr	Variable Bit Rate -b:v <Bit Rate>
cvbr	Capped Variable Bit Rate -b:v <Bit Rate> followed by any combination of [-min_qp <QP> | -max_qp <QP> | -max_bitrate <max_bitrate>]
crf	Constant Rate Factor -crf <Value> followed by any combination of [-max_qp <QP> | -max_bitrate <max_bitrate>]
auto	Auto Mode -qp <QP> implies const_qp mode. -b:v <Bit Rate> followed by -bufsize <value> implies cbr mode. -b:v <Bit Rate> implies vbr mode. -b:v <Bit Rate> followed by any combination of [-min_qp <QP> | -max_bitrate <max_bitrate>] implies cvbr mode. -crf <Value> followed by any combination of [-max_qp <QP> | -max_bitrate <max_bitrate>] implies crf mode.

The table below describes all the options for the AMD AMA Video SDK encoder that are applicable to images only.

Image Encoding Options

Options	Descriptions
-slice	See -slice
-quality	Specify JPEG encoding quality Valid values: 1 to 100. Larger values indicate higher quality. Default 80.
-still_picture	Specify AV1image format AVIF Valid value: 1

2D Adaptive Bitrate (ABR) Scaler

This section describes the 2D accelerated ABR scaler in AMA SDK. This processing engine is leveraged in FFmpeg by using the FFmpeg filter graph syntax.

2D Accelerator ABR Scaler

Engine Name	Description	Options
scaler_ama	ABR multiscaler Takes one input and generates up to 16 output streams.	outputs specifies the number of scaler outputs. Valid values are integers between 1 and desired number of outputs. out_res specifies ABR ladder rungs <1>*<16>(WxH|Rate|Format). List of up to 16 tuples of form (Resolution|Rate|Pixel Format). Note that no spaces are allowed before or after |. Valid values for resolution: 176x144 to 3840x2160 - default 1920x1080 Valid values for frame rate: half and full - default full, where full refers to the incoming frame rate and half to the half of the incoming frame rate. Note that the first entry in this option must be full rate. Valid global values for pixel format: nv12, p010le, packed10, rgbp, yuv420p, and yuv420p10le This plugin can be combined with other plugins, without any degradation in pixel throughput.

Other AMA Filters

Other AMA Filters

Filter Name	Description	Options
hwupload_ama	AMA device upload Takes the target device number as an argument and upload data to it.	device specifies the device number. Valid values are integers between 0 and available number of devices minus 1.
hwdownload_ama	AMA host download Takes a argument to enable or disable pipelining	pipeline enables pipelining Note that while enabling pipelining increases the throughput; however, it introduces 2 frames worth of latency.

Rebuilding FFmpeg

Follow the steps noted below to rebuild FFmpeg. See /opt/amd/ama/ma35/ffmpeg-src/BUILD_MA35.md for more details.

1. Install SDK's FFmpeg source code, by installing amd-ama-ffmpeg_src for Ubuntu/Debian or amd-ama-FFMPEG_SRC for Rocky/Alma. Source code will be installed under /opt/amd/ama/ma35/ffmpeg-src.

2. Create a build directory and copy files:

   mkdir -p /tmp/ffmpeg_build
   cd /tmp/ffmpeg_build/
   cp -r /opt/amd/ama/ma35/ffmpeg-src .
   

3. Add dependencies as per your distro, e.g.,:

   Ubuntu/Debian:
   sudo apt install libhugetlbfs-dev libfontconfig-dev libsrt-gnutls-dev libsrtp2-dev \
    libgnutls28-dev nasm libzmq3-dev libfribidi-dev libharfbuzz-dev build-essential pkg-config
   
   Rocky/Alma:
   sudo dnf config-manager --set-enabled crb
   sudo dnf install -y epel-release
   sudo dnf groupinstall -y "Development Tools"
   sudo dnf install yasm nasm pkgconfig fontconfig-devel fribidi-devel srt-devel zeromq-devel libuuid-devel
   

4. Configure options, build and install:

   cd /tmp/ffmpeg_build/ffmpeg-src
   ./configure_ma35 --prefix=.
   make -j
   make install
   

Note

Rocky/Alma:

For a successful build under these distros, change line 123 of configure_ma35 to:

EXTRA_LIBS="-lvpi -llog_ama -lxrm -lxrm_interface -lpthread -lm -ldl -lrt"

You can include optional plugins by following the instructions on the FFmpeg wiki page.