Mailing Lists: Apple Mailing Lists
Image of Mac OS face in stamp
Re: Updated iTunes RSS Spec
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Updated iTunes RSS Spec



Here's the current version. Happy carping!

Pete

Title: How To Publish a Podcast on the iTunes Music Store


Podcasting and iTunes: Technical Specification

Last Modified: 2005-10-20

For an overview of podcasting on iTunes, please refer to the Learn more page. From the iTunes Music Store home page:

  1. In the left column, under Inside the Music Store, click on Podcasts.
  2. In the left column, click on Submit a Podcast.
  3. Click on Learn More About Podcasting on iTunes.

This document supplements the Learn More page with the following topics:

  1. Submission and Feedback Processes
    1. Testing Your Feed
    2. Submitting Your Podcast Feed to iTunes
    3. Submission Errors
    4. The Queue
    5. Adding Episodes
    6. Removing or Blocking Your Feed
    7. Changing Your Feed URL
    8. Being Featured on the iTunes Home Page
    9. Tracking Usage
    10. Creating Video Podcasts
  2. An Example Feed
  3. iTunes RSS Tags
    1. Defining Tags with the iTunes Podcasting Namespace
    2. Text Encoding
    3. Use and Display of Common Tags in Channel and Item Sections
    4. <enclosure>
    5. <guid>
    6. <itunes:author>
    7. <itunes:block>
    8. <itunes:category>
    9. <itunes:duration>
    10. <itunes:explicit>
    11. <itunes:image>
    12. <itunes:keywords>
    13. <itunes:new-feed-url>
    14. <itunes:owner>
    15. <itunes:pubDate>
    16. <itunes:subtitle>
    17. <itunes:summary>
    18. <language>
    19. <ttl>
  4. Common Mistakes
    1. Wrong <pubDate> Format
    2. Failure to Escape Ampersands
    3. Using HTML Named Character Entities
  5. iTunes Categories for Podcasting
    1. Arts & Entertainment
    2. Audio Blogs
    3. Business
    4. Comedy
    5. Education
    6. Family
    7. Food
    8. Health
    9. International
    10. Movies & Television
    11. Music
    12. News
    13. Politics
    14. Public Radio
    15. Religion & Spirituality
    16. Science
    17. Sports
    18. Talk Radio
    19. Technology
    20. Transportation
    21. Travel

Submission and Feedback Processes

Podcasting on iTunes requires several steps:

  1. Creating your first episode, which can be an audio recording, video, or even a text document. Supported file formats include .m4a, .mp3, .mov, .mp4, .m4v, and .pdf.
  2. Posting your episode file(s) on a server with a publicly accessible URL.
  3. Creating an RSS feed (an XML file) that:
    1. conforms to the RSS 2.0 specification
    2. includes the recommended iTunes RSS tags,
    3. contains pointers to your episode.
  4. Posting the RSS file on a server.
  5. Submitting the URL for your RSS feed to iTunes.

The rest of this section covers the submission process. The remainder of this document focuses on technical aspects of preparing your RSS feed.

Testing Your Feed

When you have created your RSS feed and posted it to a server with a publicly addressable URL (i.e., not behind a firewall), you should test your feed to see if it works with iTunes:

  1. Launch iTunes.
  2. In the Advanced menu, select Subscribe to Podcast.
  3. Enter your feed URL in the text box and click OK.

iTunes will display your Podcasts list page, which shows all of the podcasts to which you have subscribed. You should see an orange circle, which indicates that iTunes is downloading your most recent episode. When the orange circle disappears, you should be able to see your Podcast title, a list of all the episodes referenced in your feed, and a check next to the most recent episode, indicating that it has been successfully downloaded. Double-click on the episode to play it in iTunes. If you can successfully play the episode, then your feed is working and you can submit your podcast to iTunes.

If the orange circle is replaced by an "i" in a black circle, iTunes encountered a problem with your feed or episode. You should troubleshoot your episode and feed before submitting it. Please do not submit your feed until you can successfully subscribe using the Advanced menu.

Submitting Your Podcast Feed to iTunes

If you can successfully subscribe to your feed using the Advanced menu in iTunes, you're ready to submit your feed:

  1. Launch iTunes.
  2. In the left navigation column, under Inside the Music Store, click on the Podcasts link to go to the Podcasts page.
  3. In the left column of the Podcasts page, click on the Submit a Podcast link.
  4. Follow the instructions on the Submit a Podcast page.

Note that you will need a valid iTunes account, and you will need to be logged into iTunes. If you are not logged in, iTunes will prompt you to do so before accepting your submission. By requiring you to log in, iTunes increases the likelihood of valid contact information for each submission. Your credit card will not be charged for submission of a podcast.

If you have created an RSS feed with all of the recommended iTunes tags, you will see a summary page immediately after you submit your feed URL. If you have not included <language>, <category>, and <explicit> tags in your feed, you will see a second screen prompting you for this information. Please note that you can change this information at a later date by including the tags in your feed. Your RSS feed is considered the current and authoritative source for information about your podcast.

Submission Errors

There are a variety of errors that iTunes can encounter when you submit your feed. Almost all of them can be avoided by testing your feed using the Advanced menu prior to submitting your feed.

In some cases, when you submit your feed URL, iTunes will respond by saying that the feed has already been submitted. There are two possible causes:

  1. Someone has already submitted the same feed URL.
  2. Someone has already submitted a feed with the same content in the <title> and <link> fields.

In either case, iTunes blocks your feed to avoid listing duplicate podcasts.

If the submission is blocked because the feed URL has already been submitted, and you are in control of the RSS feed, then you don't have a problem: your podcast is in iTunes and you can control it by editing your feed.

If you are the feed owner and the feed that is listed in iTunes is not under your control, you can attempt to contact the owner by searching the web, finding the feed, and examining the code for contact information.

The Queue

After your podcast is submitted, it is placed in a queue, where iTunes staff check it for problems. Your podcast may be rejected for a variety of reasons, including but not limited to:

In general, if there's something that you want to convey about your feed, please do so in the summary field in your RSS feed, not in the content of an episode.

Normally, podcasts that are added to the iTunes directory will appear first in iTunes search, and later in iTunes browse. Appearing in the browse category that you specified can take up to two days. The image associated with your podcast may also require additional time to appear, because images are edge-cached by iTunes and must propagate across the cacheing servers.

Adding Episodes

Whenever you create a new podcast episode, you should add a new <item> section to your podcast feed. The iTunes directory will list the episode the next time it reads your feed. The order in which the episodes appear is based on the pubDate for each item, with the most recent episodes appearing at the top of the list.

By default, the iTunes directory reads every feed once per day. However, you can control this rate using the < ttl> tag (see below). Note, however, that this tag affects the iTunes directory but not what existing subscribers see in their iTunes client. The client picks up new episodes based on the preferences set by the user.

Removing or Blocking Your Feed

If you are no longer creating a podcast and you want it removed from iTunes, you should:

  1. Log into iTunes.
  2. Find and select your podcast.
  3. Click on Report a Concern.
  4. Select "is mine and I want it removed from the Music Store" from the Choose a Reason menu.
  5. Explain why you want the podcast removed.

In most cases, we will remove the podcast from iTunes, especially if we find that the podcast is no longer available at the feed URL.

If you want to remove your feed temporarily, you can use the <block> tag described in the iTunes RSS Tags section below.

Changing Your Feed URL

Podcasters occasionally need to move their feed from one location to another. In this case, you should not remove your feed. If possible, you should set your web server to return a 301 error and redirect when receiving a request for the old feed. Doing so will cause both the iTunes Music Store and the iTunes clients that have subscribed to your podcast to pick up the new feed URL. Be sure to maintain the redirect for at least two weeks to ensure that most subscribers have attempted to download your most recent episode and have thereby received the new URL.

If you don't know how to return an HTTP 301, you can use the <itunes:new-feed-url> tag described in the iTunes RSS Tags section below. The tag will cause the iTunes music store to be updated with the new feed URL, but it will not inform iTunes clients of the new location. You may choose to include an audio note in your podcast, informing your subscribers that your podcast has changed locations. After adding the tag, be sure to keep your feed running at the old URL for at least 48 hours.

Being Featured on the iTunes Home Page

At iTunes, we're constantly on the lookout for podcasts that are breaking new ground with this medium, have new or unusual content, or just capture our interest. When we find them, we like to feature them on the Podcasts home page. While there are no sure-fire ways to get your podcast featured (and no, we do not accept payments for promotion), there are some minimum requirements. To be featured by iTunes, podcasts must have:

  1. An image. For image specs, see the iTunes RSS Tags section below.
  2. A robust and accurate description.
  3. Proper language, category, and explicit tagging.

In addition, featured podcasts must be regularly updated with new episodes. We occasionally feature a podcast after its first episode, but we generally like to see podcasts with at least 3 episodes, and we like to see that the most recent episode has been added in the past month.

Tracking Usage

Please note that iTunes does not provide usage statistics. Some podcasters have created mechanisms for tracking the number of times that each episode has been downloaded. iTunes does not provide support in how to track downloads, but the following notes may be helpful:

Creating Video Podcasts

Although iTunes can play a variety of .mp4, .m4v, and .mov video formats, video iPods require more specific formats. By following the steps in the Creating Video for iPod tutorial, QuickTime 7 Pro will automatically create an .m4v file containing H.264 video and AAC audio that is optimized for iPod. iPod can play the following video formats:

H.264 video
File formats: .m4v, .mp4, and .mov
Video: Up to 768 kbps, 320 x 240, 30 frames per second (fps), Baseline Profile up to Level 1.3
Audio: AAC-LC up to 160 kbps, 48 Khz, stereo audio

MPEG-4 video
File formats: .m4v, .mp4, and .mov
Video: Up to 2.5 mbps, 480 x 480, 30 fps, Simple Profile
Audio: AAC-LC up to 160 kbps, 48 Khz, stereo audio

An Example Feed

<?xml version="1.0" encoding="UTF-8"?>

<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" version="2.0">

 

<channel>

<ttl>60</ttl>

<title>All About Everything</title>

<link>http://www.example.com/podcasts/everything/index.html</link>

<language>en-us</language>

<copyright>&#x2117; &amp; &#xA9; 2005 John Doe &amp; Family</copyright>

<itunes:subtitle>A show about everything</itunes:subtitle>

<itunes:author>John Doe</itunes:author>

<itunes:summary>All About Everything is a show about everything. Each week we dive into any subject known to man and talk about it as much as we can. Look for our Podcast in the iTunes Music Store</itunes:summary>

<itunes:owner>

<itunes:name>John Doe</itunes:name>

<itunes:email>email@hidden</itunes:email>

</itunes:owner>

<itunes:image href="" />

<itunes:category text="Technology">

<itunes:category text="Gadgets"/>

</itunes:category>

<itunes:category text="Movies &amp; Television">

 

<item>

<title>Shake Shake Shake Your Spices</title>

<itunes:author>John Doe</itunes:author>

<itunes:subtitle>A short primer on table spices</itunes:subtitle>

<itunes:summary>This week we talk about salt and pepper shakers, comparing and contrasting pour rates, construction materials, and overall aesthetics. Come and join the party!</itunes:summary>

<enclosure url="" length="8727310" type="audio/x-m4a" />

<guid>http://example.com/podcasts/archive/aae20050615.m4a</guid>

<pubDate>Wed, 15 Jun 2005 19:00:00 GMT</pubDate>

<itunes:duration>7:04</itunes:duration>

<itunes:keywords>salt pepper shaker exciting</itunes:keywords>

</item>

 

<item>

<title>Socket Wrench Shootout</title>

<itunes:author>Jane Doe</itunes:author>

<itunes:subtitle>Comparing socket wrenches is fun!</itunes:subtitle>

<itunes:summary>This week we talk about metric vs. old english socket wrenches. Which one is better? Do you really need both? Get all of your answers here.</itunes:summary>

<enclosure url="" length="5650889" type="audio/mpeg" />

<guid>http://example.com/podcasts/archive/aae20050608.mp3</guid>

<pubDate>Wed, 8 Jun 2005 19:00:00 GMT</pubDate>

<itunes:duration>4:34</itunes:duration>

<itunes:keywords>metric socket wrenches tool</itunes:keywords>

</item>

 

<item>

<title>Red, Whine, &amp; Blue</title>

<itunes:author>Various</itunes:author>

<itunes:subtitle>Red + Blue != Purple</itunes:subtitle>

<itunes:summary>This week we talk about surviving in a Red state if you're a Blue person. Or vice versa.</itunes:summary>

<enclosure url="" length="4989537" type="audio/mpeg" />

<guid>http://example.com/podcasts/archive/aae20050601.mp3</guid>

<pubDate>Wed, 1 Jun 2005 19:00:00 GMT</pubDate>

<itunes:duration>3:59</itunes:duration>

<itunes:keywords>politics red blue state</itunes:keywords>

</item>

 

</channel>

</rss>

iTunes RSS Tags

iTunes uses RSS 2.0 plus some additional tags. Note that the additional tags are not required (except to be eligible for placement on the iTunes Home Page), but are recommended where needed in order to provide the best possible user experience, and conform with the aforementioned length limits.

Defining Tags with the iTunes Podcasting Namespace

When using the iTunes tags, you must add a namespace declaration as the second line in your feed xml, like this:

<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" version="2.0">

The namespace declaration points to a document that defines the iTunes tags. Without the declaration, the tags are meaningless.

Note that the namespace definition is case sensitive, and the previous location of the namespace had capital letters in it. The old namespace definition is still supported, but the new (all lowercase) definition is preferred.

Text Encoding

Please use UTF-8 encoding for your feed. Other encodings are not guaranteed to work in iTunes.

All values should be plain text (no markup or HTML). Values are limited to 255 characters, except for <itunes:summary> which can be up to 4000 characters. Whitespace in values is significant, i.e. it will show in iTunes, so don't add leading or trailing whitespace to your values. CDATA sections are strongly discouraged.

Use and Display of Common Tags in Channel and Item Sections

The following table shows which tags apply to the channel (podcast) as a whole and which tags apply to individual items (episodes). The table also shows where the tag contents appear in iTunes:

xml tag

channel

item

where content appears in iTunes

<title>

Y

Y

Name column

<link>

Y

 

website link and arrow in Name column

<copyright>

Y

 

in the iTunes Music Store

<pubDate>

 

Y

Release Date column

<itunes:author>

Y

Y

Artist column

<itunes:block>

Y

Y

prevent an episode or podcast from appearing

<itunes:category>

Y

 

Category column and in iTunes Music Store Browse

<itunes:duration>

 

Y

Time column

<itunes:explicit>

Y

Y

parental advisory graphic in Name column

<itunes:keywords>

Y

Y

not visible but can be searched

<itunes:owner>

Y

 

not visible, used for contact only

<itunes:subtitle>

Y

Y

Description column

<itunes:summary>

Y

Y

when the "circled i" in Description column is clicked

<enclosure>

The file extension of the url attribute of this tag is used to determine if an item should appear in the Podcast directory. Supported extensions include "m4a", "mp3", "mov", "mp4", and "pdf".

<guid>

Every <item> should have a globally unique identifier that never changes. When you add episodes to your feed, guids are compared in case sensitive fashion to determine which episodes are new. If you omit the guid for an episode, the episode url will be used instead.

<itunes:author>

The contents of this tag is shown in the Artist column in iTunes. If the tag is not present, iTunes uses the contents of the <author> tag. If <itunes:author> is not present at the feed level, iTunes will use the contents of <managingEditor>.

<itunes:block>

Use this inside a <channel> element to prevent the entire podcast from appearing in the iTunes Podcast directory. Use this inside an <item> element to prevent that episode from appearing in the iTunes Podcast directory. For example, you may want a specific episode blocked from iTunes if it's content might cause the feed to be removed from iTunes.

If this tag is present and set to "yes" (case insensitive), that means to block the feed or the episode. If the tag's value is any other value, including empty string, it's indicated as a signal to unblock the feed or episode. At the feed level, if there is no block tag, then the block status of the feed is left unchanged. At the episode level, if there is no block tag, it is the same as if a block=no were present.

<itunes:category>

When browsing Podcasts in the iTunes Music Store, categories are shown in the 2nd column and subcategories are shown in the 3rd column. Not all categories have subcategories.

Categories and subcategories can be specified as follows. Use a top level <itunes:category> to specify the browse category, and a nested <itunes:category> to specify the browse subcategory. Choose from the existing categories and subcategories on the iTunes Music Store. Be sure to properly escape ampersands. Note that multiple categories are allowed.

Single category:

  <itunes:category text="Audio Blogs" />

Category with ampersand:

  <itunes:category text="Movies &amp; Television" />

Category with Subcategory:

  <itunes:category text="Arts &amp; Entertainment">
      <itunes:category text="Games" />
  </itunes:category>

Entry with multiple categories:

  <itunes:category text="Arts &amp; Entertainment">
      <itunes:category text="Games" />
  </itunes:category>
  <itunes:category text="Technology">
      <itunes:category text="Computers" />
  </itunes:category>

<itunes:duration>

The contents of this tag is shown in the Time column in iTunes.

The tag can be formatted HH:MM:SS, H:MM:SS, MM:SS, or M:SS (H = hours, M = minutes, S = seconds). If an integer is provided (no colon present), the value is assumed to be in seconds. If one colon is present, the number to the left is assumed to be minutes, and the number to the right is assumed to be seconds. If more than two colons are present, the numbers furthest to the right are ignored.

<itunes:explicit>

This tag should be used to indicate whether or not your podcast contains explicit material. The three values for this tag are "yes", "no", and "clean".

If you populate this tag with "yes", an "explicit" parental advisory graphic will appear next to your podcast artwork on the iTunes Music Store, and in the Name column in iTunes. If the value is "clean", the parental advisory type is considered Clean, meaning that no explicit language or adult content is included anywhere in the episodes, and a "clean" graphic will appear. If the explicit tag is present and has any other value (e.g. "no") you see no indicator -- blank is the default advisory type.

<itunes:image>

This tag specifies the artwork for your podcast. Put the url to the image in the href attribute. iTunes prefers square .jpg images that are at least 300 x 300 pixels, which is different than what is specified for the standard RSS image tag.

iTunes supports images in JPEG and PNG formats. The url must end in ".jpg" or ".png". If the itunes:image tag is not present, iTunes will use the contents of the RSS image tag.

<itunes:keywords>

This tag allows users to search on text keywords. Use commas to separate keywords.

<itunes:new-feed-url>

This tag allows you to change the URL where the podcast feed is located. The feed format is:

<itunes:new-feed-url>http://newlocation.com/example.rss</itunes:new-feed-url>

After adding the tag to your old feed, you should maintain the old feed for 48 hours before retiring it. At that point, iTunes will have updated the directory with the new feed URL. For more information, please see the "Changing Your Feed URL" section above.

<itunes:owner>

This tag contains information that will be used to contact the owner of the podcast for communication specifically about their podcast. It will not be publicly displayed.

Put the email address of the owner in a nested <itunes:email>element.

Put the name of the owner in a nested <itunes:name>element.

<itunes:pubDate>

This tag specifies the date and time when an episode was released. The format for the content should be per RFC 2822; e.g.:

Wed, 15 Jun 2005 19:00:00 GMT

If <pubDate> is included, this value is used over the Itunes:pubDate value.

<itunes:subtitle>

The contents of this tag are shown in the Description column in iTunes. The subtitle displays best if it is only a few words long.

<itunes:summary>

The contents of this tag are shown in a separate window that appears when the "circled i" in the Description column is clicked. It also appears on the iTunes Music Store page for your podcast. This field can be up to 4000 characters. If <itunes:summary> is not included, the contents of the <description> tag are used.

<language>

Because iTunes operates sites worldwide, it is critical to specify the language of a podcast. Accepted values are those in the ISO 639-1 Alpha-2 list (two-letter language codes).

<ttl>

The ttl tag stands for "time-to-live". It is an optional integer value that controls how many minutes iTunes will wait between checking for changes in a podcast. If no time-to-live is set on the podcast, the updater job assumes a time-to-live of 24 hours.

Common Mistakes

Wrong <pubDate> Format

The date and time format in <pubDate> must conform toRFC 2822.

The date must be "day-of-week, day month year". The time must be in 24 hour format (no AM or PM) and must include the time zone offset.

<!-- date and time not in RFC 2822 format -->
<pubDate>7/6/2005 1:00:00 PM</pubDate>

<!-- valid date and time format -->
<pubDate>Wed, 6 Jul 2005 13:00:00 PDT</pubDate>
<pubDate>Wed, 6 Jul 2005 13:00:00 -0700</pubDate>

Failure to Escape Ampersands

<!-- illegal xml -->
<title>Food & Wine</title>

<!-- valid xml -->
<title>Food &amp; Wine</title>

Using HTML Named Character Entities

<!-- illegal xml -->
<copyright>&copy; 2005 John Doe</copyright>

<!-- valid xml -->
<copyright>&#xA9; 2005 John Doe</copyright>

Unlike HTML, XML supports only five "named character entities":

character

name

xml

&

ampersand

&amp;

<

less-than sign

&lt;

>

greater-than sign

&gt;

'

apostrophe

&apos;

"

quotation

&quot;

The five characters above are the only characters that require escaping in XML. All other characters can be entered directly in an editor that supports UTF-8. You can also use numeric character references that specify the Unicode for the character, for example

character

name

xml

©

copyright sign

&#xA9;

sound recording copyright

&#x2117;

®

trade mark sign

&#x2122;

For further reference see XML Character and EntityReferences.

iTunes Categories for Podcasting

Arts & Entertainment

Audio Blogs

Business

Comedy

Education

Family

Food

Health

International

Movies & Television

Music

News

Politics

Public Radio

Religion & Spirituality

Science

Sports

Talk Radio

Technology

Transportation

Travel




Pete Alcorn Apple iTunes Podcasting


On Nov 3, 2005, at 9:59 PM, Steve Harris wrote:

I heard Madge Weinstein (Yeast Radio - I know!) mention on a recent podcast that someone had sent her an updated iTunes spec dated October 20th - at least I think it is a spec, as it was titled "How to publish a podcast on the iTunes Music Store" - the same as the current version.

This reminds me of when a podcaster surprised me by sending the July 7th version of the iTunes spec before it was made public on July 17th, and brings me to a novel suggestion:

Regardless of whether the above information is correct, why not, as soon as the new iTunes RSS spec is deemed ready but before it is released, make it available to this list for discussion? That way we can see if it answers the outstanding questions and issues before it hits the wider world, is set in stone and everyone starts carping about it.

The scope could be to review the document, not suggest changes to the actual implementation - just to keep things focussed.

-Steve

_______________________________________________
Do not post admin requests to the list. They will be ignored.
syndication-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
40apple.com


This email sent to email@hidden

 _______________________________________________
Do not post admin requests to the list. They will be ignored.
syndication-dev mailing list      (email@hidden)
Help/Unsubscribe/Update your Subscription:

This email sent to email@hidden

References: 
 >Updated iTunes RSS Spec (From: Steve Harris <email@hidden>)



Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Contact Apple | Terms of Use | Privacy Policy

Copyright © 2011 Apple Inc. All rights reserved.