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:
- frame.id should be one of
WEBP_CHUNK_ANMForWEBP_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
WebPFeatureFlagscan 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);