WebP Container API Documentation

RIFF container manipulation for WebP images.

Mux API

Allows manipulation of WebP container images, containing features like color profile, metadata, animation and fragmented images.

Code Examples

Create a MUX with Image Data, Color Profile and XMP Metadata

 int copy_data = 0;
WebPMux* mux = WebPMuxNew();
// ... (Prepare image data).
WebPMuxSetImage(mux, &image, copy_data);
// ... (Prepare ICCP color profile data).
WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
// ... (Prepare XMP metadata).
WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
// Get data from mux in WebP RIFF format.
WebPMuxAssemble(mux, &output_data);
WebPMuxDelete(mux);
// ... (Consume output_data; e.g. write output_data.bytes to file).
WebPDataClear(&output_data); 

Get Image and Color Profile Data from a WebP File

 int copy_data = 0;
// ... (Read data from file).
WebPMux* mux = WebPMuxCreate(&data, copy_data);
WebPMuxGetFrame(mux, 1, &image);
// ... (Consume image; e.g. call WebPDecode() to decode the data).
WebPMuxGetChunk(mux, "ICCP", &icc_profile);
// ... (Consume icc_data).
WebPMuxDelete(mux);
free(data); 

Life of a Mux Object

Enums

  // 
  
 Error 
  
 codes 
 typedef 
  
 enum 
  
 WebPMuxError 
  
 { 
  
 WEBP_MUX_OK 
  
 = 
  
 1 
 , 
  
 WEBP_MUX_NOT_FOUND 
  
 = 
  
 0 
 , 
  
 WEBP_MUX_INVALID_ARGUMENT 
  
 = 
  
 - 
 1 
 , 
  
 WEBP_MUX_BAD_DATA 
  
 = 
  
 - 
 2 
 , 
  
 WEBP_MUX_MEMORY_ERROR 
  
 = 
  
 - 
 3 
 , 
  
 WEBP_MUX_NOT_ENOUGH_DATA 
  
 = 
  
 - 
 4 
 } 
  
 WebPMuxError 
 ; 
 // 
  
 IDs 
  
 for 
  
 different 
  
 types 
  
 of 
  
 chunks 
 . 
 typedef 
  
 enum 
  
 WebPChunkId 
  
 { 
  
 WEBP_CHUNK_VP8X 
 , 
  
 // 
  
 VP8X 
  
 WEBP_CHUNK_ICCP 
 , 
  
 // 
  
 ICCP 
  
 WEBP_CHUNK_ANIM 
 , 
  
 // 
  
 ANIM 
  
 WEBP_CHUNK_ANMF 
 , 
  
 // 
  
 ANMF 
  
 WEBP_CHUNK_ALPHA 
 , 
  
 // 
  
 ALPH 
  
 WEBP_CHUNK_IMAGE 
 , 
  
 // 
  
 VP8 
 / 
 VP8L 
  
 WEBP_CHUNK_EXIF 
 , 
  
 // 
  
 EXIF 
  
 WEBP_CHUNK_XMP 
 , 
  
 // 
  
 XMP 
  
 WEBP_CHUNK_UNKNOWN 
 , 
  
 // 
  
 Other 
  
 chunks 
 . 
  
 WEBP_CHUNK_NIL 
 } 
  
 WebPChunkId 
 ; 
 

WebPGetMuxVersion()

Returns the version number of the mux library, packed in hexadecimal using 8 bits for each of major/minor/revision. E.g., v2.5.7 is 0x020507 .

 int WebPGetMuxVersion(void); 

WebPMuxNew()

Creates an empty mux object.

 WebPMux* WebPMuxNew(void); 

Returns

A pointer to the newly created empty mux object.

WebPMuxDelete()

Deletes the mux object.

 void WebPMuxDelete(WebPMux* mux); 

Parameters

mux-- (in/out) object to be deleted

Mux Creation

WebPMuxCreate()

Creates a mux object from raw data given in WebP RIFF format.

  WebPMux 
 * 
  
 WebPMuxCreate 
 ( 
 const 
  
 WebPData 
 * 
  
 bitstream 
 , 
  
 int 
  
 copy_data 
 ); 
 

Parameters

bitstream-- (in) the bitstream data in WebP RIFF format

copy_data-- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the muxobject.

Returns

A pointerto the mux object created from given data - on success.

NULL-- In case of invalid data or memory error.

Non-Image Chunks

WebPMuxSetChunk()

Adds a chunk with id fourccand data chunk_datain the mux object. Any existing chunk(s) with the same id will be removed.

  WebPMuxError 
  
 WebPMuxSetChunk 
 ( 
 WebPMux 
 * 
  
 mux 
 , 
  
 const 
  
 char 
  
 fourcc 
 [ 
 4 
 ], 
  
 const 
  
 WebPData 
 * 
  
 chunk_data 
 , 
  
 int 
  
 copy_data 
 ); 
 

Note:Only non-image related chunks should be managed through chunk APIs. (Image related chunks are: "ANMF", "FRGM", "VP8 ", "VP8L" and "ALPH"). To add, get and delete images, use WebPMuxSetImage() , WebPMuxPushFrame() , WebPMuxGetFrame() and WebPMuxDeleteFrame() .

Parameters

mux-- (in/out) object to which the chunk is to be added

fourcc-- (in) a character array containing the fourcc of the given chunk; e.g., "ICCP", "XMP ", "EXIF" etc.

chunk_data-- (in) the chunk data to be added

copy_data-- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the muxobject.

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux, fourcc or chunk_data is NULL or if fourcc corresponds to an image chunk.

WEBP_MUX_MEMORY_ERROR -- on memory allocation error.

WEBP_MUX_OK -- on success.

WebPMuxGetChunk()

Gets a reference to the data of the chunk with id fourccin the mux object. The caller should NOT free the returned data.

  WebPMuxError 
  
 WebPMuxGetChunk 
 ( 
 const 
  
 WebPMux 
 * 
  
 mux 
 , 
  
 const 
  
 char 
  
 fourcc 
 [ 
 4 
 ], 
  
 WebPData 
 * 
  
 chunk_data 
 ); 
 

Parameters

mux-- (in) object from which the chunk data is to be fetched

fourcc-- (in) a character array containing the fourcc of the chunk; e.g., "ICCP", "XMP ", "EXIF" etc.

chunk_data-- (out) returned chunk data

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux, fourcc or chunk_data is NULL or if fourcc corresponds to an image chunk.

WEBP_MUX_NOT_FOUND -- If mux does not contain a chunk with the given id.

WEBP_MUX_OK -- on success.

WebPMuxDeleteChunk()

Deletes the chunk with the given fourccfrom the mux object.

  WebPMuxError 
  
 WebPMuxDeleteChunk 
 ( 
 WebPMux 
 * 
  
 mux 
 , 
  
 const 
  
 char 
  
 fourcc 
 [ 
 4 
 ]); 
 

Parameters

mux-- (in/out) object from which the chunk is to be deleted

fourcc-- (in) a character array containing the fourcc of the chunk; e.g., "ICCP", "XMP ", "EXIF" etc.

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux or fourcc is NULL or if fourcc corresponds to an image chunk.

WEBP_MUX_NOT_FOUND -- If mux does not contain a chunk with the given fourcc.

WEBP_MUX_OK -- on success.

Images

Encapsulates data about a single frame/fragment.

  struct 
  
 WebPMuxFrameInfo 
  
 { 
  
 WebPData 
  
 bitstream 
 ; 
  
 // image data: can be a raw VP8/VP8L bitstream 
  
 // or a single-image WebP file. 
  
 int 
  
 x_offset 
 ; 
  
 // x-offset of the frame. 
  
 int 
  
 y_offset 
 ; 
  
 // y-offset of the frame. 
  
 int 
  
 duration 
 ; 
  
 // duration of the frame (in milliseconds). 
  
 WebPChunkId 
  
 id 
 ; 
  
 // frame type: should be one of WEBP_CHUNK_ANMF, 
  
 // WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE 
  
 WebPMuxAnimDispose 
  
 dispose_method 
 ; 
  
 // Disposal method for the frame. 
  
 WebPMuxAnimBlend 
  
 blend_method 
 ; 
  
 // Blend operation for the frame. 
 }; 
 

WebPMuxSetImage()

Sets the (non-animated and non-fragmented) image in the mux object. Note:Any existing images (including frames/fragments) will be removed.

  WebPMuxError 
  
 WebPMuxSetImage 
 ( 
 WebPMux 
 * 
  
 mux 
 , 
  
 const 
  
 WebPData 
 * 
  
 bitstream 
 , 
  
 int 
  
 copy_data 
 ); 
 

Parameters

mux-- (in/out) object in which the image is to be set

bitstream-- (in) can be a raw VP8/VP8L bitstream or a single-image WebP file (non-animated and non-fragmented)

copy_data-- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the muxobject.

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux is NULL or bitstream is NULL.

WEBP_MUX_MEMORY_ERROR -- on memory allocation error.

WEBP_MUX_OK -- on success.

WebPMuxPushFrame()

Adds a frame at the end of the mux object.

  WebPMuxError 
  
 WebPMuxPushFrame 
 ( 
 WebPMux 
 * 
  
 mux 
 , 
  
 const 
  
 WebPMuxFrameInfo 
 * 
  
 frame 
 , 
  
 int 
  
 copy_data 
 ); 
 

Notes:

1. frame.id should be one of WEBP_CHUNK_ANMF or WEBP_CHUNK_FRGM
2. For setting a non-animated non-fragmented image, use WebPMuxSetImage() instead.
3. Type of frame being pushed must be same as the frames in mux.
4. As WebP only supports even offsets, any odd offset will be snapped to an even location using: offset &= ~1

Parameters

mux-- (in/out) object to which the frame is to be added

frame-- (in) frame data.

copy_data-- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the muxobject.

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL or if content of frameis invalid.

WEBP_MUX_MEMORY_ERROR -- on memory allocation error.

WEBP_MUX_OK -- on success.

WEBP_MUX_MEMORY_ERROR -- on memory allocation error.

WebPMuxGetFrame()

Gets the nth frame from the mux object. The content of frame->bitstreamis allocated using malloc(), and NOT owned by the muxobject. It MUST be deallocated by the caller by calling WebPDataClear() . nth=0 has a special meaning - last position.

  WebPMuxError 
  
 WebPMuxGetFrame 
 ( 
 const 
  
 WebPMux 
 * 
  
 mux 
 , 
  
 uint32_t 
  
 nth 
 , 
  
 WebPMuxFrameInfo 
 * 
  
 frame 
 ); 
 

Parameters

mux-- (in) object from which the info is to be fetched

nth-- (in) index of the frame in the mux object

frame-- (out) data of the returned frame

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL.

WEBP_MUX_NOT_FOUND -- if there are less than nth frames in the mux object.

WEBP_MUX_BAD_DATA -- if nth frame chunk in mux is invalid.

WEBP_MUX_OK -- on success.

WebPMuxDeleteFrame()

Deletes a frame from the mux object. nth=0 has a special meaning - last position.

 WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth); 

Parameters

mux-- (in/out) object from which a frame is to be deleted

nth-- (in) The position from which the frame is to be deleted

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux is NULL.

WEBP_MUX_NOT_FOUND -- If there are less than nth frames in the mux object before deletion.

WEBP_MUX_OK -- on success.

Animation

Animation Parameters

  struct 
  
 WebPMuxAnimParams 
  
 { 
  
 uint32_t 
  
 bgcolor 
 ; 
  
 // 
  
 Background 
  
 color 
  
 of 
  
 the 
  
 canvas 
  
 stored 
  
 (in 
  
 MSB 
  
 order) 
  
 as 
 : 
  
 // 
  
 Bits 
  
 00 
  
 to 
  
 07 
 : 
  
 Alpha 
 . 
  
 // 
  
 Bits 
  
 08 
  
 to 
  
 15 
 : 
  
 Red 
 . 
  
 // 
  
 Bits 
  
 16 
  
 to 
  
 23 
 : 
  
 Green 
 . 
  
 // 
  
 Bits 
  
 24 
  
 to 
  
 31 
 : 
  
 Blue 
 . 
  
 int 
  
 loop_count 
 ; 
  
 // 
  
 Number 
  
 of 
  
 times 
  
 to 
  
 repeat 
  
 the 
  
 animation 
  
 [ 
 0 
  
 = 
  
 infinite 
 ] 
 . 
 } 
 ; 
 

WebPMuxSetAnimationParams()

Sets the animation parameters in the mux object. Any existing ANIM chunks will be removed.

  WebPMuxError 
  
 WebPMuxSetAnimationParams 
 ( 
 WebPMux 
 * 
  
 mux 
 , 
  
 const 
  
 WebPMuxAnimParams 
 * 
  
 params 
 ); 
 

Parameters

mux-- (in/out) object in which ANIM chunk is to be set/added

params-- (in) animation parameters.

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux or params is NULL.

WEBP_MUX_MEMORY_ERROR -- on memory allocation error.

WEBP_MUX_OK -- on success.

WebPMuxGetAnimationParams()

Gets the animation parameters from the mux object.

  WebPMuxError 
  
 WebPMuxGetAnimationParams 
 ( 
 const 
  
 WebPMux 
 * 
  
 mux 
 , 
  
 WebPMuxAnimParams 
 * 
  
 params 
 ); 
 

Parameters

mux-- (in) object from which the animation parameters to be fetched

params-- (out) animation parameters extracted from the ANIM chunk

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux or params is NULL.

WEBP_MUX_NOT_FOUND -- if ANIM chunk is not present in mux object.

WEBP_MUX_OK -- on success.

Misc. Utilities

WebPMuxGetCanvasSize()

Gets the canvas size from the mux object.

  WebPMuxError 
  
 WebPMuxGetCanvasSize 
 ( 
 const 
  
 WebPMux 
 * 
  
 mux 
 , 
  
 int 
 * 
  
 width 
 , 
  
 int 
 * 
  
 height 
 ); 
 

Note:This method assumes that the VP8X chunk, if present, is up-to-date. That is, the mux object hasn't been modified since the last call to WebPMuxAssemble() or WebPMuxCreate() .

Parameters

mux-- (in) object from which the canvas size is to be fetched

width-- (out) canvas width

height-- (out) canvas height

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux, width or height is NULL.

WEBP_MUX_BAD_DATA -- if VP8X/VP8/VP8L chunk or canvas size is invalid.

WEBP_MUX_OK -- on success.

WebPMuxGetFeatures()

Gets the feature flags from the mux object.

  WebPMuxError 
  
 WebPMuxGetFeatures 
 ( 
 const 
  
 WebPMux 
 * 
  
 mux 
 , 
  
 uint32_t 
 * 
  
 flags 
 ); 
 

Note:This method assumes that the VP8X chunk, if present, is up-to-date. That is, the mux object hasn't been modified since the last call to WebPMuxAssemble() or WebPMuxCreate() .

Parameters

mux-- (in) object from which the features are to be fetched

flags-- (out) the flags specifying which features are present in the mux object. This will be an OR of various flag values. Enum WebPFeatureFlags can be used to test individual flag values.

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux or flags is NULL.

WEBP_MUX_BAD_DATA -- if VP8X/VP8/VP8L chunk or canvas size is invalid.

WEBP_MUX_OK -- on success.

WebPMuxNumChunks()

Gets the number of chunks having the given tag value in the muxobject.

  WebPMuxError 
  
 WebPMuxNumChunks 
 ( 
 const 
  
 WebPMux 
 * 
  
 mux 
 , 
  
 WebPChunkId 
  
 id 
 , 
  
 int 
 * 
  
 num_elements 
 ); 
 

Parameters

mux-- (in) object from which the info is to be fetched

id-- (in) chunk id specifying the type of chunk

num_elements-- (out) number of chunks with the given chunk id

Returns

WEBP_MUX_INVALID_ARGUMENT -- if mux, or num_elements is NULL.

WEBP_MUX_OK -- on success.

WebPMuxAssemble()

Assembles all chunks in WebP RIFF format and returns in assembled_data. This function also validates the mux object.

 WebPMuxError WebPMuxAssemble(WebPMux* mux, WebPData* assembled_data); 

Note:The content of assembled_datawill be ignored and overwritten. Also, the content of assembled_datais allocated using malloc(), and NOT owned by the muxobject. It MUST be deallocated by the caller by calling WebPDataClear() .

Parameters

mux-- (in/out) object whose chunks are to be assembled

assembled_data-- (out) assembled WebP data

Returns

WEBP_MUX_BAD_DATA -- if mux object is invalid.

WEBP_MUX_INVALID_ARGUMENT -- if mux or assembled_data is NULL.

WEBP_MUX_MEMORY_ERROR -- on memory allocation error.

WEBP_MUX_OK -- on success.

WebPAnimEncoder API

This API allows encoding (possibly) animated WebP images.

Code Example

  WebPAnimEncoderOptions 
  
 enc_options 
 ; 
 WebPAnimEncoderOptionsInit 
 ( 
& enc_options 
 ); 
 // Tune 'enc_options' as needed. 
 WebPAnimEncoder 
 * 
  
 enc 
  
 = 
  
 WebPAnimEncoderNew 
 ( 
 width 
 , 
  
 height 
 , 
  
& enc_options 
 ); 
 while 
 ( 
< there 
  
 are 
  
 more 
  
 frames 
> ) 
  
 { 
  
 WebPConfig 
  
 config 
 ; 
  
 WebPConfigInit 
 ( 
& config 
 ); 
  
 // Tune 'config' as needed. 
  
 WebPAnimEncoderAdd 
 ( 
 enc 
 , 
  
 frame 
 , 
  
 timestamp_ms 
 , 
  
& config 
 ); 
 } 
 WebPAnimEncoderAdd 
 ( 
 enc 
 , 
  
 NULL 
 , 
  
 timestamp_ms 
 , 
  
 NULL 
 ); 
 WebPAnimEncoderAssemble 
 ( 
 enc 
 , 
  
 webp_data 
 ); 
 WebPAnimEncoderDelete 
 ( 
 enc 
 ); 
 // Write the 'webp_data' to a file, or re-mux it further. 
 typedef 
  
 struct 
  
 WebPAnimEncoder 
  
 WebPAnimEncoder 
 ; 
  
 // Main opaque object. 
 

Global Options

  struct 
  
 WebPAnimEncoderOptions 
  
 { 
  
 WebPMuxAnimParams 
  
 anim_params 
 ; 
  
 // Animation parameters. 
  
 int 
  
 minimize_size 
 ; 
  
 // If true, minimize the output size (slow). Implicitly 
  
 // disables key-frame insertion. 
  
 int 
  
 kmin 
 ; 
  
 int 
  
 kmax 
 ; 
  
 // Minimum and maximum distance between consecutive key 
  
 // frames in the output. The library may insert some key 
  
 // frames as needed to satisfy this criteria. 
  
 // Note that these conditions should hold: kmax > kmin 
  
 // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then 
  
 // key-frame insertion is disabled; and if kmax == 1, 
  
 // then all frames will be key-frames (kmin value does 
  
 // not matter for these special cases). 
  
 int 
  
 allow_mixed 
 ; 
  
 // If true, use mixed compression mode; may choose 
  
 // either lossy and lossless for each frame. 
  
 int 
  
 verbose 
 ; 
  
 // If true, print info and warning messages to stderr. 
 }; 
 

WebPAnimEncoderOptionsInit()

Should always be called, to initialize a fresh WebPAnimEncoderOptionsstructure before modification. Returns false in case of version mismatch. WebPAnimEncoderOptionsInit() must have succeeded before using the enc_optionsobject.

Parameters

enc_options-- (in/out) options used for encoding animation

Returns

True on success.

 int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options); 

WebPAnimEncoderNew()

Creates and initializes a WebPAnimEncoder object.

Parameters

width/height-- (in) canvas width and height of the animation.

enc_options-- (in) encoding options; can be passed NULL to pick reasonable defaults.

Returns

A pointer to the newly created WebPAnimEncoderobject, or NULL in case of memory error.

  WebPAnimEncoder 
 * 
  
 WebPAnimEncoderNew 
 ( 
  
 int 
  
 width 
 , 
  
 int 
  
 height 
 , 
  
 const 
  
 WebPAnimEncoderOptions 
 * 
  
 enc_options 
 ); 
 

WebPAnimEncoderAdd()

Optimize the given frame for WebP, encode it and add it to the WebPAnimEncoderobject.

The last call to WebPAnimEncoderAddshould be with frame = NULL , which indicates that no more frames are to be added. This call is also used to determine the duration of the last frame.

Parameters

enc-- (in/out) object to which the frame is to be added.

frame-- (in/out) frame data in ARGB or YUV(A) format. If it is in YUV(A) format, it will be converted to ARGB, which incurs a small loss.

timestamp_ms-- (in) timestamp of this frame in milliseconds. Duration of a frame would be calculated as "timestamp of next frame - timestamp of this frame". Hence, timestamps should be in non-decreasing order.

config-- (in) encoding options; can be passed NULL to pick reasonable defaults.

Returns

On error, returns false and frame->error_code is set appropriately. Otherwise, returns true.

  int 
  
 WebPAnimEncoderAdd 
 ( 
  
 WebPAnimEncoder 
 * 
  
 enc 
 , 
  
 struct 
  
 WebPPicture 
 * 
  
 frame 
 , 
  
 int 
  
 timestamp_ms 
 , 
  
 const 
  
 struct 
  
 WebPConfig 
 * 
  
 config 
 ); 
 

WebPAnimEncoderAssemble()

Assemble all frames added so far into a WebP bitstream. This call should be preceded by a call to WebPAnimEncoderAddwith frame = NULL ; if not, the duration of the last frame will be internally estimated.

Parameters

enc-- (in/out) object from which the frames are to be assembled.

webp_data-- (out) generated WebP bitstream.

Returns

True on success.

 int WebPAnimEncoderAssemble(WebPAnimEncoder* enc, WebPData* webp_data); 

WebPAnimEncoderGetError()

Get error string corresponding to the most recent call using enc. The returned string is owned by encand is valid only until the next call to WebPAnimEncoderAdd() or WebPAnimEncoderAssemble() or WebPAnimEncoderDelete() .

Parameters

enc-- (in/out) object from which the error string is to be fetched.

Returns

NULL if encis NULL. Otherwise, returns the error string if the last call to enchad an error, or an empty string if the last call was a success.

  const 
  
 char 
 * 
  
 WebPAnimEncoderGetError 
 ( 
 WebPAnimEncoder 
 * 
  
 enc 
 ); 
 

WebPAnimEncoderDelete()

Deletes the WebPAnimEncoderobject.

Parameters

enc-- (in/out) object to be deleted

 void WebPAnimEncoderDelete(WebPAnimEncoder* enc); 

Demux API

Enables extraction of image and extended format data from WebP files.

Code Examples

Demuxing WebP Data to Extract All the Frames, ICC Profile and EXIF/XMP Metadata

 WebPDemuxer* demux = WebPDemux(&webp_data);

uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
// ... (Get information about the features present in the WebP file).
uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);

// ... (Iterate over all frames).
WebPIterator iter;
if (WebPDemuxGetFrame(demux, 1, &iter)) {
  do {
    // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
    // ... and get other frame properties like width, height, offsets etc.
    // ... see 'struct WebPIterator' below for more info).
  } while (WebPDemuxNextFrame(&iter));
  WebPDemuxReleaseIterator(&iter);
}

// ... (Extract metadata).
WebPChunkIterator chunk_iter;
if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
// ... (Consume the ICC profile in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
// ... (Consume the EXIF metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
// ... (Consume the XMP metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
WebPDemuxDelete(demux); 

Life of a Demux Object

Enums

  typedef 
  
 enum 
  
 WebPDemuxState 
  
 { 
  
 WEBP_DEMUX_PARSE_ERROR 
  
 = 
  
 - 
 1 
 , 
  
 // 
  
 An 
  
 error 
  
 occurred 
  
 while 
  
 parsing 
 . 
  
 WEBP_DEMUX_PARSING_HEADER 
  
 = 
  
 0 
 , 
  
 // 
  
 Not 
  
 enough 
  
 data 
  
 to 
  
 parse 
  
 full 
  
 header 
 . 
  
 WEBP_DEMUX_PARSED_HEADER 
  
 = 
  
 1 
 , 
  
 // 
  
 Header 
  
 parsing 
  
 complete 
 , 
  
 // 
  
 data 
  
 may 
  
 be 
  
 available 
 . 
  
 WEBP_DEMUX_DONE 
  
 = 
  
 2 
  
 // 
  
 Entire 
  
 file 
  
 has 
  
 been 
  
 parsed 
 . 
 } 
  
 WebPDemuxState 
 ; 
 

WebPGetDemuxVersion()

Returns the version number of the demux library, packed in hexadecimal using 8 bits for each of major/minor/revision. E.g, v2.5.7 is 0x020507 .

 int WebPGetDemuxVersion(void); 

WebPDemux()

Parses the full WebP file given by data.

  WebPDemuxer 
  
 WebPDemux 
 ( 
 const 
  
 WebPData 
 * 
  
 data 
 ); 
 

Returns a WebPDemuxer object on successful parse, NULL otherwise.

WebPDemuxPartial()

Parses the possibly incomplete WebP file given by data. If stateis non-NULL it will be set to indicate the status of the demuxer.

  WebPDemuxer 
  
 WebPDemuxPartial 
 ( 
 const 
  
 WebPData 
 * 
  
 data 
 , 
  
 WebPDemuxState 
 * 
  
 state 
 ); 
 

Returns NULL in case of error or if there isn't enough data to start parsing; and a WebPDemuxer object on successful parse.

Note that WebPDemuxer keeps internal pointers to datamemory segment. If this data is volatile, the demuxer object should be deleted (by calling WebPDemuxDelete() ) and WebPDemuxPartial() called again on the new data. This is usually an inexpensive operation.

WebPDemuxDelete()

Frees memory associated with dmux.

 void WebPDemuxDelete(WebPDemuxer* dmux); 

Data/Information Extraction

  typedef 
  
 enum 
  
 WebPFormatFeature 
  
 { 
  
 WEBP_FF_FORMAT_FLAGS 
 , 
  
 // 
  
 bit 
 - 
 wise 
  
 combination 
  
 of 
  
 WebPFeatureFlags 
  
 // 
  
 corresponding 
  
 to 
  
 the 
  
 'VP8X' 
  
 chunk 
  
 ( 
 if 
  
 present 
 ) 
 . 
  
 WEBP_FF_CANVAS_WIDTH 
 , 
  
 WEBP_FF_CANVAS_HEIGHT 
 , 
  
 WEBP_FF_LOOP_COUNT 
 , 
  
 // 
  
 only 
  
 relevant 
  
 for 
  
 animated 
  
 file 
  
 WEBP_FF_BACKGROUND_COLOR 
 , 
  
 // 
  
 idem 
 . 
  
 WEBP_FF_FRAME_COUNT 
  
 // 
  
 Number 
  
 of 
  
 frames 
  
 present 
  
 in 
  
 the 
  
 demux 
  
 object 
 . 
  
 // 
  
 In 
  
 case 
  
 of 
  
 a 
  
 partial 
  
 demux 
 , 
  
 this 
  
 is 
  
 the 
  
 number 
  
 // 
  
 of 
  
 frames 
  
 seen 
  
 so 
  
 far 
 , 
  
 with 
  
 the 
  
 last 
  
 frame 
  
 // 
  
 possibly 
  
 being 
  
 partial 
 . 
 } 
  
 WebPFormatFeature 
 ; 
 

WebPDemuxGetI()

Get the featurevalue from the dmux.

  uint32_t 
  
 WebPDemuxGetI 
 ( 
 const 
  
 WebPDemuxer 
 * 
  
 dmux 
 , 
  
 WebPFormatFeature 
  
 feature 
 ); 
 

Note:Values are only valid if WebPDemux() was used or WebPDemuxPartial() returned a state > WEBP_DEMUX_PARSING_HEADER .

Frame Iteration

 struct WebPIterator {
  int frame_num;
  int num_frames;          // equivalent to WEBP_FF_FRAME_COUNT.
  int fragment_num;
  int num_fragments;
  int x_offset, y_offset;  // offset relative to the canvas.
  int width, height;       // dimensions of this frame or fragment.
  int duration;            // display duration in milliseconds.
  WebPMuxAnimDispose dispose_method;  // dispose method for the frame.
  int complete;   // true if 'fragment' contains a full frame. partial images
                  // may still be decoded with the WebP incremental decoder.
  WebPData fragment;  // The frame or fragment given by 'frame_num' and
                      // 'fragment_num'.
  int has_alpha;      // True if the frame or fragment contains transparency.
  WebPMuxAnimBlend blend_method;  // Blend operation for the frame.
}; 

WebPDemuxGetFrame()

Retrieves frame frame_numberfrom dmux.

  int 
  
 WebPDemuxGetFrame 
 ( 
 const 
  
 WebPDemuxer 
 * 
  
 dmux 
 , 
  
 int 
  
 frame_number 
 , 
  
 WebPIterator 
 * 
  
 iter 
 ); 
 

iter->fragmentpoints to the first fragment on return from this function. Individual fragments may be extracted using WebPDemuxSelectFragment() . Setting frame_numberequal to 0 will return the last frame of the image.

Returns false if dmuxis NULL or frame frame_numberis not present. Call WebPDemuxReleaseIterator() when use of the iterator is complete.

Note: dmuxmust persist for the lifetime of iter.

WebPDemuxNextFrame() , WebPDemuxPrevFrame()

Sets iter->fragmentto point to the next ( iter->frame_num+ 1) or previous ( iter->frame_num- 1) frame. These functions do not loop.

 int WebPDemuxNextFrame(WebPIterator* iter);
int WebPDemuxPrevFrame(WebPIterator* iter); 

Returns true on success, false otherwise.

WebPDemuxSelectFragment()

Sets iter->fragmentto reflect fragment number fragment_num.

 int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num); 

Returns true if fragment fragment_numis present, false otherwise.

WebPDemuxReleaseIterator()

Releases any memory associated with iter.

 void WebPDemuxReleaseIterator(WebPIterator* iter); 

Must be called before any subsequent calls to WebPDemuxGetChunk() on the same iter. Also, must be called before destroying the associated WebPDemuxer with WebPDemuxDelete() .

Chunk Iteration

  struct 
  
 WebPChunkIterator 
  
 { 
  
 // 
  
 The 
  
 current 
  
 and 
  
 total 
  
 number 
  
 of 
  
 chunks 
  
 with 
  
 the 
  
 fourcc 
  
 given 
  
 to 
  
 // 
  
 WebPDemuxGetChunk 
 () 
 . 
  
 int 
  
 chunk_num 
 ; 
  
 int 
  
 num_chunks 
 ; 
  
 WebPData 
  
 chunk 
 ; 
  
 // 
  
 The 
  
 payload 
  
 of 
  
 the 
  
 chunk 
 . 
 }; 
 

WebPDemuxGetChunk()

Retrieves the chunk_numberinstance of the chunk with id fourccfrom dmux.

  int 
  
 WebPDemuxGetChunk 
 ( 
 const 
  
 WebPDemuxer 
 * 
  
 dmux 
 , 
  
 const 
  
 char 
  
 fourcc 
 [ 
 4 
 ], 
  
 int 
  
 chunk_number 
 , 
  
 WebPChunkIterator 
 * 
  
 iter 
 ); 
 

fourccis a character array containing the fourcc of the chunk to return, e.g., "ICCP", "XMP ", "EXIF", etc.

Setting chunk_numberequal to 0 will return the last chunk in a set.

Returns true if the chunk is found, false otherwise. Image related chunk payloads are accessed through WebPDemuxGetFrame() and related functions. Call WebPDemuxReleaseChunkIterator() when use of the iterator is complete.

Note: dmuxmust persist for the lifetime of the iterator.

WebPDemuxNextChunk() , WebPDemuxPrevChunk()

Sets iter->chunkto point to the next ( iter->chunk_num+ 1) or previous ( iter->chunk_num- 1) chunk. These functions do not loop.

 int WebPDemuxNextChunk(WebPChunkIterator* iter);
int WebPDemuxPrevChunk(WebPChunkIterator* iter); 

Returns true on success, false otherwise.

WebPDemuxReleaseChunkIterator()

Releases any memory associated with iter.

 void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter); 

Must be called before destroying the associated WebPDemuxer with WebPDemuxDelete() .

WebPAnimDecoder API

This API allows decoding (possibly) animated WebP images.

Code Example

  WebPAnimDecoderOptions 
  
 dec_options 
 ; 
 WebPAnimDecoderOptionsInit 
 ( 
& dec_options 
 ); 
 // 
  
 Tune 
  
 'dec_options' 
  
 as 
  
 needed 
 . 
 WebPAnimDecoder 
 * 
  
 dec 
  
 = 
  
 WebPAnimDecoderNew 
 ( 
 webp_data 
 , 
  
& dec_options 
 ); 
 WebPAnimInfo 
  
 anim_info 
 ; 
 WebPAnimDecoderGetInfo 
 ( 
 dec 
 , 
  
& anim_info 
 ); 
 for 
  
 ( 
 uint32_t 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 anim_info 
 . 
 loop_count 
 ; 
  
 ++ 
 i 
 ) 
  
 { 
  
 while 
  
 ( 
 WebPAnimDecoderHasMoreFrames 
 ( 
 dec 
 )) 
  
 { 
  
 uint8_t 
 * 
  
 buf 
 ; 
  
 int 
  
 timestamp 
 ; 
  
 WebPAnimDecoderGetNext 
 ( 
 dec 
 , 
  
& buf 
 , 
  
& timestamp 
 ); 
  
 // 
  
 ... 
  
 ( 
 Render 
  
 'buf' 
  
 based 
  
 on 
  
 'timestamp' 
 ) 
 . 
  
 // 
  
 ... 
  
 ( 
 Do 
  
 NOT 
  
 free 
  
 'buf' 
 , 
  
 as 
  
 it 
  
 is 
  
 owned 
  
 by 
  
 'dec' 
 ) 
 . 
  
 } 
  
 WebPAnimDecoderReset 
 ( 
 dec 
 ); 
 } 
 const 
  
 WebPDemuxer 
 * 
  
 demuxer 
  
 = 
  
 WebPAnimDecoderGetDemuxer 
 ( 
 dec 
 ); 
 // 
  
 ... 
  
 ( 
 Do 
  
 something 
  
 using 
  
 'demuxer' 
 ; 
  
 e 
 . 
 g 
 . 
  
 get 
  
 EXIF 
 / 
 XMP 
 / 
 ICC 
  
 data 
 ) 
 . 
 WebPAnimDecoderDelete 
 ( 
 dec 
 ); 
 typedef 
  
 struct 
  
 WebPAnimDecoder 
  
 WebPAnimDecoder 
 ; 
  
 // 
  
 Main 
  
 opaque 
  
 object 
 . 
 

Global Options

  struct 
  
 WebPAnimDecoderOptions 
  
 { 
  
 // 
  
 Output 
  
 colorspace. 
  
 Only 
  
 the 
  
 following 
  
 modes 
  
 are 
  
 supported 
 : 
  
 // 
  
 MODE_RGBA 
 , 
  
 MODE_BGRA 
 , 
  
 MODE_rgbA 
  
 and 
  
 MODE_bgrA 
 . 
  
 WEBP_CSP_MODE 
  
 color_mode 
 ; 
  
 int 
  
 use_threads 
 ; 
  
 // 
  
 If 
  
 true, 
  
 use 
  
 multi-threaded 
  
 decoding. 
 } 
 ; 
 

WebPAnimDecoderOptionsInit()

Should always be called, to initialize a fresh WebPAnimDecoderOptionsstructure before modification. Returns false in case of version mismatch. WebPAnimDecoderOptionsInit() must have succeeded before using the dec_optionsobject.

Parameters

dec_options-- (in/out) options used for decoding animation

Returns

True on success

 int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options); 

WebPAnimDecoderNew()

Creates and initializes a WebPAnimDecoderobject.

Parameters

webp_data-- (in) WebP bitstream. This should remain unchanged during the lifetime of the output WebPAnimDecoderobject.

dec_options-- (in) decoding options. Can be passed NULL to choose reasonable defaults (in particular, color mode MODE_RGBA will be picked).

Returns

A pointer to the newly created WebPAnimDecoderobject, or NULL in case of parsing error, invalid option or memory error.

  WebPAnimDecoder 
 * 
  
 WebPAnimDecoderNew 
 ( 
  
 const 
  
 WebPData 
 * 
  
 webp_data 
 , 
  
 const 
  
 WebPAnimDecoderOptions 
 * 
  
 dec_options 
 ); 
 

Global information about the animation.

 struct WebPAnimInfo {
  uint32_t canvas_width;
  uint32_t canvas_height;
  uint32_t loop_count;
  uint32_t bgcolor;
  uint32_t frame_count;
}; 

WebPAnimDecoderGetInfo()

Get global information about the animation.

Parameters

dec-- (in) decoder instance to get information from.

info-- (out) global information fetched from the animation.

Returns

True on success.

  int 
  
 WebPAnimDecoderGetInfo 
 ( 
 const 
  
 WebPAnimDecoder 
 * 
  
 dec 
 , 
  
 WebPAnimInfo 
 * 
  
 info 
 ); 
 

WebPAnimDecoderGetNext()

Fetch the next frame from decbased on options supplied to WebPAnimDecoderNew() . This will be a fully reconstructed canvas of size canvas_width * 4 * canvas_height , and not just the frame sub-rectangle. The returned buffer bufis valid only until the next call to WebPAnimDecoderGetNext() , WebPAnimDecoderReset() or WebPAnimDecoderDelete() .

Parameters

dec-- (in/out) decoder instance from which the next frame is to be fetched.

buf-- (out) decoded frame.

timestamp-- (out) timestamp of the frame in milliseconds.

Returns

False if any of the arguments are NULL, or if there is a parsing or decoding error, or if there are no more frames. Otherwise, returns true.

 int WebPAnimDecoderGetNext(WebPAnimDecoder* dec,
                           uint8_t** buf, int* timestamp); 

WebPAnimDecoderHasMoreFrames()

Check if there are more frames left to decode.

Parameters

dec-- (in) decoder instance to be checked.

Returns

True if decis not NULL and some frames are yet to be decoded. Otherwise, returns false.

  int 
  
 WebPAnimDecoderHasMoreFrames 
 ( 
 const 
  
 WebPAnimDecoder 
 * 
  
 dec 
 ); 
 

WebPAnimDecoderReset()

Resets the WebPAnimDecoder object, so that next call to WebPAnimDecoderGetNext() will restart decoding from 1st frame. This would be helpful when all frames need to be decoded multiple times (e.g. info.loop_count times) without destroying and recreating the decobject.

Parameters

dec-- (in/out) decoder instance to be reset

 void WebPAnimDecoderReset(WebPAnimDecoder* dec); 

WebPAnimDecoderGetDemuxer()

Grab the internal demuxer object.

Getting the demuxer object can be useful if one wants to use operations only available through demuxer; e.g. to get XMP/EXIF/ICC metadata. The returned demuxer object is owned by decand is valid only until the next call to WebPAnimDecoderDelete() .

Parameters

dec-- (in) decoder instance from which the demuxer object is to be fetched.

  const 
  
 WebPDemuxer 
 * 
  
 WebPAnimDecoderGetDemuxer 
 ( 
 const 
  
 WebPAnimDecoder 
 * 
  
 dec 
 ); 
 

WebPAnimDecoderDelete()

Deletes the WebPAnimDecoderobject.

Parameters

dec-- (in/out) decoder instance to be deleted.

Returns

True on success.

 void WebPAnimDecoderDelete(WebPAnimDecoder* dec); 

Common Data Types

Enums

  typedef 
  
 enum 
  
 WebPFeatureFlags 
  
 { 
  
 FRAGMENTS_FLAG 
  
 = 
  
 0x00000001 
 , 
  
 ANIMATION_FLAG 
  
 = 
  
 0x00000002 
 , 
  
 XMP_FLAG 
  
 = 
  
 0x00000004 
 , 
  
 EXIF_FLAG 
  
 = 
  
 0x00000008 
 , 
  
 ALPHA_FLAG 
  
 = 
  
 0x00000010 
 , 
  
 ICCP_FLAG 
  
 = 
  
 0x00000020 
 } 
  
 WebPFeatureFlags 
 ; 
 // 
  
 Dispose 
  
 method 
  
 ( 
 animation 
  
 only 
 ) 
 . 
  
 Indicates 
  
 how 
  
 the 
  
 area 
  
 used 
  
 by 
  
 the 
  
 current 
 // 
  
 frame 
  
 is 
  
 to 
  
 be 
  
 treated 
  
 before 
  
 rendering 
  
 the 
  
 next 
  
 frame 
  
 on 
  
 the 
  
 canvas 
 . 
 typedef 
  
 enum 
  
 WebPMuxAnimDispose 
  
 { 
  
 WEBP_MUX_DISPOSE_NONE 
 , 
  
 // 
  
 Do 
  
 not 
  
 dispose 
 . 
  
 WEBP_MUX_DISPOSE_BACKGROUND 
  
 // 
  
 Dispose 
  
 to 
  
 background 
  
 color 
 . 
 } 
  
 WebPMuxAnimDispose 
 ; 
 // 
  
 Blend 
  
 operation 
  
 ( 
 animation 
  
 only 
 ) 
 . 
  
 Indicates 
  
 how 
  
 transparent 
  
 pixels 
  
 of 
  
 the 
 // 
  
 current 
  
 frame 
  
 are 
  
 blended 
  
 with 
  
 those 
  
 of 
  
 the 
  
 previous 
  
 canvas 
 . 
 typedef 
  
 enum 
  
 WebPMuxAnimBlend 
  
 { 
  
 WEBP_MUX_BLEND 
 , 
  
 // 
  
 Blend 
 . 
  
 WEBP_MUX_NO_BLEND 
  
 // 
  
 Do 
  
 not 
  
 blend 
 . 
 } 
  
 WebPMuxAnimBlend 
 ; 
 

WebPDataInit()

Initializes the contents of the webp_dataobject with default values.

 void WebPDataInit(WebPData* webp_data); 

WebPDataClear()

Clears the contents of the webp_dataobject by calling free() . Does not deallocate the object itself.

 void WebPDataClear(WebPData* webp_data); 

WebPDataCopy()

Allocates necessary storage for dstand copies the contents of src. Returns true on success.

  int 
  
 WebPDataCopy 
 ( 
 const 
  
 WebPData 
 * 
  
 src 
 , 
  
 WebPData 
 * 
  
 dst 
 );