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> ............. compression method (0=fast, 6=slowest), default=4 328-exact, -noexact ..... preserve or alter RGB values in transparent area 329 (default: -noexact, may cause artifacts 330 with lossy animations) 331``` 332 333example: `img2webp -loop 2 in0.png -lossy in1.jpg -d 80 in2.tiff -o out.webp` 334 335Note: if a single file name is passed as the argument, the arguments will be 336tokenized from this file. The file name must not start with the character '-'. 337 338## Animated GIF conversion 339 340Animated GIF files can be converted to WebP files with animation using the 341gif2webp utility available under examples/. The files can then be viewed using 342vwebp. 343 344Usage: 345 346```shell 347gif2webp [options] gif_file -o webp_file 348``` 349 350Options: 351 352``` 353-h / -help ............. this help 354-lossy ................. encode image using lossy compression 355-mixed ................. for each frame in the image, pick lossy 356 or lossless compression heuristically 357-near_lossless <int> ... use near-lossless image preprocessing 358 (0..100=off), default=100 359-sharp_yuv ............. use sharper (and slower) RGB->YUV conversion 360 (lossy only) 361-q <float> ............. quality factor (0:small..100:big) 362-m <int> ............... compression method (0=fast, 6=slowest), default=4 363-min_size .............. minimize output size (default:off) 364 lossless compression by default; can be 365 combined with -q, -m, -lossy or -mixed 366 options 367-kmin <int> ............ min distance between key frames 368-kmax <int> ............ max distance between key frames 369-f <int> ............... filter strength (0=off..100) 370-metadata <string> ..... comma separated list of metadata to 371 copy from the input to the output if present 372 Valid values: all, none, icc, xmp (default) 373-loop_compatibility .... use compatibility mode for Chrome 374 version prior to M62 (inclusive) 375-mt .................... use multi-threading if available 376 377-version ............... print version number and exit 378-v ..................... verbose 379-quiet ................. don't print anything 380``` 381 382### Building 383 384With the libgif development files installed, gif2webp can be built using 385makefile.unix: 386 387```shell 388$ make -f makefile.unix examples/gif2webp 389``` 390 391or using autoconf: 392 393```shell 394$ ./configure --enable-everything 395$ make 396``` 397 398## Comparison of animated images 399 400Test utility anim_diff under examples/ can be used to compare two animated 401images (each can be GIF or WebP). 402 403Usage: 404 405```shell 406anim_diff <image1> <image2> [options] 407``` 408 409Options: 410 411``` 412-dump_frames <folder> dump decoded frames in PAM format 413-min_psnr <float> ... minimum per-frame PSNR 414-raw_comparison ..... if this flag is not used, RGB is 415 premultiplied before comparison 416-max_diff <int> ..... maximum allowed difference per channel 417 between corresponding pixels in subsequent 418 frames 419-h .................. this help 420-version ............ print version number and exit 421``` 422 423### Building 424 425With the libgif development files installed, anim_diff can be built using 426makefile.unix: 427 428```shell 429$ make -f makefile.unix examples/anim_diff 430``` 431 432or using autoconf: 433 434```shell 435$ ./configure --enable-everything 436$ make 437``` 438 439## WebP Mux tool 440 441The examples/ directory contains a tool (webpmux) for manipulating WebP files. 442The webpmux tool can be used to create an extended format WebP file and also to 443extract or strip relevant data from such a file. 444 445A list of options is available using the -help command line flag: 446 447```shell 448> webpmux -help 449Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT 450 webpmux -set SET_OPTIONS INPUT -o OUTPUT 451 webpmux -duration DURATION_OPTIONS [-duration ...] 452 INPUT -o OUTPUT 453 webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT 454 webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT] 455 [-bgcolor BACKGROUND_COLOR] -o OUTPUT 456 webpmux -info INPUT 457 webpmux [-h|-help] 458 webpmux -version 459 webpmux argument_file_name 460 461GET_OPTIONS: 462 Extract relevant data: 463 icc get ICC profile 464 exif get EXIF metadata 465 xmp get XMP metadata 466 frame n get nth frame 467 468SET_OPTIONS: 469 Set color profile/metadata/parameters: 470 loop LOOP_COUNT set the loop count 471 bgcolor BACKGROUND_COLOR set the animation background color 472 icc file.icc set ICC profile 473 exif file.exif set EXIF metadata 474 xmp file.xmp set XMP metadata 475 where: 'file.icc' contains the ICC profile to be set, 476 'file.exif' contains the EXIF metadata to be set 477 'file.xmp' contains the XMP metadata to be set 478 479DURATION_OPTIONS: 480 Set duration of selected frames: 481 duration set duration for all frames 482 duration,frame set duration of a particular frame 483 duration,start,end set duration of frames in the 484 interval [start,end]) 485 where: 'duration' is the duration in milliseconds 486 'start' is the start frame index 487 'end' is the inclusive end frame index 488 The special 'end' value '0' means: last frame. 489 490STRIP_OPTIONS: 491 Strip color profile/metadata: 492 icc strip ICC profile 493 exif strip EXIF metadata 494 xmp strip XMP metadata 495 496FRAME_OPTIONS(i): 497 Create animation: 498 file_i +di[+xi+yi[+mi[bi]]] 499 where: 'file_i' is the i'th animation frame (WebP format), 500 'di' is the pause duration before next frame, 501 'xi','yi' specify the image offset for this frame, 502 'mi' is the dispose method for this frame (0 or 1), 503 'bi' is the blending method for this frame (+b or -b) 504 505LOOP_COUNT: 506 Number of times to repeat the animation. 507 Valid range is 0 to 65535 [Default: 0 (infinite)]. 508 509BACKGROUND_COLOR: 510 Background color of the canvas. 511 A,R,G,B 512 where: 'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying 513 the Alpha, Red, Green and Blue component values respectively 514 [Default: 255,255,255,255] 515 516INPUT & OUTPUT are in WebP format. 517 518Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be 519valid. 520 521Note: if a single file name is passed as the argument, the arguments will be 522tokenized from this file. The file name must not start with the character '-'. 523``` 524
