doc/todo/fancypodcast.mdwn

   1 ikiwiki's simple podcasting, while elegant and minimal, doesn't (as
   2 mentioned in [[todo/blogging]]) produce full-featured feeds. In
   3 fancy podcasts, episodes are accompanied by text content. The feeds
   4 also have lots more metadata.
   5
   6 [[!toc]]
   7
   8 ## Status
   9
  10 [[!template id=gitbranch branch=schmonz/fancypodcast author="[[schmonz]]"]]
  11 [[!tag patch]]
  12
  13 In summary, the branch preserves ikiwiki's existing podcast behavior,
  14 adds more featureful behavior, and has been tested to work well in
  15 some common podcatchers. I believe it is ready for review and
  16 possible integration, and I'd like to get feedback to that effect
  17 (or to the contrary) before making further enhancements. I know
  18 [[joey]]'s the final arbiter here, but I'd appreciate any qualified,
  19 critical eyes ([[smcv]]?) raking over my diffs. --[[schmonz]]
  20
  21 ## Features
  22
  23 [[!table data="""
  24 Feature            |iTunes RSS|iTunes Atom|Downcast RSS|Downcast Atom
  25 Feed image         |          |           |            |
  26 Feed title         |(./)      |(./)       |(./)        |(./)
  27 Feed publisher     |          |           |            |
  28 Feed "category"    |          |           |            |
  29 Feed date          |(./)      |(./)       |(./)        |(./)
  30 Feed description   |(./)      |(./)       |(./)        |
  31 Episode image      |          |           |            |
  32 Episode title      |(./)      |(./)       |(./)        |(./)
  33 Episode date       |(./)      |(./)       |(./)        |(./)
  34 Episode duration   |          |           |            |
  35 Episode author     |          |           |            |
  36 Episode description|(./)      |(./)       |(./)        |
  37 Episode enclosure  |(./)      |(./)       |(./)        |(./)
  38 """]]
  39
  40 ## Design
  41
  42 7. For each fancy podcast episode, write a blog post containing
  43    `\[[!meta enclosure="WikiLink/to/media.mp3"]]`. (Don't specify
  44    more than one enclosure -- but if you do, last one wins.)
  45 7. When rendering to HTML (single-page or inlined), append a link
  46    to the media file.
  47 7. When rendering to RSS/Atom, the text is the entry's content and
  48    the media file is its enclosure.
  49 7. Don't break simple podcasts in pursuit of fancy podcasts.
  50
  51 ## Implementation
  52
  53 ### Completed
  54
  55 * Cover the existing simple podcast behavior with tests.
  56 * Add an `enclosure` field to [[plugins/meta]] that expands the
  57   given [[ikiwiki/WikiLink]] to an absolute URL (feed enclosures
  58   pretty much need to be, and the reference feeds I've looked at
  59   all do this).
  60 * Write failing tests for the desired single-page and inlined
  61   HTML behavior, then make them pass by adding enclosure stanzas
  62   to `{,inline}page.tmpl`.
  63 * Write failing tests for the desired RSS/Atom behavior, then make
  64   them pass via changes to `{atom,rss}item.tmpl` and [[plugins/inline]].
  65 * Match feature-for-feature with
  66   [tru_podcast](http://www.rainskit.com/blog/542/tru_podcast-a-podcasting-plugin-for-textpattern)
  67   (what [[schmonz]] will be migrating from).
  68 * Enrich [feed metadata](http://cyber.law.harvard.edu/rss/rss.html)
  69   by catching up `rsspage.tmpl` to `atompage.tmpl`.
  70 * Verify that [[plugins/more]] plays well with fancy podcasts.
  71 * Verify that the feeds validate.
  72 * Subscribe to a fancy feed in some common podcatchers and verify
  73   display details against a reference podcast.
  74 * Verify smooth transitions for two common use cases (see testing
  75   details below).
  76
  77 ### Must-have (for [[schmonz]], anyway)
  78
  79 * Think carefully about UTF-8.
  80 * Verify that _all_ the tests pass (not just my new ones).
  81
  82 ## Migration
  83
  84 ### Upgrading within ikiwiki: from simple to fancy
  85
  86 #### My test podcast
  87
  88 For this test, I chose a podcast that tries to work around ikiwiki's
  89 current limitations by issuing two separate `inline`s:
  90
  91 * One with `feedonly=yes` that includes `.mdwn`, `.pdf`, and `.mp3`
  92 * One with `feeds=no` that includes only `.mdwn` (and makes a trail)
  93
  94 This has the following effects:
  95
  96 * Browser: sees just the articles (each of which has a manually
  97   created link to its corresponding media file)
  98 * Feedreader: sees all the articles and media in one flat stream
  99 * Podcatcher: sees just the media (sans articles)
 100
 101 I want instead to write one `inline` with these effects:
 102
 103 * Browser: sees just the articles (each of which automatically links
 104   to its enclosure)
 105 * Feedreader: sees just the articles (each of which specifies its
 106   enclosure)
 107 * Podcatcher: sees just the enclosures (each of which has an enclosing
 108   article, rendered as the media's "description")
 109
 110 #### Upgrade steps
 111
 112 7. Set up a non-production copy of the podcast.
 113     7. Visually diff RSS and Atom feeds against production.
 114     7. Subscribe to the copy (both feeds) in `r2e`, iTunes, Downcast.
 115 7. Apply fancypodcast patch to the installed ikiwiki:
 116     7. `cd ~/Documents/trees/ikiwiki && git checkout fancypodcast`
 117     7. `git diff --no-prefix master > ~/Documents/trees/localpatches/www/ikiwiki/fancypodcast.diff`
 118     7. `cd ~/Documents/trees/pkgsrc-current/www/ikiwiki && make deinstall && make install clean`
 119 7. Verify that simple podcasts are unaffected:
 120     7. Rerun `ikiwiki --setup`.
 121     7. `diff -uB simple-before.rss simple-after.rss`
 122         * A few new elements and attributes, as expected.
 123     7. `diff -uB simple-before.atom simple-after.atom`
 124         * No change.
 125 7. Remove the feed-only `inline` and enable feeds on the remaining one.
 126 7. Convert articles' manual download links to `\[[!meta enclosure=""]]`.
 127 7. I want existing and future podcatchers to get my new fancy
 128    episodes, and I know my podcast isn't in any planets, so I'm
 129    going to skip [[tips/howto avoid flooding aggregators]].
 130 7. Rerun `ikiwiki --setup`.
 131 7. Verify browser shows the same stuff.
 132 7. `diff -uB simple-after.rss fancy-after.rss   # and atom`
 133     * MP3s and PDFs are no longer naked enclosures, but belong to
 134       articles as they should.
 135     * Articles have updated modification times, as they should.
 136 7. `r2e run` (both RSS and Atom)
 137     * Nothing new with the default `trust-guid = True` (otherwise
 138       would expect updated articles).
 139 7. iTunes "Update Podcast" (both RSS and Atom)
 140     * Added one episode per article, with article text as the episode
 141       description.
 142     * Kept old naked-enclosure episodes around.
 143 7. Downcast refresh (RSS):
 144     * Added one episode per article, with article text as the episode
 145       description.
 146     * Kept old naked-enclosure episodes around.
 147 7. Downcast refresh (Atom):
 148     * Added one episode per article, with no episode description
 149       (expected, see feature table).
 150     * Kept old naked-enclosure episodes around.
 151
 152 Different tradeoffs are possible. These seem okay to me.
 153
 154 ### Importing into ikiwiki: fancy (from another CMS)
 155
 156 #### My test podcast
 157
 158 For this test, I chose a podcast currently being published with
 159 Textpattern and tru_podcast, because I'd strongly prefer to publish
 160 it with ikiwiki instead.
 161
 162 #### Upgrade steps
 163
 164 7. Set up a non-production copy of the podcast.
 165     7. Visually diff RSS and Atom feeds against production.
 166     7. Subscribe to the copy (both feeds) in `r2e`, iTunes, Downcast.
 167 7. With a fancypodcast-enabled ikiwiki installed:
 168     7. Copy content from Textpattern to ikiwiki:
 169         7. Match article paths to preserve `/YYYY/MM/DD/post-title` permalinks.
 170         7. Match enclosure paths (or redirect) to preserve Textpattern's URLs.
 171         7. Match titles, post dates, and guids with `\[[!meta]]`.
 172             7. Match feed paths with permanent redirects from `/atom/` to
 173            `/index.atom` (and same for RSS).
 174         7. `\[[!inline]]` the articles.
 175     7. Rerun `ikiwiki --setup`.
 176 7. Stop Textpattern, start ikiwiki.
 177 7. Verify that podcatchers see the feeds and don't redownload anything.
 178 7. Naively add two new blog posts, one with an enclosure.
 179 7. Verify that podcatchers download the new enclosures.
 180
 181 -----
 182
 183 ## Future improvements
 184
 185 ### iTunes fancy podcasting
 186
 187 * [iTunes-specific tags](https://www.apple.com/itunes/podcasts/specs.html)
 188   appear to be RSS-only
 189     * If they work in Atom, teach `inline` to optionally iTunesify RSS/Atom.
 190     * Else, add `itunes` as a third kind of feed (RSS plus more stuff).
 191 * Notable tags for feeds:
 192     * `itunes:subtitle`
 193     * `itunes:author`
 194     * `itunes:summary` (same as `description`)
 195     * `itunes:owner` (includes `itunes:name` and `itunes:email`)
 196     * `itunes:image href=''`
 197     * `itunes:publisher`
 198     * `itunes:category text=''` (can contain subcategories)
 199     * `itunes:keywords`
 200 * Notable tags for entries:
 201     * `itunes:duration`
 202         * [[!cpan Audio::TagLib]] might be fastest, if present and applicable
 203         * [ffprobe](http://ffmpeg.org/ffprobe.html) is reasonably fast
 204         * [mediainfo](http://mediainfo.sourceforge.net/) is way slower
 205         * Cache computed durations as pagestate
 206
 207 ### Fancy podcast aggregating
 208
 209 * Write tests comparing a fancy podcast (HTML and feeds) against
 210   the same podcast aggregated and republished, then make them pass
 211   via changes to `aggregatepost.impl` and [[plugins/aggregate]].
 212
 213 ### Other ideas
 214
 215 * Don't render template text (e.g., "Use this template to insert a
 216   note into a page") in feeds.
 217 * Optionally specify the enclosure's:
 218     * MIME type, in case `File::MimeInfo` guesses wrong.
 219     * Duration, in case `ffprobe` guesses wrong.
 220 * Optionally specify enclosures outside the wiki:
 221     * Some people don't want to store big unchanging files in the VCS.
 222     * Other people like [podcasting found media](http://huffduffer.com/about).
 223     * We'd have to download the file just to compute some metadata
 224       about it, and then somehow not frequently re-download it.
 225 * Configurably generate additional subscription links (such as
 226   iTunes) alongside the RSS/Atom ones in [[plugins/inline]].
 227 * Support Apple's "enhanced podcasts" (if they're still relevant).
 228
 229 ### code review
 230
 231         +                               # XXX better way to compute relative to srcdir?
 232         +                               my $file = $absurl;
 233         +                               $file =~ s|^$config{url}/||;
 234
 235 I don't think ikiwiki offers a better way to do that, because there is
 236 normally no reason to do that. Why does it need an url of this form here?
 237 --[[Joey]]
 238
 239 > In all the popular, production-quality podcast feeds I've looked
 240 > at, enclosure URLs are always absolute (even when they could be
 241 > expressed concisely as relative). [Apple's
 242 > example](http://www.apple.com/itunes/podcasts/specs.html#example)
 243 > does too. So I told \[[!meta]] to call `urlto()` with the third
 244 > parameter true, which means the \[[!inline]] code here gets an
 245 > absolute URL in `$pagestate{$p}{meta}{enclosure}`. To compute the
 246 > enclosure's metadata, though, we of course need it as a local path.
 247 > I didn't see a less
 248 > [ongepotchket](http://www.jewish-languages.org/jewish-english-lexicon/words/1402)
 249 > way at the time. If you have a better idea, I'm happy to hear it;
 250 > if not, I'll add an explanatory comment. --[[schmonz]]
 251
 252 >> I would be more comfortable with this if two two different forms of url
 253 >> you need were both generated by calling urlto. It'd be fine to call
 254 >> it more than once. --[[Joey]]
 255
 256         +<TMPL_IF HTML5><section id="inlineenclosure"><TMPL_ELSE><div id="inlineenclosure"></TMPL_IF>
 257         +<TMPL_IF ENCLOSURE>
 258
 259 Can't we avoid adding this div when there's no enclosure? --[[Joey]]
 260
 261 > Sure, I've moved the `<TMPL_IF ENCLOSURE>` check to outside the
 262 > section-and-div block for `{,inline}page.tmpl`. --[[schmonz]]
 263
 264         +<a href="<TMPL_VAR ENCLOSURE>">Download this episode</a>
 265
 266 "Download this episode" is pretty specific to particular use cases.
 267 Can this be made more generic, perhaps just "Download"? --[[Joey]]
 268
 269 > Yep, I got a little carried away. Done. --[[schmonz]]
 270
 271         -<TMPL_IF AUTHOR>
 272         -       <title><TMPL_VAR AUTHOR ESCAPE=HTML>: <TMPL_VAR TITLE></title>
 273         -       <dcterms:creator><TMPL_VAR AUTHOR ESCAPE=HTML></dcterms:creator>
 274
 275 This change removes the author name from the title of the rss feed, which
 276 does not seem necessary for fancy podcasts. And it is a change that
 277 could negatively impact eg, Planet style aggregators using ikiwiki. --[[Joey]]
 278
 279 > While comparing how feeds render in podcatchers, I noticed that
 280 > RSS and Atom were inconsistent in a couple ways, of which this was
 281 > one. The way I noticed it: with RSS, valuable title space was being
 282 > spent to display the author. I figured Atom's display was the one
 283 > worth matching. You're right, of course, that planets using the
 284 > default template and somehow relying on the current author-in-the-title
 285 > rendering for RSS feeds (but not Atom feeds!) would be broken by
 286 > this change. I'm having trouble imagining exactly what would break,
 287 > though, since guids and timestamps are unaffected. Would it suffice
 288 > to provide a note in the changelog warning people to be careful
 289 > upgrading their planets, and to customize `rssitem.tmpl` if they
 290 > really prefer the old behavior (or don't want to take any chances)?
 291 > --[[schmonz]]
 292
 293 >> A specific example I know of is updo.debian.net, when used with
 294 >> rss2email. Without the author name there, one cannot see who posted
 295 >> an item. It's worth noting that planet.debian.org does the same thing
 296 >> with its rss feed. (That's probably what I copied.) Atom feeds may
 297 >> not have this problem, don't know. --[[Joey]]
 298
 299         +++ b/templates/rsspage.tmpl
 300         +       xmlns:atom="http://www.w3.org/2005/Atom"
 301         +<atom:link href="<TMPL_VAR FEEDURL>" rel="self" type="application/rss+xml" />
 302
 303 Why is it using atom namespace inside an rss feed? What are the chances
 304 every crummy rss reader on earth is going to understand this? I'd put it at
 305 about 0%; I doubt ikiwiki's own rss reader understands such a mashup.
 306 --[[Joey]]
 307
 308 > The validator I used (<http://validator.w3.org/>, I think) told me to.
 309 > Pretty sure it doesn't make anything work better in the podcatchers
 310 > I tried. Hadn't considered that it might break some readers.
 311 > Removed. --[[schmonz]]
 312
 313         +<generator>ikiwiki</generator>
 314
 315 Does this added tag provide any benefits? --[[Joey]]
 316
 317 > Consistency with the Atom feed, and of course it trumpets ikiwiki
 318 > to software and/or curious humans who inspect their feeds. The tag
 319 > arrived only in RSS 2.0, but that's already the version we're
 320 > claiming to be, and it's over a decade old. Seems much less risky
 321 > than the atom namespace bits. --[[schmonz]]
 322
 323 >> Sounds ok then. --[[Joey]]