D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
home
/
whatsapp-api
/
node_modules
/
node-webpmux
/
Filename :
README.md
back
Copy
# node-webpmux A mostly-complete pure Javascript re-implementation of webpmux.<br /> Can load "simple" lossy/lossless images as well as animations. ### Install ```npm install node-webpmux``` ### Basic usage ```javascript const WebP = require('node-webpmux'); let img = new WebP.Image(); // Load an animation await img.load('img.webp'); // Extract the (unprocessed) fourth frame await img.demux('.', { frame: 3 }); // Replace the fourth frame with a new image from disk await img.replaceFrame(3, 'different.webp'); // This preserves the existing frame settings // Alternatively you can do // let frame = Image.generateFrame({ path: 'different.webp' }); // img.frames[3] = frame; // Which will completely replace the frame // Save a new copy await img.save({ path: 'newimg.webp' }); // Or alternatively, img.save() to save over the existing one ``` ### Exports `TYPE_LOSSY`<br /> `TYPE_LOSSLESS`<br /> `TYPE_EXTENDED`<br /> Constants for what type of image is loaded. `encodeResults`: enum of values that set[Image/Frame]Data returns. `Image`: The main class. ### Class definition: #### Class properties ##### `.width` (read-only) The width of the loaded image. ##### `.height` (read-only) The height of the loaded image. ##### `.type` (read-only) The type of image from the TYPE_* constants table. ##### `.hasAnim` (read-only) A boolean flag for easily checking if the image is an animation. ##### `.hasAlpha` (read-only) A boolean flag for easily checking if the image has transparency in any way. ##### `.frames` (read-only) Returns the array of frames, if any, or undefined.<br /> Note that while the frames themselves are read/write, you shouldn't modify them. ##### `.frameCount` (read-only) The number of frames in the image's animation, or 0 if it's not an animation. ##### `.anim` (read-only) Direct access to the raw animation data (see below in the _Layout for internal Image data_ section). ##### `.iccp` (read/write) A Buffer containing the raw ICCP data stored in the image, or undefined if there isn't any. ##### `.exif` (read/write) A Buffer containing the raw EXIF data stored in the image, or undefined if there isn't any. ##### `.xmp` (read/write) A Buffer containing the raw XMP data stored in the image, or undefined if there isn't any. #### Image member functions ##### `async .initLib()` Calls Image.initLib(). This member function is no longer particularly useful and is kept for convenience. ##### `async .load(source)` If `source` is a string, it tries to load that as a path to a WebP image.<br /> If `source` is a buffer, it tries to load the contents of the buffer as a WebP image. ##### `.convertToAnim()` Sets the image up for being an animation. ##### `async .demux({ path = undefined, buffers = false, frame = -1, prefix = '#FNAME#', start = 0, end = 0 })` Dump the individual, unprocessed WebP frames to a directory. * `path`: The directory to dump the frames to, if desired. * `buffers`: Return the frames as an array of Buffers instead of dumping to a path. * `prefix`: What to prefix the frame names with. Default is the file name of the original image (without .webp). Format is \<prefix\>_\<frame number\>.webp. * `frame`: What frame to dump. Defaults to -1, which has it dump all available frames. Overrides `start`/`end`. * `start`: The first frame to dump. Defaults to the first frame. * `end`: The last frame to dump. Defaults to the last frame. ##### `async .replaceFrame(frameIndex, source)` Replaces a frame in the animation with another image from `source`. All other frame settings are preserved. * `frameIndex`: Which frame to replace. Frame indexes are 0-based. * `source`: If this is a string, the frame is loaded from disk. If this is a Buffer, the frame is loaded from there. ##### `async .save(path = this.path, options)` Save the image to `path`. Options are described below in the _Options for saving_ section.<br /> If `path` is `null`, this will save the image to a Buffer and return it. ##### `async .getImageData()` Get the raw RGBA pixel data for the image.<br /> Returns a Buffer in the format `[ r, g, b, a, r, g, b, a, ... ]`. Values are range 0 - 255.<br /> Use this for non-animations.<br /> On error, this returns a Buffer full of 0s. ##### `async .setImageData(buffer, { width = 0, height = 0, preset = 0, quality = 75, exact = false, lossless = 0, method = 4, advanced = undefined })` Encode `buf` as a new WebP using the provided settings and replace the image pixel data with it.<br /> This preserves EXIF/ICCP/XMP if present.<br /> Use this for non-animations.<br /> * `buffer`: A Buffer object with the raw pixels in RGBA order.<br /> Options: * `width`/`height`<br /> If either are > 0, override the existing width and/or height with this value.<br /> Use this if the pixel data in `buf` has different dimensions than the original image. * `preset`: What image preset to use, if any.<br /> Range is 0 - 5<br /> Default is 0 (DEFAULT).<br /> An enum of constants can be found under WebP.presets * `quality`: What quality to set.<br /> Range is 0 - 100.<br /> Default is 75. * `exact`: Preserve data in transparent pixels.<br /> Defaults to `false`, which means transparent pixels may be modified to help with compression. * `lossless`: Save the data as a lossy/lossless image.<br /> Range is 0 - 9.<br /> Default is 0 (lossy).<br /> Higher values will result in smaller files, but requires more processing time. * `method`: Compression method to use.<br /> Range is 0 - 6.<br /> Default is 4.<br /> Higher values will result in smaller files, but requires more processing time. * `advanced`: Access to more advanced encoding settings offered by libwebp<br /> * * `imageHint`: Hint for what type of image it is (only used for lossless encoding for now, according to libwebp spec).<br /> Range is 0 - 3.<br /> Default is 0 (DEFAULT).<br /> An enum of constants can be found under WebP.hints * * `targetSize`: Specifies the desired target size in bytes.<br /> Default is 0 (no target).<br /> Takes precedence over the `method` parameter. * * `targetPSNR`: Specifies the minimum distortion to try to achieve.<br /> Default is 0 (no target).<br /> Takes precedence over the `targetSize` parameter. * * `segments`: Maximum number of segments to use.<br /> Range is 1 - 4.<br /> Default is 4. * * `snsStrength`: Spacial Noise Shaping.<br /> Range is 0 - 100.<br /> Default is 50. * * `filterStrength`<br /> Range is 0 - 100.<br /> Default is 0 (off). * * `filterSharpness`<br /> Range is 0 - 7, with 7 being the least sharp.<br /> Default is 0 (off). * * `filterType`<br /> Range is 0 - 1.<br /> Default is 1.<br /> 0 is simple; 1 is strong.<br /> Only used if `filterStrength` > 0 or `autoFilter` > 0. * * `autoFilter`: Auto-adjust the filter's strength.<br /> Range is 0 - 1.<br /> Default is 0 (off). * * `alphaCompression`: Algorithm for encoding the alpha plane.<br /> Range is 0 - 1.<br /> Default is 1 (Lossless).<br /> 0 is off; 1 is lossless. * * `alphaFiltering`: Predictive filtering method for alpha place.<br /> Range is 0 - 2.<br /> Default is 1 (Fast).<br /> 0 is none; 1 is fast; 2 is best * * `alphaQuality`<br /> Range is 0 - 100.<br /> Default is 100. * * `pass`: Number of entropy-analysis passes.<br /> Range is 1 - 10.<br /> Default is 1. * * `showCompressed`: Export the compressed picture back.<br /> Range is 0 - 1.<br /> Default is 0 (don't).<br /> In-loop filtering is not applied. * * `preprocessing`: Preprocessing filter.<br /> Range is 0 - 2.<br /> Default is 0 (None).<br /> 0 is none; 1 is segment-smooth; 2 is pseudo-random dithering. * * `partitions`: log2(number of token partitions).<br /> Range is 0 - 3.<br /> Default is 0.<br /> Higher values result in harder progressive decoding. * * `partitionLimit`: Quality degredation allowed to fit the 512k limit on prediction modes coding.<br /> Range is 0 - 100.<br /> Default is 0. * * `emulateJpegSize`: Compression parameters are remapped to better mat the expected output size from JPEG compression.<br /> Range is 0 - 1.<br /> Default is 0 (Off).<br /> Generally, the output size will be smaller but the degredation will be lower. * * `threadLevel`: Try to use multi-threaded encoding.<br /> Default is 0 (Off).<br /> NOTE: Currently the WebAssembly is NOT compiled with support for threads, so this option does nothing.<br /> NodeJS doesn't support threads in WebAssembly without an experimental flag, and my testing with it didn't appear to use threads regardless. * * `lowMemory`: Reduce memory usage but increase CPU use.<br /> Range is 0 - 1.<br /> Default is 0 (Off). * * `nearLossless`: Near lossless encoding.<br /> Range is 0 - 100.<br /> Default is 100 (off).<br /> 0 is max loss, 100 is off. * * `useDeltaPalette`: Reserved for future lossless feature.<br /> Range is 0 - 0.<br /> Default is 0 (Off).<br /> Setting this will do nothing, as it's forced back to 0. * * `useSharpYUV`: Use sharp (and slow) RGB->YUV conversion.<br /> Range is 0 - 1.<br /> Default is 0 (Off). * * `qMin`: Minimum permissible quality factor.<br /> Range is 0 - 100.<br /> Default is 0. * * `qMax`: Maximum permissible quality factor.<br /> Range is 0 - 100.<br /> Default is 100. If `lossless` is set above 0, then setting `quality` or `method` is discouraged as they will override settings in the lossless preset.<br /> Return value can be checked against the values in `WebP.encodeResults`. ##### `async .getFrameData(frameIndex)` Get the raw RGBA pixel data for a specific frame.<br /> Use this for animations.<br /> * `frameIndex`: Which frame to get. Frame indexes are 0-based.<br /> Otherwise identical to `.getImageData()` ##### `async .setFrameData(frameIndex, buffer, { width = 0, height = 0, preset = 0, quality = 75, exact = false, lossless = 0, method = 4, advanced = undefined })` Encode `buffer` as a new WebP using the provided settings and replace an existing frame's pixel data with it.<br /> Use this for animations.<br /> * `frameIndex`: Which frame to get. Frame indexes are 0-based.<br /> Otherwise identical to `.setImageData()`. #### Static functions ##### `async Image.initLib()` Initialize the internal library used for [get/set]ImageData and [get/set]FrameData described above.<br /> There is no need to call this unless you plan to use one of those 4 functions. ##### `Image.from(webp)` Use the contents of `webp` and return a new Image using them.<br /> Mainly useful for passing Image into a Web Worker or NodeJS Worker and converting the passed object back into an Image instance.<br /> Such an approach can be used to greatly speed up saving of animations or multiple images as libwebp is *not* multi-threaded beyond saving the alpha layer of lossy images. ##### `async Image.save(path, options)` Save the `options` using `Image.getEmptyImage()`.<br /> Works the same as `.save()` otherwise.<br /> Can be used to create an animation from scratch by passing `frames` in `options`.<br />   Example: `Image.save('animation.webp', { frames: ... })` for saving to file   OR   Example: `Image.save(null, { frames: ... })` for saving to Buffer ##### `async Image.getEmptyImage(ext)` Returns a basic, lossy 1x1 black image with no alpha or metadata.<br /> Useful if you need to create a WebP from scratch, such as when converting from PNG.<br /> `.setImageData()` would be used to change the canvas size/contents.<br /> Set `ext` to `true` to force the image to be an extended type, if desired. This is mainly for use internally. ##### `async Image.generateFrame({ path = undefined, buffer = undefined, img = undefined, x = undefined, y = undefined, delay = undefined, blend = undefined, dispose = undefined })` Generates enough of an `anmf` structure to be placed in `.frames`.<br /> Note that, at the moment, only *static* images are supported in this function. * `path`/`buffer`/`img` Only one of these can be present. `path` will load image data from file. `buffer` will load from the buffer. `img` will use an existing Image instance. * `x`/`y`/`delay`/`blend`/`dispose` Explicitly set these properties. See the _Options for saving_ section for what these do. ### Options for saving #### These options affect both static images and animations * `exif`/`iccp`/`xmp`<br /> Save or override EXIF/ICCP/XMP chunks.<br /> Pass `true` to save the existing ones, or pass a Buffer to replace them.<br /> Note that there is no verification whatsoever that the data passed is valid. #### The options below are only used when saving an animation: * `width`/`height`: Width/height of the image.<br /> Range 0 - 16777216.<br /> The product of width*height must NOT exceed (2 ** 32) - 1.<br /> Passing 0 to either flags it for being set automatically. * `bgColor`: The background color of the animation.<br /> Format is [ r, g, b, a ].<br /> Defaults to [ 255, 255, 255, 255 ]. * `loops`: Number of times the animation loops.<br /> Range is 0 - 65535, with 0 being an infinite loop.<br /> Default is 0. * `x`/`y`/`delay`/`blend`/`dispose`: Changes the default frame x/y position where a frame omits it (see below). * * `x`/`y` defaults to 0. * * `delay` defaults to 100. * * `blend` defaults to `true`. * * `dispose` defaults to `false`. * * `frames`: An array of objects defining each frame of the animation with the following properties. * * * `x`/`y`: x, y offset to place the frame within the animation.<br /> Range 0 - 16777215.<br /> Default is 0,0 (defined above). * * * `delay`: Length of this frame in miliseconds.<br /> Range 0 - 16777215.<br /> Default is 100 (defined above).<br /> According to the documentation, delays <= 10ms are WebP implementation defined, and many tools/browsers/etc assign their own minimum-allowed delay. * * * `blend`: Boolean flag for whether or not to use alpha blending when drawing the frame.<br /> Default is `true` (defined above). * * * `dispose`: Boolean flag to control frame disposal method.<br /> `true` causes the background color to be drawn under the frame.<br /> `false` draws the new frame directly.<br /> Default is `false` (defined above). ### Information about the internal library [get/set]ImageData and [get/set]FrameData are powered by Google's official libwebp library obtained from the [GitHub mirror](https://github.com/webmproject/libwebp).<br /> Commit 8151f38 was the latest at the time of compilation.<br /> This library was compiled with Emscripten with the command `emcc -O3 -s WASM=1 -s MODULARIZE -s EXPORTED_RUNTIME_METHODS='[cwrap]' -s ALLOW_MEMORY_GROWTH=1 -s EXPORT_NAME=LibWebP -DHAVE_CONFIG_H -I libwebp binding.cpp libwebp/src/{dec,dsp,demux,enc,mux,utils}/*.c libwebp/sharpyuv/*.c --bind -o libwebp.js`.<br /> binding.cpp is a shim I wrote to bridge the needed parts together and can be found in the libwebp/ directory. libwebp.mjs, found in the root, is the Javascript interface to it. At present, the only options for encoding are setting the lossless preset, quality, method, and exact flag.<br /> If access to other options is desired (see upstream libwebp/src/webp/encode.h, struct WebPConfig for settings), leave a feature request and I'll add it.<br /> The upstream command line tool `cwebp` can be used to play with the features and see what you find useful. ### Layout for internal Image data ```javascript { path, // The path loaded. loaded, // Boolean flag for if this object has an image loaded. data: { // The loaded data. type, // The type of image from the constants table. vp8: { // The lossy format image. Only if .type is TYPE_LOSSY or TYPE_EXTENDED. raw, // The raw, compressed image data from the VP8 chunk. width, height // The width/height, extracted from the VP8 image data. }, vp8l: { // The lossless format image. Only if .type is TYPE_LOSSLESS or TYPE_EXTENDED. raw, // The raw, compressed image data from the VP8L chunk. alpha, // A flag for if this image has alpha data, extracted from the VP8L image data. width, height // The width/height, extracted from the VP8L image data. }, extended: { // Only if .type is TYPE_EXTENDED. raw, // The raw data for the VP8X chunk. hasICCP, // Flag for if there's an ICC profile chunk defined. hasAlpha, // Flag for if any image/frame defined has alpha data. hasEXIF, // Flag for if there's an EXIF chunk defined. hasXMP, // Flag for if there's an XMP chunk defined. hasAnim, // Flag for if this image has an animation defined. width, height // Width/height of the image. }, anim: { raw, // A Buffer containing the raw data for the ANIM chunk. Mainly for internal use. bgColor, // The background color in [ r, g, b, a ] format. loops, // The loop count. frames: [ // Array of frames { // The frame object definition raw, // The raw data for the ANMF chunk. Mainly for internal use. type, // The type of image this frame is, from the constants table. x, y, // The frame's x, y position. width, height, // The frame's width and height. delay, // The duration of the frame. blend, dispose, // The frame's blend/dispose flags. // Additionally, one or more of the following. vp8, // The raw, compressed WebP data for a lossy image. If present, there will be no `vp8l`. vp8l, // The raw, compressed WebP data for a lossless image. If present, there will be no `vp8` or `alph`. alph // The raw, compressed WebP data for an alpha map. Might be present if the image is lossy. }, ... ] }, alph: { raw // The raw alpha map chunk. Only likely to be here if .vp8 is also defined and .type is TYPE_EXTENDED. }, iccp: { raw // The raw ICCP chunk, if defined. }, exif: { raw // The raw EXIF chunk, if defined. }, xmp: { raw // The raw XMP chunk, if defined. } } } ``` ### Breaking changes from 1.x Image.muxAnim and .muxAnim were merged into Image.save and .save respectively. * Replace `Image.muxAnim({ path, frames, width, height, bgColor, loops, delay, x, y, blend, dispose, exif, iccp, xmp })` * With `Image.save(path, undefined, { frames, width, height, bgColor, loops, delay, x, y, blend, dispose, exif, iccp, xmp })` <br /><br /> * Replace `.muxAnim({ path, width, height, bgColor, loops, delay, x, y, blend, dispose, exif, iccp, xmp })` * With `.save(path, { width, height, bgColor, loops, delay, x, y, blend, dispose, exif, iccp, xmp })` `.anim.backgroundColor` renamed to `.anim.bgColor` for brevity and consisteny.<br /> `.anim.loopCount` renamed to `.anim.loop` for consistency.<br /> `.anim.frameCount` and `.frameCount` were removed. Should use `.anim.frames.length` and `.frames.length` respectively instead.<br /> `.demuxAnim()` was renamed to `.demux()` ## Breaking changes from 2.0.0 to 2.0.1 Image.generateFrame()'s `duration` input renamed to `delay`<br /> ## Breaking changes from 2.x to 3.0.0 File and buffer codepaths have been merged. * Replace `.loadBuffer(buffer)` * With `.load(buffer)` * Replace `Image.loadBuffer(buffer)` * With `Image.load(buffer)` <br /><br /> * Replace `.saveBuffer(settings)` * With `.save(null, settings)` * Replace `Image.saveBuffer(settings)` * With `Image.save(null, settings)` * Note that it's specifically `null` here. This is because the default behavior of .save() is still saving to the path it was loaded from. <br /><br /> * Replace `.demuxToBuffers({ setting, setting, ... })` * With `.demux({ buffers: true, setting, setting, ... })` * Replace `.demux(path, settings)` * With `.demux({ path, setting, setting, ... })` <br /><br /> * Replace `.replaceFrameBuffer(frame, buffer)` * With `.replaceFrame(frame, buffer)`