Zinc RSS Specification

ZeeVee Zinc® uses RSS as the document format for supporting third party content. If you are reading this document, chances are that you have decided to support Zinc with your website.

If you already understand RSS and are looking for a quick tutorial on understanding how Zinc uses RSS, you might want to first start with our tutorial.

If you manage a large site with many different feeds, you might want to read the tutorial for websites.

If you have a search engine for your site, you may integrate with Zinc using opensearch protocol. See our opensearch tutorial for more information.

Version history

• 1.0: 3/28/2009

namespace requirements

• Required: At a minimum, your RSS document should correspond to the RSS 2.0 specification.

• Better: For better support of thumbnails and media playback, your RSS feed should also support the Media RSS extensions. Media RSS is required for thumbnails to display properly in Zinc. The namespace is xmlns:media="http://search.yahoo.com/mrss/"

• Best: Zinc has created our set of extensions to support additional information about video content. The required namespace definition is xmlns:zv="http://pc.zinc.tv/zinc/2009"

Example:

<xml version="1.0" encoding="utf-8">
<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:zv="http://pc.zinc.tv/zinc/2009">

Zinc also supports a number of other third party namespaces, primarily for displaying additional information on videos such as duration, ratings, etc.

• Atom: namespace http://www.w3.org/2005/Atom
• Google: namespace http://schemas.google.com/g/2005
• Search video (Truveo): namespace http://www.searchvideo.com/schemas/av/1.0
• Youtube: namespace http://gdata.youtube.com/schemas/2007

• OpenSearch: namespace "http://a9.com/-/spec/opensearch/1.1/". Opensearch is used by Zinc for specifying a search URL and retrieving search responses from an external server.

• Boxee: namespace http://boxee.tv/spec/rss/

Best practices and data quality

• All embedded HTML is stripped and sanitized. You may include HTML formatting but it is ignored.
• UTF-8 encoding is preferred.
• Always specify image dimensions - this helps Zinc render the best possible experience for your feed.
• Please provide direct links to video content or a video player. See the media:content documentation for more information.
• Zinc supports the following Date-time formats: RFC 822, RFC 1123 and ISO8601
• Please provide rating information for your content using the media:rating element. If your feeds are automatically generated and may occasionally content adult or semi-adult content, please add a media:Rating element at the channel level.

Channel

The channel tag contains important metadata about the contents of the feed. If you are the author of the feed, we recommend that you include all of the available metadata about the feed in the channel tags. If you are not the author of the feed but are linking to the feed, you may provide the feed metadata in the item tag that links to the feed. For more information and examples see the tutorial.

<title>

Used in Zinc to display the title of your feed or site. Please keep the title short as it is used in the breadcrumb bar.

<image>

Zinc will use either the channel image or channel media:thumbnail tag as the image for your site. This is image is used in Zinc when the user is previewing a site (such as in Favorites or Zv Presents). It is important to correctly specify the image width and height. Example:

<image>
  <url>http://pc.zinc.tv/images/fake-image.jpg</url>
  <width>512</width>
  <height>512</height>
</image>

<description>

Provide a summary of a show, e.g:

<description>Diggnation is a weekly tech/web culture show based 
on the top digg.com social bookmarking news stories</description>

<zv:aspect>

Indicates the desired aspect ratio to display images in the feed. Valid values include poster, sdtv, square. Important if thumbnail sizing information is not available. The default aspect is 2:1. The aspect setting is ignored if thumbnails have a width and height. You may also specify a fractional number to represent the aspect ratio, e.g 16:9 is 1.777777.

<zv:aspect>poster</zv:aspect>

or

<zv:aspect>1.77777</zv:aspect>

<zv:branding>

A branding image and color for items can be applied to the channel. The brand color gives a hue to the screen background within Zinc, and is specified in hex as “#RRGGBB”, where each component is in the range of #00-#FF. It is recommended to avoid using very bright colors as they will make the white overlaid text hard to read. The image is used to help identify the source of the content in search results, favorites, the queue and a user’s history. It should be an image of the brand logo for the website.

<zv:branding brandcolor="#97aa24" src="http://site-art/logos/ngkids.png" />

<zv:sectionorder>

Zinc supports a "sectioned" layout for presenting content. The best example is the Netflix support. The sectioned layout means that you want your feed to be divided up into a number of similar sections that are visually different. In the case of Netflix, we chose to use sections to highlight the difference in genres. Other possible scenarios are using sections to differentiate between clips and episodes.

A sectionorder element contains, at minimum, a position attribute and an inner value that matches the zv:section tag of corresponding items. The position indicates the order of display. The optional url attribute is used when the user clicks on the section header. The optional description attribute shows up in the detail area when the user mouses over a clickable section header. The optional image attribute shows up on the left end of clickable section header (section 6 below). Example:

  <zv:sectionorder position="1" description="Humorous Videos" url="rss://feedserver.com/comedy">Comedy</zv:sectionorder>
  <zv:sectionorder position="2" description="Age-appropriate Videos" url="rss://feedserver.com/children">Children</zv:sectionorder>
  <zv:sectionorder position="3" url="rss://feedserver.com/tv">Television</zv:sectionorder>
  <zv:sectionorder position="4" url="rss://feedserver.com/action">Action</zv:sectionorder>
  <zv:sectionorder position="5" url="rss://feedserver.com/drama">Drama</zv:sectionorder>
  <zv:sectionorder position="6" image="http://www.site-art.com/sci-fi.png" width="512" height="256" url="rss://feedserver.com/scifi">Sci-Fi</zv:sectionorder>

Item

<title>

The title for the item. Zinc will combine the title you specify with extra metadata (season, episode, release year) depending on two factors: the view (grid, list-detail, or grid-detail) and the specified view-hint. For example, if the viewhint is "Movies", the release year is displayed after the title.

<description>

Zinc uses the description data in list view or when the user clicks on a video in grid view. All HTML markup is stripped from the description. However, basic HTML elements like P and DIV will be translated to include carriage returns. For example, <p>test</p><p>test2</p> is translated to "test\ntest2". Internally, Zinc uses the Mozilla ScriptableUnescapeHTML object to do the conversion. For more information see developer.mozilla.org.

<link>

URL to the specified link or content. Zinc requires the use of the "rss://" protocol when referring to an RSS document. Other URL's (http://, ftp://, etc) are handled by Mozilla / Firefox. If you are constructing a feed that points to other RSS feeds, you must use the rss:// syntax.
Zinc also supports the non standard "srss://" protocol, which simply means load the XML document using the secure HTTP protocol.

<link>rss://http://www.hulu.com/feed/show/54/episodes</link>

<author>

Zinc uses the author field for user generated content from sites like Youtube. The author is not used for episodic content or Movies where other information is more appropriate.

<author>Steve Jobs</author>

<enclosure>

Enclosure is the RSS 2.0 standard element for specifying media content. The recommended approach is to use the MediaRSS tags instead; see media:content.
If your feed already contains an enclosure tag, Zinc will support it. The required attributes url, length, and type. The most important attributes for Zinc are the url and type.

<pubDate>

The date the RSS item was published on the Internet. Note that this date may be different from the "air date", or the date the content was originally made available to the general public. Please use dates in RFC822 or ISO8601 format.
RFC 822 example:

<pubDate>Wed, 02 Oct 2002 13:00:00 GMT</pubDate>

ISO8601 example:

<pubDate>1997-07-16T19:20:30.45+01:00</pubDate>

<media:restriction>

Will be used in a future release of Zinc. Content owners who restrict their content to specific locations or countries are strongly recommended to use this element. See media:restriction in the Media RSS specification for more information. An example that is appropriate to Hulu:

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

<media:credit>

Use the media:credit element to list people who either created the content or were featured (e.g "starred") in the contnet. Zinc currently uses media:credit elements that have a role of "actor" or "director". Since Zinc is designed for the TV, it has limited to space to list all of the media credits. Please limit the number of credits to the core actors and directors. An example for the popular show "Family Guy":

<media:credit role="Executive Producer">David Zuckerman</media:credit> 
<media:credit role="Actor">Seth Green</media:credit> 
<media:credit role="Actor">Mila Kunis</media:credit> 
<media:credit role="Executive Producer">Seth MacFarlane</media:credit> 
<media:credit role="Actor">Alex Borstein</media:credit> 
<media:credit role="Actor">Mike Henry</media:credit> 

<media:category>

Not currently used in Zinc. You are encouraged to use the media:category element if you have an existing taxonomy or categorization for your content.

<media:rating>

Specifying a rating for your content is strongly encouraged. The media:rating element can be used either at the Channel level or the item level. If used at the channel level, that rating is applied to all content in the feed. Zinc uses the rating information to enable the user to filter content. In the near future Zinc will support the ability to block adult content.
If you don't have detailed rating information, please use the adult/nonadult form. Example:

<media:rating scheme="urn:simple">adult</media:rating>

Example if you have a Movie rating:

<media:Rating schema="urn:mpaa">PG</media:rating>

Example for TV ratings (v-chip):

<media:rating schema="urn:v-chip">TV-14</media:rating>

Some more information is available on the W3C feed validation service site.

<media:title>

Overrides the title element (if present). The type attribute is ignored; all HTML content is stripped and converted.

<media:description>

Overrides the description element (if present). The type attribute is ignored; all HTML content is stripped and converted.

<media:keywords>

Not currently used by Zinc but recommended for integration with future capabilities.

<media:player>

Zinc only uses the media:player element if a URL attribute is missing from a media:content element. While the media:player element could be used to specify a link to a flash player, we haven't found this is used much in practice. Instead most feed owners use the media:content element to specify a link to video URI or to a flash player.

<media:thumbnail>

A thumbnail should be included for every feed item. If multiple thumbnails are supplied, Zinc will usually choose the thumb with the highest resolution. Because Zinc is designed for HD content, we recommend using high resolution thumbnails when possible.
All thumbnails should be in the same resolution for the entire feed and should contain width and height information. If the width and height are not specified, Zinc will crop your images to fit the current View (list view, grid view, etc). Additionally, Zinc may use a smart-cropping algorithm that will automatically trim black space (or to be specific, information with low entropy) from the image border. Example from youtube (we choose the large image):

  <media:thumbnail url="http://i.ytimg.com/vi/ZCYaw5tGYAs/2.jpg" height="97" width="130" time="00:00:40" />
  <media:thumbnail url="http://i.ytimg.com/vi/ZCYaw5tGYAs/1.jpg" height="97" width="130" time="00:00:20" />
  <media:thumbnail url="http://i.ytimg.com/vi/ZCYaw5tGYAs/3.jpg" height="97" width="130" time="00:01:00" />
  <media:thumbnail url="http://i.ytimg.com/vi/ZCYaw5tGYAs/hqdefault.jpg" height="360" width="480" />

<media:copyright>

Use media:copyright to indicate the copyright holder of the content. In many cases Zinc will display the copyright when viewing the content details.

<media:copyright<2008 20th Century Fox Television</media:copyright>

<media:content>

Any directly playable content should be listed in a media:content element. There are two important variations for supporting content in Zinc: directly playable media URLs and URLs that link to a player (usually a SWF file).

Our preference is that your site should provide a direct link to a FLV, MP4, or RTSP URL directly in a media:content element. This provides the Zinc user the best possible full screen experience and gives Zinc the ability to control the video with our built in media player. Example (courtesy of The Onion):

<media:content url="http://feeds.theonion.com/~r/OnionNewsNetwork/~5/Lb38_xyrd_U/podcast_redirect.mp4" 
fileSize="21434576" type="video/mp4" />

On the other hand, many content owners choose to provide their own flash player for content, in many cases to interleave advertisements at periodic intervals. This works well with Zinc with one restriction: the Zinc user will not be able to control the video playback (pause, rewind, fast forward, etc). In this case, the solution is to use the Zinc javascript API to integrate your player with Zinc. Example (from youtube):

<media:content url="http://www.youtube.com/v/ZCYaw5tGYAs&f=gdata_videos" 
type="application/x-shockwave-flash" medium="video" isDefault="true" expression="full" 
duration="80" yt:format="5" /> 

Some important notes:

• The URL and type attribute must be specified. (type is optional in the Media RSS specification)
• The duration attribute should be specified.
• Content that is marked expression="sample" is currently ignored. Zinc will use the contents of the link tag to render the content if not other content is specified..
• The other attributes are not currently used in Zinc but may be in the future.

<zv:views>

An integer value that lists the number of times the content has been viewed.

<zv:views>116484</zv:views>

<zv:expires>

The date when the content is no longer available.

<zv:expires>Mon, 11 May 2009 12:45:00 -0000</zv:expires>

<zv:season>

An integer value >=1 for the episode season.

<zv:season>4/<zv:season>

<zv:episode>

An integer value >=1 for the episode number.

<zv:episode>3/<zv:episode>

<zv:airdate>

The date the content was "aired", e.g broadcast on television. The date should be normalized to UTC.

<zv:airdate>Sun, 15 Feb 2009 18:00:00 -0000</zv:airdate>

<zv:userrating>

A fractional number between 1.0 and 5.0 that represents the average rating of the content on a scale of 1-5. For instance, if content has rating of 4 1/2 stars, the user rating should be 4.5.

<zv:userrating>4.5/<zv:userrating>

<zv:price>

A string that indicates the cost of the item. Don't include if the content is free. The price should include the currency symbol, e.g $, €, etc.

<zv:section>

Indicate the section (see zv:sectionheader) to use when displaying the item. A section is similar to a category although specific to Zinc.

<zv:section>Action</zv:section>

The zv:controls is used when the link points to another RSS page. When used on the item tag, zv:controls is usually specifying how to display the linked RSS page. Alternatively, zv:controls can be used on the channel element to specify how a feed show be displayed. The zv:controls element consists of many attributes, all of which are optional. Example:

<zv:controls
  showtitle="true"
  fullscreen="true",
  aspect="1.777777",
  viewhint="Episodic",
  money="false",
  remotesupport="true",
  new="false",
  itemstyle="logo",
  feedstyle="captionlogo"
/>

showtitle true or false. Indicates if titles should be used in grid view.
fullscreen true or false. Indicates if content is automatically displayed in full screen. If your content support full screen but requires the user to click a button, this property should be false.
aspect. An aspect ratio in integer form (e.g 16/9=1.77777) or one of poster,sdtv, or square. Defaults to 2:1
viewhint. One of Episodic, Shows, Movies, UGC (user generated content), or News. The viewhint changes what information is displayed for the content. For example: the Movies viewhint displays the release year and Rating in list view.
money. True or false. If the content requires a purchase or subscription.
remotesupport. True or false. Set to true if your site supports the Zv Remote, a media center remote, or you have integrated with our media control javscript API.
new. true or false. Set to true if you have recently added the item. The item stays "new" as long as this attribute is specified.
itemstyle. Specifies the algorithm used to crop the individual show thumbnail. Examples:

Options:

• logo Use logo cropping on the image. The title displays behind the image while it is loading.
• captionlogo. Like logo but show the title.
• minilogo. Shrink the thumbnail and show the title. Useful when unique thumbs are not available.
• poster Fit the image to the available display area and don't show the title. (no cropping)
• screen Crop the image to fit the display area and show a title (screenshot cropping)
• keyicon Display the thumbnail as is without the title. This is the correct setting for high quality thumbnails.
• icon Display the thumbnail as is with the title.
• folderlogo Display the thumbnail with a folder background without a title.
• folder Display a folder with a title.

feedstyle The same options as itemstyle but controls the image displayed for the feed (used in list view).

<zv:duration>

Specifies the length of the content in seconds. Useful if the feed does not have a media:content element. For instance, Zinc uses zv:duration when pointing to a Netflix watch now movie.

<zv:duration>130</zv:duration>

<zv:durationstr>

Specifies the duration in hh:mm:ss format. Example:

<zv:durationstr>3:15:23</zv:durationstr>

Please only specify zv:duration or zv:durationstr, not both.