media/libwebp/README.mux

   1           __   __  ____  ____  ____  __ __  _     __ __
   2          /  \\/  \/  _ \/  _ \/  _ \/  \  \/ \___/_ / _\
   3          \       /   __/  _  \   __/      /  /  (_/  /__
   4           \__\__/\_____/_____/__/  \__//_/\_____/__/___/v1.2.0
   5
   6
   7 Description:
   8 ============
   9
  10 WebPMux: set of two libraries 'Mux' and 'Demux' for creation, extraction and
  11 manipulation of an extended format WebP file, which can have features like
  12 color profile, metadata and animation. Reference command-line tools 'webpmux'
  13 and 'vwebp' as well as the WebP container specification
  14 'doc/webp-container-spec.txt' are also provided in this package.
  15
  16 WebP Mux tool:
  17 ==============
  18
  19 The examples/ directory contains a tool (webpmux) for manipulating WebP
  20 files. The webpmux tool can be used to create an extended format WebP file and
  21 also to extract or strip relevant data from such a file.
  22
  23 A list of options is available using the -help command line flag:
  24
  25 > webpmux -help
  26 Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT
  27        webpmux -set SET_OPTIONS INPUT -o OUTPUT
  28        webpmux -duration DURATION_OPTIONS [-duration ...]
  29                INPUT -o OUTPUT
  30        webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT
  31        webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT]
  32                [-bgcolor BACKGROUND_COLOR] -o OUTPUT
  33        webpmux -info INPUT
  34        webpmux [-h|-help]
  35        webpmux -version
  36        webpmux argument_file_name
  37
  38 GET_OPTIONS:
  39  Extract relevant data:
  40    icc       get ICC profile
  41    exif      get EXIF metadata
  42    xmp       get XMP metadata
  43    frame n   get nth frame
  44
  45 SET_OPTIONS:
  46  Set color profile/metadata:
  47    loop LOOP_COUNT   set the loop count
  48    icc  file.icc     set ICC profile
  49    exif file.exif    set EXIF metadata
  50    xmp  file.xmp     set XMP metadata
  51    where:    'file.icc' contains the ICC profile to be set,
  52              'file.exif' contains the EXIF metadata to be set
  53              'file.xmp' contains the XMP metadata to be set
  54
  55 DURATION_OPTIONS:
  56  Set duration of selected frames:
  57    duration            set duration for each frames
  58    duration,frame      set duration of a particular frame
  59    duration,start,end  set duration of frames in the
  60                         interval [start,end])
  61    where: 'duration' is the duration in milliseconds
  62           'start' is the start frame index
  63           'end' is the inclusive end frame index
  64            The special 'end' value '0' means: last frame.
  65
  66 STRIP_OPTIONS:
  67  Strip color profile/metadata:
  68    icc       strip ICC profile
  69    exif      strip EXIF metadata
  70    xmp       strip XMP metadata
  71
  72 FRAME_OPTIONS(i):
  73  Create animation:
  74    file_i +di+[xi+yi[+mi[bi]]]
  75    where:    'file_i' is the i'th animation frame (WebP format),
  76              'di' is the pause duration before next frame,
  77              'xi','yi' specify the image offset for this frame,
  78              'mi' is the dispose method for this frame (0 or 1),
  79              'bi' is the blending method for this frame (+b or -b)
  80
  81 LOOP_COUNT:
  82  Number of times to repeat the animation.
  83  Valid range is 0 to 65535 [Default: 0 (infinite)].
  84
  85 BACKGROUND_COLOR:
  86  Background color of the canvas.
  87   A,R,G,B
  88   where:    'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying
  89             the Alpha, Red, Green and Blue component values respectively
  90             [Default: 255,255,255,255]
  91
  92 INPUT & OUTPUT are in WebP format.
  93
  94 Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be
  95 valid.
  96
  97 Note: if a single file name is passed as the argument, the arguments will be
  98 tokenized from this file. The file name must not start with the character '-'.
  99
 100 Visualization tool:
 101 ===================
 102
 103 The examples/ directory also contains a tool (vwebp) for viewing WebP files.
 104 It decodes the image and visualizes it using OpenGL. See the libwebp README
 105 for details on building and running this program.
 106
 107 Mux API:
 108 ========
 109 The Mux API contains methods for adding data to and reading data from WebP
 110 files. This API currently supports XMP/EXIF metadata, ICC profile and animation.
 111 Other features may be added in subsequent releases.
 112
 113 Example#1 (pseudo code): Creating a WebPMux object with image data, color
 114 profile and XMP metadata.
 115
 116   int copy_data = 0;
 117   WebPMux* mux = WebPMuxNew();
 118   // ... (Prepare image data).
 119   WebPMuxSetImage(mux, &image, copy_data);
 120   // ... (Prepare ICC profile data).
 121   WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
 122   // ... (Prepare XMP metadata).
 123   WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
 124   // Get data from mux in WebP RIFF format.
 125   WebPMuxAssemble(mux, &output_data);
 126   WebPMuxDelete(mux);
 127   // ... (Consume output_data; e.g. write output_data.bytes to file).
 128   WebPDataClear(&output_data);
 129
 130
 131 Example#2 (pseudo code): Get image and color profile data from a WebP file.
 132
 133   int copy_data = 0;
 134   // ... (Read data from file).
 135   WebPMux* mux = WebPMuxCreate(&data, copy_data);
 136   WebPMuxGetFrame(mux, 1, &image);
 137   // ... (Consume image; e.g. call WebPDecode() to decode the data).
 138   WebPMuxGetChunk(mux, "ICCP", &icc_profile);
 139   // ... (Consume icc_profile).
 140   WebPMuxDelete(mux);
 141   free(data);
 142
 143
 144 For a detailed Mux API reference, please refer to the header file
 145 (src/webp/mux.h).
 146
 147 Demux API:
 148 ==========
 149 The Demux API enables extraction of images and extended format data from
 150 WebP files. This API currently supports reading of XMP/EXIF metadata, ICC
 151 profile and animated images. Other features may be added in subsequent
 152 releases.
 153
 154 Code example: Demuxing WebP data to extract all the frames, ICC profile
 155 and EXIF/XMP metadata.
 156
 157   WebPDemuxer* demux = WebPDemux(&webp_data);
 158   uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
 159   uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
 160   // ... (Get information about the features present in the WebP file).
 161   uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);
 162
 163   // ... (Iterate over all frames).
 164   WebPIterator iter;
 165   if (WebPDemuxGetFrame(demux, 1, &iter)) {
 166     do {
 167       // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
 168       // ... and get other frame properties like width, height, offsets etc.
 169       // ... see 'struct WebPIterator' below for more info).
 170     } while (WebPDemuxNextFrame(&iter));
 171     WebPDemuxReleaseIterator(&iter);
 172   }
 173
 174   // ... (Extract metadata).
 175   WebPChunkIterator chunk_iter;
 176   if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
 177   // ... (Consume the ICC profile in 'chunk_iter.chunk').
 178   WebPDemuxReleaseChunkIterator(&chunk_iter);
 179   if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
 180   // ... (Consume the EXIF metadata in 'chunk_iter.chunk').
 181   WebPDemuxReleaseChunkIterator(&chunk_iter);
 182   if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
 183   // ... (Consume the XMP metadata in 'chunk_iter.chunk').
 184   WebPDemuxReleaseChunkIterator(&chunk_iter);
 185   WebPDemuxDelete(demux);
 186
 187
 188 For a detailed Demux API reference, please refer to the header file
 189 (src/webp/demux.h).
 190
 191 AnimEncoder API:
 192 ================
 193 The AnimEncoder API can be used to create animated WebP images.
 194
 195 Code example:
 196
 197   WebPAnimEncoderOptions enc_options;
 198   WebPAnimEncoderOptionsInit(&enc_options);
 199   // ... (Tune 'enc_options' as needed).
 200   WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
 201   while(<there are more frames>) {
 202     WebPConfig config;
 203     WebPConfigInit(&config);
 204     // ... (Tune 'config' as needed).
 205     WebPAnimEncoderAdd(enc, frame, duration, &config);
 206   }
 207   WebPAnimEncoderAssemble(enc, webp_data);
 208   WebPAnimEncoderDelete(enc);
 209   // ... (Write the 'webp_data' to a file, or re-mux it further).
 210
 211
 212 For a detailed AnimEncoder API reference, please refer to the header file
 213 (src/webp/mux.h).
 214
 215 AnimDecoder API:
 216 ================
 217 This AnimDecoder API allows decoding (possibly) animated WebP images.
 218
 219 Code Example:
 220
 221   WebPAnimDecoderOptions dec_options;
 222   WebPAnimDecoderOptionsInit(&dec_options);
 223   // Tune 'dec_options' as needed.
 224   WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options);
 225   WebPAnimInfo anim_info;
 226   WebPAnimDecoderGetInfo(dec, &anim_info);
 227   for (uint32_t i = 0; i < anim_info.loop_count; ++i) {
 228     while (WebPAnimDecoderHasMoreFrames(dec)) {
 229       uint8_t* buf;
 230       int timestamp;
 231       WebPAnimDecoderGetNext(dec, &buf, &timestamp);
 232       // ... (Render 'buf' based on 'timestamp').
 233       // ... (Do NOT free 'buf', as it is owned by 'dec').
 234     }
 235     WebPAnimDecoderReset(dec);
 236   }
 237   const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec);
 238   // ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data).
 239   WebPAnimDecoderDelete(dec);
 240
 241 For a detailed AnimDecoder API reference, please refer to the header file
 242 (src/webp/demux.h).
 243
 244
 245 Bugs:
 246 =====
 247
 248 Please report all bugs to the issue tracker:
 249     https://bugs.chromium.org/p/webp
 250 Patches welcome! See this page to get started:
 251     http://www.webmproject.org/code/contribute/submitting-patches/
 252
 253 Discuss:
 254 ========
 255
 256 Email: webp-discuss@webmproject.org
 257 Web: http://groups.google.com/a/webmproject.org/group/webp-discuss