Metadata

From pyTivo - Wiki

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.

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

Title of the series (The Simpsons, Seinfeld, etc.) or title of the movie (The Mummy, Spiderman, etc). 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.

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