Attention

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

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 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 (VBV) Buffer Size
Valid values: -1, 400M [bits] (default is -1)
(-1) For auto selection
This option is ignored unless:
1) lookahead_depth is 0 (ULL)
2) control_rate is CBR
3) Encoder is set to one of h264_ama, hevc_ama or av1_ama Type 2
Value 0 implies strict ULL, whereas, larger values imply relaxed ULL. See Latency Adjustment.
-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, -max_bitrate 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. Note that if this option is used, it implies Constant QP for -control_rate option.
-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 4
(-1) auto
(0) const_qp for Constant QP
(1) cbr for Constant Bitrate
(2) vbr for Variable Bitrate
(3) cvbr for Capped Variable Bitrate
(4) cabr for content adaptive bit-rate
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: 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. Applicable to 10 bit contents only.
Consult the Tuning Video Quality section for more details on how to use this option.
-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.
-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, in ULL mode
-latency_ms
Look Ahead Depth in Milliseconds
Valid values: 0 to 60000
Default auto selection value, based on frame rate, is -1.
-expert_option
Disable Low Latency B Frames (AVC only)
Valid value: bll=false
bll=false argument ensures that the generated GOP has a homogeneous structure. See GOP Composition.

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|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.
Valid global values for pixel format: nv12, p010le, packed10, rgbp, yuv420p, and yuv420p10le
-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

Section under construction.