Jump to content

Thumbnails: Difference between revisions

From NixOS Wiki
Crazivik (talk | contribs)
No edit summary
Crazivik (talk | contribs)
consolidated repeated code from various code blocks into a single block in new 'troubleshooting sub-sesction'
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{expansion|Explain how thumbnails can be configured in different file managers, preferably by linking to their articles}}
{{expansion|Explain how thumbnails can be configured in different file managers, preferably by linking to their articles}}


== Creating custom thumbnailers ==
== '''Enabling Thumbnailers''' ==
On minimal / custom desktop environments thumbnails in file explorers may not work by default. For example:
 
* GNOME environments with the option <code>services.gnome.core-utilities.enable = false;</code>
* Custom environments built from ground-up using window managers like sway or hyperland
 
=== Save yourself hours of troubleshooting!! ===
Thumbnailers may already be installed in your system as dependencies of image/video applications but are not activated.
 
Run <code>cd /run/current-system/sw/share/thumbnailers && ls</code> to list installed thumbnailers. If relevant .thumbnailer files are present and we still don't have thumbnails in our file explorer then we may need to activate them by updating symlinks to <code>share/thumbnailers</code>
 
<syntaxhighlight lang="nix">
# configuration.nix
{
 
  environment.pathsToLink = [
    "share/thumbnailers"
  ];
 
}
</syntaxhighlight>
 
=== Enable Video Thumbnails ===
To enable thumbnails for video files use <code>ffmpeg-headless</code> to decode videos and <code>fmpegthumbnailer</code> to generate thumbnails.
 
Thumbnails for the following MimeTypes are enabled: ''video/jpeg; video/mp4; video/mpeg; video/quicktime; video/x-ms-asf; video/x-ms-wm; video/x-ms-wmv; video/x-ms-asx; video/x-ms-wmx; video/x-ms-wvx; video/x-msvideo; video/x-flv; video/x-matroska; application/x-matroska; application/mxf; video/3gp; video/3gpp; video/dv; video/divx; video/fli; video/flv; video/mp2t; video/mp4v-es; video/msvideo; video/ogg; video/vivo; video/vnd.avi; video/vnd.divx; video/vnd.mpegurl; video/vnd.rn-realvideo; application/vnd.rn-realmedia; video/vnd.vivo; video/webm; video/x-anim; video/x-avi; video/x-flc; video/x-fli; video/x-flic; video/x-m4v; video/x-mpeg; video/x-mpeg2; video/x-nsv; video/x-ogm+ogg; video/x-theora+ogg.''
 
<syntaxhighlight lang="nix">
# configuration.nix
{ pkgs, ... }:
{
 
  environment.systemPackages = with pkgs; [
    ffmpeg-headless
    ffmpegthumbnailer
  ];
 
  # 'ffmpegthumbnailer.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers'
 
}
</syntaxhighlight>
 
=== Enable Image Thumbnails ===
To enable thumbnails for image files use <code>gdk-pixbuf</code> to decode images and generate thumbnails.
 
Thumbnails for the following MimeTypes are enabled: ''image/png; image/jpeg; image/bmp; image/x-bmp; image/x-MS-bmp; image/gif; image/x-icon; image/x-ico; image/x-win-bitmap; image/vnd.microsoft.icon; application/ico; image/ico; image/icon; text/ico; image/x-portable-anymap; image/x-portable-bitmap; image/x-portable-graymap; image/x-portable-pixmap; image/tiff; image/x-xpixmap; image/x-xbitmap; image/x-tga; image/x-icns; image/x-quicktime; image/qtif.''
 
<syntaxhighlight lang="nix">
# configuration.nix
{ pkgs, ... }:
{
 
  environment.systemPackages = with pkgs; [
    gdk-pixbuf
  ];
 
  # 'gdk-pixbuf-thumbnailer.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers'
 
}</syntaxhighlight>
 
=== Enable HEIF Image Thumbnails ===
To enable thumbnails for HEIF image format use <code>libheif</code> to decode HEIF images and <code>libheif.out</code> to generate thumbnails.
 
Thumbnails for the following MimeTypes are enabled: ''image/heif; image/avif.''
 
<syntaxhighlight lang="nix">
# configuration.nix
{ pkgs, ... }:
{
 
  environment.systemPackages = with pkgs; [
    libheif
    libheif.out
  ];
 
  # 'heif.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers'
 
}
</syntaxhighlight>
 
=== Enable RAW (Camera) Image Thumbnails ===
 
==== nufraw-thumbnailer ====
To enable thumbnails for camera RAW format use <code>nufraw</code> to decode RAW images and <code>nufraw-thumbnailer</code> to generate thumbnails.
 
Thumbnails for the following MimeTypes are enabled: ''image/x-canon-cr2;image/x-canon-crw;image/x-minolta-mrw;image/x-nikon-nef;image/x-pentax-pef;image/x-panasonic-rw2;image/x-panasonic-raw2;image/x-samsung-srw;image/x-olympus-orf;image/x-sony-arw.''
 
<syntaxhighlight lang="nix"># configuration.nix
{ pkgs, ... }:
{
 
  environment.systemPackages = with pkgs; [
    nufraw
    nufraw-thumbnailer
  ];
 
  # 'nufraw.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers'
 
}</syntaxhighlight>
 
nufraw-thumbnailer 
 
* creates thumbnails using the embedded 'jpeg' in the camera raw files. ( <code>--noexif</code> )
* does not respect the EXIF metadata. ( <code>--embedded-image</code> )
 
Output of <code>cat /run/current-system/sw/share/thumbnailers/nufraw.thumbnailer</code>:
 
<syntaxhighlight lang="nix">
[Thumbnailer Entry]
TryExec=/nix/store/piss9dl8i5xnfm5yagdffgxycm8lsqpl-nufraw-0.43-3/bin/nufraw-batch
Exec=/nix/store/piss9dl8i5xnfm5yagdffgxycm8lsqpl-nufraw-0.43-3/bin/nufraw-batch --silent --size %s --out-type=png --noexif --output=%o --embedded-image %i
MimeType=image/x-canon-cr2;image/x-canon-crw;image/x-minolta-mrw;image/x-nikon-nef;image/x-pentax-pef;image/x-panasonic-rw2;image/x-panasonic-raw2;image/x-samsung-srw;image/x-olympus-orf;image/x-sony-arw
</syntaxhighlight>
 
Additional cameras<ref>https://github.com/killhellokitty/nufraw-thumbnailer</ref> beyond those listed in the stock <code>nufraw.thumbnailer</code> file are also supported. The following additional MimeTypes are supported: ''image/x-adobe-dng; image/x-dcraw; image/x-fuji-raf; image/x-kodak-dcr; image/x-kodak-k25; image/x-kodak-kdc; image/x-nikon-nrw; image/x-panasonic-raw; image/x-sigma-x3f; image/x-sony-srf; image/x-sony-sr2''
 
Eg: Generate thumbnails from 'raw' data (not 'embedded jpeg') + respect EXIF (eg: rotation) metadata + add support for additional camera formats
 
<syntaxhighlight lang="nix">
# configuration.nix
{ pkgs, ... }:
 
{
 
  environment.systemPackages = [
    nufraw
    nufraw-thumbnailer
    # Thumbnails form 'raw' data and include EXIF tags for Adobe-DNG images
    (writeTextDir "share/thumbnailers/my-custom-nufraw.thumbnailer" ''
      [Thumbnailer Entry]
      TryExec=nufraw-batch
      Exec=nufraw-batch --silent --size %s --out-type=png --output=%o %i
      MimeType=image/x-adobe-dng;image/x-dng;
    '';)
    # MimeTypes not listed here but listed in the default nufraw.thumbnailer will continue displaying
      # thumbnails generated form the 'embedded jpeg' without the EXIF metadata
  ];
 
}
</syntaxhighlight>
 
==== gdk-pixbuf thumbnailer ====
The gdk-pixbuf thumbnailer can also generate thumbnails (from 'embedded jpeg') for RAW camera image formats. It cannot decode 'raw' image data but can read the 'embedded jpeg'.
 
<syntaxhighlight lang="nix">
# configuration.nix
{ pkgs, ... }:
 
{
 
  environment.systemPackages = [
    gdk-pixbuf
    (writeTextDir "share/thumbnailers/my-custom-nufraw.thumbnailer" ''
      [Thumbnailer Entry]
      TryExec=gdk-pixbuf-thumbnailer
      Exec=gdk-pixbuf-thumbnailer -s %s %u %o
      MimeType=image/x-adobe-dng;image/x-dng;image/x-canon-cr2;image/x-canon-crw;image/x-cr2;image/x-crw;
    '';)
  ];
 
}
</syntaxhighlight>
 
== '''Creating Custom Thumbnailers''' ==
Most package mangers accept the [https://specifications.freedesktop.org/thumbnail-spec/latest/index.html Thumbnail Managing Standard], by using it you can create your own thumbnailer for any file format, this can be done by:
Most package mangers accept the [https://specifications.freedesktop.org/thumbnail-spec/latest/index.html Thumbnail Managing Standard], by using it you can create your own thumbnailer for any file format, this can be done by:


Line 28: Line 191:
After you have a working definition, you can make it reproducible like so:
After you have a working definition, you can make it reproducible like so:


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix"># configuration.nix
# configuration.nix
{ pkgs, ... }: {
{ pkgs, ... }: {
   environment.systemPackages = [
   environment.systemPackages = [
Line 47: Line 209:
     )
     )
   ];
   ];
}
</syntaxhighlight>
=== FFmpeg thumbnailer ===
On minimal GNOME environments (for example ones with the option <code>services.gnome.core-utilities.enable</code> set to <code>false</code>, or ones without <code>pkgs.gnome.totem</code>), video thumbnails do not work by default. To fix this, you can use <code>ffmpegthumbnailer</code>:
<syntaxhighlight lang="nix"># configuration.nix
{ pkgs, ... }:
{
  # Install ffmpegthumbnailer package
  environment.systemPackages = [
    pkgs.ffmpegthumbnailer
  ];
  # Installing above package automatically creates the ffmpegthumbnailer.thumbnailer
    # in '/run/current-system/sw/share/thumbnailers' but thumbnails are not displayed
    # until symlinks to 'share/thumbnailers' are defined
  environment.pathsToLink = [
    "share/thumbnailers"
  ];
}</syntaxhighlight>
}</syntaxhighlight>
=== HEIF thumbnailer ===
On minimal GNOME environments (as explained in the <code>FFmpeg thumbnailer</code> section above) HEIF thumbnails do not work despite the <code>libheif</code> package being installed. To fix this, you need  <code>libheif.out</code> as well. HEIF thumbnails should now work correctly if the symlinks to 'share/thumbnailers' are defined:
<syntaxhighlight lang="nix">
# configuration.nix
{ pkgs, ... }:
{
  environment.systemPackages = with pkgs; [
    libheif
    libheif.out
  ];
  # 'heif.thumbnailer' is automatically generated in '/run/current-system/sw/share/thumbnailers'
  environment.pathsToLink = [
  "share/thumbnailers"
  ];
}
</syntaxhighlight>

Latest revision as of 07:19, 11 August 2025

☶︎
This article or section needs to be expanded. Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.

Enabling Thumbnailers

On minimal / custom desktop environments thumbnails in file explorers may not work by default. For example:

  • GNOME environments with the option services.gnome.core-utilities.enable = false;
  • Custom environments built from ground-up using window managers like sway or hyperland

Save yourself hours of troubleshooting!!

Thumbnailers may already be installed in your system as dependencies of image/video applications but are not activated.

Run cd /run/current-system/sw/share/thumbnailers && ls to list installed thumbnailers. If relevant .thumbnailer files are present and we still don't have thumbnails in our file explorer then we may need to activate them by updating symlinks to share/thumbnailers

# configuration.nix
{

  environment.pathsToLink = [
    "share/thumbnailers"
  ];

}

Enable Video Thumbnails

To enable thumbnails for video files use ffmpeg-headless to decode videos and fmpegthumbnailer to generate thumbnails.

Thumbnails for the following MimeTypes are enabled: video/jpeg; video/mp4; video/mpeg; video/quicktime; video/x-ms-asf; video/x-ms-wm; video/x-ms-wmv; video/x-ms-asx; video/x-ms-wmx; video/x-ms-wvx; video/x-msvideo; video/x-flv; video/x-matroska; application/x-matroska; application/mxf; video/3gp; video/3gpp; video/dv; video/divx; video/fli; video/flv; video/mp2t; video/mp4v-es; video/msvideo; video/ogg; video/vivo; video/vnd.avi; video/vnd.divx; video/vnd.mpegurl; video/vnd.rn-realvideo; application/vnd.rn-realmedia; video/vnd.vivo; video/webm; video/x-anim; video/x-avi; video/x-flc; video/x-fli; video/x-flic; video/x-m4v; video/x-mpeg; video/x-mpeg2; video/x-nsv; video/x-ogm+ogg; video/x-theora+ogg.

# configuration.nix
{ pkgs, ... }: 
{

  environment.systemPackages = with pkgs; [
    ffmpeg-headless
    ffmpegthumbnailer
  ];

  # 'ffmpegthumbnailer.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers'

}

Enable Image Thumbnails

To enable thumbnails for image files use gdk-pixbuf to decode images and generate thumbnails.

Thumbnails for the following MimeTypes are enabled: image/png; image/jpeg; image/bmp; image/x-bmp; image/x-MS-bmp; image/gif; image/x-icon; image/x-ico; image/x-win-bitmap; image/vnd.microsoft.icon; application/ico; image/ico; image/icon; text/ico; image/x-portable-anymap; image/x-portable-bitmap; image/x-portable-graymap; image/x-portable-pixmap; image/tiff; image/x-xpixmap; image/x-xbitmap; image/x-tga; image/x-icns; image/x-quicktime; image/qtif.

# configuration.nix
{ pkgs, ... }: 
{

  environment.systemPackages = with pkgs; [ 
    gdk-pixbuf
  ];

  # 'gdk-pixbuf-thumbnailer.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers'

}

Enable HEIF Image Thumbnails

To enable thumbnails for HEIF image format use libheif to decode HEIF images and libheif.out to generate thumbnails.

Thumbnails for the following MimeTypes are enabled: image/heif; image/avif.

# configuration.nix
{ pkgs, ... }: 
{

  environment.systemPackages = with pkgs; [ 
    libheif
    libheif.out
  ];

  # 'heif.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers'

}

Enable RAW (Camera) Image Thumbnails

nufraw-thumbnailer

To enable thumbnails for camera RAW format use nufraw to decode RAW images and nufraw-thumbnailer to generate thumbnails.

Thumbnails for the following MimeTypes are enabled: image/x-canon-cr2;image/x-canon-crw;image/x-minolta-mrw;image/x-nikon-nef;image/x-pentax-pef;image/x-panasonic-rw2;image/x-panasonic-raw2;image/x-samsung-srw;image/x-olympus-orf;image/x-sony-arw.

# configuration.nix
{ pkgs, ... }: 
{

  environment.systemPackages = with pkgs; [ 
    nufraw
    nufraw-thumbnailer
  ];

  # 'nufraw.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers' 

}

nufraw-thumbnailer

  • creates thumbnails using the embedded 'jpeg' in the camera raw files. ( --noexif )
  • does not respect the EXIF metadata. ( --embedded-image )

Output of cat /run/current-system/sw/share/thumbnailers/nufraw.thumbnailer:

[Thumbnailer Entry]
TryExec=/nix/store/piss9dl8i5xnfm5yagdffgxycm8lsqpl-nufraw-0.43-3/bin/nufraw-batch
Exec=/nix/store/piss9dl8i5xnfm5yagdffgxycm8lsqpl-nufraw-0.43-3/bin/nufraw-batch --silent --size %s --out-type=png --noexif --output=%o --embedded-image %i
MimeType=image/x-canon-cr2;image/x-canon-crw;image/x-minolta-mrw;image/x-nikon-nef;image/x-pentax-pef;image/x-panasonic-rw2;image/x-panasonic-raw2;image/x-samsung-srw;image/x-olympus-orf;image/x-sony-arw

Additional cameras[1] beyond those listed in the stock nufraw.thumbnailer file are also supported. The following additional MimeTypes are supported: image/x-adobe-dng; image/x-dcraw; image/x-fuji-raf; image/x-kodak-dcr; image/x-kodak-k25; image/x-kodak-kdc; image/x-nikon-nrw; image/x-panasonic-raw; image/x-sigma-x3f; image/x-sony-srf; image/x-sony-sr2

Eg: Generate thumbnails from 'raw' data (not 'embedded jpeg') + respect EXIF (eg: rotation) metadata + add support for additional camera formats

# configuration.nix
{ pkgs, ... }:

{

  environment.systemPackages = [
    nufraw
    nufraw-thumbnailer
    # Thumbnails form 'raw' data and include EXIF tags for Adobe-DNG images
    (writeTextDir "share/thumbnailers/my-custom-nufraw.thumbnailer" ''
      [Thumbnailer Entry]
      TryExec=nufraw-batch
      Exec=nufraw-batch --silent --size %s --out-type=png --output=%o %i
      MimeType=image/x-adobe-dng;image/x-dng;
    '';)
    # MimeTypes not listed here but listed in the default nufraw.thumbnailer will continue displaying
      # thumbnails generated form the 'embedded jpeg' without the EXIF metadata
  ];

}

gdk-pixbuf thumbnailer

The gdk-pixbuf thumbnailer can also generate thumbnails (from 'embedded jpeg') for RAW camera image formats. It cannot decode 'raw' image data but can read the 'embedded jpeg'.

# configuration.nix
{ pkgs, ... }:

{

  environment.systemPackages = [
    gdk-pixbuf
    (writeTextDir "share/thumbnailers/my-custom-nufraw.thumbnailer" ''
      [Thumbnailer Entry]
      TryExec=gdk-pixbuf-thumbnailer
      Exec=gdk-pixbuf-thumbnailer -s %s %u %o
      MimeType=image/x-adobe-dng;image/x-dng;image/x-canon-cr2;image/x-canon-crw;image/x-cr2;image/x-crw;
    '';)
  ];

}

Creating Custom Thumbnailers

Most package mangers accept the Thumbnail Managing Standard, by using it you can create your own thumbnailer for any file format, this can be done by:

  1. First you need to figure out how to create a .png image from a file in the desired format.
  2. Create a .thumbnailer file in $XDG_DATA_DIRS/thumbnailers.
  3. Restart your thumbnailer service (This is specific to each file manager) and test if it's working.

Example

You could create a thumbnailer for Krita's .kra file format like so:

.kra are zip files, with a preview stored at /preview.png, we can use unzip to extract the preview:

unzip -p robot-squirrel.kra preview.png > robot-squirrel.png

Create a .thumbnailer file in any $XDG_DATA_DIRS/thumbnailers directory.

# $HOME/.local/share/thumbnailers/kra.thumbnailer
[Thumbnailer Entry]
Exec=sh -c "unzip -p %i preview.png > %o"
MimeType=application/x-krita;

Restart your thumbnailer service (This is specific to each file manager) and test if it's working.

After you have a working definition, you can make it reproducible like so:

# configuration.nix
{ pkgs, ... }: {
  environment.systemPackages = [
    (
      pkgs.writeTextFile {
        # This can be anything, it's just the name of the derivation in the nix store
        name = "krita-thumbnailer";
        # This is the important part, the path under which this will be installed
        destination = "/share/thumbnailers/kra.thumbnailer";
        # The contents of your thumbnailer, don't forget to specify the full path to executables
        text = ''
          [Thumbnailer Entry]
          Exec=sh -c "${pkgs.unzip}/bin/unzip -p %i preview.png > %o"
          MimeType=application/x-krita;
        '';
      }
    )
  ];
}