feat: Add support to decode animated AVIF

Author: vegidio

README.md

@@ -1,13 +1,14 @@
 # avif-go
 
-A Go library and CLI tool to encode/decode AVIF images without system dependencies (CGO).
+A Go library & CLI tool to encode/decode static and animated AVIF without external dependencies.
 
 ## 💡 Motivation
 
 There are a couple of libraries to encode/decode AVIF images in Go, and even though they do the job well, they have some limitations that don't satisfy my needs:
 
 - They need dependencies to be installed on the system to either build the app or later execute it.
 - They rely on a WASM runtime - which is actually a really smart idea! - but it has a big impact on performance.
+- There's currently no Go library capable of encoding animated AVIFs; this library aims to fill that gap.
 
 **avif-go** uses CGO to create a static implementation of AVIF, so you don't need `libavif` (or any of its sub-dependencies) installed to build or run your Go application.
 
@@ -51,8 +52,8 @@ err = avif.Encode(avifFile, originalImage, nil) // encode the image & save it to
 
 ```go
 var frames []image.Image = ... // a slice of image.Image frames
-avifFile, err := os.Create("/path/to/animation.avif") // create the file to save the animated AVIF
-a := &avif.AVIF{Image: frames, Delay: []int{10, 10, 10}, LoopCount: 0} // 100ms per frame, loop forever
+avifFile, err := os.Create("/path/to/animation.avif") // create file to save the animation
+a := &avif.AVIF{Image: frames, Delay: []int{10, 10, 10}, LoopCount: 0} // anim configuration
 err = avif.EncodeAll(avifFile, a, nil) // encode the animation & save it to the file
 ```
 
@@ -64,6 +65,16 @@ avifFile, err := os.Open("/path/to/image.avif") // open the AVIF file to be deco
 avifImage, _, err := image.Decode(avifFile) // decode the image
 ```
 
+#### Decoding Animation
+
+```go
+avifFile, err := os.Open("/path/to/animation.avif") // open the animated AVIF file
+a, err := avif.DecodeAll(avifFile) // decode all frames
+// a.Image contains the frames, a.Delay the timing, a.LoopCount the loop behavior
+```
+
+For more examples on how to use this library, you can check the [cmd/](cmd) directory.
+
 ### CLI
 
 If you want to decode an AVIF image, run the following command:

assets/image.avif

@@ -10,43 +10,10 @@ const char* get_error_string(avifResult result) {
     return avifResultToString(result);
 }
 
-// Full decode: creates a decoder, sets up the memory I/O, and decodes the image.
-// Returns the avifImage pointer (which contains width, height, etc.) and leaves the
-// decoder pointer for cleanup. Returns error result via outResult.
-avifImage* decode_avif_image(const uint8_t * data, size_t size, avifDecoder ** outDecoder, avifResult *outResult) {
-    avifDecoder* decoder = avifDecoderCreate();
-    // Force libavif to use the dav1d backend.
-    decoder->codecChoice = AVIF_CODEC_CHOICE_DAV1D;
-
-    *outResult = avifDecoderSetIOMemory(decoder, data, size);
-    if (*outResult != AVIF_RESULT_OK) {
-        avifDecoderDestroy(decoder);
-        return NULL;
-    }
-
-    *outResult = avifDecoderParse(decoder);
-    if (*outResult != AVIF_RESULT_OK) {
-        avifDecoderDestroy(decoder);
-        return NULL;
-    }
-
-    *outResult = avifDecoderNextImage(decoder);
-    if (*outResult != AVIF_RESULT_OK) {
-        avifDecoderDestroy(decoder);
-        return NULL;
-    }
-
-    if (outDecoder) {
-        *outDecoder = decoder;
-    }
-    return decoder->image;
-}
-
 // Config-only decode: reads the header and returns width and height.
 // Returns error result via outResult.
 void get_avif_config(const uint8_t * data, size_t size, uint32_t * width, uint32_t * height, avifResult *outResult) {
     avifDecoder* decoder = avifDecoderCreate();
-    // Force libavif to use the dav1d backend.
     decoder->codecChoice = AVIF_CODEC_CHOICE_DAV1D;
 
     *outResult = avifDecoderSetIOMemory(decoder, data, size);
@@ -321,51 +288,101 @@ func createAVIFTile(pixels []byte, width, height, stride, col, row int) (*C.avif
 	return avifImage, nil
 }
 
-// decodeAVIFToRGBA decodes AVIF image data to an RGBA image.
+// decodeAVIFToRGBA decodes the first frame of AVIF image data to an RGBA image.
 func decodeAVIFToRGBA(data []byte) (*image.RGBA, error) {
+	frames, _, _, err := decodeAllAVIFToRGBA(data)
+	if err != nil {
+		return nil, err
+	}
+	return frames[0], nil
+}
+
+// decodeAllAVIFToRGBA decodes all frames from an AVIF image sequence.
+// Returns the frames as RGBA images, delays in centiseconds, and the repetition count.
+func decodeAllAVIFToRGBA(data []byte) ([]*image.RGBA, []int, int, error) {
 	if len(data) == 0 {
-		return nil, fmt.Errorf("cannot decode empty data")
+		return nil, nil, 0, fmt.Errorf("cannot decode empty data")
 	}
 
-	// Allocate C memory and copy data.
 	cData := C.CBytes(data)
 	defer C.free(cData)
 
-	var decoder *C.avifDecoder
-	var result C.avifResult
-	avifImg := C.decode_avif_image((*C.uint8_t)(cData), C.size_t(len(data)), &decoder, &result)
-	if avifImg == nil {
-		errStr := C.GoString(C.get_error_string(result))
-		return nil, fmt.Errorf("failed to decode AVIF image: %s", errStr)
+	// Create and configure decoder
+	decoder := C.avifDecoderCreate()
+	if decoder == nil {
+		return nil, nil, 0, fmt.Errorf("failed to create AVIF decoder")
 	}
 	defer C.avifDecoderDestroy(decoder)
 
-	// Set up an avifRGBImage struct to hold the converted image.
+	decoder.codecChoice = C.AVIF_CODEC_CHOICE_DAV1D
+
+	result := C.avifDecoderSetIOMemory(decoder, (*C.uint8_t)(cData), C.size_t(len(data)))
+	if result != C.AVIF_RESULT_OK {
+		errStr := C.GoString(C.get_error_string(result))
+		return nil, nil, 0, fmt.Errorf("failed to set decoder I/O: %s", errStr)
+	}
+
+	result = C.avifDecoderParse(decoder)
+	if result != C.AVIF_RESULT_OK {
+		errStr := C.GoString(C.get_error_string(result))
+		return nil, nil, 0, fmt.Errorf("failed to parse AVIF: %s", errStr)
+	}
+
+	frameCount := int(decoder.imageCount)
+	repetitionCount := int(decoder.repetitionCount)
+
+	frames := make([]*image.RGBA, 0, frameCount)
+	delays := make([]int, 0, frameCount)
+
+	for i := 0; i < frameCount; i++ {
+		result = C.avifDecoderNextImage(decoder)
+		if result != C.AVIF_RESULT_OK {
+			errStr := C.GoString(C.get_error_string(result))
+			return nil, nil, 0, fmt.Errorf("failed to decode frame %d: %s", i, errStr)
+		}
+
+		img, err := avifImageToRGBA(decoder.image)
+		if err != nil {
+			return nil, nil, 0, fmt.Errorf("frame %d: %w", i, err)
+		}
+		frames = append(frames, img)
+
+		// Get frame timing and convert to centiseconds
+		var timing C.avifImageTiming
+		C.avifDecoderNthImageTiming(decoder, C.uint32_t(i), &timing)
+		delay := 0
+		if timing.timescale > 0 {
+			delay = int(timing.durationInTimescales * 100 / timing.timescale)
+		}
+		delays = append(delays, delay)
+	}
+
+	return frames, delays, repetitionCount, nil
+}
+
+// avifImageToRGBA converts a C avifImage (YUV) to a Go image.RGBA.
+func avifImageToRGBA(avifImg *C.avifImage) (*image.RGBA, error) {
 	var rgb C.avifRGBImage
 	C.avifRGBImageSetDefaults(&rgb, avifImg)
 	rgb.format = C.AVIF_RGB_FORMAT_RGBA
-	rgb.depth = 8 // 8-bit per channel
+	rgb.depth = 8
 
-	// Allocate pixel buffer for the RGB data.
 	if C.avifRGBImageAllocatePixels(&rgb) != C.AVIF_RESULT_OK {
 		return nil, fmt.Errorf("failed to allocate RGB pixels")
 	}
 	defer C.avifRGBImageFreePixels(&rgb)
 
-	// Convert the image from YUV to RGB.
-	result = C.avifImageYUVToRGB(avifImg, &rgb)
+	result := C.avifImageYUVToRGB(avifImg, &rgb)
 	if result != C.AVIF_RESULT_OK {
 		errStr := C.GoString(C.get_error_string(result))
-		return nil, fmt.Errorf("failed to convert image to RGB: %s", errStr)
+		return nil, fmt.Errorf("failed to convert YUV to RGB: %s", errStr)
 	}
 
 	width := int(avifImg.width)
 	height := int(avifImg.height)
 	img := image.NewRGBA(image.Rect(0, 0, width, height))
 	rowBytes := int(rgb.rowBytes)
 
-	// Copy the pixel data row by row into the Go image using direct pointer access.
-	// This avoids the extra allocation from C.GoBytes for the entire buffer.
 	for y := 0; y < height; y++ {
 		srcPtr := unsafe.Add(unsafe.Pointer(rgb.pixels), y*rowBytes)
 		dstOffset := y * img.Stride

avif.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"image"
 	"image/color"
+	"image/color/palette"
 	"image/draw"
 	"image/gif"
 	"image/jpeg"
@@ -177,10 +178,10 @@ func decodeAvif(input, output string) (image.Image, os.FileInfo, error) {
 	if err != nil {
 		return nil, nil, err
 	}
-
 	defer inputFile.Close()
 
-	img, _, err := image.Decode(inputFile)
+	// Decode all frames from the AVIF
+	a, err := avif.DecodeAll(inputFile)
 	if err != nil {
 		return nil, nil, err
 	}
@@ -189,20 +190,40 @@ func decodeAvif(input, output string) (image.Image, os.FileInfo, error) {
 	if err != nil {
 		return nil, nil, err
 	}
-
 	defer outputFile.Close()
 
-	switch ext {
-	case ".bmp":
-		err = bmp.Encode(outputFile, img)
-	case ".gif":
-		err = gif.Encode(outputFile, img, nil)
-	case ".jpg", ".jpeg":
-		err = jpeg.Encode(outputFile, img, nil)
-	case ".png":
-		err = png.Encode(outputFile, img)
-	case ".tiff":
-		err = tiff.Encode(outputFile, img, nil)
+	// Animated AVIF → animated GIF
+	if ext == ".gif" && len(a.Image) > 1 {
+		g := &gif.GIF{
+			LoopCount: a.LoopCount,
+			Delay:     a.Delay,
+			Image:     make([]*image.Paletted, len(a.Image)),
+		}
+
+		for i, frame := range a.Image {
+			bounds := frame.Bounds()
+			paletted := image.NewPaletted(bounds, palette.Plan9)
+			draw.FloydSteinberg.Draw(paletted, bounds, frame, bounds.Min)
+			g.Image[i] = paletted
+		}
+
+		err = gif.EncodeAll(outputFile, g)
+	} else {
+		// Single frame or non-GIF output: use first frame
+		img := a.Image[0]
+
+		switch ext {
+		case ".bmp":
+			err = bmp.Encode(outputFile, img)
+		case ".gif":
+			err = gif.Encode(outputFile, img, nil)
+		case ".jpg", ".jpeg":
+			err = jpeg.Encode(outputFile, img, nil)
+		case ".png":
+			err = png.Encode(outputFile, img)
+		case ".tiff":
+			err = tiff.Encode(outputFile, img, nil)
+		}
 	}
 
 	if err != nil {
@@ -214,5 +235,5 @@ func decodeAvif(input, output string) (image.Image, os.FileInfo, error) {
 		return nil, nil, err
 	}
 
-	return img, info, nil
+	return a.Image[0], info, nil
 }

cmd/utils.go

@@ -27,6 +27,42 @@ func Decode(reader io.Reader) (image.Image, error) {
 	return decodeAVIFToRGBA(data)
 }
 
+// DecodeAll reads AVIF data from the provided io.Reader and decodes all frames into an AVIF struct.
+//
+// For still images, the returned AVIF struct will contain a single frame.
+// For image sequences (animations), it will contain all frames with their timing and loop information.
+func DecodeAll(reader io.Reader) (*AVIF, error) {
+	data, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode AVIF data: %w", err)
+	}
+
+	frames, delays, repetitionCount, err := decodeAllAVIFToRGBA(data)
+	if err != nil {
+		return nil, err
+	}
+
+	// Convert []*image.RGBA to []image.Image
+	images := make([]image.Image, len(frames))
+	for i, f := range frames {
+		images[i] = f
+	}
+
+	// Map AVIF repetitionCount to LoopCount (inverse of EncodeAll mapping)
+	loopCount := 0 // default: infinite
+	if repetitionCount == 0 {
+		loopCount = -1 // play once
+	} else if repetitionCount > 0 {
+		loopCount = repetitionCount
+	}
+
+	return &AVIF{
+		Image:     images,
+		Delay:     delays,
+		LoopCount: loopCount,
+	}, nil
+}
+
 // DecodeConfig reads the configuration of an AVIF image from the provided io.Reader.
 //
 // It returns an image.Config containing the width, height, and color model of the image, or an error if the