What is ttvdb.py
This python script is intended to perform TV series data lookups based on the thetvdb.comwiki
As of change set  ttvdb.py is shipped with MythTV trunk.
If you have previously installed ttvdb.py please resync your MythTV installation of trunk. A separate install is not required.
Configuring MythVideo 0.22 to use ttvdb.py
Command to search for TV Shows in Mythvideo: /usr/local/share/mythtv/mythvideo/scripts/ttvdb.py -l en -M Command to search for TV Season posters: /usr/local/share/mythtv/mythvideo/scripts/ttvdb.py -l en -mP Command to search for TV Show fanart: /usr/local/share/mythtv/mythvideo/scripts/ttvdb.py -l en -tF Command to search for TV Season banners: /usr/local/share/mythtv/mythvideo/scripts/ttvdb.py -l en -B Command to extract data for TV Episodes: /usr/local/share/mythtv/mythvideo/scripts/ttvdb.py -l en -mD Command to search for TV by Title/Subtitle: /usr/local/share/mythtv/mythvideo/scripts/ttvdb.py -l en -N
The language in these parameters are all 'en' English. Change them to your preferred language. See the next section for the supported languages. DO NOT put either single or double quotes around the language en es ... etc. Mythvideo download will not work if you add quotes.
Now you can use the mythvideo download feature "Manage Video|Download Metadata" to get a TV series artwork (poster, fanart and banner) plus episode details.
The -M option is language specific and will only return series names that match the specified language with English being the default if no language is specified.
Why am I not getting the promised episode data?
Here are the usual suspects:
- You have not set the Season and Episode number in the "Edit Metadata" screen. With all patches applied, MythVideo will automatically detect and set the season and episode numbers if you import a filename containing the common formats (ie s01e01 or 1x01), but pre-existing material will need the season and episode numbers set manually.
- The Schedules Direct series or episode name is completely different then what was entered in thetvdb.com.
- You have not set up the commands properly in the setting as described in #Configuring MythVideo 0.22 to use ttvdb.py.
- The episode data was updated but one or more of the graphics will not display. Thetvdb.com web site can get overloaded which results in graphic files that are actually html error messages. If this occurs all you need to do is use the mythvideo "Manage Video|Reset Metadata", then download again, "Manage Video|Download Metadata". If you get a lot of these issues perform your metadata downloads when thetvdb.com is not so busy.
- The format of your video file may not contain a series name matching that of any on thetvdb.com wiki or have incorrect season and episode numbers. If that is not the case then the video file name format may not be supported by ttvdb. This is the one case where you may need to use a user configuration file for mythvideo "Manage Video|Download Metadata". See section #User configuration file. You can add your own regex string for parsing your video file names. Regex is not for the faint of heart but the option is there if you need it,
- If problems persist verify that ttvdb is properly installed by viewing your mythfrontend log or trying ttvdb from the command line. See the next section on how to display examples.
- You are not running trunk, or you have not resynced your MythTV trunk installation.
- You are not running your machine with locale of 'utf-8'. Your configuration should look something like:
- > locale
- > locale
- One user pointed out the the utility 'PuTTY' (a Telnet and SSH client) was defaulting to 'latin-1' and therefore converting the TV series title so that TV series searches never found a result.
Command line examples
To view command line examples of all ttvdb features type:
User configuration file
A user configuration file is not required when grabbing TV data through mythvideo download metadata. This is because you interactively select the specific TV series. If you intend to use ttvdb in your own user scripts a user configuration file is highly recommended.
TV listing sources such as Schedules Directdo not always pass MythTV TV series and episode names that match those on thetvdb.com wiki. This can cause ttvdb to fail in retrieving data. Luckily this does not happen often. To compensate ttvdb provides a user configuration file which can deal with those rare cases.
The configuration file can tie a series name (%TITLE%) to a specific thetvdb.com series id (the equivalent of an IMDB number). Also a TV series episode name (%SUBTITLE%) can be modified to match the episode name on thetvdb.com.
Copy and rename ".../mythtv/mythvideo/scripts/ttvdb/ttvdb-example.conf" to a directory of your choosing (e.g. ~/.tvdb/ttvdb.conf). Then edit the new file making changes as required. The example configuration file contains documentation for all sections and fields. To have ttvdb use your configuration file use the -c option, For example:
ttvdb -c "/home/user/.tvdb/ttvdb.conf" ...
An example of a mismatch is where Schedules Direct has the TV Series name "The Beast" but thetvdb.com has the series name as "The Beast (2009)". Schedules Direct has the series "24" episode name of "Day 7: 10:00PM-11:00PM" while thetvdb.com has "Day 7: 10:00 PM-11:00 PM". The configuration file can compensate for these discrepancies.
Here are several examples that are included but inactive in the "ttvdb-example.conf" file. Please add new ones to this section when you encounter them.
[series_name_override] # Specify recorded "Life On Mars" shows as the US version Life on Mars:82289 # Specify recorded "Eleventh Hour" shows as the US version Eleventh Hour:83066 # Specify recorded "Frontline" or "Frontline/World" shows as the "Frontline PBS" version Frontline/World:80646 Frontline:80646 # Specify recorded "The Beast" shows are the 2009 version The Beast:83805 # Specify recorded "Castle" shows are the 2009 version Castle:83462 # Specify recorded "Battlestar Galactica" shows are the 2003 version Battlestar Galactica:73545
[ep_name_massage] # Modify the TV series 24 episode name (%SUBTITLE%) 24: PM," PM", AM, " AM",M-,"M - "
#!/bin/bash # TV Episode Video File Name generation # $1 = %TITLE% and $2 = %SUBTITLE% echo "$1 - `ttvdb -N \"$1\" \"$2\"` - $2"
> example_script.sh "Sanctuary" "Sanctuary for All (2)" Sanctuary - S01E02 - Sanctuary for All (2)
If the series and/or episode was not found the script would have return
"Sanctuary - - Sanctuary for All (2)"
You can change the format of the season and episode numbers. For example:
echo "$1 - `ttvdb -N \"$1\" \"$2\" 'Season%dx%02d'` - $2"
Generates the custom format:
Sanctuary - Season1x02 - Sanctuary for All (2)
Obviously these examples are an oversimplification but it gives you an idea of what can be done.
User jobs are not generally interactive so it is highly recommended to include a user configuration file (see: User configuration file) so that series and episode names are found without manual interaction. With a user configuration file the simple example could have looked like:
echo "$1 - `ttvdb -c \"/home/user/.tvdb/ttvdb.conf\" -N \"$1\" \"$2\"` - $2"
If you find any other valuable ways to utilize ttvdb in a user job please add an example to this section.
The ttvdb script could not exist without the tvdb_api module written by dbr/Ben. Time and again dbr/Ben has added functionality to accommodate the needs of MythTV. dbr/Ben has another useful script called tvnamer which renames video files to a standard format, tvnamer and tvdb_api can be found at:
You can install tvnamer which will also install a version of tvdb_api without fear of being out of sync with the version of tvdb_api that ttvdb uses as they are packaged separately.