~~NOTOC~~
{{ :xfce:xfce.tumbler.png?no link|}}
====== Tumbler - Available Plugins ======
The Tumbler package contains a D-Bus thumbnailing service based on the thumbnail management D-Bus specification. This is useful for generating thumbnail images of files. 

  * **[[#Configuration|Configuration]]**
  * **[[#Cover Thumbnailer|Cover Thumbnailer]]**
  * **[[#Customized Thumbnailers|Customized Thumbnailers]]**
  * **[[#Customized Thumbnailer for .dds files|Customized Thumbnailer for .dds files]]**
  * **[[#Customized Thumbnailer for folders|Customized Thumbnailer for folders]]**
  * **[[#Customized Thumbnailer for text-based documents|Customized Thumbnailer for text-based documents]]**
  * **[[#Customized Thumbnailer for comic book archives|Customized Thumbnailer for comic book archives]]**
  * **[[#Customized Thumbnailer for webp content|Customized Thumbnailer for webp content]]**
  * **[[#Customized Thumbnailer for stl content|Customized Thumbnailer for stl content]]**

----

===== Available Plugins =====
Tumbler allows to load a number plugins to support different file formats. Most plugins are loaded by default, if the required libraries are provided.
=== Image Thumbnailers ===
  * __JPEG-thumbnailer__
     * Dedicated to JPEG image files.
  * __Pixbuf-thumbnailer__
     * Supports all type gdk-pixbuf supports. The list depends on the installed optional libraries, but you can obtain a minimal mime type list by<code>
sed -n 's/MimeType=//p' /usr/share/thumbnailers/gdk-pixbuf-thumbnailer.thumbnailer
</code>
  * __Raw-thumbnailer__
     *  RAW image files using libopenraw (Adobe DNG, Canon CRW CR2, Epson ERF, Fuji RAF, Minolta MRW, Nikon NEF and NRW, Olympus ORF, Panasonic RAW and RW2, Pentax PEF, Sony ARW).
=== Video Thumbnailers ===
  * __Cover-thumbnailer__
     * Downloads video covers from omdbapi.com or themoviedb.org. [[#cover_thumbnailer|See details below]].
  * __ffmpeg-thumbnailer__
     * Main video plugin.
  * __GStreamer-thumbnailer__
     * Provides video and audio cover (e.g. mp3, flac, etc) thumbnails.
=== Document Thumbnailers ===
  * __Font-thumbnailer__
     * Provides thumbnails for font files.
  * __Poppler-thumbnailer__
     * Thumbnailer for PS/PDF files.
  * __ODF-thumbnailer__
     * Provides thumbnails for different open document types, ''oasis.opendocument'' (presentation, text,chart, image), ''sun.xml'' ( calc, writer, draw, impress. math) and some more.
  * __GEpub-thumbnailer__
     * Provides thumbnails for EPUB files.

=== External Thumbnailers ===
  * All thumbnailers provided by ''.thumbnailer'' desktop files. Also known as customized or desktop thumbnailers. [[#customized_thumbnailers|See examples below]].


[[|Back to Top]]
----

===== Configuration =====

Tumbler has since version 0.1.27 a configuration file to control the priority, locations and file sizes the plugin is used for: [[http://git.xfce.org/xfce/tumbler/plain/tumblerd/tumbler.rc|tumbler.rc]].

To override the default configuration, located in one of the xdg directories on your system, you can copy the rc-file to your ''$XDG_CONFIG_HOME'' directory.

NB: ''$XDG_CONFIG_HOME'' defaults to ''~/.config''.

  mkdir -p "${XDG_CONFIG_HOME:=~/.config}/tumbler"
  cp /etc/xdg/tumbler/tumbler.rc "$XDG_CONFIG_HOME/tumbler/"

Each group in the configuration file is responsible for the settings of a particular thumbnailer plugin. The following keys can be used to adjust a plugin:

? Disabled
! Disable the plugin, the values ''true'' and ''false'' are accepted.
? Priority
! Numeric value to control the priority of the plugin. If two plugins can provide thumbnails for the same scheme + mime-type combination, the plugin with the highest priority is used first.
? Locations
! A ;-separated path list the plugin will be used for. If the source file is not a child of one of the locations, the plugin won't be used and another plugin with a lower priority will be tried. Absolute paths, environment variables, ''~/'' and ''~username/'' are allowed. Leave empty to allow all locations.
? Excludes
! A ;-separated path list the plugin will not be used for. If the source file is a child of one of the locations, the plugin won't be used and another plugin with a lower priority will be tried. Absolute paths, environment variables, ''~/'' and ''~username/'' are allowed. Leave empty to exclude nothing. Please note that paths in ''Excludes'' precede those in ''Locations''.
? MaxFileSize
! Maximum size of the source file the plugin will still try to generate a thumbnail for. The size is in bytes, 0 disables the check.

As of Tumbler 4.17.0 (first stable release 4.18.0), these settings extend to [[#customized_thumbnailers|external thumbnailers]] of the desktop-thumbnailer plugin, by adding the group "X-Tumbler Settings" to the ''.thumbnailer'' files. Further instructions and an example are given at the end of the ''tumbler.rc'' file.

[[|Back to Top]]
----

===== Cover Thumbnailer =====

By default the cover thumbnailer is disabled. The reason is that it sends information (movie title extracted from the filename) to online services to retrieve a poster. This information is normally harmless, but it is private, so therefore it's not enabled by default.

In order to use the cover thumbnailer you need to copy the tumbler.rc file to your home directory as described above and set the ''Disabled'' key to ''false''. It is also advisable to set the Locations path to the directory where you store your movies.

  [CoverThumbnailer]
  Disabled=false
  Priority=3
  Locations=~/movies
  MaxFileSize=0
  #APIKey=your-api-key-from-themoviedb.org

The movie thumbnailer supports two different movie APIs. By default, the [[http://omdbapi.com|The Open Movie Database API]] is used. You can also choose to use [[http://themoviedb.org|The Movie DB]], but this site requires an API key which you have to [[http://docs.themoviedb.apiary.io/|request]] or uh... [[https://raw.github.com/xbmc/xbmc/master/addons/metadata.themoviedb.org/tmdb.xml|search]].\\
The advantage of the latter is that their database has better support for internationalized movie names.

After creating the rc file, it is best to log off and on again to restart Thunar and Tumbler, because both applications cache the mime-type combinations.

[[|Back to Top]]
----

===== Customized Thumbnailers =====
As of version 0.2.0, the desktop thumbnailer functionality has been added back into tumbler. This functionality supports custom ''.thumbnailer'' files placed in the ''XDG_DATA_DIRS/thumbnailers'' directories and the ''XDG_DATA_HOME/thumbnailers'' directory (which defaults to ''~/.local/share/thumbnailers''). The former is the place for system wide thumbnailers (normally in ''/usr/share/thumbnailers''), while the latter is the preferred place for the user's customized thumbnailers (see below).

Since 4.17.0 (first stable release 4.18.0), in case of several ''.thumbnailer'' files with the same name in the thumbnailer directories, the one placed in the highest priority directory override all the others.


==== Customized Thumbnailer for .dds files ====

For example, to create a custom thumbnailer for ''.dds'' files, do the following:
  - Create the appropriate ''.thumbnailer'' file:<file txt ~/.local/share/thumbnailers/dds.thumbnailer>
[Thumbnailer Entry]
Version=1.0
Encoding=UTF-8
Type=X-Thumbnailer
Name=dds Thumbnailer
MimeType=image/x-dds;
Exec=convert -thumbnail %s %i %o
</file>
  - Ensure that a dds mimetype exists in your system (you can view mimetypes with the Xfce4 Mime Type Editor). If it does not exist, create the necessary mime file:<file txt ~/.local/share/mime/packages/dds.xml><?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
    <mime-type type="image/x-dds">
        <comment>dds file</comment>
        <icon name="image"/>
        <glob-deleteall/>
        <glob pattern="*.dds"/>
    </mime-type>
</mime-info></file>...and run<code>
update-mime-database ~/.local/share/mime</code>

==== Customized Thumbnailer for folders ====

Another example are albums cover thumbnails for folders in a music collection. A custom thumbnailer can be added to e.g. add a file  ''folder.jpg'' or ''cover.jpg'' into a folder and display its thumbnail instead of the default folder icon:
<file txt ~/.local/share/thumbnailers/folder.thumbnailer>
[Thumbnailer Entry]
Version=1.0
Encoding=UTF-8
Type=X-Thumbnailer
Name=Folder Thumbnailer
MimeType=inode/directory;
Exec=sh -c '~/bin/folder-thumbnailer "$@"' _ %s %i %o %u
</file>

In order to support different names for the picture-file and to remove the thumbnail if not needed any more (display the default folder icon), a separate script is required:

<file sh ~/bin/folder-thumbnailer>
#!/bin/bash

covers=("$2"/{.,}{folder,cover}.{jpg,png})
for f in "${covers[@]}"; do
  [ -f "$f" ] && {
    cover=$f
    break
  }
done

if [ -z "$cover" ] || ! convert -thumbnail "$1" "$cover" "$3"; then
  gdbus call --session --dest=org.freedesktop.thumbnails.Cache1 --object-path /org/freedesktop/thumbnails/Cache1 \
             --method org.freedesktop.thumbnails.Cache1.Delete "['$4']" >/dev/null
fi
</file>

Don't forget to give execution permission to the file:

  chmod u+x ~/bin/folder-thumbnailer
  
and to restart Thunar and Tumbler so that the new folder mime type is taken into account.

Note: ImageMagick is a required dependency for this script.

==== Customized Thumbnailer for text-based documents ====
A thumbnailer for text-based documents can be created using the convert function from the ImageMagick package with the following thumbnailer file:

<file txt ~/.local/share/thumbnailers/text.thumbnailer>
[Thumbnailer Entry]
Version=1.0
Encoding=UTF-8
Type=X-Thumbnailer
Name=Text Thumbnailer
MimeType=text/plain;text/html;text/css;
Exec=sh -c '~/bin/textthumb "$@"' _ %s %i %o
</file>

And supporting script:

<file sh ~/bin/textthumb>
#!/bin/bash

iFile=$(<"$2")
tempFile=$(mktemp) && {
  echo "${iFile:0:1600}" > "$tempFile"
  convert -size 210x290 -background white -pointsize 5 -border 10x10 -bordercolor "#CCC" caption:@"$tempFile" "$3"
  rm "$tempFile"
}
</file>

You can add additional mime types to the ''MimeType'' line of the thumbnailer file to support additional text-based document types.

==== Customized Thumbnailer for comic book archives ====
A thumbnailer for comic book archives (cbr, cbz, cbt, cb7) can be created using the comicthumb utility (search for it your distro's repositories). If not already present as ''/usr/share/thumbnailers/comicthumb.thumbnailer'', create the following thumbnailer file:
<file txt ~/.local/share/thumbnailers/comicthumb.thumbnailer>
[Thumbnailer Entry]
TryExec=comicthumb
Exec=comicthumb %u %o %s
MimeType=application/x-cb7;application/x-cbr;application/x-cbt;application/x-cbz;application/x-ext-cb7;
application/x-ext-cbr;application/x-ext-cbt;application/x-ext-cbz;application/vnd.comicbook-rar
</file>

==== Customized Thumbnailer for webp content ====
Note: Make sure there is an image/webp mimetype defined in your system.
<file txt ~/.local/share/thumbnailers/webp.thumbnailer>
[Thumbnailer Entry]
Version=1.0
Encoding=UTF-8
Type=X-Thumbnailer
Name=webp Thumbnailer
MimeType=image/webp;
Exec=sh -c '~/bin/webpthumbs "$@"' _ %s %i %o
</file>

And supporting script:

<file sh ~/bin/webpthumbs>
#!/bin/bash

if tempfile=$(mktemp) && /usr/bin/webpmux -get frame 1 "$2" -o "$tempfile"; then
  /usr/bin/convert -thumbnail "$1" "$tempfile" "$3" 
else
  /usr/bin/convert -thumbnail "$1" "$2" "$3"
fi

[ -f "$tempfile" ] && rm "$tempfile"
</file>

==== Customized Thumbnailer for stl content ====
<file txt ~/.local/share/thumbnailers/stl.thumbnailer>
[Thumbnailer Entry]
Version=1.0
Encoding=UTF-8
Type=X-Thumbnailer
Name=STL Thumbnailer
MimeType=model/stl;
Exec=sh -c '~/bin/stl-thumbnailer "$@"' _ %i %o %s
</file>

And supporting script:

<file sh ~/bin/stl-thumbnailer>
#!/bin/bash

if (($# < 3)); then
  echo "$0: input_file_name output_file_name size"
  exit 1
fi

INPUT_FILE=$1
OUTPUT_FILE=$2
SIZE=$3

if TEMP=$(mktemp --directory --tmpdir tumbler-stl-XXXXXX); then
  cp "$INPUT_FILE" "$TEMP/source.stl"
  echo 'import("source.stl", convexity=10);' > "$TEMP/thumbnail.scad"
  openscad --imgsize "500,500" -o "$TEMP/thumbnail.png" "$TEMP/thumbnail.scad" 2>/dev/null
  convert -thumbnail "$SIZE" "$TEMP/thumbnail.png" "$OUTPUT_FILE" &>/dev/null
  rm -rf $TEMP
fi
</file>

[[|Back To Top]]
----
[[:xfce:tumbler:start:|Back to Main Tumbler documentation page]]

[[:xfce:thunar:|Back to Thunar documentation page]]