This project is read-only.
NOTE: This documentation is still being written, please check back for updates to get the latest information!

How to use MediaGerbil

So you downloaded the latest MediaGerbil release and want to dive in and use, but want some more info on how MediaGerbil should be used? No worries, follow these simple instructions and you will find yourself in media heaven in no time!

NOTE: The movie and folder titles shown below are for exemplary purposes only, MediaGerbil has no affiliation with any movie studio or movie producer and does not intentionally endorse any specific movie. Also, MediaGerbil does not condone, approve, endorse or in any way support piracy of movies or television shows, and movie titles used for example screenshots were taken from Google search results and manually recreated.


You can download, install and run the latest MediaGerbil release right here from CodePlex by clicking on the Download button on either the MediaGerbil home page or the Release Downloads page. Always make sure you grab the latest version to get the best MediaGerbil experience possible! There are two options for installing MediaGerbil:
  • ClickOnce Installer: The Click-once installer will take care of installing the necessary prerequisites as well as the MediaGerbil executable and any files needed to run. It will also create a program group in the Start Menu as well as a desktop shortcut for MediaGerbil. MediaGerbil should start automatically after the installation was completed successfully.
  • Self-Extracting Archive: If you don't want to use the ClickOnce installer you can also just grab the self-extracting archive version and unpack the archive to any location and run it from there! Just run the MediaGerbil.exe executable after unpacking and you are good to go! However, you will have to make sure that the prerequisites such as .NET Framework 4.0 are installed before running MediaGerbil.


If you already have a previous version of MediaGerbil upgrade is easy no matter which way you chose to install it:
  • ClickOnce Installer: If you used the ClickOnce installer then you don't have to do anything, MediaGerbil will let you know automatically when an update is available and install it for you:

MediaGerbil 0.2.0 Update Available (2011-01-17).png

Once you approve the update the installer will download the update automatically and install it:

MediaGerbil 0.2.0 Updating MediaGerbil (2011-01-17).png
  • Self-Extracting Archive: To upgrade from a previous version simply overwrite the files you have with the files from the latest self-extracting archive. As long as you keep your Preferences and Media Item Cache XML files they will be picked up by the new version without problems!

I am trying to make sure that upgrading from a previous version happens as smooth as possible, and MediaGerbil will let you know if there were any problems importing your old settings or media items cache.

First Run

After starting MediaGerbil you should go to the Preferences and set up your Media Directories first. Make sure to add both the included and excluded directories in case you have some folders which you don't want to be indexed, for example those home movies you've been shooting with your own camera, or any other content that doesn't belong on the list.

MediaGerbil 0.3.0 Preferences - Media Directories (2011-10-26).png

MediaGerbil 0.3.0 Preferences - Title Cleaning - Ignored Directories (2011-10-26).png

With that done hit F5 to Refresh the Media List with all the items that can be found in the specified media directories. If you don't get the right list check the Preferences and make sure the list of media file extensions includes all the extensions you are using in your media collection.

MediaGerbil 0.2.0 Preferences - Title Matching (2010-12-07).png

Automatically Match Titles

Once all the titles in your media directories show up in the list, it is time to match some titles. Depending on how you set your preferences you can match titles from either of two IMDb movie lists, or directly from the IMDb website.

MediaGerbil 0.3.0 Preferences - Title Matching (2011-10-26).png

It is recommended that you start with the smaller movie list first and then fill in the titles that didn't have any matches from one of the other two sources. However, depending on your movies your results might vary, so try it out and see what works best for you!

MediaGerbil 0.3.0 Preferences - Title Matching Help Tooltip (2011-10-26).png

There are also some options that influence how MediaGerbil matches your titles to the titles in the IMDb list:
  • Stop at first match: This algorithm will go through the alphabetical list of titles and stop at the first partial title match. This is the fastest way of matching titles but might lead to some inaccurate matches, for example "Superman" would be matched to "All-Star Superman" because it is higher up in the list than the actual movie entry for Superman.
  • Match Position within title text: Instead of stopping at the first match this algorithm will find all matches first and then sort them by the position of the original string in the title. For example "Superman" would give higher priority to "Superman Returns" than to "All-Star Superman" because the position of the word Superman in the string is closer to the original string. Results will be better than with the first method but also take slightly longer to calculate.
  • Levenshtein distance: This is a further improvement of the previous method but also takes into account the Levenshtein Distance between the original search string and the matched title, which is basically a number for how different two strings are from each other. Identical strings have a Levenshtein Distance of zero. For example, "Alien" will match both the movies "Alien" and "Aliens", and for both of them the position of the search string in the match is the same. However "Aliens" has a greater Levenshtein Distance than "Alien", therefore "Alien" would be the preferred match. This method gives the best results and is recommended even though it takes slightly longer to calculate than the other options.

For better title matching MediaGerbil also offers different views for the media item data grid. From the View menu you can select the Title Matching View, which will only show original title and matched title without any of the other metadata. You can easily switch back and forth between views at any point in time, even during title matching, it does not affect any of the data. This is what the regular view looks like for an example list of movies (see disclaimer at the top of this documentation):

MediaGerbil 0.2.0 Default View (2011-02-04).png

After switching to Title Matching View, it looks like this:

MediaGerbil 0.2.0 Title Matching View (2011-02-04).png

And after running Automatic Title Matching on all the titles, it looks like this:

MediaGerbil 0.2.0 Title Matching View after Matching (2011-02-04).png

As you can see most of the titles were matched fine, but there are some that are not correct, so let's take a look at our options for manual title matching!

Manually Match Titles

If the automatically matched title did not match a movie correctly, there are several options:
  • Title Match Drop-Down List: When you select a movie item in the item list and then click the Title field, it will switch into Edit mode and a drop-down list will be automatically populated with the best title matches. The top entry in the list will be the one that was automatically matched, but you can select any other title that fits better. In the example above, look at "The Sorcerer's Apprentice". The title was automatically matched to a movie with that name from 1955. When you click on the drop-down you can see that there are two other matches, one from 2002 and one from 2010. For our example we will pick the one from 2010.
MediaGerbil 0.2.0 Title Matching Drop-Down Example (2011-02-04).png
  • Manual Title Entry: When you select a movie item in the item list and then click the Title field, it will switch into Edit mode as described above. But the title field is also a textbox in which you can enter any title you want, in case none of the titles in the drop-down list match your movie. As you type, the drop-down list will be automatically populated with suggestions from the offline movie list, which will make manual matching a lot easier. If the movie you are looking for is not in the list you can enter it manually and just keep it, or use IMDb Advanced Title Search on your manual entry for matching with the online IMDb database.
  • IMDb Advanced Title Search: When you right-click on a movie item in the item list you can select "Pick Title Match from List" and then "From IMDb Advanced Title Search". This will open a dialog window with results from the IMDb Advanced Title Search website. This is mostly useful if a title could not be matched locally at all, as it queries the IMDb database directly instead of the offline movie list file. In our example the movie "Saw" was erroneously matched to one with the same title from 2003, but the one we are looking for is from 2004, as can be seen in the Advanced Title Search popup window. For movies that have a movie cover on IMDb it will show a little thumbnail preview for easier matching.
MediaGerbil 0.2.0 Title Matching Advanced Title Search Example (2011-02-04).png

In some cases none of the options above will lead to a successful match. There can be several reasons for that, it might be that IMDb simply has no entry for that movie, or that the original title of the movie is in a different language and did not get matched to the translated title. However, one reason might also be that the title cleaning did not clean up the title enough to automatically find a match. Let's look at an example on how to fix that: In our example movie list above the movie "16 Wishes" did not get matched at all, and when you click on it the drop-down list is empty. In the Preferences you can see what the title looks like after cleaning it up on the Title Cleaning tab. Simply copy and paste the movie title into the Test string field and look at the result, in this case for our 16 Wishes example:

MediaGerbil 0.3.0 Preferences - Title Cleaning (2011-10-26).png

As you can see there is still the word "hdtv" in our cleaned title, which is probably why it did not get matched correctly. To have this word cleaned from the title, simply add it to the list of ignored strings on the same preferences tab! After adding it, the cleaned string looks much better:

MediaGerbil 0.2.0 Preferences - Title Cleaning 2 (2011-02-04).png

Now when trying to match the title automatically, it gets correctly matched to "16 Wishes (2010) (TV)".

With that all our example movies have been matched to the correct titles and we can move on to the next step, which is retrieving the movie metadata.

TV Series Support

MediaGerbil 0.3.0 Title Matching View - TV Series (2011-10-26).png
MediaGerbil 0.3.0 Title Matching View - TV Series 2 (2011-10-26).png

Get IMDb Media Info

For the matched titles getting all the metadata from IMDb is only a mouse-click away. Either select only the titles you want to get metadata for or select the menu option to download media info for all the titles in the list, which is typically what you would do when using MediaGerbil for the first time. Once you have a list of titles with metadata in it already you would only want to update or get info for selected titles. There is also an option for MediaGerbil to only get metadata for titles which don't have an IMDb ID, which means those items have not been associated with metadata from IMDb yet.

MediaGerbil will get the production year, MPAA movie rating, IMDb rating, number of votes on IMDb, runtime, genres and description from IMDb. (Note that future MediaGerbil releases will add getting other info such as Actors, Director, Studio etc.). The downloaded data will appear in the list and can be edited when clicking on it. Note that editing these values has no effect on the IMDb database, in most cases you won't have to edit these fields manually except maybe for filling in missing information.

Here a screenshot of what our example movie list from above looks like after retrieving the IMDb metadata info and sorted by IMDb Rating (by clicking on the column header you can sort any column):

MediaGerbil 0.2.0 Title Matching View after Sorting (2011-02-04).png

With titles and metadata populated we can move on to the next step, which is retrieving cover images.

Download Cover Images

The final step is to get cover images for your movies. There are two sources for cover images available:
  • IMDb: You can download the highest resolution image that IMDb offers for the image that is displayed as the cover image on the movie page.
  • TMDb: also offers a wide range of cover images, backdrops, and fanart for movies, and there is a popup window from which you can pick the image you would like to download, for example:
MediaGerbil 0.2.0 TMDb Cover Image Picker (2011-02-04).png

You can select the default source for cover images in the Preferences, by default it is IMDb. When selecting TMDb currently you can download cover images and backdrop images. You can also set the default size for the preview image as well as for the downloaded image:
MediaGerbil 0.3.0 Preferences - Cover Images (2011-10-26).png
Also, if you would like to have other sources for cover images added, please submit a feature request through the Issue Tracker!

Download Backdrop Images

MediaGerbil 0.3.0 TMDb Backdrop Image Picker (2011-10-26).png

Last edited Oct 27, 2011 at 6:58 AM by Sertelegger, version 7


No comments yet.