Enhancing Recordings with Metadata Lookup

From MythTV Official Wiki
Revision as of 12:11, 21 February 2021 by Stevegoodey (talk | contribs) (Add TVmaze.)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

In MythTV .25 and newer, external metadata scripts can be used to enhance the information available for your recordings. As of this writing, no listings provider supplies information such as season, episode, or internet reference number (inetref, like a TVDB, TMDB or TVmaze number). Instead, MythTV can use the information the provider does provide and perform a lookup on various internet sources for additional missing information.


Make sure that the Python Bindings are installed (for example via the python-MythTV package from rpmfusion). The scripts under /usr/share/mythtv/metadata/ such as /usr/share/mythtv/metadata/Television/ttvdb.py have a -t switch that allows you to test that everything is installed correctly.

Upgrade Cheat Sheet

MythTV .25 supports metadata lookup for recordings and recording rules, including the assignment of artwork. Fast upgrade steps:

  1. To automatically look up the TVDB, TMDB or TVmaze reference number for all of your recording rules (which may produce some false matches), run:
    mythmetadatalookup --refresh-all-rules
  2. To automatically look up the inetref, season, and episode for all of your existing recordings, run:
    mythmetadatalookup --refresh-all
  3. To automatically download and assign artwork to all seasons of all content on your system, run:
    mythmetadatalookup --refresh-all-artwork
  • You can view and select artwork manually for each recording rule from the "Manage Recordings" -> "Recording Rules"->select a rule->Metadata Options screen.
  • Your backend will automatically keep your artwork up to date, but you must automatically or manually set inetrefs on your recording rules and/or recordings for this to work.
  • Make sure to allow your backends to run metadata lookup jobs.
  • Make sure to set your recording rules to perform a Metadata Lookup in the postprocessing options screen. This will ensure that future recordings are all looked up, and assigned a season and episode number.
  • Make sure you have the Fanart, Coverart, and Banner Storage Groups configured on your Master Backend.

Allowing Your Backend to Perform Metadata Lookups

Metadata lookup is a job, just like commercial detection, transcoding, and user configured jobs. As such, you need to tell MythTV's backend that it's allowed to perform metadata lookups.

Job Queue (Backend Specific)

In mythtv-setup, select the General settings. Press next until you are on the Job Queue settings page. You should see a checkbox marked Allow metadata lookup jobs. Check this box, and then press Next repeatedly until you can press Finish. Press Finish.

Configuring Recordings to Always Grab Extra Metadata

If you want to make sure that all recording rules that you create in the future perform metadata lookups, you should configure MythTV's default recording settings.

General (Jobs)

In the Front End, navigate to Setup->Video->General. Press next until you are on the General (Jobs) settings page. You should see a checkbox marked Run metadata lookup. Check this box, and then press Next repeatedly until you can press Finish. Press Finish.

Configuring A Single Recording Rule to Grab Extra Metadata

Important.png Note: Not all themes support this enhanced functionality. If you are unable to follow these steps successfully, you may need to change themes. The theme pictured here is Arclight.

When you edit a recording rule anywhere in the MythUI, you will always see the same Schedule Editor displayed. Here are the steps you should take if you want to have metadata lookups performed on a new recording rule (or if you've upgraded and are changing old rules to perform metadata lookup).

Post Processing Options

Click the "Post Processing" button. Make sure the "Automatically Look Up Metadata" option (wording may vary by theme) is checked. Press Done, then save the recording rule.

Setting the Internet Reference Number for a Recording Rule

Generally, MythTV's metadata functionality is "set it and forget it." Assuming your favorite show has a unique name, you get good guide information, and the metadata sources (TheTVDB and TheMovieDB) have a record of the show or movie, simply setting up a recording rule is enough. MythTV will handle the rest. But what should you do when your show isn't uniquely named, or when the metadata source calls it something else?

Let's take the American television show "Castle" as an example. Schedules Direct, the North American listings provider, refers to it as "Castle" (of course!). TheTVDB, however, refers to it as "Castle (2009)" because there were other shows named Castle that came before this one. Other times, a show will originate in one country and be remade abroad. "The Biggest Loser" has shows in dozens of countries! Each of them has a particular naming at TheTVDB.

MythTV solves this problem elegantly. All you need to do is tell the software which one is correct once, when setting up the rule, and all recordings made on that rule will get the correct Internet reference number (and thus will be assigned correct season and episode numbers, among other information). Here's how.

Metadata Options

When you create a rule for any show, it's a good idea to open the "Metadata Options" settings page. MythTV will automatically attempt to find the right show based on the Title and Subtitle presented. When it's not able to find the right show because there are multiple matches, you will be prompted immediately to select the right show. Based on the artwork, year, locale, description, and other information, it should be pretty easy to pick the right one. That's it! Simply press Done (wording varies) and save the recording rule.

Show Selection

If you fail to open the Metadata Options settings and save the matched number, MythTV will still do its best to provide you with good, up to date metadata. It's just going to do a much better job if you give it some help!

Picking Artwork for Your Recording Rules

In .25, the old "hunt for a filename that matches" recording artwork search is replaced by a brand new, flexible, powerful system. You now view and assign only the artwork you want to your rules. In addition to leaving nothing to chance, this new approach also allows you to set different artwork depending on the season for every show. Thus, when you highlight a show from Season 2 of Fringe, it is Season 2 artwork which appears, and the very same artwork that you have selected. It is no longer necessary to rely on an external script to harvest images for you-- you can control it all from the comfort of your couch.

You have a few options when it comes to your recording artwork. For those who prefer maximum control, you can set each piece of artwork for each season of each rule manually (instructions below). If you prefer to allow MythTV to download and keep your artwork up to date, simply do nothing. MythTV's internal housekeeper will run a daily job to keep your recording artwork up to date. When a new season of a show begins, MythTV will find all available artwork for that season within 24 hours of the recording. If you wish to invoke a mass-grab of artwork for your rules, you can simply issue this command:
mythmetadatalookup --refresh-all-artwork
This is the same command the backend runs nightly.

Manually assigning artwork to your recording rules is easy. Simply navigate to the recording rule to which you want to assign some artwork.

Recording Rule

We will again enter the Metadata Options screen.

Metadata Options

Every season within a recording rule actually has its own set of artwork. To assign artwork for Season 1 of a show, set the Season spinbox to "1." In this way, you can edit artwork for each season of a show and have any combination of artwork you like! If you simply want to set one set of artwork, that's fine too-- simply pick artwork for any season. In the absence of artwork being set for every season of a show, MythTV will simply fall back to the newest available artwork.

Metadata Options

When you're ready, click any of the online or local browsing buttons. MythTV only supports artwork downloads to and assignment from the Fanart, Coverart, and Banner Storage Groups. Legacy ("local") storage is not supported. The Fanart, Banner, and Screenshot Storage Groups must exist, and they must exist on the master backend.

Banner Selection

In this way, you can pick exactly the artwork you like for a show, and there's never any danger of a surprise while browsing your collection.

Metadata Options

Enabling Automatic Artwork Updates

By default, MythTV will not automatically fill in artwork for your recording rules. To enable a nightly job to check for recording rules and recorded programs without artwork, and to attempt to download it, navigate to: Setup->Artwork and Data Sources. Enable the "Perform daily updates of recording artwork" checkbox, and click OK/Save (wording may vary by theme). MythTV will now attempt to download new artwork once a day. As an added bonus, when a properly configured series enters a new season, the lookup will attempt to harvest fresh new artwork for the series, while leaving your old artwork intact for previous seasons.

Data and Artwork Sources


In cases where you get no results, no artwork, or other things go awry, do not panic! Metadata lookup can be very automatic-- but the amount of automation is directly related to the quality and completeness of your guide data. The metadata lookup code looks at many data points in your guide data to decide what type of content it is working with. Most issues are caused by a lack of complete guide data, or guide data which is otherwise mangled. Consider the following potential causes for your issue, and their solution.

  • Problem: A television show recording rule has no subtitle, no category_type which implies it is a series, and is otherwise indistinguishable from a movie. No metadata results (or the wrong metadata results) are found. Example scenario: You record a showing of "Scrubs" with no subtitle, and/or your guide data is otherwise poor. The metadata code attempts to look up the episode at TheMovieDB, and finds nothing (or a single record for an entire series in some cases, preventing Season/Episodes from ever being found).
    • Solution: Force the metadata grabber to use the television grabber by editing the recording rule. Set the season and episode to any legal value (Season 1, Episode 1 is suggested). This notifies the grabber to attempt to use the television grabber first, and you can at least set artwork for the series. Moreover, whether your guide data improves or not, future recordings for this rule will automatically know that this is a television show, and will call the right grabber first.
  • Problem: You are running the frontend in one language, but passing in titles from another. No matches are found.
    • Solution: A language mismatch only prevents automation in the lookup code-- not function. Even with desperately bad guide data, the metadata lookup and artwork code can still be made to work. Edit the rule for the recording in question, and navigate to the Metadata Options page. If the item is a television show/series, set the season and episode to any legal value (Season 1, Episode 1 is suggested). Press "Perform Lookup." If no data is found, you can *still* make this rule work by looking up the inetref at the metadata source. Enter the item number from TheTVDB/TheMovieDB/other metadata source. You can now test artwork picking by selecting one of the Online artwork buttons.


Additional metadata is by no means a requirement to enjoy MythTV. However, we live in a data-centric age where television is more commonly referenced by season and episode numbers than subtitle, or when it aired. Moreover, having access to this information makes it much easier to organize your files, transcode and name exported content, and to pick artwork. Having this information accessible directly from the MythTV user interface is fun and helpful.