gowebp

README

gowebp

声明：本项目完全通过AI生成

Go WebP 转换库与命令行工具。内置 libwebp C 源码，通过 CGO 静态编译，不依赖系统安装的 libwebp 动态库。

将 PNG、JPEG、BMP、GIF 等常见图片格式转换为 WebP。

特性

• 内置 libwebp 1.4.0 C 源码（third_party/libwebp）
• CGO 静态编译，无需 brew install webp 或系统 libwebp
• 支持无损 / 有损编码
• 支持 GIF 动画转 WebP 动画
• 提供库 API 和 gowebp 命令行工具

环境要求

• Go 1.22+
• CGO 编译器（macOS/Linux 上通常为 clang/gcc）
• 启用 CGO（默认开启）

安装

go install github.com/tjbrains/gowebp/cmd/gowebp@latest

命令行用法

# PNG 转 WebP（默认无损）
gowebp photo.png

# JPEG 有损压缩（推荐用于照片）
gowebp -lossy -q 80 photo.jpg

# GIF 动画转 WebP 动画
gowebp anim.gif

# 批量转换
gowebp a.png b.jpg c.bmp

# 输出到指定目录
gowebp -o out/ *.png

# 从标准输入读取
cat image.png | gowebp - > image.webp

参数

参数	说明
-o	输出文件或目录（- 表示 stdout）
-lossy	启用 VP8 有损压缩
-q	质量 0–100，默认 75
-m	编码力度 0（最快）到 6（最小体积），默认 4
-near	近无损位数 0–9，0 为完全无损

库用法

import (
    "os"
    "github.com/tjbrains/gowebp"
)

f, _ := os.Create("output.webp")
defer f.Close()

// 无损编码
gowebp.Encode(f, img, nil)

// 有损编码
gowebp.Encode(f, img, &gowebp.Options{
    Lossy:   true,
    Quality: 80,
})

文件转换

err := gowebp.ConvertFile("input.png", "output.webp", nil)

支持格式

输入	输出
PNG	WebP
JPEG	WebP
BMP	WebP
GIF	WebP（单帧或动画）

项目结构

gowebp/
├── cmd/gowebp/          # 命令行工具
├── internal/cwebp/      # CGO 绑定（调用 libwebp C API）
│   └── wrapper/         # libwebp C 源码编译包装
├── third_party/libwebp/ # libwebp C 源码
├── encode.go            # 公共编码 API
├── decode.go            # 公共解码 API
└── convert.go           # 文件转换

更新 libwebp 源码

1. 下载新版本到 third_party/libwebp
2. 在 internal/cwebp/wrapper 目录执行 go generate ./...

License

MIT（Go 代码）+ libwebp BSD 许可（C 源码）

Documentation

Index

• Constants
• func ConvertBytes(data []byte, w io.Writer, opts *Options) error
• func ConvertFile(src, dst string, opts *Options) error
• func Decode(r io.Reader) (image.Image, error)
• func Encode(w io.Writer, img image.Image, opts *Options) error
• func EncodeAll(w io.Writer, ani *Animation, opts *Options) error
• func EncodeGIF(w io.Writer, g *gif.GIF, opts *Options) error
• func OutputPath(input, output string) (string, error)
• type Animation
• type Options

Constants

const WebPMaxDimension = 16383

WebPMaxDimension is the maximum width or height supported by libwebp.

Functions

func ConvertBytes

func ConvertBytes(data []byte, w io.Writer, opts *Options) error

ConvertBytes decodes image bytes and writes WebP to w.

func ConvertFile

func ConvertFile(src, dst string, opts *Options) error

ConvertFile reads an image file and writes WebP to dst. Supported inputs: PNG, JPEG, BMP, GIF (including animated GIF).

func Decode

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

Decode reads a WebP image from r.

func Encode

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

Encode writes img as a WebP file to w.

func EncodeAll

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

EncodeAll writes an animated WebP to w.

func EncodeGIF

func EncodeGIF(w io.Writer, g *gif.GIF, opts *Options) error

EncodeGIF encodes a decoded GIF (including animation) to WebP.

func OutputPath

func OutputPath(input, output string) (string, error)

OutputPath returns the default WebP output path for an input file.

Types

type Animation

type Animation struct {
	Images          []image.Image
	Durations       []uint // milliseconds per frame
	Disposals       []uint // 0=keep, 1=clear to background
	LoopCount       uint16 // 0 = infinite
	BackgroundColor uint32 // BGRA
}

Animation holds frames for animated WebP output.

type Options

type Options struct {
	// Lossy enables VP8 lossy compression. Default is lossless VP8L.
	Lossy bool

	// Quality ranges from 0 (smallest) to 100 (best). Default 75.
	Quality int

	// Method controls encoder effort from 0 (fastest) to 6 (best compression).
	// Default 4.
	Method int

	// NearLossless sets near-lossless bits for lossless mode (0-9).
	// 0 means exact lossless. When Lossy is true and this is 0, quality drives compression.
	NearLossless int
}

Options controls WebP encoding.