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 mux object.
Returns: A pointer to 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 fourcc and data chunk_data in 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 mux object.
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 fourcc in 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 fourcc from 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 mux object.
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:

frame.id should be one of WEBP_CHUNK_ANMF or WEBP_CHUNK_FRGM
For setting a non-animated non-fragmented image, use WebPMuxSetImage() instead.
Type of frame being pushed must be same as the frames in mux.
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 mux object.
Returns: WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL or if content of frame is 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->bitstream is allocated using malloc(), and NOT owned by the mux object. 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 mux object.

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_data will be ignored and overwritten. Also, the content of assembled_data is allocated using malloc(), and NOT owned by the mux object. 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 WebPAnimEncoderOptions structure before modification. Returns false in case of version mismatch. WebPAnimEncoderOptionsInit() must have succeeded before using the enc_options object.

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 WebPAnimEncoder object, 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 WebPAnimEncoder object.

The last call to WebPAnimEncoderAdd should 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 WebPAnimEncoderAdd with 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 enc and 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 enc is NULL. Otherwise, returns the error string if the last call to enc had an error, or an empty string if the last call was a success.

const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

`WebPAnimEncoderDelete()`

Deletes the WebPAnimEncoder object.

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 state is 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 data memory 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 feature value 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_number from dmux.

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

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

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

Note: dmux must persist for the lifetime of iter.

`WebPDemuxNextFrame()`, `WebPDemuxPrevFrame()`

Sets iter->fragment to 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->fragment to reflect fragment number fragment_num.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

Returns true if fragment fragment_num is 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_number instance of the chunk with id fourcc from dmux.

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

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

Setting chunk_number equal 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: dmux must persist for the lifetime of the iterator.

`WebPDemuxNextChunk()`, `WebPDemuxPrevChunk()`

Sets iter->chunk to 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 WebPAnimDecoderOptions structure before modification. Returns false in case of version mismatch. WebPAnimDecoderOptionsInit() must have succeeded before using the dec_options object.

Parameters

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

Returns: True on success

int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

`WebPAnimDecoderNew()`

Creates and initializes a WebPAnimDecoder object.

Parameters: webp_data -- (in) WebP bitstream. This should remain unchanged during the lifetime of the output WebPAnimDecoder object.; 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 WebPAnimDecoder object, 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 dec based 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 buf is 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 dec is 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 dec object.

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 dec and 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 WebPAnimDecoder object.

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_data object with default values.

void WebPDataInit(WebPData* webp_data);

`WebPDataClear()`

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

void WebPDataClear(WebPData* webp_data);

`WebPDataCopy()`

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

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

WebP Container API Documentation

Mux API

Code Examples

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

Get Image and Color Profile Data from a WebP File

Life of a Mux Object

Enums

WebPGetMuxVersion()

WebPMuxNew()

WebPMuxDelete()

Mux Creation

WebPMuxCreate()

Non-Image Chunks

WebPMuxSetChunk()

WebPMuxGetChunk()

WebPMuxDeleteChunk()

Images

WebPMuxSetImage()

WebPMuxPushFrame()

WebPMuxGetFrame()

WebPMuxDeleteFrame()

Animation

Animation Parameters

WebPMuxSetAnimationParams()

WebPMuxGetAnimationParams()

Misc. Utilities

WebPMuxGetCanvasSize()

WebPMuxGetFeatures()

WebPMuxNumChunks()

WebPMuxAssemble()

WebPAnimEncoder API

WebPAnimEncoderOptionsInit()

WebPAnimEncoderNew()

WebPAnimEncoderAdd()

WebPAnimEncoderAssemble()

WebPAnimEncoderGetError()

WebPAnimEncoderDelete()

Demux API

Code Examples

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

Life of a Demux Object

Enums

WebPGetDemuxVersion()

WebPDemux()

WebPDemuxPartial()

WebPDemuxDelete()

Data/Information Extraction

WebPDemuxGetI()

Frame Iteration

WebPDemuxGetFrame()

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

WebPDemuxSelectFragment()

WebPDemuxReleaseIterator()

Chunk Iteration

WebPDemuxGetChunk()

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

WebPDemuxReleaseChunkIterator()

WebPAnimDecoder API

WebPAnimDecoderOptionsInit()

WebPAnimDecoderNew()

WebPAnimDecoderGetInfo()

WebPAnimDecoderGetNext()

WebPAnimDecoderHasMoreFrames()

WebPAnimDecoderReset()

WebPAnimDecoderGetDemuxer()

WebPAnimDecoderDelete()

Common Data Types

Enums

WebPDataInit()

WebPDataClear()

WebPDataCopy()

`WebPGetMuxVersion()`

`WebPMuxNew()`

`WebPMuxDelete()`

`WebPMuxCreate()`

`WebPMuxSetChunk()`

`WebPMuxGetChunk()`

`WebPMuxDeleteChunk()`

`WebPMuxSetImage()`

`WebPMuxPushFrame()`

`WebPMuxGetFrame()`

`WebPMuxDeleteFrame()`

`WebPMuxSetAnimationParams()`

`WebPMuxGetAnimationParams()`

`WebPMuxGetCanvasSize()`

`WebPMuxGetFeatures()`

`WebPMuxNumChunks()`

`WebPMuxAssemble()`

`WebPAnimEncoderOptionsInit()`

`WebPAnimEncoderNew()`

`WebPAnimEncoderAdd()`

`WebPAnimEncoderAssemble()`

`WebPAnimEncoderGetError()`

`WebPAnimEncoderDelete()`

`WebPGetDemuxVersion()`

`WebPDemux()`

`WebPDemuxPartial()`

`WebPDemuxDelete()`

`WebPDemuxGetI()`

`WebPDemuxGetFrame()`

`WebPDemuxNextFrame()`, `WebPDemuxPrevFrame()`

`WebPDemuxSelectFragment()`

`WebPDemuxReleaseIterator()`

`WebPDemuxGetChunk()`

`WebPDemuxNextChunk()`, `WebPDemuxPrevChunk()`

`WebPDemuxReleaseChunkIterator()`

`WebPAnimDecoderOptionsInit()`

`WebPAnimDecoderNew()`

`WebPAnimDecoderGetInfo()`

`WebPAnimDecoderGetNext()`

`WebPAnimDecoderHasMoreFrames()`

`WebPAnimDecoderReset()`

`WebPAnimDecoderGetDemuxer()`

`WebPAnimDecoderDelete()`

`WebPDataInit()`

`WebPDataClear()`

`WebPDataCopy()`