Add-on:TvTunes

Forum, Repository and Issue Report Pages
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 Future Enhancements Forum

If you find any bugs or have an enhancement requests, these can be recorded at the following location:


 * TvTunes Google Issue List

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: This allows for nested directories where seasons of TV Series are in separate directories, but all wish to use the same theme.
 * 1) Themes in the same directory as the video file
 * 2) (If no theme found) search for themes in the parent directory

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)

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 XBMC playlist file. (The extension "m3u" will be added if not already specified)

Smart Playlists: To make use of a Smart Playlist in XBMC 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.

Settings
This section details all the settings options for TvTunes

Playback

 * Play theme in loop
 * Will continue to play all themes in a loop
 * Lower sound value
 * Reduces the volume before stating to play the theme in the background
 * Delay Theme Start (Seconds)
 * Wait the set amount of time before starting to play the theme
 * Fade out after playing for (minutes)
 * Stop playing themes after a set amount of time
 * 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
 * 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
 * Limit track duration when multiple themes (seconds)
 * Only play the given amount of a track before moving to the next track

Download

 * Automatically download if an exact match is found
 * When searching for themes, if there is only one theme found them it will download it without prompting (Warning: This may not be the correct theme - just the only one listed)
 * Always add additional themes (no overwrite)
 * Will not overwrite additional themes, instead it will add to the existing list of themes
 * Search for movie themes
 * Allows download suport for Movies as well as TV Shows
 * 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
 * Theme Search Source
 * Select the web site to search in order to retrieve themes, default value is goear.com. This can be changed to televisiontunes.com if desired
 * Perform Complete Search Now
 * Will look for themes for your entire library (Note: If you have changed the download settings - such as "Search for Movies" - you will need to exit the settings screen and go back in again for the Perform Search button to pick up those changes)

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
 * Enable debug logging
 * Enables TvTunes debug logging (Required if reporting a problem) - for this to work, system-wide XBMC logging must also be enabled

File Types

 * These settings are simply a list of types that can be supported by TvTunes. MP3's are always enabled, the remaining types (WMA,FLAC,M4A,WAV) can be toggled on or off.

Skins With Build In Support
The following skins have built-in support for TV Tunes, so require no user skin modifications:
 * Confluence
 * Transparency!
 * XTV-SAF
 * Amber
 * Aeon MQ 5
 * Rapier
 * XBMC Immerse
 * Cirrus Extended (V3)
 * Confluence Modified
 * Xperience1080++

Skin Changes
In order to support TvTunes a few alterations are required to the skin, the following show what is required to change in confluence (Other skins will have similar changes)

MyVideoNav.xml
Add to the top of the file [Triggers the start of the theme playing]:

DialogVideoInfo.xml
Add to the top of the file [Triggers the start of the theme playing]:

Add to near the foot of the file after the last control statement [Allows download of theme on a video by video basis]:

Skin - TvTunes Active Detection
If a skin 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 TvTunesIsAlive value is set: This can be useful if you wish to stop things like "Music Visualizations" while the theme is playing.

Skin - 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:

For TV Themes add:

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:

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

Known Issues
There is currently a known issue that can not currently be fixed, please do not raise an Issue on the google system for this, as there is currently nothing that can be done about this.

Sceensaver
When the screensaver is about to start, TvTunes stops playing the theme. Unfortunately this is seen as "activity" so the screensaver time is reset and will not kick in again until the screensaver idle time as expired for a second time (This may be able to be resolved in the Gotham release)

In the official repository there is a fix that needed to be commented out in order to meet with the rules of the official repo. This means that strange behavious can occur if the screensaver starts while playing a TV Theme. There are two methods to resolve this:
 * 1) Uncomment the method "_loadScreensaverSettings" in tvtunes_backend.py
 * 2) [Recommended] Set the "Fade out after playing for (minutes)" to less than the screen saver value in TvTunes setting

Creating Your Own Theme
If a theme is not available on www.televisiontunes.com 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:

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 www.televisiontunes.com 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 jayzoo@gmail.com, including the exact name and year of the tv shows/movies.

Debugging
If reporting a problem, please also provide a debug log. To do this you need to enable BOTH: Please do not paste the log into the forum thread, just link to it.
 * XBMC logging from the main setting menu
 * TvTunes debug from the TvTunes addon settings menu

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. Any donations made will be put towards hardware to enable support and development on different platforms (I can currently only test Windows - however I would like to be able to verify changes on Android and Mac - and this is what donations would go towards)

Please use the link on the top of the TvTunes Forum

Note: Donations will not make any difference to the level of support I will give people on the forum - this project is Open Source - and is completely free!! Also, this plugin is built on top of XBMC - so please donate to that first.

Additional Information and History
The support and enhancement of TvTunes was taken over by rob_webset at version v3.0.9, since then several enahncements and bugfixes have gone in, these include (but are not limited to):


 * Added support for playing themes in Movie and TV Show list screen
 * Added support for playing themes of Multi Part (Stacked) Video Files
 * Added support for playing themes on display of the Info Screen for TV and Movies
 * Restructured code to try and improve reset of volume
 * Added support for different file types
 * Added support for multiple theme files (default order alphabetical)
 * Added option to allow multiple files to be shuffled in the playlist
 * Added option to allow random start point within media track
 * Add support for fading in theme on start
 * Fix scraper bug when selecting from Information Page
 * Add support for downloading additional themes
 * Add support for downloading movie themes
 * Improve volume correction when exiting XBMC quickly
 * Make sure TvTunes stops before screensaver starts
 * Ability to hide the TvTunes button on the Video Information screen
 * Add ability to fade out the theme after a given duration
 * Add support for delaying the start of a theme playing
 * Support themes stored in sub-directories
 * Support of tvtunes.nfo files
 * Support playlists
 * Add support for only play a fraction of each track