Merge branch 'master' of ssh://git.ikiwiki.info
[ikiwiki.git] / 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).