=====================
Podcast RSS Namespace
=====================

About This Document
===================

.. sidebar:: This is NOT a finished product. 

    We haven't been the only people thinking about a podcast namespace.
    August and Ray of the iPodderX team have been chatting with Adam and
    Dave about the same stuff, and have put up `another podcast namespace
    proposal`__. 

    __ http://ipodderx.com/podcastRSSModule

    It turns out that adding namespaced attributes to the RSS
    ``enclosure`` tag is not kosher. It might parse, and it might validate, but
    it's frowned upon. So, *neither* the original iPodderX proposal or my
    initial mail to ipodder-dev proposing a ``podcast`` namespace are going
    to get any traction. 
    
    Version 1.5 of this document is based on namespaced sub-tags of
    ``item`` as proposed in my `original mail`_ of November 26. This
    approach should be fine, but it remains to be seen how much traction
    it'll get. 
    
:Author: Garth T Kidd
:Organisation: iPodder "Lemon Edition" Team
:Version: $Revision: 1.5 $
:Date: 2004/11/24

This document is a dry technical reference to the ``podcast`` RSS module. 
See the `Busy Podcaster's Guide`_ for a more complete description of what
each element does and how it should be used. 

.. _Busy Podcaster's Guide: bpg.html

.. _hassle Garth:

If you have any questions about this specification, hassle Garth__ 
either privately or in public in the `ipodder-dev`__ mailing list. 

__ mailto:garthk@gmail.com
__ http://groups.yahoo.com/group/ipodder-dev/

Why Bother?
-----------

The ``podcast`` RSS module provides a structured way for podcasters to
provide additional information to podcatchers so that they can: 

* Try multiple ways of downloading a show, some of which prioritise saving
  money and some of which prioritise reliability; 

* Check that a show was downloaded correctly, whichever method was used; 

* Avoid downloading duplicates of a single show made available on multiple
  feeds, even if the filename or file type is different; 

* Impose user-configured limits on downloads by listening time as well as
  sheer size; and

* Display structured production notes for each show that users can get to
  without having to switch to their web browser. 

Table of Contents
-----------------

.. contents:: 

Change Notes
------------

* Nov 26: Nearly full re-write. 
* Nov 24: Initial version

What to put in your feed
========================

Namespace Definition
--------------------

First, you *must* make XML parsers happy (and let everyone know how to 
find this document) by adding the ``podcache`` namespace definition to 
your ``rss`` tag::

  <rss xmlns:podcast="http://ipodder.sourceforge.net/docs/podcast.html">
     ...
  </rss>

iPodder and anything else using a permissive feed parser won't mind if 
you skip that, but I suspect other podcatchers using strict XML parsers 
won't be able to parse your feed if you omit it. 

Where's the Rest?
-----------------

This is in such flux it's probably best if I just stick up the `original
mail`_. 

Original Mail
=============

    Goodo! Righto, then, let's keep it simple::

       <item>
           <title>We need one of title or description, or it ain't RSS</title>
           <enclosure url="...mp3" type="..." length="..."/>
           <podcast:alt_path url="...torrent" type="application/bittorrent" length="..."/>
           <podcast:prodnotes type="text/opml" length="..." url="..."/>
           <podcast:payload_info duration="..." guid="..."/>
           <podcast:enclosure_protection md5="..." length="..."/>
           <guid>it's an item guid, not an enclosure guid, or it's not RSS</guid>
       </item>

    All tags are optional. All tags are optional. All tags are optional.

    Note that there are no duplicate enclosure tags and no extra elements
    (namespaced or not) in the enclosure tag. That keeps it simple, leaves
    existing RSS elements alone, and -- I should disclaim -- makes life a
    lot easier for anyone (including iPodder) using Mark Pilgrim's
    feedparser.py, which exposes all namespaced tags under item but NOT
    anything you shove in enclosure.

    Allowing for multiple podcast:alt_path tags will permit podcasters to
    point to BitTorrent or alternative peer-to-peer download methods;
    point to mirrors contributed by other friendly people; or whatever.
    I'd say all the attributes would be compulsory. Obviously, the tag
    itself wouldn't be.

    Giving podcast:prodnotes a type lets a podcaster put up their
    production notes in whatever format they're most comfortable with. I'm
    sure OPML will make it easier for podcatchers to funkily display the
    production notes, which should in turn encourage any podcaster capable
    of doing so to use OPML. I'd like to permit beginners to point to HTML
    or plain text if they want to do so, however. Again, the tag would be
    optional but the attributes would be compulsory.

    [If people want to attach images and other stuff to their podcast, I'd
    urge them to point to those from their prodnotes. I think that should
    let us stamp out multiple enclosures, but I need to wade through my
    logs and figure out who's doing it and why.]

    podcast:payload_info gives information about the payload, which is
    related to but distinct from the enclosure: a single payload (let's
    say it's a podcast episode) might be made available as multiple
    different enclosures in different flavours (mp3, m4b, ogg, and high or
    low quality versions of each).

    Aside from preventing downloading the same payload in multiple
    flavours, I'd suggest podcast:payload_info guid also be used in the
    same way item guids are: letting podcatchers avoid duplicates if the
    content has subtly changed. I've seen a few podcasters re-issue a
    podcast because their levels were out, and they politely used
    different filenames. Leaving the payload guid the same would let
    podcatchers choose whether or not to download the new version.

    Again, podcast:payload_info would be optional. I'd like guid to be
    compulsory, but suspect that might not fly. Duration strikes me as
    optional.

    Finally, podcast:enclosure_protection (I need a better name) lets
    everyone check that they downloaded the enclosure correctly. This is
    especially important if there are multiple ways of getting hold of it.
    Both length and md5 should be compulsory; md5 to detect corruption
    even if the lengths match, and length because there might not be a
    direct download method available and thus the length in the enclosure
    and podcast:alt_path tags might not match the payload itself.

    Regards,
    Garth.