Hide

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_FRGM,     // FRGM
  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.
  uint32_t    pad[1];     // padding for later use
};

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:

  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 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.

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,  // Extended format flags present in the 'VP8X' chunk.
  WEBP_FF_CANVAS_WIDTH,
  WEBP_FF_CANVAS_HEIGHT,
  WEBP_FF_LOOP_COUNT,
  WEBP_FF_BACKGROUND_COLOR,
  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.

  uint32_t pad[2];         // padding for later use.
  void* private_;          // for internal use only.
};

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.

  uint32_t pad[6];   // padding for later use
  void* private_;
};

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().

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);