API Definitions

Visionular’s Aurora4 AVC encoder supports input of 8/10-bit YUV400/420/422/444 image/video and outputs a bitstream compliant with the AVC/H.264 standard.

The encoding interface is defined in the file aurora4enc.h.

For related integration examples, please refer to aurora4_sample_encoder.c.

Log Callback Function

WZ4_API void wz4_set_log_printf(void *encoder, wz4_log_printf_func log_cb);
  • Function: Log callback function.
  • Return Value: NULL.
  • Parameters:
    • encoder: A handle, can be a pointer to any structure;
    • log_cb: The function to print logs; if log_cb is NULL, the default printf will be used;

Get Encoder Version Information

WZ4_API extern const char *wz4_version_str(void);
  • Function: Get the encoder version information.
  • Return Value: A string representing the encoder version.
  • Parameters: NULL.

Generate Default Configuration Parameters

WZ4_API void wz4_encoder_config_default(wz4_enc_cfg_t *cfg);
  • Function: Initialize default configuration parameters.
  • Return Value: NULL.
  • Parameters:
    • cfg: A pointer to the encoder's basic configuration parameters.

Parse Pair of “name=value” Parameters

WZ4_API int32_t wz4_config_parse(wz4_enc_cfg_t *cfg, const char *name, const char *value);
  • Function: Parse name-value pair information and assign it to cfg;
  • Return Value: Error code, 0 indicates normal.
  • Parameters:
    • cfg: Pointer to basic configuration parameters for the encoder.
    • name: The name of the string configured by the user, e.g., "tune";
    • value: The value of the string configured by the user, e.g., "zerolatency,screen".

The following table lists the supported "name=value" pairs,

name DataType, {Value} Description
input-csp int, {1~24} Input image format, for setting range refer to wz4_input_csp_e.
frame-rate-num int Frame rate numerator
frame-rate-den int Frame rate denominator, default is 1
time-base-num int Time base numerator, default is 1
time-base-den int Time base denominator, time scale of pts
fps float Input frame rate
force-cfr int, {0~1} Force constant framerate, default is 1
pass int, {0~2} Multi pass rate control, 1: First pass - creates stats file, 2: Second pass.
stats string Filename (in UTF-8) of the 2pass stats file
dump-bs string Filename for dumping output info.
dump-src string Filename for dumping input info.
dump-rec string Filename for dumping reconstructed info.
bit-depth int, {8,10} Set specific bit depth
duration float Duration of the video by seconds
rc int, {-1~2} Rate control modes, -1: adaptive quality, 0: constant QP, 1: constant quality, 2: averaged bitrate
bitrate int, {0~2000000} Target bitrate in kbps
vbv-maxrate int, {0~2000000} Maximum average bitrate limit, in kbps
vbv-bufsize int, {0~2000000} Rate control buffer size, in kbits
crf float, {0~51} Quality parameter for constant quality rate control mode.
crf-max float, {0.1~51} Maximum quality parameter for constant quality rate control mode.
quality float, {0~51} Set the encoding quality
keyint int, >0 Maximum key frame interval
keyint-min int, >0 Minimum key frame interval
ipratio float, {0.1~2.0} QP ratio between I and P frames
pbratio float, {0.1~2.0} QP ratio between P and B frames
temp-svc int, {0~3} Temporal scalability
qp int, {0~51} Constant quantization parameter control mode quantization parameter, default is 30
qpmin int, {0~51} Minimum quantization parameter for frame-level, default is 0
qpmax int, {qpmin~51} Maximum quantization parameter for frame-level, default is 51
threads int Number of encoding threads
numa-mask string Specify NUMA nodes in binary format, where each bit represents one NUMA node
aq-mode int, {0~5} PSY adaptive QP mode, default is 2
repeat_headers int, {0~1} Put SPS/PPS before each key frame
cabac int, {0~1} Whether to enable cabac
annexb int, {0~1} 1: place start codes (4 bytes) before NAL units, 0: place size (4 bytes) before NAL units. Default is 1.
bframes int, {0~15} Number of B-frames between adjacent non-B-frames
rc-lookahead int, {0~65} Number of frames for lookahead analysis, affects latency frame count
open-gop int, {0~1} Whether to enable open GOP
intra-refresh int, {0~1} Not supported yet!
me int, {0~9} Full-pixel motion estimation method
subme int, {0~10} Sub-pixel motion estimation method
visual-opt int, {0~2} Set visual optimize option, 0: Not enabled; 1-2 use different algorithms
detail-opt int, {0~1} Maintain details, 0: Not enabled; 1: enabled.
sar string Should be set like Value1,Value2
vid-format string Support: "component", "pal", "ntsc", "secam", "mac", "undef"
full-range string Support: “off”, “on”
color-prim string Specify color primaries. Support: "bt709", "undef", "bt470m", "bt470bg", "smpte170m", "smpte240m", "film", "bt2020", "smpte428", "smpte431", "smpte432"
transfer string Specify transfer characteristics. Support: "bt709", "undef", "bt470m", "bt470bg", "smpte170m", "smpte240m", "linear", "log100", "log316", "iec61966-2-4", "bt1361e", "iec61966-2-1", "bt2020-10", "bt2020-12", "smpte2084", "smpte428", "arib-std-b67"
col-matrix string Support: "GBR", "bt709", "undef", "fcc", "bt470bg", "smpte170m", "smpte240m", "YCgCo", "bt2020nc", "bt2020c", "smpte2085", "chroma-derived-nc", "chroma-derived-c", "ICtCp"
chroma-loc int, {0~5} Chroma sample location
alternative-transfer string Specify an alternative transfer characteristics. Support: "bt709", "undef", "bt470m", "bt470bg", "smpte170m", "smpte240m", "linear", "log100", "log316", "iec61966-2-4", "bt1361e", "iec61966-2-1", "bt2020-10", "bt2020-12", "smpte2084", "smpte428", "arib-std-b67"
master-display string Specify 'G(x,y)B(x,y)R(x,y)WP(x,y)L(max,min)' for primaries, white point, and display brightness. Should be set like G(Value1,Value2)B(Value3,Value4)R(Value5,Value6)WP(Value7,Value8)L(Value9,Value10)
max-cll string Specify 'max_content,max_frame_average' content light levels. Should be set like Value1,Value2
ave string Should be set like Value1,Value2,Value3
aud int, {0~1} Access unit delimiters
psnr int, {0~2} Calculate PSNR metrics, 0: Not enabled (default); 1: print sequence level PSNR values; 2: print frame level PSNR values.
ssim int, {0~2} Calculate SSIM metrics, 0: Not enabled (default); 1: print sequence level SSIM values; 2: print frame level SSIM values.
log int, {-1,3} Output log level, -1: debug; 0: info; 1: warn; 2: err; 3: fatal. Default is 0.

Validate Configuration Parameters

WZ4_API int32_t wz4_config_validate(const wz4_enc_cfg_t *base_cfg, const char *extra_cfg);
  • Function: Validates the configuration content for the encoder.
  • Return Value: WZ_OK on successful validation, or an error code indicating the type of error.
  • Parameters:
  • base_cfg: A pointer to the encoder's basic configuration parameters;
  • extra_cfg: A pointer to the encoder's extra configuration parameters, which can be set using the format "key=value"; if multiple parameters need to be set, they can be concatenated using ":", for example, "key0=val0:key1=val1";
  • Notes:
  • Users may call this function proactively before invoking wz4_encoder_open. If not called, wz4_encoder_open will automatically validate the configuration before creating the encoder instance.
  • For fatal errors, the encoder cannot recover and will return a value not equal to WZ_OK, logging the reason in the error-level log.
  • For non-fatal errors, the encoder will attempt recovery and return WZ_OK, logging the reason in the warn-level log.

Create Encoder

WZ4_API void *wz4_encoder_open(const wz4_enc_cfg_t *cfg, const char *extra_cfg, int32_t *error_code);
  • Function: Creates an encoder instance.
  • Return Value: Pointer to the encoder instance.

  • Parameters:

    • cfg: A pointer to the encoder's basic configuration parameters;
    • extra_cfg: A pointer to the encoder's extra configuration parameters, which can be set using the format "key=value"; if multiple parameters need to be set, they can be concatenated using ":", for example, "key0=val0:key1=val1";
    • error_code: A pointer to the error code address.

  • Note: Before calling this interface, the incoming cfg must first be filled with default values using wz4_encoder_config_default, and then some parameters can be configured as needed. If an error occurs when creating the encoder, the corresponding Error code will be returned.

Destroy Encoder

WZ4_API int32_t wz4_encoder_close(void *encoder);
  • Function: Destroy an encoder instance.
  • Return Value: Error code, 0 indicates normal.
  • Parameters:
    • encoder: A pointer to the encoder instance.

Dynamically Update Encoder Configuration Parameters

WZ4_API int32_t wz4_encoder_update_config(void *encoder, wz4_enc_cfg_t *cfg);
  • Function: Adjust some parameters of the encoder during the encoding process.
  • Return Value: Error code.
  • Parameters:
    • encoder: A pointer to the encoder instance;
    • cfg: A pointer to the encoder's basic configuration parameters.

Get Encode Parameter Sets (SPS, PPS, etc. headers)

WZ4_API int32_t wz4_encoder_headers(void *encoder, wz4_nal_t **nals, int32_t *nal_count);
  • Function: Returns the SPS and PPS information of the video stream.
  • Return Value: Error code.
  • Parameters:
    • encoder: A pointer to the encoder instance.
    • nals: A pointer to the generated NAL units; nals[i] represents a pointer to the i-th NAL unit.
    • nal_count: The number of NAL units generated by encoding.

Get Encode AVCC headers

c WZ4_API int32_t wz4_encoder_avcc_headers(void *encoder, uint8_t **avcc_buffer); - Function: Returns the AVCDecoderConfigurationRecord (ISO/IEC 14496-15) containing the SPS and PPS for the entire stream when cfg.annexb=0. - Return Value: The number of bytes in the returned buffer. A negative value indicates an error. - Parameters: - encoder: A pointer to the encoder instance. - avcc_buffer: An internal buffer that should not be freed by the user. The user must copy the data to their own buffer before calling any other API. - Notes: - This function provides the SPS and PPS information that will be used for the whole stream. - The returned buffer is internal and should be copied by the user before performing any other actions.

Encode a Frame of Image

WZ4_API int32_t wz4_encoder_encode_frame(void *encoder, wz4_nal_t **nals, int32_t *nal_count,
                                 wz4_picture_t *pic_in, wz4_picture_t *pic_out);
  • Function: Encodes one frame of image.
  • Return Value: Error code.
  • Parameters:
    • encoder: A pointer to the encoder instance.
    • nals: A pointer to the generated NAL units; nals[i] represents a pointer to the i-th NAL unit.
    • nal_count: The number of NAL units generated by encoding.
    • pic_in: A pointer to the incoming image; it is not synchronized with output nals, and when pic_in is NULL, it indicates that there is still unsent data in the cache.
    • pic_out: A pointer to the outgoing image; it serves as auxiliary information for output nals, synchronized with output nals. This parameter is for reference only and does not affect normal encoding.

Query the Number of Delayed Frames

WZ4_API int32_t wz4_encoder_delayed_frames(void *encoder);
  • Function: Query the number of frames delayed and not yet encoded by the encoder; used only when the sequence ends. If the return value is greater than 0, it indicates that there are still delayed frames that have not been completed; you need to continue calling wz4_encoder_encode_frame until all frames are encoded.
  • Return Value: Number of delayed frames. 0 indicates all frames have been encoded.
  • Parameters:
    • encoder: A pointer to the encoder instance.