libwebp/doc/tools.md

WebP tools

Encoding tool

The examples/ directory contains tools for encoding (cwebp) and decoding (dwebp) images.

The easiest use should look like:

cwebp input.png -q 80 -o output.webp

which will convert the input file to a WebP file using a quality factor of 80 on a 0->100 scale (0 being the lowest quality, 100 being the best. Default value is 75).

You might want to try the -lossless flag too, which will compress the source (in RGBA format) without any loss. The -q quality parameter will in this case control the amount of processing time spent trying to make the output file as small as possible.

A longer list of options is available using the -longhelp command line flag:

> cwebp -longhelp
Usage:
 cwebp [-preset <...>] [options] in_file [-o out_file]

If input size (-s) for an image is not specified, it is assumed to be a PNG, JPEG, TIFF or WebP file. Note: Animated PNG and WebP files are not supported.

Options:

-h / -help ............. short help
-H / -longhelp ......... long help
-q <float> ............. quality factor (0:small..100:big), default=75
-alpha_q <int> ......... transparency-compression quality (0..100),
                         default=100
-preset <string> ....... preset setting, one of:
                          default, photo, picture,
                          drawing, icon, text
   -preset must come first, as it overwrites other parameters
-z <int> ............... activates lossless preset with given
                         level in [0:fast, ..., 9:slowest]

-m <int> ............... compression method (0=fast, 6=slowest), default=4
-segments <int> ........ number of segments to use (1..4), default=4
-size <int> ............ target size (in bytes)
-psnr <float> .......... target PSNR (in dB. typically: 42)

-s <int> <int> ......... input size (width x height) for YUV
-sns <int> ............. spatial noise shaping (0:off, 100:max), default=50
-f <int> ............... filter strength (0=off..100), default=60
-sharpness <int> ....... filter sharpness (0:most .. 7:least sharp), default=0
-strong ................ use strong filter instead of simple (default)
-nostrong .............. use simple filter instead of strong
-sharp_yuv ............. use sharper (and slower) RGB->YUV conversion
-partition_limit <int> . limit quality to fit the 512k limit on
                         the first partition (0=no degradation ... 100=full)
-pass <int> ............ analysis pass number (1..10)
-qrange <min> <max> .... specifies the permissible quality range
                         (default: 0 100)
-crop <x> <y> <w> <h> .. crop picture with the given rectangle
-resize <w> <h> ........ resize picture (after any cropping)
-mt .................... use multi-threading if available
-low_memory ............ reduce memory usage (slower encoding)
-map <int> ............. print map of extra info
-print_psnr ............ prints averaged PSNR distortion
-print_ssim ............ prints averaged SSIM distortion
-print_lsim ............ prints local-similarity distortion
-d <file.pgm> .......... dump the compressed output (PGM file)
-alpha_method <int> .... transparency-compression method (0..1), default=1
-alpha_filter <string> . predictive filtering for alpha plane,
                         one of: none, fast (default) or best
-exact ................. preserve RGB values in transparent area, default=off
-blend_alpha <hex> ..... blend colors against background color
                         expressed as RGB values written in
                         hexadecimal, e.g. 0xc0e0d0 for red=0xc0
                         green=0xe0 and blue=0xd0
-noalpha ............... discard any transparency information
-lossless .............. encode image losslessly, default=off
-near_lossless <int> ... use near-lossless image
                         preprocessing (0..100=off), default=100
-hint <string> ......... specify image characteristics hint,
                         one of: photo, picture or graph

-metadata <string> ..... comma separated list of metadata to
                         copy from the input to the output if present.
                         Valid values: all, none (default), exif, icc, xmp

-short ................. condense printed message
-quiet ................. don't print anything
-version ............... print version number and exit
-noasm ................. disable all assembly optimizations
-v ..................... verbose, e.g. print encoding/decoding times
-progress .............. report encoding progress

Experimental Options:

-jpeg_like ............. roughly match expected JPEG size
-af .................... auto-adjust filter strength
-pre <int> ............. pre-processing filter

The main options you might want to try in order to further tune the visual quality are:

-preset -sns -f -m

Namely:

• preset will set up a default encoding configuration targeting a particular type of input. It should appear first in the list of options, so that subsequent options can take effect on top of this preset. Default value is 'default'.
• sns will progressively turn on (when going from 0 to 100) some additional visual optimizations (like: segmentation map re-enforcement). This option will balance the bit allocation differently. It tries to take bits from the "easy" parts of the picture and use them in the "difficult" ones instead. Usually, raising the sns value (at fixed -q value) leads to larger files, but with better quality. Typical value is around '75'.
• f option directly links to the filtering strength used by the codec's in-loop processing. The higher the value, the smoother the highly-compressed area will look. This is particularly useful when aiming at very small files. Typical values are around 20-30. Note that using the option -strong/-nostrong will change the type of filtering. Use "-f 0" to turn filtering off.
• m controls the trade-off between encoding speed and quality. Default is 4. You can try -m 5 or -m 6 to explore more (time-consuming) encoding possibilities. A lower value will result in faster encoding at the expense of quality.

Decoding tool

There is a decoding sample in examples/dwebp.c which will take a .webp file and decode it to a PNG image file (amongst other formats). This is simply to demonstrate the use of the API. You can verify the file test.webp decodes to exactly the same as test_ref.ppm by using:

cd examples
./dwebp test.webp -ppm -o test.ppm
diff test.ppm test_ref.ppm

The full list of options is available using -h:

> dwebp -h
Usage: dwebp in_file [options] [-o out_file]

Decodes the WebP image file to PNG format [Default]. Note: Animated WebP files are not supported.

Use following options to convert into alternate image formats:

-pam ......... save the raw RGBA samples as a color PAM
-ppm ......... save the raw RGB samples as a color PPM
-bmp ......... save as uncompressed BMP format
-tiff ........ save as uncompressed TIFF format
-pgm ......... save the raw YUV samples as a grayscale PGM
               file with IMC4 layout
-yuv ......... save the raw YUV samples in flat layout

Other options are:

-version ..... print version number and exit
-nofancy ..... don't use the fancy YUV420 upscaler
-nofilter .... disable in-loop filtering
-nodither .... disable dithering
-dither <d> .. dithering strength (in 0..100)
-alpha_dither  use alpha-plane dithering if needed
-mt .......... use multi-threading
-crop <x> <y> <w> <h> ... crop output with the given rectangle
-resize <w> <h> ......... scale the output (*after* any cropping)
-flip ........ flip the output vertically
-alpha ....... only save the alpha plane
-incremental . use incremental decoding (useful for tests)
-h ........... this help message
-v ........... verbose (e.g. print encoding/decoding times)
-quiet ....... quiet mode, don't print anything
-noasm ....... disable all assembly optimizations

WebP file analysis tool

webpinfo can be used to print out the chunk level structure and bitstream header information of WebP files. It can also check if the files are of valid WebP format.

Usage:

webpinfo [options] in_files

Note: there could be multiple input files; options must come before input files.

Options:

-version ........... Print version number and exit.
-quiet ............. Do not show chunk parsing information.
-diag .............. Show parsing error diagnosis.
-summary ........... Show chunk stats summary.
-bitstream_info .... Parse bitstream header.

Visualization tool

There's a little self-serve visualization tool called 'vwebp' under the examples/ directory. It uses OpenGL to open a simple drawing window and show a decoded WebP file. It's not yet integrated in the automake build system, but you can try to manually compile it using the recommendations below.

Usage:

vwebp in_file [options]

Decodes the WebP image file and visualize it using OpenGL

Options are:

-version ..... print version number and exit
-noicc ....... don't use the icc profile if present
-nofancy ..... don't use the fancy YUV420 upscaler
-nofilter .... disable in-loop filtering
-dither <int>  dithering strength (0..100), default=50
-noalphadither disable alpha plane dithering
-usebgcolor .. display background color
-mt .......... use multi-threading
-info ........ print info
-h ........... this help message

Keyboard shortcuts:

'c' ................ toggle use of color profile
'b' ................ toggle background color display
'i' ................ overlay file information
'd' ................ disable blending & disposal (debug)
'q' / 'Q' / ESC .... quit

Building

Prerequisites:

1. OpenGL & OpenGL Utility Toolkit (GLUT)

   Linux: sudo apt-get install freeglut3-dev mesa-common-dev

   Mac + Xcode: These libraries should be available in the OpenGL / GLUT frameworks.

   Windows: http://freeglut.sourceforge.net/index.php#download

2. (Optional) qcms (Quick Color Management System)

   1. Download qcms from Mozilla / Chromium: https://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms https://source.chromium.org/chromium/chromium/src/+/main:third_party/qcms/;drc=d4a2f8e1ed461d8fc05ed88d1ae2dc94c9773825
   2. Build and archive the source files as libqcms.a / qcms.lib
   3. Update makefile.unix / Makefile.vc
      1. Define WEBP_HAVE_QCMS
      2. Update include / library paths to reference the qcms directory.

Build using makefile.unix / Makefile.vc:

$ make -f makefile.unix examples/vwebp
> nmake /f Makefile.vc CFG=release-static \
    ../obj/x64/release-static/bin/vwebp.exe

Animation creation tool

The utility img2webp can turn a sequence of input images (PNG, JPEG, ...) into an animated WebP file. It offers fine control over duration, encoding modes, etc.

Usage:

img2webp [file_options] [[frame_options] frame_file]...

File-level options (only used at the start of compression):

-min_size ............ minimize size
-loop <int> .......... loop count (default: 0, = infinite loop)
-kmax <int> .......... maximum number of frame between key-frames
                        (0=only keyframes)
-kmin <int> .......... minimum number of frame between key-frames
                        (0=disable key-frames altogether)
-mixed ............... use mixed lossy/lossless automatic mode
-v ................... verbose mode
-h ................... this help
-version ............. print version number and exit

Per-frame options (only used for subsequent images input):

-d <int> ............. frame duration in ms (default: 100)
-lossless  ........... use lossless mode (default)
-lossy ... ........... use lossy mode
-q <float> ........... quality
-m <int> ............. method to use

example: img2webp -loop 2 in0.png -lossy in1.jpg -d 80 in2.tiff -o out.webp

Note: if a single file name is passed as the argument, the arguments will be tokenized from this file. The file name must not start with the character '-'.

Animated GIF conversion

Animated GIF files can be converted to WebP files with animation using the gif2webp utility available under examples/. The files can then be viewed using vwebp.

Usage:

gif2webp [options] gif_file -o webp_file

Options:

-h / -help ............. this help
-lossy ................. encode image using lossy compression
-mixed ................. for each frame in the image, pick lossy
                         or lossless compression heuristically
-q <float> ............. quality factor (0:small..100:big)
-m <int> ............... compression method (0=fast, 6=slowest)
-min_size .............. minimize output size (default:off)
                         lossless compression by default; can be
                         combined with -q, -m, -lossy or -mixed
                         options
-kmin <int> ............ min distance between key frames
-kmax <int> ............ max distance between key frames
-f <int> ............... filter strength (0=off..100)
-metadata <string> ..... comma separated list of metadata to
                         copy from the input to the output if present
                         Valid values: all, none, icc, xmp (default)
-loop_compatibility .... use compatibility mode for Chrome
                         version prior to M62 (inclusive)
-mt .................... use multi-threading if available

-version ............... print version number and exit
-v ..................... verbose
-quiet ................. don't print anything

Building

With the libgif development files installed, gif2webp can be built using makefile.unix:

$ make -f makefile.unix examples/gif2webp

or using autoconf:

$ ./configure --enable-everything
$ make

Comparison of animated images

Test utility anim_diff under examples/ can be used to compare two animated images (each can be GIF or WebP).

Usage:

anim_diff <image1> <image2> [options]

Options:

-dump_frames <folder> dump decoded frames in PAM format
-min_psnr <float> ... minimum per-frame PSNR
-raw_comparison ..... if this flag is not used, RGB is
                      premultiplied before comparison
-max_diff <int> ..... maximum allowed difference per channel
                      between corresponding pixels in subsequent
                      frames
-h .................. this help
-version ............ print version number and exit

Building

With the libgif development files installed, anim_diff can be built using makefile.unix:

$ make -f makefile.unix examples/anim_diff

or using autoconf:

$ ./configure --enable-everything
$ make

WebP Mux tool

The examples/ directory contains a tool (webpmux) for manipulating WebP files. The webpmux tool can be used to create an extended format WebP file and also to extract or strip relevant data from such a file.

A list of options is available using the -help command line flag:

> webpmux -help
Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT
       webpmux -set SET_OPTIONS INPUT -o OUTPUT
       webpmux -duration DURATION_OPTIONS [-duration ...]
               INPUT -o OUTPUT
       webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT
       webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT]
               [-bgcolor BACKGROUND_COLOR] -o OUTPUT
       webpmux -info INPUT
       webpmux [-h|-help]
       webpmux -version
       webpmux argument_file_name

GET_OPTIONS:
 Extract relevant data:
   icc       get ICC profile
   exif      get EXIF metadata
   xmp       get XMP metadata
   frame n   get nth frame

SET_OPTIONS:
 Set color profile/metadata/parameters:
   loop LOOP_COUNT            set the loop count
   bgcolor BACKGROUND_COLOR   set the animation background color
   icc  file.icc              set ICC profile
   exif file.exif             set EXIF metadata
   xmp  file.xmp              set XMP metadata
   where:    'file.icc' contains the ICC profile to be set,
             'file.exif' contains the EXIF metadata to be set
             'file.xmp' contains the XMP metadata to be set

DURATION_OPTIONS:
 Set duration of selected frames:
   duration            set duration for all frames
   duration,frame      set duration of a particular frame
   duration,start,end  set duration of frames in the
                        interval [start,end])
   where: 'duration' is the duration in milliseconds
          'start' is the start frame index
          'end' is the inclusive end frame index
           The special 'end' value '0' means: last frame.

STRIP_OPTIONS:
 Strip color profile/metadata:
   icc       strip ICC profile
   exif      strip EXIF metadata
   xmp       strip XMP metadata

FRAME_OPTIONS(i):
 Create animation:
   file_i +di[+xi+yi[+mi[bi]]]
   where:    'file_i' is the i'th animation frame (WebP format),
             'di' is the pause duration before next frame,
             'xi','yi' specify the image offset for this frame,
             'mi' is the dispose method for this frame (0 or 1),
             'bi' is the blending method for this frame (+b or -b)

LOOP_COUNT:
 Number of times to repeat the animation.
 Valid range is 0 to 65535 [Default: 0 (infinite)].

BACKGROUND_COLOR:
 Background color of the canvas.
  A,R,G,B
  where:    'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying
            the Alpha, Red, Green and Blue component values respectively
            [Default: 255,255,255,255]

INPUT & OUTPUT are in WebP format.

Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be
valid.

Note: if a single file name is passed as the argument, the arguments will be
tokenized from this file. The file name must not start with the character '-'.