README

Thumbro

Can we get Thumbor for the wiki?
We have Thumbor at home.
Thumbor at home:

Thumbro improves and expands thumbnail generation in MediaWiki. Instead of relying on a single tool, it automatically picks the most suitable image library for each file format — so every thumbnail comes out at the best quality and smallest size, with no manual tuning and room to add better libraries over time. Forked from Extension:VipsScaler.

Features

• Routes each format to the best-suited image library automatically (currently libvips and libwebp), instead of MediaWiki's default ImageMagick and GD
• Produces higher-quality, smaller thumbnails — including for animated images
• Renders WebP thumbnails by default for GIF, JPEG, PNG, and WebP (including animated)
• Lets you fine-tune encoding per format with custom load and save options
• Extends thumbnail support to more formats, such as animated WebP
• Adds a <source> element to images via the ThumbroBeforeProduceHtml hook
• Adds a hidden anchor so web crawlers can reach the original-resolution image (T54647)

Installation

1. Install the image libraries Thumbro uses. libvips is required; libwebp is recommended for crisp, compact animated-GIF thumbnails. On Debian-based systems:

apt-get install libvips-tools webp

1. Download the extension and place the files in a directory called Thumbro in your extensions/ folder.
2. Add the following to the bottom of your LocalSettings.php, after all other extensions:

wfLoadExtension( 'Thumbro' );

1. ✔️ Done — visit Special:Version on your wiki to confirm the extension is installed.

Configuration

ℹ️ Thumbro works out of the box — no configuration required.

$wgThumbroLibraries

The image libraries Thumbro can run, keyed by library. Each library maps its binaries (by binary name) to their executable paths. libwebp ships two tools — gif2webp and cwebp — so it owns both.

Default:

$wgThumbroLibraries = [
	'libvips' => [ 'vipsthumbnail' => '/usr/bin/vipsthumbnail' ], // resize (+ vips-webp encode)
	'libwebp' => [
		'gif2webp' => '/usr/bin/gif2webp', // animated-GIF encode
		'cwebp'    => '/usr/bin/cwebp',     // static-WebP encode
	],
];

$wgThumbroOptions

Controls how each file type is thumbnailed as a resize → encode pipeline. The defaults are tuned per format, so most wikis never need to change this.

Each MIME block has:

Encoders: vips-webp (libvips webpsave — also handles animation), cwebp (libwebp, static only — more byte-efficient), gif2webp (libwebp, animated). when guards match the file's capabilities: animated, alpha (transparency), underThreshold (area ≤ $wgThumbroMaxAnimatedArea).

Default (abridged):

$wgThumbroOptions = [
	// Static WebP → cwebp (smaller); animated WebP → vips; vips catch-all if cwebp is absent.
	'image/webp' => [
		'enabled' => true,
		'resize'  => [ 'options' => [] ],
		'encode'  => [
			[ 'encoder' => 'vips-webp', 'when' => [ 'animated' => true ],
			  'options' => [ 'strip' => 'true', 'Q' => '90', 'smart_subsample' => 'true' ] ],
			[ 'encoder' => 'cwebp', 'options' => [ 'q' => '80', 'm' => '6' ] ],
			[ 'encoder' => 'vips-webp',
			  'options' => [ 'strip' => 'true', 'Q' => '90', 'smart_subsample' => 'true' ] ],
		],
	],
	'image/jpeg' => [
		'enabled' => true,
		'resize'  => [ 'options' => [] ],
		'encode'  => [ [ 'encoder' => 'vips-webp',
			'options' => [ 'strip' => 'true', 'Q' => '80', 'smart_subsample' => 'false', 'effort' => '6' ] ] ],
	],
	'image/png' => [
		'enabled' => true,
		'resize'  => [ 'options' => [] ],
		'encode'  => [ [ 'encoder' => 'vips-webp',
			'options' => [ 'near_lossless' => 'true', 'Q' => '60', 'strip' => 'true' ] ] ],
	],
	// GIF: transparent animation → gif2webp; opaque animation → vips animated; else vips first-frame.
	'image/gif' => [
		'enabled' => true,
		'resize'  => [ 'options' => [] ],
		'encode'  => [
			[ 'encoder' => 'gif2webp', 'when' => [ 'animated' => true, 'alpha' => true, 'underThreshold' => true ],
			  'options' => [ 'mixed' => '', 'q' => '80', 'm' => '4' ] ],
			[ 'encoder' => 'vips-webp', 'when' => [ 'animated' => true, 'underThreshold' => true ],
			  'options' => [ 'strip' => 'true', 'Q' => '90', 'smart_subsample' => 'true' ] ],
			[ 'encoder' => 'vips-webp',
			  'options' => [ 'strip' => 'true', 'Q' => '90', 'smart_subsample' => 'true' ] ],
		],
	],
];

Other options

Comparing thumbnails

Thumbro ships a special page for comparing thumbnails before and after Thumbro. Enable it with:

// Enable the Special:ThumbroTest page
$wgThumbroExposeTestPage = true;

To keep the "before" thumbnail untouched by Thumbro, either disable Thumbro site-wide:

// Disable Thumbro site-wide
$wgThumbroEnabled = false;

…or disable the specific file format you want to test under $wgThumbroOptions.

Requirements

• MediaWiki 1.43.0 or later
• libvips (8.14 or later; older versions may work but are untested) — required. Drives core thumbnail generation via the vipsthumbnail command.
• libwebp (the cwebp and gif2webp tools; Debian/Ubuntu webp package) — recommended. cwebp encodes static WebP thumbnails more compactly than libvips; gif2webp encodes animated GIFs to compact animated WebP, far smaller than libvips for transparent animations. Without it, both fall back to libvips automatically.
• Imagick — optional. Powers the detailed comparison statistics on Special:ThumbroTest.