From Kodi
Jump to: navigation, search


See this add-on on the showcase

Author: robwebset

Type: Program
Version: 6.3.0
Repo: repo v16 repo v15 repo v14

License: GPL v2.0
Source: Source code
Summary: Retrieve and play your soundtrack or video themes whilst browsing your library
Home icon grey.png   ▶ Add-ons ▶ TvTunes
Attention talk.png Need help with this add-on? See here.

TvTunes is equipped with powerful features that enable the fetching, organising and playing of themes whilst browsing your Kodi library.


1 Installing

To install this add-on you must do so from the Add-on manager from within Kodi by going to:

  1. Settings
  2. Add-ons
  3. Install from repository (v15/v16) / Get add-ons (v14)
  4. Kodi add-on repository
  5. Program Add-ons
  6. TvTunes
  7. Install

2 Introduction

TvTunes has been around for several years now, and has had several versions. The current version is v6.x.x which will work on Kodi version 15 (Isengard) and later. If you are using an earlier version such as 14 (Helix) or 13 (Gotham) then version 5.0.5 of TvTunes is the latest version available for you. (Note: No development or bug fixes will be submitted to versions of TvTunes before version 6.0.0)

If you have any questions, found an issue to report or would just like to know a little more you can take part in the forum discussions at:

TvTunes Forum

3 Downloading Themes

You can use TvTunes to download themes for you using one of the following methods:

  • Using the TvTunes Context Menu when on a given TV Show or Movie
  • Using the Theme Browser
  • Using the TvTunes button on the Video Information page (If your skin supported this)

TvTunes has the ability to retrieve themes from the web for a given TV Show, Movie or Music Video. The websites currently supported are:

TvTunes will search for two specific terms (<title> and <originaltitle> of the video) and will try and automatically filter the results in order to display only the best matches. If you wish to view the un-filtered version of results, then you can make use of the "Manual Search" option within TvTunes.

Obs: As it searches, TvTunes will show a progress bar; please be patient since sometimes the results to be filtered are in the magnitude of thousands.

3.1 Understanding the Entries List

3.1.1 Prioritisation of the entries

The priorities in which the filtered results are shown on the entries list are:

  • priority 1 = * (full match: most accurate match in relation to TvTunes' pre-defined soundtrack music tags/appendixes)
  • priority 2 = ~ (album only match: only the album name (not the artist) contains one of the search terms)
  • priority 3 = + (title only match: only the track title contains one of the search terms)
  • priority 4 =    (everything else: all which was filtered out)

Obs: priority 2 is currently only applicable to Goear retrieved results.

3.1.2 Tags & Separators

Entries from each scraper are listed using their available tag identifiers (in angled brackets) and separators (in blue), in the following order (identifiers are not always available or properly tagged at the source):

  • Televisiontunes: <title name> e.g., Jaws
  • Soundcloud: <title name> [hh:mm:ss] | e.g., Jaws Theme Song [00:02:16]
  • Goear: <title name> / <artist name> [mm:ss] (###kbps) | e.g., Jaws Overture / John Williams [2:55] (320kbps)

3.1.3 International characters

People from all over the world share their themes and hence many different languages are used to tag them. If some of these tags had special characters not compatible with certain Kodi fonts, you would see blank spaces instead. If this happened to you (1st item below), all you have to do is switch to a font such as 'arial base' (2nd item below) and you will see the missing content:

  •               /                     (Nausicaä of the Valley) -           Joe Hisaishi [00:03:54]
  • 風の伝説 / 风之谷交响乐(Nausicaä of the Valley) - 久石讓 Joe Hisaishi [00:03:54]

4 Theme Browser

The "Theme Browser" enables you to look at which Movies/TV Shows/Music Videos already have themes available for. You can listen to them as it gives you the ability to download new themes. You can load the theme browser in the following ways:

  1. Via the TvTunes Settings screen "Download" -> "Browse Themes"
  2. From the Programs Menu -> TvTunes
  3. Videos -> Addons -> TvTunes

5 Video Themes

If you are using video themes and are storing them with your main videos (i.e. theme.avi) then you will need to ensure that they are not picked up when you run the scrapper to load your videos into the library. To ensure they are not picked up you can add the following to the advanced settings

        <!-- TvTunes: Section Start -->
        <excludefromscan action="append">
        <excludetvshowsfromscan action="append">
        <!-- TvTunes: Section End -->

There is also a button in the TvTunes settings that will do this for you.

6 NFO File Support

The themes for TvTunes to play can also be configured via a "tvtunes.nfo" file. This file should take the following format:


There can be any number of "file"/"directory"/"playlistfile" elements, where they represent:

  • file - The name of a theme file in the same directory, or the full path if in a different directory
  • directory - The name of a directory below the existing directory, or the full path to a remote directory
  • playlistfile - Either the full path to a playlist file, a playlist file in the same directory or the name of an Kodi playlist file. (The extension "m3u" will be added if not already specified)
  • excludeFromScreensaver - Will result in the given Movie or TvShow being excluded from the TvTunes screensaver
  • checkThemeExists - Will check each file and directory location listed to see if it exists before adding it to the playlist (This can be useful if you have a removable drive with the themes that is not always attached)

Smart Playlists: To make use of a Smart Playlist in Kodi you can supply just the name of the playlist file (No path) but including the extension ".xsp"

Inclusive behavior:The tvtunes.nfo files are non-exclusive to any other valid set up through which the audio themes will play in TVTunes, which means that a tvtunes.nfo will follow same location, search and play criteria as described for 'Theme File Names and Locations', e.g.; any spare audio themes located within the same directory of the tvtunes.nfo will be played along (and shuffled, if option selected) with the themes defined by the latter.

7 Theme File Names and Locations

If you wish to store your own theme files with each video and have TvTunes play them for you then the naming of the theme is important. There can be multiple themes with each video, but they must all start with the word "theme" and be of one of the supported types configured in the settings menu.
The search order for themes is:

  1. Themes in the same directory as the video file
  2. (If no theme found) search for themes in the parent directory

This allows for nested directories where seasons of TV Series are in separate directories, but all wish to use the same theme. It is also possible to store themes in a "Series directory" under a given TV Show, this can allow you to have different themes for each series of a given show. (Note: the TvTunes downloaded will only fetch themes at an entire TV Show level, not a per series level, so series specific themes need to be added or relocated manually)

For Movie Sets, all Movies in the set will be searched for themes, and these themes played in a random order when the Movie Set is selected in the Movie List screen.

There is also a settings option to define a directory (e.g. Themes) under the Movie or TV Show directory to look for themes, if themes are not found in this directory, then the previously defined order will be followed. (Note: Setting this value will result in downloaded themes also being saved into sub-directories)

Practical scenario of how themes are picked up by TvTunes
Regardless of how they are named and the file structure you have selected to use in TvTunes (Video folder, Themes folder or Custom path), TvTunes will play all audio files, which extensions are supported by TvTunes, as long as they include the string "theme" in their names. There is an additional feature provided only by the "Themes" folder, which allow you to even ignore the string "theme" in the names.
For example, all the following audio files will be played by TvTunes as themes for Maleficient (2014) regardless of the TvTunes' file system chosen:
  • Maleficent (2014) 1080p BRRip H264 AAC-theme.ext
  • Theme - Meleficient Suite.ext
  • The Curse Won't Reverse theme.ext
  • Arthemesia.ext (this will play too ;-))
  • Theme.ext, theme1.ext, theme2.ext, theme3.ext, etc.
And if the themes are within the Themes folder, the following will also be played:
  • Maleficient Suite.ext
  • Battle of the Moors.ext
Obs. where .ext is any valid audio file supported by TvTunes. Remember you can also just have a tvtunes.nfo file pointing to a directory which contains the whole OST of the movie. Supported audio extensions refer to the extensions configured in TvTunes settings.

8 Screensaver

TvTunes has a built in screensaver. This can be used completely independently of the theme playing ability (So if you do not want Themes playing on your installation, you can still make use of the screensaver). There are several different formats of screensaver within TvTunes:

Slider - This will slide the images into view from either the left, right, top or bottom of the screen. TvTunes-Screensaver-Slider.JPG
Crossfade - will fade one image in over the top of the next image TvTunes-Screensaver-Crossfade.JPG
TableDrop - will drop each image onto the screen at random overlaps and angles TvTunes-Screensaver-Tabledrop.JPG
StarWars - will show a stream of images similar to the Star Wars intro sequence TvTunes-Screensaver-Starwars.JPG
RandomZoomIn - will randomly zoom in to each image in turn TvTunes-Screensaver-RandomZoomIn.JPG
AppleTVLike - like the Apple TV Screensaver, will scroll a mix of images up from the bottom of the screen TvTunes-Screensaver-AppleTVLike.JPG
GridSwitch - will show several images at the same time in a grid format TvTunes-Screensaver-GridSwitch.JPG
Random - will randomly show one of the above screensaver formats

There are several options for each of the different screen saver that control the speed images move or how frequently the image changes.

9 Settings

This section details all the settings options for TvTunes

9.1 TVTunes

Enable Theme Playing (Restart Required)
Enable or disable if the themes are played while navigating (Useful if you only wish to use the Sceeensaver option). A restart of Kodi is required to pick up this change.
Play themes when browsing Movie list
When moving over items in the Movie list, play the theme if it remains selected
Play themes when browsing TV Show list
When moving over items in the TV Show list, play the theme if it remains selected
Play themes when browsing Music Video list
When moving over items in the Music Video list, play the theme if it remains selected
Play themes when viewing Video Information
Play the theme when showing the Video Information screen
Play themes when browsing TV Show Seasons
Play the theme when showing the seasons in a TV Show
Play themes when browsing TV Show Episodes
Play the theme when showing the episodes in a TV Show
Play themes when browsing Music Library
Play a track by the given artist or from the selected album while browsing (This is supported when browsing by Artist or Album)

9.2 Playback

Play theme in loop
Will continue to play all themes in a loop
Theme Volume
Sets the volume that should be used to play the theme in the background (Setting to 0 will result in no change in volume when playing the themes)
Delayed Audio Theme Start (Seconds)
Wait the set amount of time before starting to play the audio theme
Delay Video Theme Start (Seconds)
Wait the set amount of time before starting to play the video theme
Fade out after playing for (minutes)
Stop playing themes after a set amount of time
Fade tune out when exiting
When it is time to stop playing the theme, fade it out
Fade in tune when starting
When a theme starts playing, fade the it in so it starts very quietly
Shuffle multiple tracks
When there are multiple themes, play them in a random order
Random start time
When a theme starts, play it from a random point in the theme
Only ever play single theme
When there are multiple themes, will only play one of them
Limit track duration when multiple themes (seconds)
Only play the given amount of a track before moving to the next track

9.3 Download

Enable Theme Library
Enables the TvTunes Theme Library
- Load Registration File
Loads the registration file that allows access to the TvTunes Theme Library
Automatically Download Theme If
  • Never - Always prompt the user to select the theme to use
  • Only Single Entry Found - Download automatically if there is only one theme found
  • Priority 1 (*) Entry Found - Download automatically if there is a priority 1 theme found
  • Priority 1 (*)or Priority 2 (~) Entry Found - Download automatically if there is a priority 1 or 2 theme found
- Show Selection Dialog If Auto Match Fails
If no automatic match found, prompt the user for a selection (otherwise skip it)
Always add additional themes (no overwrite)
Will not overwrite additional themes, instead it will add to the existing list of themes
Show the TvTunes button on the Video Info screen
Enables the Download TvTune button on the Video Information screen so that you can download themes on a per Movie/TV Show basis
Default Theme Search Source
Select the web site to search in order to retrieve themes, default value is "All Sites"
Show TvTunes On Context Menu
If the TvTunes menu item should be shown on the context menu to allow the download of a theme directly from a given video item
Browse Themes
Will load the theme browser plugin to allow you to look for themes for your entire library
Update advancedsettings.xml File
Will update (or create if it does not already exist) the advancedsettings.xml file so that your theme files are not accidentally read into the library and incorrectly detected as actual Movies or TV Shows
Update Confluence Skin
Adds a TvTunes button to the Video Information dialog

9.4 File System

Use Protected SMB Share
Allows you to define a username and password when accessing themes via an SMB share
Store tunes in a custom path
Allows you to specify a location where the themes will be stores (i.e. not embeded within your Video collection)
Support themes in sub directories
Allows you to define the name of a sub directory where the themes will be stored under each movie in the video library
Change File Types
Allows the selection of which file types are supported for theme files i.e. mp3, flac, wav
When A Video Theme Exists
Allows you to select what to do when a video theme is encountered. The options are "Mix With Audio Themes", "Play Video Themes First" and "Only Play Video Themes"
- Repeat Single Audio Theme After Video
Only valid when "Play Video Themes First" is set, will play the video theme first, then if there is also an audio theme, will keep repeating just the audio theme
Block Refresh Rate Change
If you have the setting to "Adjust display refresh rate to match video" enabled, then this setting will ignore that setting when playing video themes
Reset Volume On Startup
Will reset the Kodi volume on startup of the system - this is useful if you always run your system at a set volume and use the TV or external audio system to change the volume (This way if the system crashes while playing a TvTunes theme, it will not leave the volume in an inconsistent state)
- Set Volume On Startup To
The value to set the Kodi volume to on startup
Enable debug logging
Enables TvTunes debug logging (Required if reporting a problem) - for this to work, system-wide Kodi logging must also be enabled

9.5 Screensaver

Select which format of screensaver to use
Image Source
Select if the Movie, TV Show or custom path is used to show images for the screensaver
- Image Type
Which type of images to use for the screensaver i.e. Fanart, Thumbnails, Cast
Play Themes During Screensaver
If a theme is available, play it while showing the images for the given Movie or TV Show
- Only Show Images When A Theme Exists
Only add a Movie or TV Show to the screensaver if it has a theme
- Repeat Rules
When to move to the next set of images for a different Movie or TV Show
Include Artwork Downloader Images
If the Artwork Downloader Addon is installed and has stored images with the Movie or TV Show, also show those images
Dim Level
If to dim the screen when the screensaver runs

10 Skins And Addon Customisations

No skin changes are required in order to use TvTunes, however some skins have added additional changes to help trigger the downloading of themes (Such as a TvTunes button on the Video Information Dialog)
The following information is aimed at skinners and show what the TvTunes changes in Confluence could be to add specific additional features.

10.1 Adding A Download Button To Video Information

If you wish to add a TvTunes theme download button to the Video Information dialog you will need to change DialogVideoInfo.xml. Add the following near the foot of the file after the last control statement:

<control type="button" id="100">
	<description>Fetch TvTunes stuff</description>
	<visible>Skin.HasSetting(ActivateTvTunes) + System.HasAddon(script.tvtunes) + 
	[Container.Content(TVShows) | Container.Content(movies) | Container.Content(musicvideos)] +
Location of XML files
OS X: /Applications/
Windows 8.1: Program Files (x86)\Kodi\addons\skin.confluence\720p

10.2 TvTunes Active Detection

If a skin (or other Addon) wishes to work out if TvTunes is currently playing a theme (and maybe not show something if TvTunes is running), then a check can be made to see if the PlayingBackgroundMedia value is set:


This can be useful if you wish to stop things like "Music Visualizations" while the theme is playing.
Note: In Pre 5.0 versions of TvTunes, this variable was called TvTunesIsAlive.

10.3 Blocking Theme Playing

If you wish to stop TvTunes from playing a theme, then you can set the value "TvTunesBlocked":

xbmcgui.Window(10025).setProperty("TvTunesBlocked", "true")

But please ensure you also clear the property when the plugin no longer needs to block themes playing

xbmcgui.Window(10025).clearProperty( "TvTunesBlocked" )

10.4 Custom Windows

By Default TvTunes will only activate when in the official "Videos" section. If you have a custom Window in a skin or Addon that you with a theme to be activated for, then you can add the following line to your window-xml file in addition to the previously detailed onLoad action.

For Movie Themes add:

<onload>SetProperty("TvTunesSupported", "Movies")</onload>

For TV Themes add:

<onload>SetProperty("TvTunesSupported", "TvShows")</onload>

If you have an addon that is migrating between screens and you want to ensure that TvTunes does not have a break in playing, you can set a property on the home screen to force playing of an existing track continues. This can be done by:

xbmcgui.Window( 12000 ).setProperty( "TvTunesContinuePlaying", "True" )

But please ensure you also clear the property when the plugin no longer needs to force the theme to play

xbmcgui.Window( 12000 ).clearProperty( "TvTunesContinuePlaying" )

11 Known Issues

There are currently the following known issue that can not currently be fixed, please do not raise an Issue for these, as there is currently nothing that can be done about this.

11.1 Addon Selection

In order for TvTunes to download themes via the Videos -> Add-on method, you must have the System setting for Video -> File lists -> "Default select action" set to "Play". With this set to the other values such as "Show Information" the addon will not even be called by Kodi. (Downloading via the Video Information Screen is unaffected by this setting)

11.2 Setting: Store tunes in a custom path

There is an issue with storing all the themes in a custom path if you use TvTunes to play themes for both TV Shows and Movies. This can occur when you have a TV Show and a Movie with the same name, as it will store them in the same sub-directory. This is a legacy setting that has been in TvTunes a while, ideally the TV Shows and Movies would be stored in different location, however making this change now would break existing users.

11.3 Video Themes And Looping

If you have a video theme and set it to loop then when it starts the second playing of a video theme, it will flash up full screen. This is a Kodi issue detailed on the following bug report: TRAC-16013

12 Creating Your Own Theme

If a theme is not available on for your TV Show or Movie, then it is possible to create your own from your video file. You can do this in many ways, but detailed below is one that is free.

First download ffmpeg

Then play your video file and take note of the timestamps of where your TV Theme starts playing and where it stops. Then on the command line you can run the command:

ffmpeg -ss 00:02:00 -t 00:04:00 -i VideoFile.mkv theme.mp3

Where the value after -ss is the start time in the format hh:mm:ss and the value after -t is the duration to extract for. (You can use -to hh:mm:ss after the filename instead of the -t option to specify an explicit stop time)

Once you have generated the theme, then maybe uploading your newly generated theme to would be a nice thing to do so other users can benefit from it. You may email any songs that you have to their e-mail address [email protected], including the exact name and year of the tv shows/movies.

13 Debugging

If reporting a problem, please also provide a debug log. To do this you need to enable BOTH:

  • Kodi logging from the main setting menu
  • TvTunes debug from the TvTunes addon settings menu

Please do not paste the log into the forum thread, just link to it.

14 Donations

If you have found TvTunes useful and would like to help support future development and bug fixes, then please feel free to make a small donation.

Please use the link on the top of the TvTunes Forum

Personal tools

Wiki help