nativewebp

README

Native WebP for Go

This is a native WebP encoder written entirely in Go, with no dependencies on libwebp or other external libraries. Designed for performance and efficiency, this encoder generates smaller files than the standard Go PNG encoder and is approximately 50% faster in execution.

Currently, the encoder supports only WebP lossless images (VP8L).

Decoding Support

We provide WebP decoding through a wrapper around golang.org/x/image/webp, with an additional DecodeIgnoreAlphaFlag function to handle VP8X images where the alpha flag causes decoding issues.

Benchmark

We conducted a quick benchmark to showcase file size reduction and encoding performance. Using an image from Google’s WebP Lossless and Alpha Gallery, we compared the results of our nativewebp encoder with the standard PNG encoder.

For the PNG encoder, we applied the png.BestCompression setting to achieve the most competitive compression outcomes.

		PNG encoder	nativeWebP encoder	reduction
	file size	120 kb	96 kb	20% smaller
	encoding time	42945049 ns/op	27716447 ns/op	35% faster
	file size	46 kb	36 kb	22% smaller
	encoding time	98509399 ns/op	31461759 ns/op	68% faster
	file size	236 kb	194 kb	18% smaller
	encoding time	178205535 ns/op	102454192 ns/op	43% faster
	file size	53 kb	41 kb	23% smaller
	encoding time	29088555 ns/op	14959849 ns/op	49% faster
	file size	139 kb	123 kb	12% smaller
	encoding time	63423995 ns/op	21717392 ns/op	66% faster

_{image source: https://developers.google.com/speed/webp/gallery2}

Installation

To install the nativewebp package, use the following command:

go get github.com/HugoSmits86/nativewebp

Usage

Here’s a simple example of how to encode an image:

file, err := os.Create(name)
if err != nil {
  log.Fatalf("Error creating file %s: %v", name, err)
}
defer file.Close()

err = nativewebp.Encode(file, img, nil)
if err != nil {
  log.Fatalf("Error encoding image to WebP: %v", err)
}

Here’s a simple example of how to encode an animation:

file, err := os.Create(name)
if err != nil {
  log.Fatalf("Error creating file %s: %v", name, err)
}
defer file.Close()

ani := nativewebp.Animation{
  Images: []image.Image{
    frame1,
    frame2,
  },
  Durations: []uint {
    100,
    100,
  },
  Disposals: []uint {
    0,
    0,
  },
  LoopCount: 0,
  BackgroundColor: 0xffffffff,
}

err = nativewebp.EncodeAll(file, &ani, nil)
if err != nil {
  log.Fatalf("Error encoding WebP animation: %v", err)
}

Documentation

Index

• func Decode(r io.Reader) (image.Image, error)
• func DecodeConfig(r io.Reader) (image.Config, error)
• func DecodeIgnoreAlphaFlag(r io.Reader) (image.Image, error)
• func Encode(w io.Writer, img image.Image, o *Options) error
• func EncodeAll(w io.Writer, ani *Animation, o *Options) error
• type Animation
• type Options

Functions

func Decode

func Decode(r io.Reader) (image.Image, error)

Decode reads a WebP image from the provided io.Reader and returns it as an image.Image.

This function is a wrapper around the underlying WebP decode package (golang.org/x/image/webp). It supports both lossy and lossless WebP formats, decoding the image accordingly.

Parameters:

r - The source io.Reader containing the WebP encoded image.

Returns:

The decoded image as image.Image or an error if the decoding fails.

func DecodeConfig

func DecodeConfig(r io.Reader) (image.Config, error)

DecodeConfig reads the image configuration from the provided io.Reader without fully decoding the image.

This function is a wrapper around the underlying WebP decode package (golang.org/x/image/webp) and provides access to the image's metadata, such as its dimensions and color model. It is useful for obtaining image information before performing a full decode.

Parameters:

r - The source io.Reader containing the WebP encoded image.

Returns:

An image.Config containing the image's dimensions and color model, or an error if the configuration cannot be retrieved

func DecodeIgnoreAlphaFlag

func DecodeIgnoreAlphaFlag(r io.Reader) (image.Image, error)

DecodeIgnoreAlphaFlag reads a WebP image from the provided io.Reader and returns it as an image.Image.

This function fixes x/image/webp rejecting VP8L images with the VP8X alpha flag, expecting an ALPHA chunk. VP8L handles transparency internally, and the WebP spec requires the flag for transparency.

This function is a wrapper around the underlying WebP decode package (golang.org/x/image/webp). It supports both lossy and lossless WebP formats, decoding the image accordingly.

Parameters:

r - The source io.Reader containing the WebP encoded image.

Returns:

The decoded image as image.Image or an error if the decoding fails.

func Encode

func Encode(w io.Writer, img image.Image, o *Options) error

Encode writes the provided image.Image to the specified io.Writer in WebP format.

This function always encodes the image using VP8L (lossless WebP). If `UseExtendedFormat` is enabled, it wraps the VP8L frame inside a VP8X container, allowing the use of metadata such as EXIF, ICC color profiles, or XMP metadata.

Note: VP8L already supports transparency, so VP8X is **not required** for alpha support.

Parameters:

w   - The destination writer where the encoded WebP image will be written.
img - The input image to be encoded.
o   - Pointer to Options containing encoding settings:
      - UseExtendedFormat: If true, wraps the image in a VP8X container to enable
        extended WebP features like metadata.

Returns:

An error if encoding fails or writing to the io.Writer encounters an issue.

func EncodeAll

func EncodeAll(w io.Writer, ani *Animation, o *Options) error

EncodeAll writes the provided animation sequence to the specified io.Writer in WebP format.

This function encodes a list of frames as a WebP animation using the VP8X container, which supports features like looping, frame timing, disposal methods, and background color settings. Each frame is individually compressed using the VP8L (lossless) format.

Note: Even if `UseExtendedFormat` is not explicitly set, animations always use the VP8X container because it is required for WebP animation support.

Parameters:

w   - The destination writer where the encoded WebP animation will be written.
ani - Pointer to Animation containing the frames and animation settings:
      - Images: List of frames to encode.
      - Durations: Display times for each frame in milliseconds.
      - Disposals: Disposal methods after frame display (keep or clear).
      - LoopCount: Number of times the animation should loop (0 = infinite).
      - BackgroundColor: Background color for the canvas, used when clearing.
o   - Pointer to Options containing additional encoding settings:
      - UseExtendedFormat: Currently unused for animations, but accepted for consistency.

Returns:

An error if encoding fails or writing to the io.Writer encounters an issue.

Types

type Animation

type Animation struct {
	Images          []image.Image
	Durations       []uint
	Disposals       []uint
	LoopCount       uint16
	BackgroundColor uint32
}

Animation holds configuration settings for WebP animations.

It allows encoding a sequence of frames with individual timing and disposal options, supporting features like looping and background color settings.

Fields:

• Images: A list of frames to be displayed in sequence.
• Durations: Timing for each frame in milliseconds, matching the Images slice.
• Disposals: Disposal methods for frames after display; 0 = keep, 1 = clear to background.
• LoopCount: Number of times the animation should repeat; 0 means infinite looping.
• BackgroundColor: Canvas background color in BGRA order, used for clear operations.

type Options

type Options struct {
	UseExtendedFormat bool
}

Options holds configuration settings for WebP encoding.

Currently, it provides a flag to enable the extended WebP format (VP8X), which allows for metadata support such as EXIF, ICC color profiles, and XMP.

Fields:

• UseExtendedFormat: If true, wraps the VP8L frame inside a VP8X container to enable metadata support. This does not affect image compression or encoding itself, as VP8L remains the encoding format.