dev.michaelgravel.com

Apr 28 2007

Podcasting With Textpattern - A Tutorial

Introduction

This tutorial is aimed at those who wish to publish an iTunes-friendly audio podcast with Textpattern. It’s skued towards an audio broadcast, but with a few mods you can rig it for video as well. I wrote this tutorial because I felt that there was not a single comprehensive, easy-to-follow tutorial on the process of creating and publishing a podcast with Textpattern. It should be noted that there are much easier ways to publish a podcast than this (i.e. feedburner and libsyn are two services that make it easy). This tutorial is also aimed at the control freaks: Those who like to have fine-grained control over everything they publish. This document will show you how to generate a proper podcast feed, and how to set up an audio player so that visitors to your site can listen to streaming audio of your episodes.

What this tutorial will not show you

This tutorial does not show you how to create and / or edit an audio file. It assumes that you know how to do that. It doesn’t tell you all the ins and outs of using iTunes. Read the podcast specs (link below) for that information.

Before you start

Before undertaking this tutorial, it is very important to read Apple’s tech specs for podcasters. There is a ton of valuable, easy-to-read information there. Read it before proceeding. Once you’ve read the specs, you’re ready to start.

Step One – Create Two New Sections

You’ll need to create two new sections – one in which you will post your podcast episodes, and one that will generate your podcast feed. In this example, we’re going to name these two sections like so:

1. Podcast. We will post our podcast episodes to this section.

1. Broadcast. This section will generate a valid, iTunes-friendly RSS feed.

Name these sections any names you want, but keep them consistent throughout this tutorial.

Step Two – Download mg_setheader

Download my plugin <txp:mg_setheader />. Install and activate the plugin as per normal. I’ll show you how to implement it later on.

Step Three – Name three new custom fields

You’ll need to name three new custom fields. Custom fields are named in Admin > Preferences > Advanced. If you need to expand the number of custom fields you have available (i.e., if you need more than 10 in total), please see Gerhard Lazu’s tutorial on creating 10 more custom fields in Textpattern. In this example, we’re naming our three new custom fields like so:

1. podcast-audio-url. This is the URL (NOT the local path) to your podcast episode.
2. audio-file-bytes. This is the size of our audio file in bytes (you can get this information by checking the properties of the file in Windows or Mac OS).

1. podcast-duration. This is the length of the file in this format: HH:MM:SS. You can also go MM:SS. PLEASE NOTE that the value you place here will be plunked directly into your feed. If you plug in something like “3 minutes” in this field, you’ll get an error when you submit your feed to iTunes.

Step Four – Set up your feed template

Create a page template called ‘broadcast’. Make sure that the ‘broadcast’ section is using the ‘broadcast’ page template (set this in Presentation > Sections). Plunk the following into the ‘broadcast’ page template:

<txp:mg_setheader value="application/rss+xml" /><?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" version="2.0">
<channel>
<title>Example Podcast</title>
<link>http://www.example.com</link>
<language>en-us</language>
<copyright>&#x2117; &amp; &#xA9; 2007 onwards by The Author</copyright>
<itunes:subtitle>A Podcast About Everything and Nothing</itunes:subtitle>
<itunes:author>Fictitious Author</itunes:author>
<itunes:summary>A good description of your podcast should go here.  This is what iTunes will use to search for your podcast.  Make it good and short.</itunes:summary>
<description>A good description of your podcast should go here.  This is what iTunes will use to search for your podcast.  Make it good and short.</description>
<itunes:keywords>example, example, example, example</itunes:keywords>
<itunes:owner>
	<itunes:name>Fictitious Author</itunes:name>
	<itunes:email>you@example.com</itunes:email>
</itunes:owner>
<itunes:explicit>No</itunes:explicit>
<itunes:image href="http://www.example.com/images/podcast-image.jpg" />
<itunes:category text="Main Category">
	<itunes:category text="Sub Category" />
</itunes:category>
<txp:article_custom form="podcast" limit="10" section="podcast" />
</channel>
</rss>

Notes on the above:

• Change all tag information to your own.
• Note the position of the <txp:mg_setheader /> tag (you downloaded, installed, and activated this plugin in step #2, remember?). This position is NON NEGOTIABLE. It must reside at the top of the page and the opening XML tag MUST immediately follow it. No spaces, no linebreaks.
• Be sure to change the URL in the <itunes:image> tag to the URL of your own podcast image.

• Change the category of your podcast to suit.

Again, for those who missed it earlier, please read Apple’s tech specs for podcasters. The above will make alot more sense if you do. Note that everything above the <txp:article_custom /> tag can be hard coded into the feed, OR you can use Textpattern tags (like <txp:site_url /> or <txp:site_slogan /> to generate the title or link, etc.

This template will be called when iTunes (or another user agent) hits http://www.example.com/broadcast/. We’re using the <txp:article_custom /> tag to pull in items from the ‘podcast’ section. In other words, when you want to post a new podcast episode, DO NOT post it to the ‘broadcast’ section. It won’t show up. Post it to the ‘podcast’ section.

Step Five – Create an article form called ‘podcast’

From the above step, you’ll notice that we also need to create an article form called ‘podcast’. Create the form and plunk the following into it:

<item>
<title><txp:title /></title>
<itunes:author><txp:author /></itunes:author>
<itunes:subtitle><txp:php>$text = body ( array () ); echo strip_tags($text);</txp:php></itunes:subtitle>
<itunes:summary>
<txp:php>$text = body ( array () ); echo strip_tags($text);</txp:php>
</itunes:summary>
<description>
<![CDATA[<txp:body />]]>
</description>
<enclosure url="<txp:custom_field name="podcast-audio-url" />" length="<txp:custom_field name="audio-file-bytes" />" type="audio/mpeg" />
<guid><txp:custom_field name="podcast-audio-url" /></guid>
<pubDate><txp:posted format="%a, %d %b %Y %I:%m:%S %z" /></pubDate>
<itunes:duration><txp:custom_field name="podcast-duration" /></itunes:duration>
<itunes:explicit>Yes</itunes:explicit>
</item>

Notes on the above:

• The date format (%a, %d %b %Y %I:%m:%S %z) is non-negotiable. This is the standard RSS date format. If another format is used, your feed will be invalid.
• You may have to tweak the timezone (%z) to your own – you can throw that in there manually, if need be.
• Be sure to change the <itunes:explicit> tag to suit. You could modify this on an article-to-article basis by using an additional custom field.
• Obviously, the above example won’t suit everyone’s fancy. Feel free to tweak and modify as you see fit. For instance, you might want to use a different field for the <itunes:subtitle> tag. You could populate it with data from an additional custom field, if so desired.

• If you’re doing a video podcast, you’ll want to change the ‘type’ attribute on the enclosure tag. If you’re mixing media types (i.e. one episode is video, the next is audio), you could populate that attribute with an additional custom field so that the type is selectable on an article-to-article basis.

Step Six – Set up and tweak your podcast section

It’s good practice to have your audio content available for both podcast subscribers and regular visitors to your website. You’ll need to get your hands on a drop-in audio player that you can include in your articles. Fortunately, someone has thought of this and made one available. Here it is:

http://www.textpatternmania.com/2006/04/29/plugin-jnmaudio

Download the plugin and associated files and set them up as described on the above page. The next step in this process is to create a page template for the ‘podcast’ section and customize it as needed. How you do that is completely up to you. When you want to display the audio player for your visitors, you’d use this code in an article form:

<txp:jnm_audio url="."><txp:custom_field name="podcast-audio-url" /></txp:jnm_audio>

That will place the audio player on the page (provided that you have downloaded and installed the jnm_audio plugin as per instructions) and allow your visitors to listen to your podcast. The above can also be accomplished by building your own audio player (in Dreamweaver, say) and using custom fields. Again, how you actually implement this is completely up to you.

The net effect of this step is this: When someone visits www.example.com/podcast/, they can listen to your episodes on an audio player. This has absolutely no effect on your podcast feed.

Step Seven – Posting a test episode

Before you submit your podcast to iTunes, it is ABSOLUTELY IMPERATIVE that you test the feed that you built in steps four and five. It’s time to post a test episode. You’ve set up your Textpattern templates and forms. You’ve recorded your audio file. Lets post a test epsiode and check the results.

• Make sure that you gather the information you need: Size of the audio file in bytes (no commas in the value, i.e. 2,300,202 is not acceptable – 2300202 is acceptable), duration of audio file in HH:MM:SS format (or MM:SS), and the url of the audio file. Obviously, the audio file must reside on a publicly-accessible web server. If you’re using your own server, be aware of the bandwidth implications of audio files. They chew up alot of transfer capacity really quick.
• Create a new article and place your information in the appropriate fields. The body of the article will become the subtitle of the episode – this is what will show up in the ‘description’ column in iTunes.
• Make sure that you post your article to the ‘podcast’ section. Otherwise, it won’t show up in your feed.

• Once you’ve posted your test episode, have a look at your feed. It should look something like this (with the correct values of course):

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" version="2.0">
<channel>
<title>Example Podcast</title>
<link>http://www.example.com</link>
<language>en-us</language>
<copyright>&#x2117; &amp; &#xA9; 2007 onwards by The Author</copyright>
<itunes:subtitle>A Podcast About Everything and Nothing</itunes:subtitle>
<itunes:author>Ficitious Author</itunes:author>
<itunes:summary>A good description of your podcast should go here.  This is what iTunes will use to search for your podcast.  Make it good and short.</itunes:summary>
<description>A good description of your podcast should go here.  This is what iTunes will use to search for your podcast.  Make it good and short.</description>
<itunes:keywords>example, example, example, example</itunes:keywords>
<itunes:owner>
	<itunes:name>Fictitious Author</itunes:name>
	<itunes:email>you@example.com</itunes:email>
</itunes:owner>
<itunes:explicit>No</itunes:explicit>
<itunes:image href="http://www.example.com/images/podcast-image.jpg" />
<itunes:category text="Arts">
	<itunes:category text="Design" />
</itunes:category>
<item>
<title>Episode Title</title>
<itunes:author>Fictitious Athor</itunes:author>
<itunes:subtitle>Body of test episode</itunes:subtitle>
<itunes:summary>
Body of test episode
</itunes:summary>
<description>
<![CDATA[body of test epsiode]]>
</description>
<enclosure url="http://www.example.com/audio/episode-1.mp3" length="2116532" type="audio/mpeg" />
<guid>http://www.example.com/audio/episode-1.mp3</guid>
<pubDate>Sat, 15 Jun 2007 17:00:00 MDT</pubDate>
<itunes:duration>02:20</itunes:duration>
<itunes:explicit>No</itunes:explicit>
</item>
</channel>
</rss>

At this stage, you should definitely run your feed through a feed validator: http://www.feedvalidator.org. Just enter the URL of your feed. In this example, you’d enter www.example.com/broadcast/. If your feed is similar to the example above and it validates, it’s time to test it in iTunes.

Step Eight – Testing in iTunes

The real acid test of this whole process is testing your podcast feed in iTunes. Obviously, you must have iTunes on your computer to do this. Here are the steps:

• Launch iTunes.
• In the Advanced menu, select ‘Subscribe to Podcast’.
• Enter the URL of your podcast feed. In this example, we’d enter www.example.com/broadcast/.

• Click OK.

If your feed is good and you posted everything properly, iTunes should add your podcast to your list of podcasts and start downloading your first episode. If this happens, cogratulations! You’ve just entered the world of podcasting. If it doesn’t happen, you’ll have to go back and troubleshoot.

Step Nine – Submit your podcast to iTunes

Read the podcaster tech specs for complete details on how to submit your podcast to iTunes.

Thanks for reading

I know this tutorial was exhaustive, but I hope it was worth it. Thanks for reading.

Posted in text on April 28, 2007