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 n4.4, 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:

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


Example Commands

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

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, video composition and ML are included in FFmpeg tutorials.


General FFmpeg Options

Options

Descriptions
-i
Input video URI.
-c:v
Specify the video codec
This option must be set for any video stream processed on an MA35 device.
Valid decode values are h264_ama, hevc_ama, and av1_ama for H.264, HEVC, and AV1, respectively.
Valid encode values are h264_ama, hevc_ama, and av1_ama for H.264, HEVC, and AV1, respectively.
-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.
Valid value is scaler_ama, for ABR scaler.
Consult MA35 Filters for more details on how to use this option.
-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
Specify DMA direction. Valid options are hwdownload and hwupload, 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.

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.

Options

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

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
Valid values for HEVC: 1, 2, 2.1, 3, 3.1, 4, 4.1, 5, 5.1
Valid values for AV1: 2, 2.1, 3, 4, 4.1, 5, 5.1, 5.2, 5.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.
-crf
Constant Rate Factor
Valid values: 0, 1 (default is 0)
(0) disable - default
(1) enable
This option uses -qp for its quality assignment.
Note that this option ignores all other options that may impose restrictions on qp values. These include -min_qp, -max_qp, -b:v and -control_mode.
-qp
Quantization Parameter
Valid values for H.264 and HEVC 0-51
Valid values for AV1 0-255
Default value -1 implies not used.
-bf
Number of B frames
Valid values for H.264, HEVC and type-2 AV1: 0-3
Valid values for type-1 AV1: 0-7
Default auto selection value is -1.
-lookahead_depth
Number of frames to lookahead for qp maps
Valid values: -1 to 50
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 3
(-1) auto
(0) const_qp for Constant QP
(1) cbr for Constant Bitrate
(2) vbr for Variable Bitrate
(3) cvbr for Capped Variable Bitrate
Default value is auto.
-min_qp
Minimum QP value allowed for rate control
Valid values for H264 and HEVC: 0 to 51
Valid values for AV1: 0 to 255
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 for H264 and HEVC: 0 to 51
Valid values for AV1: 0 to 255
Default auto selection value is -1.
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
-vsync
Add a vsync frame
Valid values: 0, 1 (default is 0)
Set this to 0 to prevent extra frames being added.
-latency_logging
Log latency information to syslog
Valid values: enable and disable.
Default value is disable.
-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: medium or slow. (default is medium)
(medium) Full density with medium VQ - default
(slow) High VQ at lower density
Consult the Tuning Video Quality section for more details on how to use this option.
Note that this option has no effects on AV1 -type 1 encoding.
-dynamic_gop
Enable Dynamic GOP
Valid values: -1, 0 or 1.
(-1) auto
(0) disabled
(1) enable
Default value is auto.
-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.

Video Scaling

The AMD AMA Video SDK hardware scaler is leveraged in FFmpeg by using the scaler_ama complex filter and the FFmpeg filter graph syntax. This section describes the options of the scaler_ama complex filter.

scaler_ama

Filter implementing the AMD AMA Video SDK ABR multiscaler. Takes one input and up to 16 output streams. The complete list of options is described below.

Multiscale Filter Options

Options

Description
-outputs
Specify the number of scaler outputs
Valid values are integers between 1 and desired number of outputs.
-out_res
Specify ABR ladder rungs <1>*<16>(WxH | [Format] | [Rate])
List of up to 16 tuples of form (Resolution | Pixel Format | Frame Rate)
Valid values for resolution: 176x144 to 3840x2160 - default 1920x1080
Valid global values for pixel format: nv12, p010le, packed10, rgbp, yuv420p, and yuv420p10le
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.
-log_level
Specify log level
Valid values: 0 to 3 (default 0)
(0) off - default
(1) session detail
(2) command block descriptor
(3) verbose
-perf
Extract performance data
Valid values: 0 and 1 (default 0)
(0) disable - default
(1) enable
-enable_pipeline
Enable pipelining to improve performance
Valid values: 0 and 1 (default 1)
(0) disable
(1) enable - default
Note that enabling this option adds 2 frames worth of latency to the pipeline.

Using the AMD AMA Video SDK Scaler Filter

The filter graph specification for the scaler_ama filter should be constructed in the following way:

  • Add the scaler_ama filter to the graph

  • Set the number of scaler outputs

  • Set the width, height, pixel format and rate settings for each scaler output

  • Define the name each scaler output

  • If the outputs are not to encoded on the device, add -vf filters to the filter graph to copy the frames back to the host and convert them to AV frames.

The following example shows a complete command to decode, scale and encode to 4 different resolutions and 3 different encode formats, where the input is an H.264 file:

ffmpeg -y -hwaccel ama -hwaccel_device /dev/ama_transcoder0 \
-c:v h264_ama -i <INPUT> \
-filter_complex "scaler_ama=outputs=4:out_res=(1920x1080)(1280x720)(720x480)(360x240) [a][b][c][d]" \
-map '[a]' -c:v hevc_ama -b:v 6M -frames 1200 -f rawvideo -y /tmp/hevc_1080p.hevc \
-map '[b]' -c:v av1_ama  -b:v 2M -frames 1200 -f rawvideo -y /tmp/av1_720p.av1 \
-map '[c]' -c:v h264_ama -b:v 1M -frames 1200 -f rawvideo -y /tmp/h264_480p.h264 \
-map '[d]' -c:v av1_ama  -b:v 1M -frames 1200 -f rawvideo -y /tmp/av1_240p.av1

This example can also be found in the FFmpeg introductory tutorials: Transcode With Multiple-Resolution Outputs.


Rebuilding FFmpeg

Obtain the zipped version of SDK's FFmpeg source code, from ma35d_sdk_v1.0_ffmpeg.zip. Unzip this file into ma35_ffmpeg folder. This folder contains the entire source code for the FFmpeg executable, which is a fork of the main FFmpeg GitHub (release 5.1.2) with AMD plugins patches applied. Due to licensing restrictions, the FFmpeg executable included in the Video SDK is enabled with the AMD AMA Video SDK plugins only.

You can rebuild the FFmpeg executable with optional plugins by following the instructions below. Additionally, comprehensive instructions for compiling FFmpeg can be found on the FFmpeg wiki page.

  1. Make sure libhugetlbfs-dev, nasm and yasm are installed on your machine.

  2. Unzip the downloaded zip file:

    unzip ma35d_sdk_v1.0_ffmpeg.zip

and navigate to root folder of the unzipped file.

  1. Execute the following:

    ./configure --disable-alsa --disable-libxcb --disable-libxcb-shm --disable-libxcb-xfixes --disable-libxcb-shape --disable-xlib --disable-libmfx --disable-vaapi --disable-vulkan --prefix=$PWD --disable-stripping --enable-shared --enable-vpe --enable-libxrm --extra-libs="-L/opt/amd/ama/ma35/lib -lvpi -lcommon -lg2dec -lh2enc -lcache -lGAL -lVSC -lArchModelSw  -lNNArchPerf -lxav1sdk -llog_ama /opt/amd/ama/ma35/lib/libxrm.so.1.6.0 -lxrm_interface -lroi_scale -lhugetlbfs -lpthread -lstdc++ -lm -ldl -lrt" --extra-cflags="-I/usr/include -I$PWD -I/opt/amd/ama/ma35/include/xrm_interface/ -I/opt/amd/ama/ma35/include/xrm/" --extra-ldflags="-Wl,-rpath=$PWD/libavutil:$PWD/libavfilter:$PWD/libavcodec:$PWD/libavformat:$PWD/libavdevice:$PWD/libswscale:$PWD/libswresample:$PWD:/opt/amd/ama/ma35/lib/"

If during this operation permission errors are encountered, then execute the following:

chmod 755 configure; find . -name "*.sh" -exec chmod 755 {} \;

  1. Add any other plugins such as libx264 to the above configure line. (See FFmpeg Compilation Guide for details.) A list of configure options is printed by running configure --help.

  2. Type make -j to build FFmpeg. GNU Make 3.81 or later is required.

  3. Type make install to install all binaries and libraries you built.