libavif — PPM Packages

libavif clib

AVIF image codec for PascalAI. Encode and decode AV1-based AVIF images — the next-generation format that beats JPEG by ~50% file size at equal quality, with full alpha channel, HDR, and wide color gamut support. Open and royalty-free.

Version1.0.0

Typeclib

System reqlibavif-dev

CategoryMultimedia

ppm install libavif

CLib package — system library required

Ubuntu/Debian: sudo apt install libavif-dev • Fedora: sudo dnf install libavif-devel • macOS: brew install libavif

Quick Start

uses libavif;

{ Decode AVIF to raw RGBA pixels }
var w, h: Integer;
var rgba := DecodeFile('/images/photo.avif', w, h);
WriteLn('Decoded: ' + IntToStr(w) + 'x' + IntToStr(h));

{ Re-encode from RGBA at quality 75, speed 6 }
EncodeFile(rgba, w, h, '/output/photo.avif', 75, 6);

uses libavif;

{ Batch convert JPEG to AVIF }
var files := ['a.jpg', 'b.jpg', 'c.jpg'];
for var f in files do
begin
  var avifPath := ChangeFileExt(f, '.avif');
  JPEGToAVIF(f, avifPath, 75);
  WriteLn(f + ' → ' + avifPath);
end;

Decode API

All decode functions return raw RGBA pixel data as a byte array. Width and height are returned via var parameters.

Function	Description
DecodeFile(path, var w, var h)	Decode AVIF file to RGBA byte array. Sets `w` and `h`.
Decode(data, var w, var h)	Decode AVIF from in-memory byte array.
DecodeRGB(path, var w, var h)	Decode to RGB (no alpha channel, 3 bytes/pixel).
DecodeToFloat(path, var w, var h)	Decode HDR content to 32-bit float RGBA (0.0..1.0 per channel).
DecodeResized(path, targetW, targetH)	Decode and resize in a single pass. Returns RGBA bytes.
ReadInfo(path)	Returns `TAvifInfo` without decoding pixels.

uses libavif;

{ Read metadata without decoding }
var info := ReadInfo('/images/photo.avif');
WriteLn('Size:     ' + IntToStr(info.Width) + 'x' + IntToStr(info.Height));
WriteLn('Depth:    ' + IntToStr(info.BitDepth) + ' bits');
WriteLn('Alpha:    ' + BoolToStr(info.HasAlpha));
WriteLn('HDR:      ' + BoolToStr(info.IsHDR));
WriteLn('YUV:      ' + info.YUVFormat);   { 'YUV420', 'YUV444', ... }

Encode API

The encoder accepts raw RGBA pixels plus a TAvifEncodeOptions record for fine control, or use the simplified overloads with quality and speed integers directly.

Function	Description
EncodeFile(rgba, w, h, path, quality, speed)	Encode RGBA buffer to AVIF file. Quality 0..100, speed 0 (slowest/best) ..10 (fastest).
Encode(rgba, w, h, quality, speed)	Encode to in-memory byte array.
EncodeEx(rgba, w, h, opts)	Encode with full `TAvifEncodeOptions` control.
EncodeLossless(rgba, w, h, path)	Lossless encode (quality=100). Larger files but pixel-perfect.
EncodeHDR(floatRgba, w, h, path, bitDepth)	Encode HDR float buffer. `bitDepth` = 10 or 12.

TAvifEncodeOptions fields

Field	Type	Description
Quality	Integer	0..100. 100 = lossless, 60–80 = high-quality lossy. Default: 60.
QualityAlpha	Integer	Alpha channel quality, 0..100. Default: 100 (lossless alpha).
Speed	Integer	0 (slowest, smallest) .. 10 (fastest, larger). Default: 6.
BitDepth	Integer	8, 10, or 12. Use 10/12 for HDR. Default: 8.
YUVFormat	String	'YUV420' (default), 'YUV422', 'YUV444' (best chroma).
Codec	String	'aom' (best quality) or 'svt' (much faster encode). Default: 'aom'.
Threads	Integer	Encoder threads. 0 = auto-detect CPU cores.
ExifData	Bytes	Raw EXIF bytes to embed. Pass empty array to skip.
ICCProfile	Bytes	ICC profile bytes for wide color gamut / HDR metadata.

uses libavif;

var w, h: Integer;
var rgba := DecodeFile('/photos/raw.png', w, h);  { any RGBA source }

{ High quality, keep lossless alpha, fast encode }
var opts: TAvifEncodeOptions;
opts.Quality      := 72;
opts.QualityAlpha := 100;
opts.Speed        := 4;
opts.YUVFormat    := 'YUV444';
opts.Codec        := 'aom';
opts.Threads      := 0;  { auto }

EncodeEx(rgba, w, h, opts, '/output/photo.avif');

Conversion Helpers API

One-call helpers that read a source image format and write AVIF without handling raw pixels manually.

Function	Description
JPEGToAVIF(srcPath, dstPath, quality)	Convert JPEG file to AVIF lossy.
PNGToAVIF(srcPath, dstPath, quality)	Convert PNG to AVIF. Alpha channel preserved.
WebPToAVIF(srcPath, dstPath, quality)	Convert WebP to AVIF.
TIFFToAVIF(srcPath, dstPath, quality)	Convert TIFF (including 16-bit) to AVIF.
AVIFToJPEG(srcPath, dstPath, quality)	Decode AVIF, re-encode as JPEG.
AVIFToPNG(srcPath, dstPath)	Decode AVIF, save as PNG (lossless round-trip).
BatchConvert(srcDir, dstDir, quality)	Convert all JPEG/PNG files in `srcDir` to AVIF, writing to `dstDir`.

Metadata API

Function	Description
GetEXIF(path)	Extract embedded EXIF bytes from AVIF container.
GetXMP(path)	Extract embedded XMP metadata bytes.
GetICCProfile(path)	Extract ICC color profile bytes.
StripMetadata(srcPath, dstPath)	Copy AVIF, removing all EXIF/XMP/ICC. Useful for privacy.
CopyMetadata(srcPath, dstPath)	Copy EXIF+XMP+ICC from `srcPath` into an existing `dstPath`.
AVIFVersion()	Returns libavif version string.

TAvifInfo Record

Field	Type	Description
Width	Integer	Image width in pixels.
Height	Integer	Image height in pixels.
BitDepth	Integer	Bit depth per channel: 8, 10, or 12.
HasAlpha	Boolean	True if the image has an alpha channel.
IsHDR	Boolean	True if BitDepth > 8 and transfer characteristics indicate HDR.
YUVFormat	String	Chroma subsampling: 'YUV420', 'YUV422', 'YUV444', or 'MONO'.
ColorPrimaries	Integer	CICP color primaries code (1=BT.709/sRGB, 9=BT.2020).
TransferChar	Integer	Transfer characteristics (1=BT.709, 16=PQ/HDR10, 18=HLG).
FileSize	Integer	File size in bytes.

Quality Guide

AVIF quality uses the same 0–100 scale as JPEG, but produces much smaller files at the same perceptual quality.

Quality	Use case	Typical size vs JPEG
100	Lossless (pixel-perfect archiving)	~10–30% larger than PNG
80–90	Near-lossless, professional photos	~60% smaller than JPEG
60–80	High-quality web photos	~50% smaller than JPEG
40–60	General web delivery, thumbnails	~40% smaller than JPEG
<40	Very small files, lower fidelity	~30% smaller than JPEG

Speed vs quality tradeoff

Speed 0–3 produces the smallest files but can take minutes on high-resolution images. Speed 6 (default) is a good balance. Speed 8–10 is suitable for live encoding but sacrifices ~10% compression efficiency. Use Codec='svt' for dramatically faster encoding at the cost of slightly larger files.

AVIF vs JPEG vs WebP vs HEIF

Feature	AVIF	JPEG	WebP	HEIF
Compression (lossy)	Best	Baseline	~30% better	~45% better
Alpha channel	Yes	No	Yes	Yes
HDR / 10-bit	Yes	No	No	Yes
Wide color gamut	Yes	Limited	Limited	Yes
Lossless mode	Yes	No	Yes	Yes
Royalty-free	Yes	Yes	Yes	No (HEVC)
Browser support	All modern	Universal	All modern	Safari only
Encode speed	Slow (aom) / Fast (svt)	Fast	Medium	Medium