Gestire il formato WebP in Node.js
In questo articolo vedremo come affrontare tutti questi casi con sharp, la libreria di riferimento per l'elaborazione di immagini in Node.js, basata su libvips e quindi su libwebp.
WebP è oggi il formato immagine più pragmatico per il web: è supportato da tutti i browser moderni, offre sia la compressione con perdita sia quella senza perdita, gestisce la trasparenza e le animazioni e, a parità di qualità percepita, produce file sensibilmente più leggeri di JPEG e PNG. In un'applicazione Node.js le occasioni per maneggiarlo sono continue: convertire le immagini caricate dagli utenti, generare le varianti responsive per un CMS, servire WebP solo ai client che lo accettano, trasformare GIF animate in qualcosa di meno pesante.
In questo articolo vedremo come affrontare tutti questi casi con sharp, la libreria di riferimento per l'elaborazione di immagini in Node.js, basata su libvips e quindi su libwebp. Prima, però, scriveremo un piccolo parser in JavaScript puro per capire com'è fatto un file WebP: conoscere la struttura del formato ci servirà per validare i file in ingresso senza decodificarli.
Com'è fatto un file WebP
Un file WebP è un contenitore RIFF, lo stesso schema usato da WAV e AVI. I primi dodici byte sono sempre uguali nella forma: la stringa ASCII RIFF, un intero a 32 bit little-endian con la dimensione del file meno otto byte, e la stringa WEBP. Seguono uno o più chunk, ciascuno composto da un identificatore di quattro caratteri (FourCC), una dimensione a 32 bit e il contenuto, allineato a un numero pari di byte.
Il primo chunk determina la variante del file:
VP8(con lo spazio finale): immagine con perdita, codificata con un singolo fotogramma del codec video VP8, senza canale alfa;VP8L: immagine senza perdita, con un codec dedicato che supporta nativamente l'alfa;VP8X: formato esteso, necessario quando l'immagine ha trasparenza in modalità con perdita, un profilo colore ICC, metadati EXIF o XMP, oppure un'animazione. Il chunk contiene una serie di flag e le dimensioni della tela; i dati veri e propri seguono in chunk comeALPH,VP8,ANIMeANMF.
Le dimensioni si trovano in punti diversi a seconda della variante. Nel chunk VP8 dopo tre byte di intestazione del fotogramma e la sequenza di sincronizzazione 9d 01 2a ci sono larghezza e altezza su 14 bit ciascuna. Nel chunk VP8L, dopo il byte di firma 0x2f, larghezza e altezza meno uno sono impacchettate in 28 bit. Nel chunk VP8X la tela è descritta da due interi a 24 bit, anch'essi memorizzati come valore meno uno.
Un parser dell'intestazione in JavaScript puro
Con queste informazioni possiamo scrivere una funzione che, letti pochi byte, ci dice se il file è davvero WebP, di quale variante si tratta, quanto è grande e quali caratteristiche ha. È utile per rifiutare subito un caricamento sospetto, per conoscere le dimensioni senza allocare la bitmap e per non fidarsi mai dell'estensione o del tipo MIME dichiarato dal client.
// webp-info.js
const VP8X_FLAGS = {
icc: 0x20,
alpha: 0x10,
exif: 0x08,
xmp: 0x04,
animation: 0x02,
};
export function readWebpInfo(buffer) {
// Servono almeno 30 byte per leggere intestazione e dimensioni
if (buffer.length < 30) return null;
if (buffer.toString('ascii', 0, 4) !== 'RIFF') return null;
if (buffer.toString('ascii', 8, 12) !== 'WEBP') return null;
const fourcc = buffer.toString('ascii', 12, 16);
if (fourcc === 'VP8 ') {
// Sequenza di sincronizzazione del fotogramma chiave VP8
if (buffer[23] !== 0x9d || buffer[24] !== 0x01 || buffer[25] !== 0x2a) return null;
return {
format: 'lossy',
width: buffer.readUInt16LE(26) & 0x3fff,
height: buffer.readUInt16LE(28) & 0x3fff,
alpha: false,
animated: false,
};
}
if (fourcc === 'VP8L') {
if (buffer[20] !== 0x2f) return null;
const bits = buffer.readUInt32LE(21);
return {
format: 'lossless',
width: (bits & 0x3fff) + 1,
height: ((bits >>> 14) & 0x3fff) + 1,
alpha: ((bits >>> 28) & 0x1) === 1,
animated: false,
};
}
if (fourcc === 'VP8X') {
const flags = buffer[20];
return {
format: 'extended',
width: buffer.readUIntLE(24, 3) + 1,
height: buffer.readUIntLE(27, 3) + 1,
alpha: (flags & VP8X_FLAGS.alpha) !== 0,
animated: (flags & VP8X_FLAGS.animation) !== 0,
icc: (flags & VP8X_FLAGS.icc) !== 0,
exif: (flags & VP8X_FLAGS.exif) !== 0,
xmp: (flags & VP8X_FLAGS.xmp) !== 0,
};
}
return null;
}
La funzione restituisce null per tutto ciò che non riconosce, invece di sollevare eccezioni: in un controllo di validazione è più comodo ragionare su un valore assente. Per leggerla da un file non serve caricarlo tutto in memoria: bastano i primi byte.
// inspect.js
import { open } from 'node:fs/promises';
import { readWebpInfo } from './webp-info.js';
export async function inspectFile(path) {
const handle = await open(path, 'r');
try {
const header = Buffer.alloc(64);
const { bytesRead } = await handle.read(header, 0, header.length, 0);
return readWebpInfo(header.subarray(0, bytesRead));
} finally {
await handle.close();
}
}
// Uso da riga di comando: node inspect.js foto.webp
if (import.meta.url === `file://${process.argv[1]}`) {
const info = await inspectFile(process.argv[2]);
console.log(info ?? 'Il file non è un WebP valido');
}
Installare sharp
sharp distribuisce binari precompilati per Linux (glibc e musl), macOS e Windows su x64 e ARM64, con libvips e libwebp già inclusi: nella maggior parte dei casi l'installazione non richiede compilatori né librerie di sistema.
npm install sharp
node -e "const sharp = require('sharp'); console.log(sharp.versions.webp, sharp.format.webp.output)"
Il secondo comando stampa la versione di libwebp inclusa e conferma che la scrittura in WebP è disponibile. Vale la pena registrarla nei log all'avvio dell'applicazione: nel settembre 2023 una grave vulnerabilità di libwebp (CVE-2023-4863, un buffer overflow nella decodifica senza perdita, sfruttato attivamente) ha costretto a aggiornare browser e librerie in tutto il mondo. Sapere quale versione gira in produzione è il primo passo per reagire in fretta.
Nel resto dell'articolo useremo i moduli ECMAScript, quindi nel package.json va impostato "type": "module".
La prima conversione
La conversione più semplice richiede una sola catena di chiamate: si costruisce un'istanza di sharp a partire da un percorso, un Buffer o uno stream, si sceglie il formato di uscita e si scrive il risultato.
// convert.js
import sharp from 'sharp';
export async function toWebp(input, output, quality = 80) {
const info = await sharp(input)
.webp({ quality })
.toFile(output);
// info contiene formato, dimensioni e peso del file generato
return info;
}
const result = await toWebp('foto.jpg', 'foto.webp');
console.log(`${result.width}x${result.height}, ${result.size} byte`);
Il metodo webp() accetta un oggetto di opzioni che espone quasi tutti i parametri dell'encoder di libwebp. Quelli che contano davvero sono pochi:
quality(da 1 a 100, predefinito 80): la qualità della compressione con perdita. È il parametro con il maggiore impatto sul peso.effort(da 0 a 6, predefinito 4): quanto tempo di CPU dedicare alla ricerca della codifica migliore. Corrisponde all'opzione-mdicwebp. Valori alti producono file un po' più piccoli a parità di qualità, al prezzo di tempi di codifica sensibilmente maggiori.alphaQuality(da 0 a 100, predefinito 100): la qualità del canale alfa, che nella modalità con perdita viene compresso separatamente.lossless: attiva la compressione senza perdita.nearLossless: una modalità intermedia in cui l'encoder ritocca leggermente i valori dei pixel per renderli più comprimibili, poi applica la compressione senza perdita.smartSubsample: usa un sottocampionamento della crominanza più accurato, utile per i bordi netti tra colori saturi, come il testo rosso su fondo blu.preset: uno tradefault,photo,picture,drawing,iconetext, che regola i parametri interni in base al tipo di contenuto.
Scegliere la qualità con i numeri
Non esiste un valore di qualità giusto in assoluto: dipende dal contenuto e dall'uso. Una foto di prodotto a tutta pagina tollera meno artefatti di una miniatura. Il modo più onesto per decidere è misurare: lo script seguente codifica la stessa immagine con diverse combinazioni di parametri e confronta pesi e tempi.
// compare.js
import sharp from 'sharp';
import { stat } from 'node:fs/promises';
const profiles = [
{ name: 'jpeg-q82', format: 'jpeg', options: { quality: 82, mozjpeg: true } },
{ name: 'webp-q60', format: 'webp', options: { quality: 60 } },
{ name: 'webp-q75', format: 'webp', options: { quality: 75 } },
{ name: 'webp-q82', format: 'webp', options: { quality: 82 } },
{ name: 'webp-q82-e6', format: 'webp', options: { quality: 82, effort: 6 } },
{ name: 'webp-lossless', format: 'webp', options: { lossless: true } },
];
export async function compare(input) {
const original = (await stat(input)).size;
const rows = [];
for (const profile of profiles) {
const started = performance.now();
const buffer = await sharp(input)[profile.format](profile.options).toBuffer();
rows.push({
profile: profile.name,
kilobytes: Math.round(buffer.length / 1024),
ratio: `${Math.round((buffer.length / original) * 100)}%`,
milliseconds: Math.round(performance.now() - started),
});
}
console.table(rows);
}
await compare(process.argv[2] ?? 'foto.jpg');
Su fotografie tipiche WebP con qualità tra 75 e 82 produce file più leggeri di un JPEG di qualità comparabile, anche ottimizzato con mozjpeg, e effort: 6 guadagna ancora qualche punto percentuale moltiplicando però il tempo di codifica. La modalità senza perdita, invece, su una fotografia genera quasi sempre un file più pesante dell'originale JPEG: non è un difetto, semplicemente conserva anche il rumore e gli artefatti della compressione precedente. Per giudicare la qualità visiva, oltre al peso, conviene affiancare ai numeri un confronto a occhio o una metrica come SSIM.
Trasparenza e immagini grafiche
Uno dei vantaggi più concreti di WebP è la possibilità di avere trasparenza con compressione con perdita: un PNG di prodotto scontornato da 800 KB può diventare un WebP da 60 KB senza differenze visibili. sharp conserva il canale alfa automaticamente; possiamo però decidere la strategia in base al contenuto dell'immagine.
// graphics.js
import sharp from 'sharp';
export async function encodeGraphic(input, output) {
const image = sharp(input);
const { hasAlpha, isPalette } = await image.metadata();
// Loghi, icone e grafiche piatte: compressione senza perdita
if (isPalette) {
return image.webp({ lossless: true, effort: 6 }).toFile(output);
}
// Foto scontornate: con perdita, ma con un canale alfa curato
if (hasAlpha) {
return image.webp({ quality: 82, alphaQuality: 90, smartSubsample: true }).toFile(output);
}
return image.webp({ quality: 80 }).toFile(output);
}
// Con nearLossless il parametro quality regola il preprocessamento:
// valori più bassi alterano di più i pixel e riducono il peso
export function nearLossless(input, output) {
return sharp(input).webp({ nearLossless: true, quality: 60 }).toFile(output);
}
Il campo isPalette restituito da metadata() indica una sorgente a tavolozza, come i PNG a 8 bit: è un buon indizio di grafica piatta, per la quale la compressione senza perdita di WebP è spesso nettamente migliore di quella con perdita, che tende a sporcare i bordi netti.
Varianti responsive
Servire la stessa immagine da 4000 pixel a uno smartphone e a un monitor 4K è uno spreco. Il caso d'uso più frequente in un CMS è quindi generare un insieme di larghezze da usare con l'attributo srcset. Con sharp conviene decodificare la sorgente una sola volta e clonare la pipeline per ogni variante.
// variants.js
import sharp from 'sharp';
import { mkdir } from 'node:fs/promises';
import { basename, extname, join } from 'node:path';
const WIDTHS = [320, 640, 960, 1280, 1920];
export async function createVariants(input, outputDir) {
await mkdir(outputDir, { recursive: true });
const name = basename(input, extname(input));
// autoOrient applica l'orientamento EXIF prima di ridimensionare
const source = sharp(input).autoOrient();
// metadata() descrive la sorgente: con una rotazione di 90 gradi
// la larghezza effettiva è quella riportata in autoOrient
const { autoOrient } = await source.clone().metadata();
const originalWidth = autoOrient.width;
const jobs = WIDTHS
.filter((width) => width <= originalWidth)
.map(async (width) => {
const file = join(outputDir, `${name}-${width}.webp`);
await source
.clone()
.resize({ width, withoutEnlargement: true })
.webp({ quality: width <= 640 ? 75 : 80 })
.toFile(file);
return { width, file };
});
return Promise.all(jobs);
}
export function srcset(variants, publicPath) {
return variants
.map(({ width, file }) => `${publicPath}/${basename(file)} ${width}w`)
.join(', ');
}
Il filtro sulle larghezze evita di produrre varianti più grandi dell'originale, che peserebbero di più senza aggiungere dettaglio. Si noti la qualità leggermente più bassa per le varianti piccole: sugli schermi ad alta densità una miniatura viene mostrata a dimensioni ridotte e gli artefatti diventano meno visibili. Il risultato si usa tipicamente così:
<picture>
<source type="image/webp"
srcset="/media/foto-320.webp 320w, /media/foto-640.webp 640w, /media/foto-1280.webp 1280w"
sizes="(max-width: 700px) 100vw, 700px">
<img src="/media/foto-1280.jpg" alt="Descrizione della foto" width="1280" height="853" loading="lazy">
</picture>
Oggi il supporto a WebP è universale tra i browser in uso, quindi l'elemento picture con un'alternativa JPEG è soprattutto una garanzia per client particolari, come vecchie webview, lettori RSS o strumenti di terze parti.
Metadati: EXIF, ICC e privacy
Per impostazione predefinita sharp rimuove tutti i metadati dall'immagine di uscita. È il comportamento giusto per la maggior parte dei siti: i dati EXIF di una foto scattata con uno smartphone contengono spesso le coordinate GPS del luogo, il modello del dispositivo e la data esatta, informazioni che un utente difficilmente vuole pubblicare. C'è però un'eccezione importante: il profilo colore. Una foto in Display P3 o Adobe RGB a cui viene tolto il profilo ICC appare con colori spenti o alterati.
// metadata.js
import sharp from 'sharp';
// Conserva solo il profilo colore: niente GPS, modello o data di scatto
export function publishPhoto(input, output) {
return sharp(input)
.autoOrient()
.keepIccProfile()
.webp({ quality: 80 })
.toFile(output);
}
// Converte in sRGB, lo spazio colore che tutti i client interpretano allo stesso modo
export function publishAsSrgb(input, output) {
return sharp(input)
.autoOrient()
.toColorspace('srgb')
.webp({ quality: 80 })
.toFile(output);
}
// Archivio interno: conserva EXIF, ICC e XMP
export function archive(input, output) {
return sharp(input)
.keepMetadata()
.webp({ lossless: true })
.toFile(output);
}
export async function describe(input) {
const { format, width, height, hasAlpha, orientation, exif, icc, pages } =
await sharp(input).metadata();
return {
format,
width,
height,
hasAlpha,
orientation,
hasExif: Boolean(exif),
hasIcc: Boolean(icc),
frames: pages ?? 1,
};
}
Quando i metadati vengono rimossi bisogna ricordarsi dell'orientamento: le fotocamere salvano spesso i pixel nella posizione del sensore e annotano la rotazione nel tag EXIF Orientation. Se il tag sparisce senza che la rotazione sia stata applicata, la foto appare coricata. autoOrient() ruota fisicamente i pixel e rende il problema irrilevante.
Animazioni: da GIF a WebP
Le GIF animate sono un formato del 1987, limitato a 256 colori per fotogramma e con una compressione inefficiente. WebP animato supporta milioni di colori, la trasparenza a 8 bit e la compressione con perdita: il risparmio è spesso nell'ordine del 50-70%. Per lavorare con tutti i fotogrammi bisogna chiedere esplicitamente a sharp di caricarli, con l'opzione animated.
// animation.js
import sharp from 'sharp';
export async function gifToWebp(input, output) {
const source = sharp(input, { animated: true });
const { pages, delay, loop } = await source.metadata();
const info = await source
.webp({
quality: 75,
effort: 4,
// Mantiene il numero di ripetizioni della GIF (0 significa all'infinito)
loop: loop ?? 0,
delay,
// Prova anche la codifica senza perdita per ogni fotogramma e sceglie la migliore
mixed: true,
})
.toFile(output);
return { frames: pages, delays: delay, size: info.size };
}
// Ridimensionare un'animazione: sharp applica l'operazione a ogni fotogramma
export function resizeAnimation(input, output, width) {
return sharp(input, { animated: true })
.resize({ width, withoutEnlargement: true })
.webp({ quality: 70 })
.toFile(output);
}
// Estrarre il primo fotogramma come anteprima statica
export function poster(input, output) {
return sharp(input, { pages: 1 })
.webp({ quality: 80 })
.toFile(output);
}
Internamente sharp rappresenta un'animazione come un'unica immagine alta, con i fotogrammi impilati verticalmente: metadata() restituisce in pageHeight l'altezza del singolo fotogramma e in pages il loro numero. È un dettaglio da ricordare quando si combinano operazioni come extract(), che lavorano sulle coordinate dell'immagine complessiva. L'opzione mixed rallenta la codifica ma è molto efficace sulle GIF fatte di grafiche piatte, dove alcuni fotogrammi si comprimono meglio senza perdita.
Gestire i caricamenti in modo sicuro
Ogni immagine caricata da un utente è un input non fidato. Un attacco classico è la cosiddetta decompression bomb: un file di pochi kilobyte che dichiara dimensioni enormi, per esempio 30000 per 30000 pixel, e che durante la decodifica richiede gigabyte di memoria. sharp rifiuta per impostazione predefinita le immagini oltre circa 268 milioni di pixel, ma per un servizio di caricamento è bene fissare un limite più basso e controllare tutto ciò che si può controllare prima della decodifica.
// upload.js
import sharp from 'sharp';
import { readWebpInfo } from './webp-info.js';
const MAX_BYTES = 15 * 1024 * 1024;
const MAX_PIXELS = 40_000_000;
const ALLOWED_FORMATS = new Set(['jpeg', 'png', 'webp', 'gif', 'avif']);
export class UploadError extends Error {}
export async function processUpload(buffer) {
if (buffer.length > MAX_BYTES) {
throw new UploadError('File troppo grande');
}
// Se il client dichiara un WebP, l'intestazione deve essere coerente
const webp = readWebpInfo(buffer);
if (webp && webp.width * webp.height > MAX_PIXELS) {
throw new UploadError('Dimensioni dichiarate eccessive');
}
const image = sharp(buffer, {
limitInputPixels: MAX_PIXELS,
// Un file troncato o corrotto deve generare un errore, non un'immagine parziale
failOn: 'error',
});
let metadata;
try {
metadata = await image.metadata();
} catch {
throw new UploadError('Immagine non leggibile');
}
if (!ALLOWED_FORMATS.has(metadata.format)) {
throw new UploadError(`Formato non ammesso: ${metadata.format}`);
}
return image
.autoOrient()
.resize({ width: 2560, height: 2560, fit: 'inside', withoutEnlargement: true })
.keepIccProfile()
.webp({ quality: 82 })
.toBuffer({ resolveWithObject: true });
}
Il formato viene determinato da libvips leggendo il contenuto, non dall'estensione né dall'intestazione Content-Type della richiesta, che il client può impostare a piacere. Il ridimensionamento con fit: 'inside' garantisce un limite superiore per lato mantenendo le proporzioni: è una forma di normalizzazione che rende prevedibile lo spazio occupato su disco.
Servire WebP con la negoziazione dei contenuti
Quando le immagini originali restano in JPEG o PNG, si può decidere al momento della richiesta se servire WebP. I browser che lo supportano lo dichiarano nell'intestazione Accept, per esempio image/avif,image/webp,*/*. Il server sceglie la rappresentazione e, cosa fondamentale, risponde con Vary: Accept: senza questa intestazione una CDN o un proxy potrebbero memorizzare la versione WebP e servirla anche a un client che non la sa leggere.
Il server seguente usa solo il modulo node:http, genera la versione WebP alla prima richiesta e la salva in una cartella di cache. Una mappa di promesse in corso evita che dieci richieste simultanee per la stessa immagine avviino dieci conversioni.
// server.js
import { createServer } from 'node:http';
import { createReadStream } from 'node:fs';
import { access, mkdir, rename } from 'node:fs/promises';
import { extname, join, normalize, sep } from 'node:path';
import sharp from 'sharp';
const SOURCE_DIR = join(process.cwd(), 'media');
const CACHE_DIR = join(process.cwd(), 'cache');
const CONTENT_TYPES = { '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png' };
const inFlight = new Map();
function acceptsWebp(header = '') {
return header
.split(',')
.map((part) => part.trim().split(';'))
.some(([type, ...params]) => type === 'image/webp' && !params.some((p) => p.trim() === 'q=0'));
}
async function exists(path) {
try {
await access(path);
return true;
} catch {
return false;
}
}
async function ensureWebp(source, target) {
if (await exists(target)) return target;
if (!inFlight.has(target)) {
// Scrittura su file temporaneo e rinomina atomica: nessun client legge un file a metà
const temporary = `${target}.${process.pid}.tmp`;
const job = sharp(source)
.autoOrient()
.keepIccProfile()
.webp({ quality: 80 })
.toFile(temporary)
.then(() => rename(temporary, target))
.then(() => target)
.finally(() => inFlight.delete(target));
inFlight.set(target, job);
}
return inFlight.get(target);
}
function send(response, path, type) {
response.writeHead(200, {
'Content-Type': type,
'Cache-Control': 'public, max-age=31536000, immutable',
Vary: 'Accept',
});
createReadStream(path).pipe(response);
}
const server = createServer(async (request, response) => {
const url = new URL(request.url, 'http://localhost');
const relative = normalize(decodeURIComponent(url.pathname)).replace(/^([/\\])+/, '');
const source = join(SOURCE_DIR, relative);
const type = CONTENT_TYPES[extname(source).toLowerCase()];
// Blocca i tentativi di uscire dalla cartella delle immagini
if (!source.startsWith(SOURCE_DIR + sep) || !type || !(await exists(source))) {
response.writeHead(404).end();
return;
}
try {
if (acceptsWebp(request.headers.accept)) {
await mkdir(CACHE_DIR, { recursive: true });
const cacheName = relative.replaceAll(/[\\/]/g, '__').replace(/\.\w+$/, '.webp');
send(response, await ensureWebp(source, join(CACHE_DIR, cacheName)), 'image/webp');
} else {
send(response, source, type);
}
} catch (error) {
console.error(error);
response.writeHead(500).end();
}
});
server.listen(3000, () => console.log('Server in ascolto su http://localhost:3000'));
Il nome del file in cache appiattisce il percorso relativo, così due immagini omonime in cartelle diverse non entrano in conflitto. In un'applicazione Express o Fastify la logica è identica: cambia solo il modo di leggere l'intestazione e di impostare la risposta. In produzione, se le immagini cambiano, è prudente includere nel nome della cache anche un'impronta del contenuto o la data di modifica dell'originale.
Conversione in blocco con concorrenza controllata
Convertire un archivio esistente di migliaia di immagini è un altro scenario tipico. La tentazione è lanciare Promise.all su tutti i file, ma ogni conversione alloca buffer consistenti e il risultato è un picco di memoria ingestibile. sharp usa già un pool di thread nativi per parallelizzare il lavoro di libvips: lato JavaScript basta limitare il numero di immagini in elaborazione contemporaneamente.
// batch.js
import sharp from 'sharp';
import { availableParallelism } from 'node:os';
import { mkdir, readdir, stat } from 'node:fs/promises';
import { dirname, extname, join, relative } from 'node:path';
const EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif']);
async function* walk(dir) {
for (const entry of await readdir(dir, { withFileTypes: true })) {
const path = join(dir, entry.name);
if (entry.isDirectory()) yield* walk(path);
else if (EXTENSIONS.has(extname(entry.name).toLowerCase())) yield path;
}
}
export async function convertTree(sourceDir, targetDir, concurrency = availableParallelism()) {
// Senza cache interna la memoria resta stabile anche su migliaia di file
sharp.cache(false);
const stats = { converted: 0, failed: 0, savedBytes: 0 };
const running = new Set();
for await (const file of walk(sourceDir)) {
const target = join(targetDir, relative(sourceDir, file)).replace(/\.\w+$/, '.webp');
const task = (async () => {
try {
await mkdir(dirname(target), { recursive: true });
const animated = extname(file).toLowerCase() === '.gif';
const { size: before } = await stat(file);
const { size: after } = await sharp(file, { animated })
.webp({ quality: 80 })
.toFile(target);
stats.converted += 1;
stats.savedBytes += before - after;
} catch (error) {
stats.failed += 1;
console.error(`Errore su ${file}: ${error.message}`);
}
})();
running.add(task);
task.finally(() => running.delete(task));
// Attende che si liberi un posto prima di avviare il file successivo
if (running.size >= concurrency) await Promise.race(running);
}
await Promise.all(running);
return stats;
}
const [source = 'media', target = 'media-webp'] = process.argv.slice(2);
console.log(await convertTree(source, target));
Il generatore asincrono walk produce i percorsi uno alla volta, quindi anche un albero con centomila file non viene mai caricato per intero in memoria. Se il processo gira su un server che serve anche traffico web, conviene ridurre il parallelismo nativo con sharp.concurrency() per lasciare CPU alle richieste.
Decodificare WebP verso altri formati
Il percorso inverso serve meno spesso, ma serve: un'integrazione con un gestionale che accetta solo JPEG, un PDF generato da una libreria che non legge WebP, un'anteprima per un client di posta. Il codice è speculare a quello di codifica, con un dettaglio: JPEG non ha il canale alfa, quindi la trasparenza va appiattita su un colore di sfondo esplicito.
// decode.js
import sharp from 'sharp';
export function webpToJpeg(input, output) {
return sharp(input)
// Senza flatten le aree trasparenti diventerebbero nere
.flatten({ background: '#ffffff' })
.jpeg({ quality: 88, mozjpeg: true })
.toFile(output);
}
export function webpToPng(input, output) {
return sharp(input).png({ compressionLevel: 9 }).toFile(output);
}
// Pixel grezzi RGBA, per esempio per un'analisi o un algoritmo personalizzato
export async function rawPixels(input) {
const { data, info } = await sharp(input).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
return { pixels: data, width: info.width, height: info.height, channels: info.channels };
}
Testare il codice
Il parser dell'intestazione è il pezzo più delicato, perché lavora su offset e maschere di bit. Il modo più affidabile per testarlo è generare immagini reali con sharp in tutte e tre le varianti e verificare che il parser restituisca le stesse informazioni. Il test runner integrato in Node è sufficiente.
// webp-info.test.js
import { test } from 'node:test';
import assert from 'node:assert/strict';
import sharp from 'sharp';
import { readWebpInfo } from './webp-info.js';
const solid = (channels) => sharp({
create: { width: 123, height: 45, channels, background: { r: 200, g: 30, b: 60, alpha: 0.5 } },
});
test('riconosce un WebP con perdita', async () => {
const buffer = await solid(3).webp({ quality: 80 }).toBuffer();
assert.deepEqual(readWebpInfo(buffer), {
format: 'lossy', width: 123, height: 45, alpha: false, animated: false,
});
});
test('riconosce un WebP senza perdita con alfa', async () => {
const info = readWebpInfo(await solid(4).webp({ lossless: true }).toBuffer());
assert.equal(info.format, 'lossless');
assert.equal(info.alpha, true);
assert.equal(info.width, 123);
});
test('riconosce il formato esteso', async () => {
const info = readWebpInfo(await solid(4).webp({ quality: 80 }).toBuffer());
assert.equal(info.format, 'extended');
assert.equal(info.alpha, true);
assert.equal(info.height, 45);
});
test('rifiuta i file che non sono WebP', async () => {
assert.equal(readWebpInfo(await solid(3).png().toBuffer()), null);
assert.equal(readWebpInfo(Buffer.from('RIFF')), null);
});
Il terzo test è istruttivo: un'immagine con trasparenza codificata con perdita richiede il formato esteso, perché il canale alfa viaggia in un chunk ALPH separato dal fotogramma VP8. Si esegue tutto con node --test.
Conclusioni
In Node.js la gestione di WebP si riduce in gran parte a una buona conoscenza di sharp: una pipeline che legge da file, buffer o stream, applica orientamento, ridimensionamento e gestione dei metadati e scrive in WebP con un controllo fine sull'encoder. Attorno a questa pipeline, il lavoro vero è di ingegneria: misurare la qualità invece di sceglierla a caso, conservare il profilo colore ma non le coordinate GPS, limitare i pixel in ingresso, rispondere con Vary: Accept quando si negozia il formato e tenere sotto controllo la memoria nelle conversioni massive. Il piccolo parser dell'intestazione, infine, ricorda che dietro un formato apparentemente opaco c'è una struttura semplice e documentata, che possiamo interrogare in pochi byte senza decodificare nulla.