Artwork/Accessing with skins and JSON-RPC

From Official Kodi Wiki
Jump to: navigation, search
Home icon grey.png   ▶ Development ▶ Artwork ▶ Accessing with skins and JSON-RPC

The primary usage of artwork is to be displayed, and to that end, they can be accessed by name in skins and over JSON-RPC.

Media items with a "parent" media type, such as episodes to their TV show, can also access their parent's artwork with certain prefixes, like "tvshow.poster".

1 From skins

Skins can access library artwork for media items in a list with "ListItem.Art(<arttype>)" and artwork for the currently playing item with "Player.Art(<arttype>)". "Container.Art(<arttype>)" can also be filled in some instances. Some examples are ​Player.Art(poster)​, ​Player.Art(fanart)​, ​ListItem.Art(banner)​, and ​ListItem.Art(tvshow.clearlogo)​.

Additional InfoLabels
Skin InfoLabel Description
ListItem.Art(poster) Artwork for the currently focused ListItem.
Player.Art(poster) Artwork for the currently playing item.
Container.Art(poster) Artwork for the currently focused Container. Container artwork may be filled with "parent" type media item artwork if navigating a single item, like a list of episodes from a single TV show.
Container(555).ListItem.Art(poster) Artwork for the currently focused ListItem in a specific container.

1.1 Additional InfoLabels for artwork

There are other InfoLabels for artwork that don't match the above pattern, but many of them are deprecated. A set of them that can still be useful are

Additional InfoLabels
Skin InfoLabel Description Examples
MusicPlayer.offset(number).Cover Cover of the item offset by number from the currently playing item in the currently playing music player queue. ​MusicPlayer.offset(1).Cover​ - next item in queue

​MusicPlayer.offset(-1).Cover​ - previous item in queue

MusicPlayer.Position(number).Cover Cover of the item in position number of currently playing music player queue. ​MusicPlayer.Position(1).Cover​ - first item in queue

​MusicPlayer.Position(2).Cover​ - second item in queue

MusicPlayer.Position(number).Property(Fanart_Image) Fanart of the item in position number of the currently playing music player queue. ​MusicPlayer.Position(1).Property(Fanart_Image)​ - first item in queue

​MusicPlayer.Position(2).Property(Fanart_Image)​ - second item in queue

2 From JSON-RPC

Several JSON-RPC methods (like "VideoLibrary.GetMovies", "AudioLibrary.GetAlbumDetails", and "Playlist.GetItems") return info for media items in the library, and requesting the "art" property will return an "art" dictionary that maps all available artwork for the media item. The key is the artwork type and the value is a Kodi-encoded URL or path to the assigned artwork.

2.1 Example

example request:

{"jsonrpc":"2.0","id":11,"method":"VideoLibrary.GetEpisodes","params":{"properties":["art"],"limits":{"end":1},"sort":{"method":"random"}}}

and a possible response:

{
    "id": 11,
    "jsonrpc": "2.0",
    "result": {
        "episodes": [
           {
                "art": {
                    "season.banner": "image://nfs%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2fseason02-banner.jpg/",
                    "season.landscape": "image://nfs%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2fseason02-landscape.jpg/",
                    "season.poster": "image://nfs%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2fseason02-poster.jpg/",
                    "thumb": "image://[email protected]%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2fV%20(2009)%20-%2002x05%20-%20Concordia%20-%20720p%20WEB-DL.mkv/",
                    "tvshow.banner": "image://nfs%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2fbanner.jpg/",
                    "tvshow.clearlogo": "image://nfs%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2fclearlogo.png/",
                    "tvshow.fanart": "image://nfs%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2ffanart.jpg/",
                    "tvshow.poster": "image://nfs%3a%2f%2fCUBER%2fmedia%2fpreserved%2fTVShows%2fV%20(2009)%2fposter.jpg/"
                },
                "episodeid": 2196,
                "label": "2x05. Concordia"
            }
        ],
        "limits": {
            "end": 1,
            "start": 0,
            "total": 3352
        }
    }
}

2.2 Kodi-encoded URL

The image paths returned by JSON-RPC are the path or URL to the image encoded as Kodi's internal "image://" path.

To turn that path into a URL that can actually be displayed in another application, you will need to encode it as a URI component (examples are encodeURIComponent in JS and urllib.parse.quote in Python 3), then add that to the end of the "images/" path of the Kodi HTTP server (like http://kodihost:8080/images/). With these URLs you can display images wherever they happen to be stored; Kodi will handle opening a file over SMB or NFS if they are stored on a NAS next to the media items, for instance.

The final URL will look like 

http://kodihost:8080/images/image%3A%2F%2Fnfs%253a%252f%252fCUBER%252fmedia%252fpreserved%252fTVShows%252fV%2520(2009)%252fposter.jpg%2F

You can also turn the "image://" URL into a more traditional looking path/URL (https:// or smb:// or H:\) by chopping off the "image://" up front and the slash at the end, then decoding the rest as a URI component.

3 Access "parent" artwork

For several media types, it is possible to access artwork for the "parent" media item as well as the item's own artwork. This works for skins and JSON-RPC. For instance, TV episodes can access the artwork for the containing season and TV show. Use "<parenttype>.<arttype>" as the art type.

Media types and their parent types
Media type Parent type Description Skin examples
TV episodes "season", "tvshow" TV episodes can access artwork for their containing season and TV show "Player.Art(tvshow.clearlogo)", "Player.Art(season.poster)"
Seasons "tvshow" TV show artwork "ListItem.Art(tvshow.banner)", "ListItem.Art(tvshow.clearlogo)"
Movies "set" In Kodi 18, movies can access artwork for their containing set / collection "ListItem.Art(set.clearlogo)", "ListItem.Art(set.poster)"
Songs "album", "artist", "albumartist", "artist1", "albumartist1" Songs can access the artwork for their containing album and all artists. Songs can have multiple artists; in Kodi 18 "artist1" will be artwork for the second artist - "artist2", "artist3", and so on will be filled for additional artists. "albumartist" works the same for album artists. "Player.Art(album.thumb)", "Player.Art(artist.fanart)", "Player.Art(albumartist.clearlogo)", "Player.Art(artist1.fanart)"
Albums "artist", "artist1" Albums can access the artwork for their containing album. Albums can have multiple artists; in Kodi 18 "artist1" will be artwork for the second artist - "artist2", "artist3", and so on will be filled for additional artists. "ListItem.Art(artist.fanart)", "ListItem.Art(artist.clearlogo)"

3.1 Example artwork types

Here is a short list of example artwork types and how to access them. Kodi's artwork system allows any number of artwork types, so it's impossible to list all that may be available here. See the artwork pages for different library sections like Movie artwork or Music artwork for a list of generally available artwork types, or navigate to image 2 of Artwork#Kodi- Choose Art on a media item in your local Kodi installation to see what types of artwork are currently available for at least one of that media type in your local library.

Example artwork types and skin access
Artwork type Skin InfoLabel Description
poster ListItem.Art(poster) Poster of the currently focused media item (like a movie or TV show)
fanart ListItem.Art(fanart) Fanart of the currently focused media item
landscape ListItem.Art(landscape) Landscape of the currently focused media item
clearlogo Player.Art(clearlogo) Clearlogo of the currently playing media item
tvshow.poster Player.Art(tvshow.poster) For a currently playing TV episode, this is the poster of the parent TV show
set.poster Player.Art(set.clearlogo) For currently playing movies, this is the clearlogo of the containing movie set
album.thumb Player.Art(album.thumb) For currently playing music, this is the cover of the album
album.thumb ListItem.Art(thumb) Thumb of the currently focused media item. This has some notable fallback behavior in the video library. It will be the artwork type named exactly "thumb" if it exists for the current item, but will fall back to "poster" then "banner" if not.

4 Kodi version updates

  • The music library in Kodi 17 and before was limited to just "fanart" and "thumb" for artist images and "thumb" for album images, it did not have the flexibility to add a wide variety of artwork. The video library has had this level of support for some time now.
  • Kodi 18 adds a whitelist in advancedsettings.xml (for the video library) so that Kodi will add any specified artwork from scrapers and the file system automatically.
Return to top