RSS Specification

From DevWiki

Jump to: navigation, search

Back to Main Page


Contents



Boxee Content API

Library RSS Example

Full Boxee Library RSS Example


General

The Boxee Content API allows 3rd party content owners to push TV shows and movies into the Boxee database. The API is HTTP and XML based to allow for easy integration. The XML document format partially follows the Yahoo Media RSS (http://search.yahoo.com/mrss) with Boxee extensions.


Preparation

Every content owner that would like to use the Boxee Content API would need to sign up at the Boxee developer site. This document does not describe the full details of the developer site. The content owner will provide one or more sources that Boxee will poll to collect content catalogs. For each source, the content owner will provide: URL of the catalog XML file

  1. Optional username and password that Boxee will use when requesting the catalog.
  2. This should be used if the content owner does not want unprotected access to the file.


Protocol

Boxee servers will poll the URL or URLs that were defined by the content owner at the Boxee developer site. For security reasons and in order to avoid complicated authentication schemes, Boxee only pulls information from the content owner site and not the other way around. Boxee will go out and grab the catalog XML document using HTTP. Boxee will pass along the following in HTTP requests:

  1. In order to allow for compressed catalogs to save network bandwidth, all HTTP requests from Boxee will be sent with Accept-Encoding: gzip, deflate. The HTTP server of the content owner can decide whether to send compressed responses or not.
  2. In order to save unneeded data collection, Boxee will keep track of the Last-Modified header and will only collect XML files which are new. In the HTTP GET request, Boxee will include in the header the field If-Modified-Since along with the last date/time received from the server. The content owner web server should honor this field and return 304 (Not Modified) in case the catalog has not been changed. As an alternative to this method, Boxee will support etags as well. If the content owner web server adds an etag header to the GET response, boxee will send If-None-Match header with the received etag in following requests. If the content of the catalog has not changed, the content owner web server should respond with 304 (Not Modified).
  3. During signup (as described in section 2) the content owner had an option to provide a user/password for authentication purposes. If those have been provided, the Boxee server will access the URL over HTTP with SSL (https) and will pass along the authentication information in the header in either Simple or Digest authentication.


Catalog Document

General

The catalog document is XML/RSS based. Every item in the RSS will represent a movie or a series/show or a series/show episode with all the required meta data. An item could either represent a feature (film or full episode) or a clip (trailer, excerpt, etc). The RSS will contain the parent/child references so that boxee understands that a trailer relates to a specific movie or that a episode is of a specific show.

An RSS is for a specific language. To accommodate situations that more than one language is required, multiple RSS will be required with different language definition. The following is a definition of how specific data types should be encoded in the XML:

  1. Every element/attribute that requires a date/time should conform to the Date and Time Specification of RFC 822. For example: Sat, 07 Sep 2002 09:42:31 GMT.
  2. Every element/attribute that requires a language identifier should conform to RFC 3066. We support local languages, seperated with a dash. For example: "en" is for English while "en-us" is for English of the US.
  3. Every element/attribute that requires a country identifier should conform to ISO 3166 Alpha-2. For example "us" stands for USA, "il" stands for Israel.


RSS Format

At the top level, a RSS document is a <rss> element, with a mandatory attribute called version, that specifies the version of RSS that the document conforms to. If it conforms to this specification, the version attribute must be 2.0. The Yahoo Media RSS and Boxee RSS namespaces are required to be present. For example:

<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:boxee="http://boxee.tv/spec/rss/" xmlns:dcterms="http://purl.org/dc/terms/">

Subordinate to the <rss> element is a single <channel> element, which contains information about the channel (metadata) and its contents.


Subordinates of <channel>

This section describes elements that are direct subordinates of the <channel> element.


<title>

The name of the content owner. Can appear only once. Mandatory.

<title>Great Content LLC</title>


<description>

Text describing the content owner. Can appear only once. Mandatory.

<description>Great Content provides the best long form programming on the web!</description>


<copyright>

Copyright notice for the content owner. Can appear only once. Optional.

<copyright>2010</copyright>


<image>

URL for an image of the content owner. The image width/height should be 70x210 or larger with similar aspect ratio. If the aspect ratio is not kept, Boxee might crop the center of the image or scale it while keeping the aspect ratio. Can appear only once. Mandatory.

<image>http://greatcontent.com/img/logo.png</image>


<link>

Link to the content owner web site. Can appear only once. Optional.

<link>http://greatcontent.com/</link>


<language>

The language used throughout this catalog. Can appear only once. Optional. The default is "en-us".

<language>en-us</language>


<webmaster>

Email address of a technical contact for this catalog. Boxee will use this email to report issues that have been found in the catalog. Can appear only once. Optional.

<webmaster>webmaster@greatcontent.com</webmaster>


<lastBuildDate>

The last time the content of this catalog has changed. Conforms to the Date and Time Specification of RFC 822. Should be similar to the value returned in the HTTP header Last-Modified. Can appear only once. Optional, if the content owner server supports Last-Modified or etag (as described in section 3). Mandatory otherwise.

<lastBuildDate>Wed, 02 Jun 2010 08:00:00 EST</lastBuildDate>


<item>

A single content item. Can appear multiple times. See definition below. Mandatory.


<ttl>

ttl stands for the time to live. It's a number of minutes that indicates how long this catalog can be cache before boxee will refresh it. If this element does not appear, boxee assumes that the default would be 24 hours. Can appear only once. Optional.

<ttl>720</ttl>


<skipHours>

A hint for boxee telling which hours they can skip for catalog polling. This element contains up to 24 <hour> sub-elements whose value is a number between 0 and 23, representing a time in GMT, when Boxee will not read the channel on hours listed in the <skipHours> element. The hour beginning at midnight is hour zero. Can appear only once. Optional.

<skipHours>
  <hour>23</hour>
  <hour>24</hour>
  <hour>0</hour>
  <hour>1</hour>
</skipHours>


<skipDays>

A hint for boxee telling which days they can skip for catalog polling. This element contains up to seven <day> sub-elements whose value is Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday. Boxee will not read the channel during days listed in the <skipDays> element. Can appear only once. Optional.

<skipDays>
  <day>Monday</day>
  <day>Tuesday</day>
</skipDays>


Subordinates of <item>

This section describes elements that are direct subordinates of a <item> element. An item represents a single video/audio clip (could be in multiple representations) or a show. An audio/video clip which is part of a show must reference the show.


<guid>

Globally unique id in URL format. In order for it to be globally unique it should have the FQDN of the content owner and some kind of local id. For example: http://greatcontent.com/r2d2x. Can appear only once. Mandatory.

<guid>http://greatcontent.com/r2d2x</guid>


<link>

Link to a web site of this media item. Will be used when reporting to 3rd party such as Twitter and Facebook that a Boxee user has watched this item. Can appear only once. Optional, but highly recommended.

<link>http://greatcontent.com/r2d2x</link>


<title>

Title of the media item. Supports only plain text formatting. Can appear only once. Mandatory.

<title>The Godfather</title>


<description>

Description of the media item. Can be a few sentences in length. Supports only plain text formatting. Can appear only once. Optional.

<description>The aging patriarch of an organized crime dynasty transfers control of his clandestine empire to his reluctant son.</description>


<media:thumbnail>

Single frame thumbnail of the media item. Aspect ratio should be 2:3 with minimum size of 200x300. If the aspect ratio is not kept, Boxee might crop the center of the image or scale it while keeping the aspect ratio. Can appear only once. Optional, but highly recommended. The following attribute is required:

<medua:thumbnail url="http://greatcontent/films/4654/boxart.png" />


<boxee:media-type>

Defines the media content for this media item, whether it's a clip, a full episode, etc. Can appear only once. Mandatory. The following attributes are required:

Examples:


<boxee:content-of>

This is used to reference an item with a parent or "container" item. For an item which is a clip or trailer of a show, it must reference the GUID item of the show. For an item which is an clip or trailer of a movie, it must reference to the GUID item of the movie, if it the movie is present in the catalog. If the movie is not present in the catalog, this element is not needed as all the details of the trailer/clip can be present as part of the clip/trailer.
For example, if there is a movie called the "Star Force" will be defined in the following way (just an excerpt does not contain all required elements:

<item>
 <guid>http://efg.com/starforce</guid>
 <title>Star Force</title>
 <boxee:media-type expression="full" type="movie" name="Feature"/>
</item>

A trailer for the movie:

<item>
 <guid>http://efg.com/starforce-t1</guid>
 <title>Trailer: Star Force</title>
 <boxee:media-type expression="trailer" type="movie" name="Trailer"/>
 <boxee:content-of>http://efg.com/starforce-t1</boxee:trailer-of>
</item>

Another example: a TV show called "Found" will be defined in the following way (just an excerpt does not contain all required elements:

<item>
 <guid>http://efg.com/found</guid>
 <title>Found</title>
 <boxee:media-type expression="none" type="show" name="TV Show"/>
</item>

An episode for the show:

<item>
 <guid>http://efg.com/found-s01e01</guid>
 <title>The Great Beginning</title>
 <boxee:media-type expression="full" type="episode" name="Episode"/>
 <boxee:content-of>http://efg.com/starforce-t1</boxee:trailer-of>
</item>


<media:group> or <media:content>

A definition of the actual content. <media:group> should be used if there are multiple representations of the same video/audio in different resolutions/bit-rates. In this case multiple instance of <media:content> will appear inside <media:group>. If there is only one representation, a single <media:content> should be used directly under <item>. Mandatory for audio/video clips. Should not be used when the item represents a show, which is a "container" for episodes. Boxee recommends the following video file format, although many other formats are supported:

  1. Container of type MPEG-4 Part 14 (.mp4)
  2. Video codec of type MPEG-4 Part 10 (H.264 AVC). In order to support playback on devices with lower hardware requirements, it is recommended to use Base Profile.
  3. Audio codec of type MPEG-4 Part 3 (AAC)
  4. Some guidelines regarding bit-rate:
    • For 1080p: 7000-8000 Kbps
    • For 720p: 5000-6000 Kbps
    • For 480p: 1000-2000 Kbps
    • For 360p: 750-1500 Kbps

Boxee will use the "width" and "height" attributes to determine the video quality name. In the following manner:

This element has the following attributes:

<media:content url="http://greatcontent/films/4654/watch" type="text/html" duration="10500" height="720" width="1280" lang="en-us" />
<media:content url="http://greatcontent/watch/the_godfather.mp4" type="video/x-matroska" duration="10500" height="1080" width="1920" lang="en-us" />


<media:copyright>

Copyright information for media object. Optional.

<media:copyright>2005 FooBar Media</media:copyright>


<media:rights>

Optional element to specify the rights information of a media object.

<media:rights status="userCreated" />
<media:rights status="official" />


<media:credit>

Notable entity and the contribution to the creation of the media item. It has one mandatory attribute of the role the person has. May appear multiple times. Optional.

<media:credit role="actor">Al Pacino</media:credit>


<media:rating>

This allows the permissible audience to be declared. This is an optional element, and if not included, it assumes that no restrictions are necessary. It has an optional "scheme" attribute that defines the rating scheme. The following schemes are supported:

For example:

  1. Movie rated PG-13:
    <media:rating scheme="urn:mpaa">PG-13</media:rating>
  2. TV show rated PG:
    <media:rating scheme="urn:v-chip">PG</media:rating>


<media:restriction>

Allows restrictions to be placed on the Boxee client. Restrictions are based on country codes. This element is purely informational and no obligation can be assumed or implied. Entities in this element should be space separated. To allow the producer to explicitly declare his/her intentions, two literals are reserved: 'all', 'none'. These literals can only be used once. This element has 1 required attribute, and 1 optional attribute (with strict requirements for its exclusion).

<media:restriction relationship="allow" type="country">au us</media:restriction>


<media:price>

Optional tag to include pricing information about a media object. If this tag is not present, the media object is supposed to be free and without advertising. One media object can have multiple instances of this tag for including different pricing structures. The presence of this tag would mean that media object is not free or free to watch with advertising.

<media:price type="adsupported"/>
<media:price type="rent" price="19.99" currency="EUR"/>
<media:price type="rent" price="19.99" currency="EUR" external="true"/>
<media:price type="subscription" id="AXDW0123SAD" price="19.99" currency="EUR"/>


<media:community>

This elements stands for the community related content. This allows inclusion of the user perception about a media object in the form of view count, ratings and tags.

<media:community>
  <media:starRating average="3.5" count="20" min="1" max="10"/>
  <media:statistics views="5" favorites="5"/>
   <media:tags>news: 5, abc:3, reuters </media:tags>
</media:community>


<media:subtitle>

Optional element for subtitle/CC link. It contains type and language attributes. Language is based on RFC 3066. There can be more than one such tag per media element e.g. one per language. Please refer to Timed Text spec - W3C for more information on Timed Text and Real Time Subtitling.

<media:subTitle type="application/smil" lang="en-us" href="http://www.example.org/subtitle.smil"/>


<media:category scheme="urn:boxee:genre">

The genre of the content. May appear more than once. Optional. Should have one of the values: action, dult, adventure, animation, biography, comedy, crime, documentary, drama, family, fantasy, film noir, game show, history, horror, music, musical, news, reality tv, romance, sci fi, short, sport, talk show, thriller, war, western.

<media:category scheme="urn:boxee:genre">action</media:category>
<media:category scheme="urn:boxee:genre">drama</media:category>


<media:category scheme="urn:boxee:season">

Defines the season number for a show that has multiple seasons. Must be a numeric value. Can appear only once. Optional.

<media:category scheme="urn:boxee:season">4</media:category>

You may also use urn:tvcom:show-season

<media:category scheme="urn:tvcom:show-season"></media:category>


<media:category scheme="urn:boxee:episode">

Defines the episode number for a show episode/clip. Should be a numeric value, but in rare cases could have string values such as "pilot". Can appear only once. Required for show episodes or clips.

<media:category scheme="urn:boxee:episode">2</media:category>
<media:category scheme="urn:boxee:episode">pilot</media:category>

You may also use urn:tvcom:episode-number

<media:category scheme="urn:tvcom:episode-number"></media:category>


<media:category scheme="urn:imdb">

Defines the URL to web page for the movie, show or episode in the IMDB web site. Can only appear once. Optional, but highly recommended. For example, for "Star Wars":

<media:category scheme="urn:imdb">http://www.imdb.com/title/tt0076759</media:category>


<media:category scheme="urn:thetvdb">

Defines the URL to web page for the show or episode in the "TheTBDB" web site. Can only appear once. Optional, but highly recommended. For example, for "24" season 6:

<media:category scheme="urn:thetvdb">http://thetvdb.com/?tab=season&seriesid=76290&seasonid=16794</media:category>


<boxee:release-date>

The date/time the movie was released or the show was aired. Could be either a full date or just a 4 digit year. Can appear only once. Mandatory element.

<boxee:release-date>2008</boxee:release-date>
<boxee:release-date>Tue, 13 Nov 2008 18:20:45 EST</boxee:release-date>


<dcterms:valid>

The catalog can limit the duration in which boxee publishes the content item in the Boxee database. To enable this, the item can contain a <dcterms:valid> element and define the "start" and "end" values as shown in the following example:

<dcterms:valid>
  start=2002-10-13T09:00+01:00;
  end=2002-10-17T17:00+01:00;
  scheme=W3C-DTF
</dcterms:valid>
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox