# WebP tools ## Encoding tool The examples/ directory contains tools for encoding (cwebp) and decoding (dwebp) images. The easiest use should look like: ```shell 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: ```shell > 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 ............. quality factor (0:small..100:big), default=75 -alpha_q ......... transparency-compression quality (0..100), default=100 -preset ....... preset setting, one of: default, photo, picture, drawing, icon, text -preset must come first, as it overwrites other parameters -z ............... activates lossless preset with given level in [0:fast, ..., 9:slowest] -m ............... compression method (0=fast, 6=slowest), default=4 -segments ........ number of segments to use (1..4), default=4 -size ............ target size (in bytes) -psnr .......... target PSNR (in dB. typically: 42) -s ......... input size (width x height) for YUV -sns ............. spatial noise shaping (0:off, 100:max), default=50 -f ............... filter strength (0=off..100), default=60 -sharpness ....... 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 . limit quality to fit the 512k limit on the first partition (0=no degradation ... 100=full) -pass ............ analysis pass number (1..10) -qrange .... specifies the permissible quality range (default: 0 100) -crop .. crop picture with the given rectangle -resize ........ resize picture (after any cropping) -mt .................... use multi-threading if available -low_memory ............ reduce memory usage (slower encoding) -map ............. print map of extra info -print_psnr ............ prints averaged PSNR distortion -print_ssim ............ prints averaged SSIM distortion -print_lsim ............ prints local-similarity distortion -d .......... dump the compressed output (PGM file) -alpha_method .... transparency-compression method (0..1), default=1 -alpha_filter . predictive filtering for alpha plane, one of: none, fast (default) or best -exact ................. preserve RGB values in transparent area, default=off -blend_alpha ..... 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 ... use near-lossless image preprocessing (0..100=off), default=100 -hint ......... specify image characteristics hint, one of: photo, picture or graph -metadata ..... 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 ............. 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: ```shell cd examples ./dwebp test.webp -ppm -o test.ppm diff test.ppm test_ref.ppm ``` The full list of options is available using -h: ```shell > 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 .. dithering strength (in 0..100) -alpha_dither use alpha-plane dithering if needed -mt .......... use multi-threading -crop ... crop output with the given rectangle -resize ......... 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: ```shell 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: ```shell 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 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: ```shell $ 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: ```shell img2webp [file_options] [[frame_options] frame_file]... ``` File-level options (only used at the start of compression): ``` -min_size ............ minimize size -loop .......... loop count (default: 0, = infinite loop) -kmax .......... maximum number of frame between key-frames (0=only keyframes) -kmin .......... 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 ............. frame duration in ms (default: 100) -lossless ........... use lossless mode (default) -lossy ... ........... use lossy mode -q ........... quality -m ............. 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: ```shell 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 ............. quality factor (0:small..100:big) -m ............... 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 ............ min distance between key frames -kmax ............ max distance between key frames -f ............... filter strength (0=off..100) -metadata ..... 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: ```shell $ make -f makefile.unix examples/gif2webp ``` or using autoconf: ```shell $ ./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: ```shell anim_diff [options] ``` Options: ``` -dump_frames dump decoded frames in PAM format -min_psnr ... minimum per-frame PSNR -raw_comparison ..... if this flag is not used, RGB is premultiplied before comparison -max_diff ..... 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: ```shell $ make -f makefile.unix examples/anim_diff ``` or using autoconf: ```shell $ ./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: ```shell > 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 '-'. ```