Classes

This section describes the classes and structures provided by the ConvAvif library.

Core Classes

EncodeConfig

struct EncodeConfig

Main configuration structure for AVIF encoding.

This structure contains all the parameters that control the AVIF encoding process, including quality settings, codec choice, and various encoder-specific parameters.

Public Functions

inline void setQuality(int q)

Set the quality value with validation.

Parameters:: q – New quality value

inline void setMinQuantizer(int q)

Set the minimum quantizer value with validation.

Parameters:: q – New minimum quantizer value

inline void setMaxQuantizer(int q)

Set the maximum quantizer value with validation.

Parameters:: q – New maximum quantizer value

inline void setTileRowsLog2(int t)

Set the tile rows log2 value with validation.

Parameters:: t – New tile rows log2 value

inline void setTileColsLog2(int t)

Set the tile columns log2 value with validation.

Parameters:: t – New tile columns log2 value

inline void setSharpness(int s)

Set the sharpness value with validation.

Parameters:: s – New sharpness value

inline int getQuality() const

Get the current quality value.

Returns:: Current quality value

inline int getMinQuantizer() const

Get the current minimum quantizer value.

Returns:: Current minimum quantizer value

inline int getMaxQuantizer() const

Get the current maximum quantizer value.

Returns:: Current maximum quantizer value

inline int getTileRowsLog2() const

Get the current tile rows log2 value.

Returns:: Current tile rows log2 value

inline int getTileColsLog2() const

Get the current tile columns log2 value.

Returns:: Current tile columns log2 value

inline int getSharpness() const

Get the current sharpness value.

Returns:: Current sharpness value

inline int getSpeed() const

Get the current speed value.

Returns:: Current speed value

inline void setPreset(SpeedPreset newPreset)

Set a new speed preset and update speed settings.

Parameters:: newPreset – New speed preset

inline SpeedPreset getPreset() const

Get the current speed preset.

Returns:: Current speed preset

inline void updateSpeed(int new_speed, SpeedPreset newPreset)

Update speed settings with new values.

Parameters:

new_speed – New speed value
newPreset – New speed preset

inline CodecChoice getCodecChoice() const

Get the current codec choice.

Returns:: Current codec choice

inline void setCodecChoice(CodecChoice choice)

Set a new codec choice and update speed settings.

Parameters:: choice – New codec choice

inline void printConfig() const

Print the current configuration to stdout.

Useful for debugging and logging purposes

Public Members

int quality = 30: Quality value (0-100, higher is better quality)

int qualityAlpha = -1: Alpha channel quality (-1 means use quality value)

int sharpness = 0: Sharpness filter strength (0-7)

avifPixelFormat pixelFormat = AVIF_PIXEL_FORMAT_YUV420: YUV pixel format.

CodecChoice codecChoice: Selected codec (AOM, SVT, AUTO)

SpeedPreset preset: Speed preset.

int minQuantizer = -1: Minimum quantizer (0-63, -1 for default)

int maxQuantizer = -1: Maximum quantizer (0-63, -1 for default)

int tileRowsLog2 = 0: Log2 of tile rows (0 = 1 tile row, 1 = 2 rows, etc)

int tileColsLog2 = 0: Log2 of tile columns.

Tune tune = Tune::TUNE_DEFAULT : Encoder tuning option.

ImageGuru

class ImageGuru

Utility class for image format detection and support checking.

This class provides static methods to detect image formats from binary data and check whether specific formats are supported for conversion to AVIF.

Public Static Functions

static inline ImageType GetImageType(const std::vector<uint8_t> &data)

Detect the image format from binary data.

Examines the file header/magic bytes in the provided data to determine the image format.

Parameters:: data – Binary image data to analyze
Returns:: Detected ImageType, or ImageType::UNKNOWN if format isn’t recognized

static inline bool IsValid(const std::vector<uint8_t> &data)

Check if binary data appears to be a valid image.

Parameters:: data – Binary data to check
Returns:: true if the data appears to be a recognized image format, false otherwise

static inline bool IsSpecificType(const std::vector<uint8_t> &data, ImageType type)

Check if binary data matches a specific image format.

Parameters:

data – Binary data to check
type – Specific ImageType to check for

Returns:

true if the data matches the specified format, false otherwise

static inline bool isSupported(const ImageType type)

Check if a specific image type is supported for conversion.

Parameters:: type – The ImageType to check support for
Returns:: true if the format is supported for conversion, false otherwise

static inline std::string typeToString(const ImageType type)

Convert an ImageType enum to a string representation.

Parameters:: type – The ImageType to convert
Returns:: String representation of the image type

struct imageSupport

Structure for tracking image format support status.

Public Members

ImageType type: Type of image format.

bool supported: Whether conversion is supported.

Error

class Error

Error class for reporting conversion errors.

This class encapsulates an error code, a descriptive message, and optional stack trace information for debugging.

Public Functions

Error(ConverterError c, const std::string &msg, const std::string &trace = "")

Constructor for Error objects.

Parameters:

c – Error code identifying the error type
msg – Human-readable error message
trace – Optional function name or call stack information

Public Members

ConverterError code: Error code identifying the error type.

std::string message: Human-readable error message.

std::string stackTrace: Function call stack or context information.

Speed

struct Speed

Speed settings manager for AVIF encoding.

This class manages speed settings based on the selected codec and preset. Different codecs have different optimal speed ranges for various quality/speed tradeoffs.

Public Functions

inline Speed(CodecChoice codec, SpeedPreset preset)

Constructor that sets appropriate speed ranges based on codec and preset.

Parameters:

codec – The selected codec (AOM, SVT, AUTO)
preset – The desired speed preset (Good, MemoryHungry, RealTime)

inline int getDefault() const

Get the default speed value.

Returns:: Current default speed value

inline void setSpeedRange(const SpeedRange &range)

Set a new speed range.

Parameters:: range – New speed range to use

inline SpeedRange getRange() const

Get the current speed range.

Returns:: Current speed range

inline bool isValid(int speed)

Check if a speed value is within the valid range.

Parameters:: speed – Speed value to check
Returns:: true if speed is valid, false otherwise

inline SpeedPreset getPreset() const

Get the current speed preset.

Returns:: Current SpeedPreset value

inline void set(int ns)

Set a new speed value if it’s valid.

Parameters:: ns – New speed value to set

Public Members

SpeedPreset preset_ = SpeedPreset::Good : Current speed preset.

int default_speed = 5: Default speed value.

SpeedRange speed_range = {5, 6}: Valid speed range.

SpeedRange

struct SpeedRange

Structure to define the range of valid speed values.

Public Members

int min: Minimum valid speed value.

int max: Maximum valid speed value.

ImageBuffer

class ImageBuffer

Container class for image binary data.

This class encapsulates a vector of bytes representing image data and provides methods to access this data from both C++ and JavaScript.

Public Functions

inline ImageBuffer(std::vector<uint8_t> data)

Constructor that takes ownership of image data.

Parameters:: data – Vector containing the binary image data (typically AVIF encoded)

inline emscripten::val getData() const

Get the image data as a JavaScript typed array.

Note

This creates a view into the existing memory without copying

Returns:: JavaScript typed array (Uint8Array) view of the image data

inline size_t getSize() const

Get the size of the image data in bytes.

Returns:: Size of the image data in bytes

inline const std::vector<uint8_t> &getRawData() const

Get direct access to the underlying data vector.

Returns:: Const reference to the underlying byte vector

Enumerations

CodecChoice

enum class CodecChoice

Codecs available for AVIF encoding.

Values:

enumerator AUTO

enumerator AOM

enumerator SVT

Tune

enum class Tune

Tuning options for the encoder.

Values:

enumerator TUNE_DEFAULT

enumerator TUNE_PSNR

enumerator TUNE_SSIM

SpeedPreset

enum class SpeedPreset : int

Speed presets for encoding with different performance/quality tradeoffs.

Values:

enumerator Good

enumerator MemoryHungry

enumerator RealTime

ConverterError

enum class ConverterError

Error codes for the image converter.

These error codes identify different failure modes in the conversion process. Error codes 100-199 are specific to the converter, while codes 200+ are mapped from the AVIF library.

Values:

enumerator OK: No error, operation successful.

enumerator INVALID_DIMENSIONS: Image dimensions are invalid (too small/large)

enumerator UNSUPPORTED_IMAGETYPE: Image format is not supported.

enumerator IMAGE_LOAD_FAILED: Failed to load/decode the input image.

enumerator ENCODER_CREATION_FAILED: Failed to create the AVIF encoder.

enumerator CONVERSION_FAILED: Failed during the RGB to YUV conversion.

enumerator ENCODING_FAILED: Failed during the encoding process.

enumerator INVALID_ARGUMENT: Invalid argument provided to a function.

enumerator OUT_OF_MEMORY: Memory allocation failed.

enumerator INVALID_QUANTIZER_VALUES: Invalid quantizer values (e.g., min > max)

enumerator UNKNOWN_ERROR: Unspecified error.

enumerator AVIF_ERROR_START: Start of error codes mapped from avifResult.