Add-on:Artist Slideshow

Features

 * displays slideshow as background for music visualization (must use a compatible skin or update skin using the instructions below)
 * option to have artist images downloaded and/or use a local directory of artist images
 * option for a fallback slideshow if no local or remote images are found
 * option to have a single slideshow displayed regardless of artist playing
 * options to download artwork from fanart.tv, theaudiodb.com, and htbackdrops.org to display as background for music visualization
 * option to download artist bio and other additional information from theaudiodb.com with fallback to last.fm (skin must support display of this information)
 * support for overriding the artist bio, discography, and similar artists list with local information
 * option to limit size of download cache
 * option to display notification during download of first image for an artist with option to provide a local image (or images) to use instead of default XBMC notification
 * option to display notification when downloads are complete (or no images found for download)
 * ability to exclude images from being downloaded (see Tips and Tricks below)
 * support for multiple artists for a single song (as passed by XBMC)
 * also supports iTunes/Amazon standard of song name (feat. artist 2) in title MP3 tag
 * support for internet streams that put the artist name in the XBMC title field
 * support for other addons using Artist Slideshow to provide the background
 * support for an alternate name for the folder containing the images (i.e. something instead of extrafanart)

Find a Compatible Skin
There are a number of skins that support Artist Slideshow, but keeping a running list of them has proved too much work. I'd suggest visiting the Kodi forums and see if the skin you want to use supports Artist Slideshow. I do have a modified version of the default Confluence theme for Kodi that includes support for Artist Slideshow. To use that skin you will need to download and install my skin repo (Gotham or Helix) and then install the skin from there.

Using Artist Slideshow with the default Confluence Skin
Change Default Skin Files

This is probably the easiest way, but anytime you upgrade or reinstall XBMC you will have to redo these modifications. Go to the Kodi installation root folder (see this wiki page under special://xbmc for the path for your operating system). Then go to addons --> skin.confluence. Quit Kodi, modify the appropriate files, and then start up Kodi again.

Create Custom Skin

This is a bit more complicated but will keep your modifications intact across upgrades. Go to the directory above, enter the addon directory and find the skin.confluence folder. Make a copy of it and move it to your user addon directory. Rename the directory to skin.confluence.mod. In that directory open the file called addon.xml. Change the third line to read id="skin.confluence.mod" and then launch (or relaunch Kodi). Go to SYSTEM --> APPEARANCE --> SKIN and switch to the modified skin. When you do that you will lose all your current skin settings, so you might want to write them down before changing. Quit Kodi again, modify the appropriate files, and then start up Kodi again.

Changes to MusicVisualisation.xml
To run the script: RunScript(script.artistslideshow)

On AppleTV if ArtistSlideshow isn't updating after the first artist, use this instead: RunScript(script.artistslideshow, daemon=True)

To add a multiimage conrol: 0     0      1280      720      $INFO[Window(Visualisation).Property(ArtistSlideshow)] keep 10000     2000      true

Addon settings
There are three groupings of settings: Download, Slideshow, and Advanced.

Download
Download images from fanart.tv: (default true)

fanart.tv has very high quality (1080p) artwork.

Download images from theaudiodb.com: (default false)

theaudiodb.com has no more than three images per artist, and they are often duplicates of artwork from fanart.tv.

Download images from htbackdrops.com: (default false)

Site changed to htbackdrops.org, but the setting description hasn't been changed.

Download additional artist info: (default false)

Includes information like the artist's bio and artists similar to the one to which you are listening. Artist bio and album list come from theaudiodb.com by default and from last.fm if nothing is found on theaudiodb.com. Similar artist information comes from last.fm. Includes option to select download language. Skin must support this extra information, or nothing will be displayed.

Slideshow
Local artist folder: (default none)

path to a directory that has artist images. Images must be organized in artist/extrafanart/ unless you set a different local fanart folder name in the advanced settings.

Fallback slideshow folder: (default none)

path to a directory of images that should be used if no local or remote images can be found.

Priority: (default remote first)

three options: remote first, local first, both

remote first will try and download images from remote sites. if none found will use local images. if none found will use fallback slideshow

local first will use local images. if none found will try and download remote images. if none found will use fallback slideshow

both will check for local images first. if they exist the downloaded images will be placed in the same directory as the local images. if not remote images will be stored in normal cache dir.

Override slideshow folder: (default none)

path to a directory of images that should be used intead of artist artwork. With this set no artwork will ever be downloaded.

Use transparent background when no artist found: (default false)

When set to true, Artist Slideshow will use a transparent background (instead of a black one), allowing the layer below to be seen. Please note that exactly what you see will be very dependent on the skin you are using and the settings you have for that skin.

Advanced
Limit size of download cache: (default false)

if enabled, the download cache will be trimmed (oldest first) to keep the size below the specified minimum. Please note that if you set the image download priority to both on the Slideshow settings, this setting has no effect, as the cache manger is disabled to protect your local artwork from being deleted.

Maximum cache size (in megabytes): (default 1024)

if Limit size of download cache is set to true, this allows the user to specify the maximum size of the cache

Download notification type: (default none)

three options: none, text notifications, custom images

none will surpress all notifications

text notifications will use the built in XBMC notification pop-up to let you know about images being downloaded for the first time and the completion status (either nothing downloaded or download complete)

custom images let's you show an image or directory of images when artwork for an artist is being downloaded for the first time. This won't display if there are local images available to display. If you select this option you must provide the path to the directory that has the custom image or images in it (stored in progress images folder)

Progress images folder: (default empty)

Must be set to a valid local path with one or more images to be displayed while first image for an artist is being downloaded

Alternate name for local fanart folder: (default empty)

This is a text field where you can provide an alternate name for the add-on to use to find local images. If this has text in it, the add-on will look in artist/customfolder instead of artist/extrafanart for local images.

Enable debug logging: (default false)

When enabled, if you have XBMC logging set the DEBUG you will get a very verbose set of information in your log file. You should only need to activate this when troubleshooting issues.

Directory Structure
To override the downloaded information, you need to create another directory in the folder you defined in the settings as the Local artist folder. Your folder structure will look something like this: extrafanart override albums (folder with artist album art) albumname.jpg (any XBMC image type supported) anotheralbumname.jpg artistbio.nfo (see below for format) artistsalbum.nfo (see below for format) artistsimilar.nfo (see below for format) similar artistimage.jpg anotherartistimage.jpg

Override nfo file formats
All .nfo files are xml files (pretty simple ones) patterned after the XML files downloaded from last.fm.

Example artistbio.nfo  This is the artist's bio.

Example artistsalbum.nfo  Some Album albumname.jpg Another Album anotheralbumname.jpg

Example artistsimilar.nfo  Some Similar Artist artistimage.jpg Another Similar Artist anotherartistimage.jpg

Accessing Script from Other Screens
You might want to use Artist Slideshow to display images somewhere other than on the music visualization. To do that you need to start Artist Slideshow when XBMC starts using DAEMON mode. To do that use: RunScript(script.artistslideshow, daemon=True)

New skin properties
Window(Visualisation).Property(ArtistSlideshow) This is the path to the directory containing the downloaded images for the currently playing artist

Window(Visualisation).Property(ArtistSlideshowRunning) This one is used internally by the script to check if it is already running. There's no need to use this property in your skin.

Window(Visualisation).Property(ArtistSlideshow.ArtistBiography) Artist biography from theaudiodb.com (or last.fm as fallback)

Window(Visualisation).Property(ArtistSlideshow.%d.SimilarName) Window(Visualisation).Property(ArtistSlideshow.%d.SimilarThumb) Similar artists (from last.fm)

Window(Visualisation).Property(ArtistSlideshow.%d.AlbumName) Window(Visualisation).Property(ArtistSlideshow.%d.AlbumThumb) Albums by the artist (from theaudiodb.com)

Window(Visualisation).Property(ArtistSlideshowTransparent) Let's the skin know that the user has enabled the option to have AS use a transparent background when no artist images are found.

How to call this addon from another addon
To use this addon to provide the background for another addon, the calling addon must create a window that uses a multimage control: 0     0      1280      720      $INFO[Window.Property(ArtistSlideshow)] keep 10000     2000      true Visible Hidden

That window must have an infolabel in which the currently playing artist is stored (suggested name is CURRENTARTIST) as well as one for the song title (suggested name is CURRENTTILE). It is the responsibility of the calling addon to change those infolabels when the artist/song changes.

Calling the addon
Artist Slideshow does not exit after being called. It continues to run to check for changes in the artist infolabel. Becasue of that, the calling addon will have to create another thread for Artist Slideshow. The calling addon needs to import the python theading module for this to work.

def runArtistSlideshow(self): #startup artistslideshow xbmcgui.Window(xbmcgui.getCurrentWindowId).setProperty("ArtistSlideshow.ExternalCall", "True") #assumes addon is using suggested infolabel name of CURRENTARTIST and CURRENTTITLE artistslideshow = "RunScript(script.artistslideshow,windowid=%s&artistfield=%s&titlefield=%s&albumfield=%s&mbidfield=%s)" % (xbmcgui.getCurrentWindowId, "CURRENTARTIST", "CURRENTTITLE", "CURRENTALBUM", "CURRENTMBID") xbmc.executebuiltin(artistslideshow) self.thread = threading.Thread(target=self.runArtistSlideshow) self.thread.setDaemon(True) self.thread.start

When calling Artist Slideshow, only artistfield and titlefield (and their corresponding information stored in the skin) are required. It would be helpful to have albumfield, as it makes it easier to lookup the Musicbrainz ID. If you happen to have the MusicBrainz ID, you can pass that as well.

Note that the line wrap in artistslideshow = is there just for presentation purposes. If you copy and paste the code exactly as is you will get a python error. The suggestion is for the addon to spawn this thread right after it spawns the window.

Exiting the addon
When the calling addon is preparing to exit, it must tell Artist Slideshow to stop and wait until it has. This logic should be added *before* the addon's window is destroyed. Failure to include this step will likely cause XBMC to crash.

xbmcgui.Window(xbmcgui.getCurrentWindowId).clearProperty("ArtistSlideshow.ExternalCall") while (not xbmcgui.Window(xbmcgui.getCurrentWindowId).getProperty("ArtistSlideshow.CleanupComplete") == "True"): time.sleep(1)
 * 1) tell ArtistSlideshow to exit
 * 1) wait until ArtistSlideshow exits

Additional script/skin properties available
Window.Property(ArtistSlideshow) This is the path to the directory containing the downloaded images for the currently playing artist.

Window.Property(ArtistSlideshow.ArtistBiography) Artist biography from theaudiodb.com (or last.fm as fallback)

Window.Property(ArtistSlideshow.%d.SimilarName) Window.Property(ArtistSlideshow.%d.SimilarThumb) Similar artists from last.fm

Window.Property(ArtistSlideshow.%d.AlbumName) Window.Property(ArtistSlideshow.%d.AlbumThumb) Albums by the artist from theaudiodb.com

Window.Property(ArtistSlideshowRunning) This one is used internally by Artist Slideshow to check if it is already running. There's no need to use this property in the calling addon's skin.

Window.Property(ArtistSlideshowTransparent) Let's the skin know that the user has enabled the option to have AS use a transparent background when no artist images are found.

Window.Property(ArtistSlideshow.ExternalCall) An external addon needs to set this to True so that Artist Slideshow will run properly when called by an external script. This property should be cleared to tell ArtistSlideshow to stop running.

Window.Property(ArtistSlideshow.CleanupComplete) This one is used internally by Artist Slideshow to tell an external script that ArtistSlideshow is done running and is exiting.

Excluding Images from Download
Every artist's directory (whether your local one or the one in the cache directory) will have a file named _exclusions.nfo. To exclude an image you have downloaded from displaying or being downloaded again, just add the image name to the _exclusions.nfo file for that artist (one image name per line). Artist Slideshow will then delete that image and not download it again. This can be helpful if you have lots of duplicate images from the various sources, aren't happy with the quality of an image, or don't really like the content of an image.

Using Artist Slideshow with a Visualization
If you want to see artist images and a visualization, make sure the skin is loading the Artist Slideshow images first (i.e at the top of the XML file). That will ensure the artist image is the furtherest back layer. If you choose to use a visualization, please select one with a significant amount of transparent area or you may not see much of anything. For any other skin, please contact the skin developer for a clarification on how visualizations interact with Artist Slideshow.

Using Artist Slideshow with AppleTV
On AppleTV the PAPlayer sometimes stops after each song and restarts at the beginning of a new one. That, by default, causes Artist Slideshow to stop. Once that happens, artist background images no longer update. Please see Changes to MusicVisualisation.xml above for a workaround.

Getting help
If you need assistance using Artist Slideshow, integrating it a skin, or calling it using another addon, please see the support thread on the XBMC forums.
 * http://forum.kodi.tv/showthread.php?t=124880

Beta Testing
If you are interested in beta testing new versions of this add on (or just like being on the bleeding edge of up to date), you can install beta versions from pkscout's Add On Beta Channel. You can also monitor the support thread, as links to particular beta releases will be available there as well.