Customize Tumbler's Thumbnail Entries on Arch Linux
We'll go over how to detect mime types and customize ffmpegthumbnailer to support additional mime types for certain files.
This post is going to be related to solving a problem I had around MKV files no longer getting thumbnails generated for them.
Along the way we’ll go over how to debug issues around thumbnails not being generated and how to customize Tumbler to generate thumbnails for different MIME types which will use ffmpegthumbnailer to do the generation.
I like having thumbnails get generated for images and videos. It’s useful to see them in file explorers such as Thunar or whatever you prefer.
You can get this ability by installing these packages from the official Arch repo:
After opening your file explorer, you’ll start to see thumbnails get generated on demand.
# Symptoms and Debugging
In early July 2026 I noticed MKV files (videos) weren’t having thumbnails get generated for them, instead the default video icon was being used. I create a lot of MKV files because I have OBS set up to record videos using that format.
Prior to July, thumbnails would get generated without issues. If I opened Thunar and browsed a directory with MKV files, they would get generated.
I ran journalctl --boot --user --unit tumblerd to look through logs, hoping
to maybe see errors thrown by tumbler but there was nothing of interest. It
only showed a few warnings for plugins I don’t have which was unrelated.
Then I started to better understand how thumbnails get generated.
At the very least I was 99% sure ffmpegthumbnailer was involved since it
creates the thumbnails. At the time of this post, the last release was in
December 2025 so a recent update there didn’t break it, but I wanted to
explore what files are related to this package.
With Arch Linux, that’s a quick task:
$ pacman -Ql ffmpegthumbnailer
ffmpegthumbnailer /usr/
ffmpegthumbnailer /usr/bin/
ffmpegthumbnailer /usr/bin/ffmpegthumbnailer
ffmpegthumbnailer /usr/include/
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/ffmpegthumbnailertypes.h
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/filmstripfilter.h
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/ifilter.h
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/imagetypes.h
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/videoframe.h
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/videothumbnailer.h
ffmpegthumbnailer /usr/include/libffmpegthumbnailer/videothumbnailerc.h
ffmpegthumbnailer /usr/lib/
ffmpegthumbnailer /usr/lib/libffmpegthumbnailer.so
ffmpegthumbnailer /usr/lib/libffmpegthumbnailer.so.4
ffmpegthumbnailer /usr/lib/libffmpegthumbnailer.so.4.16.1
ffmpegthumbnailer /usr/lib/pkgconfig/
ffmpegthumbnailer /usr/lib/pkgconfig/libffmpegthumbnailer.pc
ffmpegthumbnailer /usr/share/
ffmpegthumbnailer /usr/share/man/
ffmpegthumbnailer /usr/share/man/man1/
ffmpegthumbnailer /usr/share/man/man1/ffmpegthumbnailer.1.gz
ffmpegthumbnailer /usr/share/thumbnailers/
ffmpegthumbnailer /usr/share/thumbnailers/ffmpegthumbnailer.thumbnailer
The last file listed above looked interesting. As of the December 2025 release, it looked like this:
$ cat /usr/share/thumbnailers/ffmpegthumbnailer.thumbnailer
[Thumbnailer Entry]
TryExec=ffmpegthumbnailer
Exec=ffmpegthumbnailer -i %i -o %o -s %s -f
MimeType=video/3gpp;video/3gpp2;video/annodex;video/dv;video/isivideo;video/mj2;video/mp2t;video/mp4;video/mpeg;video/ogg;video/quicktime;video/vnd.avi;video/vnd.mpegurl;video/vnd.radgamettools.bink;video/vnd.radgamettools.smacker;video/vnd.rn-realvideo;video/vnd.vivo;video/vnd.youtube.yt;video/wavelet;video/webm;video/x-anim;video/x-flic;video/x-flv;video/x-javafx;video/x-matroska;video/x-matroska-3d;video/x-mjpeg;video/x-mng;video/x-ms-wmv;video/x-nsv;video/x-ogm+ogg;video/x-sgi-movie;video/x-theora+ogg;application/mxf;application/vnd.ms-asf;application/vnd.rn-realmedia;application/x-matroska;application/ogg;
It has 3 entries for MKV files: video/x-matroska;video/x-matroska-3d;application/x-matroska;
By the way, on Arch you can do a reverse lookup on a file to see which package
it’s associated with by running pacman -Qo /usr/share/thumbnailers/ffmpegthumbnailer.thumbnailer.
Finding the MIME type of MKV Files
The next step was figuring out what MKV files identify as for their MIME type:
$ xdg-mime query filetype example-video.mkv
video/x-matroska
That’s confusing because that MIME type is covered by the thumbnailer file.
You can run Bash with -x to get more details since xdg-mime is a shell
script:
$ bash -x xdg-mime query filetype example-video.mkv
I’ve done videos about set -x, in our case here near the bottom of the output you’ll see:
+ /usr/bin/file --brief --dereference --mime-type example-video.mkv
video/x-matroska
This demonstrates that xdg-mime is using the file command to determine the
MIME type, at least on my system with niri. It can differ based on your desktop
environment. Also, other tools may pick different MIME back-ends to use.
The file command uses the libmagic library.
Depending on your desktop environment, xdg-mime may use GLib / GIO and the
data comes from the shared-mime-info package in Arch’s repo. If you run gio info -a standard::content-type example-video.mkv directly, that returns
video/matroska, at least at the time of this post. That’s due to this
commit
that I found while poking around.
So then I thought maybe Thunar isn’t using xdg-mime or more specifically
libmagic.
Finding How Thunar Sends MIME types
We can use D-Bus for this. I ran the D-Bus command below, opened Thunar and then created an MKV file with OBS. Once I navigated to the directory with that file this was emitted.
I’m going to remove a lot of lines for the sake of brevity, but check this out:
$ dbus-monitor --session "interface='org.freedesktop.thumbnails.Thumbnailer1'"
array [
string "video/matroska"
]
It looks like the MIME type being sent to Tumbler is video/matroska and that
is missing from the ffmpegthumbnailer file. At this point, Tumbler can’t
render a thumbnail because it doesn’t know what to do with video/matroska.
# Customizing ffmpegthumbnailer’s Tumbler Entry
I confirmed in the docs that Tumbler supports adding *.thumbnailer files and
you can add your own in ~/.local/share/thumbnailers, so I created
mkv.thumbnailer, the file name doesn’t need to match the extension, I named
it that so it makes sense to a human.
Here’s what I added to the above file. The main takeaway is I added
video/matroska since that’s what MKV files identify as. The other 2 lines
were copied directly from the default
/usr/share/thumbnailers/ffmpegthumbnailer.thumbnailer file.
[Thumbnailer Entry]
TryExec=ffmpegthumbnailer
Exec=ffmpegthumbnailer -i %i -o %o -s %s -f
MimeType=video/matroska;
Then I restarted Tumbler with systemctl --user restart tumblerd and closed
Thunar (thunar -q). After re-opening Thunar and going to a directory with MKV
files, thumbnails were being generated again. Victory!
If you’re using DotFriedRice this is already set up for you.
This Is Only Temporary
Turns out ffmpegthumbnailer was patched a few days
later to support the
updated format and the next release should have it. Once that’s released then
the above ~/.local/share/thumbnailers/mkv.thumbnailer file can be deleted.
It took about half an hour to arrive at this but I love little debugging adventures. For me the journey is more important than the destination. Now I know more about how thumbnails get generated, how to customize Tumbler and what’s responsible for associating MIME types to a file. Learning more about your system is fun!
The video below shows running some of the commands.
# Demo Video
Timestamps
- 0:57 – Seeing files associated with a package
- 2:25 – Looking at journalctl logs for tumbler
- 3:01 – Checking the MIME type of a file
- 5:03 – xdg-mime uses different backends based on your DE
- 6:30 – Using D-Bus to see what’s happening
- 7:45 – Creating a custom tumbler thumbnailer file
- 9:48 – Verifying the last minute tweak worked
What are some stories on how you debugged something? Let me know below.