Internal caches

The thumbnailer service maintains three internal caches:

Image cache

The image cache stores images that are expensive to retrieve (namely images downloaded from the image server (dash.ubuntu.com) or extracted from video files). Images in this cache are kept at high resolution, up to a limit of max-thumbnail-size (usually 1920) pixels in the larger dimension (see thumbnailer-settings(5)). The image cache is used to create thumbnails at smaller sizes that are then inserted into the thumbnail cache (to avoid repeated download or extraction of the original images).

Thumbnail cache

The thumbnail cache stores images that are scaled to a size that was previously requested by a client. If a client asks for a thumbnail that was previously generated at the same size, it is returned from this cache.

Failure cache

The failure cache contains the keys for media (local or remote) for which no thumbnail could be generated, either because a local file does not contain artwork, or because the image server has returned an authoritative answer that no image is available. If a client asks for an image that is in the failure cache, the service does not try to create a thumbnail for some period of time, to avoid expensive repeated attempts to retrieve artwork that does not exist.

Commands that can selectively be applied to these caches use the following cache-id:

i

Image cache

t

Thumbnail cache

f

Failure cache

Sizes and scaling

Thumbnails are never larger than max-thumbnail-size in the larger dimension (usually 1920, see thumbnailer-settings(5)), even if a larger size is requested.

Commands that create thumbnails expect a size in pixels to be specified as follows:

widthxheight

Create a thumbnail scaled to fit a bounding box of width and height, for example, --size 640x480. If only a single dimension is provided, the thumbnail is scaled to fit into a square bounding box of the specified size, for example, -s 256.

Specifying a size with one dimension explicitly set to zero leaves that dimension unconstrained. For example, --size 0x480 produces a thumbnail no taller than 480 pixels of any width, (subject to the max-thumbnail-size limit).

Specifying a size of zero (or not specifying any size) is equivalent to specifying max-thumbnail-size in both dimensions.

Scaling always maintains the aspect ratio of the original image, and ensures that a thumbnail has a size of at least one pixel in the smaller dimension.

Requests for thumbnails that are larger than the original image are automatically reduced to the original image size, that is, original artwork is never scaled up.

Media formats and output files

Most common image formats, such as PNG, JPEG, BMP, and so on, are recognized. For streaming media, the recognized formats depend on the installed gstreamer codecs.

Thumbnails are always returned in PNG format, regardless of the encoding of the original image. The generated thumbnail file is tagged with the requested (not actual) image size. For example,

creates a file named screen_320x480.png.