gowebp

gowebp

A pure-Go WebP codec. No libwebp, no cgo, no runtime dependencies beyond golang.org/x/image (which is used for decoding only).

Encodes to either WebP format:

• VP8L (lossless) — default. Every pixel preserved exactly.
• VP8 (lossy) — opt-in via Options.Lossy. Full intra-only VP8 keyframe encoder with I16 + B_PRED + UV8 intra prediction, DCT + Walsh-Hadamard transforms, boolean arithmetic coding, loop filter, and reconstruction-based RD mode selection.

Also encodes WebP animations (ANIM/ANMF) with either codec, and preserves alpha channels via ALPH chunks (raw or VP8L-compressed, static or in-animation).

Installation

go get github.com/KarpelesLab/gowebp

Usage

Lossless

import "github.com/KarpelesLab/gowebp"

f, _ := os.Create(name)
defer f.Close()
if err := gowebp.Encode(f, img, nil); err != nil {
    log.Fatal(err)
}

Lossy

err := gowebp.Encode(f, img, &gowebp.Options{
    Lossy:   true,
    Quality: 75, // 0 (smallest) to 100 (best), default 75
    Method:  4,  // 0 (fastest) to 6 (highest quality), default 0
})

Animation

ani := gowebp.Animation{
    Images:          []image.Image{frame1, frame2, frame3},
    Durations:       []uint{100, 100, 100}, // ms per frame
    Disposals:       []uint{0, 0, 0},       // 0=keep, 1=clear
    LoopCount:       0,                     // 0 = infinite
    BackgroundColor: 0xffffffff,            // BGRA
}
// Pass Options{Lossy: true} for VP8 frames; nil for VP8L.
gowebp.EncodeAll(f, &ani, nil)

Decoding

img, err := gowebp.Decode(r)

Wraps golang.org/x/image/webp. Also provides DecodeIgnoreAlphaFlag for VP8X files where a misset alpha flag trips up the standard decoder.

Lossy method tiers

The Method field picks between different speed/quality/size tradeoffs. Higher values spend more CPU per macroblock to produce smaller or higher-quality output.

Encoding is goroutine-safe: each Encode/EncodeAll call is self-contained and has no shared mutable state.

Benchmarks

Measured on Intel i9-14900K (Linux, Go 1.25) against the 5 natural photos linked from Google's WebP Gallery. Baseline is Go's image/png with png.BestCompression.

Reproduce:

NATIVEWEBP_FETCH=1 go test -run TestGalleryPSNR -v    # populate testdata/
go test -bench=. -benchtime=5x

File sizes (bytes per frame)

• Lossless (VP8L) averages 13–23 % smaller than PNG's best compression.
• Lossy Q=75 M=3 is 1.8×–3.3× smaller than lossless on the same images.
• Lossy Q=50 M=4 can reach 7× smaller than PNG while still producing visually acceptable output on photos.

Encode time (ns/op)

All timings in microseconds for brevity: lossless WebP is ≈ 1.5–2.8× faster than PNG across the gallery, while producing smaller files. Lossy encoding is typically within a small constant factor of lossless speed.

Quality (spec-correct Y-PSNR, lossy Q=75 M=3)

Y-PSNR measured against VP8 limited-range BT.601 (what a real decoder shows). Higher is better; >40 dB is visually lossless on photographic content.

Threshold floors on these numbers are asserted by TestGalleryPSNR so future encoder changes can't quietly regress quality.

BT.601 color handling

VP8 stores pixels in limited-range BT.601 YCbCr (luma 16–235, chroma 16–240) per RFC 6386. Go's stdlib image/color.YCbCrToRGB uses the JFIF full-range inverse, which shifts the resulting RGB by 2–5 units per channel when applied to VP8 samples.

Decode handles this automatically: for VP8 sources the returned image is a *gowebp.BT601YCbCr (or *gowebp.BT601NYCbCrA when the source has an ALPH chunk) whose At() method uses the spec-correct limited-range BT.601 inverse. Calling img.At(x, y).RGBA() gives the same RGB values a libwebp or browser decoder would produce.

Users who want the raw *image.YCbCr for zero-copy plane access can type-assert to *gowebp.BT601YCbCr and read the embedded field:

img, _ := gowebp.Decode(r)
if y, ok := img.(*gowebp.BT601YCbCr); ok {
    rawYCbCr := y.YCbCr     // *image.YCbCr with limited-range samples
    _ = rawYCbCr
}

VP8L (lossless) sources decode to *image.NRGBA with exact pixel fidelity and don't go through YCbCr, so no wrapping is applied.

Implementation notes

The lossy VP8 encoder lives in internal/vp8enc/ and is a pure-Go implementation of RFC 6386 (The VP8 Data Format and Decoding Guide). The following open-source implementations were consulted as references for bit-exact compatibility; no code was copied, but table values (which are specification constants) were transcribed:

• golang.org/x/image/vp8 — pure-Go VP8 decoder, used as the round-trip test oracle (BSD-3-Clause).
• libwebp — the reference C encoder/decoder from Google (BSD-3-Clause).
• libvpx — VP8/VP9 reference codec (BSD-3-Clause).

Every file in internal/vp8enc/ references the relevant RFC 6386 section and the matching path in the x/image/vp8 decoder, which is the oracle used by the test suite's round-trip integration tests.

Remaining work (tracked in the source, not here): full rate-distortion optimization with calibrated λ; proper Viterbi trellis quantization with context-aware token-tree rate estimation.

License

MIT, same as the upstream project this was forked from (HugoSmits86/nativewebp).