Difference between revisions of "MythVideo Grabber Script Format"
m (mark outdated, remove category) |
m (Protected "MythVideo Grabber Script Format": Historical archive ([edit=sysop] (indefinite) [move=sysop] (indefinite))) |
(No difference)
| |
Latest revision as of 00:46, 22 November 2011
Outdated: This format is no longer in use as of the 0.24 release in Nov. 2010. Please see the MythTV Universal Metadata Format instead.
MythVideo grabber scripts are small executable perl, python, or binary applications which query online sources of metadata and return it in a format parseable by MythVideo. This page documents the current format required of the grabber scripts to function.
Contents
The Language Option (-l)
All grabber scripts must accept a -l language option. Not all grabbers offer multiple language results, but they must at least silently ignore the option. If your grabber does offer multilingual results, it is important to note that the language is passed as a two-letter ISO-639 language code. Good Practice (not required): If your grabber offers multiple languages of results, it should combine the default language with the selected language search results when applicable. An example of this is the tvdb.py script, which combines english and german results when -l de is passed. If your grabber only supports certain results and an invalid language is passed, it should fallback elegantly to the default langauge.
The Title Search Command (-M)
All scripts must provide a title search command, which takes a title as an argument and return a list of possible results. The results must be one per line, in the format:
| Command Format | SCRIPTNAME -l LANGUAGE -M TITLE |
| Command Example | ./tmdb.pl -l en -M "Harry" |
| Response Format | INETREF:TITLE |
| Response Example | 0241527:Harry Potter And The Philosopher's Stone (2001) 0304141:Harry Potter And The Prisoner Of Azkaban (2004) 0373889:Harry Potter and the Order of the Phoenix (2007) 0295297:Harry Potter And The Chamber Of Secrets (2002) 0330373:Harry Potter And The Goblet Of Fire (2005) 0216800:Harry, un ami qui vous veut du bien (2000) 0329028:Dumb and Dumberer: When Harry Met Lloyd (2003) 0118954:Deconstructing Harry (1997) 0066999:Dirty Harry (1971) 0098645:Who's Harry Crumb? (1989) 0098635:When Harry Met Sally... (1989) 0093148:Harry and the Hendersons (1987) 1201607:Harry Potter and the Deathly Hallows: Part II (2011) 0926084:Harry Potter and the Deathly Hallows: Part I (2010) 0417741:Harry Potter and the Half-Blood Prince (2009) 0048750:The Trouble with Harry (1955) |
Inetref is a number like an IMDB, TMDB, or TVDB number. It is a unique serial ID that identifies that film to the data source's API.
The Title/Subtitle Search Command (-N)
Television Grabber scripts must offer a Title/Subtitle search. If the data source does not allow for this type of search, it is acceptable to simply return nothing. The result must be in S##E## format.
| Command Format | SCRIPTNAME -l LANGUAGE -N TITLE SUBTITLE |
| Command Example | ./ttvdb.py -l en -N "Battlestar Galactica (2003)" "Water" |
| Response Format | S##E## |
| Response Example | S01E02 |
The Data Command (-D)
Each grabber must also provide a data command. The data returned includes items such as title, subtitle, year of release, and other textual metadata. Grabbers written for MythTV .23 or greater should also return image results for coverart, fanart, banners, and screenshots (where available). This command varies slightly depending on whether the script is for TV or Film material. For Television Material, the season and episode numbers are added to the arguments.
| Command Format (FILM) | SCRIPTNAME -l LANGUAGE -D INETREF |
| Command Example (FILM) | ./tmdb.pl -l en -D 0241527 |
| Command Format (TELEVISION) | SCRIPTNAME -l LANGUAGE -D INETREF SEASONNUM EPISODENUM |
| Command Example (TELEVISION) | ./ttvdb.py -l en -D 73739 5 1 |
| Response Format | KEY:DATA |
| Response Example | Title:Lost Subtitle:Because You Left Season:5 Episode:1 Year:2009 Director:Stephen Williams Plot:The remaining island survivors start to feel the effects of the aftermath of moving the island, and Jack and Ben begin their quest to reunite the Oceanic 6 in order to return to the island with Locke's body in an attempt to save their former fellow castaways. UserRating:7.9 Screenshot:http://www.thetvdb.com/banners/episodes/73739/382841.jpg InetRef:73739 Cast:Matthew Fox, Evangeline Lilly, Naveen Andrews, Elizabeth Mitchell, Michael Emerson, Terry O'Quinn, Daniel Dae Kim, Yunjin Kim, Josh Holloway, John Terry, Andrew Divoff, Sam Anderson, L. Scott Caldwell, Nestor Carbonell, Kevin Durand, Jeff Fahey, Tania Raymonde, Mira Furlan, Alan Dale, Sonya Walger, Rebecca Mader, Ken Leung, Jeremy Davies, Kiele Sanchez, Rodrigo Santoro Genres:Action and Adventure, Drama, Science-Fiction Runtime:45 |
Valid Key:Data Pairs
The following table illustrates valid values that can be returned by the grabber script, and explains the necessary formatting. None of the values are required.
| Title | The title of the film or program. | Text |
| Subtitle | The subtitle of the film or program. | Text |
| Year | The release or transmission date of the film or program. | Integer Value |
| ReleaseDate | A YYYY-MM-DD format release date for the item. | Text/Date |
| InetRef | The serial number/key value used to identify the movie to the API/site. Examples are IMDB nmber, TMDB number, etc. Note: Returning InetRef overwrites the previous InetRef. You should only return it if you know what you are doing, such as attempting to transition from one numbering type to another. | Integer Value or String |
| URL | A URL to open in a web browser for the item grabbed. Most scripts return the item's page at the data source. | String/Web Address |
| Director | The Director of the queried item. | Text |
| Plot | The Plot/Description of the queried item. | Text |
| UserRating | The rating of the item by the data source's users. | Floating Point number 0-10.0 |
| MovieRating | The classification/Film Rating of the item (eg G, PG, PG-13, R) | Text |
| Runtime | The playing time of the item. | Integer |
| Season | The Season of the item. | Integer |
| Episode | The episode number of the item. | Integer |
| Coverart | The Coverart/Poster download URLs for the item. Multiple values can be returned, and should be separated by commas. | comma-separated URLs |
| Fanart | The Fanart download URLs for the item. Multiple values can be returned, and should be separated by commas. | comma-separated URLs |
| Banner | The Banner download URLs for the item. Multiple values can be returned, and should be separated by commas. | comma-separated URLs |
| Screenshot | The Screenshot download URLs for the item. Multiple values can be returned, and should be separated by commas. | comma-separated URLs |
| Cast | The Cast for the item. Multiple values can be returned, and should be separated by commas. | comma-separated text |
| Genres | The Genres for the item. Multiple values can be returned, and should be separated by commas. | comma-separated text |
| Countries | The production countries for the item. Multiple values can be returned, and should be separated by commas. | comma-separated text |
The Version Command (-v)
Your script must return a version string which is used in the Myth interface to identify it. -v is lower case and case sensitive. The current format looks something like this:
themoviedb Query (v0.1.1) by William Stewart, Stuart Morgan
Adding a new script
To test your script, you can add it to the /usr{/local}/share/mythtv/mythvideo/scripts/Television or /usr{/local}/share/mythtv/mythvideo/scripts/Movie directories, depending on its purpose. Assuming your script is executable, and responds properly to a -v version command, it should now appear in the User Interface as a valid option. Please remember to submit your script at http://svn.mythtv.org so that others can enjoy it! Note that any official grabber scripts must comply with the terms or service (TOS) of the data service from which they grab. If the site prohibits scraping/grabbing, then the script cannot be distributed with MythTV.
