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

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

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

wfLoadExtension( 'Thumbro' );

✔️ 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:

Key	Description
`enabled`	Turn Thumbro on or off for this file type
`minArea` / `maxArea`	Optional: only handle sources whose area (px²) is within range
`resize`	The resize stage: `{ "options": { … } }` — libvips load/resize options
`encode`	An ordered list of encoder choices. Each entry is `{ "encoder", "when"?, "options" }`. The first entry whose `when` capability guard the file satisfies is used; an entry with no `when` is the catch-all (put it last). Each encoder owns its own `options`.

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

Name	Description	Values	Default
`$wgThumbroMaxAnimatedArea`	Largest animation Thumbro will fully re-encode, measured as width × height × frames. Bigger animations are rendered as a single static frame to keep thumbnailing fast.	integer	`25000000`
`$wgThumbroEnabled`	Disable Thumbro across the wiki (the Special:ThumbroTest page still works)	`true` / `false`	`true`
`$wgThumbroExposeTestPage`	Enable the Special:ThumbroTest comparison page	`true` / `false`	`false`
`$wgThumbroTestExpiry`	Cache lifetime, in seconds, for images streamed to Special:ThumbroTest	integer	`3600`

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.

starcitizentools / thumbro

Maintainers

Package info

Statistics

Security