Project

Purpose

Thumbrella is a server that creates thumbnails and metadata for online media. The code is open source under the Apache 2.0 license, making it easy to customize, use, and contribute to.

A thumbnail is a lightweight visual representation of something’s identity. Thumbrella is focused on the generation of small, single images to represent the identity of various media and file types.

At the time of creation, there weren’t many existing options. Minimal thumbnail examples are integrated into file explorer interfaces, but nothing is easy to integrate into separate projects.

Initial Goals

• Strive for developer experience and flexible open source use cases
• Browsers can only reliably render a handful of image formats
• HTTP streams don’t provide the random access needed by most thumbnail tools
• Take advantage of the excellent caching definitions from HTTP
• Create a standalone, static executable with as much functioanlity as possible
• Configuration free, just run for quality results
• Should work on Windows, MacOS, and Linux
• Create an architecture that allows astonishingly cheap hosting
• Pass those savings on to customers and make a reliable free tier
• Simple HTTP API for the simple cases
• Provide fantastic client libraries that go even farther

How It Compares

If you’re evaluating thumbnail solutions, here is how Thumbrella relates to common alternatives:

Approach	Example	Thumbrella difference
Browser-only <img>	Standard HTML	Only supports ~5 image formats. No video, documents, or camera photos.
Cloud image services	Imgix, Cloudinary	These are focused on images and producing high slow results, and generally 100x more expensive.
Server-side ffmpeg scripts	Custom bash/python	Challenges to distribute, deploy, and integrate into hosted environments.
Image libraries	Sharp, libvips, ImageMagick	Images only and inefficient on remote media.
Thumbrella		Open source server + clients. One binary, 100+ formats, CDN-ready.

Authors

Peter Shinners, creator and maintainer of Thumbrella.

Has been building software for games, film, and open source software for several decades. He works primarily in Python, with a focus on artist tools and studio pipeline backends. He is the original developer of Pygame along with various small and specialized projects.

Thumbnail Output

Every Thumbrella thumbnail shares a consistent set of characteristics. These are not configurable, the output is opinionated by design to keep the API simple and the results predictable. Custom sizes, formats, and styling are an intended future feature but not part of the initial release.

Property	Value
Size	250 × 200 pixels (5:4 aspect ratio)
Format	JPEG, quality ~60 or less
Opacity	Transparency composited over a neutral background
Cropping	Loosely represents the media’s aspect ratio
Look	Lightweight image processing for visual consistency

Thumbnails are small, typically 5–10 KB, and optimized for fast loading. The JPEG compression quality is deliberately low and lossy. Enough to recognise the content, not for archival reproduction.

The resulting thumbnail is always a full edge to edge 5:4. This consistency is intended to simplify client uses and help galleries and tools predictable. The thumbnail is still cropped to represent the aspect ratio used by the source media.

Every request comes with a resulting image. For formats Thumbrella does not understand it will still classify the media type and provide a simple placeholder for that media. Applications don’t need special error-handling code paths for missing or failed thumbnails.

Each thumbnail result also contains lightweight metadata from the source media. This describes the resolutions for images, lengths of videos, and more. The Result structure for each thumbnail.

Unsupported Features

There is no way to configure the style, resolution, or format of the thumbnails. The settings are hardcoded into the converter and cannot be changed. The thumbnails are never animated.

This is not an image optimization or viewing service. The thumbnails are intended to look good but are low resolution with low quality compression. It is not a media viewing toolset, it provides no interactive or optimized viewing of the media itself.

Thumbrella does not generate thumbnails for websites. This would be an ideal target for the future, but there are no immediate plans to support this.

Thumbrella runs as a standalone server. It cannot be run inside a browser environment.

GitHub Repositories

Thumbrella is hosted across several GitHub projects under the thumbrella-dev organization. Everything is released under the Apache-2 license.

The Github organization also has a simple discussion section and news posts.

Description	Repository
Thumbrella server in Rust	thumbrella-dev / thumbrella
Public client packages (TypeScript, Python, Rust)	thumbrella-dev / clients
Project information and documentation (this site)	thumbrella-dev / website