podcast-namespace/docs/1.0.md

RSS Namespace Extension for Podcast (xmlns:podcast DTD)

A wholistic RSS namespace for podcasting that is meant to synthesize the fragmented world of podcast namespaces. As elements are canonized, they will be added to this document so developers can begin implementation. The specifications below are considered locked and the team will prioritize backward compatibility. We are operating under the Rules for Standards-Makers.

The namespace for this extension is https://podcastindex.org/namespace/1.0. Clients which recognize this namespace must also recognize https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md as identical. The suggested tag prefix for use in XML is podcast, but clients should support alternate prefixes for this namespace. If your application generates RSS feeds and you implement one or more elements below, you will need to link this DTD in your XML:

<rss version="2.0" xmlns:podcast="https://podcastindex.org/namespace/1.0">

Podcast Tags

Each tag below exists in the podcast namespace within the specified parent. All attributes are required unless explicitly specified as optional.

Anywhere the url of a hyper-text based resource is specified, it must be given as https: and not http:.

Transcript

<podcast:transcript> This tag is used to link to a transcript or closed captions file. Multiple tags can be present for multiple transcript formats.

Parent

<item>

Count

Multiple

Attributes

• url: URL of the podcast transcript.

• type: Mime type of the file such as text/plain, text/html, application/srt, text/vtt, application/json

• language (optional): The language of the linked transcript. If there is no language attribute given, the linked file is assumed to be the same language that is specified by the RSS <language> element.

• rel (optional): If the rel="captions" attribute is present, the linked file is considered to be a closed captions file, regardless of what the mime type is. In that scenario, time codes are assumed to be present in the file in some capacity.

Examples

<podcast:transcript url="https://example.com/episode1/transcript.html" type="text/html" />

<podcast:transcript url="https://example.com/episode1/transcript.srt" type="text/srt" rel="captions" />

<podcast:transcript url="https://example.com/episode1/transcript.json" type="application/json" language="es" rel="captions" />

<podcast:transcript url="https://example.com/episode1/transcript.vtt" type="text/vtt" />

Detailed file format information and example files are here.

Locked

<podcast:locked> This tag may be set to yes or no. The purpose is to tell other podcast platforms whether they are allowed to import this feed. A value of yes means that any attempt to import this feed into a new platform should be rejected.

Parent

<channel>

Count

Single

Attributes

• owner: The owner attribute is an email address that can be used to verify ownership of this feed during move and import operations. This could be a public email or a virtual email address at the hosting provider that redirects to the owner's true email address. This is a critical element, and it's expected that podcast hosting providers (if not providing virtual addresses) will allow setting this element's value in their GUI with an emphasis to their users of how important it is to have this be a valid, working email address.

Examples

<podcast:locked owner="email@example.com">yes</podcast:locked>

<podcast:locked owner="email@example.com">no</podcast:locked>

Funding

<podcast:funding> This tag lists possible donation/funding links for the podcast. The content of the tag is the recommended string to be used with the link.

Parent

<channel>

Count

Multiple

Attributes

• url: The URL to be followed to fund the podcast.

Examples

<podcast:funding url="https://www.example.com/donations">Support the show!</podcast:funding>

<podcast:funding url="https://www.example.com/members">Become a member!</podcast:funding>

Please do not exceed 128 characters for the node value or it may be truncated by aggregators.

Chapters

<podcast:chapters> Links to an external file (see example file) containing chapter data for the episode. See the jsonChapters.md file for a description of the chapter file syntax. And, see the example.json example file for a real world example.

Parent

<item>

Count

Single

Attributes

• url: The URL where the chapters file is located.
• type: Mime type of file - JSON prefered, 'application/json+chapters'.

Examples

<podcast:chapters url="https://example.com/episode1/chapters.json" type="application/json+chapters" />

Soundbite

<podcast:soundbite> Points to one or more soundbites within a podcast episode. The intended use includes episodes previews, discoverability, audiogram generation, episode highlights, etc. It should be assumed that the audio/video source of the soundbite is the audio/video given in the item's <enclosure> element.

Parent

<item>

Count

Multiple

Attributes

• startTime: The time where the soundbite begins
• duration: How long is the soundbite (recommended between 15 and 120 seconds)
• node value (optional): Used as free form string from the podcast creator to specify a title for the soundbite (null defaults to episode title)

Examples

<podcast:soundbite startTime="73.0" duration="60.0" />

<podcast:soundbite startTime="1234.5" duration="42.25">Why the Podcast Namespace Matters</podcast:soundbite>

Please do not exceed 128 characters for the node value or it may be truncated by aggregators.

Person

<podcast:person> This element specifies a person of interest to the podcast. It is primarily intended to identify people like hosts, co-hosts and guests. Although, it is flexible enough to allow fuller credits to be given using the roles and groups that are listed in the Podcast Taxonomy Project

Parent

<item> or <channel>

Count

Multiple

Node value

This is the full name or alias of the person. This value cannot be blank.

Attributes

• role: (optional) Used to identify what role the person serves on the show or episode. This should be a reference to an official role within the Podcast Taxonomy Project list (see below). If role is missing then "host" is assumed.
• group: (optional) This should be a reference to an official group within the Podcast Taxonomy Project list. If group is not present, then "cast" is assumed.
• img: (optional) This is the url of a picture or avatar of the person.
• href: (optional) The url to a relevant resource of information about the person, such as a homepage or third-party profile platform. Please see the example feed for possible choices of what to use here.

The role and group attributes are case-insensitive. So, "Host" is the same as "host", and "Cover Art Designer" is the same as "cover art designer".

The full taxonomy list is here as a json file.

Please do not exceed 128 characters for the node value or they may be truncated by aggregators.

Examples

<podcast:person href="https://example.com/johnsmith/blog" img="http://example.com/images/johnsmith.jpg">John Smith</podcast:person>

<podcast:person role="guest" href="https://www.imdb.com/name/nm0427852888/" img="http://example.com/images/janedoe.jpg">Jane Doe</podcast:person>

<podcast:person role="guest" href="https://www.wikipedia/alicebrown" img="http://example.com/images/alicebrown.jpg">Alice Brown</podcast:person>

<podcast:person group="writing" role="guest" href="https://www.wikipedia/alicebrown" img="http://example.com/images/alicebrown.jpg">Alice Brown</podcast:person>

<podcast:person group="visuals" role="Cover Art Designer" href="https://example.com/artist/beckysmith">Becky Smith</podcast:person>

Location

<podcast:location> This tag is intended to describe the location of editorial focus for a podcast's content (i.e. "what place is this podcast about?"). The tag has many use cases and is one of the more complex ones. You are highly encouraged to read the full implementation document before starting to code for it.

Parent

<item> or <channel>

Count

Single

Node Value

This is a free-form string meant to be a human readable location. It may conform to conventional location verbiage (i.e. "Austin, TX"), but it shouldn't be depended on to be parseable in any specific way. This value cannot be blank.

Attributes

• geo: (recommended) This is a latitude and longitude given in "geo" notation (i.e. "geo:30.2672,97.7431").
• osm: (recommended) The Open Street Map identifier of this place, given using the OSM notation (i.e. "R113314")

Please do not exceed 128 characters for the node value or it may be truncated by aggregators.

Examples

<podcast:location geo="geo:30.2672,97.7431" osm="R113314">Austin, TX</podcast:location>

<podcast:location geo="geo:33.51601,-86.81455" osm="R6930627">Birmingham Civil Rights Museum</podcast:location>

<podcast:location geo="geo:-27.86159,153.3169" osm="W43678282">Dreamworld (Queensland)</podcast:location>

Please see the implementation document and the example feed for more examples.

Season

<podcast:season> This element allows for identifying which episodes in a podcast are part of a particular "season", with an optional season name attached.

Parent

<item>

Count

Single

Node Value

The node value is an integer, and represents the season "number". It is required.

Attributes

• name: (optional) - This is the "name" of the season. If this attribute is present, applications are free to not show the season number to the end user, and may use it simply for chronological sorting and grouping purposes.

Please do not exceed 128 characters for the name attribute.

Examples

<podcast:season>5</podcast:season>

<podcast:season name="Race for the Whitehouse 2020">3</podcast:season>

<podcast:season name="Egyptology: The 19th Century">1</podcast:season>

<podcast:season name="The Yearling - Chapter 3">3</podcast:season>

Episode

<podcast:episode> This element exists largely for compatibility with the season tag. But, it also allows for a similar idea to what "name" functions as in that element.

Parent

<item>

Count

Single

Node Value

The node value is a decimal number. It is required.

Attributes

• display: (optional) - If this attribute is present, podcast apps and aggregators are encouraged to show it's value instead of the purely numerical node value. This attribute is a string.

The episode numbers are decimal, so numbering such as 100.5 is acceptable if there was a special mini-episode published between two other episodes. In that scenario, the number would help with proper chronological sorting, while the display attribute could specify an alternate special "number" (a moniker) to display for the episode in a podcast player app UI.

Please do not exceed 32 characters for the display attribute.

Examples

<podcast:episode>3</podcast:episode>

<podcast:episode>315.5</podcast:episode>

<podcast:episode display="Ch.3">204</podcast:episode>

<podcast:episode display="Day 5">9</podcast:episode>