1# WebP tools 2 3## Encoding tool 4 5The examples/ directory contains tools for encoding (cwebp) and decoding (dwebp) 6images. 7 8The easiest use should look like: 9 10```shell 11cwebp input.png -q 80 -o output.webp 12``` 13 14which will convert the input file to a WebP file using a quality factor of 80 on 15a 0->100 scale (0 being the lowest quality, 100 being the best. Default value is 1675). 17 18You might want to try the `-lossless` flag too, which will compress the source 19(in RGBA format) without any loss. The `-q` quality parameter will in this case 20control the amount of processing time spent trying to make the output file as 21small as possible. 22 23A longer list of options is available using the `-longhelp` command line flag: 24 25```shell 26> cwebp -longhelp 27Usage: 28 cwebp [-preset <...>] [options] in_file [-o out_file] 29``` 30 31If input size (-s) for an image is not specified, it is assumed to be a PNG, 32JPEG, TIFF or WebP file. Note: Animated PNG and WebP files are not supported. 33 34Options: 35 36``` 37-h / -help ............. short help 38-H / -longhelp ......... long help 39-q <float> ............. quality factor (0:small..100:big), default=75 40-alpha_q <int> ......... transparency-compression quality (0..100), 41 default=100 42-preset <string> ....... preset setting, one of: 43 default, photo, picture, 44 drawing, icon, text 45 -preset must come first, as it overwrites other parameters 46-z <int> ............... activates lossless preset with given 47 level in [0:fast, ..., 9:slowest] 48 49-m <int> ............... compression method (0=fast, 6=slowest), default=4 50-segments <int> ........ number of segments to use (1..4), default=4 51-size <int> ............ target size (in bytes) 52-psnr <float> .......... target PSNR (in dB. typically: 42) 53 54-s <int> <int> ......... input size (width x height) for YUV 55-sns <int> ............. spatial noise shaping (0:off, 100:max), default=50 56-f <int> ............... filter strength (0=off..100), default=60 57-sharpness <int> ....... filter sharpness (0:most .. 7:least sharp), default=0 58-strong ................ use strong filter instead of simple (default) 59-nostrong .............. use simple filter instead of strong 60-sharp_yuv ............. use sharper (and slower) RGB->YUV conversion 61-partition_limit <int> . limit quality to fit the 512k limit on 62 the first partition (0=no degradation ... 100=full) 63-pass <int> ............ analysis pass number (1..10) 64-qrange <min> <max> .... specifies the permissible quality range 65 (default: 0 100) 66-crop <x> <y> <w> <h> .. crop picture with the given rectangle 67-resize <w> <h> ........ resize picture (*after* any cropping) 68-mt .................... use multi-threading if available 69-low_memory ............ reduce memory usage (slower encoding) 70-map <int> ............. print map of extra info 71-print_psnr ............ prints averaged PSNR distortion 72-print_ssim ............ prints averaged SSIM distortion 73-print_lsim ............ prints local-similarity distortion 74-d <file.pgm> .......... dump the compressed output (PGM file) 75-alpha_method <int> .... transparency-compression method (0..1), default=1 76-alpha_filter <string> . predictive filtering for alpha plane, 77 one of: none, fast (default) or best 78-exact ................. preserve RGB values in transparent area, default=off 79-blend_alpha <hex> ..... blend colors against background color 80 expressed as RGB values written in 81 hexadecimal, e.g. 0xc0e0d0 for red=0xc0 82 green=0xe0 and blue=0xd0 83-noalpha ............... discard any transparency information 84-lossless .............. encode image losslessly, default=off 85-near_lossless <int> ... use near-lossless image preprocessing 86 (0..100=off), default=100 87-hint <string> ......... specify image characteristics hint, 88 one of: photo, picture or graph 89 90-metadata <string> ..... comma separated list of metadata to 91 copy from the input to the output if present. 92 Valid values: all, none (default), exif, icc, xmp 93 94-short ................. condense printed message 95-quiet ................. don't print anything 96-version ............... print version number and exit 97-noasm ................. disable all assembly optimizations 98-v ..................... verbose, e.g. print encoding/decoding times 99-progress .............. report encoding progress 100``` 101 102Experimental Options: 103 104``` 105-jpeg_like ............. roughly match expected JPEG size 106-af .................... auto-adjust filter strength 107-pre <int> ............. pre-processing filter 108``` 109 110The main options you might want to try in order to further tune the visual 111quality are: 112 113-preset -sns -f -m 114 115Namely: 116 117* `preset` will set up a default encoding configuration targeting a particular 118 type of input. It should appear first in the list of options, so that 119 subsequent options can take effect on top of this preset. Default value is 120 'default'. 121* `sns` will progressively turn on (when going from 0 to 100) some additional 122 visual optimizations (like: segmentation map re-enforcement). This option 123 will balance the bit allocation differently. It tries to take bits from the 124 "easy" parts of the picture and use them in the "difficult" ones instead. 125 Usually, raising the sns value (at fixed -q value) leads to larger files, 126 but with better quality. Typical value is around '75'. 127* `f` option directly links to the filtering strength used by the codec's 128 in-loop processing. The higher the value, the smoother the highly-compressed 129 area will look. This is particularly useful when aiming at very small files. 130 Typical values are around 20-30. Note that using the option 131 -strong/-nostrong will change the type of filtering. Use "-f 0" to turn 132 filtering off. 133* `m` controls the trade-off between encoding speed and quality. Default is 4. 134 You can try -m 5 or -m 6 to explore more (time-consuming) encoding 135 possibilities. A lower value will result in faster encoding at the expense 136 of quality. 137 138## Decoding tool 139 140There is a decoding sample in examples/dwebp.c which will take a .webp file and 141decode it to a PNG image file (amongst other formats). This is simply to 142demonstrate the use of the API. You can verify the file test.webp decodes to 143exactly the same as test_ref.ppm by using: 144 145```shell 146cd examples 147./dwebp test.webp -ppm -o test.ppm 148diff test.ppm test_ref.ppm 149``` 150 151The full list of options is available using -h: 152 153```shell 154> dwebp -h 155Usage: dwebp in_file [options] [-o out_file] 156``` 157 158Decodes the WebP image file to PNG format [Default]. Note: Animated WebP files 159are not supported. 160 161Use following options to convert into alternate image formats: 162 163``` 164-pam ......... save the raw RGBA samples as a color PAM 165-ppm ......... save the raw RGB samples as a color PPM 166-bmp ......... save as uncompressed BMP format 167-tiff ........ save as uncompressed TIFF format 168-pgm ......... save the raw YUV samples as a grayscale PGM 169 file with IMC4 layout 170-yuv ......... save the raw YUV samples in flat layout 171``` 172 173Other options are: 174 175``` 176-version ..... print version number and exit 177-nofancy ..... don't use the fancy YUV420 upscaler 178-nofilter .... disable in-loop filtering 179-nodither .... disable dithering 180-dither <d> .. dithering strength (in 0..100) 181-alpha_dither use alpha-plane dithering if needed 182-mt .......... use multi-threading 183-crop <x> <y> <w> <h> ... crop output with the given rectangle 184-resize <w> <h> ......... resize output (*after* any cropping) 185-flip ........ flip the output vertically 186-alpha ....... only save the alpha plane 187-incremental . use incremental decoding (useful for tests) 188-h ........... this help message 189-v ........... verbose (e.g. print encoding/decoding times) 190-quiet ....... quiet mode, don't print anything 191-noasm ....... disable all assembly optimizations 192``` 193 194## WebP file analysis tool 195 196`webpinfo` can be used to print out the chunk level structure and bitstream 197header information of WebP files. It can also check if the files are of valid 198WebP format. 199 200Usage: 201 202```shell 203webpinfo [options] in_files 204``` 205 206Note: there could be multiple input files; options must come before input files. 207 208Options: 209 210``` 211-version ........... Print version number and exit. 212-quiet ............. Do not show chunk parsing information. 213-diag .............. Show parsing error diagnosis. 214-summary ........... Show chunk stats summary. 215-bitstream_info .... Parse bitstream header. 216``` 217 218## Visualization tool 219 220There's a little self-serve visualization tool called 'vwebp' under the 221examples/ directory. It uses OpenGL to open a simple drawing window and show a 222decoded WebP file. It's not yet integrated in the automake build system, but you 223can try to manually compile it using the recommendations below. 224 225Usage: 226 227```shell 228vwebp in_file [options] 229``` 230 231Decodes the WebP image file and visualize it using OpenGL 232 233Options are: 234 235``` 236-version ..... print version number and exit 237-noicc ....... don't use the icc profile if present 238-nofancy ..... don't use the fancy YUV420 upscaler 239-nofilter .... disable in-loop filtering 240-dither <int> dithering strength (0..100), default=50 241-noalphadither disable alpha plane dithering 242-usebgcolor .. display background color 243-mt .......... use multi-threading 244-info ........ print info 245-h ........... this help message 246``` 247 248Keyboard shortcuts: 249 250``` 251'c' ................ toggle use of color profile 252'b' ................ toggle background color display 253'i' ................ overlay file information 254'd' ................ disable blending & disposal (debug) 255'q' / 'Q' / ESC .... quit 256``` 257 258### Building 259 260Prerequisites: 261 2621. OpenGL & OpenGL Utility Toolkit (GLUT) 263 264 Linux: `sudo apt-get install freeglut3-dev mesa-common-dev` 265 266 Mac + Xcode: These libraries should be available in the OpenGL / GLUT 267 frameworks. 268 269 Windows: http://freeglut.sourceforge.net/index.php#download 270 2712. (Optional) qcms (Quick Color Management System) 272 273 1. Download qcms from Mozilla / Chromium: 274 https://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms 275 https://source.chromium.org/chromium/chromium/src/+/main:third_party/qcms/;drc=d4a2f8e1ed461d8fc05ed88d1ae2dc94c9773825 276 2. Build and archive the source files as libqcms.a / qcms.lib 277 3. Update makefile.unix / Makefile.vc 278 1. Define WEBP_HAVE_QCMS 279 2. Update include / library paths to reference the qcms directory. 280 281Build using makefile.unix / Makefile.vc: 282 283```shell 284$ make -f makefile.unix examples/vwebp 285> nmake /f Makefile.vc CFG=release-static \ 286 ../obj/x64/release-static/bin/vwebp.exe 287``` 288 289## Animation creation tool 290 291The utility `img2webp` can turn a sequence of input images (PNG, JPEG, ...) into 292an animated WebP file. It offers fine control over duration, encoding modes, 293etc. 294 295Usage: 296 297```shell 298img2webp [file_options] [[frame_options] frame_file]... [-o webp_file] 299``` 300 301File-level options (only used at the start of compression): 302 303``` 304-min_size ............ minimize size 305-kmax <int> .......... maximum number of frame between key-frames 306 (0=only keyframes) 307-kmin <int> .......... minimum number of frame between key-frames 308 (0=disable key-frames altogether) 309-mixed ............... use mixed lossy/lossless automatic mode 310-near_lossless <int> . use near-lossless image preprocessing 311 (0..100=off), default=100 312-sharp_yuv ........... use sharper (and slower) RGB->YUV conversion 313 (lossy only) 314-loop <int> .......... loop count (default: 0, = infinite loop) 315-v ................... verbose mode 316-h ................... this help 317-version ............. print version number and exit 318``` 319 320Per-frame options (only used for subsequent images input): 321 322``` 323-d <int> ............. frame duration in ms (default: 100) 324-lossless ........... use lossless mode (default) 325-lossy ... ........... use lossy mode 326-q <float> ........... quality 327-m <int> ............. method to use 328``` 329 330example: `img2webp -loop 2 in0.png -lossy in1.jpg -d 80 in2.tiff -o out.webp` 331 332Note: if a single file name is passed as the argument, the arguments will be 333tokenized from this file. The file name must not start with the character '-'. 334 335## Animated GIF conversion 336 337Animated GIF files can be converted to WebP files with animation using the 338gif2webp utility available under examples/. The files can then be viewed using 339vwebp. 340 341Usage: 342 343```shell 344gif2webp [options] gif_file -o webp_file 345``` 346 347Options: 348 349``` 350-h / -help ............. this help 351-lossy ................. encode image using lossy compression 352-mixed ................. for each frame in the image, pick lossy 353 or lossless compression heuristically 354-q <float> ............. quality factor (0:small..100:big) 355-m <int> ............... compression method (0=fast, 6=slowest) 356-min_size .............. minimize output size (default:off) 357 lossless compression by default; can be 358 combined with -q, -m, -lossy or -mixed 359 options 360-kmin <int> ............ min distance between key frames 361-kmax <int> ............ max distance between key frames 362-f <int> ............... filter strength (0=off..100) 363-metadata <string> ..... comma separated list of metadata to 364 copy from the input to the output if present 365 Valid values: all, none, icc, xmp (default) 366-loop_compatibility .... use compatibility mode for Chrome 367 version prior to M62 (inclusive) 368-mt .................... use multi-threading if available 369 370-version ............... print version number and exit 371-v ..................... verbose 372-quiet ................. don't print anything 373``` 374 375### Building 376 377With the libgif development files installed, gif2webp can be built using 378makefile.unix: 379 380```shell 381$ make -f makefile.unix examples/gif2webp 382``` 383 384or using autoconf: 385 386```shell 387$ ./configure --enable-everything 388$ make 389``` 390 391## Comparison of animated images 392 393Test utility anim_diff under examples/ can be used to compare two animated 394images (each can be GIF or WebP). 395 396Usage: 397 398```shell 399anim_diff <image1> <image2> [options] 400``` 401 402Options: 403 404``` 405-dump_frames <folder> dump decoded frames in PAM format 406-min_psnr <float> ... minimum per-frame PSNR 407-raw_comparison ..... if this flag is not used, RGB is 408 premultiplied before comparison 409-max_diff <int> ..... maximum allowed difference per channel 410 between corresponding pixels in subsequent 411 frames 412-h .................. this help 413-version ............ print version number and exit 414``` 415 416### Building 417 418With the libgif development files installed, anim_diff can be built using 419makefile.unix: 420 421```shell 422$ make -f makefile.unix examples/anim_diff 423``` 424 425or using autoconf: 426 427```shell 428$ ./configure --enable-everything 429$ make 430``` 431 432## WebP Mux tool 433 434The examples/ directory contains a tool (webpmux) for manipulating WebP files. 435The webpmux tool can be used to create an extended format WebP file and also to 436extract or strip relevant data from such a file. 437 438A list of options is available using the -help command line flag: 439 440```shell 441> webpmux -help 442Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT 443 webpmux -set SET_OPTIONS INPUT -o OUTPUT 444 webpmux -duration DURATION_OPTIONS [-duration ...] 445 INPUT -o OUTPUT 446 webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT 447 webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT] 448 [-bgcolor BACKGROUND_COLOR] -o OUTPUT 449 webpmux -info INPUT 450 webpmux [-h|-help] 451 webpmux -version 452 webpmux argument_file_name 453 454GET_OPTIONS: 455 Extract relevant data: 456 icc get ICC profile 457 exif get EXIF metadata 458 xmp get XMP metadata 459 frame n get nth frame 460 461SET_OPTIONS: 462 Set color profile/metadata/parameters: 463 loop LOOP_COUNT set the loop count 464 bgcolor BACKGROUND_COLOR set the animation background color 465 icc file.icc set ICC profile 466 exif file.exif set EXIF metadata 467 xmp file.xmp set XMP metadata 468 where: 'file.icc' contains the ICC profile to be set, 469 'file.exif' contains the EXIF metadata to be set 470 'file.xmp' contains the XMP metadata to be set 471 472DURATION_OPTIONS: 473 Set duration of selected frames: 474 duration set duration for all frames 475 duration,frame set duration of a particular frame 476 duration,start,end set duration of frames in the 477 interval [start,end]) 478 where: 'duration' is the duration in milliseconds 479 'start' is the start frame index 480 'end' is the inclusive end frame index 481 The special 'end' value '0' means: last frame. 482 483STRIP_OPTIONS: 484 Strip color profile/metadata: 485 icc strip ICC profile 486 exif strip EXIF metadata 487 xmp strip XMP metadata 488 489FRAME_OPTIONS(i): 490 Create animation: 491 file_i +di[+xi+yi[+mi[bi]]] 492 where: 'file_i' is the i'th animation frame (WebP format), 493 'di' is the pause duration before next frame, 494 'xi','yi' specify the image offset for this frame, 495 'mi' is the dispose method for this frame (0 or 1), 496 'bi' is the blending method for this frame (+b or -b) 497 498LOOP_COUNT: 499 Number of times to repeat the animation. 500 Valid range is 0 to 65535 [Default: 0 (infinite)]. 501 502BACKGROUND_COLOR: 503 Background color of the canvas. 504 A,R,G,B 505 where: 'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying 506 the Alpha, Red, Green and Blue component values respectively 507 [Default: 255,255,255,255] 508 509INPUT & OUTPUT are in WebP format. 510 511Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be 512valid. 513 514Note: if a single file name is passed as the argument, the arguments will be 515tokenized from this file. The file name must not start with the character '-'. 516``` 517
