Artwork/Cache

Development Artwork

Cache

See also: Artwork

Kodi maintains a texture cache on local device storage for all artwork displayed in the GUI, whether from an online source or the local file system. These textures are optimized and stored locally for faster loading.

When artwork is added to the library, Kodi initially only has a URL or path to the artwork. The artwork itself is only downloaded (if from an online source) and then cached when the image is displayed in the GUI or other interface such as the Chorus web interface.

All images that Kodi loads, with the exception of textures that are provided directly by the skin, are cached to the userdata/Thumbnails folder.

Artwork for library items

The artwork URLs associated with library items are stored in the art table inside the video or music databases. These store the original URL to the artwork (e.g. from local artwork files or from web sources such as https://themoviedb.org, https://thetvdb.com, or https://theaudiodb.com). This means that central databases store where the art is obtained from, and multiple devices then just keep a local thumbnail cache as described below.

The caching procedure

The caching procedure utilizes an optimized copy of the original image saved in .jpg or .png format and an SQL database that maintains the local cache.

The cache operates primarily on an "as and when needed" basis; i.e. textures are cached when they're first requested for display in a skin or web interface. In some cases textures may be cached before they're immediately needed, such as thumbnails generated from video files. In either case, the main caching procedure starts with an image URL. It caches as follows:

1. Kodi generates a hash (CRC) of the URL, like "6a643bff".
2. The texture is optimized (see section 4) and cached to a device-local file with the given URL hash. It is cached as a PNG or JPG based on whether transparency is required.
3. Another hash of the image is generated based on size and modified date, which can be used to check if the original image has changed.
4. These details are stored in the SQL database Textures.db, along with information on when the image was cached.

Loading textures

When loading a texture for display in a skin or web interface, Kodi basically just has a URL to the image. Given a particular URL, it loads the texture as follows:

1. If the image is provided by the skin, skip to step 5.
2. If the URL is directly to a cached version of a texture in the cache, skip to step 5.
3. If the URL is for an image already cached in the thumbnail cache, swap the URL to the cached version and skip to step 5.
4. Cache the image as outlined in the section above.
5. Load the image. If the image is provided by the skin, skip steps 6 and 7.
6. The access time for this texture is saved in the texture database.
7. If the image is not from a web service (HTTP/S) and at least 24 hours have passed since it was last loaded, check the hash generated in step 3 of "The caching procedure" for changes to the image. If the hash has changed, cache the new image as outlined in the section above.

Texture optimization

1. Images are limited to a maximum pixel dimension to fit in a 16:9 box, with a default configuration of 1920x1080 for images that are 16:9 (like fanart) and larger than this, and 1280x720 for all other images. This can be changed with advancedsettings.xml.
   • If you are experiencing slow loading images or lagging GUI navigation on low powered equipment and/or your Kodi device has minimal storage available, these defaults can be lowered to noticeably reduce the cost of artwork. For higher powered equipment these settings can be increased to maintain the original artwork size. (eg 3840x2160 fanart)
2. Images are re-encoded in a decoder-friendly way so that the image can be displayed as quickly as possible.

This optimized image is exported with Kodi's Library Export feature, rather than the original full-quality image, so it is best to avoid exporting artwork if at all possible. An easily understandable explanation of the effects of these optimizations can be located in the forum here.

Cache manipulation tools

• Texture Cache Maintenance utility

Advanced: How to refresh the cached image of an icon manually

There is an image like /home/x/.xbmc/addons/my.lovely.addon/icon.png . After changing that file, the old image is still visible in XBMC. To solve this we need to remove the actual thumbnail file from the filesystem and its reference in the DB:

# Get the thumbnail path to remove the file from the filesystem
$ sqlite3 .xbmc/userdata/Database/Textures13.db "SELECT cachedurl FROM texture WHERE url = '/home/x/.xbmc/addons/my.lovely.addon/icon.png';"
6/6a643bff.png

This 6/6a643bff.png is the cached image under /home/x/.xbmc/userdata/Thumbnails. So: you need to remove from your filesystem /home/x/.xbmc/userdata/Thumbnails/6/6a43bff.png"

# Remove the image->cached image link in the DB
$ sqlite3 .xbmc/userdata/Database/Textures13.db "DELETE FROM texture WHERE url = '/home/x/.xbmc/addons/my.lovely.addon/icon.png';"

Next time Kodi needs the image, it will recreate the thumbnail.

Note: The "Textures13.db" number/version Increases with newer Kodi versions.

See also: Database Versions