libwebp/README.mux

          __   __  ____  ____  ____  __ __  _     __ __
         /  \\/  \/  _ \/  _ \/  _ \/  \  \/ \___/_ / _\
         \       /   __/  _  \   __/      /  /  (_/  /__
          \__\__/\_____/_____/__/  \__//_/\_____/__/___/


Description:
============

WebP Mux: library to create a WebP container object for features like
color profile, metadata, animation and tiling. A reference command line
tool 'webpmux' and WebP container specification 'doc/webp-container-spec.txt'
are also provided in this package.

WebP Mux tool:
==============

The examples/ directory contains a tool (webpmux) for manipulating WebP
files. The webpmux tool can be used to create a WebP container file and to
extract or strip relevant data from the container file.

A list of options is available using the -help command line flag:

> webpmux -help
Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT
       webpmux -set SET_OPTIONS INPUT -o OUTPUT
       webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT
       webpmux -tile TILE_OPTIONS [-tile...] -o OUTPUT
       webpmux -frame FRAME_OPTIONS [-frame...] -loop LOOP_COUNT -o OUTPUT
       webpmux -info INPUT
       webpmux [-h|-help]

GET_OPTIONS:
 Extract relevant data.
   icc       Get ICC profile.
   exif      Get EXIF metadata.
   xmp       Get XMP metadata.
   tile n    Get nth tile.
   frame n   Get nth frame.

SET_OPTIONS:
 Set color profile/metadata.
   icc  file.icc     Set ICC profile.
   exif file.exif    Set EXIF metadata.
   xmp  file.xmp     Set XMP metadata.
   where:    'file.icc' contains the ICC profile to be set,
             'file.exif' contains the EXIF metadata to be set and
             'file.xmp' contains the XMP metadata to be set

STRIP_OPTIONS:
 Strip color profile/metadata.
   icc       Strip ICC profile.
   exif      Strip EXIF metadata.
   xmp       Strip XMP metadata.

TILE_OPTIONS(i):
 Create tiled image.
   file_i +xi+yi
   where:    'file_i' is the i'th tile (WebP format),
             'xi','yi' specify the image offset for this tile.

FRAME_OPTIONS(i):
 Create animation.
   file_i +xi+yi+di
   where:    'file_i' is the i'th animation frame (WebP format),
             'xi','yi' specify the image offset for this frame.
             'di' is the pause duration before next frame.

INPUT and OUTPUT are in WebP format.

Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be
valid.

WebP Mux API:
==============
The WebP Mux API contains methods for adding data to and reading data from
WebPMux (a WebP container object). This API currently supports XMP/EXIF
metadata, ICC profile, animation and tiling. Other features will be added
in subsequent releases.

Example#1 (pseudo code): Creating a WebPMux object with image data, color
profile and XMP metadata.

  int copy_data = 0;
  WebPMux* mux = WebPMuxNew();
  // ... (Prepare image data).
  WebPMuxSetImage(mux, &image, copy_data);
  // ... (Prepare ICC 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);


Example#2 (pseudo code): 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_profile).
  WebPMuxDelete(mux);
  free(data);


For detailed Mux API reference, please refer to the header file (src/webp/mux.h)

Bugs:
=====

Please report all bugs to our issue tracker:
    http://code.google.com/p/webp/issues
Patches welcome! See this page to get started:
    http://www.webmproject.org/code/contribute/submitting-patches/

Discuss:
========

Email: webp-discuss@webmproject.org
Web: http://groups.google.com/a/webmproject.org/group/webp-discuss