Skip to content

Spec: iTunes Podcast RSS

Ryan Parman edited this page Aug 27, 2017 · 7 revisions

Updated: WWDC 2017

Table of Contents

Abstract

Podcasts Connect accepts RSS 2.0 tags as well as some additional tags specific to the iTunes Store. Additional tags are not required, but are recommended for possible feature placement on the iTunes Store and Podcasts.

When you use tags specific to the iTunes Store, you must add the following namespace declaration as the second line in your XML:

<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 Store tags. Without this declaration, Podcasts Connect ignores all tags specific to the iTunes Store. The namespace definition is case sensitive, and must be entered as shown.

For text encoding, use plain text UTF-8 encoding for your feed (no markup or HTML). Tag values are limited to 255 characters, except for <itunes:summary>, which can be up to 4000 characters. Don’t add leading or trailing spaces to your values. Enclose all portions of your XML that contain embedded links in a CDATA section to prevent formatting issues, and to ensure proper link functionality. For example:

<itunes:summary><![CDATA[<a href="http://www.apple.com">Apple</a>]]></itunes:summary>

The following table lists the RSS tags for Podcasts Connect and shows which tags apply at the <channel> level (which relate to the podcast as a whole), which tags apply to individual <item> tags (which are specific to a given episode), and where the tag contents appear on the iTunes Store.

RSS Elements

<enclosure>

The <enclosure> tag has three attributes: URL, length, and type:

  • url: The URL attribute points to your podcast content. The file extension specified within the URL attribute determines whether or note content appears in the podcast directory. Supported file formats include M4A, MP3, MOV, MP4, M4V, PDF, and EPUB.

  • length: The length attribute is the file size in bytes. You can find this information in the properties of your podcast file (on a Mac, choose File → Get Info and refer to the size row).

  • type: The type attribute provides the correct category for the type of file you are using. The type values for the supported file formats are: audio/x-m4a, audio/mpeg, video/quicktime, video/mp4, video/x-m4v, application/pdf, and document/x-epub.

<enclosure url="http://example.com/podcasts/everything/AllAboutEverythingEpisode2.mp3" length="5650889" type="audio/mpeg"/>
Usage Description
<channel> Unsupported
<item> Supported
iTunes UI N/A

<guid>

Every <item> tag (episode) should have a permanent, case-sensitive globally unique identifier (GUID). When you add episodes to your RSS feed, GUIDs are compared in case-sensitive fashion to determine which episodes are new. If you don’t add the GUID for an episode, the episode URL is used instead.

Assign the GUID to an episode only once and never change it. Assigning new GUIDs to existing episodes can cause issues with your podcast’s listing and chart placement in the iTunes Store.

Usage Description
<channel> Supported
<item> Supported
iTunes UI N/A

<title>

Pay close attention to the title at the <channel> and <item> level of your podcast feed. The iTunes Store uses these fields for search. The metadata for your podcast, along with your cover art, is your product packaging and can affect whether your podcast shows up in relevant searches, and how likely users are to subscribe to it.

Make your title specific. A podcast titled Our Community Bulletin is too vague to attract many subscribers, no matter how compelling the content.

Usage Description
<channel> Supported
<item> Supported
iTunes UI Name column

<link>

<link>http://www.example.com/podcasts/everything/index.html</link>
Usage Description
<channel> Supported
<item> Unsupported
iTunes UI Website link under podcast details

<copyright>

<copyright>&#x2117; &amp; &#xA9; 2014 John Doe &amp; Family</copyright>
Usage Description
<channel> Supported
<item> Unsupported
iTunes UI Visible under podcast details

<pubDate>

The <pubDate> tag specifies the date and time when an episode was released. Format the content using the RFC 2822 specifications. For example: Wed, 15 Jun 2014 19:00:00 GMT.

Usage Description
<channel> Unsupported
<item> Supported
iTunes UI Released column

<itunes:author>

The content you specify in the <itunes:author> tag appears in the Artist column on the iTunes Store. If the tag is not present, the iTunes Store uses the contents of the <author> tag. If <itunes:author> is not present at the RSS feed level, the iTunes Store uses the contents of the <managingEditor> tag.

Usage Description
<channel> Supported
<item> Supported
iTunes UI Visible under podcast title and in iTunes Store browse

<itunes:block>

Specifying the <itunes:block> tag with a Yes value in:

  • A <channel> tag (podcast), prevents the entire podcast from appearing on the iTunes Store podcast directory

  • An <item> tag (episode), prevents that episode from appearing on the iTunes Store podcast directory

For example, you might want to block a specific episode if you know that its content would otherwise cause the entire podcast to be removed from the iTunes Store. Specifying any value other than Yes has no effect.

Usage Description
<channel> Supported
<item> Supported
iTunes UI N/A

<itunes:category>

Users can browse podcast subject categories in the iTunes Store by choosing a category from the Podcasts pop-up menu in the navigation bar. Use the <itunes:category> tag to specify the browsing category for your podcast.

You can also define a subcategory if one is available within your category. Although you can specify more than one category and subcategory in your feed, the iTunes Store only recognizes the first category and subcategory. For a complete list of categories and subcategories, see Podcasts Connect categories.

NOTE: When specifying categories and subcategories, be sure to properly escape ampersands:

Single category:

<itunes:category text="Music" />

Category with ampersand:

<itunes:category text="TV &amp; Film" />

Category with subcategory:

<itunes:category text="Society &amp; Culture">
    <itunes:category text="History" />
</itunes:category>

Multiple categories:

<itunes:category text="Society &amp; Culture">
    <itunes:category text="History" />
</itunes:category>

<itunes:category text="Technology">
    <itunes:category text="Gadgets" />
</itunes:category>
Usage Description
<channel> Supported
<item> Unsupported
iTunes UI Visible under podcast details and in iTunes Store browse

<itunes:image>

Specify your podcast artwork using the <a href> attribute in the<itunes:image> tag. If you do not specify the <itunes:image> tag, the iTunes Store uses the content specified in the RSS feed image tag and Apple does not consider your podcast for feature placement on the iTunes Store or Podcasts.

Depending on their device, subscribers see your podcast artwork in varying sizes. Therefore, make sure your design is effective at both its original size and at thumbnail size. Apple recommends including a title, brand, or source name as part of your podcast artwork. For examples of podcast artwork, see the Top Podcasts. To avoid technical issues when you update your podcast artwork, be sure to:

  • Change the artwork file name and URL at the same time
  • Verify the web server hosting your artwork allows HTTP head requests

The <itunes:image> tag is also supported at the <item> (episode) level. For best results, Apple recommends embedding the same artwork within the metadata for that episode’s media file prior to uploading to your host server; using Garageband or another content-creation tool to edit your media file if needed.

NOTE: Artwork must be a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels, in JPEG or PNG format, 72 dpi, with appropriate file extensions (.jpg, .png), and in the RGB colorspace. These requirements are different from the standard RSS image tag specifications.

Usage Description
<channel> Supported
<item> Supported
iTunes UI Visible in the same location as the album art

<itunes:duration>

The content you specify in the <itunes:duration> tag appears in the Time column in the List View on the iTunes Store.

Specify one of the following formats for the <itunes:duration> tag value:

  • HH:MM:SS
  • H:MM:SS
  • MM:SS
  • M:SS

Where H = hours, M = minutes, and S = seconds.

If you specify a single number as a value (without colons), the iTunes Store displays the value as seconds. If you specify one colon, the iTunes Store displays the number to the left as minutes and the number to the right as seconds. If you specify more then two colons, the iTunes Store ignores the numbers farthest to the right.

Usage Description
<channel> Unsupported
<item> Supported
iTunes UI Time column

<itunes:explicit>

The <itunes:explicit> tag indicates whether your podcast contains explicit material. You can specify the following values:

  • If you specify yes, explicit, or true, indicating the presence of explicit content, the iTunes Store displays an Explicit parental advisory graphic for your podcast.

  • If you specify clean, no, or false, indicating that none of your podcast episodes contain explicit language or adult content, the iTunes Store displays a Clean parental advisory graphic for your podcast.

NOTE: Podcasts containing explicit material are not available in some iTunes Store territories.

Usage Description
<channel> Supported
<item> Supported
iTunes UI Parental advisory graphic under podcast details or episode badge in Name column

<itunes:isClosedCaptioned>

Specifying the <itunes:isClosedCaptioned> tag with a Yes value indicates that the video podcast episode is embedded with closed captioning and the iTunes Store should display a closed-caption icon next to the corresponding episode. This tag is only supported at the <item> level (episode).

NOTE: If you specify a value other than Yes, no closed-caption indicator appears.

Usage Description
<channel> Unsupported
<item> Supported
iTunes UI Closed caption graphic in Name column

<itunes:order>

Use the <itunes:order> tag to specify the number value in which you would like the episode to appear and override the default ordering of episodes on the iTunes Store.

For example, if you want an <item> to appear as the first episode of your podcast, specify the <itunes:order> tag with 1. If conflicting order values are present in multiple episodes, the iTunes Store uses <pubDate>.

Usage Description
<channel> Unsupported
<item> Supported
iTunes UI N/A

<itunes:complete>

Specifying the <itunes:complete> tag with a Yes value indicates that a podcast is complete and you will not post any more episodes in the future. This tag is only supported at the <channel> level (podcast).

NOTE: If you specify a value other than Yes, nothing happens.

Usage Description
<channel> Supported
<item> Unsupported
iTunes UI N/A

<itunes:new-feed-url>

Use the <itunes:new-feed-url> tag to manually change the URL where your podcast is located. This tag is only supported at a <channel>level (podcast).

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

NOTE: You should maintain your old feed until you have migrated your existing subscribers. For more information, see Update your RSS feed URL.

Usage Description
<channel> Supported
<item> Unsupported
iTunes UI Not visible, reports new feed URL to the iTunes Store

<itunes:owner>

Use the <itunes:owner> tag to specify contact information for the podcast owner. Include the email address of the owner in a nested <itunes:email> tag and the name of the owner in a nested <itunes:name> tag.

The <itunes:owner> tag information is for administrative communication about the podcast and is not displayed on the iTunes Store.

Usage Description
<channel> Supported
<item> Unsupported
iTunes UI Not visible, used for contact information only

<itunes:subtitle>

The content you specify in the <itunes:subtitle> tag appears in the Description column on the iTunes Store. For best results, choose a subtitle that is only a few words long.

Usage Description
<channel> Supported
<item> Supported
iTunes UI Description column

<itunes:summary>

The content you specify in the <itunes:summary> tag appears on the iTunes Store page for your podcast. You can specify up to 4000 characters. The information also appears in a separate window if a users clicks the Information icon in the Description column. If you do not specify a <itunes:summary> tag, the iTunes Store uses the information in the <description> tag.

Usage Description
<channel> Supported
<item> Supported
iTunes UI Visible when users click the Information icon in the Description column

<language>

Use the <language> tag to specify a language for your podcast.

Because the iTunes Store is available in territories around the world, it is critical to specify the language of a podcast. The iTunes Store only supports values from the ISO 639 list (two-letter language codes, with some possible modifiers, such as "en-us").

Usage Description
<channel> Supported
<item> Supported
iTunes UI N/A

The following is an example of a well-formed RSS feed.

Apple recommends using http://validator.w3.org/feed/ to validate your feeds.

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd">
    <channel>
        <title>All About Everything</title>
        <link>http://www.example.com/podcasts/everything/index.html</link>
        <language>en-us</language>
        <copyright>℗ &amp; © 2014 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 Podcasts app or in the iTunes Store</itunes:summary>
        <description>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 Podcasts app or in the iTunes Store</description>
        <itunes:owner>
            <itunes:name>John Doe</itunes:name>
            <itunes:email>john.doe@example.com</itunes:email>
        </itunes:owner>
        <itunes:image href="http://example.com/podcasts/everything/AllAboutEverything.jpg"/>
        <itunes:category text="Technology">
            <itunes:category text="Gadgets"/>
        </itunes:category>
        <itunes:category text="TV &amp; Film"/>
        <itunes:category text="Arts">
            <itunes:category text="Food"/>
        </itunes:category>
        <itunes:explicit>no</itunes:explicit>
        <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><![CDATA[This week we talk about 
                <a href="https://itunes/apple.com/us/book/antique-trader-salt-pepper/id429691295?mt=11">salt and pepper shakers</a>
                , comparing and contrasting pour rates, construction materials, and overall aesthetics. Come and join the party!]]></itunes:summary>
            <itunes:image href="http://example.com/podcasts/everything/AllAboutEverything/Episode1.jpg"/>
            <enclosure length="8727310" type="audio/x-m4a" url="http://example.com/podcasts/everything/AllAboutEverythingEpisode3.m4a"/>
            <guid>http://example.com/podcasts/archive/aae20140615.m4a</guid>
            <pubDate>Tue, 08 Mar 2016 12:00:00 GMT</pubDate>
            <itunes:duration>07:04</itunes:duration>
            <itunes:explicit>no</itunes:explicit>
        </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>
            <itunes:image href="http://example.com/podcasts/everything/AllAboutEverything/Episode2.jpg"/>
            <enclosure length="5650889" type="video/mp4" url="http://example.com/podcasts/everything/AllAboutEverythingEpisode2.mp4"/>
            <guid>http://example.com/podcasts/archive/aae20140608.mp4</guid>
            <pubDate>Wed, 09 Mar 2016 13:00:00 EST</pubDate>
            <itunes:duration>04:34</itunes:duration>
            <itunes:explicit>no</itunes:explicit>
        </item>
        <item>
            <title>The Best Chili</title>
            <itunes:author>Jane Doe</itunes:author>
            <itunes:subtitle>Jane and Eric</itunes:subtitle>
            <itunes:summary>This week we talk about the best Chili in the world. Which chili is better?</itunes:summary>
            <itunes:image href="http://example.com/podcasts/everything/AllAboutEverything/Episode3.jpg"/>
            <enclosure length="5650889" type="video/x-m4v" url="http://example.com/podcasts/everything/AllAboutEverythingEpisode2.m4v"/>
            <guid>http://example.com/podcasts/archive/aae20140697.m4v</guid>
            <pubDate>Thu, 10 Mar 2016 02:00:00 -0700</pubDate>
            <itunes:duration>04:34</itunes:duration>
            <itunes:explicit>no</itunes:explicit>
            <itunes:isClosedCaptioned>Yes</itunes:isClosedCaptioned>
        </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 are a Blue person. Or vice versa.</itunes:summary>
            <itunes:image href="http://example.com/podcasts/everything/AllAboutEverything/Episode4.jpg"/>
            <enclosure length="498537" type="audio/mpeg" url="http://example.com/podcasts/everything/AllAboutEverythingEpisode4.mp3"/>
            <guid>http://example.com/podcasts/archive/aae20140601.mp3</guid>
            <pubDate>Fri, 11 Mar 2016 01:15:00 +3000</pubDate>
            <itunes:duration>03:59</itunes:duration>
            <itunes:explicit>no</itunes:explicit>
        </item>
    </channel>
</rss>
Clone this wiki locally