BMT User’s Guide 4.9.x for SageTV 7

What is BMT

BMT Terms

Installing BMT

Installing BMT after upgrading from Sage6

Removing BMT

Upgrading BMT

BMT Web Interface

Configuring BMT

Phoenix Fanart/Metadata Options

Image: Regular Expression Editor Dialog

Reset Configuration

Configuration Summary

Using BMT

Browsing Media Files

Updating Metadata for Multiple Items

Updating Metadata for a Single Item

Using the Find Metadata Button

Handling TV Specials

TV Series Information

Manually Adding Fanart

Movie Fanart

TV Fanart

Music Fanart

Genre Fanart

Actor Fanart

Automatic Metadata/Fanart

Forcing BMT to Fetch Metadata Automatically

Checking for Errors

Naming Your Media Files

Forcing a Title Matches

Batch Operations

Searching Views

Using BMT Summary

Showing Fanart in SageTV




Sage Properties

SageTV Settings that affect BMT

What is BMT

See the Everything you wanted to know about BMT document.  If you are new to BMT, then I recommend that you start with that document before continuing with the User Guide.  Please note that BMT 4+ is only compatible with SageTV7.  You can also check out the Quick Start guide if you are looking for something a little shorter to read.

BMT Terms

Metadata - Information that is attached to a media file, including its title, description, rating, release date, etc.

Fanart - Posters, Backgrounds and Banners that are associated with a media file.  While SageTV will show a thumbnail for each item, fanart is different, in that they are typicallly higher resolution images, and they require a plugin to show them within SageTV.

Web Interface - For the purposes of this document, it refers ONLY to the BMT Web UI, and not to be confused with the Nielm’s Web Interface or the Mobile Web Interface.  The terms Web Interface and Web UI are interchangeable.

VFS - Virtual File System.  It abstracts the real filesystem in such a way that other sources of media files can be used, and made to look like they are comming from the filesystem, when in fact they may be comming from another location.  VFS is crucial to the concepts of Views and Folders.

Views - Groups of related media files that are logically organized.  Views may contain media files and media folders.

Folders - Groups of media files.

Batch Operations - Operations that can be performed from the Web Interface that affect multiple media files.

Media Files - Any media resource, such as an image, music, video, DVD, sage recording, etc.  Typically, as it relates to BMT, it refers to mainly TV and Video files.

Metadata Provider - A source for metadata and fanart.  ie, IMDb, TheMovieDB, TheTVDB, DVD Profiler, etc.

STV - SageTV UI that you would see when you are connected to SageTV via an extender, placeshifter, or client.

Plugin, Add-on, Add-in - These all mean the same thing, wich means that it is a user contributed feature added to SageTV, usually via, SageTV’s Plugin Manager.

SAGE_HOME -  The SageTV installation directory.

Folder Path Notions - You may see paths specified as /folder/folder/item.ext and the forward slashes may throw you off, especially if you are a Windows user, but you can simply translate them in your mind to read \folder\folder\item.ext

filesystem, File System - Refers to where you store your files, ie, on Windows it would be C: or D:, for a network share it might be \\myserver\sharename.  The File System is where your physical files are stored.

(#.#.#) - In various places in this guide, you’ll see a label, or sentence, and beside it, you’ll see a number in brackets.  That means that the feature being discussed was added as of the version that is specified in backets, ie, “Help (4.9.4)” means the feature was added in Batch Metadata Tools 4.9.4.

Installing BMT

Please note, that if you are installing BMT after upgrading from Sage6 to Sage7 please see the section, ‘Installing BMT after upgrading from Sage6’, before you continue with this section.

Installing BMT in Sage7 is very easy.  From the SageTV Plugin Manager, select Batch Metadata Tools - Web Interface and install the plugin.  BMT must be installed on the Server and not on a client.  If you are installing it via a placeshifter or an extender then it will install on the Server, as required.

Installing BMT will cause a number of other plugins to be installed as well, including, Jetty (for the web server), Phoenix-API (for Fanart/Metadata), Phoenix-Core (For VFS services), Sagex-API, a bunch of Commons- libraries, Lucene, and some other misc libraries.  If this is a fresh, new installation, then it may take some time downloading and installing the dependencies.

Once BMT is installed, it is recommended that you restart your SageTV server to ensure that it is completely loaded.  SageTV may prompt you to restart, but if it doesn’t then I recommend that you restart the server process anyways.

After you've restarted, you can access the web interface by going to http://localhost:8080/bmt/ provided you are on the same machine as the SageTV server, where BMT is installed.  If you are on another machine then you can access BMT remotely, using the IP address of the SageTV Server, ie, something like this where would be replaced by your Server’s IP Address.

By default, BMT is password protected.  The default username/password is sage/frey.  This is the default password used by Jetty under SageTV.  For information on how to change the Jetty Username and Password, consult the Jetty documentation.

Installing BMT after upgrading from Sage6

SageTV6 did not have the concept of plugins, at least not in the same way as SageTV7.  For this reason, SageTV cannot automatically upgrade BMT from Sage6 to BMT in Sage7.  And, to make matters worse, the libraries for BMT (and a few other plugins) are different in Sage7, and as such, if you simply install BMT from the Plugin Manager after upgrading, then it will fail.

Fortunately, I’ve created a small tool that helps with the transition.  You can grab the tool from the SageTV forum.  Basically what this tool does, is prepare your system to be able to accept BMT from the SageTV Plugin Manager.  This tool removes the BMT libraries from your system, so that BMT can be installed using the Plugin Manager.

After you have run this tool, you can follow the instructions in the previous section on installing BMT.

Removing BMT

You may find that BMT is not to your liking.  That is unfortunate, but understandable as well.  To completely remove BMT, you must also remove all of its dependencies, and the dependencies must be uninstalled in the correct order.

The Following Plugins/Dependendencies must be removed.

If you get an error trying to remove phoenix-core or phoenix-api it is probably because other plugins are using those services, and so they cannot be removed, until those other plugins are removed.

If you’ve removed phoenix-api (which means that no other plugins is using it), then you can completely remove any residual files from the SageTV installation.  These directories include

Once you completely remove BMT, you can restart the SageTV server, to ensure that it gets unloaded from memory.

Upgrading BMT

The SageTV plugin manager will let you know via System Messages when there is an update, or you can manually check for updates using Sage’s Plugin Manager from within the SageTV application.  If there is an update, then you can choose to install it.  Once the upgrade is complete, you’ll need to restart the SageTV server for the new plugin to take effect.  SageTV will prompt for a restart, and you should restart as soon as possible.  If you restart and Batch Metadata Tools shows that it failed, then you can try restarting one more time.  There have been the odd occasion where during the instalation, the Plugin has failed to install properly, but forcing SageTV to restart, usually fixes that issue.

BMT Web Interface

Your first interaction with BMT, will be the Web Interface, so it’s important to know about about the main toolbar in that application.

The BMT Toolbar contains 5 options to the right of the application title, including, Status, Configure, Browse, Tools, and Refresh.

The space immediately below the toolbar is an empty white bar.  From time to time messages will appear in there, either in blue or red.  Blue messages are just information messages, and Red messages are warnings or errors.  Messages will disappear after about 2 seconds, so read quickly :)

Configuring BMT

When BMT is installed, by default, the settings are set to the most common settings, which a fine for most people.  It is recommended that you at least familiarize yourself with the settings, so that you know what can be configured.

You can change most configuration settings either from the web interface or from the Plugin Manager.  For the purposes of this document, I’ll assume you are using the web interface.

To begin configuring BMT, go to Configure -> Phoenix -> Fanart Metadata Options, and your browser should look something like the image below.

There are a number of things to notice about this panel.  First, there is a lot of information contained in this section, and finding the settings buried in there can be tricky.  Something that is often overlooked is the Search box in the upper left corner.  This search is a simple text search that will search configuration labels, and descriptions for the text that you enter.  For example, if you were looking for a particular setting, you could search for it there.

Directly below the Search is a Tree View of all of the configuration nodes.  The top level nodes should be

Something to note about the configuration screen is that most, if not all, configuration options, (the right hand panel) have a blue question mark icon beside the label.  This a context help for that particular field.  In many cases it may not have much information, but in other cases it might.  You should always check the help, if you are unsure about a field, just in case there is something useful in there :)  One useful piece of information in the help dialog for a field is the actual property name that is being configured.  The configuration panel only shows the labels, but when you click on the blue help icon, the dialog that shows, will contain the property key, which is most likely the property key in the file.  The following dialogs show the help for the Automatic Fanart/Metadata configuration option.

Phoenix Fanart/Metadata Options

There are many panels in the configuration, and we won’t cover them all, but for the most part, this panel is the most important configuration panel for BMT.  It is from here that you can configure what types of files to be scanned by the automatic plugin, files to ignore, or even whether or not you want the automatic plugin to run at all.  Many of these options are advanced options, and I’ll only cover them briefly, since most people will only care about a select few.

To configure the Fanart/Metadata Options go to Configure -> Phoenix -> Fanart/Metadata Options, and you should see the screen that was shown in the previous section.

The options for this section include

Ignore Words in Title

This is a comma separated list of words that are automatically removed from a title before it is sent to a metadata provider for lookup.  You probably don’t need to edit this field.

TV Metadata Providers

A comma separated list of TV Providers that are used for metadata and fanart.  Supported IDs include

  • tvdb - The TVDB

Movie Metadata Providers

A comma separated list ov Movie Metadata providers that are used for fanart and metadata.  If more than one is listed, then they are tried in that order, until a successful match it made.  So, if you have imdb,tmdb in the list, but a match is found using imdb, then tmdb is never used.  Supported IDs include

  • imdb -
  • tmdb -
  • imdb.xml - another Xbmc based scraper that uses imdb and themoviedb
  • dvdprofiler - Uses a collection.xml exported from DVD Profiler (This provider requires extra configuration in the DVD Profiler configuration section)

You should know that when you use imdb then is used as the metadata source, but fanart is automatically pulled down from, provided that fanart is enabled.

Good Score Threshold

Since Movies and TV are looked up by Title, you may not always get a 100% match on the title.  This field is a decimal number between 0 and 1 that represents your tolerance for errors.  1 being no tolerance and that you require an exact title match all the time.  As you decrease the number you allow for some “closer” matches that can count as exact matches.

For example if the value was set to 1, then a search for “Dr. DoLittle” would not match “Dr Do Little”, but with the value set to .9, then even if the titles don’t match 100%, we use some fuzzy logic to score how closely the titles match, and if they match close enough, then we consider it a hit.  

Typically you’ll never need to adjust this value.  But if you are noticing way to many false hits, then you can increase the number closer to 1.

Score Alternate Titles

Some searches may return more than one title for a movie.  If this is checked, then those other titles are checked against the search query as well.  Alternate titles may include titles in other languages.

Scale Poster width

A poster when downloaded will be rescaled proportionally to this width.  Use -1 to indicate no scaling.

Scale Banner width

A Banner, when downloaded will be rescaled proportionally to this width.  Use -1 to indicate no scaling.

Scale Background width

A background, when downloaded will be rescaled proportionally to this width.  Use -1 to indicate no scaling.

Max Images to download

This the maximum number of images to download, per category (poster, background, and banner).  So, if there are 10 posters, and this is set to 3, then only 3 posters will downloaded, including only 3 banners and only 3 backgrounds.

Fanart Enabled

Chances are you’ll always leave this enabled.  If you uncheck it, then fanart will be disabled.

Central Fanart Folder

This is the directory were ALL fanart will be stored.   By default all fanart is stored under SAGE_HOME/STVs/Phoenix/Fanart/ but you can change this to be any valid path you want, including a network share.  If you have existing fanart in the STVs/Phoenix/Fanart area, then you can simply move that to the new location.  Changing this field does not move the fanart for you, you’ll have to do that manually.

Automatic Fanart/Metadata

This is perhaps the main reason to use BMT, which is for automatic fanart and metadata when new files are added to your SageTV library.  

Once you install BMT, it will immediately begin waiting for new media files, and when they are added, BMT will use the appropriate metadata provider (TV or Movies) and attempt to automatically lookup the metadata and fanart for the item.  

NOTE: BMT does not automatically scan existing files, only new files added since you installed BMT.  Also, BMT relies on SageTV to notify it about new files, which is done either when SageTV checks for new media files or when you hit the Refresh action on the main BMT web toolbar.

Use System Messages for Failed Lookups

When items that handled by the automatic plugin fail, then System Messages is how you get notified. If you find the messages to be annoying, then simply turn this off.

Preserve Original Metadata for Recordings

One of the Media Types that BMT handles is Sage Recordings.  Because a recording originated from within SageTV then it will most likely have some metadata, such as description, original air date, etc.  With this checked, then bmt will not overwrite the metadata that SageTV provided, but it will still augment the metadata with additional details such as genres, user ratings, etc.  If you uncheck, then the SageTV metadata will be replaced with the TVDB metadata.

Note that files that you have imported as recordings will not be affected by this setting.  This setting only applies to recordings that originated from within SageTV.  (4.9.5)

Import TV Media Types as Recordings

If you like to manage ALL your TV files in the Sage Recording screen, then you can choose to import TV files (ie, files you recorded elsewhere), into the Sage Recordings, so that they appear along side of the other native sage recordings.

Archive imported Recordings

In many cases, you don’t want the imported recordings (see previous setting) to show up in the Recordings menu, but rather in the Archived Recordings menu.  With this checked, then imported Recordings automatically become archived.

Prefix Videos with Relative Path

SageTV documents that non-recordings show include the relative path of the media file in the media file title field.  With this checked, then non recordings that are handled by BMT will automatically get prefixed with their relative path.  By default it is disabled (contrary to Sage documentation) since it causes TV files that are not recordings to have a relative path in their Titles, which is not ideal.  So, if you want relative paths in your Titles, then turn this on.

Media Types

This is a comma separated list of media types that you want the automatic plugin to handle.  The valid types are

  • ANY_VIDEO - Any Video File (Movie, TV, Recording, etc)
  • TV - Any TV File
  • RECORDING - A TV file that is also a Sage Recording (Not all TV Files are Recordings)
  • DVD
  • HD - HD Video/TV/Recording File
  • VIDEO - Video file by not TV

Exclude Pattern

This is a Regular Expression that you want to use to exclude from the automatic plugin.

When you enter this using the Regular Expression editor (see image below), you’ll see 3 fields.  The first field in the regular expression that you are creating.  The second field below it, is a place for you to enter some dummy data on which you can test the regular expression, and finally the last field in the output field, or the results of the regular expression test.

Regular expression can be quite powerful, but they can be problematic as well, which is why BMT provides this Regex Editor/Test dialog.

Initially all 3 fields are empty in the dialog, but you must enter the regular expression and some test data, and then click test.  In the test data, you should enter data that you think will match the expression and some data that you think will not.  Then when you click test, you should see the items from the test field that matched your regular expression.

If you are in windows, and you are entering full paths or partial paths, then note that you must use a \\ to represent a single \.  So if you were ignoring \\Vidoes\Home, then you would enter that as \\\\Videos\\Home.

In regular expressions you can separate entries using a pipe | to add more items to exclude.  For example, if you needed exclude \\Videos\Home or \\Vidoes\Test, then you can enter that as \\\\Videos\Home|\\Videos\Test

For a complete Reference on the Java Regular Expression, you can check out this resource.

Remember, always use the regular expression dialog with test data and verify the data before you save your regular expression.  A malformed regular expression can cause all sort of headaches.

Image: Regular Expression Editor Dialog

Reset Configuration

There is no easy way to reset the configuration, once you have made changes.  Even if you remove the plugin and re-install, then the configuration options will remain, since they are stored in the  But, if you do need to completely reset the configuration, then you can shut down the sage server, and edit the directly.  In an editor, search and remove all keys that start with phoenix/ and bmt/.  Now, when you restart SageTV the configuration will be reset to it’s original values.

Configuration Summary

Using BMT

The main purpose of using BMT in the web interface is to find and/or fix metadata, and in this

section I’ll deal with some of the most common cases.

Browsing Media Files

Most, if not all your of you interaction will be in the Browse panel.  When you select Browse from the main menu, then you are presented with a list of Views.  A View is a grouped set of media files that are logically grouped together.  Some of the more common views are

When you browse a view, the right side pane will fill with a button bar and a list of media files.  The button bar, above the media files, contains a few actions that can be performed on the current view and its sub folders, these include

There 2 types of items that will show up as view items; Media Files, and Folders.  When you see a folder, you can click it to see it’s children.  If you see a media file, then you can click it and it will bring you to metadata editor for that media file.  We’ll discuss more about the metadata editor later.  One thing that you’ll see on a media file is a blue sprocket in the bottom right hand corner of the media file.  You can ignore this, for the most part.  When you click it, it gives you a “debug” view of the metadata for that item.  It really only has value to people that are working with metadata, and you need to compare how BMT has stored the metadata.

Updating Metadata for Multiple Items

As mentioned before, when you Browse views, then an Update Metadata button is available.  One common place where you will want to update metadata for multiple items is in the Missing Metadata view.  So, if you go there, and click Update Metadata, you’ll see a dialog with 2 options

Scan Sub Folders (4.9.5)

If checked, this will scan all items in the current view, and all sub folders of that view.

Update Fanart (4.9.5)

If checked, then fanart will be downloaded.  If you don’t want fanart, but just the metadata, then uncheck this option.

Update Metadata (4.9.5)

If checked, the metadata will be fetched and updated.  Typically you’ll want this checked always.  If you uncheck this, then only fanart is downloaded.  With this unchecked, but fanart checked, then some custom metadata fields are still updated, but core SageTV fields are not touched.

Only Update Items that have not been updated previously

When this is checked, the ONLY files that are missing metadata will be updated.  In our case, since we are in the Missing Metadata view, then all files will be updated, but if you were in another view, where some files were already updated, then those files would not be updated again.  But, if you navigate to a view or folder, and then uncheck this value, then ALL files will be updated, no matter if they have metadata or not.  You’d only want to do this if the metadata was incorrect.

Import TV Files as Recordings

If you want TV media files to show up as recordings within SageTV, then this option should be checked.  By default this option is not checked, which means that media files that also TV shows will simply show up in the video library, just like regular imported videos.

The biggest reason, in my mind, to enable this option, is so that when you import a group of TV files, you see all of your TV files in the same location as your recorded shows.

When you are ready to scan, you can click the Scan button.  When you scan a group of files, it is important to know that you are scanning ALL media files for the current folder AND any children of that folder, including sub folders.  Even if the view/folder has not loaded all of it’s media files (ie, there is a Load More button), the scan will scan ALL files.  Note that ONLY the files that are not excluded by the global exclude filter will be scanned.  So while a view may contain some files, such as home videos, that you have excluded from being scanned, then a scan from the web interface will not scan those files either.

Once a scan is started, then a new a entry is added to the left hand side View panel.  It has a header of Scans, and any scans that are currently running, or have run in the past (since you’ve restarted SageTV) show up there.  When you click on a Scan item, you’ll get information about that scan.

The scan information contains the following information


This is the name of the Scan, which is typically just the name of the view or folder that you were on, when you started the scan.

Scan Date/Time

The Date/Time the scan was started

Total Success

How many items were successfully scanned and as a result now have new metadata and fanart.

Something that is not well known, is that if you click on the # (not the label), then it will open a new View of those items.

Total Failed

How many items failed to get updated fanart/metadata.

If you click on the # (not the label), then it will open a new View of just those items.

Is Done

If the scan is complete then this will be true.  If the scan is still in progress, then this will false.

Was Cancelled

One of the options for a Scan item in the Scans view is to Cancel it.  If you click cancel on a scan that is in progress, then this will indicated that the scan was cancelled, as opposed to a scan that as run its course normally.

If you have a number of scans in your Scans View, then you can remove them using the Remove link on the scan.  If you remove a scan that is in progress, then that scan will be canceled as well.

Updating Metadata for a Single Item

When you are Browsing a View or Folder, and you click on a media item, then it will automatically open the Metadata editor for that media file.

There is a lot of information in this view.  First, notice that the button bar has 3 options

If you make changes to the data, then that information is not saved until you press the Save button.

Here is a list of the information that can be modified in the metadata editor.

Sage Recording?

This is checkbox that indicates if this is either a Sage Recording, or, if it’s unchecked, and you check it, then you will import this file in as a Sage Recording when Save is clicked.

Likewise, if the value is checked, so that it is a sage recording, and you uncheck it, then the file will be removed from the Recordings and end up in the Video library as a normal video file.

Note, whether you import as a recording or remove as a recording, the physical file is not moved, just the metadata that indicates that it is a recording is updated.

Media Type

This is the Fanart Media Type, which currently only supports TV or Movie.  

A TV Media Types does not mean that it is a Sage Recording, but rather, it just means that the data should be treated as TV data, which means, that it includes Season and Episode information.

Fanart Title

Fanart Title, also called, Media Title, is the Title that Phoenix will use when it tries to resolve fanart for a media file.  Normally, this will always be the same as the Show Title, but it does not have to be.

Movie Title

This is the Title of the Movie

(Only visible when Media Type is Movie)

Show Title

This the Series Title for a TV Show

(Only visible when Media Type is TV)

Episode Name

This is the Episode Title for a TV Show

(Only visible when Media Type is TV)

Season #

The Season # as indicated in TVDB.  0 is not supported.

(Only visible when Media Type is TV)

Episode #

The Episode # as indicated in TVDB

(Only visible when Media Type is TV)


This is the description or overview for the Movie or TV Show episode

Genres (Comma Separated) (4.9.5)

The genres or categories to which this media file belongs.   You can specify multiple genres by separating them by commas.


The Year of the Movie or TV episode

Original Air Date

The date that the Movie or TV episode first aired.  Must be in the format YYYY-MM-DD.

MPAA Rating (4.9.5)

SageTV MPAA Rating for the Movie.


G, PG, PG-13, R, NC-17, AO and NR (AO is adults only and NR is not rated)

If an invalid rating is specified then NR will be used.

Parental Rating

SageTV Partental Rating for the TV episode.



If an invalid rating is specified the TVM will be used.

Extending Ratings

Any additional parantal rating information, such as, “May contains scenes of nudity”, etc.

User Rating

A Numeric value between 0 and 100, indicating the user rating of this Movie or TV Episode at the time the metadata was fetched.  You can obviously set this to be your own personal user rating for the item.

Running Time

The length of this media item in milliseconds.  Sometimes this value is 0, for whatever reason.  So, I wouldn’t put much faith in this value.  If you are manually updating this field, then here are some common values.

  • 1800000 - 30 Mins
  • 3600000 - 1 hr
  • 5400000 - 1.5 hrs
  • 7200000 - 2 hrs
  • 9000000 - 2.5 hrs


This field can contain anything you want.  It has no format, and any information you put in here will simply be stored.  SageTV will show this information in the default STV, and other plugins may show it as well.

External ID

This is ‘external’ id from SageTVs point of view, which usually maps to a Zap2It id.  While you can change this ID, it is recommended that you do not change it, unless you absolutely know what you are doing.  BMT changes this from time to time when it needs to import a show as a recordings or remove a show from the recordings.  Other than that, it is rarely changed.

Some notes about this field.

  • If the field has ‘mt’ as the 3rd and 4th characters, then it means that BMT has modified the field.  ie, EPmt164951S01E01 would an external ID that BMT has calculated, and it can be broken down to mean this. EP means it’s a Sage Recording.  mt is short for ‘metadata tools’. The number, 164951 is the tvdb Series Id, and the S01E01 is the Season and Episode information.  Other plugins may edit this field, and doing so, can cause some side effects, so if you ever want to know if BMT imported a file as a Recording, check this field.
  • Other prefixes for this field include ‘MV’ which means that it’s a Movie in the Sage Recordings, and MF which means it’s a regular Media File.  (There are other pefixes as well)


This is only enabled when the media file is a Sage Recording, and it means that it’s an Archived Recording.


You can change the watched status on the media file using this check box.

To the right of the main metadata, there is also a list of Cast Members.  You can click on a cast member to edit the data, but at this time, you cannot add or remove cast members.

As was mentioned, there is a lot of editable metadata in this section, but in addition to the editable metadata, this panel contains some other useful information.  This information includes


This is the ID of this media file on IMDB

Metadata Id

This is the metadata id of this item as it is known by the metadata provider that fetched its metadata.  So, if TVDB fetched this data, then it will be the TVDB id for the show, but if themoviedb fetched the information, then it will be id of the movie on

Sage MediaFile Id

This is Sage’s ID for this item

Sage Airing Id

This is the Sage Airing id for this item.

Sage Show Id

This is the Sage Show Id for this item.

Sage Series Info Id

This the Sage Series Info ID (ie Series Overview).  If this series overview was added by BMT (ie, it did not originally exist in the SageTV database), then this number will start with 2 and it will be a very large number, ie, something like, 200164951.  The format of this number will include the TVDB series id wrapped inside this number.  You can use this information to determine if the Series Information attached to this item was added by BMT, or if it is attached to an existing Sage Series Information.


This is the id that is used by the VFS to unique identify this item in it’s view folder.


This is the physical location of this media item on the filesystem.

Fanart Location

This is the physical location of where fanart would be stored for this item.  This is perhaps the most interesting of the non editable fields, since using this information, you can deploy your own fanart to this location.  Even though this location is shown, it doesn’t mean that there is fanart in that location, but if there was fanart, then this is the location where you can find it.

Using the Find Metadata Button

Being able to manually edit and update the metadata is fine, if all you need to do is edit a single field, and then click save, but more often, when you are go into the metadata editor, you have no metadata or fanart at all, and you want to quickly update the item.  For this, you can use the Find Metadata button in the button bar above the editable metadata.  When you click the Find Metadata button a dialog appears that enables to you enter some information about the item

The search options dialog will be different depending on whether or not you are searching for a TV show or a Movie.  For a Movie you’ll just have Search Type, Source, Search Title, and Year, but for TV, you’ll also have Episode Title, Season Number, Episode Number and Aired Date.

Sometimes when you go into this dialog, you will have very little information displayed, so it’s always a good to hit the Discover Defaults button, which will parse information from the media and attempt to fill in the defaults.  This would be the same process that the automatic scanner uses as well, so you’ll be able to see how the automatic scanner would have parsed the information about your file.

Only fill in the fields that you want to use for the scan.  For example if Season and Episode have 0 in their fields, then those values would be used for the scan, and as a result the scan would fail.  So blank any fields that you do not want, before clicking Search.

The search options include

Search Type

This is the same as the Media Type from the previous panel.  It will include TV or Movie.


This is the metadata provider that you want to use to do the lookup.

Search Title

The title that is passed to the provider to find.  You should make sure this is cleaned up to not include any characters that would cause issues for the provider.  ie, If after you use Discover Defaults, the title is “The.Terminator”, you should fix it so that it says, “The Terminator”.  Metadata providers can be very picky about their searches, so the cleaner the data you send, the better the odds of getting a match.


Year is optional, but you can add it in, especially if you are searching for a re-make of a TV show or movie for a specific year.

Episode Title

If you are doing a TV episode lookup, you can either fill in the episode title OR the season and episode fields.  If you are going to do your search based on the episode title, then fill in this field.


If you know the season number, then enter it here.


If you know the episode number, then enter it here.  Keep in mind this is the episode number as it appears on tvdb, if you are using the tvdb metadata provider.

Aired Date (4.9.5)

If you know the exact date that the episode was aired on, then you can enter it here.  The date must be in the format YYYY-MM-DD.

If you are using Aired Date, then you do not need to fill in Season, Episode, or Episode Title.

Once you are satisfied with the search data, click Search and you’ll get a list of search results of either TV Series or Movies.  Click your TV Series or Movie from the returned list, and BMT will fetch the metadata.  In the case of TV lookups, you may get a Failed lookup after you select the TV series, because the specific episode matching is not done until after you select the Series.  If this happens, then refine your episode numbers or episode title and try again.

Handling TV Specials

There isn’t much to say here, except that BMT does not yet handle TV specials.  It is something that is being looked at, but there is no timing on when such a feature would arrive.

TV Series Information

When BMT does a TV episode search, it will automatically assign that TV episode to an existing TV Series Overview within SageTV.  But, if BMT cannot find an existing TV Series Overview within SageTV, then it will add a new TV Series Overview with the Series Overview information, and add that to SageTV.

Manually Adding Fanart

As mentioned, BMT uses the Phoenix Fanart format for storing fanart.  Phoenix uses a folder based layout for fanart that is in a separate location from the media files.  This folder is call the Central Fanart Folder, and by default, unless you configure it, it will be located in SAGE_HOME/STVs/Phoenix/Fanart/.

Some highlights about the Phoenix Fanart model

To manually add your own fanart, you’ll need understand how Phoenix stores fanart on the filesystem.

At the top level of the fanart folder, there will be any of the following folder names.  Note, your fanart folder may only have somes of these folders, and that’s OK.

I’ll take each fanart group separately, since the format differs depending on if you are working with TV fanart or Movie fanart.

Movie Fanart

In the Movie folder will contain a separate folder for each movie that has fanart.  The name of that folder may be the same of the movie title, but in some cases, the folder name will be different.  That is because some movie titles contain characters that are not valid for a filesystem.  As a rule of thumb, the following characters are removed from a Title; \/:*?\"<>|.

A quick way to determine the location for the fanart is to find the item in the Web Interface, and then check the Fanart Location field.  This will be a complete path to where fanart should be stored.

Under the movie title folder, may include 2 other folders; Posters and Backgrounds.

The Posters and Backgrounds may contain multiple image files representing multiple Posters and Backgrounds respectively.  The names of the image files do not matter.

Here are some example file locations

Background for the movie 10,000 BC

Movies/10,000 BC/Backgrounds/tt0443649.jpg

Movies/10,000 BC/Posters/tt0443649.jpg

TV Fanart

TV Fanart is probably the most complex of the fanart structures.  TV Fanart, like the movie fanart,  starts out with the Series Title, and under there, you can have series specific fanart for Backgrounds, Posters, and Banners.  But, in addition to series level fanart, you can have season specific fanart as well.  In the Series Title folder, you can have a Season ## folder for each season, such as ‘Season 01’, ‘Seaons 02’, etc.  And then within the Season folder, you can fanart for Posters, Banners, Backgrounds, and Episodes.

Posters, Banners, and Backgrounds are like normal fanart folders, where you have multiple images per folder, than can be named anything you like.  But, the Episodes folder is a little different.  When you provide Episode level fanart, you are providing a fanart image for a single episode, and that image has to be named the same as episode number, but with leading zeros.  The total length of the episode number is 5 digits.  So, episode fanart for episode number 121 would look like, 00121.jpg.

Here are some example file locations for TV Fanart

Series Posters for House



Series Backgrounds for House



Series Banners for House



Season Backgrounds for House, Season 1

TV/House/Seaon 01/Backgrounds/house.jpg

TV/House/Seaon 01/Backgrounds/house2.jpg

Season Backgrounds for House, Season 1

TV/House/Seaon 01/Backgrounds/house.jpg

TV/House/Seaon 01/Backgrounds/house2.jpg

Episode Fanart for House, Season 1

TV/House/Seaon 01/Episodes/00001.jpg

TV/House/Seaon 01/Episodes/00002.jpg

TV/House/Seaon 01/Episodes/00003.jpg

Music Fanart

Music fart is not yet supported

Genre Fanart

Genre fanart is found at the same level as TV and Movie fanart.  Within the Genres folder, there will be a folder for each Genre, and within that folder, you can have multiple genre images.

Example Genre level fanart paths





Actor Fanart

Like Genre fanart, Actor fanart is also at the same level as TV and Movies.  You create a folder the same name as the actor under the Actors folder and in there you can put multiple images.

Example Actor fanart

Actors/Hugh Laurie/huge1.jpg

Actors/Hugh Laurie/huge2.jpg

Actors/Bruce Willis/b.jpg

Automatic Metadata/Fanart

While being able to manually go in an fix metadata, and manually add metadata is nice, nothing beats the fact that most of the time, you’ll never need to use those features.  When you install BMT, it will by default, begin listening for new media files, and when new files are added, then it will automatically try to fetch metadata and fanart for those items.  This works for Movies, DVDs, BluRays, and Recordings.

It’s important to note that even though BMT does do automatic fanart and metadata lookups, it will not fetch metadata and fanart for items that are already in your SageTV library at the time that the plugin is installed.  To update those, either manually, or automatically, you’ll need to use the Web Interface.

Forcing BMT to Fetch Metadata Automatically

BMT does not sit around polling for new media files, instead, it relies on SageTV to notify it when new files are added.  This includes new recordings, as well as new media files, such as movies, that you may have ripped and are now adding to SageTV.  SageTV, itself, does not immediately see new files, but rather it checks every couple of hours (configurable via the detailed setup menu in SageTV).  So, if you add some new files to SageTV, and you are not seeing them show up withing SageTV, it’s because SageTV hasn’t scanned them yet, and as a result SageTV hasn’t notified BMT that they have been added.  You can, however, force SageTV to check for new files immediately.  You can do this using the Refresh link on the BMT’s Web Interface toolbar.  When you click that link, it sends a message to SageTV to look for new files, and and in turn, BMT gets notified about those files, and attempts to locate fanart and metadata.

Checking for Errors

Since the Automatic updater runs in the background, it’s hard to tell if it’s working, especially if you are not seeing any metadata and fanart showing up.  BMT will, by default, add a System Message for any failed updates, but if you’ve turned that off, then the only want to tell if things are working is to manually check.

The first place to look to see if BMT is handling your files automatically is in the SAGE_HOME/logs/phoenix-metadata.log file.  This is a condensed log that contains an entry for every file that BMT handles, and it will report either an update or failure on the item.  

A typical log entry looks like this (color was added by me to help separate the parts, the actual log contains no color)...

2010-12-05 20:15:30,575 - ERROR; DecoratedItem: [SageMediaFile [sageId=513318, sageObject=MediaFile[id=513318 A[513345,513319,"",0@0401.20:23,89] mask=V host=sean-desktop encodedBy= format=AVI 1:29:13 1096 kbps [#0 Video[MPEG4-Video 23.98 fps 640x352 20:11 progressive]#1 Audio[MP3 48000 Hz 2 channels 128 kbps idx=1]{SeriesInfoID=0, UserRating=0, DiscNumber=0, EpisodeNumber=0, SeasonNumber=0}] /home/sean/BETA/Movies/Movies/DummyRecording.avi, Seg0[Thu 4/1 20:23:39.990-Thu 4/1 21:52:53.000]]]]; Class: sagex.phoenix.vfs.views.ViewItem; >>> Sage Object[MediaFile[id=513318 A[513345,513319,"",0@0401.20:23,89] mask=V host=sean-desktop encodedBy= format=AVI 1:29:13 1096 kbps [#0 Video[MPEG4-Video 23.98 fps 640x352 20:11 progressive]#1 Audio[MP3 48000 Hz 2 channels 128 kbps idx=1]{SeriesInfoID=0, UserRating=0, DiscNumber=0, EpisodeNumber=0, SeasonNumber=0}] /home/sean/BETA/Movies/Movies/DummyRecording.avi, Seg0[Thu 4/1 20:23:39.990-Thu 4/1 21:52:53.000]], Class: sage.b3]; Failed to get Metadata from the list of results

Now, this can be intimidating, at first, especially if you have no idea what you are looking at.  Hopefully, I can break it down, so that you can recognize imports parts of that log message.

Typically, when you see a message like, “Failed to get Metadata from the list of results”, it means that while the search happened, bmt could not find a good match for your title against what was returned in the search query for the metadata provider.  For example, if it was handling a TV file, then perhaps it did not find a valid season number and episode number in the filename.  Or, for a movie, perhaps the title of the movie in the filename was spelled incorrectly.

Naming Your Media Files

BMT provides filename scrapers for several formats, and it can handle some wildly named files, but to really ensure that you get better results, naming your files to something that you know BMT will process well, can make a huge difference.

Here is a list of the filename scrapers that BMT currently supports

Title with Year

This is basic Movie scraper and it looks for filenames that have a Title and year, in the format “TITLE (YEAR).ext”


The Terminator (1998).avi

Sherlock Holmes (2010).avi

Sherlock Holmes (2010) - DVDRip.avi

Having a year in your Movie title will help BMT choose the best match, especially in the cases where you have the same movie that has been remade over several years.  ie, a title like “King Kong” may match several items, but “King Kong (1933)” will only try to find King Kong that was aired in 1933.

You can put any text, after the year, and it will not affect the scan.  ie, something like,

The Terminator (1998) - Director’s Cut.avi

Series SeasonxEpisode

This is used to match TV shows in the format “SeriesName SeasonxEpisode.ext”, where Season and Episode are the numeric Season and Episode numbers.


House 01x02.avi

House - 01x04.avi

House - 01x05 - Episode Title.avi

Series S##E##

This is used to match TV shows in the format “SeriesName S##E##.ext”


House s01e01.avi

House - S01E01 - Episode Title.avi

Lie to Me s02e03.avi

Lie to Me - s01e01 - Pilot Episode.avi

Series -- EpisodeTitle

This is used to match TV shows, in the event that you do not know the specific Season and Episode values, but you do know the Episode Title.  The Series and Episode must be separated by 2 dashes.


House -- Random Episode.avi

Lie to Me -- Pilot.avi

Series AiredDate

This used to match a TV show based on it’s original aired date.  The date must be in the format YYY-MM-DD.


House 2010-11-22.avi

Lie to Me 2008-01-15.avi

While this can be used to locate “specials”, BMT will still refuse to find the special, since the Season number and/or the Episode number will be invalid.


This is a SageTV recording format that includes the Series name and the Episode title.  BMT will do a compressed search on the episode titles to match the sage Episode title.




This is another SageTV recording format that only contains the Series name and NOT the episode title.  In this case BMT will do a lookup using the original aired date of the file.



If BMT can’t use one of those filename scrapers to parse out the information on which to search, it will still try its best to do a search.  First, it will assume it’s a Movie search, and it will attempt to clean out the filename by removing non alphanumeric characters, and it will then to try to strip out words like, ‘dvdrip’ or ‘720p’.  Whatever is left is what  BMT will use as the search.  So, you can imagine that this is a last resort effort by BMT to find metadata and fanart.  How successful will depend on how badly named the original file was.  

Examples of files that might work



Forcing a Title Matches

There are times, especially for TV shows, where you have your files named in such a way, that BMT is not able to find any matches.  You don’t want to rename all your files, and luckily, BMT provides a facility, albeit manual, to map filepath/filename patterns to something that be meaninful.

For example, if your files are called,

Dora - S01E01.avi and Dora - S01E02.avi, then BMT may not find a match, since the name of the show is really called Dora The Explorer.  But, you can map Dora to Dora the Explorer in a file called MediaTitles.xml.  This file must be located in the SAGE_HOME/userdata/Phoenix/scrapers/ directory.  If you add/edit the MediaTitles.xml, then sagetv will need to be restarted, or you’ll need to reload the xml using Configure -> Refresh Configurations -> Refresh MediaTitles.xml from the BMT Web UI.

To map Dora to Dora the Explorer, you would manually add an entry to that file, that looks like this.


                <regex>[\\/]Dora </regex>

                <title>Dora The Explorer</title>


Now whenever BMT encounters a filename that starts with “Dora “, then it will set the Title of that media file to Dora The Explorer.  Then the searcher will use the title, “Dora The Explorer” instead of “Dora” when doing a the lookup.  BMT uses regular expressions to match a portion of the file path to the <regex> element, and if the match is good, then it will then set the title of that file to the <title> element.  Regular expressions can be complicated, but in the example expression, [\\/] is a platform independent way of saying match either the \ or the / in a path.  This way a file like, “TV\Dora - S01E01.avi” in windows or “TV/Dora - S01E01.avi” in Linux/Mac would match.  

When BMT uses the MediaTitles, it will test the ENTIRE path of the media file against the regular expression that is provided, and the regular expression behaves like a contains search on the path.  So, it is not just testing the filename, but rather the file path, including the parent directories, etc.  This is handy to know because another case may be that you want to force every thing that is in a folder called “TwiZone” to use the “Twilight Zone”.



                <metadata type="tv" name="tvdb">73587</metadata>


You might notice that in this case, instead of using a <title> element, I’ve used a <metadata> element and I’ve given it the metadata provider, tvdb, and the series id on tvdb for the original Twilight Zone series from 1959, which has a series id of 73587.  So, in this example, I’m forcing everything that has /TwiZone/ or \TwiZone\ in it’s path to use tvdb series id 73587.

Keep in mind that MediaTitles are used when searching, so the titles that you specify, if any, are used during searching, but the title that the media file will finally get will be determined by the data returned in the search results.

MediaTitles.xml can be handy, at times, when you need to force a large group of files to use a particular series id based on the fact that they all share a common folder.

One the most common uses for MediaTitles is to map SageTV recordings to a specific TVDB id.   Sage Recordings usually follows the format, “SeriesName-EpisodeName-AiringID-Number.ts”.  So knowning this, we only ever want to match against the “SeriesName”, for a typical MediaTitles entry for a Sage Recording looks like this...



        <title>Hawaii Five-0</title>


        <metadata type="tv" name="tvdb">164541</metadata>


Note that the in this case because we are using the <metadata> element to force an exact series id lookup, then the <title> and <year> are simply there for user information and they are not actually used in the search, since they are not needed.

Pay special attention to the <regex>, [\\/]HawaiiFive0-.*, since it matches all filenames that starts with HawaiiFive0-, which is how the SageTV recording would look for those items.

Complete MediaTitles.xml sample






        <metadata type="tv" name="tvdb">83462</metadata>






        <metadata type="tv" name="tvdb">94551</metadata>




        <title>The Good Guys</title>


        <metadata type="tv" name="tvdb">140101</metadata>




        <title>The Defenders</title>


        <metadata type="tv" name="tvdb">140101</metadata>




        <title>Hawaii Five-0</title>


        <metadata type="tv" name="tvdb">164541</metadata>






        <metadata type="tv" name="tvdb">161511</metadata>




        <title>The Cape</title>


        <metadata type="tv" name="tvdb">160671</metadata>




        <title>Mr. Sunshine</title>


        <metadata type="tv" name="tvdb">164481</metadata>



Batch Operations

It would be odd, if a tool that has “batch” in its name didn’t provide some batch operations.  A batch operation, is an operation that BMT can apply against a collection of media files.  Batch Operations are available from 2 locations; The Tools menu has a bunch of operations, and when you are browsing views, there is a Batch Operations drop down menu in the button bar.

In the above screenshot, you can see both the batch operations drop down in the button bar, and I’ve clicked on the Tools menu, which shows many of the same operations. (Although the tools menu does have a few more operations)

It is important to know the distinction between using an operation from the Tools menu, vs using an operation from the folder’s button bar.  When you use an operation from the folder’s button bar, that operation is applied to the current folder and all of it’s sub folders.  But, when you use the same operation from the Tools menu, that operation is applied to every media file in your library.  So, use the operations in the Tools menu with caution.

Here is complete list of the Batch Operations, and what they do.

Set Watched

Sets the watched status to true

Set UnWatched

Sets the watched status to false

Set Archived

This is only applicable to Sage Recordings, and it will Archive the recordings.

Set Unarchived

This is only applicable to Sage Recordings, and it will remove the recording from the archived recordings.

Import as Recording

Imports non Sage Recordings into the SageTV recordings view.  Keep in mind that this will import both TV and Videos into the Sage Recordings.

Un-import as recording

Moves sage recordings to the video library.

Remove Fanart Files

Removes fanart files from the central fanart folder

Remove .properties

Removes .properties files

Clear custom metadata fields

Clear any custom metadata fields from the media files.  ie, things like SeasonNumber and EpisodeNumber are store in the custom metadata fields.  Custom metadata fields are fields that are not supported natively by SageTV.

Export .properties

Export .properties files.  You might do this to simply create a backup of your metadata.

Fix Genres

This will force a maximum of 2 genres per media file, and it fix the genres so that genres like “Action and Adventure” actually become 2 genres, “Action” and “Adventure”.

Export SageTV media thumbnail

Exports a thumbnail images in the same directory as the media files.

Add Relative Path to Titles

SageTV expects that non recordings contain the relative path of the media file in the Title field.  BMT doesn’t normally do this, so, you can add the relative path, if you want it.

Remove Relative Path from Titles

In the event that some media files (most likely TV files that are not imported as recordings) has a relative path in front of the Series name, then you can use this to clean out the relative path.

Associate TV Series Information

This will attempt to locate a Series Info for every TV file in the library.  Sage Recordings will have a Series Info automatically, but TV files that you’ve imported may not.

Fix Parental Ratings (4.9.5)

This will rewrite all the parental ratings that do not conform to the SageTV ratings.  For examples, ratings like, TV-MA will become TVM.  Prior to 4.9.5, bmt would simply store a rating based on what was provided by the metadata provider.  As of 4.9.5, bmt will convert all ratings from a provider into a rating that is valid for SageTV, so that SageTV parental controls can continue to work as expected.

When you apply this fix, any rating that cannot be converted will be default to TVM and NR for TV and Movies respectively.  TVM means mature content, and NR means not rated.

Fix Year for TV Shows (4.9.5)

Prior to 4.9.5, bmt would store a Year for each episode.  Unfortunately, SageTV, when it sees a year, it will append that to the Title for display.  This results in TV shows showing up as “House (2010)” instead of just “House”.  This fix removes the year metadata from all TV shows.

Searching Views

Immediately above the list of views, is a search box.  Many people tend to miss it, but that search box will perform a quick search against the titles in your collection.  You can see from the screenshot below, that I have searched for ‘house’ and it shows 3 results in the right side panel.

Notice that also, it added the search to a view, called ‘house’ that is available immediately below the search box.  When you search, any searches are added below the search box, and you can quickly recall that search details during your browsing session.  The searches disappear once you close your browser session.

Using BMT Summary

As you can see, BMT includes many features, and it’s not complete.  It provides both automatic and manual means of getting fanart. It also provides tools to help you clean up your library, and it tries to be fairly accommodating in term of providing different options for different types of people.

Showing Fanart in SageTV

As was mentioned, BMT does not actually add anything to the SageTV UI.  So, if you want to see the fanart the BMT has downloaded, then you’ll need another Plugin.  There are many plugins today that do use the Phoenix Central Fanart, which is the Fanart stucture that BMT saves.  For a complete list of known plugins that use Fanart, check out this posting.

I can’t get into details about each of those plugins, so you’ll need to do some investigating on your own to see which plugins you’ll want to use for showing fanart.

It is worth noting that Fanart plugins need to be installed on each client, extender, or placeshifter on which you want to see Fanart.  If you are using a PC client, you’ll also need to make sure that the PC Client and can access the Fanart that is downloaded by the server.  Typically, this means that if you have PC clients, then you’ll want to make sure that your Fanart is on a share that can be accessed by the Client and Server.


There are going to be times when things just don’t work.  It can be frustrating to you, as the user, and it is frustrating for me as well, since I like it, when things just work.

Sometimes, it’s just a matter of understand what BMT is trying to do, so your first step, should be consult this document and see if you are using it correctly.  If you are using it correctly, and things are not working, then you can post a question on the forums.

BMT has it’s own sub-forum on the SageTV forums.  There are a number of “stickies” there that may provide some information, but if you don’t see what you are looking for them use the “Search this Forum” section to search for answers in the forum.  You’d be hard pressed to find a problem that someone else hasn’t already encountered.

But, if you decide that your problem is different, you can post a question in the forum.  Either myself, or someone else, will try to help.

If I’m helping, then I might ask that you send me your log files.  To do this, you can use the “Create Support Request” option in the Tools menu of the BMT web interface.  This will create a .zip file of all your log files and provide you with an email address to which your can email the logs.

Troubleshooting can take time, and I don’t always have time to immediately respond.  I try to quickly look at the logs and see if I can find a solution, but if nothing is forth coming, then it may take a few days, or even weeks to resolve. :(  In some rare cases, I may never be able to solve your issue.

If you are technical, you can choose to look that the log files yourself.  I don’t expect users to do this, but you are free to do so.  The logs are provided for my benefit, but a technical person may also be able to solve their own issues by looking at the log files.



I’ve gotten a few requests to donate to this project.  If you want to donate, then you can click the donate icon, or if you want to know more about donating, then see this section of the About Guide.

Sage Properties

While BMT no longer creates .properties, it does export them.  You can use this sample to see some the property names that SageTV expects, and to see the format of some of the values

Actor=Leonardo DiCaprio -- Cobb;Joseph Gordon-Levitt -- Arthur;Ellen Page -- Ariadne;Marion Cotillard -- Mal;Ken Watanabe -- Saito;Michael Caine -- Professor;Tom Hardy -- Eames;Cillian Murphy -- Fischer;Tom Berenger -- Browning;Lukas Haas -- Nash;Dileep Rao -- Yusuf



Description=In a world where technology exists to enter the human mind through dream invasion, a highly skilled thief is given a final chance at redemption which involves executing his toughest job till date, Inception.

Director=Christopher Nolan





Genre=Science Fiction;Thriller

Guest=Hans Zimmer -- Music;Emma Thomas -- Producer;Christopher Nolan -- Producer;Wally Pfister -- Director of Photography;Lee Smith -- Editor;Christopher Nolan -- Author


























SageTV Settings that affect BMT

The Configuration panel of the Web Interface, there is a SageTV node that contains 2 configuration sections; Debug Settings and Metadata Settings

If you are seeing .properties files being created after installing BMT it’s probably because the the setting, Update .properties when changed is enabled in the Metadata Settings section.  

BMT doesn’t create .properties, but as a side effect of updating SageTV metadata, SageTV will by default persist those new changes as .properties.  Those files are not required by SageTV or BMT, they are simply a backup, and it is perfectly ok to turn off their creation using the above setting.