Artwork/Accessing with skins and JSON-RPC: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
(Hope you don't mind the little tweaks bossanova)
Line 5: Line 5:


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".
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".


= From skins =
= 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:
<syntaxhighlight lang="json">
{{code|Player.Art(poster)}}
{{code|Player.Art(fanart)}}
{{code|ListItem.Art(banner)}}
{{code|ListItem.Art(tvshow.clearlogo)}}
</syntaxhighlight>


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 {{code|Player.Art(poster)}}, {{code|Player.Art(fanart)}}, {{code|ListItem.Art(banner)}}, and {{code|ListItem.Art(tvshow.clearlogo)}}.


{| class="prettytable" width="100%"
{| class="prettytable" width="100%"
Line 27: Line 34:
| Artwork for the currently focused ListItem in a specific container.
| Artwork for the currently focused ListItem in a specific container.
|}
|}


== Additional InfoLabels for artwork ==
== 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
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


Line 53: Line 60:
{{code|MusicPlayer.Position(2).Property(Fanart_Image)}} - second item in queue
{{code|MusicPlayer.Position(2).Property(Fanart_Image)}} - second item in queue
|}
|}


= From JSON-RPC =
= 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.


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.


== Example ==
== Example ==
 
Example request:
example request:
<syntaxhighlight lang="json">
{"jsonrpc":"2.0","id":11,"method":"VideoLibrary.GetEpisodes","params":{"properties":["art"],"limits":{"end":1},"sort":{"method":"random"}}}
{"jsonrpc":"2.0","id":11,"method":"VideoLibrary.GetEpisodes","params":{"properties":["art"],"limits":{"end":1},"sort":{"method":"random"}}}
</syntaxhighlight>


and a possible response:
and a possible response:
{
<syntaxhighlight lang="json">
{
     "id": 11,
     "id": 11,
     "jsonrpc": "2.0",
     "jsonrpc": "2.0",
Line 90: Line 101:
         }
         }
     }
     }
}
}
</syntaxhighlight>
 


== Kodi-encoded URL ==
== 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.
The image paths returned by JSON-RPC are the path or URL to the image encoded as Kodi's internal "image://" path.


Line 103: Line 115:


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.
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.


= Access "parent" artwork =
= 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.
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.


Line 140: Line 153:
|  "ListItem.Art(artist.fanart)", "ListItem.Art(artist.clearlogo)"
|  "ListItem.Art(artist.fanart)", "ListItem.Art(artist.clearlogo)"
|}
|}


== Example artwork types ==
== Example artwork types ==
Line 183: Line 197:
|  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.
|  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.
|}
|}


= {{Kodi}} version updates =
= {{Kodi}} version updates =
Line 188: Line 204:
* 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.
* 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 '''[[Advancedsettings.xml#Music library extra artwork| whitelist in advancedsettings.xml]]''' ([[Advancedsettings.xml#Extra artwork|for the video library]]) so that {{Kodi}} will add any specified artwork from scrapers and the file system automatically.
* {{Kodi}} 18 adds a '''[[Advancedsettings.xml#Music library extra artwork| whitelist in advancedsettings.xml]]''' ([[Advancedsettings.xml#Extra artwork|for the video library]]) so that {{Kodi}} will add any specified artwork from scrapers and the file system automatically.


{{Top}}
{{Top}}

Revision as of 22:31, 3 February 2023

Artwork contents

Artwork Main Page



See also:


Return to:

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".


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:

{{code|Player.Art(poster)}}
{{code|Player.Art(fanart)}}
{{code|ListItem.Art(banner)}}
{{code|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.


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


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.


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://video@nfs%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
         }
     }
}


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 "image/" path of the Kodi HTTP server (like http://kodihost:8080/image/). 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/image/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.


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)"


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.


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