webp

Documentation

Overview

Package webp decodes and encodes WebP through the standard library's image interfaces, at the import path .../webp-go-pure/std.

It has the same shape as image/png and image/jpeg, so it drops into code that already speaks image.Image:

img, err := webp.Decode(r)
err = webp.Encode(w, img, &webp.Options{Quality: 80})

Importing it registers WebP with image.Decode and image.DecodeConfig, the way image/png and golang.org/x/image/webp do.

Avoiding conversions

Lossy WebP and JPEG are both planar 4:2:0 YCbCr, so this package moves planes rather than pixels wherever it can. Decode hands back the decoder's own planes as an *image.YCbCr instead of converting them to RGBA, and Encode feeds an *image.YCbCr to the encoder in the same layout. Transcoding a JPEG to lossy WebP therefore skips the RGBA round trip.

Anything else still works, it just costs a conversion through *image.NRGBA.

Index

• Constants
• Variables
• func Decode(r io.Reader) (image.Image, error)
• func DecodeBytes(data []byte) (image.Image, error)
• func DecodeConfig(r io.Reader) (image.Config, error)
• func DecodeNRGBA(r io.Reader) (*image.NRGBA, error)
• func DecodeNRGBABytes(data []byte) (*image.NRGBA, error)
• func Encode(w io.Writer, m image.Image, o *Options) error
• func EncodeBytes(m image.Image, o *Options) ([]byte, error)
• type Animation
  • func DecodeAll(r io.Reader) (*Animation, error)
• type Options

Constants

const DefaultQuality = 90

DefaultQuality is the lossy quality Options uses when Quality is zero.

const EffortFastest = -1

EffortFastest asks for the fastest encode. It exists because the zero value of Options.Effort means "the default for this mode" rather than zero, so this is how you request effort 0 explicitly.

Variables

var (
	ErrInvalidParam  = codec.ErrInvalidParam
	ErrNotEnoughData = codec.ErrNotEnoughData
	ErrBitstream     = codec.ErrBitstream
	ErrUnsupported   = codec.ErrUnsupported
	ErrAnimated      = codec.ErrAnimated
	ErrLossyAlpha    = codec.ErrLossyAlpha
)

Errors from the underlying codec, re-exported so that a caller matching on them does not have to import the root package as well.

Functions

func Decode

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

Decode reads a WebP image from r.

The returned concrete type is whatever avoids a conversion: *image.YCbCr for lossy input, *image.NYCbCrA for lossy input with an alpha channel, and *image.NRGBA for lossless input. For animated input it is the first frame, as an *image.NRGBA; use DecodeAll to get every frame.

func DecodeBytes

func DecodeBytes(data []byte) (image.Image, error)

DecodeBytes is Decode without the io.Reader, for callers who already hold the encoded image. It saves the copy io.ReadAll makes.

func DecodeConfig

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

DecodeConfig returns the color model and dimensions of a WebP image without decoding it.

The color model is the one Decode would produce: color.YCbCrModel for lossy, color.NYCbCrAModel for lossy with alpha, and color.NRGBAModel for lossless and for animations.

func DecodeNRGBA

func DecodeNRGBA(r io.Reader) (*image.NRGBA, error)

DecodeNRGBA decodes a WebP image into an *image.NRGBA whatever the file holds, for callers who want one predictable pixel layout rather than the type Decode picks. The alpha is straight, not premultiplied.

This is cheaper than decoding and converting yourself, because the codec converts its own planes rather than going through an intermediate image.

func DecodeNRGBABytes

func DecodeNRGBABytes(data []byte) (*image.NRGBA, error)

DecodeNRGBABytes is DecodeNRGBA without the io.Reader.

func Encode

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

Encode writes m to w as a WebP image. A nil *Options uses the defaults: lossy, quality 90.

Both encoders keep transparency. The lossy encoder stores the color channels lossily and the alpha channel losslessly, so alpha survives a lossy encode unchanged.

func EncodeBytes

func EncodeBytes(m image.Image, o *Options) ([]byte, error)

EncodeBytes is Encode without the io.Writer, for callers who want the encoded image as a buffer. It saves the copy Encode's Write makes.

Types

type Animation

type Animation struct {
	// Image holds the frames, each already composited onto the canvas, so a
	// frame can be displayed without reference to the ones before it.
	Image []image.Image
	// Delay holds each frame's display duration in milliseconds. Note that
	// gif.GIF measures delays in 100ths of a second; WebP does not.
	Delay []int
	// LoopCount is how many times the animation repeats. Zero means forever.
	LoopCount int
	// Config is the canvas color model and dimensions.
	Config image.Config
}

Animation is a decoded animated WebP, in the shape of gif.GIF.

func DecodeAll

func DecodeAll(r io.Reader) (*Animation, error)

DecodeAll reads every frame of an animated WebP from r. A still image decodes as a single-frame animation.

type Options

type Options struct {
	// Quality is the lossy quality target in 1..100. Higher is better looking
	// and larger. Zero means [DefaultQuality]. Ignored when Lossless is set.
	Quality int
	// Effort trades encode time for file size, in 0..9 for lossy and 0..6 for
	// lossless (7..9 accepted there, but do not enable any additional options
	// beyond 6 at the moment). Higher is slower and
	// smaller. Zero means the default for the mode, which is 0 for lossy and 6
	// for lossless; pass [EffortFastest] to ask for 0 explicitly.
	Effort int
	// Lossless selects the VP8L encoder, which reproduces the input exactly.
	Lossless bool
	// EXIF, if non-nil, is embedded as a raw EXIF metadata chunk.
	EXIF []byte
}

Options configures Encode. A nil *Options, or a zero field, means the default.