API Parameters
Note
- When a parameter is supported by both
wz_codec_controlandwz_codec_set_option, setting it with thewz_codec_set_optionis recommended. - If a parameter is set multiple times, the value from the last setting will take effect.
Set by wz_codec_enc_init() and type wz_codec_enc_cfg_t()
| Ctrl ID | Range | Default | Recommend Setting | Description | Sample app command line options |
|---|---|---|---|---|---|
| g_usage | [0-2] | 0 | 0 | Algorithm specific "usage" value. Valid values: 0 - Good Quality; 2 - All Intra | --usage |
| g_threads | [0, core count of the machine] | 0 | Maximum number of threads to use | --threads | |
| g_profile | [0-2] | 0 | 0 | Bitstream profile to use | --profile |
| g_w | [64-16384] | 320 | Set according to the actual input frame width | Width of the frame | --width |
| g_h | [64-8704] | 240 | Set according to the actual input frame height | Height of the frame | --height |
| g_limit | [0-(2^31)-1] | 0 | Max number of frames to encode | --limit | |
| g_forced_max_frame_width | [64-16384] | 0 | Forced maximum width of the frame | --forced_max_frame_width | |
| g_forced_max_frame_height | [64-8704] | 0 | Forced maximum height of the frame | --forced_max_frame_height | |
| g_bit_depth | [8,10] | 8 | Bit-depth of the codec | --bit-depth | |
| g_input_bit_depth | [8,10] | 8 | Depend on input source | Bit-depth of the input frames | --input-bit-depth |
| g_timebase | {1, 30} | Depend on input source | Indicates the smallest interval of time, in fractional seconds, used by the stream | --timebase | |
| g_error_resilient | 0 | 0 | Enable error resilient modes | --global-error-resilient | |
| g_pass | [0-2] | 0 (WZ_RC_ONE_PASS) | Multi-pass Encoding Mode. This value should be set to the current phase for multi-pass encoding | n/a | |
| g_lag_in_frames | [0-72] | 25 | 72 | Allow lagged encoding. If set, this value allows the encoder to consume a number of input frames before producing output frames | --lag-in-frames |
| rc_end_usage | [0-3] | 0 | 0(VBR), 3(Q) | Rate control algorithm to use, 0: VBR, 1: CBR, 2: CQ, 3: Q | --end-usage |
| rc_twopass_stats_in | n/a | NULL | A buffer containing all of the stats packets produced in the first pass | n/a | |
| rc_firstpass_mb_stats_in | n/a | NULL | Do not change the default value | First pass mb stats buffer | n/a |
| rc_target_bitrate | [1-100000] | 256 | Target data rate in kilobits per second | --target-bitrate | |
| rc_min_quantizer | [0-63] | 0 | Set to 4 for grain preservation | Minimum (Best Quality) Quantizer | --min-q |
| rc_max_quantizer | [0-63] | 63 | Maximum (Worst Quality) Quantizer | --max-q | |
| rc_undershoot_pct | [0-100] | 25 | Rate control adaptation undershoot control | --undershoot-pct | |
| rc_overshoot_pct | [0-100] | 25 | Rate control adaptation overshoot control | --overshoot-pct | |
| rc_buf_sz | [0-(2^32)-1] | 6000 | Decoder Buffer Size in milliseconds | --buf-sz | |
| rc_buf_initial_sz | [0-(2^32)-1] | 4000 | Decoder Buffer Initial Size in milliseconds | --buf-initial-sz | |
| rc_buf_optimal_sz | [0-(2^32)-1] | 5000 | Decoder Buffer Optimal Size in milliseconds | --buf-optimal-sz | |
| rc_2pass_vbr_bias_pct | [0-100] | 50 | Two-pass mode CBR/VBR bias expressed on a scale of 0 to 100 | --bias-pct | |
| rc_2pass_vbr_minsection_pct | [0-(2^32)-1] | 0 | Two-pass mode per-GOP minimum bitrate expressed as a percentage of the target bitrate | --minsection-pct | |
| rc_2pass_vbr_maxsection_pct | [0-(2^32)-1] | 2000 | Two-pass mode per-GOP maximum bitrate expressed as a percentage of the target bitrate | --maxsection-pct | |
| kf_mode | [0,1] | 1 | Do not change the default value | Keyframe placement mode, 0: disabled, 1: auto | --disable-kf |
| kf_min_dist | [0-(2^32)-1] | 0 | Keyframe minimum interval expressed as a number of frames | --kf-min-dist | |
| kf_max_dist | [0-(2^32)-1] | 999999 | Keyframe maximum interval expressed as a number of frames | --kf-max-dist | |
| full_still_picture_hdr | [0,1] | 0 | Do not change the default value | If this is nonzero, the encoder will generate a full header even for still picture encoding | --full-still-picture-hdr |
| save_as_annexb | [0,1] | 0 | Bitstream syntax mode. Value of 0 indicates bitstream is saved as Section 5 bitstream. A value of 1 indicates the bitstream is saved in Annex-B format | --annexb | |
| tile_width_count | [0-64] | 0 | Number of explicit tile widths specified | Derived from --tile-width | |
| tile_height_count | [0-64] | 0 | Number of explicit tile heights specified | Derived from --tile-height | |
| tile_widths | no greater than frame width | {0} | Array of specified tile widths | --tile-width | |
| tile_heights | no greater than frame height | {0} | Array of specified tile heights | --tile-height | |
| use_fixed_qp_offsets | [0,1] | 0 | Set to 1 for grain preservation in capped CRF RC mode | Whether encoder should use fixed QP offsets | --use-fixed-qp-offsets |
| fixed_qp_offsets | [-1-63] | { -1, -1, -1, -1, -1 } | Set to 0,0,0,0,0 for grain preservation in capped CRF RC mode | Fixed QP offsets for frames at different levels of the pyramid | --fixed-qp-offsets |
| encoder_cfg | n/a | Do not change the default value | Options defined per config file | n/a | |
| enable_frame_mt | [0,2,4,8] | 0 | Enable frame-level parallel encoding, 0: disable frame-level parallel encoding, 2, 4, and 8: enable frame-level parallel encoding. A greater value represents increasing levels of parallelism | --enable-frame-mt | |
| forced_kf_min_dist | [0-(2^31)-1] | 0 | Minimum distance between forced keyframes | --forced-kf-min-dist | |
| kf_pos_fn | any string | NULL | File path to write/read the key frame position for the whole sequence | --kf-pos-fn | |
| kf_pos_mode | [0,1,2] | 2 (disable) | Mode to indicate the operations to key frame position, 0: read, 1: record, 2: disable | --kf-pos-mode | |
| fp_scale | [-1,0,1] | 0 (no scale) | Scale frame in first pass, 0: no scale, 1: scale down, -1: scale up | --fp-scale |
Set by wz_codec_control(wz_codec_ctx_t *ctx, int ctrl_id)
| Ctrl ID | Range | Default | Recommend Setting | Description | Sample app command line options |
|---|---|---|---|---|---|
| WZE_SET_CPUUSED | [0-22] | 0 | 3,5 | Speed setting | --cpu-used |
| WZE_SET_CQ_LEVEL | [0-6400] | 10 | Constant/Constrained Quality level. Values 0–63 use the standard libaom CQ scale. For values greater than 63, the actual quality level is value / 100, allowing finer-grained quality control. | --cq-level | |
| WZAV1E_SET_MIN_GF_INTERVAL | [0,4,8,16,32] | 0 | Min gf/arf frame interval. It is recommended to set this parameter using the function wz_codec_set_option. E.g. wz_codec_set_option("min-gf-interval", "0") | --min-gf-interval | |
| WZAV1E_SET_MAX_GF_INTERVAL | [0,4,8,16,32] | 0 | 16 for VOD | Max gf/arf frame interval. It is recommended to set this parameter using the function wz_codec_set_option. E.g. wz_codec_set_option("max-gf-interval", "16") | --max-gf-interval |
| WZAV1E_SET_SUPERBLOCK_SIZE | [0,1,2] | 2 (dynamic) | WZ_SUPERBLOCK_SIZE_64X64 for 1080p or lower resolution content; WZ_SUPERBLOCK_SIZE_128x128 for 4k content | Superblock size to use, enum wz_superblock_size. It is recommended to set this parameter using the function wz_codec_set_option. See property "sb-size" in Table 3 | --sb-size |
| WZAV1E_SET_ENABLE_OVERLAY | [0,1] | 0 | Enable/disable overlay frame | --enable-overlay | |
| WZE_SET_TUNING | [0,1,10] | 0 (PSNR) | WZ_TUNE_SSIM (1) or WZ_TUNE_WZVMAF(10) | enum wz_tune_metric | --tune |
| WZAV1E_SET_TILE_COLUMNS | [0-6] | 0 | 1 (2 tile columns) for better MT efficiency | Tile columns in log2 units. It is recommended to set this parameter using the function wz_codec_set_option. E.g. wz_codec_set_option("tile-columns", "1") | --tile-columns |
| WZAV1E_SET_TILE_ROWS | [0-6] | 0 | 0 | Tile rows in log2 units. It is recommended to set this parameter using the function wz_codec_set_option. E.g. wz_codec_set_option("tile-rows", "1") | --tile-rows |
| WZAV1E_SET_DENOISE_NOISE_LEVEL | [0-50] | 0 | 25 | Act as a switch for Film Grain Synthesis (FGS). While the noise level itself is estimated internally, setting this parameter to 0 disables FGS, while any value greater than 0 enables it | --denoise-noise-level |
| WZAV1E_SET_FILM_GRAIN_TABLE | any string | NULL | Set the path to the film grain table file | --film-grain-table | |
| WZAV1E_SET_COLOR_RANGE | [0,1] | 0 | 0: studio range, 1: full range | ||
| WZAV1E_SET_COLOR_PRIMARIES | [1,2,4-12,22] | 2 | CICP color primaries: 1: BT.709 2: Unspecified 4: BT.470 System M (historical) 5: BT.470 System B, G (historical) 6: BT.601 7: SMPTE 240 8: Generic film (color filters using illuminant C) 9: BT.2020, BT.2100 10: SMPTE 428 (CIE 1921 XYZ) 11: SMPTE RP 431-2 12: SMPTE EG 432-1 22: EBU Tech. 3213-E |
--color-primaries | |
| WZAV1E_SET_TRANSFER_CHARACTERISTICS | [1,2,4-18] | 2 | CICP transfer characteristics: 1: BT.709 2: Unspecified 4: BT.470 System M (historical) 5: BT.470 System B, G (historical) 6: BT.601 7: SMPTE 240 M 8: Linear 9: Logarithmic (100:1 range) 10: Logarithmic (100 * Sqrt(10):1 range) 11: IEC 61966-2-4 12: BT.1361 13: sRGB or sYCC 14: BT.2020 10-bit systems 15: BT.2020 12-bit systems 16: SMPTE ST 2084, ITU BT.2100 PQ 17: SMPTE ST 428 18: BT.2100 HLG, ARIB STD-B67 |
--transfer-characteristics | |
| WZAV1E_SET_MATRIX_COEFFICIENTS | [0-2,4-14] | 2 | CICP matrix coefficients: 0: Identity matrix 1: BT.709 2: Unspecified 4: US FCC 73.628 5: BT.470 System B, G (historical) 6: BT.601 7: SMPTE 240 M 8: YCgCo 9: BT.2020 non-constant luminance, BT.2100 YCbCr 10: BT.2020 constant luminance 11: SMPTE ST 2085 YDzDx 12: Chromaticity-derived non-constant luminance 13: Chromaticity-derived constant luminance 14: BT.2100 ICtCp |
--matrix-coefficients | |
| WZAV1E_SET_CHROMA_SAMPLE_POSITION | [0-2] | 0 | Chroma sample positions: 0: Unknown 1: Horizontally co-located with luma (0,0) sample, between two vertical samples 2: Co-located with luma (0,0) sample |
--chroma-sample-position | |
| WZAV1E_SET_TIMING_INFO_TYPE | [0-2] | 0 | Signal timing info in the bitstream: 0: Unspecified 1: equal 2: decoder model |
--timing-info | |
| WZAV1E_SET_ENABLE_TX_SIZE_SEARCH | [0,1] | 1 | Enable transform size search to find the best size for each block (0: disabled; transforms always use the largest possible size, 1: enabled (default)) | --enable-tx-size-search |
Set by wz_codec_set_option(wz_codec_ctx_t *ctx, const char *name, const char *value)
| Property Name | Range | Default | Recommend Setting | Description | Sample app command line options |
|---|---|---|---|---|---|
| tile-columns | [0-6] | 0 | 1 (2 tile columns) for better MT efficiency | Number of tile columns to use, in log2 units. The number of tile columns (not in log2 units) is returned by wz_codec_get_option() |
--tile-columns |
| tile-rows | [0-6] | 0 | 0 | Number of tile rows to use, in log2 units. The number of tile rows (not in log2 units) is returned by wz_codec_get_option() |
--tile-rows |
| enable-tpl-model | [0,1] | 1 | RDO based on frame temporal dependency (0: off, 1: backward source based). This is required for deltaq mode. | --enable-tpl-model | |
| arnr-maxframes | [0-15] | 7 | Set to 0 to disable Temporal Filter for grain preservation | The max number of frames to create arf frame (0..15). | --arnr-maxframes |
| enable-cdef | [0,1] | 1 | Set to 0 for grain preservation | Enable the constrained directional enhancement filter (0: false, 1: true (default), 2: disable for non-reference frames) | --enable-cdef |
| enable-restoration | [0,1] | 1 | Set to 0 for grain preservation | Enable the loop restoration filter (0: false, 1: true) | --enable-restoration |
| enable-tx64 | [0,1] | 1 | Set to 0 for grain preservation | Enable 64-pt transform (0: false, 1: true) | --enable-tx64 |
| sb-size | [64,128,dynamic] | dynamic | 64 for 1080p or lower resolution content; 128 for 4k content. | Superblock size to use (dynamic: super block size is decided by encoder, 64: superblock size is 64x64, 128: superblock size is 128x128) | --sb-size |
| min-gf-interval | [0,4,8,16,32] | 0 | Min gf/arf frame interval, valid values (0,4,8,16,32), default is 0, indicating in-built behavior | --min-gf-interval | |
| max-gf-interval | [0,4,8,16,32] | 0 | 16 for VOD | Max gf/arf frame interval, valid values (0,4,8,16,32), default is 0, indicating in-built behavior | --max-gf-interval |
| target-seq-level-idx | 31 | Target sequence level index. Possible values are in the form of "ABxy". AB: Operating point (OP) index, xy: Target level index for the OP. E.g. "0" means target level index 0 (2.0) for the 0th OP, "1019" means target level index 19 (6.3) for the 10th OP. | --target-seq-level-idx | ||
| set-tier-mask | [0-(2^32)-1] | 0 | 0 | Set bit mask to specify which tier each of the 32 possible operating points conforms to. Bit value 0(default): Main Tier, 1: High Tier. | --set-tier-mask |
| enable-vbv | [0,1] | 0 | 1 | Take vbv buffer level into account for vbr and crf modes | --enable-vbv |
| psy-rd | [0-100] | 0 | Set to 15 for grain preservation | Psychovisually rate-distortion optimization | --psy-rd |
| psy-rdoq | [0-100] | 0 | Set to 10 for grain preservation | Strength of psy optimization in coefficient quantization | --psy-rdoq |
| max-lps | [0, core count of the machine] | 0 | Maximum logical processors to be used, default 0, mean all available logical processors | --max-lps | |
| chroma-delta-q | [-64 - 63] | 0 | Chroma-delta-q adjustment | --chroma-delta-q | |
| deltaq-mode | [0-3] | 1 | Delta qindex mode (0: off, 1: deltaq objective (default), 2: deltaq perceptual, 3: deltaq HDR perceptual) | --deltaq-mode | |
| deltaq-strength | [0-100] | 50,50 | Specified as comma-separated list of 2 int for deltaq strength in DELTA_Q_PERCEPTUAL mode. The strengths are for aggressiveness of perceptual quality | --deltaq-strength | |
| enable-dlf | [0,1] | 1 | Enable the loop deblocking filter (0: false, 1: true) | --enable-dlf | |
| hdr-boost | [0,1] | 0 | Enhance perceptual optimization, default is 0. Should not be used with chroma-delta-q | --hdr-boost | |
| hdr10-opt | [0,1] | 0 | Only signal hdr10 data when data changes | --hdr10-opt | |
| enable-tpl-scale | [-1-2] | -1 | Enable tpl model downscaling (-1: auto, 0: disable, 1: enable when resolution is 720p or larger, 2: enable for all resolutions | --enable-tpl-scale | |
| rc-model | [0,1] | 0 | Select the rate control model to use. (0: legacy model (default), 1: new model) | --rc-model | |
| enable-overlay | [0,1] | 0 | 1 for improved subjective quality | Enable coding overlay frames (0: false, 1: true) | --enable-overlay |
| tune-content | 0 / default, 3 / grain, 6 / auto | 0 | 6 (auto) for both normal and grain preservation | Optimizes encoding based on content characteristics. | --tune-content |
| color-primaries | [1,2,4-12,22] | 2 | CICP color primaries: 1: BT.709 2: Unspecified 4: BT.470 System M (historical) 5: BT.470 System B, G (historical) 6: BT.601 7: SMPTE 240 8: Generic film (color filters using illuminant C) 9: BT.2020, BT.2100 10: SMPTE 428 (CIE 1921 XYZ) 11: SMPTE RP 431-2 12: SMPTE EG 432-1 22: EBU Tech. 3213-E |
--color-primaries | |
| transfer-characteristics | [1,2,4-18] | 2 | CICP transfer characteristics: 1: BT.709 2: Unspecified 4: BT.470 System M (historical) 5: BT.470 System B, G (historical) 6: BT.601 7: SMPTE 240 M 8: Linear 9: Logarithmic (100:1 range) 10: Logarithmic (100 * Sqrt(10):1 range) 11: IEC 61966-2-4 12: BT.1361 13: sRGB or sYCC 14: BT.2020 10-bit systems 15: BT.2020 12-bit systems 16: SMPTE ST 2084, ITU BT.2100 PQ 17: SMPTE ST 428 18: BT.2100 HLG, ARIB STD-B67 |
--transfer-characteristics | |
| matrix-coefficients | [0-2,4-14] | 2 | CICP matrix coefficients: 0: Identity matrix 1: BT.709 2: Unspecified 4: US FCC 73.628 5: BT.470 System B, G (historical) 6: BT.601 7: SMPTE 240 M 8: YCgCo 9: BT.2020 non-constant luminance, BT.2100 YCbCr 10: BT.2020 constant luminance 11: SMPTE ST 2085 YDzDx 12: Chromaticity-derived non-constant luminance 13: Chromaticity-derived constant luminance 14: BT.2100 ICtCp |
--matrix-coefficients |