1<!--
2
3Although you may be viewing an alternate representation, this document
4is sourced in Markdown, a light-duty markup scheme, and is optimized for
5the [kramdown](http://kramdown.rubyforge.org/) transformer.
6
7See the accompanying README. External link targets are referenced at the
8end of this file.
9
10-->
11
12
13WebP Container Specification
14============================
15
16* TOC placeholder
17{:toc}
18
19
20Introduction
21------------
22
23WebP is an image format that uses either (i) the VP8 key frame encoding
24to compress image data in a lossy way, or (ii) the WebP lossless encoding
25(and possibly other encodings in the future). These encoding schemes should
26make it more efficient than currently used formats. It is optimized for fast
27image transfer over the network (e.g., for websites). The WebP format has
28feature parity (color profile, metadata, animation etc) with other formats as
29well. This document describes the structure of a WebP file.
30
31The WebP container (i.e., RIFF container for WebP) allows feature support over
32and above the basic use case of WebP (i.e., a file containing a single image
33encoded as a VP8 key frame). The WebP container provides additional support
34for:
35
36  * **Lossless compression.** An image can be losslessly compressed, using the
37    WebP Lossless Format.
38
39  * **Metadata.** An image may have metadata stored in EXIF or XMP formats.
40
41  * **Transparency.** An image may have transparency, i.e., an alpha channel.
42
43  * **Color Profile.** An image may have an embedded ICC profile as described
44    by the [International Color Consortium][iccspec].
45
46  * **Animation.** An image may have multiple frames with pauses between them,
47    making it an animation.
48
49The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
50"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
51document are to be interpreted as described in [RFC 2119][].
52
53Bit numbering in chunk diagrams starts at `0` for the most significant bit
54('MSB 0') as described in [RFC 1166][].
55
56**Note:** Out of the features mentioned above, lossy compression, lossless
57compression, transparency, metadata, color profile and animation are finalized
58and are to be considered stable.
59
60Terminology &amp; Basics
61------------------------
62
63A WebP file contains either a still image (i.e., an encoded matrix of pixels)
64or an [animation](#animation). Optionally, it can also contain transparency
65information, color profile and metadata. In case we need to refer only to the
66matrix of pixels, we will call it the _canvas_ of the image.
67
68Below are additional terms used throughout this document:
69
70_Reader/Writer_
71
72: Code that reads WebP files is referred to as a _reader_, while code that
73  writes them is referred to as a _writer_.
74
75_uint16_
76
77: A 16-bit, little-endian, unsigned integer.
78
79_uint24_
80
81: A 24-bit, little-endian, unsigned integer.
82
83_uint32_
84
85: A 32-bit, little-endian, unsigned integer.
86
87_FourCC_
88
89: A _FourCC_ (four-character code) is a _uint32_ created by concatenating four
90  ASCII characters in little-endian order.
91
92_1-based_
93
94: An unsigned integer field storing values offset by `-1`. e.g., Such a field
95  would store value _25_ as _24_.
96
97
98RIFF File Format
99----------------
100
101The WebP file format is based on the RIFF (resource interchange file format)
102document format.
103
104The basic element of a RIFF file is a _chunk_. It consists of:
105
106     0                   1                   2                   3
107     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
108    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
109    |                         Chunk FourCC                          |
110    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
111    |                          Chunk Size                           |
112    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
113    |                         Chunk Payload                         |
114    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
115
116Chunk FourCC: 32 bits
117
118: ASCII four-character code used for chunk identification.
119
120Chunk Size: 32 bits (_uint32_)
121
122: The size of the chunk not including this field, the chunk identifier or
123  padding.
124
125Chunk Payload: _Chunk Size_ bytes
126
127: The data payload. If _Chunk Size_ is odd, a single padding byte -- that
128  SHOULD be `0` -- is added.
129
130_ChunkHeader('ABCD')_
131
132: This is used to describe the _FourCC_ and _Chunk Size_ header of individual
133  chunks, where 'ABCD' is the FourCC for the chunk. This element's
134  size is 8 bytes.
135
136**Note:** RIFF has a convention that all-uppercase chunk FourCCs are standard
137chunks that apply to any RIFF file format, while FourCCs specific to a file
138format are all lowercase. WebP does not follow this convention.
139
140
141WebP File Header
142----------------
143
144     0                   1                   2                   3
145     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
146    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
147    |      'R'      |      'I'      |      'F'      |      'F'      |
148    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
149    |                           File Size                           |
150    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
151    |      'W'      |      'E'      |      'B'      |      'P'      |
152    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
153
154'RIFF': 32 bits
155
156: The ASCII characters 'R' 'I' 'F' 'F'.
157
158File Size: 32 bits (_uint32_)
159
160: The size of the file in bytes starting at offset 8. The maximum value of
161  this field is 2^32 minus 10 bytes and thus the size of the whole file is at
162  most 4GiB minus 2 bytes.
163
164'WEBP': 32 bits
165
166: The ASCII characters 'W' 'E' 'B' 'P'.
167
168A WebP file MUST begin with a RIFF header with the FourCC 'WEBP'. The file size
169in the header is the total size of the chunks that follow plus `4` bytes for
170the 'WEBP' FourCC. The file SHOULD NOT contain anything after it. As the size
171of any chunk is even, the size given by the RIFF header is also even. The
172contents of individual chunks will be described in the following sections.
173
174
175Simple File Format (Lossy)
176--------------------------
177
178This layout SHOULD be used if the image requires _lossy_ encoding and does not
179require transparency or other advanced features provided by the extended format.
180Files with this layout are smaller and supported by older software.
181
182Simple WebP (lossy) file format:
183
184     0                   1                   2                   3
185     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
186    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
187    |                    WebP file header (12 bytes)                |
188    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
189    |                          VP8 chunk                            |
190    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
191
192VP8 chunk:
193
194     0                   1                   2                   3
195     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
196    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
197    |                      ChunkHeader('VP8 ')                      |
198    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
199    |                           VP8 data                            |
200    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
201
202VP8 data: _Chunk Size_ bytes
203
204: VP8 bitstream data.
205
206The VP8 bitstream format specification can be found at [VP8 Data Format and
207Decoding Guide][vp8spec]. Note that the VP8 frame header contains the VP8 frame
208width and height. That is assumed to be the width and height of the canvas.
209
210The VP8 specification describes how to decode the image into Y'CbCr
211format. To convert to RGB, Rec. 601 SHOULD be used.
212
213
214Simple File Format (Lossless)
215-----------------------------
216
217**Note:** Older readers may not support files using the lossless format.
218
219This layout SHOULD be used if the image requires _lossless_ encoding (with an
220optional transparency channel) and does not require advanced features provided
221by the extended format.
222
223Simple WebP (lossless) file format:
224
225     0                   1                   2                   3
226     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
227    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
228    |                    WebP file header (12 bytes)                |
229    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
230    |                          VP8L chunk                           |
231    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
232
233VP8L chunk:
234
235     0                   1                   2                   3
236     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
237    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
238    |                      ChunkHeader('VP8L')                      |
239    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
240    |                           VP8L data                           |
241    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
242
243VP8L data: _Chunk Size_ bytes
244
245: VP8L bitstream data.
246
247The current specification of the VP8L bitstream can be found at
248[WebP Lossless Bitstream Format][webpllspec]. Note that the VP8L header
249contains the VP8L image width and height. That is assumed to be the width
250and height of the canvas.
251
252
253Extended File Format
254--------------------
255
256**Note:** Older readers may not support files using the extended format.
257
258An extended format file consists of:
259
260  * A 'VP8X' chunk with information about features used in the file.
261
262  * An optional 'ICCP' chunk with color profile.
263
264  * An optional 'ANIM' chunk with animation control data.
265
266  * Image data.
267
268  * An optional 'EXIF' chunk with EXIF metadata.
269
270  * An optional 'XMP ' chunk with XMP metadata.
271
272  * An optional list of [unknown chunks](#unknown-chunks). _\[status: experimental\]_
273
274For a _still image_, the _image data_ consists of a single frame, which is made
275up of:
276
277  * An optional [alpha subchunk](#alpha).
278
279  * A [bitstream subchunk](#bitstream-vp8vp8l).
280
281For an _animated image_, the _image data_ consists of multiple frames. More
282details about frames can be found in the [Animation](#animation) section.
283
284All chunks SHOULD be placed in the same order as listed above. If a chunk
285appears in the wrong place, the file is invalid, but readers MAY parse the
286file, ignoring the chunks that come too late.
287
288**Rationale:** Setting the order of chunks should allow quicker file
289parsing. For example, if an 'ALPH' chunk does not appear in its required
290position, a decoder can choose to stop searching for it. The rule of
291ignoring late chunks should make programs that need to do a full search
292give the same results as the ones stopping early.
293
294Extended WebP file header:
295{:#extended_header}
296
297     0                   1                   2                   3
298     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
299    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
300    |                   WebP file header (12 bytes)                 |
301    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
302    |                      ChunkHeader('VP8X')                      |
303    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
304    |Rsv|I|L|E|X|A|R|                   Reserved                    |
305    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
306    |          Canvas Width Minus One               |             ...
307    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
308    ...  Canvas Height Minus One    |
309    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
310
311Reserved (Rsv): 2 bits
312
313: SHOULD be `0`.
314
315ICC profile (I): 1 bit
316
317: Set if the file contains an ICC profile.
318
319Alpha (L): 1 bit
320
321: Set if any of the frames of the image contain transparency information
322  ("alpha").
323
324EXIF metadata (E): 1 bit
325
326: Set if the file contains EXIF metadata.
327
328XMP metadata (X): 1 bit
329
330: Set if the file contains XMP metadata.
331
332Animation (A): 1 bit
333
334: Set if this is an animated image. Data in 'ANIM' and 'ANMF' chunks should be
335  used to control the animation.
336
337Reserved (R): 1 bit
338
339: SHOULD be `0`.
340
341Reserved: 24 bits
342
343: SHOULD be `0`.
344
345Canvas Width Minus One: 24 bits
346
347: _1-based_ width of the canvas in pixels.
348  The actual canvas width is '1 + Canvas Width Minus One'
349
350Canvas Height Minus One: 24 bits
351
352: _1-based_ height of the canvas in pixels.
353  The actual canvas height is '1 + Canvas Height Minus One'
354
355The product of _Canvas Width_ and _Canvas Height_ MUST be at most `2^32 - 1`.
356
357Future specifications MAY add more fields.
358
359### Chunks
360
361#### Animation
362
363An animation is controlled by ANIM and ANMF chunks.
364
365ANIM Chunk:
366{:#anim_chunk}
367
368For an animated image, this chunk contains the _global parameters_ of the
369animation.
370
371     0                   1                   2                   3
372     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
373    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
374    |                      ChunkHeader('ANIM')                      |
375    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
376    |                       Background Color                        |
377    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
378    |          Loop Count           |
379    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
380
381Background Color: 32 bits (_uint32_)
382
383: The default background color of the canvas in \[Blue, Green, Red, Alpha\]
384  byte order. This color MAY be used to fill the unused space on the canvas
385  around the frames, as well as the transparent pixels of the first frame.
386  Background color is also used when disposal method is `1`.
387
388**Note**:
389
390  * Background color MAY contain a transparency value (alpha), even if the
391    _Alpha_ flag in [VP8X chunk](#extended_header) is unset.
392
393  * Viewer applications SHOULD treat the background color value as a hint, and
394    are not required to use it.
395
396  * The canvas is cleared at the start of each loop. The background color MAY be
397    used to achieve this.
398
399Loop Count: 16 bits (_uint16_)
400
401: The number of times to loop the animation. `0` means infinitely.
402
403This chunk MUST appear if the _Animation_ flag in the VP8X chunk is set.
404If the _Animation_ flag is not set and this chunk is present, it
405SHOULD be ignored.
406
407ANMF chunk:
408
409For animated images, this chunk contains information about a _single_ frame.
410If the _Animation flag_ is not set, then this chunk SHOULD NOT be present.
411
412     0                   1                   2                   3
413     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
414    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
415    |                      ChunkHeader('ANMF')                      |
416    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
417    |                        Frame X                |             ...
418    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
419    ...          Frame Y            |   Frame Width Minus One     ...
420    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
421    ...             |           Frame Height Minus One              |
422    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
423    |                 Frame Duration                |  Reserved |B|D|
424    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
425    |                         Frame Data                            |
426    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
427
428Frame X: 24 bits (_uint24_)
429
430: The X coordinate of the upper left corner of the frame is `Frame X * 2`
431
432Frame Y: 24 bits (_uint24_)
433
434: The Y coordinate of the upper left corner of the frame is `Frame Y * 2`
435
436Frame Width Minus One: 24 bits (_uint24_)
437
438: The _1-based_ width of the frame.
439  The frame width is `1 + Frame Width Minus One`
440
441Frame Height Minus One: 24 bits (_uint24_)
442
443: The _1-based_ height of the frame.
444  The frame height is `1 + Frame Height Minus One`
445
446Frame Duration: 24 bits (_uint24_)
447
448: The time to wait before displaying the next frame, in 1 millisecond units.
449  Note the interpretation of frame duration of 0 (and often <= 10) is
450  implementation defined. Many tools and browsers assign a minimum duration
451  similar to GIF.
452
453Reserved: 6 bits
454
455: SHOULD be 0.
456
457Blending method (B): 1 bit
458
459: Indicates how transparent pixels of _the current frame_ are to be blended
460  with corresponding pixels of the previous canvas:
461
462    * `0`: Use alpha blending. After disposing of the previous frame, render the
463      current frame on the canvas using [alpha-blending](#alpha-blending). If
464      the current frame does not have an alpha channel, assume alpha value of
465      255, effectively replacing the rectangle.
466
467    * `1`: Do not blend. After disposing of the previous frame, render the
468      current frame on the canvas by overwriting the rectangle covered by the
469      current frame.
470
471Disposal method (D): 1 bit
472
473: Indicates how _the current frame_ is to be treated after it has been
474  displayed (before rendering the next frame) on the canvas:
475
476    * `0`: Do not dispose. Leave the canvas as is.
477
478    * `1`: Dispose to background color. Fill the _rectangle_ on the canvas
479      covered by the _current frame_ with background color specified in the
480      [ANIM chunk](#anim_chunk).
481
482**Notes**:
483
484  * The frame disposal only applies to the _frame rectangle_, that is, the
485    rectangle defined by _Frame X_, _Frame Y_, _frame width_ and _frame height_.
486    It may or may not cover the whole canvas.
487
488{:#alpha-blending}
489  * **Alpha-blending**:
490
491    Given that each of the R, G, B and A channels is 8-bit, and the RGB
492    channels are _not premultiplied_ by alpha, the formula for blending
493    'dst' onto 'src' is:
494
495~~~~~
496    blend.A = src.A + dst.A * (1 - src.A / 255)
497    if blend.A = 0 then
498      blend.RGB = 0
499    else
500      blend.RGB = (src.RGB * src.A +
501                   dst.RGB * dst.A * (1 - src.A / 255)) / blend.A
502~~~~~
503
504  * Alpha-blending SHOULD be done in linear color space, by taking into account
505    the [color profile](#color-profile) of the image. If the color profile is
506    not present, sRGB is to be assumed. (Note that sRGB also needs to be
507    linearized due to a gamma of ~2.2).
508
509Frame Data: _Chunk Size_ - `16` bytes
510
511: Consists of:
512
513  * An optional [alpha subchunk](#alpha) for the frame.
514
515  * A [bitstream subchunk](#bitstream-vp8vp8l) for the frame.
516
517  * An optional list of [unknown chunks](#unknown-chunks).
518
519**Note**: The 'ANMF' payload, _Frame Data_ above, consists of individual
520_padded_ chunks as described by the [RIFF file format](#riff-file-format).
521
522#### Alpha
523
524     0                   1                   2                   3
525     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
526    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
527    |                      ChunkHeader('ALPH')                      |
528    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
529    |Rsv| P | F | C |     Alpha Bitstream...                        |
530    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
531
532Reserved (Rsv): 2 bits
533
534: SHOULD be `0`.
535
536Pre-processing (P): 2 bits
537
538: These INFORMATIVE bits are used to signal the pre-processing that has
539  been performed during compression. The decoder can use this information to
540  e.g. dither the values or smooth the gradients prior to display.
541
542    * `0`: no pre-processing
543    * `1`: level reduction
544
545Filtering method (F): 2 bits
546
547: The filtering method used:
548
549    * `0`: None.
550    * `1`: Horizontal filter.
551    * `2`: Vertical filter.
552    * `3`: Gradient filter.
553
554For each pixel, filtering is performed using the following calculations.
555Assume the alpha values surrounding the current `X` position are labeled as:
556
557     C | B |
558    ---+---+
559     A | X |
560
561We seek to compute the alpha value at position `X`. First, a prediction is
562made depending on the filtering method:
563
564  * Method `0`: predictor = 0
565  * Method `1`: predictor = A
566  * Method `2`: predictor = B
567  * Method `3`: predictor = clip(A + B - C)
568
569where `clip(v)` is equal to:
570
571  * 0    if v < 0
572  * 255  if v > 255
573  * v    otherwise
574
575The final value is derived by adding the decompressed value `X` to the
576predictor and using modulo-256 arithmetic to wrap the \[256-511\] range
577into the \[0-255\] one:
578
579`alpha = (predictor + X) % 256`
580
581There are special cases for left-most and top-most pixel positions:
582
583  * Top-left value at location (0,0) uses 0 as predictor value. Otherwise,
584  * For horizontal or gradient filtering methods, the left-most pixels at
585    location (0, y) are predicted using the location (0, y-1) just above.
586  * For vertical or gradient filtering methods, the top-most pixels at
587    location (x, 0) are predicted using the location (x-1, 0) on the left.
588
589
590Decoders are not required to use this information in any specified way.
591
592Compression method (C): 2 bits
593
594: The compression method used:
595
596    * `0`: No compression.
597    * `1`: Compressed using the WebP lossless format.
598
599Alpha bitstream: _Chunk Size_ - `1` bytes
600
601: Encoded alpha bitstream.
602
603This optional chunk contains encoded alpha data for this frame. A frame
604containing a 'VP8L' chunk SHOULD NOT contain this chunk.
605
606**Rationale**: The transparency information is already part of the 'VP8L'
607chunk.
608
609The alpha channel data is stored as uncompressed raw data (when
610compression method is '0') or compressed using the lossless format
611(when the compression method is '1').
612
613  * Raw data: consists of a byte sequence of length width * height,
614    containing all the 8-bit transparency values in scan order.
615
616  * Lossless format compression: the byte sequence is a compressed
617    image-stream (as described in the [WebP Lossless Bitstream Format]
618    [webpllspec]) of implicit dimension width x height. That is, this
619    image-stream does NOT contain any headers describing the image dimension.
620
621    **Rationale**: the dimension is already known from other sources,
622    so storing it again would be redundant and error-prone.
623
624    Once the image-stream is decoded into ARGB color values, following
625    the process described in the lossless format specification, the
626    transparency information must be extracted from the *green* channel
627    of the ARGB quadruplet.
628
629    **Rationale**: the green channel is allowed extra transformation
630    steps in the specification -- unlike the other channels -- that can
631    improve compression.
632
633#### Bitstream (VP8/VP8L)
634
635This chunk contains compressed bitstream data for a single frame.
636
637A bitstream chunk may be either (i) a VP8 chunk, using "VP8 " (note the
638significant fourth-character space) as its tag _or_ (ii) a VP8L chunk, using
639"VP8L" as its tag.
640
641The formats of VP8 and VP8L chunks are as described in sections
642[Simple File Format (Lossy)](#simple-file-format-lossy)
643and [Simple File Format (Lossless)](#simple-file-format-lossless) respectively.
644
645#### Color profile
646
647     0                   1                   2                   3
648     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
649    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
650    |                      ChunkHeader('ICCP')                      |
651    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
652    |                       Color Profile                           |
653    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
654
655Color Profile: _Chunk Size_ bytes
656
657: ICC profile.
658
659This chunk MUST appear before the image data.
660
661There SHOULD be at most one such chunk. If there are more such chunks, readers
662MAY ignore all except the first one.
663See the [ICC Specification][iccspec] for details.
664
665If this chunk is not present, sRGB SHOULD be assumed.
666
667#### Metadata
668
669Metadata can be stored in 'EXIF' or 'XMP ' chunks.
670
671There SHOULD be at most one chunk of each type ('EXIF' and 'XMP '). If there
672are more such chunks, readers MAY ignore all except the first one. Also, a file
673may possibly contain both 'EXIF' and 'XMP ' chunks.
674
675The chunks are defined as follows:
676
677EXIF chunk:
678
679     0                   1                   2                   3
680     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
681    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
682    |                      ChunkHeader('EXIF')                      |
683    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
684    |                        EXIF Metadata                          |
685    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
686
687EXIF Metadata: _Chunk Size_ bytes
688
689: image metadata in EXIF format.
690
691XMP chunk:
692
693     0                   1                   2                   3
694     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
695    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
696    |                      ChunkHeader('XMP ')                      |
697    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
698    |                        XMP Metadata                           |
699    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
700
701XMP Metadata: _Chunk Size_ bytes
702
703: image metadata in XMP format.
704
705Additional guidance about handling metadata can be found in the
706Metadata Working Group's [Guidelines for Handling Metadata][metadata].
707
708#### Unknown Chunks _\[status: experimental\]_
709
710A RIFF chunk (described in [this](#terminology-amp-basics) section) whose _chunk
711tag_ is different from any of the chunks described in this document, is
712considered an _unknown chunk_.
713
714**Rationale**: Allowing unknown chunks gives a provision for future extension
715of the format, and also allows storage of any application-specific data.
716
717A file MAY contain unknown chunks:
718
719  * At the end of the file as described in [Extended WebP file
720    header](#extended_header) section.
721  * At the end of ANMF chunks as described in the
722    [Animation](#animation) section.
723
724Readers SHOULD ignore these chunks. Writers SHOULD preserve them in their
725original order (unless they specifically intend to modify these chunks).
726
727### Assembling the Canvas from frames
728
729Here we provide an overview of how a reader should assemble a canvas in the
730case of an animated image. The notation _VP8X.field_ means the field in the
731'VP8X' chunk with the same description.
732
733Displaying an _animated image_ canvas MUST be equivalent to the following
734pseudocode:
735
736~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
737assert VP8X.flags.hasAnimation
738canvas ← new image of size VP8X.canvasWidth x VP8X.canvasHeight with
739         background color ANIM.background_color.
740loop_count ← ANIM.loopCount
741dispose_method ← ANIM.disposeMethod
742if loop_count == 0:
743    loop_count = ∞
744frame_params ← nil
745assert next chunk in image_data is ANMF
746for loop = 0..loop_count - 1
747    clear canvas to ANIM.background_color or application defined color
748    until eof or non-ANMF chunk
749        frame_params.frameX = Frame X
750        frame_params.frameY = Frame Y
751        frame_params.frameWidth = Frame Width Minus One + 1
752        frame_params.frameHeight = Frame Height Minus One + 1
753        frame_params.frameDuration = Frame Duration
754        frame_right = frame_params.frameX + frame_params.frameWidth
755        frame_bottom = frame_params.frameY + frame_params.frameHeight
756        assert VP8X.canvasWidth >= frame_right
757        assert VP8X.canvasHeight >= frame_bottom
758        for subchunk in 'Frame Data':
759            if subchunk.tag == "ALPH":
760                assert alpha subchunks not found in 'Frame Data' earlier
761                frame_params.alpha = alpha_data
762            else if subchunk.tag == "VP8 " OR subchunk.tag == "VP8L":
763                assert bitstream subchunks not found in 'Frame Data' earlier
764                frame_params.bitstream = bitstream_data
765        render frame with frame_params.alpha and frame_params.bitstream on
766            canvas with top-left corner at (frame_params.frameX,
767            frame_params.frameY), using dispose method dispose_method.
768        canvas contains the decoded image.
769        Show the contents of the canvas for frame_params.frameDuration * 1ms.
770~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
771
772
773Example File Layouts
774--------------------
775
776A lossy encoded image with alpha may look as follows:
777
778~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
779RIFF/WEBP
780+- VP8X (descriptions of features used)
781+- ALPH (alpha bitstream)
782+- VP8 (bitstream)
783~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
784
785A losslessly encoded image may look as follows:
786
787~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
788RIFF/WEBP
789+- VP8X (descriptions of features used)
790+- XYZW (unknown chunk)
791+- VP8L (lossless bitstream)
792~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
793
794A lossless image with ICC profile and XMP metadata may
795look as follows:
796
797~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
798RIFF/WEBP
799+- VP8X (descriptions of features used)
800+- ICCP (color profile)
801+- VP8L (lossless bitstream)
802+- XMP  (metadata)
803~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
804
805An animated image with EXIF metadata may look as follows:
806
807~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
808RIFF/WEBP
809+- VP8X (descriptions of features used)
810+- ANIM (global animation parameters)
811+- ANMF (frame1 parameters + data)
812+- ANMF (frame2 parameters + data)
813+- ANMF (frame3 parameters + data)
814+- ANMF (frame4 parameters + data)
815+- EXIF (metadata)
816~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
817
818[vp8spec]:  http://tools.ietf.org/html/rfc6386
819[webpllspec]: https://chromium.googlesource.com/webm/libwebp/+/master/doc/webp-lossless-bitstream-spec.txt
820[iccspec]: http://www.color.org/icc_specs2.xalter
821[metadata]: http://www.metadataworkinggroup.org/pdf/mwg_guidance.pdf
822[rfc 1166]: http://tools.ietf.org/html/rfc1166
823[rfc 2119]: http://tools.ietf.org/html/rfc2119
824