This project has moved and is read-only. For the latest updates, please go here.

Best Practice Guide


Getting good results using Media Companion for scraping movie details.

There are many ways that a person may store their media on a system, but Media Companion supports two methods that will make it suitable for most people.

1. File Method - The file method uses only the filename to search for a correct movie, eg: 'D:\Movies\Star Trek.avi'
2. Folder Method - The folder method ignores the filename and uses the folder name in order to identify the movie, eg: 'D:\Movies\Star Trek\whatever.avi'

In both instances the only folder Media Companion needs to know about is 'D:\Movies'. The default setting uses the File Method, if you wish to use the folder method then be sure to select this in the movie preferences.

Media Companion uses IMDB Or TMDB (depending on selected options) to collect movie information, and using either of the above methods is fairly accurate with about 9 out of 10 movies being scraped correctly. The accuracy of the scraper can be increased using a couple of methods. The easiest is by using the year within the folder of filename. eg.

'D:\Movies\Star Trek (2009).avi' or
'D:\Movies\Star Trek (2009)\whatever.avi'

The year should be inside parenthesis, and will increase accuracy to about 90%. (although note: Some movies release close to the end of a year, may be listed as the following year.)

100% accuracy is possible using the IMDB ID in either the filename, or an accompanying .nfo file.
The IMDB ID can be found using IMDB, the IMDB url for 'Star Trek (2009)' is '' the case of the 'Star Trek' Movie, it is 'tt0796366'

Using the IMDB ID within the file or folder name.
The file or folder can contain the ID, using this method overrules all other methods. eg.

'D:\Movies\whatever (tt0796366).avi' or

Using the IMDB ID within an .nfo file.
The nfo must be named the same as the media file, if the nfo file contains the IMDB ID then the name is not important. eg.


The nfo file is simply a text file, and the contents are not important. As long as an IMDB ID is located within the text somewhere, Media Companion will find it, and use that ID.

Some Notes:
1. Artwork is predominantly gathered from TheMovieDb site. If you find you can not get Fanart or Posters from TMDB (TheMovieDb), there is a possibility the IMDB ID number is not allocated to the movie on TMDB's site.
2. Use of XBMC TMDB scraper, will store both TMDB and IMDB Id's in the movies nfo file.

Clean Filenames
All of the above methods, with the exception of those that use the IMDB ID, have clean filenames. There maybe instances when Media Companion encounters less useful filenames. eg.

Star.Trek.720p.Blu Ray.DTS.x264.mkv

Media Companion checks for matches for things such as 720, or Blu Ray, and will crop the filename of anything after a matching term. In the above example, the filename would be cropped to become:

The final period would then be removed and the period between the words would be replaced with a space, Media Companion would then search for the movie 'Star Trek'.

TV Shows

TV Shows can be a little more complicated to get organized than Movies but the following section should help.

Folder Structure

The easiest way for MC to find all your TV Shows will be for them to all be in one folder on your system, which we will call the Root TV Shows folder. This folder can be anywhere on your system as long as you have user privileges so that MC can make changes within the folder. Individual TV Show folders located elsewhere can be added manually, but it's easier to have MC scan the root folder and add the bulk of the TV Show folders for you.

The Root folder should not contain seasons of shows, rather each show must be in it's own folder. A show's folder may simply contain all of the episodes or can be organized with sub-folders by season, the latter being preferable.

The file path for any show you want MC to look for when searching the Root folder should look like one of the following:

  • TV Shows Root\Show\Show Season #\episode.avi
  • TV Shows Root\Show\episode.avi

Naming Conventions

To begin with, it is important that name of the show's folder, match the shows name as it appears on TVDB, this can be the cause of shows not being recognized, or not being recognized properly by MC.
The only way to attain 100% accuracy is to have the show's TVDB id# in the show's .NFO file which MC does automatically for all identified shows; fortunately, mis-identified shows can easily be fixed with MC's TV Show Selector.

As far as the actual file names are concerned, all MC really cares about are the numbers identifying the season and episode number. There are three conventions built into MC that should recognize the episodes from the bulk of the shows in a collection right off the bat because they are the most commonly used. Those being:

  • ##x##
    • e.g. Firefly 01x02 The Train Job.avi
  • S##E##
    • e.g. Firefly S01E02 The Train Job.avi
  • ###
    • e.g. Firefly 102 The Train Job.avi

The 1 being the first season and the 02 being the episode number. (Note: the .avi is just for the sake of the example, and not a required format.)

Files not adhering to one of these three naming conventions can either be edited manually, or recognized in MC by adding custom Regex entries.

Dirty File Names

While the scraper will ignore most of the file name, only looking for info to identify season and episode number, sometimes extra text in the file name can cause problems.

For example: Chuck.S02E02.VOSTFR.HDTV.XViD-PM5.avi should be identified as episode 2 of season 2 of whatever show the tvshow.nfo file in the show folder says it is, but it doesn't always work perfectly.

If you are having trouble getting a show's episodes to be identified correctly, the obvious solution would be to chop down those file names, but with possibly dozens of files to modify this can be a long and painstaking process.
Fortunately, the Regex section in MC can help with this as well, by allowing you to test the file name against the existing regex strings to see if this is really where the problem lays, possibly allowing you to adress the problem by creating a new regex string that will identify the episode correctly.

<MC documentation home

Last edited Apr 20 at 1:05 AM by vbat99, version 13