TV Listings

This plugin is a replacement for the built-in TV Guide and Recordings plugins.


  • Same base functionality as the default TV Guide plugin
  • Same "Look & Feel" as the default TV Guide plugin
  • Support for multiple TV Guides
  • Support for video overlay
  • Immediate startup when activating the plugin - the complete listings will be loaded in the background
  • The plugin recognizes EPG-Updates and restarts loading the data automatically
  • Advanced "Details Popup":
    • Support for long descriptions (scrollable text)
    • Support for images, either loaded from the internet or from harddisk
    • Additional icons to indicate a premiere ("new" show), audio and video quality and star-rating
  • Advanced "Find More Popup":
    • Search in titles, subtitles or descriptions
    • Search all channels or only the current one
    • Search for all or any words of the title
    • Search for all capitalized words or any capitalized words
    • Search on Amazon (.com,, .de,, .fr, .ca) for the current keywords
    • Search on TheTVDB or TheMovieDB for the current keywords
    • Common words (so called "stopwords") can be optionally excluded
  • Adjustable recording-quality setting for "Quick Record"
  • Possibility to update scheduled and in-progress recordings directly
  • Ability to use icons to indicate scheduled recordings in guide
  • Highly customizable TV Recordings plugin similar to the core recordings plugin
  • Built-in TheTVDB integration with automatic episode lookup, no external application needed
  • Genre-based colorization of tv programmes in the listings
  • Recordings Panel to display upcoming recordings inside the 'now playing' area
  • Categories popup to list all upcoming shows of a genre

More Screenshots:

Downloading and Installing

The plugin is available here:

The .zip package contains all files necessary to run the plugin in the necessary subfolders, simply put them into your NPVR data directory. Skin files are included for the default skin. If you're using another Skin, please make sure to download the skin files for your skin in the correct version.

Note: When upgrading from a previous version, you do not need to overwrite your existing TV Listings.db3 file and keep your settings and data.

After installing, both the TV Listings and TV Recordings can be enabled in the "Plugins"/"Visible Menu Plugins" section of NPVR's config screen. The settings can be adjusted in the "TV Listings" plugin section (see below).

Additional programme information and categories/genres

To display additional audio and video information for shows, the plugin looks into the skin subdirectory for small icons that are displayed by the details popup. There are already some icons included, but you can add more depending on the xmltv-source you're using. E.g. if your xmltv source indicates that the video aspect is "16:9", the plugin looks for an image file named 169 (note that illegal filename characters are removed) with an image extension (.jpg|.jpeg|.png|.gif|.bmp). Or if the programme is broadcasted in "Dolby Digital", the plugin looks for an image file named Dolby Digital and so on. The same is done with some additional information that is retrieved when displaying an amazon search result.

To colorize the programmes in the listings, the plugin uses the color definitions from npvr (configurable via the settings form, section "Misc2"). Colorization can be enabled or disabled in the skin file, see Skin Configuration below for details.

If you're from Germany and are using 'TV Movie Clickfinder', I can provide an utitlity that converts the data from Clickfinder (including the additional information) to xmltv. Please contact me over at the forums for details.

TheTVDB integration

The plugin is able to automatically enhance the tv shows with information from, once a tv show's title has been linked to a TheTVDB series. In order to do so, the following simple steps are needed: In the listings, open the details for a programme of a series you wish to link. Select "Find More", and choose "TheTVDB" from the dropdown button. If a series with the programme's title could be found, the episodes are shown in the results list. Now, select one of the episodes and click "Create Link" to establish a link between the show's title and the series information on TheTVDB. After that, all episodes in the listings will automatically contain the additional information (description, star-rating, images, ...) found on TheTVDB.

Note: is an open database that can be modified by anybody. Everyone is encouraged to contribute information and artwork if possible. More details can be found at .

Images for Programmes

The utility XmltvExtras adds additional information for programme images automatically if your xmltv-source includes them. Alternatively or in combination with the images generated by XmltvExtras, the plugin looks in the "Media\Shows" directory for programme-images. See Configuration below for details. Images from TheTVDB are used automatically for linked shows.


NPVR 3.9.2 and above. For displaying additional images from xmltv for programmes, the utility XmltvExtras is needed.


The plugins' configuration is done via the settings dialog NPVR, both for TV Listings and TV Recordings plugin:

TV Listings:

  • Fill gaps with "no show details" programmes:
    Whether timespans without epg data should be filled with placeholders or not.
  • Image directory:
    Path to a directory where the plugin loads images matching a show's title from.
  • Guides:
    Add, edit or remove guides here. You need to provide a name for a guide, and check the channels this guide should include. You can reorder the channels by using the "Channel position" up/down control. At least one guide must be defined, and each guide must contain at least one enabled channel.

TV Recordings:

  • Default View:
    Specify which view should be opened when the plugin is activated.
  • View enabled:
    Each view can be enabled or disabled with the checkbox next to the view's name. The configured default view is always enabled.
  • Default Sort Order:
    For each view, you can configure the default sort order of the shown recordings.
  • Ready - Group Mode:
    In the ready view, you can choose between 4 modes how the recordings are organized:
    • Always group recordings: All recordings are listed in separate subfolder-groups based on their title
    • Never group recordings: All recordings displayed in one single list
    • Group only multiple recordings: Multiple recordings with the same title are put into subfolder-groups, single recordings are shown directly in the ready-list
    • Group only season recordings: Recurring recordings are listed in subfolder-groups, while normal recordings appear ungrouped
  • What's New - Day Count:
    Up to how many days in the past recordings are treated as 'new'
  • What's New - Include failed recordings:
    Whether failed recordings should appear in the list or not
  • What's New - Include in-progress recordings:
    Whether in-progress recordings should appear in the list or not
  • Last Watched - Day Count:
    Up to how many days in the past partly watched recordings appear in the list
  • Pending - Include conflicting recordings:
    Whether conflicting recordings should appear in the list or not
  • Videos - Group Mode:
    In the videos view, you can choose between 2 modes how the recordings are organized:
    • No grouping, skip recording files: All video files that are not stored as recordings are listed in a single list
    • No grouping, include recording files: All video files are listed in a single list
  • Videos - Directories:
    Specify which directories are scanned for video files
  • Videos - Filename extensions:
    Specify which filename extensions are used

Find More:

  • Exclude stop words from 'Find More' search:
    Whether you want to exclude too common words from the search or not. You can edit the list of stop words by clicking the 'Edit...' button. Lists of stop-words in your language are available in the internet, e.g. on
  • Exclude single character words:
    Whether you want to exclude single-character words from the search or not.
  • 'Find More' using cached data:
    Whether to search in the already loaded tv listings data when performing a 'Find More' search or to always search in the database.
  • Automatically append 'Further Showings' information to show details:
    When enabled, the details popup appends the dates of the next shows with the same title on the same channel to indicate possible repeats.
  • Include recordings in 'Find More' search:
    Whether to search through the existing recordings when performing a 'Find More' search or not

External Search:

  • Amazon Locale:
    The localisation information used for the Amazon-Lookup
  • TheMovieDb Language tag:
    The preferred language tag (e.g. 'en-US', 'en-CA', 'es-MX', 'fr-PF') used for TheMovieDb searches
  • TheTVDB Language:
    The primary language used for the TheTVDB-Lookup
  • TheTVDB Data directory:
    The path to the local TVDB cache directory
  • TheTVDB Cache update interval:
    The number of days between updates of the cached information from TheTVDB
  • Always prefer data from TheTVDB if available:
    When enabled, the default description is replaced with the description from TheTVDB if it exists


  • Genres selectable in 'Categories' popup:
    Here you can select all genres that should be selectable by the 'Categories' popup.


  • Recordings Panel:
    When enabled, the plugin displays upcoming recordings inside the 'Now Playing' area.
  • Display duration:
    The time in seconds after which the panel shows the next recording.
  • Recording Soon time:
    Configures the timeframe of the start time recordings to be shown in the panel.
  • Restrict to main menu:
    Whether the panel is only acive inside the main menu or not.


  • Default recording quality:
    Here you can select a recording profile that will be used when doing quick recordings.
  • Font smoothing mode:
    Here you can change the way how the text is displayed by the plugin.
  • Use 'friendly' date formats:
    Whether to use default date formats or some more intuitive ones like 'Tomorrow' or 'Last Sunday'.
  • Wrap around in lists:
    When enabled, pressing the 'Down' key wraps to the first item in recording lists when being at the bottom and the other way around
  • Use default schedule popup:
    Whether to use the default (NPVR built in) schedule popup or the tv listings schedule popup.
  • Confirmations - Confirm 'Delete' of completed recordings:
    When enabled, a confirmation dialog is shown when deleting a recording
  • Confirmations - Confirm 'Cancel' of pending / in progress recordings:
    When enabled, a confirmation dialog is shown when deleting a pending or in-progress recording
  • Confirmations - Confirm 'Remove' of failed recordings:
    When enabled, a confirmation dialog is shown when deleting a failed recording
  • Confirmations - Default button:
    Whether to default to the 'OK' or 'Cancel' button when a confirmation dialog is shown

Skin Configuration

To change the appearance of the TV Listings plugin, a few parameters can be changed in the TV Listings skin.xml file. In the upper section, the following named values can be adjusted:

  • <NamedValue name="ListingsLineAlignment" value="Near"/> :
    Adjusts how the show titles in the grid are aligned vertically. Possible values are Center, Near and Far.
  • <NamedValue name="ListingsRows" value="7"/> :
    Adjusts the number of displayed channel rows in the grid
  • <NamedValue name="ListingsMinutes" value="120"/> :
    Adjusts the timepsan in minutes that is shown on one page
  • <NamedValue name="ScrollMinutes" value="60"/> :
    Adjusts the timepsan in minutes the listings scroll to the left or right per keypress
  • <NamedValue name="ShowNavigation" value="false"/> :
    Whether to show navigation arrows for mouse control or not. Possible values are true and false.
  • <NamedValue name="ShowRecordingStatusColor" value="false"/> :
    Whether to colorize scheduled recordings based on their state or not. Possible values are true and false.
  • <NamedValue name="ShowGenreColor" value="false"/> :
    Whether to colorize programmes based on their genre or not. Possible values are true and false.
  • <NamedValue name="ShowRecordingStatusIcon" value="true"/> :
    Whether to show a status icon for scheduled recordings or not. Possible values are true and false.
  • <NamedValue name="ShowFirstRunStatusIcon" value="true"/> :
    Whether to show a status icon for 'first run' programmes or not. Possible values are true and false.
  • <NamedValue name="ColorizationMode" value="2"/> :
    Controls which mode is used internally when colorizing programmes in the gird. Possible values are 1 and 2.
  • <NamedValue name="ColorizationFlags" value="SkipGrays"/> :
    Controls which areas of the programme images in the grid are colorized. Possible values are Default and SkipGrays.
  • <NamedValue name="ColorizationStrength" value="75"/> :
    Adjusts the strength of the applied colorization in percent (0 - 100).
  • <NamedValue name="ChannelHeaderType" value="1"/> :
    Defines the type of the used channel header. Possible values are 1, 2 and 3.


This plugin is discussed here:




2016-11-21v3.7.2- prevent premature dispose of ui elements in client mode
- also try to lookup images by name with invalid chars replaced by '-'
- limited the auto-inserted number of categories in the popup to 12
- adopted API changes for comaptibility with NextPVR 3.9.2
- aligned recurring recording options to default ones
2014-12-24v3.7.1- added workaround for a potential null reference in the default schedule popup
- added support for "@expanded" / "!@expanded" parameters for dropdown skin elements
- considering "cast_member" and "crew" fields when building the description string for epg events
- fixed an issue where the clicked location was not translated to the correct channel row when there are only few channels in a guide
- added support for choosing 'major.minor' channel numbers for custom guides
- using a channel's formatted number now for the '@number' skin attribute
2013-10-23v3.7.0- added logic to activate listings screen during video playback on F1 key if plugin is configured as default guide
- added changes to TheMovieDB integration to reflect upcoming API changes
- upgraded to .NET 4.0 for NPVR 3.0
2013-03-09v3.6.2- changed TVDB data preference setting to also use images from TVDB in favor of others
- added option to sort 'ready' recordings and groups by last watched date
- fixed an issue where the overlay guide caused a crash when being opened a second time
2012-08-05v3.6.1- added "please wait" message when starting live tv
- added option to initiate 'Archive' procedure on complete recordings
- added option to delete all recordings from a recording group at once (Ctrl+K on the group in TV Recordings)
- adjusted TVDB mapping logic to include a generic series information as fallback in specific situations
- added logic to use the plugin during video playback (available with F9 key)
- added config option for the image directory
- added support for the extra recording directories and 'archive' functionality
- added support to tag/flag recordings with the red, green, yellow and blue keys
- fixed an issue where the 'next' recording in the panel was not really the next one
2012-03-19v3.6.0- added TheMovieDB lookup
- fixed daymask for scheduling manual recurring recordings
- improved startup behaviour of recording panel
- added 'failure reason' for failed scheduled recordings to description string
- fixed an issue regarding start- and endtime calcualtion for manual recordings
- added option to update an existing image in \Media\Shows from the details popup
- using the stock npvr data for genre, audio-/video-descriptions and 'first run' information
- added status indicator image to indicate first-runs inside listings grid (enable/disable in skin file)
- added checkbox-selection of genres for categories popup
- added preview image for selected show details area on tv listings main screen
- taking 'WatchedKickInSeconds' from config.xml in account for playback positions
- fixed an issue where the recording schedule did not get updated automatically
- fetching the complete epg event prior scheduling now
- added logic to invalidate cached programmes after updating an image
- applied timezone corrections to calculation for recording now/next/soon times in panel
2011-11-20v3.5.1- added additional check to recognize external EPG updates
- fixed fallback mechanism for multiple possible images
- fixed opening the default manual recording popup
- changed keymapping to toggle the current guide from Ctrl+Y to Alt+Y (yellow button)
- updated amazon lookup to reflect API changes of the webservice
- added support for the numpad keys to jump to a specific channel in the listings
2011-06-15v3.5.0- added new images and different font for selected programme
- added option to use the default schedule popups (to use advanced rules etc.)
- added option to change the sort order of the guides
- added 'Categories' popup that lists all upcoming shows of a genre
- added logic to move the guide to the current time after playback has stopped
- added support for the inset rectangle
- the panel no longer tries to clear the now playing area when the application exits
- added option to disable the panel on the mvp
- on the mvp, the panel no longer tries to call ForceRender() after updateing the panel
- added logic that wraps the first line of the description when a star-rating image overlaps
2011-02-13v3.4.1- fixed a problem with the next recording panel on the nmt
2011-02-11v3.4.0- fixed last recording date of recording groups being displayed in utc time
- added channel names in conflict popup
- added logic to save an image from the details popup (amazon item or thetvdb episode) to the .\media\shows directory
- added option to exclude/include single character words in find more searches
- removed obsolete 'past days' config setting
- including '-' character in find more searches now
- added support for categories / genres, including display of the genre in the description, genre-based colorization of the programmes in the grid, genre-based 'find more' searches
- fixed an issue where find more results show wrong data of imported recordings
- added logic to detect renamed recording files
- added recordings panel to display upcoming recordings inside the 'now playing' area
2011-01-16v3.3.0- added workaround for the buttonstrip always requesting render updates
- increased width for the timespan in the selected show details ui element
- added option to prefer descriptions from TheTVDB if available
- added quick jump navigation using the first letter of the title in recording lists
- added option to include existing recordings in 'Find More' search
- added alternative keymappings for paging up/down in recording lists
- implemented quick jumps in lists using the number keys to relative positions (0%, 10%, ..., 90%)
2010-12-28v3.2.2- fixed an issue where the plugin tries to access a non-existant directory
2010-12-28v3.2.1- fixed an issue where the plugin tries to access a non-existant language service
2010-12-28v3.2.0- fixed a bug where the what's new list was based on universal time
- fixed a potential threading problem in recordings lists
- added combined skin parameters for recording list items representing 'selected' and 'preview image' state
- included new default skin
- added option to define the channel header type
2010-12-06v3.1.2- fixed an issue where the PCH client identifier was not interpreted correctly
2010-12-04v3.1.1- fixed a bug where images were not loaded from the "Media\Shows" subdirectory
- increased log output when collecting images
- added "@abbrPeriod" parameters for video file items
- when available, "resume" is now prefered against "play" action
2010-11-30v3.1.0- improved performance when rendering tv recordings lists
- added more details for amazon lookups
- fixed recording status colorization for recording states other than pending
- added fallback for tvdb episode lookups where the epsidoe name not matches or is empty
- added confirmation message when cancelling recurring recordings
- added "@abbrPeriod" skin parameter with abbrevations of the day and month names
- added possibility to cancel recurring recordings from the recurring list
- changed TV Listings keymappings: Ctrl+R now moves one page back in listings (previously Ctrl+D), Ctrl+S reloads the listings (previously Ctrl+R)
- changed TV Recordings keymappings: Ctrl+S now sorts the reocrdings in reverse order (previously Ctrl+R)
- improved background image scanning for TV Recordings lists and details popup images
2010-11-13v3.0.2- fixed an issue where the daymask of weekly reucrring recordings was calcualted in utc time
- included xml serializers to avoid assembly generation latency
- fixed a bug where the buttons in the schedule popup didn't respond to mouseclicks
2010-11-12v3.0.1- fixed a bug with a static path to the TVDB cache directory
- increased general log output
- fixed an issue where the recurring recordings list showed utc timeslots
- added logic for better recognition of npvr startup
2010-11-09v3.0.0- initial version for NPVR


Compatibility: NPVR_v3_9

Page last modified on November 21, 2016, at 11:55 AM