Zinc RSS Tutorial

Overview

Zinc works with RSS feeds. This means that you can import any RSS feed (that conforms to the RSS spec) into Zinc and it will "just work". It won't always look pretty, but the titles and descriptions will show up and the links will point to the right places.

In 2004, Yahoo designed Media RSS to syndicate multimedia content, such as videos. Media RSS tags use the media XML namespace (all tags begin with media:). Using these tags will allow you to include extra metadata, such as duration, rating, actors, and directors. Zinc uses this information to display extra information about videos and implement sorting/filtering.

Zinc also has its own namespace, which uses the zv prefix. This namespace is used for features unique to Zinc, such as how to graphically lay out the content page, whether remote controls are supported, and whether fullscreen is supported.

In this tutorial, we'll show you how to use these elements to create a fully-integrated video feed that looks good in Zinc.

The Skeleton

First, we'll fill in some boilerplate: standard RSS tags and our XML preamble:

<?xml version="1.0"?>
<rss xmlns:media="http://search.yahoo.com/mrss/" xmlns:zv="http://zeevee.com/zinc/2009" version="2.0">
  <channel>
    <title>Sample Feed Title</title>
    <link>http://link.to/feedwebsite</link>
    <description>Description of feed</description>
    <media:thumbnail url="http://feedwebsite.com/feedthumbnail.png"/>
    <zv:aspect>1.77777</zv:aspect>
    <zv:controls showtitle="true"/>
    <item>
      <title>Item title</title>
      <description>Item description</description>
      <media:thumbnail url="http://feedwebsite.com/videothumb.png"/>
      <link>http://feedwebsite.com/videopage</link>
      <pubDate>Wed, 02 Oct 2002 13:00:00 GMT</pubDate>
    </item>
  </channel>
</rss>

Those xmlns attributes are declaring that we're using 2 XML namespaces: zv and media. We then use the channel tag to indicate that we're describing an RSS "channel" (feed), and leave space for the title and description and a link to the website corresponding to the feed (this link isn't currently used by Zinc, but it is required by the RSS spec). We're also including a thumbnail tag, which, while not strictly required, will vastly increase the attractiveness of your feed.

We're also including a sample item tag to show the structure of the document. Item tags are the "meat" of the feed; they contain the titles, descriptions, thumbnails, and links (plus some Zinc-specific info) for each video.

The pubDate value must be in RFC822 or ISO8601 format. See the spec for more information.

Tweaking the Presentation

One key to a good-looking page is controlling your aspect ratio. Zinc's default thumbnail aspect ratio is 2:1. Many HD shows use a 16:9 aspect ratio. SDTV shows are generally more square. If you use the wrong aspect ratio, you'll see color bars around your thumbnails, or you'll get an auto-cropped image:

Bad aspect ratio

In the above screenshot, we're using the default aspect ratio when we should be using "poster".

Good aspect ratio

Here, we are using the correct "poster" aspect ratio:

  <channel>
    ...
    <zv:aspect>poster</zv:aspect>
  </channel>

Aspect ratio is controlled by the zv:aspect tag at the channel level. For HDTV shows, you can generally use the default aspect ratio and omit this tag. For SDTV shows, use "sdtv", and for movie posters, use "poster". You can also use the decimal representations of fraction; for example, 1.77777 is 16:9. See the spec for more information. If there is no zv:aspect tag, Zinc will attempt to determine the correct aspect ratio by averaging the ratios of the height and width attributes of the provided images. This can only work if you provide these attributes! Your feed will look best if all your thumbnails use the same aspect ratio.

The showtitle tag determines whether the titles of the videos will be shown when you're viewing a playlist in tile view. For example, in the above screenshot we don't show titles because the titles are shown in the actual thumbnails. In the screenshot below, we choose to show titles because the thumbnails don't give enough information about the title. Notice that each item gets two lines of title space. That's all the space available, so make sure not to use long titles!

Show title

  <channel>
    ...
    <zv:control showtitle="true" />
  </channel>

Optional Item-Level Elements

Actors and directors can be specified with the media:credit tag:

Actors

<media:credit role="actor">Adam Sandler</media:credit>
<media:credit role="actor">Jackie Titone</media:credit>
<media:credit role="director">Seth Kearsley</media:credit>

Linking Directly to Media Files

You may notice that for certain Zv Presents feeds, such as content from Revision3, the videos open directly in Zinc instead of through a web page interface. You can make this work for your web site by using the media:content tag. Make sure you specify the type correctly!

<media:content duration="402" medium="video" fileSize="75709636" url="http://www.podtrac.com/pts/redirect.flv/bitcast-a.bitgravity.com/revision3/flv/bestof/0324/bestof--0324--tekzilla-0088--large.fl8.flv" cnettv:aspectRatio="16x9" type="video/x-flv">

In addition to FLV files, we'll natively play mp4 files and run SWF files in fullscreen.

A Special Note for Youtube Content

Linking to the Youtube page will work, but you won't get automatic fullscreen or full remote integration. Instead, use the media:content tag as seen below:

<item>
   <title>130 cat mosh pit</title>
   <link>http://www.youtube.com/watch?v=_LQSoMakoIU</link>
   <description>[clipped for space]</description>
   <guid isPermaLink="false">http://www.reddit.com/r/videos/comments/8jehs/130_cat_mosh_pit/</guid>
   <pubDate>Sun, 10 May 2009 16:55:45 -0700</pubDate>
   <media:content url="http://www.youtube.com/v/_LQSoMakoIU?f=standard&amp;amp;app=youtube_gdata" type="application/x-shockwave-flash" />
   <media:title>130 cat mosh pit</media:title>
   <media:thumbnail url="http://thumbs.reddit.com/t3_8jehs.png" />
</item>

If you use the application/x-shockwave-flash type, the video will open in Zinc's internal flash player. So how do you compute the URL when you're just given a link? In this case, the link is http://www.youtube.com/watch?v=_LQSoMakoIU. We take the "v" variable, _LQSoMakoIU, and copy it into the embed URL after the "/v/", and append some static variables to the end to get: http://www.youtube.com/v/_LQSoMakoIU?f=standard&app=youtube_gdata.

Some Final Notes

Make sure that you serve the feed up with a mimetype of text/xml. Using the "xml" extension on the file will normally force your web server to send the document with the correct headers.

Using the zinc:// protocol (yes, we know it's not really a protocol) instead of http:// in your links will instruct Firefox to open the feed in Zinc. For example, zinc://feeds2.feedburner.com/RedditVideo.