Difference between revisions of "MythTV Universal Metadata Format"

From MythTV Official Wiki
Jump to: navigation, search
m (you can use this format in mxml files for your home videos, too)
(Slight rewording (contrary bolded statements made me uncomfortable))
Line 124: Line 124:
| inetref || string
| inetref || string
| '''REQUIRED'''.  The reference number/serial number of the item at the metadata source.  Used for a detailed lookup. <br/> '''OPTIONAL'''. If you manually add metadata to your home videos which are not available at any metadata source.
| '''REQUIRED'''.  The reference number/serial number of the item at the metadata source.  Used for a detailed lookup. <br/> ''Inetref is not required with .mxml files (external metadata xml files)-- you can use .mxml files to maintain external, portable metadata for home movies, etc.''
| {{YES}} || {{YES}} || {{YES}}
| {{YES}} || {{YES}} || {{YES}}

Latest revision as of 20:43, 22 November 2011

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.

You can manually add metadata to your home videos by putting a single query result in a file named <basename>.mxml.

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 Type 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
filename string Filename of connected media. Yes No No
title string A textual title for the item being returned. Yes Yes Yes
subtitle string The subtitle on the item being returned. Yes No No
tagline string The tagline/catch phrase of the item being returned. Yes No No
description string The plot of the item being returned. In music, this is used to contain the lyrics. Yes Yes Yes
season uint The season number of the item being returned. Yes No No
episode uint The episode number of the item being returned. Yes No No
chanid uint Internal channel id for recorded show. Yes No No
channum string Displayed channel number for recorded show. Yes No No
callsign string Short broadcast callsign for recorded show. Yes No No
channame string Full channel name for recorded show. Yes No No
playbackfilters string Post processing filters for use in playback. Yes No No
recgroup string Group defining additional recording parameters. Yes No No
playgroup string Group defining additional playback parameters. Yes No No
seriesid string Guide data code for the television series. Yes No No
programid string Guide data code for the specific episode. Yes No No
storagegroup string Location of file within MythTV's storage system. Yes No No
startts datetime Listed start time of program. Yes No No
endts datetime Listed end time of program. Yes No No
recstartts datetime Actual start time of recording. Yes No No
recendts datetime Actual end time of recording. 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 string The title of the album on which this item was released. No Yes No
system string The game system for which this item was released. No No Yes
inetref string REQUIRED. The reference number/serial number of the item at the metadata source. Used for a detailed lookup.
Inetref is not required with .mxml files (external metadata xml files)-- you can use .mxml files to maintain external, portable metadata for home movies, etc.
Yes Yes Yes
imdb string the IMDB number for the item being returned. Yes No No
tmsref string The Tribune Media Services code number for the item being returned (only provided by TheTVDB so far). Yes No No
homepage string The homepage of the item being returned.. Yes No No
trailer string A web link to the trailer for the returned item. Yes No No
language string The two-character (ISO-639) language code of the item. Yes Yes No
releasedate date The release date for the returned item in RFC-822 format. Yes Yes No
lastupdated datetime The date and time the item was last updated at the source in RFC-822 format. Yes Yes Yes
userrating float A float value of the user rating at the source. Yes Yes No
tracknum uint The integer track number of the returned item. No Yes No
popularity uint An integer popularity value for the item. Yes Yes Yes
budget uint The integer amount spent to produce the returned item. Yes No No
revenue uint The integer amount earned by the returned item. Yes No No
year uint The integer year of the returned item. Yes Yes Yes
runtime uint The runtime of the returned item in minutes. Yes No No
runtimesecs uint 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

Version Output

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

./grabbername -v

The version output enumerates the capabilities and information about your grabber to MythTV.

<?xml version='1.0' encoding='UTF-8'?>
  <name>GiantBomb Query</name>
  <author>R.D. Vaughan</author>
  <description>Search and Metadata downloads for Games from the giantbomb.com API</description>

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'?>
    <title>Star Wars: Episode V</title>
    <subtitle>The Empire Strikes Back</subtitle>
      <certification locale="us" name="PG"/>
    <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>
      <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"/>
    <lastupdated>Wed, 26 May 2010 04:11:22 GMT</lastupdated>
    <title>Star Wars: Episode VI</title>
    <subtitle>Return of the Jedi</subtitle>
      <certification locale="us" name="PG"/>
    <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>
      <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"/>
    <lastupdated>Sat, 15 May 2010 22:20:40 GMT</lastupdated>

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'?>
    <title>Star Wars: Episode IV</title>
    <subtitle>A New Hope</subtitle>
    <tagline>A long time ago in a galaxy far, far away...</tagline>
    <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>
      <certification locale="us" name="PG"/>
      <category type="genre" name="Action"/>
      <category type="genre" name="Adventure"/>
      <category type="genre" name="Fantasy"/>
      <category type="genre" name="Science Fiction"/>
      <studio name="Lucasfilm"/>
      <country name="Tunisia"/>
      <country name="United States of America"/>
    <lastupdated>Sat, 29 May 2010 16:18:37 GMT</lastupdated>
      <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"/>
      <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"/>

Television Example

<?xml version='1.0' encoding='UTF-8'?>
    <subtitle>What They Died For</subtitle>
    <description>While Locke devises a new strategy, Jack's group searches for Desmond.</description>
      <certification locale="us" name="TV-14"/>
      <category type="genre" name="Action and Adventure"/>
      <category type="genre" name="Drama"/>
      <category type="genre" name="Science-Fiction"/>
      <studio name="ABC"/>
    <lastupdated>Sun, 30 May 2010 11:59:09 GMT</lastupdated>
      <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"/>
      <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"/>

Recording Example

        <title>My Strange Addiction</title>
        <subtitle>Eats Couch Cushion; Furry</subtitle>
        <description>Lauren can not go to a party or social event without wearing her fur suit; Adele has been eating couch cushions for twenty years.</description>
        <channame>The Learning Channel HD</channame>
        <startts>Sat, 16 July 2011 18:30:00</startts>
        <endts>Sat, 16 July 2011 19:00:00</endts>
        <recstartts>Sat, 16 July 2011 18:29:00</recstartts>
        <recendts>Sat, 16 July 2011 19:00:00</recendts>
        <lastupdated>Sat, 16 July 2011 18:38:11</lastupdated>
            <category type="genre" name="Health"/>

Music Example

    <title>Break Your Heart</title>
    <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 don't think theres anybody as bomb as me so you can take this chance and everybody's gonna be wonderin' how you feel you might say this is Ludacris but Taio Cruz tell her how you feel.</description>
        <category type="genre" name="Hip-hop" />
        <category type="genre" name="Pop" />
        <studio name="Island" /> 
        <country name="United Kingdom" /> 
        <country name="United States of America" /> 
    <lastupdated>Tue, 01 Jul 2008 11:37:47 GMT</lastupdated>
        <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="" />
        <image type="coverart" thumb="" url="http://upload.wikimedia.org/wikipedia/en/f/fa/Taio_Cruz_Rokstarr.jpg" />

Game Example

<?xml version='1.0' encoding='UTF-8'?>
    <description>One of the most popular arcade games of all time, Pac-Man was first released in 1980 and has become a pop culture icon for that decade.</description>
      <category type="genre" name="Puzzle"/>
      <category type="genre" name="Strategy"/>
      <system>Game Boy Advance</system>
      <system>Wii Shop</system>
      <system>Atari 8-bit</system>
      <system>Neo Geo Pocket Color</system>
      <system>ZX Spectrum</system>
      <system>Commodore 64</system>
      <system>Apple II</system>
      <system>Game Gear</system>
      <system>Game Boy</system>
      <system>Atari 5200</system>
      <studio name="Atari"/>
      <studio name="Namco Bandai Games Inc."/>
      <studio name="SNK Playmore"/>
      <studio name="Thunder Mountain"/>
      <studio name="Bug-Byte Software Ltd."/>
    <lastupdated>Wed, 02 Jun 2010 11:44:18 GMT</lastupdated>
      <image type="coverart" url="http://media.giantbomb.com/uploads/8/87209/1331111-pacman_box_super.png" thumb="http://media.giantbomb.com/uploads/8/87209/1331111-pacman_box_thumb.png"/>
      <image type="screenshot" url="http://media.giantbomb.com/uploads/1/14200/946257-pm2_super.jpg" thumb="http://media.giantbomb.com/uploads/1/14200/946257-pm2_thumb.jpg"/>
      <image type="screenshot" url="http://media.giantbomb.com/uploads/1/14200/946256-pm_super.jpg" thumb="http://media.giantbomb.com/uploads/1/14200/946256-pm_thumb.jpg"/>
      <image type="screenshot" url="http://media.giantbomb.com/uploads/1/15562/496458-pac_man__1981___atari__5_super.png" thumb="http://media.giantbomb.com/uploads/1/15562/496458-pac_man__1981___atari__5_thumb.png"/>
      <image type="screenshot" url="http://media.giantbomb.com/uploads/1/15562/496457-pac_man__1981___atari__4_super.png" thumb="http://media.giantbomb.com/uploads/1/15562/496457-pac_man__1981___atari__4_thumb.png"/>

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"