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.
1 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.
2 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:
- Kodi generates a hash (CRC) of the URL, like "6a643bff".
- The texture is optimized (see #Texture optimization) and cached to a device-local file with the given URL hash. It is cached as a PNG if transparency is required and JPG otherwise.
- 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.
- These details are stored in the SQL database Textures.db, along with information on when the image was cached.
3 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:
- If the image is provided by the skin, skip to step 5.
- If the URL is directly to a cached version of a texture in the cache, skip to step 5.
- 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.
- Cache the image as outlined in the section above.
- Load the image. If the image is provided by the skin, skip steps 6 and 7.
- The access time for this texture is saved in the texture database.
- 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.
4 Texture optimization
- 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)
- 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.
5 Cache manipulation tools
- Texture Cache Maintenance utility
- Texture Cache Maintenance utility is a python script created by MillhouseVH, that can do a number of artwork related maintenance on the Kodi library. The script can be used to pre-generate thumbnails, clean up old thumbnail files, find corrupted files, and much more. The script can work on any OS that can run Python 2.6 or higher.
6 Advanced: How to refresh the cached image of an icon manually
The Texture Cache Maintenance utility can do this in a safer way, but this is the manual option. 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.
See also: Database Versions
7 Advanced: delete textures13.db
This last resort procedure is one sure way to repair any image caching problem: delete the Textures13.db database and the thumbnail directory. This procedure does not affect the entries in the Video and Music libraries, so Kodi will not find more images after, this is just a brute-force solution to a caching problem. It affects the artwork database only. Texture Cache Maintenance utility can do very targeted fixes of the texture cache, so consider it before doing this.
- Be aware that this should be a last resort procedure. Deleting this database file and the thumbnail directory will remove all cache entries and links, requiring remote URLs to web services to be downloaded again.
- As the URL link to the original artwork location is stored in the video or music databases, Kodi will use the existing URLs to rebuild the Texture database and thumbnail cache, rather than finding new images locally or from a scraper.
- Using this procedure, you cannot change the scraping location for artwork. ie- If you originally scraped from online sources, you cannot expect that Kodi will now scrape from your newly added local artwork and vice-versa. It will retrieve artwork from the same source as it was before, so the result will be the same image. To bulk change artwork, refer to Importing-Scraping Artwork
You will need to perform the following for a clean start with respect to the artwork texture cache.
- Exit Kodi
- Delete texturesxx.db located in the \userdata\database\ folder.
- Delete the Thumbnails directory located at \userdata\ which stores all the cached images,
Once the above steps are performed
- Restart Kodi
- Kodi will automatically rebuild the Textures database and repopulate the Thumbnails cache as the images are displayed in the GUI or other Kodi interface.
8 Kodi version updates
Note: The maximum resolution currently available for cached artwork is 1920x1080, regardless of any advancedsettings.xml entries. The only known workaround requires you to manually locate the existing cached artwork, delete it and replace it with the higher resolution image, ensuring the new image is named exactly as the former image was.
Note: In v18, the 1920x1080 limitation has been removed. Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size. See: https://github.com/xbmc/xbmc/pull/13599