MythTV Universal Metadata Format

From MythTV Official Wiki
Revision as of 17:08, 6 June 2010 by Rdv (Talk | contribs)

Jump to: navigation, search

In order to unify metadata grabbing for all MythTV screens and plugins, the following universal metadata grabber format specification will be used. Metadata grabbing will be handled by common code with relatively little custom code necessary for new plugins. Grabber scripts must conform the the standard, and can otherwise "drop in" to provide metadata lookup for user plugins and core MythTV screens.

Explanation of supported tags

The "Used in" values below only reflect the tags which could be displayed in the plugins today. When writing your grabber script, you should feel free to use any and all tags listed to make data available to future improvements in MythTV.

Tag name Description Used in Video Used in Music Used in Games
metadata All results are encapsulated in <metadata> tags. Metadata tags are the root node. Yes Yes Yes
item Any returned item is encapsulated in an <item> tag. Yes Yes Yes
title A textual title for the item being returned. Yes Yes Yes
subtitle The subtitle on the item being returned. Yes No No
tagline The tagline/catch phrase of the item being returned. Yes No No
description The plot of the item being returned. In music, this is used to contain the lyrics. Yes Yes Yes
season The season number of the item being returned. Yes No No
episode The episode number of the item being returned. Yes No No
dvdseason The DVD season on which the returned item appears. Yes No No
dvdepisode The DVD episode number of the returned item.. Yes No No
albumtitle The title of the album on which this item was released. No Yes No
system The game system for which this item was released. No No Yes
inetref REQUIRED. The reference number/serial number of the item at the metadata source. Used for a detailed lookup. Yes Yes Yes
imdb the IMDB number for the item being returned. Yes No No
tmsref The Tribune Media Services code number for the item being returned (only provided by TheTVDB so far). Yes No No
homepage The homepage of the item being returned.. Yes No No
trailer A web link to the trailer for the returned item. Yes No No
language The two-character (ISO-639) language code of the item. Yes Yes No
releasedate The release date for the returned item in RFC-822 format. Yes Yes No
lastupdated The date and time the item was last updated at the source in RFC-822 format. Yes Yes Yes
userrating A float value of the user rating at the source. Yes Yes No
tracknum The integer track number of the returned item. No Yes No
popularity An integer popularity value for the item. Yes Yes Yes
budget The integer amount spent to produce the returned item. Yes No No
revenue The integer amount earned by the returned item. Yes No No
year The integer year of the returned item. Yes Yes Yes
runtime The runtime of the returned item in minutes. Yes No No
runtimesecs The runtime of the returned item in seconds. No Yes No
certifications Encapsulates <certification> items, this is the parental rating container. Yes Yes No
certification An individual parental rating item, must be contained in a <certifications> tag. Takes two attributes, locale and name. Yes Yes Yes
categories Encapsulates <category> items, this is the genre container. Yes Yes Yes
category An individual genre item, takes attribute name. Yes Yes Yes
countries Encapsulates <country> items, this is the locale container. Yes Yes Yes
country A locale of production for the returned item, takes attribute name. Yes Yes Yes
studios Encapsulates <studio> items, this is the production company container. Yes Yes Yes
studio The production company/publisher of the item, takes attribute name. Yes Yes Yes
people Encapsulates <person> items, this is the role/job container. Yes Yes No
person A person involved with the production of this item, requires attribute job and name, optionally takes character, thumb and url. Yes Yes No
images Encapsulates <image> items, this is the artwork container. Yes Yes Yes
image A binary graphic related to the returned item, requires attribute type and url, optionally takes attribute thumb for a thumbnail. Yes Yes Yes

Query Results

Important.png Note: For consistency between grabbers, please use the following format for your grabber query command line:

./grabbername -M "query phrase"

A query result is nothing more than a series of items filled as completely as you care or are able to fill them. The only caveat is that a query (and by definition, any returned single item) must return an inetref to use in a followup query.

<?xml version='1.0' encoding='UTF-8'?>
<metadata>
  <item>
    <language>en</language>
    <title>Star Wars: Episode V</title>
    <subtitle>The Empire Strikes Back</subtitle>
    <inetref>1891</inetref>
    <imdb>0080684</imdb>
    <userrating>8.4</userrating>
    <certifications>
      <certification locale="us" name="PG"/>
    </certifications>
    <description>While Luke takes advanced Jedi training from Yoda, his friends are relentlessly pursued by Darth Vader as part of his plan to capture Luke.</description>
    <releasedate>1980-05-21</releasedate>
    <images>
      <image type="coverart" url="http://i2.themoviedb.org/posters/4a7/4bc9138c017a3c57fe0074a7/star-wars-episode-v-the-empire-strikes-back-original.jpg" thumb="http://i1.themoviedb.org/posters/4a7/4bc9138c017a3c57fe0074a7/star-wars-episode-v-the-empire-strikes-back-cover.jpg"/>
      <image type="fanart" url="http://i1.themoviedb.org/backdrops/494/4bc9138a017a3c57fe007494/star-wars-episode-v-the-empire-strikes-back-original.jpg" thumb="http://i1.themoviedb.org/backdrops/494/4bc9138a017a3c57fe007494/star-wars-episode-v-the-empire-strikes-back-thumb.jpg"/>
    </images>
    <lastupdated>Wed, 26 May 2010 04:11:22 GMT</lastupdated>
  </item>
  <item>
    <language>en</language>
    <title>Star Wars: Episode VI</title>
    <subtitle>Return of the Jedi</subtitle>
    <inetref>1892</inetref>
    <imdb>0086190</imdb>
    <userrating>7.8</userrating>
    <certifications>
      <certification locale="us" name="PG"/>
    </certifications>
    <description>After rescuing Han Solo from the palace of Jabba the Hutt, the Rebels attempt to destroy the Second Death Star, while Luke Skywalker tries to bring his father back to the Light Side of the Force.</description>
    <releasedate>1983-05-25</releasedate>
    <images>
      <image type="coverart" url="http://i1.themoviedb.org/posters/506/4bc9139e017a3c57fe007506/star-wars-episode-vi-return-of-the-jedi-original.jpg" thumb="http://i2.themoviedb.org/posters/506/4bc9139e017a3c57fe007506/star-wars-episode-vi-return-of-the-jedi-cover.jpg"/>
      <image type="fanart" url="http://i3.themoviedb.org/backdrops/4f8/4bc9139c017a3c57fe0074f8/star-wars-episode-vi-return-of-the-jedi-original.jpg" thumb="http://i3.themoviedb.org/backdrops/4f8/4bc9139c017a3c57fe0074f8/star-wars-episode-vi-return-of-the-jedi-thumb.jpg"/>
    </images>
    <lastupdated>Sat, 15 May 2010 22:20:40 GMT</lastupdated>
  </item>
</metadata>
 

Data Grab Commands

Important.png Note: For consistency between grabbers, please use the following format for your grabber data command line:

Title Search: ./grabbername -D "Inetref"

Television Title And Subtitle Search: ./grabbername -N "title" "subtitle"

Television Season and Episode Search: ./grabbername -D "Inetref" "season number" "episode number"

Movie Example

<?xml version='1.0' encoding='UTF-8'?>
<metadata>
  <item>
    <title>Star Wars: Episode IV</title>
    <subtitle>A New Hope</subtitle>
    <tagline>A long time ago in a galaxy far, far away...</tagline>
    <language>en</language>
    <description>When Princess Leia is taken prisoner by Darth Vader, she sends her two droids on a mission to find an old Jedi Knight. Their paths cross that of Luke Skywalker who, along with Obi Wan Kenobi, Han Solo and Chewbacca, heads off to Alderaan to deliver the droids to the Rebellion.</description>
    <certifications>
      <certification locale="us" name="PG"/>
    </certifications>
    <categories>
      <category type="genre" name="Action"/>
      <category type="genre" name="Adventure"/>
      <category type="genre" name="Fantasy"/>
      <category type="genre" name="Science Fiction"/>
    </categories>
    <studios>
      <studio name="Lucasfilm"/>
    </studios>
    <countries>
      <country name="Tunisia"/>
      <country name="United States of America"/>
    </countries>
    <popularity>3</popularity>
    <userrating>8.2</userrating>
    <budget>11000000</budget>
    <revenue>775398007</revenue>
    <year>1977</year>
    <releasedate>1977-05-25</releasedate>
    <lastupdated>Sat, 29 May 2010 16:18:37 GMT</lastupdated>
    <runtime>121</runtime>
    <inetref>11</inetref>
    <imdb>0076759</imdb>
    <homepage>http://www.themoviedb.org/movie/11</homepage>
    <trailer>http://www.youtube.com/watch?v=96</trailer>
    <people>
      <person name="George Lucas" job="Director" thumb="http://i2.themoviedb.org/profiles/15a/4bccb006017a3c0f2a00015a/george-lucas-thumb.jpg" url="http://www.themoviedb.org/person/1" department="Directing"/>
      <person name="George Lucas" job="Author" thumb="http://i3.themoviedb.org/profiles/15a/4bccb006017a3c0f2a00015a/george-lucas-thumb.jpg" url="http://www.themoviedb.org/person/1" department="Writing"/>
      <person name="Mark Hamill" job="Actor" character="Luke Skywalker" thumb="http://i1.themoviedb.org/profiles/174/4bccaf4c017a3c0f32000174/mark-hamill-thumb.jpg" url="http://www.themoviedb.org/person/2" department="Actors"/>
      <person name="Harrison Ford" job="Actor" character="Han Solo" thumb="http://i3.themoviedb.org/profiles/00a/4bd38e2c017a3c534700000a/harrison-ford-thumb.jpg" url="http://www.themoviedb.org/person/3" department="Actors"/>
      <person name="Carrie Fisher" job="Actor" character="Leia Organa" thumb="http://i2.themoviedb.org/profiles/1a7/4bccb3c4017a3c0f300001a7/carrie-fisher-thumb.jpg" url="http://www.themoviedb.org/person/4" department="Actors"/>
      <person name="Peter Cushing" job="Actor" character="Grand Moff Tarkin" thumb="http://i2.themoviedb.org/profiles/1fe/4bccb56b017a3c0f340001fe/peter-cushing-thumb.jpg" url="http://www.themoviedb.org/person/5" department="Actors"/>
      <person name="Anthony Daniels" job="Actor" character="C-3PO" thumb="http://i3.themoviedb.org/profiles/17a/4bccb612017a3c0f2f00017a/anthony-daniels-thumb.jpg" url="http://www.themoviedb.org/person/6" department="Actors"/>
      <person name="Kenny Baker" job="Actor" character="R2-D2" url="http://www.themoviedb.org/person/130" department="Actors"/>
      <person name="George Lucas" job="Executive Producer" thumb="http://i1.themoviedb.org/profiles/15a/4bccb006017a3c0f2a00015a/george-lucas-thumb.jpg" url="http://www.themoviedb.org/person/1" department="Production"/>
      <person name="Gary Kurtz" job="Producer" url="http://www.themoviedb.org/person/12401" department="Production"/>
      <person name="Rick McCallum" job="Producer" url="http://www.themoviedb.org/person/19801" department="Production"/>
      <person name="Alec Guinness" job="Actor" character="Obi-Wan Kenobi" url="http://www.themoviedb.org/person/12248" department="Actors"/>
    </people>
    <images>
      <image type="coverart" thumb="http://i1.themoviedb.org/posters/0a9/4bc90144017a3c57fe0000a9/star-wars-episode-iv-a-new-hope-cover.jpg" url="http://i3.themoviedb.org/posters/0a9/4bc90144017a3c57fe0000a9/star-wars-episode-iv-a-new-hope-original.jpg"/>
      <image type="coverart" thumb="http://i3.themoviedb.org/posters/08b/4bc90140017a3c57fe00008b/star-wars-episode-iv-a-new-hope-cover.jpg" url="http://i2.themoviedb.org/posters/08b/4bc90140017a3c57fe00008b/star-wars-episode-iv-a-new-hope-original.jpg"/>
      <image type="coverart" thumb="http://i3.themoviedb.org/posters/0a4/4bc90144017a3c57fe0000a4/star-wars-episode-iv-a-new-hope-cover.jpg" url="http://i1.themoviedb.org/posters/0a4/4bc90144017a3c57fe0000a4/star-wars-episode-iv-a-new-hope-original.jpg"/>
      <image type="fanart" thumb="http://i3.themoviedb.org/backdrops/06e/4bc9013a017a3c57fe00006e/star-wars-episode-iv-a-new-hope-thumb.jpg" url="http://i2.themoviedb.org/backdrops/06e/4bc9013a017a3c57fe00006e/star-wars-episode-iv-a-new-hope-original.jpg"/>
      <image type="fanart" thumb="http://i1.themoviedb.org/backdrops/062/4bc90139017a3c57fe000062/star-wars-episode-iv-a-new-hope-thumb.jpg" url="http://i3.themoviedb.org/backdrops/062/4bc90139017a3c57fe000062/star-wars-episode-iv-a-new-hope-original.jpg"/>
    </images>
  </item>
</metadata>

Television Example

<?xml version='1.0' encoding='UTF-8'?>
<metadata>
  <item>
    <title>Lost</title>
    <subtitle>What They Died For</subtitle>
    <language>en</language>
    <description>While Locke devises a new strategy, Jack's group searches for Desmond.</description>
    <season>6</season>
    <episode>16</episode>
    <certifications>
      <certification locale="us" name="TV-14"/>
    </certifications>
    <categories>
      <category type="genre" name="Action and Adventure"/>
      <category type="genre" name="Drama"/>
      <category type="genre" name="Science-Fiction"/>
    </categories>
    <studios>
      <studio name="ABC"/>
    </studios>
    <runtime>60</runtime>
    <inetref>73739</inetref>
    <tmsref>SH672362</tmsref>
    <userrating>8.0</userrating>
    <year>2010</year>
    <releasedate>2010-05-18</releasedate>
    <lastupdated>Sun, 30 May 2010 11:59:09 GMT</lastupdated>
    <homepage>http://thetvdb.com/?tab=episode&seriesid=73739&seasonid=66871&id=1685191</homepage>
    <people>
      <person job="Actor" name="Matthew Fox" character="Jack Shephard" url="http://www.thetvdb.com/banners/actors/27747.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27747.jpg"/>
      <person job="Actor" name="Terry O'Quinn" character="John Locke" url="http://www.thetvdb.com/banners/actors/27745.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27745.jpg"/>
      <person job="Actor" name="Evangeline Lilly" character="Kate Austen" url="http://www.thetvdb.com/banners/actors/27741.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27741.jpg"/>
      <person job="Actor" name="Naveen Andrews" character="Sayid Jarrah" url="http://www.thetvdb.com/banners/actors/27749.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27749.jpg"/>
      <person job="Actor" name="Daniel Dae Kim" character="Jin Kwon" url="http://www.thetvdb.com/banners/actors/27742.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27742.jpg"/>
      <person job="Actor" name="Yunjin Kim" character="Sun Kwon" url="http://www.thetvdb.com/banners/actors/27740.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27740.jpg"/>
      <person job="Actor" name="Josh Holloway" character="James 'Sawyer' Ford" url="http://www.thetvdb.com/banners/actors/27739.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27739.jpg"/>
      <person job="Actor" name="Jorge Garcia" character="Hugo 'Hurley' Reyes" url="http://www.thetvdb.com/banners/actors/27737.jpg" thumb="http://www.thetvdb.com/banners/_cache/actors/27737.jpg"/>
      <person job="Guest Star" name="Michelle Rodriguez"/>
      <person job="Guest Star" name="Mira Furlan"/>
      <person job="Director" name="Paul Edwards"/>
      <person job="Author" name="Edward Kitsis"/>
      <person job="Author" name="Adam Horowitz"/>
      <person job="Author" name="Elizabeth Sarnoff"/>
    </people>
    <images>
      <image type="screenshot" url="http://www.thetvdb.com/banners/episodes/73739/1685191.jpg" thumb="http://www.thetvdb.com/banners/_cache/episodes/73739/1685191.jpg"/>
      <image type="coverart" url="http://www.thetvdb.com/banners/seasons/73739-6-5.jpg" thumb="http://www.thetvdb.com/banners/_cache/seasons/73739-6-5.jpg"/>
      <image type="coverart" url="http://www.thetvdb.com/banners/seasons/73739-6-4.jpg" thumb="http://www.thetvdb.com/banners/_cache/seasons/73739-6-4.jpg"/>
      <image type="fanart" url="http://www.thetvdb.com/banners/fanart/original/73739-43.jpg" thumb="http://www.thetvdb.com/banners/_cache/fanart/original/73739-43.jpg" width="1920" height="1080"/>
      <image type="fanart" url="http://www.thetvdb.com/banners/fanart/original/73739-34.jpg" thumb="http://www.thetvdb.com/banners/_cache/fanart/original/73739-34.jpg" width="1920" height="1080"/>
      <image type="fanart" url="http://www.thetvdb.com/banners/fanart/original/73739-21.jpg" thumb="http://www.thetvdb.com/banners/_cache/fanart/original/73739-21.jpg" width="1280" height="720"/>
      <image type="fanart" url="http://www.thetvdb.com/banners/fanart/original/73739-47.jpg" thumb="http://www.thetvdb.com/banners/_cache/fanart/original/73739-47.jpg" width="1920" height="1080"/>
      <image type="banner" url="http://www.thetvdb.com/banners/seasonswide/73739-6.jpg" thumb="http://www.thetvdb.com/banners/_cache/seasonswide/73739-6.jpg"/>
    </images>
  </item>
</metadata>

Music Example

<metadata>
  <item>
    <title>Break Your Heart</title>
    <albumtitle>Rokstarr</albumtitle>
    <tracknum>1</tracknum>
    <language>en</language> 
    <description>Now I might not be the worst of the best but you gotta respect my honesty so let me break your heart but I dont think theres anybody as bomb as me so you can take this chance and everybodys gonna be wonderin how you feel you might say this is Ludacris but Taio Cruz tell her how you feel.</description>
    <categories> 
        <category type="genre" name="Hip-hop" />
        <category type="genre" name="Pop" />
    </categories> 
    <studios> 
        <studio name="Island" /> 
    </studios> 
    <countries> 
        <country name="United Kingdom" /> 
        <country name="United States of America" /> 
    </countries> 
    <userrating>8.2</userrating>
    <year>2010</year>
    <lastupdated>Tue, 01 Jul 2008 11:37:47 GMT</lastupdated>
    <runtimesecs>203</runtimesecs>
    <inetref>2703d604</inetref>
    <people>
        <person name="Taio Cruz" job="Artist" character="" thumb="" url="" />
        <person name="Ludacris" job="Artist" character="" thumb="" url="" />
        <person name="Taio Cruz" job="Album Artist" character="" thumb="" url="" />
    </people>
    <images>
        <image type="coverart" thumb="" url="http://upload.wikimedia.org/wikipedia/en/f/fa/Taio_Cruz_Rokstarr.jpg" />
    </images>
  </item>
</metadata>

Game Example

<metadata>
  <item>
    <title>The Secret of Monkey Island</title>
    <description>Aspiring pirate Guybrush Threepwood goes on the adventure of a lifetime.</description>
    <system>PC</system>
    <categories> 
        <category type="genre" name="Adventure" /> 
    </categories> 
    <studios> 
        <studio name="Lucasfilm Games" /> 
    </studios> 
    <countries> 
        <country name="United States of America" /> 
    </countries> 
    <year>1990</year>
    <images>
        <image type="coverart" thumb="http://www.mobygames.com/images/covers/small/1080415346-00.jpg" url="http://www.mobygames.com/images/covers/large/1080415346-00.jpg" />
        <image type="fanart" url="http://img528.imageshack.us/img528/8982/14786890je6.jpg" />
    </images>
  </item>
</metadata>

Supported jobs

These are the strings to insert for the various jobs/professions. More can be added, but these are the currently supported jobs:

Movie/Video Jobs

  • "Actor"
  • "Guest Star"
  • "Author"
  • "Producer"
  • "Executive Producer"
  • "Director"
  • "Cinematographer"
  • "Composer"
  • "Editor"
  • "Casting"

Music Jobs

  • "Artist"
  • "Album Artist"

Supported image types

General Image Types

  • "Coverart"
  • "Fanart"
  • "Banner"
  • "Screenshot"

Music Image Types

  • "Poster"
  • "Back Cover"
  • "Inside Cover"
  • "CD Image"