XMLTVImportPlugin: Demideus
A while ago I started adding features to the XMLTVImportPlugin. Mainly to translate categories so that shows would appear color-coded in the EPG.
After several updates I think it's high time to put this plugin in it's own thread...
Before you unzip xmltvimportplugin.zip in the SageTV directory, make a backup of the current xmltv subdirectory 
After unzipping, restart SageTV, this will reload the classes.
The translation of categories happens just before the show is committed to SageTV. This makes it possible to translate category combinations rather than just single categories (also handy if you want to reverse the categories).
If the category combination is not configured the categories will be translated seperately.
Only the first two resulting categories will be used (any single category can be translated to a category combination).
I try to avoid ending up with the same category being specified twice, but I think I'd better rewrite part of that function so it will be more consistent.
Only shows have not yet been started are updated. Shows that already have started, or are in the past, are not updated.
For those interested in the source: The testcases in the Eclipse project use a mock object generated by MockCreator.
Tell me what you think,
L8r, Demideus
Install- If present make a backup copy of the xmltv directory in the SageTV directory (\Program Files\Sage\SageTV or \Program Files\Frey Technologies\SageTV).
- Unzip xmltvimportplugin.zip into the SageTV directory.
This should have created an xmltv directory containing 4 .class files.
- Exit Sage and stop the Sage server.
- Edit the Sage.properties file and set the value of "epg/epg_import_plugin" to "xmltv.XMLTVImportPlugin".
- Save and exit the editor.
- Restart Sage (and the Sage server).
Configuration
The plugin doesn't need to be configured. If you're fine with the defaults, you can simply ignore the configuration options.
If however you want to change some of the defaults you can create a xmltv.properties file in the SageTV directory.
Below is the 'documentation' for the configuration options. It may also be used as a template.
Unfortunately, this forum does not lend itself to preformatted text. So this documentation, of necessity, is not well-spaced...
################################################################################
# configurations=<filename>[,<filename>]...
# @since 1-2006
################################################################################
# The configuration files that should be used.
# This option only works in "xmltv.properties".
#
# - filename - The name of a properties file.
# Default: xmltv.properties
#
# This can be used for the following options:
#
# 1. Allow for seperate configuration of seperate xmltv files (in combination
# with the setting xmltv.files).
# 2. Allow for separate configuration of channels or channel-groups (in
# combination with the setting channel.ids).
# 3. Allow for multiple providers (or lineups) (in combination with the setting
# provider.name).
################################################################################
# include=<filename>[,<filename>]...
# @since 1-2006
################################################################################
# The configuration files that should be included.
# Settings in the current file will override any settings in the included files.
#
# - filename - The name of a properties file.
################################################################################
# provider.name=<name>
# provider.id=<id>
# @since 1-2006
################################################################################
# The provider.
#
# - name - The provider name.
# Default: XMLTV Lineup
#
# - id - The provider id.
# Must be between 1 and 9223372036854775807.
# Default: If the name is "XMLTV Lineup" then 867507149 (for backwards
# compatibility) otherwise the CRC32 value of the name.
################################################################################
# timeslot=<time>-<time>
# @since 4-2006
################################################################################
# The plugin will wait for this timeslot before starting the update.
# The timeslot is evaluated for each configuration.
#
# - time - a time using the following format: hhmm
#
# Example:
# timeslot=0400-0500
################################################################################
# run.before=<command>
################################################################################
# The command that should be executed before reading the xmltv files.
# This can be used to run the process that actually collects the xmltv data.
#
# - command - The command that is executed.
################################################################################
# xmltv.files=<filename>[,<filename>]...
################################################################################
# The xmltv files that should be parsed.
#
# - filename - The name of a xmltv file.
# Default: epgdata.xml
################################################################################
# inputstream.filter=<boolean>
################################################################################
# Filters invalid XML characters from the xmltv input file.
#
# Characters between 0x0 and 0x1f (0 - 31) are filtered
# (only works on 8-bit encoded xmltv files).
#
# - filter - 'true' if the filter should be activated.
# Default: false
################################################################################
# channel.ids=<id>[,<id>]...
################################################################################
# The channels that are added to the guide.
#
# - id - The xmltv id of a channel that should be added to the guide.
# '*' if all channels should be added.
# Default: *
#
# NOTE: filtered channels will still be parsed, they will merely not be added to
# the guide.
################################################################################
# channel.<id>.names=<name>[,<name>]
# channel.<id>.network=<network>
# channel.<id>.numbers=<number>[,<number>]...
################################################################################
# The channel details from the xmltv file can be overridden.
#
# - id - The xmltv id for the channel.
# - names - The short and long names for the channel.
# - network - The name of the network.
# - numbers - The tuner channel numbers for this channel.
#
# Examples:
# channel.TMF.names=TMF, The Music Factory
# channel.TMF.network=Network1
# channel.TMF.numbers=22, 50
#
# The missing data will be obtained from the xmltv file.
################################################################################
# rating.<system>.<value>=[<rating>][,<expanded-rating>]...
# @since 1-2006
################################################################################
# Translate the rating information to Sage ratings.
# Any rating that is not configured will be logged to the error log.
#
# - system - The rating system. Leave empty if the rating system is not
# specified in the xmltv file.
# '*' if this setting should be used for all rating systems.
#
# - value - The xmltv rating value.
#
# - rating - The Sage rating.
# Sages parental control can block programmes with the following ratings:
# NR, AO, NC-17, R, PG-13, PG, G, TVM, TV14, TVPG, TVG, TVY7, TVY
# Any value may be used though.
#
# - expanded-rating - An expanded rating.
# Possible values:
# - Graphic Violence
# - Violence
# - Mild Violence
# - Graphic Language
# - Language
# - Adult Situations
# - Strong Sexual Content
# - Nudity
# - Brief Nudity
# - Rape
#
# The defaults are:
# - rating.*.NC-17=NC-17
# - rating.*.X=NC-17
# - rating.*.R=R
# - rating.*.PG-13=PG-13
# - rating.*.PG=PG
# - rating.*.G=G
# - rating.*.TV-MA=TVM
# - rating.*.TV-MA-V=TVM, Graphic Violence
# - rating.*.TV-MA-S=TVM, Strong Sexual Content
# - rating.*.TV-MA-L=TVM, Language
# - rating.*.TV-14=TV14
# - rating.*.TV-14-V=TV14, Violence
# - rating.*.TV-14-S=TV14, Adult Situations
# - rating.*.TV-14-L=TV14, Language
# - rating.*.TV-14-D=TV14, Graphic Language
# - rating.*.TV-PG=TVPG
# - rating.*.TV-PG-V=TVPG, Mild Violence
# - rating.*.TV-PG-S=TVPG, Adult Situations
# - rating.*.TV-PG-L=TVPG, Language
# - rating.*.TV-PG-D=TVPG, Graphic Language
# - rating.*.TV-G=TVG
# - rating.*.TV-Y7=TVY7
# - rating.*.TV-Y=TVY
################################################################################
# max.stars=<number>
# @since 1-2006
################################################################################
# Specifies the maximum number of stars that the star-ratings element will be
# rescaled to.
#
# - number - The maximum number of stars.
# Default: 4
################################################################################
# initcap.title=<boolean>
# initcap.episode.name=<boolean>
# initcap.channel.ids=<id>[,<id>]...
# initcap.skip.words=<word>[,<word>]...
################################################################################
# Titles on dutch channels are capitalized differently from titles on english
# channels. This would be ok if sage's favourites weren't case-sensitive.
# To solve this the parser can capitalize the initial letter of each word in
# a title. Since in english not all words are capitalized there is also a list
# of words that can be excluded from this (this also helps in IMDB lookups).
#
# - boolean - 'true' if the title or episode name should be processed.
# Default: false
#
# - id - a channel for which the titles and/or episode names should be
# processed.
# '*' if all channels should be processed.
# Default: *
#
# - skip.words - The words that should be ignored.
# Default: the, a, an, at, in, on, and, of, from, to, is, with, not, en, de,
# der, het, op, voor, uit, van
################################################################################
# title.add.year=<boolean>
# title.add.year.categories=<category>[,<category>]...
################################################################################
# The year of the show can be added to the title between braces.
# This should help in IMDB lookups, but it doesn't (it doesn't hurt though).
#
# - boolean - 'true' if the year (xmltv date element) should be added to the
# title (kept for backward compatibility).
# Default: true
#
# - category - A category for which this option is activated.
# '*' if this option should be activated for all categories.
# Default: Movie
#
# NOTE: This does not affect the generated show-id.
################################################################################
# date.title.decoration=<decoration>
# date.title.decoration.categories=<category>[,<category>]...
# @since 3-2006:
################################################################################
# The date of the show can be added to the title between braces.
# (if both title.add.year and date.title.decoration are applicable
# only the date.title.decoration is used).
# This should help in IMDB lookups, but it doesn't (it doesn't hurt though).
#
# - decoration - The decoration of the title.
# -- Use {0} to represent the current title.
# -- Use {1,date,short} to represent the date.
# Default: {0} ({1,date,short})
#
# - category - A category for which this is activated.
# '*' if this option should be activated for all categories.
#
# NOTE: This does not affect the generated show-id.
################################################################################
# hd.title.decoration=<decoration>
# hd.title.decoration.channels=<channel>[,<channel>]...
# @since 3-2006:
################################################################################
# The title can be decorated if the content of the quality element starts with
# "HD". This is intended to allow seperate favourites for a series that is
# broadcast in different qualities (presumably on separate channels).
#
# - decoration - The decoration of the title.
# -- Use {0} to represent the current title.
# Default: HD - {0}
#
# - channel - A channel for which this is activated (should only be the channels
# for which you can record in HD).
# '*' if this option should be activated for all channels.
#
# NOTE: This does not affect the generated show-id.
################################################################################
# episode.name.add.episode.number=<boolean>
# episode.name.add.part.number=<boolean>
################################################################################
# The episode number can be prepended to the episode name.
# The part number of the episode can be added to the episode name.
#
# - boolean - 'true' if the corresponding option should be activated.
# Default: true
#
# NOTE: This does not affect the generated show-id.
################################################################################
# split.movie.detect.time=<milliseconds>
################################################################################
# The parser tries to detect movies that were split into two separate timeslots
# and adds an appropriate sequence number to the parts.
#
# - milliseconds - The maximum time that two shows can be set apart (start-time)
# for them to be considered split movie parts.
# Default: 14400000 (4 hours)
################################################################################
# credits.director=<role>
# credits.actor=<role>
# credits.writer=<role>
# credits.adapter=<role>
# credits.producer=<role>
# credits.presenter=<role>
# credits.commentator=<role>
# credits.guest=<role>
################################################################################
# Support any credits in xmltv to aid the Intelligent Recording setting. It
# could also help in IMDB lookup... but it doesn't
#
# - role
# The Sage role.
# Possible values:
# - actor
# - actor.lead
# - actor.support
# - actress
# - actress.lead
# - actress.support
# - guest
# - guest.star
# - host
# - director
# - choreographer
# - writer
# - producer
# - producer.executive
# - sports.figure
# - coach
#
# The defaults are:
# - credits.director = director
# - credits.actor = actor
# - credits.writer = writer
# - credits.adapter =
# - credits.producer = producer
# - credits.presenter = host
# - credits.commentator =
# - credits.guest = guest
#
# @since 1-2006 The value 'none' is no longer needed to deactivate a default
# credits setting.
################################################################################
# translate.category.<category>[/<category>]...=<category>[/<category>]...
# report.missing.translate.category=<boolean> @since 1-2006
################################################################################
# Translate category-combinations so the Live TV Guide can use colors and movies
# and series can be recognized as such.
#
# Any missing translations can be reported in the error log.
#
# - category - A category.
# - boolean - 'true' or 'false'
#
# Known colored categories:
# - Movie: purple
# - News: yellow
# - Sports event: green
# - Sports non-event: green
# - Sports talk: green
#
# Examples:
# - report.missing.translate.category=true
# - translate.category.Fantasyfilm=Movie/Fantasy
# - translate.category.Sf-serie=Series/Sci-Fi
# - translate.category.Sport=Sports event
# - translate.category.Stomme\ film=Movie/Silent
################################################################################
# max.subcategories=<number>
# @since 1-2006
################################################################################
# Sage only allows for 1 subcategory. Any additional categories are combined
# by the plugin before they are added to the guide.
# This option allows you to set a limit to the number of subcategories that are
# added to the guide.
#
# - number - The maximum number of subcategories.
#
# Example:
# - max.subcategories=1
################################################################################
# rerun.after.date=<days>
# rerun.after.date.categories=<category>[,<category>]...
# @since 3-2006
################################################################################
# In some feeds the date is used to store the original air date (either globally
# or on that network). This can be used to detect if the show is a rerun.
# This option specifies the number of days that should have passed since that
# date to mark the airing as a rerun.
#
# - days - The number of days.
#
# - category - A category for which this option is activated
# (only if rerun.age.days has a value).
# '*' if this option should be activated for all categories.
# Default: Series
################################################################################
# rerun.no-episode.categories=<category>[,<category>]...
# @since 3-2006
################################################################################
# Some feeds do not provide episode information on late night reruns
# (xmltv <sub-title> and <episode-num> elements) . This results in Sage
# recording all such reruns for any favourite that has been programmed.
#
# By using this option such episodes are marked as reruns so that they can be
# ignored by the favourite.
#
# - category - A category for which this option is activated
#
# Example:
# - rerun.no-episode.categories=Series
################################################################################
# rerun.no-date.categories=<category>[,<category>]...
# @since 3-2006
################################################################################
# The categories for which the absence of a date element should indicate a
# rerun.
#
# - category - A category for which this option is activated
#
# Example:
# - rerun.no-date.categories=Series
################################################################################
# categories.for.star-rating=<category>[,<category>]...
# @since 3-2006
################################################################################
# The categories are not always enough to determine if something is a movie.
# This option allows you to add a category (or categories) if a star-rating
# exists.
#
# - category - A category that should be added.
#
# Example:
# - categories.for.star-rating=Movie
################################################################################
# date.year.decoration=<decoration>
# @since 4-2006
################################################################################
# If the xmltv specified a full date, this date can be put into the year field.
#
# - decoration - The decoration of the title.
# -- Use {0} to represent the xmltv date.
#
# Example:
# - date.year.decoration={0,date,short} Update 28-11-2004- Bugfix: Import crashed when processing show with single resulting category (Sage was Ok, EPG was merely not updated from that point onward).
- Added exception handling. Separate exception log: "xmltv.exceptions.log".
- Added run.before setting to xmltv.properties. It is now possible to run your favourite xmltv generator just prior to importing it's result. Doesn't seem to work in server mode.
- Captured console output to "xmltv.console.log".
Update 7-12-2004- The presence of a previously-shown element now indicates a rerun.
- Episode numbers are now added to the detail screen and the episode name (after calculating the show ID).
- The episode number is now used in the show ID:
- If an episode name is present, the show ID will be generated from the title and the episode name (unchanged).
- If no episode name is present but an episode number is, the show ID will be generated from the title and the episode number.
- If no episode name and no episode number is present, the show ID will be generated from the title and the start time (unchanged).
Update 5-1-2005- Removed the show description from the show ID calculation. It caused same shows to show up with different ID's simply because the description wasn't the same. (I really should have had this update out earlier...)
- Added dot behind the episode number in the episode name (it just didn't look right without it).
- Redone the show ID generation. All text-items are now processed in lowercase. The initial letter in the ID now indicates the algorithm used in calculating the ID.
'T': Title + start-time. (used when no episode or year information is available).
'E': Title + episode name + episode number.
'M': Title + year. (only used for category "Movie") .
- If a movie ID is started multiple times on a single channel within four hours it is assumed to be a split-up movie and the second ID will receive a sequence number.
- Shows that have already started will not be added to the EPG. This should prevent recorded shows to lose their title and other information simply because the shows information has changed.
Update 8-1-2005- New configuration option: inputstream.filter.
Setting this to true will remove any invalid XML characters between 0x0 and 0x1f in an 8-bit encoded epgdata.xml.
Update 28-8-2005- Moved plugin to it's own forum thread.
- Changed the showId creation (again) to reflect the Zap2It showId format. This enables other plugins to grab the episode number from the end of the showId.
- Added multiple xmltv-files support (xmltv.files).
- Added channel filtering (channel.ids).
- Added channel details override (channel.[id].*).
- Added capitalization of titles (initcap.*).
- Added option to add the year to the title (title.add.year).
- Added option to prepend the episode number to the episode name(episode.name.add.episode.number).
- Added option to add the part number to the episode name (episode.name.add.part.number).
- Added split movie detection (split.movie.detect.time).
- Made credits mapping default (credits.*).
- Added series, episode and part numbers to the bonus info.
- Added media info to the bonus info.
Update 4-1-2006- Renamed log files to xmltv.log and xmltv.error.log.
If there are no errors, xmltv.error.log is deleted at the end of the import.
The logfiles are automatically deleted if they are older than 4hrs at the begin of the import.
- Added multiple configuration support. configurations=<filename>[,<filename>]...
- Added include option. include=<filename>[,<filename>]...
- Added provider configuration and thereby multiple lineup support. provider.name=<name>; provider.id=<id> (info gathered from Nielm's plugin)
- Added import of <star-rating>. max.stars=<number>
- Added import of <country>.
- Added import of <language> and <orig-language>.
- Added import and translation of <rating>. rating.<system>.<value>=[<rating>][,<expanded-rating>]...
- Added support for dummy channels. channel.ids=<id>[,<id>]...
- Added option to reduce the number of subcategories. max.subcategories=<number>
- Added option for logging missing category translations. report.missing.translate.category=<boolean>
- Added splitting of multiple persons in a single credit element (from Koeli's plugin).
Update 5-3-2006- Multiple categories in a single <category> element are now split if they are separated by '/'.
- Added the info from the <quality> element to the bonus information.
- Added support for the <date> element to contain an actual date of completion rather than only a year of completion.
- Added option to mark a show as a rerun based on the time passed since the original air date. rerun.after.date=<days>; rerun.after.date.categories=<category>[,<category>]...
- Added option to mark a show as a rerun if no episode information is present. rerun.no-episode.categories=<category>[,<category>]...
- Added option to add a category if a <star-rating> is specified. categories.for.star-rating=<category>[,<category>]...
Update 22-3-2006- Added option to add the xmltv programme date to the title. date.title.decoration=<decoration> and date.title.decoration.categories=<category>[,<category>]...
- Added option to modify the title for HDTV programmes. hd.title.decoration=<decoration> and hd.title.decoration.channels=<channel>[,<channel>]...
- Added option to mark a show as a rerun if no xmltv programme date has been supplied. rerun.no-date.categories=<category>[,<category>]...
Update 26-4-2006- Corrected the typo in episode.name.add.*
- Added option to put the full xmltv <date> into Sage's show-year. date.year.decoration=<decoration>
- Added option to delay the update until a specified timeslot timeslot=<time>-<time>
- Use the Zap2it showid if it is found in the xmltv feed (<episode-num system="dd_progid">EP808403.0006</episode-num>)
Last edited by Demideus; 04-26-2006 at 02:17 PM.
Reason: Update
|