Difference between revisions of "MythTV Universal Metadata Format"

From MythTV Official Wiki
Jump to: navigation, search
(Data Grab Commands)
Line 232: Line 232:
 
{{Note box|For consistency between grabbers, please use the following format for your grabber query command line:
 
{{Note box|For consistency between grabbers, please use the following format for your grabber query command line:
  
<code>./grabbername -MX "query phrase"</code>
+
<code>./grabbername -M "query phrase"</code>
 
}}
 
}}
 
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.
 
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.
Line 277: Line 277:
  
 
'''Title Search:'''
 
'''Title Search:'''
<code>./grabbername -DX "Inetref"</code>
+
<code>./grabbername -D "Inetref"</code>
  
 
'''Television Title And Subtitle Search:'''
 
'''Television Title And Subtitle Search:'''
<code>./grabbername -NX "title" "subtitle"</code>
+
<code>./grabbername -N "title" "subtitle"</code>
  
 
'''Television Season and Episode Search:'''
 
'''Television Season and Episode Search:'''
<code>./grabbername -DX "Inetref" "season number" "episode number"</code>
+
<code>./grabbername -D "Inetref" "season number" "episode number"</code>
 
}}
 
}}
  

Revision as of 19:08, 31 May 2010

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
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 Rhe 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.

<metadata>
    <item> 
      <language>en</language> 
      <title>Star Wars: Episode V - The Empire Strikes Back</title>  
      <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" thumb="http://i1.themoviedb.org/posters/4a7/4bc9138c017a3c57fe0074a7/star-wars-episode-v-the-empire-strikes-back-thumb.jpg" url="http://i3.themoviedb.org/posters/4a7/4bc9138c017a3c57fe0074a7/star-wars-episode-v-the-empire-strikes-back-original.jpg" /> 
      </images> 
      <lastupdated>Tue, 01 Jul 2008 11:37:47 GMT</lastupdated> 
    </item>
    <item> 
      <language>en</language> 
      <title>Star Wars: Episode VI - Return of the Jedi</title>  
      <inetref>1892</inetref> 
      <imdb>0086190</imdb>  
      <userrating>8.4</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" thumb="http://i1.themoviedb.org/posters/506/4bc9139e017a3c57fe007506/star-wars-episode-vi-return-of-the-jedi-thumb.jpg" url="http://i1.themoviedb.org/posters/506/4bc9139e017a3c57fe007506/star-wars-episode-vi-return-of-the-jedi-original.jpg" /> 
      </images> 
      <lastupdated>Tue, 01 Jul 2008 11:37:47 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"

Video Example

<metadata>
  <item>
    <title>Star Wars</title>
    <subtitle>A New Hope</subtitle>
    <tagline>A long time ago, in a galaxy far, far away...</tagline>
    <language>en</language> 
    <description>A band of rebels travel the galaxy attempting to free themselves from the tyranny of the evil galactic empire.</description>
    <season>0</season>
    <episode>0</episode> 
    <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>7</popularity>
    <userrating>8.2</userrating>
    <budget>21000000</budget>
    <revenue>1000000000</revenue>
    <year>1977</year>
    <releasedate>1977-05-25</releasedate>
    <lastupdated>Tue, 01 Jul 2008 11:37:47 GMT</lastupdated> <!-- RFC-822 date-time -->
    <runtime>121</runtime> <!-- In minutes -->
    <inetref>11</inetref> <!-- Per source reference string -->
    <imdb>0076759</imdb> <!-- IMDB number -->
    <tmsref>SH672362</tmsref> 
    <homepage>http://www.starwars.com</homepage>
    <trailer>http://www.youtube.com/watch?v=96</trailer>
    <people>
        <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" />
        <person name="George Lucas" job="Author" character="" thumb="http://i3.themoviedb.org/profiles/15a/4bccb006017a3c0f2a00015a/george-lucas-thumb.jpg" url="http://www.themoviedb.org/person/1" />
    </people>
    <images>
        <image type="coverart" thumb="http://i2.themoviedb.org/posters/0a9/4bc90144017a3c57fe0000a9/star-wars-episode-iv-a-new-hope-thumb.jpg" url="http://i2.themoviedb.org/posters/0a9/4bc90144017a3c57fe0000a9/star-wars-episode-iv-a-new-hope-original.jpg" />
        <image type="fanart" thumb="http://i1.themoviedb.org/backdrops/06e/4bc9013a017a3c57fe00006e/star-wars-episode-iv-a-new-hope-thumb.jpg" url="http://i3.themoviedb.org/backdrops/06e/4bc9013a017a3c57fe00006e/star-wars-episode-iv-a-new-hope-original.jpg" />
        <image type="fanart" thumb="http://i3.themoviedb.org/backdrops/07a/4bc9013e017a3c57fe00007a/star-wars-episode-iv-a-new-hope-thumb.jpg" url="http://i2.themoviedb.org/backdrops/07a/4bc9013e017a3c57fe00007a/star-wars-episode-iv-a-new-hope-original.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"
  • "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"