RSS Specification
From DevWiki
Overview
RSS – "Really Simple Syndication" – is a mechanism for web site developers to publish headlines and frequently-updated content as a web feed. A web feed is a low-bandwidth, stripped down version of a web site that readers can subscribe to in a feed reader or that developers can parse and manipulate for their own use. There are a number of competing technical formats for feeds on the web including several different incompatible versions of RSS and a competing format called Atom.
Boxee can read and manage many different types of rss/mrss feeds. However, to ensure all your metadata is processed correctly, its best to use the Boxee RSS Specification. Highly customizable, with the ability to add custom values to each item that can later be used/retrieved from within your application. Such custom tags are useful for text/data you want to display in your application but doesn't really fit in any standard RSS tag.
Namespace
The following namespaces are used:
- Yahoo Media RSS (URI: http://search.yahoo.com/mrss/). Required, namespace prefix “media”.
- Boxee Media RSS (URI: http://boxee.tv/spec/rss/). Optional, namespace prefix “boxee”.
<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:boxee="as http://boxee.tv/spec/rss/">
Primary Elements
This section describes how Boxee processes and parses RSSs, Media RSS and Boxee specific RSS tags.
<rss>
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 namespace is defined here.
<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:boxee="as http://boxee.tv/spec/rss/">
<channel>
Subordinate to the <rss> element is a single <channel> element, which contains information about the channel (metadata) and its contents.
<channel> <title>My Boxee Youtube Videos</title> <link>http://www.youtube.com/</link> <description>My favorite Boxee related videos from Youtube!</description>
<item>
Each individual item (media file/title) should be wrapped in its own item tag (<item>...</item>).
<title>
Sub-element of either <channel> or <item>. It is used to display the title of the window or item in the Boxee UI.
<title>The Future of Boxee</title>
<link>
Sub-element of <item>. Should be used only to reference/link to a child (directory) rss listing. The URL in the link tag needs to use the rss:// protocol. This tag should not be used to link to media itself, only another rss link.
<link>rss://www.metacafe.com/rss.xml</link>
<media:content>
Sub-element of <item>. Used to link to any media file (use <link> if linking to rss feed). Only one media:content element should appear per item. The following attributes are supported:
- url - Url of the media object. Supports only the http:// and flash:// protocol. The flash:// protocol is Boxee specific and defined in another section of the document. However for urls that contain a flash object that you want to play, please use http:// unless you need to perform specific actions described at the bottom of this page.
- type - The content type of the media object. Most video/* and audio/* content types are supported for video and audio, respectively. For Flash content use the application/x-shockwave-flash content type. For Microsoft Silverlight use the application/x-silverlight or application/x-silverlight-2 content type. For downloadable Torrent files use the application/x-torrent content type.
- duration - The duration of the media in seconds.
<media:content url="http://www.youtube.com/watch?v=al6IKc6eP9E" type="application/x-shockwave-flash" />
Optional Elements
Below describes all the optional rss tags that can be used. Remember the more data you can include in your feeds, the richer the experience can be for the user.
<description>
Sub-element of <item>. Used to display the description, plot or synopsis of an item. Only plain text is supported. If HTML tags are present, they are silently removed.
<description>The best video ever!</description>
<pubDate>
Sub-element of <item>. Used to set the "Release Date" of an item in Boxee. This date is displayed and can be used to sort items. The date format should conform to RFC 822. Optional.
<pubDate>Mon, 27 Aug 2001 16:08:56 PST</pubDate>
<media:thumbnail>
Sub element of <item>. Allows particular image to be used as representative image for the media object. Only one <media:thumbnail> element should appear per item. If more than one elements is presented, Boxee picks one of them. Please do not rely on this heuristics as it may change between versions of Boxee.
- url - Url of the thumbnail. Supported thumbnail formats are: JPEG, GIF and PNG. For animated GIF, only the first frame is displayed. Only the http:// protocol is supported.
<media:thumbnail url="http://mysite.com/thumbnail.png" />
<media:credit>
Sub-element of <item>. Notable entity and the contribution to the creation of the media object. The following attributes are supported:
- role - specifies the role the entity played. The following roles are supported:
- actor
- director
- writer
- arist
- author
<media:credit role="actor">Al Pacino</media:credit>
<media:rating>
Sub-element of <item>. Defines the rating of the media item. Optional. The following attributes are supported:
- scheme - the scheme used for the rating. The following schemes are supported:
- urn:mpaa - MPAA rating of a movie or clip
- urn:tv - TV rating of a TV video or clip
- urn:user - user rating of the media item in scale from 1 to 10
<media:rating schema="urn:user">7.2</media:rating> <media:rating schema="urn:mpaa">PG-13</media:mpaa>
<media:copyright>
Sub-element of <item>. Copyright information for media object, usually the name of the studio.
<media:copyright>Universal Studios</media:copyright>
<media:keywords>
Sub-element of <item>. Highly relevant keywords describing the media object with typically a maximum of ten words. The keywords and phrases should be comma delimited.
<media:keywords>fail,epic fail,fall,break,painfull,funny</media:keywords>
<media:category>
Sub-element of <item>. Allows a taxonomy to be set that gives an indication of the type of media content, and its particular contents. Optional. The following attributes are supported:
- scheme - The category scheme. The following schemes are supported:
- urn:boxee:genre - the genre of the media item.
- urn:boxee:title-type - the media item title type. For this scheme the following values are allowed: tv or movie.
- urn:boxee:episode - the episode number for a TV show.
- urn:boxee:season - the season number for a TV show.
- urn:boxee:show-title - the title of the TV show or movie when the item is an episode or a clip. In this case the <title> element holds the title of the episode or clip.
- urn:boxee:view-count - the number of views this media item had.
- urn:boxee:source - a label that represents the source of the video. For example: Hulu or Netflix. This label will be used when a user clicks on recommended item generated by this RSS item. The menu will then show "Play from <source>" for example "Play from Netflix".
<media:category scheme="urn:boxee:genre">Drama</media:category> <media:rating category="urn:boxee:title-type">tv</media:category> <media:rating category="urn:boxee:episode">4</media:category> <media:rating category="urn:boxee:season">3</media:category> <media:rating category="urn:boxee:show-title">Lost</media:category> <media:rating category="urn:boxee:view-count">48972</media:category> <media:category scheme="urn:boxee:source">Netflix</media:category>
Boxee Elements
Boxee specific elements - All elements here are optional.
<boxee:expiry>
Sub-element of <channel>. Boxee keeps a cache of all RSS documents loaded. The cache is cleared every time Boxee is restarted. By default, the RSS is cached for 10 minutes. However, the RSS can define for how much time it should be cached. For example, RSS that returns queue items should not be cached but rather fetched every time Boxee requests. This element is used to specify in minutes for how much time this RSS should be cached. Setting a value of 0 means that the RSS should not be cached.
<boxee:expiry>60</boxee:expiry>
<boxee:background-image>
Sub-element of <channel>. Background image that will be displayed behind the RSS. This gives a richer experience to the user. The image should be of size 1280×720. Larger/smaller images will be scaled to 1280×720.
<boxee:background-image>http://www.wallpapers.net/wallpapers/snow_leopard-1280x720.jpg</boxee:background-image>
<boxee:alternative-link>
Sub-element of <item>. As noted before, the <media:content> element defines which is played when the Play button is pressed. However, sometimes, there are additional items that could be played or displayed. For example, if a video is available in multiple resolutions. The user will still see only one item in the list of items, however, the “Action Menu” which is displayed after Play is pressed will contain additional options after the “Play” and “Read More” options. Multiple elements of this type is allowed. The following attributes are supported:
- label the label which will be displayed in the Boxee user interface. For example: “Play in HD”. Required.
- thumb a URL of a thumbnail that will be displayed next to the above label. Reqruired.
- url a URL to the media that will be played when this item is selected.
<boxee:alternative-link url="http://myvideo.com/video_720.mov" thumb="http://myvideo.com/images/720.png" label="Watch in 720p" />
<boxee:image>
Can be used for thumbnails in place of <media:thumbnail>
<boxee:image>http://myvideo.com/movie/thumbs/1435.png</boxee:image>
<boxee:interval>
Sub element of <channel>. Sets the feed check interval.
<boxee:interval val="60" />
<boxee:category>
Sub element of <channel>. Sets the feed category.
<boxee:category name="Video" />
<boxee:user_agent>
Sub element of <item>. Sets the user_agent for the given item.
<boxee:user_agent>Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.6) Gecko/20091201 Firefox/3.5.6</boxee:user_agent>
<boxee:content_type>
Sub element of <item>. Sets the content_type for the given item.
<boxee:content_type>tv</boxee:content_type>
<boxee:view-count>
Sub element of <item>. Sets the view-count for the given item.
<boxee:view-count>3265</boxee:view-count>
<boxee:episode>
Sub element of <item>. Sets the episode for the given item.
<boxee:episode>3</boxee:episode>
<boxee:season>
Sub element of <item>. Sets the season for the given item.
<boxee:season>4</boxee:season>
<boxee:tv-show-title>
Sub element of <item>. Sets the tv-show-title for the given item.
<boxee:tv-show-title>Lost</boxee:tv-show-title>
<boxee:release-date>
Sub element of <item>. Sets the release-date for the given item.
<boxee:release-date>10-25-2006</boxee:release-date>
<boxee:release-year>
Sub element of <item>. Sets the release-year for the given item.
<boxee:release-year>1979</boxee:release-year>
<boxee:imdb-id>
Sub element of <item>. Sets the imdb-id for the given item.
<boxee:imdb-id>tt0850964</boxee:imdb-id>
<boxee:plot>
Sub element of <item>. Sets the plot for the given item.
<boxee:plot>The Others perform a sadistic medical procedure on Sawyer in order to prevent him from causing any more mischief.</boxee:plot>
<boxee:plot-summary>
Sub element of <item>. Sets the plot-summary for the given item.
<boxee:plot-summary>Sawyer discovers just how far his captors will go to thwart any plans of escape he and Kate might have when they forcibly and surgically implant a pacemaker in his heart which will detonate if he tries to escape again. Jack is called upon to scrub up in order to save the life of one of "The Others,", a team leader, named Colleen, who was shot by Sun during the theft of the sailboat.</boxee:plot-summary>
<boxee:user-rating>
Sub element of <item>. Sets the user-rating for the given item.
<boxee:user-rating>8.3</boxee:user-rating>
<boxee:cast>
Sub element of <item>. Sets the cast for the given item.
<boxee:cast>Matthew Fox</boxee:cast>
<boxee:producers>
Sub element of <item>. Sets the producers for the given item.
<boxee:producers>J.J. Abrams</boxee:producers>
<boxee:directors>
Sub element of <item>. Sets the directors for the given item.
<boxee:directors>Stephen Williams</boxee:directors>
<boxee:provider>
Sub element of <item>. Sets the provider id for the given item.
<boxee:provider>netflix</boxee:provider>
<boxee:provider-name>
Sub element of <item>. Sets the provider-name for the given item.
<boxee:provider-name>Netflix</boxee:provider-name>
<boxee:provider-thumb>
Sub element of <item>. Sets the provider-thumb for the given item.
<boxee:provider-thumb>http://netflix.com/images/thumb.png</boxee:provider-thumb>
<boxee:country-allow>
Sub element of <item>. Sets the country-allow for the given item.
<boxee:country-allow>US</boxee:country-allow>
Flash Protocol
ATTENTION - flash:// links are not required to play flash/silverlight/move video. Please use normal http links for most cases. Use flash:// links only to specify bx-ourl and bx-jsactions if needed - everything else should be done via the Boxee JavaScript API.
Media URLs supports two protocols: http:// and flash://. This section describes the format and parameters of URLs with the flash:// protocol.
In the host name portion of the URL, specify an identifier for the flash player. This could be any identifier and is not currently used by Boxee. For example, the player of Hulu could have the “hulu.com” in the host name.
In the file name portion of the URL there are several parameters which can be defined. The parameters should be encoded like an HTTP GET query string in format: key=value1&key2=value2 etc. The values must be encoded according to RFC 1738 in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits.
The following keys are supported in the query string:
- src Required. The full URL of the flash content including all query string paramters.
- width Optional. Width of the original Flash stage. Required for using bx-crop.
- height Optional. Height of the original Flash stage. Required for using bx-crop.
- bx-croptop Optional. Number of pixels to crop from the top when displaying in Boxee.
- bx-cropbottom Optional. Number of pixels to crop from the bottom when displaying in Boxee.
- bx-cropleft Optional. Number of pixels to crop from the left when displaying in Boxee.
- bx-cropright Optional. Number of pixels to crop from the right when displaying in Boxee.
- bx-ourl Optional. When Boxee reports in the web site or Twitter about actions, it provides a link to a HTML page of that content. This parameter should include the URL for the original content. If case this parameter is not passed, the src URL is displayed.
- bx-jsactions Optional. URL of a JavaScript file that is downloaded and executed by the Boxee Flash/Silverlight/Move player and is used to control actions during the playback of the file. The JavaScript has several functions which are called by the player and in turn they can call the player to retrieve information during the playback. See Boxee JavaScript API below for details.
For example, we want to create link to http://joost.com/embed/13600fs?autoplay=true, width is 480, height is 360, we don’t want to crop any pixels, and the original URL was http://joost.com/13600fs. After encoding both URLs, we get:
flash://joost.com/src=http%3A%2F%2Fjoost.com%2Fembed%2F13600fs%3Fautoplay%3Dtrue&width=480&height=360&ourl=http%3A%2F%2Fjoost.com%2F13600fs
Since this data resides in an XML, we need to encode the & to &:
flash://joost.com/src=http%3A%2F%2Fjoost.com%2Fembed%2F13600fs%3Fautoplay%3Dtrue&width=480&height=360&ourl=http%3A%2F%2Fjoost.com%2F13600fs
Example
<?xml version="1.0" encoding="utf-8"?> <rss version="2.0" xmlns:boxee="http://boxee.tv/rss" xmlns:media="http://search.yahoo.com/mrss/"> <channel> <title>New choices to watch instantly</title> <link>rss://dir.boxee.tv/apps/netflix/new</link> <description>New choices to watch instantly</description> <language>en-us</language> <item> <title>1941</title> <guid>http://api.netflix.com/catalog/titles/movies/206584</guid> <description>In the days after the Japanese attack on Pearl Harbor, panic sets in among California's citizens, who imagine their shores as the next target.</description> <media:content url="http://www.netflix.com/Movie/1941/206584" type="application/x-silverlight"/> <media:thumbnail url="http://cdn-4.nflximg.com/us/boxshots/ghd_ste/206584.jpg"/> <boxee:runtime>2:26:00</boxee:runtime> <media:rating schema="urn:user">6.4</media:rating> <boxee:property name="avgrating">6</boxee:property> <media:category scheme="urn:boxee:source">Netflix</media:category> <boxee:release-date>1979</boxee:release-date> <media:rating schema="urn:mpaa">NR</media:rating> <media:credit role="actor">John Belushi</media:credit> <media:credit role="actor">Dan Aykroyd</media:credit> <media:credit role="actor">John Candy</media:credit> <media:credit role="director">Steven Spielberg</media:credit> <media:category scheme="urn:boxee:genre">Comedy</media:category> <media:category scheme="urn:boxee:genre">Spoofs and Satire</media:category> <media:category scheme="urn:boxee:genre">Screwball</media:category> <media:category scheme="urn:boxee:genre">Universal Studios Home Entertainment</media:category> </item> <item> <title>Amarcord</title> <guid>http://api.netflix.com/catalog/titles/movies/247784</guid> <description>A traditional seaside village during the uncertainty of Mussolini's fascist rule. Fellini drew from personal experience to bring the small town and all its colorful characters to life in this story about the escapades of a boy on the cusp of becoming a man.</description> <media:content url="http://www.netflix.com/Movie/Amarcord/247784" type="application/x-silverlight"/> <media:thumbnail url="http://cdn-4.nflximg.com/us/boxshots/large/247784.jpg"/> <boxee:runtime>2:03:00</boxee:runtime> <media:rating schema="urn:user">7.2</media:rating> <boxee:property name="avgrating">7</boxee:property> <media:category scheme="urn:boxee:source">Netflix</media:category> <boxee:release-date>1974</boxee:release-date> <media:rating schema="urn:mpaa">R</media:rating> <media:credit role="actor">Pupella Maggio</media:credit> <media:credit role="actor">Armondo Brancia</media:credit> <media:credit role="actor">Magali Noel</media:credit> <media:category scheme="urn:boxee:genre">Foreign</media:category> </item> </channel> </rss>
