Gestire il formato WebP in Java
Java ha una lunga tradizione nell'elaborazione delle immagini lato server, dalla generazione di miniature nei CMS alla produzione di tile per i server cartografici.
Java ha una lunga tradizione nell'elaborazione delle immagini lato server, dalla generazione di miniature nei CMS alla produzione di tile per i server cartografici. Il cuore di questa tradizione è Image I/O, l'API del pacchetto javax.imageio che offre un'interfaccia uniforme per leggere e scrivere formati diversi. Il JDK, però, include solo i plugin per JPEG, PNG, GIF, BMP, WBMP e TIFF: WebP non è supportato, e ImageIO.read() su un file WebP restituisce semplicemente null.
La buona notizia è che Image I/O è estensibile tramite il meccanismo dei service provider: basta aggiungere al classpath un plugin WebP perché ImageIO impari a leggerlo e scriverlo, senza modificare il codice esistente. In questo articolo vedremo quali plugin scegliere, come scrivere un parser dell'intestazione con ByteBuffer, come codificare con e senza perdita usando solo l'API standard, come gestire orientamento EXIF, ridimensionamento e caricamenti sicuri, e come costruire un piccolo server HTTP che negozia il formato con il browser. Il codice usa Java 21.
Scegliere il plugin
Le opzioni principali sono due, e possono convivere:
- webp-imageio, nella versione mantenuta da usefulness (
com.github.usefulness:webp-imageio): un binding JNI a libwebp con le librerie native per Linux, macOS e Windows incluse nel JAR, anche per ARM64. Legge e scrive, con e senza perdita. È un fork del progetto originale di Luciad, di cui conserva le classi. - TwelveMonkeys ImageIO (
com.twelvemonkeys.imageio:imageio-webp): un decoder in Java puro, senza codice nativo. Sa solo leggere, ma è ideale quando le dipendenze native non sono ammesse o quando serve esclusivamente decodificare.
In questo articolo useremo webp-imageio per entrambe le direzioni. Le dipendenze Maven sono queste:
<dependencies>
<!-- Lettura e scrittura WebP tramite libwebp, con le librerie native incluse -->
<dependency>
<groupId>com.github.usefulness</groupId>
<artifactId>webp-imageio</artifactId>
<version>0.11.0</version>
</dependency>
<!-- Facoltativo: lettura dei JPEG CMYK e di altri casi non gestiti dal JDK -->
<dependency>
<groupId>com.twelvemonkeys.imageio</groupId>
<artifactId>imageio-jpeg</artifactId>
<version>3.13.0</version>
</dependency>
</dependencies>
La versione 0.11.0 di webp-imageio include libwebp 1.6.0. Non è un dettaglio secondario: nel settembre 2023 la vulnerabilità CVE-2023-4863, un heap overflow nella decodifica senza perdita sfruttato attivamente, ha colpito libwebp e quindi tutti i software che la incorporano. Con un binding JNI, la versione della libreria nativa è legata a quella del JAR, e aggiornare la dipendenza è l'unico modo per ricevere le correzioni. Il plugin JPEG di TwelveMonkeys non è necessario per WebP, ma risolve un problema frequente: il decoder JPEG del JDK non legge le immagini in CMYK, comuni tra i file che arrivano dalla stampa.
Verificare che il plugin sia attivo
I plugin Image I/O vengono scoperti all'avvio tramite i file META-INF/services presenti nei JAR. Un controllo all'avvio dell'applicazione evita di scoprire in produzione che il plugin manca, per esempio perché un fat JAR è stato costruito senza unire correttamente quei file.
// src/main/java/com/example/webp/WebpSupport.java
package com.example.webp;
import java.util.Arrays;
import javax.imageio.ImageIO;
import javax.imageio.ImageWriter;
public final class WebpSupport {
private WebpSupport() {
}
public static void requireWebp() {
// Ricarica i plugin presenti nel classpath, utile nei container applicativi
ImageIO.scanForPlugins();
boolean canRead = ImageIO.getImageReadersByMIMEType("image/webp").hasNext();
boolean canWrite = ImageIO.getImageWritersByMIMEType("image/webp").hasNext();
if (!canRead || !canWrite) {
throw new IllegalStateException("Plugin WebP non disponibile (lettura: %s, scrittura: %s)"
.formatted(canRead, canWrite));
}
}
public static void main(String[] args) {
requireWebp();
ImageWriter writer = ImageIO.getImageWritersByMIMEType("image/webp").next();
System.out.println("Writer: " + writer.getClass().getName());
System.out.println("Compressioni: " + Arrays.toString(writer.getDefaultWriteParam().getCompressionTypes()));
}
}
L'ultima riga stampa i tipi di compressione esposti dal writer. Ci servirà tra poco: invece di dipendere dalle classi specifiche del plugin, sceglieremo la modalità con o senza perdita attraverso l'API standard di ImageWriteParam.
La struttura del formato e un parser dell'intestazione
Un file WebP è un contenitore RIFF: la stringa RIFF, la dimensione del resto del file come intero a 32 bit little-endian, la stringa WEBP e poi una sequenza di chunk, ciascuno con un identificatore di quattro caratteri, una dimensione e il contenuto. Il primo chunk determina la variante:
VP8, con lo spazio finale: compressione con perdita, senza alfa. Dopo tre byte di intestazione e il codice di sincronizzazione9d 01 2a, larghezza e altezza occupano 14 bit ciascuna.VP8L: compressione senza perdita. Dopo il byte di firma0x2f, 28 bit contengono larghezza e altezza meno uno, seguiti da un bit che indica l'uso dell'alfa.VP8X: formato esteso, per alfa con perdita, profili ICC, EXIF, XMP e animazioni. Contiene un byte di flag e le dimensioni della tela su 24 bit, meno uno.
Un ByteBuffer impostato in ordine little-endian rende la lettura diretta. Un record è il contenitore ideale per il risultato.
// src/main/java/com/example/webp/WebpInfo.java
package com.example.webp;
import java.io.IOException;
import java.io.InputStream;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Optional;
public record WebpInfo(String format, int width, int height, boolean alpha, boolean animated,
boolean icc, boolean exif, boolean xmp) {
private static final int FLAG_ICC = 0x20;
private static final int FLAG_ALPHA = 0x10;
private static final int FLAG_EXIF = 0x08;
private static final int FLAG_XMP = 0x04;
private static final int FLAG_ANIMATION = 0x02;
public static Optional<WebpInfo> read(Path path) throws IOException {
try (InputStream in = Files.newInputStream(path)) {
// Bastano i primi 30 byte, qualunque sia la dimensione del file
return parse(in.readNBytes(30));
}
}
public static Optional<WebpInfo> parse(byte[] data) {
if (data.length < 30 || !ascii(data, 0).equals("RIFF") || !ascii(data, 8).equals("WEBP")) {
return Optional.empty();
}
ByteBuffer buffer = ByteBuffer.wrap(data).order(ByteOrder.LITTLE_ENDIAN);
return switch (ascii(data, 12)) {
case "VP8 " -> {
// Codice di sincronizzazione del fotogramma chiave VP8
if ((data[23] & 0xff) != 0x9d || data[24] != 0x01 || data[25] != 0x2a) {
yield Optional.empty();
}
int width = Short.toUnsignedInt(buffer.getShort(26)) & 0x3fff;
int height = Short.toUnsignedInt(buffer.getShort(28)) & 0x3fff;
yield Optional.of(new WebpInfo("lossy", width, height, false, false, false, false, false));
}
case "VP8L" -> {
if (data[20] != 0x2f) {
yield Optional.empty();
}
int bits = buffer.getInt(21);
int width = (bits & 0x3fff) + 1;
int height = ((bits >>> 14) & 0x3fff) + 1;
boolean alpha = ((bits >>> 28) & 0x1) == 1;
yield Optional.of(new WebpInfo("lossless", width, height, alpha, false, false, false, false));
}
case "VP8X" -> {
int flags = data[20] & 0xff;
yield Optional.of(new WebpInfo("extended", uint24(data, 24) + 1, uint24(data, 27) + 1,
(flags & FLAG_ALPHA) != 0, (flags & FLAG_ANIMATION) != 0,
(flags & FLAG_ICC) != 0, (flags & FLAG_EXIF) != 0, (flags & FLAG_XMP) != 0));
}
default -> Optional.empty();
};
}
private static String ascii(byte[] data, int offset) {
return new String(data, offset, 4, StandardCharsets.US_ASCII);
}
private static int uint24(byte[] data, int offset) {
return (data[offset] & 0xff) | (data[offset + 1] & 0xff) << 8 | (data[offset + 2] & 0xff) << 16;
}
}
In Java i byte sono con segno, e questa è la fonte più comune di errori nei parser binari: 0x9d letto come byte vale -99. Per questo i confronti con valori superiori a 127 usano la maschera & 0xff, e lo spostamento a destra dell'intero a 32 bit usa l'operatore senza segno >>>. Il metodo readNBytes legge esattamente il numero di byte richiesto, salvo fine del file, senza dover gestire letture parziali.
Codificare con l'API standard
Per scrivere un WebP con parametri personalizzati si ottiene un ImageWriter dal registro, se ne configura l'ImageWriteParam e si scrive su un ImageOutputStream. La qualità si esprime come float tra 0 e 1, convenzione comune a tutti i writer Image I/O; il tipo di compressione si sceglie tra quelli esposti dal writer, che per webp-imageio sono una modalità con perdita e una senza perdita.
// src/main/java/com/example/webp/WebpCodec.java
package com.example.webp;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.Arrays;
import java.util.Locale;
import javax.imageio.IIOImage;
import javax.imageio.ImageIO;
import javax.imageio.ImageWriteParam;
import javax.imageio.ImageWriter;
import javax.imageio.stream.ImageOutputStream;
public final class WebpCodec {
public record Options(float quality, boolean lossless) {
public static final Options PHOTO = new Options(0.80f, false);
public static final Options GRAPHIC = new Options(1.0f, true);
}
private WebpCodec() {
}
public static void write(BufferedImage image, OutputStream out, Options options) throws IOException {
ImageWriter writer = ImageIO.getImageWritersByMIMEType("image/webp").next();
try (ImageOutputStream stream = ImageIO.createImageOutputStream(out)) {
writer.setOutput(stream);
ImageWriteParam param = writer.getDefaultWriteParam();
param.setCompressionMode(ImageWriteParam.MODE_EXPLICIT);
param.setCompressionType(compressionType(param, options.lossless()));
// In modalità senza perdita la qualità indica lo sforzo di compressione
param.setCompressionQuality(options.quality());
writer.write(null, new IIOImage(image, null, null), param);
} finally {
writer.dispose();
}
}
public static byte[] encode(BufferedImage image, Options options) throws IOException {
var buffer = new ByteArrayOutputStream();
write(image, buffer, options);
return buffer.toByteArray();
}
// Scrive su un file temporaneo e lo sposta: nessun lettore vede un file incompleto
public static long save(BufferedImage image, Path target, Options options) throws IOException {
Path temporary = Files.createTempFile(target.toAbsolutePath().getParent(), ".webp-", ".tmp");
try {
try (OutputStream out = Files.newOutputStream(temporary)) {
write(image, out, options);
}
Files.move(temporary, target, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
} finally {
Files.deleteIfExists(temporary);
}
return Files.size(target);
}
private static String compressionType(ImageWriteParam param, boolean lossless) {
String[] types = param.getCompressionTypes();
// I nomi esatti dipendono dal plugin: si cerca quello che contiene "lossless"
return Arrays.stream(types)
.filter(type -> type.toLowerCase(Locale.ROOT).contains("lossless") == lossless)
.findFirst()
.orElseThrow(() -> new IllegalStateException("Compressione non disponibile: " + Arrays.toString(types)));
}
}
La ricerca del tipo di compressione per nome invece che per indice rende il codice indipendente dai dettagli del plugin: funziona con i diversi fork di webp-imageio e continuerebbe a funzionare cambiando implementazione. Il blocco finally con writer.dispose() è importante con un plugin JNI, perché rilascia le risorse native associate al writer.
Con ImageIO.write(image, "webp", file) si ottiene la stessa codifica con i parametri predefiniti del plugin, comodo per gli script ma poco adatto a un'applicazione in cui si vuole controllare il compromesso tra peso e qualità.
Normalizzare l'immagine sorgente
ImageIO.read() può restituire BufferedImage di tipi molto diversi: a tavolozza per le PNG a 8 bit e le GIF, in scala di grigi, a tre byte per i JPEG, a 16 bit per canale per alcune PNG. Gli encoder nativi lavorano su RGB o RGBA a 8 bit, e i plugin convertono internamente con risultati non sempre prevedibili. Conviene quindi portare l'immagine in un tipo noto prima della codifica.
// src/main/java/com/example/webp/Images.java
package com.example.webp;
import java.awt.Graphics2D;
import java.awt.RenderingHints;
import java.awt.image.BufferedImage;
import java.util.HashSet;
import java.util.Set;
public final class Images {
private Images() {
}
// Converte in ARGB o RGB a 8 bit per canale, conservando la trasparenza
public static BufferedImage normalize(BufferedImage source) {
boolean alpha = source.getColorModel().hasAlpha();
int type = alpha ? BufferedImage.TYPE_INT_ARGB : BufferedImage.TYPE_INT_RGB;
if (source.getType() == type) {
return source;
}
BufferedImage target = new BufferedImage(source.getWidth(), source.getHeight(), type);
Graphics2D g = target.createGraphics();
try {
g.drawImage(source, 0, 0, null);
} finally {
g.dispose();
}
return target;
}
// Ridimensiona dimezzando ripetutamente: con la sola interpolazione bicubica
// le riduzioni forti producono aliasing
public static BufferedImage resize(BufferedImage source, int width) {
int height = Math.round((float) source.getHeight() * width / source.getWidth());
BufferedImage current = normalize(source);
int w = current.getWidth();
int h = current.getHeight();
do {
w = Math.max(width, w / 2);
h = Math.max(height, h / 2);
BufferedImage step = new BufferedImage(w, h, current.getType());
Graphics2D g = step.createGraphics();
try {
g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BICUBIC);
g.setRenderingHint(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY);
g.drawImage(current, 0, 0, w, h, null);
} finally {
g.dispose();
}
current = step;
} while (w != width || h != height);
return current;
}
// Stima se l'immagine è una grafica a pochi colori, come un logo o una schermata
public static boolean isFlatGraphic(BufferedImage image, int maxColors) {
int step = Math.max(1, Math.min(image.getWidth(), image.getHeight()) / 128);
Set<Integer> colors = new HashSet<>();
for (int y = 0; y < image.getHeight(); y += step) {
for (int x = 0; x < image.getWidth(); x += step) {
colors.add(image.getRGB(x, y));
if (colors.size() > maxColors) {
return false;
}
}
}
return true;
}
}
Il ridimensionamento a passi successivi è una tecnica nota nel mondo Java2D: l'interpolazione bicubica considera solo i pixel vicini, quindi riducendo un'immagine da 4000 a 320 pixel in un colpo solo la maggior parte dei pixel viene ignorata e compaiono scalettature. Dimezzando a ogni passo, ciascun passaggio usa tutta l'informazione disponibile. La funzione isFlatGraphic ci aiuterà a scegliere la compressione senza perdita per loghi e schermate, dove quella con perdita produce aloni attorno ai bordi netti.
L'orientamento EXIF
Gli smartphone salvano spesso le foto nell'orientamento del sensore, annotando la rotazione corretta nel tag EXIF Orientation. Image I/O non applica la rotazione, e il writer WebP non copia i metadati: senza un intervento esplicito le foto verticali appaiono coricate. Il JDK non ha un lettore EXIF, ma i metadati nativi del plugin JPEG espongono il segmento APP1 come array di byte, da cui possiamo estrarre il tag con poche righe.
// src/main/java/com/example/webp/Orientation.java
package com.example.webp;
import java.awt.image.BufferedImage;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.charset.StandardCharsets;
import javax.imageio.metadata.IIOMetadata;
import javax.imageio.metadata.IIOMetadataNode;
import org.w3c.dom.NodeList;
public final class Orientation {
private static final String JPEG_FORMAT = "javax_imageio_jpeg_image_1.0";
private Orientation() {
}
// Legge il tag Orientation dai metadati del plugin JPEG del JDK
public static int fromJpegMetadata(IIOMetadata metadata) {
if (metadata == null || !JPEG_FORMAT.equals(metadata.getNativeMetadataFormatName())) {
return 1;
}
var root = (IIOMetadataNode) metadata.getAsTree(JPEG_FORMAT);
NodeList markers = root.getElementsByTagName("unknown");
for (int i = 0; i < markers.getLength(); i++) {
var marker = (IIOMetadataNode) markers.item(i);
// Il segmento APP1 ha codice 225 (0xE1)
if ("225".equals(marker.getAttribute("MarkerTag")) && marker.getUserObject() instanceof byte[] data) {
int value = fromExif(data);
if (value != 1) {
return value;
}
}
}
return 1;
}
static int fromExif(byte[] app1) {
if (app1.length < 14 || !new String(app1, 0, 6, StandardCharsets.ISO_8859_1).equals("Exif\0\0")) {
return 1;
}
ByteBuffer tiff = ByteBuffer.wrap(app1, 6, app1.length - 6).slice();
switch (new String(app1, 6, 2, StandardCharsets.ISO_8859_1)) {
case "II" -> tiff.order(ByteOrder.LITTLE_ENDIAN);
case "MM" -> tiff.order(ByteOrder.BIG_ENDIAN);
default -> {
return 1;
}
}
try {
int offset = tiff.getInt(4);
int count = Short.toUnsignedInt(tiff.getShort(offset));
for (int i = 0; i < count; i++) {
int entry = offset + 2 + i * 12;
if (Short.toUnsignedInt(tiff.getShort(entry)) == 0x0112) {
int value = Short.toUnsignedInt(tiff.getShort(entry + 8));
return value >= 1 && value <= 8 ? value : 1;
}
}
} catch (IndexOutOfBoundsException e) {
// Un EXIF malformato non deve mai interrompere l'elaborazione
}
return 1;
}
public static BufferedImage apply(BufferedImage source, int orientation) {
if (orientation <= 1 || orientation > 8) {
return source;
}
int w = source.getWidth();
int h = source.getHeight();
boolean swap = orientation >= 5;
var target = new BufferedImage(swap ? h : w, swap ? w : h, Images.normalize(source).getType());
for (int y = 0; y < h; y++) {
for (int x = 0; x < w; x++) {
int argb = source.getRGB(x, y);
switch (orientation) {
case 2 -> target.setRGB(w - 1 - x, y, argb);
case 3 -> target.setRGB(w - 1 - x, h - 1 - y, argb);
case 4 -> target.setRGB(x, h - 1 - y, argb);
case 5 -> target.setRGB(y, x, argb);
case 6 -> target.setRGB(h - 1 - y, x, argb);
case 7 -> target.setRGB(h - 1 - y, w - 1 - x, argb);
case 8 -> target.setRGB(y, w - 1 - x, argb);
default -> throw new IllegalStateException();
}
}
}
return target;
}
}
Il pattern matching con instanceof byte[] data unisce verifica del tipo ed estrazione del valore. Le letture assolute di ByteBuffer sollevano IndexOutOfBoundsException se l'offset esce dai limiti: invece di disseminare il codice di controlli, intercettiamo l'eccezione e trattiamo un EXIF malformato come assente. Le otto trasformazioni corrispondono alle combinazioni di rotazione e specchiatura previste dallo standard.
Caricare in modo sicuro
Ogni immagine proveniente da un utente è un input ostile. Il rischio più concreto è la decompression bomb: un file di pochi kilobyte che dichiara dimensioni enormi e, una volta decodificato, occupa gigabyte di heap, con il risultato di un OutOfMemoryError che può abbattere l'intera JVM. Image I/O permette di difendersi in modo elegante: un ImageReader legge le dimensioni dall'intestazione prima di decodificare i pixel, e il formato viene riconosciuto dal contenuto del file.
// src/main/java/com/example/webp/ImageLoader.java
package com.example.webp;
import java.awt.image.BufferedImage;
import java.io.IOException;
import java.io.InputStream;
import java.util.Iterator;
import java.util.Locale;
import java.util.Set;
import javax.imageio.IIOImage;
import javax.imageio.ImageIO;
import javax.imageio.ImageReader;
import javax.imageio.stream.ImageInputStream;
public final class ImageLoader {
public static final long MAX_PIXELS = 40_000_000L;
private static final Set<String> ALLOWED = Set.of("jpeg", "png", "webp", "gif");
public record Loaded(BufferedImage image, String format) {
}
public static class InvalidImageException extends IOException {
private static final long serialVersionUID = 1L;
public InvalidImageException(String message) {
super(message);
}
}
private ImageLoader() {
}
public static Loaded load(InputStream input) throws IOException {
// La cache su disco evita di tenere in memoria due copie del file
ImageIO.setUseCache(false);
try (ImageInputStream stream = ImageIO.createImageInputStream(input)) {
Iterator<ImageReader> readers = ImageIO.getImageReaders(stream);
if (!readers.hasNext()) {
throw new InvalidImageException("Formato non riconosciuto");
}
ImageReader reader = readers.next();
try {
String format = reader.getFormatName().toLowerCase(Locale.ROOT);
if (format.equals("jpg")) {
format = "jpeg";
}
if (!ALLOWED.contains(format)) {
throw new InvalidImageException("Formato non ammesso: " + format);
}
reader.setInput(stream, true, false);
// Dimensioni lette dall'intestazione, prima di allocare i pixel
long pixels = (long) reader.getWidth(0) * reader.getHeight(0);
if (pixels > MAX_PIXELS) {
throw new InvalidImageException("Dimensioni eccessive: " + pixels + " pixel");
}
IIOImage decoded = reader.readAll(0, null);
BufferedImage image = (BufferedImage) decoded.getRenderedImage();
if (format.equals("jpeg")) {
image = Orientation.apply(image, Orientation.fromJpegMetadata(decoded.getMetadata()));
}
return new Loaded(Images.normalize(image), format);
} finally {
reader.dispose();
}
}
}
}
readAll() restituisce in un colpo solo l'immagine e i metadati, che ci servono per l'orientamento. Il secondo argomento di setInput, seekForwardOnly, impostato a true consente al reader di non conservare i dati già letti; il terzo, ignoreMetadata, è false proprio perché i metadati del JPEG ci interessano. Come effetto collaterale, la ricodifica in WebP produce un file privo di EXIF: le coordinate GPS e il modello del telefono non vengono pubblicati. Si perde però anche l'eventuale profilo colore ICC, quindi per le immagini in spazi colore ampi conviene convertire in sRGB prima della codifica.
Varianti responsive
Con caricamento e codifica a disposizione, generare l'insieme di larghezze per l'attributo srcset è questione di pochi metodi. La sorgente viene decodificata una sola volta e ogni variante parte da quella copia.
// src/main/java/com/example/webp/Variants.java
package com.example.webp;
import java.awt.image.BufferedImage;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
public final class Variants {
public static final List<Integer> WIDTHS = List.of(320, 640, 960, 1280, 1920);
public record Variant(int width, int height, Path path) {
}
private Variants() {
}
public static List<Variant> create(BufferedImage image, String name, Path outputDir) throws IOException {
Files.createDirectories(outputDir);
List<Variant> variants = new ArrayList<>();
for (int width : WIDTHS) {
// Nessuna variante più grande dell'originale
if (width > image.getWidth()) {
break;
}
BufferedImage resized = Images.resize(image, width);
Path path = outputDir.resolve("%s-%d.webp".formatted(name, width));
var options = new WebpCodec.Options(width <= 640 ? 0.75f : 0.80f, false);
WebpCodec.save(resized, path, options);
variants.add(new Variant(width, resized.getHeight(), path));
}
return variants;
}
public static String srcset(List<Variant> variants, String publicPath) {
return variants.stream()
.map(v -> "%s/%s %dw".formatted(publicPath, v.path().getFileName(), v.width()))
.collect(Collectors.joining(", "));
}
}
Animazioni
webp-imageio codifica e decodifica immagini statiche: per le animazioni non offre supporto. Quando serve convertire GIF animate in WebP animati, la soluzione più solida in un'applicazione Java è delegare il lavoro agli strumenti ufficiali di libwebp, gif2webp e img2webp, tramite ProcessBuilder. Gli argomenti vengono passati come lista, senza passare per una shell, quindi un nome di file con caratteri speciali non può trasformarsi in un comando.
// src/main/java/com/example/webp/AnimationConverter.java
package com.example.webp;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.TimeUnit;
public final class AnimationConverter {
private static final Duration TIMEOUT = Duration.ofSeconds(60);
private AnimationConverter() {
}
public static void gifToWebp(Path source, Path target, int quality) throws IOException, InterruptedException {
List<String> command = List.of(
"gif2webp",
"-q", Integer.toString(quality),
"-m", "4",
// Ogni fotogramma viene codificato con o senza perdita, scegliendo il più piccolo
"-mixed",
"-mt",
source.toString(),
"-o", target.toString());
Process process = new ProcessBuilder(command).redirectErrorStream(true).start();
// Il processo va drenato, altrimenti può bloccarsi riempiendo il buffer di output
String output = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
if (!process.waitFor(TIMEOUT.toSeconds(), TimeUnit.SECONDS)) {
process.destroyForcibly();
throw new IOException("gif2webp: tempo scaduto");
}
if (process.exitValue() != 0) {
throw new IOException("gif2webp è terminato con codice " + process.exitValue() + ": " + output);
}
}
}
Il timeout protegge il server da file costruiti apposta per richiedere tempi di elaborazione enormi. Il parser dell'intestazione visto all'inizio torna utile anche qui: il flag di animazione del chunk VP8X permette di sapere se un WebP caricato è animato, e quindi di instradarlo verso la pipeline corretta prima di passarlo a un plugin che lo rifiuterebbe.
Un server che negozia il formato
Il JDK include un server HTTP leggero nel modulo jdk.httpserver, più che sufficiente per mostrare il principio, e da Java 21 può usare i virtual thread come executor. Quando gli originali restano in JPEG o PNG, il server serve WebP ai browser che lo dichiarano nell'intestazione Accept, generandolo alla prima richiesta. Una ConcurrentHashMap di CompletableFuture garantisce che più richieste simultanee per la stessa immagine attendano un'unica conversione.
// src/main/java/com/example/webp/ImageServer.java
package com.example.webp;
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executors;
public final class ImageServer {
private static final Map<String, String> TYPES = Map.of("jpg", "image/jpeg", "jpeg", "image/jpeg", "png", "image/png");
private final Path mediaDir;
private final Path cacheDir;
private final ConcurrentHashMap<Path, CompletableFuture<Path>> inFlight = new ConcurrentHashMap<>();
public ImageServer(Path mediaDir, Path cacheDir) {
this.mediaDir = mediaDir.toAbsolutePath().normalize();
this.cacheDir = cacheDir.toAbsolutePath().normalize();
}
static boolean acceptsWebp(String header) {
if (header == null) {
return false;
}
for (String part : header.split(",")) {
String[] params = part.trim().split(";");
if (params[0].trim().equalsIgnoreCase("image/webp")) {
for (int i = 1; i < params.length; i++) {
// q=0 significa rifiuto esplicito
if (params[i].trim().matches("q=0(\\.0*)?")) {
return false;
}
}
return true;
}
}
return false;
}
private void handle(HttpExchange exchange) throws IOException {
try (exchange) {
String relative = URLDecoder.decode(exchange.getRequestURI().getRawPath(), StandardCharsets.UTF_8)
.replaceFirst("^/media/", "");
Path source = mediaDir.resolve(relative).normalize();
String name = source.getFileName().toString();
String extension = name.substring(name.lastIndexOf('.') + 1).toLowerCase();
// normalize() risolve i ../: il file deve restare dentro la cartella media
if (!source.startsWith(mediaDir) || !TYPES.containsKey(extension) || !Files.isRegularFile(source)) {
exchange.sendResponseHeaders(404, -1);
return;
}
exchange.getResponseHeaders().set("Vary", "Accept");
exchange.getResponseHeaders().set("Cache-Control", "public, max-age=86400");
if (acceptsWebp(exchange.getRequestHeaders().getFirst("Accept"))) {
send(exchange, ensureWebp(source), "image/webp");
} else {
send(exchange, source, TYPES.get(extension));
}
}
}
private Path ensureWebp(Path source) throws IOException {
String relative = mediaDir.relativize(source).toString().replaceFirst("\\.\\w+$", ".webp");
Path target = cacheDir.resolve(relative);
if (Files.exists(target) && Files.getLastModifiedTime(target).compareTo(Files.getLastModifiedTime(source)) >= 0) {
return target;
}
var created = new CompletableFuture<Path>();
CompletableFuture<Path> existing = inFlight.putIfAbsent(target, created);
if (existing != null) {
// Un'altra richiesta sta già convertendo questo file: si attende il suo risultato
return await(existing);
}
try {
Files.createDirectories(target.getParent());
ImageLoader.Loaded loaded;
try (InputStream in = Files.newInputStream(source)) {
loaded = ImageLoader.load(in);
}
WebpCodec.save(loaded.image(), target, WebpCodec.Options.PHOTO);
created.complete(target);
return target;
} catch (IOException | RuntimeException e) {
created.completeExceptionally(e);
throw e;
} finally {
inFlight.remove(target);
}
}
private static Path await(CompletableFuture<Path> future) throws IOException {
try {
return future.get();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new IOException(e);
} catch (ExecutionException e) {
throw new IOException(e.getCause());
}
}
private static void send(HttpExchange exchange, Path file, String type) throws IOException {
exchange.getResponseHeaders().set("Content-Type", type);
exchange.sendResponseHeaders(200, Files.size(file));
try (OutputStream out = exchange.getResponseBody()) {
Files.copy(file, out);
}
}
public static void main(String[] args) throws IOException {
WebpSupport.requireWebp();
var app = new ImageServer(Path.of("media"), Path.of("cache"));
HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
server.createContext("/media/", exchange -> {
try {
app.handle(exchange);
} catch (IOException | RuntimeException e) {
System.err.println("Errore: " + e.getMessage());
}
});
// Un virtual thread per richiesta: costo trascurabile anche con migliaia di connessioni
server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
server.start();
System.out.println("Server in ascolto su http://localhost:8080/media/");
}
}
L'intestazione Vary: Accept va impostata per entrambe le risposte: comunica alle cache intermedie che il contenuto dipende dall'intestazione Accept della richiesta, e senza di essa una CDN potrebbe servire WebP a un client che non lo supporta. In un'applicazione Spring Boot la logica è identica: il controller legge l'intestazione con @RequestHeader, restituisce un ResponseEntity con il tipo corretto e aggiunge Vary con HttpHeaders.VARY.
Conversione parallela di un archivio
La codifica WebP è dominata dalla CPU, e per questo lavoro i virtual thread non sono la scelta giusta: brillano quando i thread passano la maggior parte del tempo in attesa di I/O, non quando calcolano. Un pool di thread di piattaforma pari al numero di core, alimentato da Files.walk, tiene impegnati tutti i processori senza moltiplicare le immagini decodificate in memoria.
// src/main/java/com/example/webp/BatchConverter.java
package com.example.webp;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Locale;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;
import java.util.stream.Stream;
public final class BatchConverter {
private BatchConverter() {
}
public static void main(String[] args) throws IOException {
if (args.length != 2) {
System.err.println("Uso: BatchConverter <sorgente> <destinazione>");
System.exit(2);
}
WebpSupport.requireWebp();
Path sourceDir = Path.of(args[0]);
Path targetDir = Path.of(args[1]);
List<Path> files;
try (Stream<Path> walk = Files.walk(sourceDir)) {
files = walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().toLowerCase(Locale.ROOT).matches(".*\\.(jpe?g|png)$"))
.toList();
}
var converted = new AtomicInteger();
var failed = new AtomicInteger();
var saved = new AtomicLong();
// Il blocco try-with-resources attende la fine di tutti i task prima di chiudere il pool
try (ExecutorService pool = Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors())) {
for (Path source : files) {
pool.submit(() -> {
Path relative = sourceDir.relativize(source);
Path target = targetDir.resolve(relative.toString().replaceFirst("\\.\\w+$", ".webp"));
try (InputStream in = Files.newInputStream(source)) {
Files.createDirectories(target.getParent());
var loaded = ImageLoader.load(in);
var options = Images.isFlatGraphic(loaded.image(), 256)
? WebpCodec.Options.GRAPHIC
: WebpCodec.Options.PHOTO;
long after = WebpCodec.save(loaded.image(), target, options);
saved.addAndGet(Files.size(source) - after);
converted.incrementAndGet();
} catch (IOException | RuntimeException e) {
failed.incrementAndGet();
System.err.printf("Errore su %s: %s%n", relative, e.getMessage());
}
});
}
}
System.out.printf("Convertiti %d, falliti %d, risparmiati %d KB%n", converted.get(), failed.get(), saved.get() / 1024);
}
}
Da Java 19 ExecutorService implementa AutoCloseable, e il suo metodo close() attende il completamento dei task inviati: il codice non ha bisogno di shutdown() e awaitTermination() espliciti. Ogni task cattura le proprie eccezioni, così un file corrotto non interrompe la conversione degli altri.
Test con JUnit
Il parser e la lettura dell'EXIF meritano test dedicati. Per il parser generiamo immagini reali con il writer WebP nelle tre varianti; per l'orientamento verifichiamo la trasformazione su un'immagine minuscola di cui conosciamo ogni pixel.
// src/test/java/com/example/webp/WebpTest.java
package com.example.webp;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import java.awt.image.BufferedImage;
import org.junit.jupiter.api.Test;
class WebpTest {
private static BufferedImage solid(boolean alpha) {
var image = new BufferedImage(123, 45, alpha ? BufferedImage.TYPE_INT_ARGB : BufferedImage.TYPE_INT_RGB);
for (int y = 0; y < 45; y++) {
for (int x = 0; x < 123; x++) {
image.setRGB(x, y, alpha ? 0x80c81e3c : 0xffc81e3c);
}
}
return image;
}
@Test
void parsesLossy() throws Exception {
var info = WebpInfo.parse(WebpCodec.encode(solid(false), WebpCodec.Options.PHOTO)).orElseThrow();
assertEquals("lossy", info.format());
assertEquals(123, info.width());
assertEquals(45, info.height());
}
@Test
void parsesLosslessWithAlpha() throws Exception {
var info = WebpInfo.parse(WebpCodec.encode(solid(true), WebpCodec.Options.GRAPHIC)).orElseThrow();
assertEquals("lossless", info.format());
assertTrue(info.alpha());
}
@Test
void rejectsOtherFormats() {
assertTrue(WebpInfo.parse("RIFF\0\0\0\0WAVEfmt ".getBytes()).isEmpty());
}
@Test
void rotatesClockwise() {
var source = new BufferedImage(2, 1, BufferedImage.TYPE_INT_RGB);
source.setRGB(0, 0, 0xff0000);
source.setRGB(1, 0, 0x0000ff);
// Orientamento 6: rotazione di 90 gradi in senso orario
var rotated = Orientation.apply(source, 6);
assertEquals(1, rotated.getWidth());
assertEquals(2, rotated.getHeight());
assertEquals(0xff0000, rotated.getRGB(0, 0) & 0xffffff);
}
@Test
void acceptHeader() {
assertTrue(ImageServer.acceptsWebp("image/avif,image/webp,*/*;q=0.8"));
assertTrue(!ImageServer.acceptsWebp("image/webp;q=0"));
}
}
Conclusioni
In Java la gestione di WebP passa per l'estensibilità di Image I/O: aggiunto il plugin giusto, il formato diventa un cittadino di prima classe accanto a JPEG e PNG, e il codice applicativo può restare legato alla sola API standard, scegliendo qualità e modalità di compressione attraverso ImageWriteParam. Attorno alla codifica, il lavoro che fa la differenza in produzione riguarda la robustezza: controllare le dimensioni dall'intestazione prima di decodificare, normalizzare il tipo di BufferedImage, applicare l'orientamento EXIF, rilasciare le risorse native con dispose(), scrivere i file in modo atomico e rispondere con Vary: Accept quando si negozia il formato. Per le animazioni, infine, delegare agli strumenti ufficiali di libwebp resta la scelta più affidabile.