Metadata

From pyTivo - Wiki

Jump to: navigation, search

A pyTivo metadata file is a text file that is located in the same folder as the associated video file. It must have the same name as the video file along with a .txt extension. An example is if you have a video file called myVideo.avi, you will have to name your metadata file as: myVideo.avi.txt

Optionally, if a metadata file named default.txt exists, the settings in it will be used as defaults for all of the video files within that directory/folder. And if you don't like the .txt files cluttering your video directory, you may create a .meta subfolder within each directory and move your txt to the .meta subfolder.

For example, if you have a folder dedicated to a series, it'd be desirable to have the following fields in default.txt: seriesTitle, isEpisode (true), seriesId, displayMajorNumber, callsign, tvRating, showingBits, vProgramGenre, vActor, vExecProducer, vProducer, vHost. With those stored as defaults, one could add minimal episode-specific overrides such as episodeTitle, episodeNumber, tvRating, showingBits; additional vActor and vProducer fields; and fields without defaults such as vGuestStar.

Also, if a file with the extension .nfo is found, it is also used as metadata. .nfo files are created for use with XBMC, another media server but pyTivo can now read it's metadata files.

  • A GUI called MetaGenerator3 exists to create metadata files using data pulled from the Web and its database
  • Another GUI called PyTivoMetaGen exists to create metadata files semi-automatically from .TiVo files
  • Other video processing programs such as kmttg and VideoReDoAutoProcessor (VAP) can automatically generate pyTiVo metadata files.

Only a subset of metadata keywords are used in "Push" mode.

Here is a list of the items that pyTivo can send to the TiVo and a description of what each does. Please note that in the file each line must formatted as: keyword: value, for example: title: As Good As It Gets.

Contents

Keywords

time

This is the time and date the file was recorded by a TiVo. The TiVo uses this to determine the recording's place in a date-sorted list. The format is the same as originalAirDate, below, and the same rules apply, with two special exceptions: a value of "File" tells pyTivo to use the file's time stamp, while a value of "OAD" tells it to use the originalAirDate. These values are intended for use with default.txt.

Field must have a value present or be omitted from the document completely. If field is present with no value entered, common error* occurs. If field is omitted, all the other information will be intact, and the current time and date (the time and date you instructed the TiVo to retrieve the information from pyTiVo) adjusted based on your location relative to GMT.

originalAirDate

This must be entered as yyyy-mm-ddThh:mm:ssZ (the t is capitalized and never changes, the Z is also capitalized and never changes). This is the original air date of the episode. It must be filled in completely. Whether or not the info is correct doesn't matter, as long as it's formatted properly. TiVo adjusts this value back based on your time zone relative to GMT. So, for example, if you live in GMT-6 (US Central Time) and you enter this value as 2007-12-08T04:30:00Z, TiVo will show the original air date as being December 7th, 2007 at 10:30pm. Consequently, if you want this date to show as December 1, 2005 at 12:00AM, and you live in US Central Time, you would fill in this field as 2005-12-01T06:00:00Z.

Field must have a value present or be omitted from the document completely. If field is present with no value entered, common error* occurs. If field is omitted, all the other information will be intact, and the current date will be used for the original air date.

movieYear

This must be entered as yyyy. This is the original air date of the movie. Whether or not the info is correct doesn't matter. One should use movieYear for movies instead of originalAirDate (which is for television programs).

seriesTitle

Name of series (The Simpsons, Seinfeld, etc.). This should be included if the show is episodic. For movies, you may repeat the name of the movie (The Mummy, Spiderman, etc), leave blank, or omit.

title

For a movie, use the title of the movie (The Mummy, Spiderman, etc). For a TV series, use the title of the series (The Simpsons, Seinfeld, etc.) followed by a dash and the episode title. For example: "The Simpsons - Treehouse of Horror". This is the text that will show up in your transfer folder. A seemingly endless number of characters can be entered. Only so many will be shown on the Program screen, but all are shown on the Details screen.

episodeTitle

Title of the episode (Pilot, Homer's Night Out, Episode 02, etc.) Should be included for episodic shows. Leave blank or omit for movies.

description

Write the synopsis of the video here. No ill effects if left blank or omitted. Seemingly endless number of characters can be entered, only so many will be shown on the Program screen, but all are shown on the Details screen.

isEpisode

Must be entered as true or false. If true, the year from originalAirDate will be shown in parentheses after the episode’s title and before the description on the Program screen. If false, the year will not appear. Does not affect grouping based on seriesId. No capital letters. Capitalizing will cause the common error*. Leaving field blank will cause the common error*. Can be omitted with no ill effects.

seriesId

Usually starts with "SH" and followed by 6-8 digits. TiVo uses this to allow for grouping once a program is transferred to a TiVo, provided the TiVo is set to grouping in the NPL (Now Playing List). Leaving this field blank or omitting doesn’t seem to cause any problems, except when it comes time to group when transferring to TiVo. Will not group without a series ID.

  • SH is for general TV shows.
  • MV is for movies (e.g. Amazon Unbox).
  • SP is for sports.
  • TS is for Tivocast content.

SeriesId can be located at zap2it.com for a show. These values will all start with EP and must be changed to SH before using.

episodeNumber

This should be entered for episodic shows and omitted for movies. The standard tivo format is to enter the season number followed by the episode number for that season. For example, enter 201 for season 2 episode 01. This only shows up if you go into the Details from the Program screen. This seems to disappear once the video is transferred to TiVo. But it is very helpful in determining the next episode you need to transfer to the tivo for viewing. Some versions of pytivo also use this field to add the episode number to the title so that it is not lost during transfer. Field must have value present or omitted from the document completely. If field is present with no value entered, common error* occurs. No more than 9 numeric characters may be entered. If more then 9 are entered, or non-numeric characters are included (spaces, letters, punctuation, etc.), common error* occurs.

displayMajorNumber

This is the channel the episode was recorded from. Field must have value present or omitted from the document completely. If field is present with no value entered, common error* occurs. Value will not be displayed on Program screen unless callsign value is entered as well. No more then 5 digits will be displayed. If more than 5 digits are entered, a seemingly random five-digit number will be displayed in its place.

callsign

This is the call sign of the channel the episode was recorded from. You can enter anything here, leave it blank or omit it from the document with no ill consequences. Only 7 characters will be displayed. However, it shares space with the displayMajorNumber field, and displayMajorNumber gets first priority. If displayMajorNumber has all 5 of its allowed characters entered, only 3 of the callsign digits are displayed, followed by an ellipsis. If only 4 of displayMajorNumber’s allowed characters are entered, 4 of callsign’s digits are displayed. When only 3 of displayMajor’s allowed characters are entered, all 7 of callsign’s digits will be displayed.

showingBits

This tells the TiVo to display various combinations things in parentheses at the end of the description. It only accepts numerical digits, if any alpha digits are entered, common error* occurs. Field must have a value present or be omitted from the document completely. If field is present with no value entered, common error* occurs. More than one field can be present in one document, but only the last value will be used, any preceding will be ignored. The field is the sum of the following values:

  • 1 = CC
  • 2 = Stereo
  • 4 = Sub (subtitled)
  • 8 = In Prog
  • 16 = Class (classroom)
  • 32 = SAP
  • 64 = Blackout
  • 128 = Intercast
  • 256 = Three D
  • 512 = R (repeat)
  • 1024 = Letterbox
  • 4096 = HD (High Definition)
  • 65536 = S (sex rating)
  • 131072 = V (violence rating)
  • 262144 = L (language rating)
  • 524288 = D (dialog rating)
  • 1048576 = FV (fantasy violence rating)

displayMinorNumber

This doesn’t seem to do anything. Field must have value present or omitted from the document completely. If field is present with no value entered, common error* occurs.

tvRating

The standard U.S. TV rating system rating. This is shown on both the Program screen and the Details screen. One of the following values should be used:

  • Y7
  • Y
  • G
  • PG
  • 14
  • MA
  • NR

Case is not significant. pyTivo will recognize these with or without the "TV-" prefix.

In the past, pyTivo used a different format for tvRating; and third-party programs sometimes generate other variants. pyTivo attempts to recognize as many of these as possible, but if you have the choice, they should not be used. Use the list above.

starRating

This is shown on both the Program screen and the Details screen. Use one of the following values:

  • 1
  • 1.5
  • 2
  • 2.5
  • 3
  • 3.5
  • 4

You can also use strings of asterisks for the whole-number ratings. Other values should not be used. pyTivo will attempt to recognize some other formats, but they're deprecated. Values not rounded to the half point, cause an error. Remaining metadata is not processed if a numeric error (ie, 1.3) is found.

mpaaRating

The MPAA rating, for theatrical movies. This is shown on both the Program screen and the Details screen. Use one of the following values:

  • G
  • PG
  • PG-13
  • R
  • X
  • NC-17
  • NR

Case is not significant. Some other variants are recognized, but they're deprecated.

colorCode

This is shown on the Details screen. It uses the second character to determine the color mode. The list is as follows:

  • x1 = B & W
  • x2 = Color and B & W
  • x3 = Colorized
  • x4 = Color Series

vProgramGenre

This field can be repeated as many times as necessary or omitted completely. Only the first two entries will show up on the Program screen, but all the rest will show up on the Details screen from the Program screen. I don't know what the limit is, I tried 24 and they all showed up on the Details screen. If field(s) are left blank, an appropriate number of commas will show up on the Details screen. Seemingly unlimited number of characters can be entered, only so many will show up on the Program Screen, all will show up on the Details screen.

These values will show up when viewing files on your server, but once transferred to TiVo, they seem to disappear.

vSeriesGenre

This doesn't seem to show up anywhere. I suspect that TiVo uses these values when deciding on what programs to recommend or other internal functions. Can be left blank or omitted with no ill effects.

vActor

This shows up at the beginning of the description on the Program screen and on the Details screen. Only one value per field (no commas allowed), but many fields can be entered. Can be left blank or omitted with no ill effects. Seemingly endless number of characters can be entered, only so many will show up on the Program screen, only 72 will show up for each entry on the Details screen.

While one can put the name in common order, the internal TiVo custom is to enter as:

  • lastname|firstname
  • lastname modifier|firstname (e.g. "Begley Jr.|Ed")
  • lastname|firstname middlename (e.g. "Brooks|James L.", "Olmos|Edward James")
  • multi lastname|firstname (e.g. "de Ravin|Emilie")
  • lastname|initial firstname (e.g. "Fitzgerald|L. Scott", "Gainey|M. C.")
  • onename| (e.g. "Coolio|")
  • title|firstname (e.g. "the Entertainer|Cedric")
  • band name|

vGuestStar, vDirector, vExecProducer, vProducer, vWriter, vHost, vChoreographer

All of these show up only on the Details screen, not on the Program screen. Only one value per field (no commas allowed), but many fields can be entered. Seemingly endless number of characters can be entered, only so many will show up on the Program screen, only 72 will show up for each entry on the Details screen. Can be left blank or omitted with no ill effects.

partCount

May be included if it is a multipart episode. If applicable, both must be included. Example metadata, partCount : 2, partIndex : 1. Will appear on the tivo info screen as "Part Index 1 of 2".

partIndex

May be included if it is a multipart episode. If applicable, both must be included. Example metadata, partCount : 2, partIndex : 1. Will appear on the tivo info screen as "Part Index 1 of 2".

Example Episodic metadata

title : Dharma & Greg
seriesTitle : Dharma & Greg
episodeTitle : See Dharma Run
episodeNumber : 216
isEpisode : true
description : Dharma runs for office; Pete and Jane fight the blues on St. Valentine's Day.
seriesId : SH225826
originalAirDate : 1999-02-10T00:00:00Z
time : 2009-01-01T16:30:00Z
displayMajorNumber : 111
callsign : WE
showingBits : 262659
tvRating : x5
partCount : 2
partIndex : 1
vProgramGenre : Holiday
vProgramGenre : Sitcom
vProgramGenre : Valentine's Day
vDirector : Berlinger|Bob
vActor : Elfman|Jenna
vActor : Gibson|Thomas
vActor : Kennedy|Mimi
vActor : Rachins|Alan
vActor : Sullivan|Susan
vActor : Ryan|Mitchell
vActor : Murray|Joel
vActor : D'Lyn|Shae
vSeriesGenre : Sitcom
vSeriesGenre : Comedy

Example Movie metadata

title : It's a Wonderful Life
seriesTitle : It's a Wonderful Life
episodeTitle : 
movieYear : 1946
isEpisode : false
description : (1946) Ruined by a miser on Christmas Eve, a suicidal family man sees life anew thanks to his guardian angel.
seriesId : MV004401
time : 2008-12-14T01:00:00Z
displayMajorNumber : 5-1
callsign : KSDKDT
showingBits : 3
starRating : x7
tvRating : x3
vProgramGenre : Comedy
vProgramGenre : Drama
vProgramGenre : Holiday
vProgramGenre : Christmas
vDirector : Capra|Frank
vProducer : Capra|Frank
vActor : Stewart|James
vActor : Reed|Donna
vActor : Barrymore|Lionel
vActor : Mitchell|Thomas
vActor : Travers|Henry
vActor : Bondi|Beulah
vActor : Faylen|Frank
vActor : Bond|Ward
vActor : Grahame|Gloria
vActor : Warner|H.B.
vActor : Albertson|Frank
vActor : Karns|Todd
vActor : Hinds|Samuel S.
vActor : Leonard|Sheldon
vActor : Corby|Ellen
vActor : Patton|Virginia
vActor : Treen|Mary
vActor : Williams|Charles
vActor : Edwards|Sarah
vActor : Edmunds|William
vSeriesGenre : Comedy
vSeriesGenre : Drama
vSeriesGenre : Holiday
vSeriesGenre : Christmas
vSeriesGenre : Interests
vSeriesGenre : Comedy
vSeriesGenre : Drama
vSeriesGenre : Movies

Common Errors

Common Error: TiVo will not display all the information correctly or at all when a field is missing, improperly configured, or left blank. The symptoms of this are:

  1. The top of the Program screen displaying the episode title instead of the series title.
  2. The episode title not being displayed in the synopsis area.
  3. The original air year not being displayed in the synopsis area (normally in parentheses), and the original air date not displayed on the Details screen.
  4. No program genre information displayed on the Program screen or the Details screen.
  5. Other things that I can't remember off the top of my head, but those are the major, most noticeable ones.

Seemingly not implemented

  • recordingQuality (always 75 [High])
  • vAdvisory (e.g. 1=AL)
Personal tools
Get pytivo at SourceForge.net. Fast, secure and Free Open Source software downloads