GStreamer Encoding Parameters - 2024.1 English

H.264/H.265 Video Codec Unit v1.2 Solutions LogiCORE IP Product Guide (PG252)
Document ID
PG252
Release Date
2024-05-30
Version
2024.1 English

The GStreamer encoding parameters are shown in the following table.

Table 1. GStreamer Encoding Parameters
VCU Parameter GStreamer Property Description
Rate Control Mode control rate Available bit rate control modes, Constant Bit rate (CBR) and Variable Bit rate (VBR) Encoding
  • 0 = Disable (CONST_QP, Constant QP)
  • 1 = Variable (VBR)
  • 2 = Constant (CBR)
  • 3 = Variable skip frames
  • 4 = Constant skip frames
  • 2130706433=low-latency (Hardware rate control, used in slice level encoding)
  • 2130706434=capped-variable (CVBR)

Default value: 2

Note: Variable Skip Frames and Constant Skip Frames are coming from gstreamer default plugin, not supported in VCU. 1, 2, 3, 4, 5
Use Output Port Buffer Pool use-out-port-pool If enabled, use DMA based buffer pool on encoder’s the output pool.

Default value: FALSE
Target Bit Rate 6 target bitrate Target bitrate in Kbps

Default value: 64
Maximum Bit Rate 6 max bitrate Maximum bitrate, in Kbps, used in VBR rate control mode. Default value: target-bitrate. The max-bitrate value should always be the target-bitrate

Default value: 64
Profile Through caps

Supported profiles for corresponding codec are mentioned in Table 1

Default value: HEVC_MAIN
Level Through caps

Supported Levels for corresponding codec are mentioned in Table 1

Default value: 51
Tier Through caps

Supported Tier for H.265 (HEVC) codec is mentioned in Table 1

Default value: MAIN_TIER
Slice QP / I-frame QP quant-i-frames Quantization parameter for I‑frames in CONST_QP mode, also used as initial QP in other rate control modes. Range 0–51.

Default value: 30
P-frame QP quant-p-frames Quantization parameter for P‑frames in CONST_QP mode. Range 0–51.

Default value: 30
B-frame QP quant-b-frames Quantization parameter for B‑frames in CONST_QP mode. Range 0–51.

Default value: 30
GOP Length gop-length Distance between two consecutive Intra frames. Specify integer value between 0 and 1,000. Value 0 and 1 corresponds to Intra-only encoding

Default value: 30
Number of B-frames b-frames Number of B-frames between two consecutive P-frames. Used only when gop-mode is basic or pyramidal.

Range:

0-4 (for gop-mode = basic)

3, 5, or 7 (for gop-mode = pyramidal)

B-frames should be set to zero in low-latency and reduced-latency mode as there cannot be any frame reordering when b-frames is set.

Default value: 0
Number of Slices num-slices Specifies the number of slices used for each frame. Each slice contains one or more full LCU row or rows and are spread over the frame as regularly as possible. The minimum value is 1.

Max supported value as below:

In low-latency mode

H.264(AVC): 32

H.265 (HEVC): 22

More than 16 slices will not bring much benefit in low latency mode because of overhead

In normal latency-mode

H.264(AVC): picture_height/16

H.265(HEVC): minimum of picture_height/32

Above max supported values in normal mode will work but HEVC has some more limitations when encoder uses multiple cores

When HEVC encoder uses multiple cores (i.e. anything beyond 1080p60 resolution) then the max num-slices is limited by "Max # of tile rows MaxTileRows."

Refer to Table 1. In 4k encoding, num-slices should be set to 8 for all latency-modes to achieve best performance.

Default value: 1
Minimum QP min-qp Minimum QP value allowed in encoding session.

Range 0–51.

Default value: 10
Maximum QP max-qp Maximum QP value allowed in encoding session.

Range 0–51.

Default value: 51
GOP Configuration gop-mode Specifies group of pictures configuration
  • 0 = basic (IPPP..IPPP…)
  • 1 = basic-b (basic GOP settings, includes only B-frames)
  • 2 = pyramidal (advanced GOP pattern with hierarchical B frame, works with B=3, 5, 7 and 15)
  • 3 = pyramidal-b (advanced GOP pattern with hierarchical B-frames, includes only B-frames)
  • 4 = adaptive (advanced GOP pattern with adaptive B-frames)
  • 5 = low-delay-p ( IPPPPP…)
  • 6 = low-delay-b (IBBBBB…)

Both open and closed GOP structures are supported.

When Gop.FreqIDR ≠ Gop.Length and B-frames ≠ 0, open GOP structures are possible.

For pyramidal gop-mode, encoder uses closed GOPs only.

Without B-frames, it only uses closed GOPs.

With B-frames, gop-mode=pyramidal, it uses closed GOPs.

With B-frames, gop-mode=default and periodicity-idr = 0, it uses open GOPs.

With B-frames, gop-mode=default and IDR_freq= GOP. Length, it uses closed GOPs.

(For different IDR_freq, you can get mix of open and closed GOPs)

Default value: 0
Gradual Decoder Refresh gdr-mode Specifies which Gradual Decoder Refresh scheme should be used when gop-mode = low_delay_p
  • 0 = disable
  • 1 = vertical (Gradual refresh using a vertical bar moving from left to right)
  • 2 = horizontal (Gradual refresh using a horizontal bar moving from top to bottom)

Default value: 0
QP Control Mode qp-mode QP control mode used by the VCU encoder
  • 0 = uniform (Use the one QP for all coding units of the frame)
  • 1 = roi (Adjust QP according to the regions of interest defined on each frame. ROI metadata must be supplied)
  • 2 = auto (Let the VCU encoder change the QP for each coding unit according to its content)

Default value: 2
Filler data filler-data Enable/Disable filler data adding functionality in CBR rate control mode. Boolean: TRUE or FALSE

Default value: True
Entropy Mode entropy-mode Specifies the entropy mode for H.264 (AVC) encoding process
  • 0 = CAVLC
  • 1 = CABAC

Default value: 1
Deblocking Filter loop-filter-mode Enables/disables the deblocking filter option
  • 0 = enable
  • 1 = disable
  • 2 = disable-slice-boundary (Excludes slice boundaries from filtering)

Default value: 0
IDR picture frequency periodicity-idr Specifies the number of frames between consecutive instantaneous decoder refresh (IDR) pictures. The periodicity-idr property was formerly called gop-freq-idr.

Allowed values: <Positive value> or -1 to disable IDR insertion

Default value: 0 (first frame is IDR)
Initial Removal Delay initial-delay Specifies the initial removal delay as specified in the
HRD model in milliseconds. Not used when control-rate = disable
Note: If this value is set too low (less than 1 frame period), you can see reduced visual quality.

Default value: 1500
Coded Picture buffer size cpb-size Specifies the coded picture buffer (CPB) as specified in the HRD model in milliseconds. Not used when control-rate = disable

Default value: 3000
Dependent slice dependent-slice Specifies whether the additional slices are dependent on other slice segments or regular slices in multiple slices encoding sessions. Used in H.265 (HEVC) encoding only. Boolean: TRUE or FALSE

Default value: False
Target slice size slice-size If set to 0, slices are defined by the num-slices parameter, else it specifies the target slice size in bytes. Used to automatically split the bitstream into approximately equally‑sized slices.

Range 0–65,535.

Default value: 0
Scaling Matrix scaling-list Specifies the scaling list mode
  • 0 = flat
  • 1 = default

Default value: 1
PrefetchLevel2 prefetch-buffer Enable/Disable L2Cache buffer in encoding process

Default value: false
Vertical Search Range low-bandwidth Specifies low bandwidth mode. Decreases the vertical search range used for P-frame motion estimation. TRUE or FALSE.

Default values: FALSE
Slice Height slice-height This parameter is used for 2017.4 and earlier releases only. It is deprecated in 2018.3 and later releases. Specifies input buffer height alignment of upstream element, if any.

Default value: 1
Aspect-Ratio aspect-ratio Selects the display aspect ratio of the video sequence to be written in SPS/VUI.
  • 0 = auto - 4:3 for SD video,16:9 for HD video, unspecified for unknown format
  • 1 = aspect_ratio_4_3 (4:3 aspect ratio)
  • 2 = aspect_ratio_16_9 (16:9 aspect ratio)
  • 3 = none (Aspect ratio information is not present in the stream)

Default value: 0
Constrained Intra Prediction constrained-intra-prediction If enabled, prediction only uses residual data and decoded samples from neighboring coding blocks that are coded using intra prediction modes. Boolean: TRUE or FALSE.

Default value: False
Long term Ref picture long-term-ref If enabled, encoder accepts dynamically inserting and using long-term reference picture events from upstream elements

Boolean: TRUE or FALSE

Default value: False
Long term picture frequency long-term-freq Periodicity of Long-term reference picture marking in encoding process Units in frames, distance between two consecutive long-term reference pictures

Default value: 0
Dual pass encoding look-ahead The number of frames processed ahead of second pass encoding. If smaller than 2, dual pass encoding is disabled.

Default value: 0
Alignment Through caps Encoder alignment
  • =au (normal mode)
  • =nal (low-latency mode)

Default value: au

Note: When encoder alignment is set to low-latency mode, it is recommended that you set the rate control mode (control-rate) to low latency. See VCU Latency Modes on how to set alignment. When using Low Latency mode, the encoder and decoder are limited by the number of internal cores. The encoder has a maximum of four streams and the decoder has a maximum of two streams.
Max Quality Target max-quality-target Caps quality at certain limit keeping the bit rate variable. Only used with capped variable rate-control. It xcps the quality at a certain high limit, keeping bitrate variable

Range: 0 to 20 (20 = lossless quality)

Default value: 14

The allowed values are between 0 and 20 (where 0 is really poor quality and 20 is close to visual lossless quality). If the encoder cannot reach this quality level due to the video complexity and/or a restricted bitrate, or If the quality target is too high, then the Capped-VBR has no effect compared to VBR.

Note: The controlSW parameter name in cfg is MaxQuality.
Max Picture Size max-picture-size You can curtail instantaneous peak in the bit-stream using this parameter. It works in CBR/VBR rate-control only. When Max Picture Size is enabled, the VCU encoder uses CBR/VBR but it also enables the hardware rate control module to keep track of encoding frame size. The hardware rate control module adjusts the QPs within the frame to ensure that the encoded picture sizes honor the provided max-picture-size.

MaxPictureSize = TargetBitrate / FrameRate * AllowedPeakMargin

For 100 Mb/s TargetBitrate, 60 fps FrameRate, and 10% AllowedPeakMargin,

MaxPictureSize = (100 Mb/s / 60 fps ) * 1.1 = 1834 Kb per frame.
Slice Type Value Selection uniform-slice-type

Enable/Disable uniform slice type in slice header.

When this is enabled, the following slice-type values are used in slice header.

  • I slice: slice-type = 7 is used
  • P slice: slice-type=5 is used
  • B slice: slice-type=6 is used

Supported from 2021.1 release onwards.
Input yuv Crop Feature input-crop

The input-crop parameter sets <pos-x, pos-y, cropWidth, cropHeight> values for the VCU encoder.

The property type of max-picture-sizes is GstValueArray.

This parameter is supported only from release 2021.1 onwards.
Latency latency-mode For 2018.3 and prior releases (Not used in 2019.1 or later releases; for 2019.1 and future releases, use the Alignment parameter), specifies encoder latency modes:
  • 0 = normal (provides frame level output to the next element)
  • 1 = low-latency (provides slice level output to the next element)

Default value: 0

Note: The low-latency latency mode is not recommended when Rate Control is CBR/VBR.
Default ROI Quality default-roi-quality Default quality level to apply to each Region of Interest
  • 0=high – Delta QP of -5
  • 1=medium – Delta QP of 0
  • 2=low – Delta QP of +5
  • 3=don't-care – Maximum delta QP value

Default: 0
Frame Skip skip-frame If enabled and encoded, picture exceeds the CPB buffer size; the specific picture is discarded and replaced by a picture with all MB/CTB encoded as skip. Only use of control-rate=constant/variable and b-frames are less than 2.

Default: FALSE
Maximum number of consecutive frame skips max-consecutive-skip Specifies the maximum number of consecutive skipped frames if skip-frame is enabled.

Default Value: 4294967295
Max picture size for frame types max-picture-sizes Max picture sizes based on frame types ('<I, P, B>’) Maximum picture size of I, P, and B frames in Kb, encoded picture size is limited to max-picture-size-x value. If set it to 0, the max-picture-size-x does not have any effect. GstValueArray of GValue of type "gint" Write only.

The property type of max-picture-sizes is GstValueArray.
Intraframes interval interval-intraframes Interval of coding Intra frames

Default: 0
Beta offset for deblocking filters loop-filter-beta-offset Beta offset for the deblocking filter is used only when loop-filter-mode is enabled.

Range: -6 to 6

Default: -1
Alpha offset for deblocking filters loop-filter-alpha-c0-offset Alpha C0 offset for the deblocking filter, used only when loop-filter-mode is enabled.

Range: -6 to 6

Default: -1
  1. Rate control is handled in MCU FW only and no signals (either in Software API or FPGA signals) that are triggered during rate control process.
  2. CBR: The goal of CBR is to reach the target bitrate on average (at the level of one or a few GOPs) and to comply with the "HRD" model, that is avoiding decoder buffer overflows and underflows. In CBR mode, a single bitrate value defines both the target stream bitrate and the output/transmission (leaky bucket) bitrate. The reference decoder buffer parameters are CPBSize and Initial Delay. The CBR rate control mode tries to keep the bit rate constant whilst avoiding buffer overflows and underflows. If a buffer underflow happens, the QP is increased (up to MaxQP) to lower the size in bits of the next frames. If a buffer overflow occurs, the QP is decreased (down to MinQP) to increase the size in bits.
  3. VBR: When using VBR, the encoder buffer is allowed to underflow (be empty), and the maximum bitrate, which is the transmission bitrate used for the buffering model, can be higher than the target bitrate. So VBR relaxes the buffering constraints and allows to decrease the bitrate for simple content and can improve quality by allowing more bits on complex frames. VBR mode constrains the bitrate with a specified maximum while keeping it on the target bit rate where possible. Similar to CBR, it avoids buffer underflow by increasing the QP. However, the target bit rate can be exceeded up to the maximum bit rate. So, the QP has to be increased by a smaller factor. A buffer overflow results in an unchanged QP and a lower bit rate.
  4. Both CBR and VBR use frame-level statistics from the hardware to update the initial QP for the next frame (rate control can be combined with QP control that can adjust the QP at block level for improving subjective quality).
  5. LOW_LATENCY rate control (hardware rate control) computes the QP at block level to reach a target bitstream size for each frame in an accurate way, and is especially useful for the support of low-latency pipelines.
  6. Xilinx low latency supports 25 Mb/s for single stream of 4K and 6 Mb/s for 4x stream of 1080.
  7. The following is an example for the v4l2src encode and file sink using custom max-pictures-sizes:
    gst-launch-1.0 v4l2src io-mode=4 ! video/x-raw, width=1920, height=1080 format=NV12, framerate=60/1 ! omxh265enc control-rate=2 target-bitrate=20000 gop-mode=5 qp-mode=auto gop-length=60 cpb-size=1000 initial-delay=500 max-picture-sizes="<666,333,0>" ! filesink location="/media/card/output_maxpicture1.hevc"
  8. The sample pipeline for the input-crop feature is as follows: 
    gst-launch-1.0 filesrc location= "test_720x243.nv16" ! videoparse width=720 height=243 format=nv16 framerate=60/1 ! omxh264enc input-crop="<0,1,720,240>" ! filesink location=test.avc -v