1
.TH thumbnailer\-admin 1 "05 August 2015" "Ubuntu" "Linux User's Manual"
4
thumbnailer\-admin \- Thumbnailer administrative tool
13
The \fBthumbnailer\-admin\fP program provides a simple administrative tool to access
14
the \fBthumbnailer\-service\fP(1), for example, to retrieve a thumbnail, display
15
statistics, or selectively clear one ore more of the service's internal caches.
17
The thumbnailer service maintains three internal caches:
20
The image cache stores images that are expensive to retrieve (namely
21
images downloaded from the image server (dash.ubuntu.com) or extracted from audio
22
or video files). Images in the this cache are kept at high resolution,
23
up to a limit of \fBmax\-thumbnail\-size\fP (usually 1920) pixels in the larger dimension (see
24
\fBthumbnailer\-settings\fR(5)\fP). The image cache
25
is used to create thumbnails at smaller sizes that are then inserted
26
into the thumbnail cache (to avoid repeated download or extraction
27
of the original images).
30
The thumbnail cache stores images that are scaled to a size that was previously requested
31
by a client. If a client asks for a thumbnail that was previously generated at the same size,
32
it is returned from this cache.
35
The failure cache contains the keys for media (local or remote) for which no thumbnail
36
could be generated, either because a local file does not contain artwork, or because
37
the image server has returned an authoritative answer that no image is available.
38
If a client asks for an image that is in the failure cache, the service does not
39
try to create a thumbnail for some period of time, to avoid expensive repeated
40
attempts to artwork that does not exist.
42
Commands that can selectively be applied to these caches use the following \fIcache\-id\fP:
52
.SS "Sizes and scaling"
53
Commands that create thumbnails expect a size in pixels to be specified as follows:
55
\fIwidth\fP\fBx\fP\fIheight\fP
56
Create a thumbnail scaled to fit a bounding box of \fIwidth\fP and \fIheight\fP, for example,
57
\fB\-\-size 640x480\fP. If only a single dimension is provided, the thumbnail is scaled to fit into
58
a square bounding box of the specified size, for example, \fB\-s 256\fP.
60
Scaling always maintains the aspect ratio of the original image, and ensures that a thumbnail
61
has a size of at least one pixel in the smaller dimension.
63
Specifying a size of zero (or not specifying any size) is equivalent to specifying \fBmax\-thumbnail\-size\fP
64
(see \fBthumbnailer\-settings\fR(5)\fP).
66
Requests for thumbnails that are larger than the original image are automatically reduced to the original
67
image size, that is, original artwork is never scaled up.
68
.SS "Media formats and output files"
69
Most common image formats, such as PNG, JPEG, BMP, and so on, are recognized. For streaming media, the
70
recognized formats depend on the installed gstreamer codecs.
72
Thumbnails are always returned in JPEG format, regardless of the encoding of the original image. The generated
73
thumbnail file is tagged with the requested (not actual) image size. For example,
76
.B thumbnailer\-admin get \-\-size=320x240 screen.png
79
creates a file named \fBscreen_320x480.jpg\fP.
83
.B thumbnailer\-admin clear \fR[\fIcache\-id\fR]
84
Clear all internal caches.
86
.B thumbnailer\-admin stats \fR[\fIcache\-id\fR]
87
Display cache statistics.
89
.B thumbnailer\-admin zero\-stats \fR[\fIcache\-id\fR]
90
Zero statistics counters.
92
.B thumbnailer\-admin get file \fR[\fIdir\fR]
93
Get a thumbnail from a file.
95
.B thumbnailer\-admin get\-artist artist album \fR[\fIdir\fR]
96
Get an artist thumbnail from the image server.
98
.B thumbnailer\-admin get\-album artist album \fR[\fIdir\fR]
99
Get an album thumbnail from the image server.
101
.B thumbnailer\-admin compact
102
Compact internal caches.
104
.B thumbnailer\-admin shutdown
105
Shut down the thumbnailer service.
107
.SH COMMAND REFERENCE
108
.B thumbnailer\-admin \-\-help
110
.B thumbnailer\-admin \-h
112
Display a general help message for all commands.
116
.B thumbnailer\-admin clear \fR[\fIcache\-id\fR]
128
Clear all three internal caches. If \fIcache\-id\fP is provided, clear only the selected cache.
132
.B thumbnailer\-admin stats \fR[\fIcache\-id\fR]
148
Show histogram of entry sizes.
152
Display detailed cache statistics. If \fIcache\-id\fP is provided, limit the display to the selected cache.
156
.B thumbnailer\-admin zero\-stats \fR[\fIcache\-id\fR]
168
Reset the statistics counters and timestamps to zero. If \fIcache\-id\fP is provided, reset the
169
statistics only for the selected cache.
173
.B thumbnailer\-admin get file \fR[\fIdir\fR]
185
.B \-\-size \fIpixels\fP
187
.B \-\-s \fIpixels\fP
189
Set the thumbnail size.
193
Extract a thumbnail from the specified media \fBfile\fP.
195
If \fIdir\fP is specified, place the thumbnail into the specified directory (default: current directory).
199
.B thumbnailer\-admin get\-artist artist album \fR[\fIdir\fR]
211
.B \-\-size \fIpixels\fP
213
.B \-\-s \fIpixels\fP
215
Set the thumbnail size.
219
Retrieve artist artwork for the specified \fBartist\fP and \fBalbum\fP. It is necessary to specify an album
220
title because artist names alone can be ambiguous.
222
If \fIdir\fP is specified, place the thumbnail into the specified directory (default: current directory).
226
.B thumbnailer\-admin get\-album artist album \fR[\fIdir\fR]
238
.B \-\-size \fIpixels\fP
240
.B \-\-s \fIpixels\fP
242
Set the thumbnail size.
246
Retrieve album cover artwork for the specified \fBartist\fP and \fBalbum\fP.
248
If \fIdir\fP is specified, place the thumbnail into the specified directory (default: current directory).
252
.B thumbnailer\-admin compact \fR[\fIcache\-id\fR]
264
Compact all three internal caches so the take up the smallest possible amount of disk space. If \fIcache\-id\fP is provided, clear only the selected cache.
266
After some time of use, the on\-disk size of a cache can be 25\(en30% larger than its nominal size. Compaction reclaims
267
the wasted space, but is slow and, while in progress, other thumbnail requests are delayed until compaction completes.
268
(It can take tens of seconds to compact a cache with a nominal size of 100 MB, depending on the speed of the hardware.)
272
.B thumbnailer\-admin shutdown
284
Shut down the thumbnailer service. This is useful mainly after changing settings (which are read only once when the
289
.B thumbnailer\-service\fR(1)\fP, thumbnailer\-settings\fR(5)\fP
added
removed
man/thumbnailer-admin.1
