Package dev.matrixlab.webp4j

Class WebPCodec

java.lang.Object
dev.matrixlab.webp4j.WebPCodec
public final class WebPCodec extends Object
Main facade class for WebP encoding and decoding operations.

This class provides a unified API for all WebP-related operations including:

  • Static image encoding/decoding
  • GIF to WebP conversion
  • Animated WebP creation
Since:
1.4.0
Author:
MrNanko

  • Method Details

    • isAvailable

      public static boolean isAvailable()
      Checks if WebP support is available on the current platform.

      This method verifies that the native WebP library has been successfully loaded for the current operating system and architecture. It provides a lightweight way to check platform support without attempting to encode or decode an image.

      Example usage: 

       if (WebPCodec.isAvailable()) {
     // Show WebP export option in UI
     byte[] webpData = WebPCodec.encodeImage(image, 75);
 } else {
     // Hide WebP option or show unsupported message
 }
      Returns:
      true if WebP operations are supported on this platform, false otherwise

    • getWebPInfo

      public static int[] getWebPInfo(byte[] webPData) throws IOException
      Retrieves information about a WebP image.
      Parameters:
      webPData - Byte array containing WebP image data
      Returns:
      int array containing width and height of the image [width, height]
      Throws:
      IOException - If there is an error processing the image

    • encodeImage

      public static byte[] encodeImage(BufferedImage bufferedImage, float quality, boolean lossless) throws IOException
      Encodes an RGB/RGBA BufferedImage to a WebP encoded byte array.
      Parameters:
      bufferedImage - The input BufferedImage in RGB/RGBA format.
      quality - The WebP quality parameter (0-100). Ignored when lossless is true.
      lossless - True for lossless encoding, false for lossy encoding.
      Returns:
      A byte array containing the WebP encoded data.
      Throws:
      IOException - If an error occurs during image conversion or encoding.
      IllegalArgumentException - If bufferedImage is null.

    • encodeImage

      public static byte[] encodeImage(BufferedImage bufferedImage, float quality) throws IOException
      Encodes an RGB/RGBA BufferedImage to a lossy WebP encoded byte array. This is a convenience method that calls encodeImage(bufferedImage, quality, false).
      Parameters:
      bufferedImage - The input BufferedImage in RGB/RGBA format.
      quality - The WebP quality parameter (0-100).
      Returns:
      A byte array containing the lossy WebP encoded data.
      Throws:
      IOException - If an error occurs during image conversion or encoding.
      IllegalArgumentException - If bufferedImage is null.

    • encodeLosslessImage

      public static byte[] encodeLosslessImage(BufferedImage bufferedImage) throws IOException
      Encodes an RGB/RGBA BufferedImage to a lossless WebP encoded byte array. This is a convenience method that calls encodeImage(bufferedImage, 0, true).
      Parameters:
      bufferedImage - The input BufferedImage in RGB/RGBA format.
      Returns:
      A byte array containing the lossless WebP encoded data.
      Throws:
      IOException - If an error occurs during image conversion or encoding.
      IllegalArgumentException - If bufferedImage is null.

    • decodeImage

      public static BufferedImage decodeImage(byte[] webPData) throws IOException
      Decodes a WebP image (stored as a byte array) into an RGB/RGBA BufferedImage.
      Parameters:
      webPData - The byte array containing the WebP encoded image.
      Returns:
      A BufferedImage representing the decoded RGB/RGBA image.
      Throws:
      IOException - If an error occurs during retrieval of image info or decoding.
      IllegalArgumentException - If webPData is null or empty.

    • getGifInfo

      public static AnimationInfo getGifInfo(byte[] gifData) throws IOException
      Gets information about a GIF image without performing full conversion.

      This is useful for determining whether a GIF is animated, its dimensions, and other properties before deciding how to convert it.

      Parameters:
      gifData - Byte array containing the GIF image data
      Returns:
      AnimationInfo containing frame count, dimensions, loop count, and transparency info
      Throws:
      IOException - If reading GIF information fails
      IllegalArgumentException - If gifData is null or empty

    • encodeGifToWebP

      public static byte[] encodeGifToWebP(byte[] gifData) throws IOException
      Converts a GIF image to WebP format with default lossy settings.

      This is a convenience method that uses quality factor 75 and lossy compression. For more control over the conversion, use encodeGifToWebP(byte[], GifToWebPConfig).

      Parameters:
      gifData - Byte array containing the GIF image data
      Returns:
      Byte array containing the WebP encoded image
      Throws:
      IOException - If conversion fails
      IllegalArgumentException - If gifData is null or empty

    • encodeGifToWebP

      public static byte[] encodeGifToWebP(byte[] gifData, GifToWebPConfig config) throws IOException
      Converts a GIF image to WebP format.

      This method automatically detects whether the GIF is static or animated, and handles both cases appropriately. It uses a dual-path approach:

      • Primary: Native giflib decoder (fast, complete GIF support)
      • Fallback: Java ImageIO decoder (slower, but works when native library unavailable)
      Parameters:
      gifData - Byte array containing the GIF image data
      config - Configuration for conversion (quality, lossless, compression, etc.)
      Returns:
      Byte array containing the WebP encoded image
      Throws:
      IOException - If conversion fails
      IllegalArgumentException - If gifData or config is null

    • encodeGifToWebPLossless

      public static byte[] encodeGifToWebPLossless(byte[] gifData) throws IOException
      Converts a GIF image to lossless WebP format.

      This is a convenience method that uses lossless compression to preserve the original GIF quality without any loss.

      Parameters:
      gifData - Byte array containing the GIF image data
      Returns:
      Byte array containing the lossless WebP encoded image
      Throws:
      IOException - If conversion fails
      IllegalArgumentException - If gifData is null or empty

    • createAnimatedWebP

      public static byte[] createAnimatedWebP(List<BufferedImage> frames, int[] delays, GifToWebPConfig config) throws IOException
      Creates an animated WebP from a list of BufferedImage frames.

      This method provides direct conversion from Java BufferedImage objects to animated WebP without requiring an intermediate GIF file.

      Example usage: 

      
 List<BufferedImage> frames = Arrays.asList(frame1, frame2, frame3);
 int[] delays = {100, 100, 100};  // milliseconds per frame
 GifToWebPConfig config = GifToWebPConfig.createLosslessConfig();
 byte[] webp = WebPCodec.createAnimatedWebP(frames, delays, config);
      Parameters:
      frames - List of BufferedImage frames (must not be empty)
      delays - Array of frame delays in milliseconds (must match frame count)
      config - Configuration for encoding (quality, compression, etc.)
      Returns:
      Byte array containing the animated WebP data
      Throws:
      IOException - If encoding fails
      IllegalArgumentException - If frames is empty or delays length doesn't match

    • decodeAnimatedWebP

      public static AnimatedWebPData decodeAnimatedWebP(byte[] webPData) throws IOException
      Decodes an animated WebP image into individual frames.

      This method extracts all frames from an animated WebP as BufferedImage objects along with their timestamps and animation metadata.

      Each frame is a fully composited canvas-sized RGBA image.

      Example usage: 

      
 byte[] webPData = Files.readAllBytes(Paths.get("animation.webp"));
 AnimatedWebPData result = WebPCodec.decodeAnimatedWebP(webPData);

 // Access individual frames
 for (AnimatedWebPFrame frame : result.getFrames()) {
     BufferedImage image = frame.getImage();
     int timestamp = frame.getTimestamp();
 }

 // Get per-frame delays
 int[] delays = result.getDelays();
      Parameters:
      webPData - Byte array containing the animated WebP image data
      Returns:
      AnimatedWebPData containing all decoded frames and animation metadata
      Throws:
      IOException - If decoding fails
      IllegalArgumentException - If webPData is null or empty