gowebp

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.

Supported output formats:

• VP8L (lossless) — default, used when Options.Lossy is false or Options is nil. Preserves every pixel exactly.

• VP8 (lossy) — enabled by Options.Lossy = true. Pure-Go VP8 keyframe encoder supporting I16 (4 modes), B_PRED (10 I4 modes per 4×4 sub-block), UV8 chroma prediction, DCT + Walsh-Hadamard transforms, round-to-nearest quantization, context-adaptive boolean arithmetic coding of coefficient tokens, the decoder-side loop filter, and per-MB I16/B_PRED arbitration at Method=3.

  Measured RGB-PSNR (spec-correct, limited-range BT.601) on smooth content: ~41 dB at Q=90, ~40 dB at Q=75, ~32 dB at Q=50 — visually lossless at high Q and comparable to cwebp within a few dB. Files are roughly 1.5–3× cwebp's size at the same quality setting; closing that gap with full rate-distortion optimization and trellis quantization is future work.

  BT.601 range note: VP8 uses limited-range BT.601 YCbCr (luma 16–235) per RFC 6386. Go's stdlib image/color.YCbCrToRGB uses JFIF full-range BT.601, so when you decode a lossy WebP with golang.org/x/image/webp and convert to RGB via .At().RGBA(), colors shift 2–5 units per channel — making Go's naive RGB-PSNR look like ~28 dB even on near-perfect output. Real VP8 decoders (libwebp, browsers) apply the correct inverse and show the encoder's true quality. This is a Go stdlib issue, not an encoder bug.

• Animation (ANIM/ANMF) — supported for both VP8L and VP8 frames. EncodeAll respects Options.Lossy per-animation.

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 gowebp encoder with the standard PNG encoder.

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

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

Installation

To install the gowebp package, use the following command:

go get github.com/KarpelesLab/gowebp

Usage

Here’s a simple example of how to encode an image losslessly (VP8L):

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

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

Or encode with lossy VP8 compression:

err = gowebp.Encode(file, img, &gowebp.Options{
  Lossy:   true,
  Quality: 75, // 0 (smallest) to 100 (best); 75 is a reasonable default
  Method:  3,  // speed/quality tradeoff
})

Method levels (measured on i9-14900K, 256×256 image):

On natural content, Method=4 produces both smaller files AND higher PSNR than Method=3, at a reasonable speed overhead. It's recommended for most use cases. Method=5 is a more principled but rarely- different reference; Method=6 adds a simple trellis that helps on textured content where post-quantization noise survives. Higher levels (>6) currently behave like 6.

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

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 := gowebp.Animation{
  Images: []image.Image{
    frame1,
    frame2,
  },
  Durations: []uint {
    100,
    100,
  },
  Disposals: []uint {
    0,
    0,
  },
  LoopCount: 0,
  BackgroundColor: 0xffffffff,
}

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

Pass &gowebp.Options{Lossy: true, Quality: 75} to EncodeAll to produce an animation whose frames use VP8 (lossy) instead of VP8L.

Implementation notes and references

The VP8 encoder in internal/vp8enc/ is a pure-Go implementation built against the RFC 6386 specification (The VP8 Data Format and Decoding Guide). The following open-source implementations were consulted as references for bit-exact roundtrip 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/ includes an RFC 6386 section pointer and cross-reference to the equivalent path in the x/image/vp8 decoder, which is what the encoder is verified against in the roundtrip tests.