Configuration File Parameters
Parameters that specify the length of an array, such as
ExplicitFrameInvervalPatternLength
or
ExplicitFrameInvervalPattern
, do not need to be set or may be set
to 0
. In either case, the application uses the default array size of
1000.
General Configuration Parameters
The following table describes the general configuration parameters:
Parameter | Description |
---|---|
InputFile | Identifies the YUV file fed as input to the encoder. |
InputFileFormat |
Input file format. The supported values are listed below. For Codec-specific details, refer to Input File Format.
|
OutputFile | Specifies the output file where the encoded bitstream will be written by the application. |
StartFrame | Specifies the start frame for encoding. Encoding for
StartFrame−1 is skipped. Default value is
0 |
FramesToBeEncoded | Number of frames to encode. Set to 0 for encoding all frames in input YUV |
EPCodec |
Specifies the video codec type. The values can be:
|
ExtradataFileName | Specifies the path to the file in which the frame-wise extra data will get dumped, when -enableExtradata flag is enabled. The extradata includes information such as frame average QP, frame type, intra/inter MB or CTB counts, and so on. |
DynamicResolutionFileName | Specifies the path to the configuration file for Dynamic Resolution Change (DRC) feature. Refer to the DRC section below for the expected structure of the DRC configuration file. |
DRCBufferRealloc | Specifies whether DRC support should be enabled using the buffer
reallocation approach. The values can be:
|
InputFileDRC | Specifies the path to the input file after the DRC resolution change. This parameter should only be used when DRCBufferRealloc is set to 1. Refer to the DRC Buffer Reallocation section below for more information. |
QPDeltaMapFileBaseName | Specifies the base name of the per-frame QP delta map files. Refer to the QP delta map section below for the expected structure of the QP delta map files. |
BitrateFileName | Specifies the path to the configuration file for Dynamic Bitrate Change (DBC) feature. Refer to the DBC section below for the expected structure of the DBC configuration file. |
ROIParamFileName | Specifies the path to the configuration file for the ROI encode
feature, which is only applcable for H.264 and H.265 codecs.
Following is the expected structure of the ROI file. Each line of
the file corresponds to ROI parameters for one frame and should be
formatted using the following structure:
|
Encode Configuration Parameters
The following table describes the encode configuration parameters:
Parameter | Description |
---|---|
EPEncodeWidth | Specifies the width of the encode. |
EPEncodeHeight | Specifies the height of the encode. |
EPFrameRateNum EPFrameRateDen |
Specifies the numerator and denominator for the frame rate to use for encoding, in frames per second. The frame rate is: EPFrameRateNum / EPFrameRateDen |
EPGopLength | Specifies the number of pictures in a GOP. If 0, keyframes are not inserted automatically. |
EPGopPattern |
Specifies the GOP pattern. If the GOP length is 0, the Frame Interval Pattern must be set to IPP. The values can be:
|
EPMaxNumRefFrames |
Specifies the maximum number of reference frames. The value can be:
|
EPEnableROIEncode | Enables ROI encode by taking input region based deltaQp to be
provided through ROIParamFileName. This is only applicable for H.264
and H.265 codecs.
|
Quantization Configuration Parameters
The following table describes the quantization configuration parameters:
Parameter | Description |
---|---|
QPBSlice | Specifies the Quantization parameter for B slices . |
QPISlice | Specifies the Quantization parameter for I Slices. |
QPPSlice | Specifies the Quantization parameter P Slices. |
The range of QP values supported for each of the above parameter is as follows:
H264/HEVC -[0-51]
AV1 - [1-255]
Rate Control Configuration Parameters
The following table describes the rate control configuration parameters:
Parameter | Description |
---|---|
RCMode |
Specifies the rate control mode. The values can be:
|
RCAverageBitrate | Specifies the average bit rate in bits/second; used for encoding. |
RCMaxBitrate | Specifies the maximum bit rate for the encoded output. This is used in Variable Bit Rate (VBR) mode and is ignored for Constant Bit Rate (CBR) mode. |
RCVbvBufferSize | Specifies the VBV (HRD) buffer size in bits. Set to 0 to use the default VBV buffer size. |
RCVbvInitialDelay | Specifies the VBV (HRD) initial delay in bits. Set to 0 to use the default VBV initial delay. |
RCEnableMinQP | Set to 1 if minimum QP is used for the rate control. |
RCEnableMaxQP | Set to 1 if maximum QP is used for the rate control. |
Per-Frame Encode Configuration Parameters
The following table describes the per-frame encode configuration parameters:
Parameter | Description |
---|---|
EPEencodePicFlags |
Specifies the bitwise OR’ed encode picture flags. The flags are:
|
EPPictureType |
Specifies the input picture type. The client must set this parameter explicitly if it has not set the Enable PTD (picture type decision) to 1. The picture types are:
|
H.264 Encode Configuration Parameters
The following table describes the H.264 encode configuration parameters:
Parameter | Description |
---|---|
H264Profile |
Supported profiles are:
|
H264Level | Specifies the encoding level. The recommendation is for the
client to set the level to 0 to enable the NvMedia
Encode interface to select the correct level. |
H264EncPreset | Specifies the encoder preset to
use0x0 = NVMEDIA_ENCODE_QUALITY_HQ 0x10 = NVMEDIA_ENCODE_QUALITY_HP 0x20 = NVMEDIA_ENCODE_QUALITY_UHP recommend quality setting is NVMEDIA_ENCODE_QUALITY_HP |
H264Features |
Specifies the bitwise OR'ed configuration feature flags. The flags are:
|
H264IdrPeriod | Specifies the IDR interval. If not set, it defaults to the GOP length. A low latency application client must set the IDR interval to 0 so that IDR frames are not inserted automatically. |
H264RepeatSPSPPSMode |
Specifies the frequency of writing Sequence and Picture parameters. The values can be:
|
H264NumSliceCountMinus1 | One less than the number of slices desired per frame. |
H264DisableDeblockingFilterIDC | Deblocking filter mode. The value can be 0, 1, or 2. |
H264IntraRefreshPeriod |
The interval between successive intra refreshes if intra refresh is enabled and one-time intra refresh configuration is desired. If H264IntraRefreshPeriod is specified, the first IDR is encoded, and no more key frames are encoded. The client must set |
H264IntraRefreshCnt | The number of frames over which intra refresh occurs. |
H264MaxSliceSizeInBytes | The maximum slice size, in bytes, for dynamic slice mode. The client must enable dynamic slice mode to use this parameter. |
H264AdaptiveTransformMode |
Specifies the Adaptive Transform Mode. Available modes are:
|
H264BdirectMode |
Specifies the B Direct mode. Available modes are:
|
H264EntropyCodingMode |
Specifies the entropy coding mode. Available modes are:
|
H264MotionPredictionExclusionFlags |
Specifies the bitwise OR’ed exclusion flags for motion prediction. Available flags are:
|
H.264 VUI Configuration Parameters
The following table describes the H.264 VUI configuration parameters:
Parameter | Description |
---|---|
VUIAspectRatioInfoPresentFlag | A value of 1 indicates that the aspect ratio information is present. |
VUIAspectRatioIDC | Specifies the sample aspect ratio of the luma samples. |
VUIAspectSARWidth | Specifies the horizontal size of the sample aspect ratio. |
VUIAspectSARHeight | Specifies the vertical size of the sample aspect ratio. |
VUIOverscanInfoPresentFlag | A value of 1 indicates that overscan info is present. |
VUIOverscanInfo | Specifies overscan information, as defined in Annex E of the ITU-T Specification. |
VUIVideoSignalTypePresentFlag | If set to 1, specifies that Video Format, Video Full Range Flag, and Color Description Present Flag are present. |
VUIVideoFormat | Specifies the source video format as defined in Annex E of the ITU-T Specification. |
VUIVideoFullRangeFlag | Specifies the output range of the luma and chroma samples, as defined in Annex E of the ITU-T Specification. |
VUIColourDescriptionPresentFlag | A value of NVMEDIA_TRUE indicates that the color
primaries, transfer characteristics, and color matrix are
present. |
VUIColourPrimaries | Specifies the color primaries for converting to RGB, as defined in Annex E of the ITU-T Specification. |
VUITransferCharacteristics | Specifies the opto-electronic transfer characteristics to use, as defined in Annex E of the ITU-T Specification. |
VUIMatrixCoefficients | Specifies the matrix coefficients used to derive the luma and chroma from the RGB primaries, as defined in Annex E of the ITU-T Specification. |
H.264 Payload Configuration Parameters
The following describes the H.264 payload configuration parameters:
Parameter | Description |
---|---|
H264PayloadSize | SEI payload 1 size in bytes. SEI payload must be byte aligned, as described in Annex D of the H.264 Specification. |
H264PayloadType | SEI payload 1 types and syntax is available in Annex D of the H.264 Specification. |
H264Payload | Payload 1 data. |
H.264 Per-Frame Encode Configuration Parameters
The following table describes the H.264 per-frame encode configuration parameters. These are in addition to the per-frame encode configuration parameters. These parameters must be sent on a per-frame basis.
Parameter | Description |
---|---|
H264PayloadArraySize | Size of Payload Array. |
H264PayloadArrayIndexes | Array of the Payload section indexes to be used. |
H.265 Configuration Parameters
The following table describes the H.265 configuration parameters:
Parameter | Description |
---|---|
H265Profile |
Supported profiles are: 1: Main profile (supported) |
H265Level | Specifies the encoding level. It is recommended that the client set the level to 0 to enable the NvMedia Encode interface to select the correct level. |
H265EncPreset | Specifies the encoder preset to
use0x0 = NVMEDIA_ENCODE_QUALITY_HQ 0x10 = NVMEDIA_ENCODE_QUALITY_HP 0x20 = NVMEDIA_ENCODE_QUALITY_UHP recommend quality setting is NVMEDIA_ENCODE_QUALITY_HP |
H265Features |
Specifies bitwise OR'ed configuration feature flags. The flags are:
|
H265IdrPeriod | Specifies the IDR interval. If not set, defaults to the GOP Length. A low latency application client can set the IDR interval to 0 so that IDR frames are not inserted automatically. |
H265RepeatSPSPPSMode |
Specifies the frequency of writing Sequence and Picture parameters. Available values are:
|
H265NumSliceCountMinus1 | One less than the number of slices desired per frame. |
H265IntraRefreshPeriod |
The interval between successive intra refreshes, assuming:
If The client must set |
H265IntraRefreshCnt | Specifies the number of frames over which intra refresh occurs. |
H265MaxSliceSizeInBytes | Specifies the maximum slice size, in bytes, for dynamic slice mode. The client must enable dynamic slice mode to use this parameter. |
H.265 VUI Configuration Parameters
The following table describes the H.265 VUI configuration parameters:
Parameter | Description |
---|---|
H265VUIAspectRatioInfoPresentFlag | A value of 1 indicates that aspect ratio information is present. |
H265VUIAspectRatioIDC | Specifies the value of the sample aspect ratio of the luma samples. |
H265VUIAspectSARWidth | Horizontal size of the sample aspect ratio. |
H265VUIOverscanInfoPresentFlag | A value of 1 indicates that overscan information is present. |
H265VUIOverscanInfo | Specifies overscan information, as defined in Annex E of the ITU-T Specification. |
H265VUIVideoSignalTypePresentFlag | A value of 1 indicates that Video Format, Video Full Range Flag, and Color Description Present Flag are present. |
H265VUIVideoFormat | Specifies the source video format, as defined in Annex E of the ITU-T Specification. |
H265VUIVideoFullRangeFlag | Specifies the output range of the luma and chroma samples, as defined in Annex E of the ITU-T Specification. |
H265VUIColourDescriptionPresentFlag | A value of NVMEDIA_TRUE indicates that the color primaries, transfer characteristics, and color matrix are present. |
H265VUIColourPrimaries | Specifies color primaries for converting to RGB, as defined in Annex E of the ITU-T Specification. |
H265VUITransferCharacteristics | Specifies the opto-electronic transfer characteristics to use, as defined in Annex E of the ITU-T Specification. |
H265VUIMatrixCoefficients | Specifies the matrix coefficients to use to derive the luma and chroma from the RGB primaries, as defined in Annex E of the ITU-T Specification. |
H.265 Payload Configuration Parameters
The following table describes the H.265 payload configuration parameters:
Parameter | Description |
---|---|
H265PayloadSize | SEI payload 1 size in bytes. SEI payload must be byte aligned, as described in Annex D of the ITU‑T Specification. |
H265PayloadType | SEI payload 1 types and syntax are available in Annex D of the ITU‑T Specification. |
H265Payload | Payload 1 data. |
H.265 Per-Frame Encode Configuration Parameters
The following table describes the H.265 per-frame encode configuration parameters. These parameters must be sent on a per frame basis.
Parameter | Description |
---|---|
H265PayloadArrayIndexes | Array of Payload section indexes to be used. |
H265PayloadArraySize | Size of Payload Array. |
AV1 Configuration Parameters
The following table describes the AV1 configuration parameters:
Parameter | Description |
---|---|
EPEnableTileEncode | Enable encoding with multiple tile configuration. |
EPlog2NumTileInRow | Specifies the log of number of tiles in a row. |
EPlog2NumTileInCol | Specifies the log of number of tiles in a column. |
AV1EnableInternalHighBitDepth | Enables internal high bit depth. When enabled, input YUV is 8 bit, but the encoded bitstream is 10 bit. |
AV1EnableSsimRdo | Enables SSIM-based rate distortion optimization |
AV1FrameRestorationType | Specifies the frame restoration type. |
AV1EnableUniCompound | Enables the uni-compound for P frames. |
AV1IdrPeriod |
Specifies the IDR interval. If not set, the interval is equal to the GOP length. Low latency application client can set the IDR interval to 0 so that IDR frames are not inserted automatically. Default value = 0 |
AV1EncPreset | Specifies the encoder preset to
use0x10 = NVMEDIA_ENCODE_QUALITY_HP 0x20 = NVMEDIA_ENCODE_QUALITY_UHP recommend quality setting is NVMEDIA_ENCODE_QUALITY_HP |
AV1Features |
Specifies bitwise OR'ed configuration feature flags. The flags are:
|
Supported Input File Format
H264 Enc supports the following File formats- IYUV, YV12, YUV444
H265 Enc supports the following File formats- IYUV, YV12, YUV444, IYUV420_10bit (LSB aligned), IYUV444_10bit (LSB aligned), IYUV420_10bit (MSB aligned), IYUV444_10bit (MSB aligned)
AV1 Enc supported the following File formats - IYUV, YV12, IYUV420_10bit (LSB aligned), IYUV420_10bit (MSB aligned)
Configuration Parameters for Dynamic Features
The following dynamic features can be configured using additional input files:
<frame_id> <width> <height>
For
each line in the preceding configuration file, the specified resolution will
take effect for all the frames starting from the specified frame_id until the
frame_id specified on the next line (if any) or the end of the encode session,
whichever occurs first.The DRC feature can be applied in two different modes, as described below:
- The test app allocates all buffers at the maximum DRC resolution specified by EncodeWidth x EncodeHeight, and reads all the frames of the input YUV file at the same max resolution.
- Within each input frame, the actual frame to be encoded should be positioned by aligning to the top-left corner, with the rest of the frame buffer being filled with black padding, to match the maximum DRC resolution.
- The DynamicResolutionFileName parameter should be configured as per the preceding description; and the specified file should contain only one line, because only one resolution change can be supported using the buffer reallocation approach.
- The InputFile parameter should be used to identify the input YUV file for the initial resolution, whereas the InputFileDRC parameter should be used to identify the input YUV file after the resolution change.
- The test app pre-allocates buffers for the initial resolution as well as the changed resolution after DRC.
- The test app starts by reading frames from the InputFile for encoding at the initial resolution.
- When the processing reaches the frame_id specified on the first (and only) line of DynamicResolutionFileName, the test app switches to using the buffers allocated for the changed resolution.
- The test app now starts reading the subsequent frames from InputFileDRC file, until the end of the encode session.
<frame_id> <bitrate_bps> <vbv_buffer_size_bits>
For
each line in the above configuration file, the specified bitrate settings will take
effect for all the frames starting from the specified frame_id until the frame_id
specified on the next line (if any) or the end of the encode session, whichever
occurs first.This feature can be enabled by providing the QPDeltaMapFileBaseName parameter, which
should be set to the basename of a path containing input QP delta files for each
frame. The filename of each frame's QP delta map should be as per the format
<QPDeltaMapFileBaseName>_%05d.bin
where
%05d
will be replaced with the frame index starting from
1.
Usage guide for Dynamic Features
- After changing any dynamic parameter, there should be a gap of at least 3 frames before the same or different dynamic parameter is changed. This will allow the rate control algorithm to stabilize at the current operating point, and avoid bitrate overflows.
- While applying DRC, the Encode Configuration Parameters
EPEncodeWidth, EPEncodeHeight
should be set to the maximum target resolution that would be applied during the encode session. In addition, the encoding should always start with this maximum target resolution; in other words, DRC should not be applied to the first frame of the session. - Although DRC supports changes from any initial resolution to any new target resolution, it is recommended to perform a gradual resolution change, by applying not more than 2x increase or decrease in the width and height of the resolution at a time. For example, to instead of changing the resolution from 540p(960x540) to 4k(3840x2160), a smoother rate control can be achieved by first switching from 540p to 1080p(1920x1080), and then after 3 frames to 4k.
- The dimensions of QP delta map for each frame should be computed as
follows:
where#define ALIGN_256(x) (x << 8) frameWidthInCTB = (EPEncodeWidth + CTB_SIZE - 1)/CTB_SIZE frameHeightInCTB = (EPEncodeHeight + CTB_SIZE - 1)/CTB_SIZE QPDeltaBufferSizeInBytes = ALIGN_256(frameWidthInCTB) * (frameHeightInCTB + 2)
CTB_SIZE=32
, andEPEncodeWidth, EPEncodeHeight
are as per the Encode Configuration Parameters. Each entry in the QP delta map file should be a signed 8-bit integer, denoting the QP delta value for a CTB of 32x32 pixels. The frame should be scanned row-wise from the top-left to bottom-right. - In particular, the dimensions of the QP delta map buffer do not change even while applying Dynamic Resolution Change. In this case,, the QP delta map values should be arranged as if the actual frame to be encoded is positioned by aligning to the top-left corner, with the rest of the frame buffer being filled with black padding, to match the maximum DRC resolution.
- QP delta map should not contain any values with a magnitude exceeding 5. In addition, the average value of QP delta map should be close to zero, for each row of CTBs within the frame. This allows a uniform allocation of the bits throughout the frame.
- It is possible to update multiple dynamic parameters at the same frame; and it may also be necessary to take advantage of the same. For example, the target bitrate should be adjusted based on the current resolution, as well as the complexity of the encoding content. Increasing the resolution without increasing the target bitrate causes a reduction in video quality.