tru_podcast: Usage instructions

filed under: , , ,

15 January 2007

To learn more about tru_podcast, check out the introductory article, the releases page, or the feature list.

Table of Contents

Installation

  1. Go to the releases page to get the latest release. Don’t save it – just open it in your browser.
  2. Scroll down a slight bit and follow the on-page instructions: copy/paste the big square block of characters into your Textpattern install, under Admin -> Plugins.
  3. Hit “Upload”.
  4. Remember to switch the plugin to “Active” in the plugin list.

Configuration

Step 1: Rename one of your custom fields

tru_podcast uses a custom field named “tru_podcast”. Name one of your unused custom fields “tru_podcast” on the Admin -> Preferences -> Advanced tab.

tru_podcast custom field

Step 2: Upload a media file (a podcast)

Whenever you want to create a new episode, upload a media file to a web server. You can use Textpattern’s “Files” features, if you want. (Note that it is possible to FTP large media files to Textpattern’s files directory, and then use the “Files” tab in the admin to alert Textpattern that the file is there.)

Step 3: Start podcasting!

Find the tru_podcast field on the “Write” tab. It will be hiding behind the “Advanced Options” link.

Put the URL of the media file into that field. If you uploaded a file through Textpattern’s “Files” interface, just put the ID# of the file into the tru_podcast field. If the file is somewhere else on your web server, you can use a relative URL. Write whatever you want in the article, and save it.

That’s all it takes – the file will appear in your RSS and Atom feeds as an enclosure, and podcast clients (iTunes, for example) will identify it correctly.

You’ll probably want to install Rob Sable’s rss_admin_show_adv_opts, which will automatically expand the “Advanced Options” section of the “Write” page, when you are writing articles. That gives you easy access to the custom fields.

Step 4: Include links in your articles (Optional)

For people reading your site via their web browser, you can link to the media file from your articles with something like:

<txp:tru_podcast_if_podcast>
This article has a podcast!  <txp:tru_podcast_link linktext="Right here!" />
<txp:else />
No podcast here!
</txp:tru_podcast_if_podcast>

Step 5: Use a category to create a podcast-only feed (Optional)

You don’t have to create a special RSS feed for podcasts – the “enclosures” will simply show up in your normal feed(s) any time you specify a media file – but you can do so if you want. Simply create a new category for all your podcasting, and use the feed for that category as your podcast-only feed.

Step 6: Other types of “podcasts” (Optional)

You don’t have to limit yourself to audio; tru_podcast supports any type of media (video, images, etc.). As long as your server knows the correct MIME type for your media, everything should work.

Step 7: Advanced configuration (Optional)

The source code of tru_podcast has a few well-commented settings (right at the top) that you might want to change, especially if you use Textpattern’s “Files” features for your podcasts and if you’re using a non-default /files/ directory. If you run into problems with your podcast clients, you might want to try editing the plugin and changing those settings to see if it helps. (I don’t know of any problems with any clients, at the moment.)

Tag reference

tru_podcast_link

This tag will generate an <a href... link if the current article has a podcast URL set. The generated link will automatically have rel="enclosure" set in case an old podcast client is looking for it. You can pass any attribute to this tag and it will be passed on to the <a> tag, except linktext as indicated below.

Attributes:
  • linktext will set the content of the <a>...</a> link. If you don’t specify linktext, it defaults to the URL of the media.
  • Any other attribute desired can be passed to the <a>. For example, <txp:tru_podcast_link linktext="test" junk="worthy" /> will generate this HTML: <a href="/some/media.url" junk="worthy">test</a>

tru_podcast_if_podcast

This conditional tag will render its contents if the current article has an associated media file (in the tru_podcast custom field).

tru_podcast_get_url

This tag will return the URL of an associated media file, if any.

Attributes:
  • full="1" tells tru_podcast_get_url to convert relative URLs to full URLs
  • protocol can be used in conjunction with full="1" to specify a protocol other than “http://” for the generated full URLs.
  • convertnumber="0" will turn off the automatic conversion of file index numbers (from Textpattern’s “Files” interface). This is only really useful if you want to get directly at the text entered into the tru_podcast custom field.
Comments
  1. Jason Das says:

    This looks great. I’m implementing it now on for the Glass Bees. Thanks!

  2. Christian says:

    Thanks for this! Now I don’t have to edit the php-files anymore.

    I edited the code a little bit, because I wanted to be able to just write the id of a file instead of an url. It would be great if you implemented this too.

  3. Nathan Arthur says:

    Christian – I looked into doing that when I originally wrote the plugin, but it causes a problem. This plugin (like many others) determines the mime-type by making a web request and asking the web server what the mime-type is. Textpattern always answers “application/octet-stream” as the mime-type, to try to trick browsers into downloading files (rather than showing them embedded), and that’s never the right type for media files.

    That means that the podcast feed always has the wrong mime-type for any files that are uploaded via textpattern’s ‘files’ feature, and therefore they don’t show up correctly in a lot of feed readers. Crappy. Of course, it hadn’t occurred to me that people might just go ahead and upload the files anyway. (duh.) I’ll document the problem on the ‘features’ page.

    Do you mind sending me your updated plugin code? I’ll merge it into mine (and give you credit) and publish it. I think the long-term for this problem (and many others) is probably to utilize a second custom field for the mime-type, and allow users to override it. I’ll add that to the list for version 1.0.

  4. Amitai Schlair says:

    As I accumulate episodes, I’m realizing it’d be nice if there were a way to override Textpattern’s limit of N articles per feed. Ideally, I’d like to have it be unlimited for the podcast feed (but not other feeds). That way, if someone comes late to the party, they can still go back and get the early goodies directly in iTunes (or whatever). Is there already a way to do this with Textpattern, or with a plugin?

  5. Nathan Arthur says:

    Amitai – Textpattern has a setting for how many articles to include in your feeds, but it isn’t feed-specific. See Admin -> Preferences -> Advanced -> How many articles should be included in feeds?

    Whenever TXP 4.0.5 comes out, it will have my patch to consolidate and refactor the feed code, which will then allow me (or someone else) to make a custom feed. At that point, it should be possible to make a custom podcast feed with any number of articles. Until then, though, I don’t see any easy way.

  6. Nathan Arthur says:

    Amitai – strike that, reverse it. I accidentally discovered that TXP will allow you to override the feed limit, by simply appending “?limit=20” to your URL. This can also be accomplished with the “limit” attribute to “txp:feed_link”.

  7. Amitai Schlair says:

    Nice! It seems there is a hard-coded limit of 100, though, and “limit=0” doesn’t do what I thought it might, so 4.0.5 will still be good to have.

  8. Will says:

    Great! Thanks for this. Just downloaded Audacity, fiddled around a bit, uploaded your plugin to my textpattern site, and I’ve now published my first podcast. Thanks again,
    Will

  9. Nathan Arthur says:

    Will – glad to hear it’s working for you! Thanks for the feedback.

  10. Fabio says:

    Thanks Nathan for this plugin! Just discovered it and blogged about it to tell my German audience.

  11. Nathan Arthur says:

    Fabio – thank you! That’s great :)

  12. Amitai Schlair says:

    In case anyone on this thread is looking (7 years later!) for alternatives to Textpattern and tru_podcast, I’ve moved my podcast to ikiwiki.

Add a comment

(will not be displayed)

(not required)