=====================
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.