Proposal - <podcast:notes>

[barrowclift]

⚠️ Click here to read the latest proposal in the comments ⚠️

This original proposal remains below for historical preservation purposes only.

---

What

Two new tags:

1. <podcast:notes> for what we'd consider "show notes", where long form details from a particular episode like referenced materials, links, images, etc. would reside (e.g. see https://atp.fm/503)
2. <podcast:summary> for a brief summary or synopsis of the episode in question (e.g. Tony and friends discuss Netflix's new series, "The Sandman")

Why

Against the RSS spec, the <description> element is used by many creators for long form "show notes" and not a short synopsis, leaving no tag appropriate to hold a brief actual description of the episode in question.

Since <description> is often used in this way, clients don't have a nice, brief synopsis available to display in episode lists. The only appropriate tag they have is <description>, but since many creators use this for long form show notes, it can result in suboptimal episode lists like this: https://podcastindex.org/podcast/44367

The community would greatly benefit from having a proper means to supply both a brief list-friendly episode summary and long form show notes.

How

I propose two new tags instead of just introducing a single new one because there's no community consensus on how to use <description>. There are many podcasts out there that use <description> for that brief summary (e.g. https://podcastindex.org/podcast/961821), but there are many others that instead use <description> for their detailed episode notes (e.g. https://podcastindex.org/podcast/44367).

Perhaps because of this, Podcast clients commonly use <description> for both their episode list summary text (trimmed to a certain number of characters) and their notes text when viewing or playing a particular episode. This historical baggage not only leads to a subpar user experience, but also prevents us from making assumptions about what it does or does not contain.

The most pragmatic way to solve this is a clean break for the podcast namespace: leave <description> as the abused fallback, but provide two new tags in the podcast namespace to prevent this issue from happening again: <podcast:notes> and <podcast:summary>.

---

Parent

<item> for both

Count

Single for each

Node values

<podcast:summary> would be a free-form String, with a plead similar to the Person node value to not exceed 180 characters for the node value or risk truncation by aggregators or clients.

<podcast:notes> would also be a free-form String, only this time with no specified character limit, in the same way there's no character limit today on the RSS <description> field.

Examples

<podcast:summary>Tony and friends discuss Netflix's new series, "The Sandman"</podcast:summary>
<podcast:notes><![CDATA[<ul>
<li>Follow-up:
<ul>
<li>Link to the previous show discussed: <a href="#">"Some Great Show"</a></li>
<li>Some correction on an assertion made on a previous episode, it was Foo, not Bar.</li>
</ul>
</li>
<li><a href="#">Click here to read up on some event mentioned off-hand during the show</a>
<li><a href="#">Direct link to some cool quote from someone</a></li>
<li><img src="#" alt="some image referenced during the show"</li>
<li>You get the idea.</li>
</ul>
]]></podcast:nodes>

[theDanielJLewis]

I agree that there we should have a <podcast:notes> tag, but for a different use, and I have issues with the presented premise.

Most podcasters aren't actually making these choices about the text fields. They either don't know the best way to use the separate fields, or their publishing tools don't actually give all the right guidance and options.

Apple has deprecated their own <itunes:summary> tag in favor of the RSS standard tag <description>. And we already have a tag that's so common for long-form content that I think many people don't realize it's not a standard RSS tag: <content:encoded>.

I think the description should be for the one-paragraph summary of the episode, <content:encoded> for the full text version (either an article or a well-formatted transcript), and then our new tag <podcast:notes> for the actionable notes (like the outline, links, and citations).

I publish my own feed with PowerPress and not even it gives the full control I wish it did. So here's how I would like my RSS feed to work with these three fields (taken from "What Is Podcasting 2.0 and Why Does It Matter?"):

<description>
  The podcasting industry has grown a lot since its birth in 2004, but the core of what a podcast could be
  and what it could do hasn&#039;t changed much. Now, Podcasting 2.0 revolutionizes the industry with highly requested
  innovations that will help everyone on all sides of the RSS feeds.
</description>

<podcast:notes>
  <![CDATA[
    <p>The podcasting industry has grown a lot since its birth in 2004, but the core of what a podcast could be and what it could do hasn't changed much. Now, Podcasting 2.0 revolutionizes the industry with highly requested innovations that will help everyone on all sides of the RSS feeds.</p>
    <p>Please share this episode from your podcast app or https://theaudacitytopodcast.com/podcasting20</p>
    <p>## What is "Podcasting 2.0"?</p>
    <ul>
      <li><a href="https://PodcastNamespace.org">Learn more about the Podcast Namespace</a></li>
      <li><a href="https://podcastindex.org/podcast/920666">Follow the Podcasting 2.0 podcast</a></li>
    </ul>
    <p>## Podcasting 2.0 is for audiences</p>
    <p>## Podcasting 2.0 is for podcasters</p>
    <p>## Podcasting 2.0 is for developers</p>
    <p>## Podcasting 2.0 is even for advertisers</p>
    <p>## This is the new litmus test for podcasting tools</p>
    <p>If your podcast-publishing tools do not already support Podcasting 2.0, switch!</p>
    <a href="">Retweet this</a></p>
    <p>## How to upgrade your podcast experience with Podcasting 2.0</p>
    <ul>
      <li><a href="https://github.com/Lehmancreations/Podcast-Namespace-Wordpress-Plugin/releases">WordPress with PowerPress, plus the Podcast Namespace plugin</a></li>
      <li><a href="https://theaudacitytopodcast.com/blubrry">Blubrry podcast hosting</a></li>
      <li><a href="https://theaudacitytopodcast.com/buzzsprout">Buzzsprout</a></li>
      <li><a href="https://theaudacitytopodcast.com/libsyn">Libsyn</a></li>
      <li><a href="https://theaudacitytopodcast.com/captivate">Captivate</a></li>
      <li><a href="https://podcastindex.org/apps">More options</a></li>
    </ul>
    <p>## How to get involved in Podcasting 2.0</p>
    <ul>
      <li><a href="https://podcastindex.org">Main website</a></li>
      <li><a href="https://podcastindex.org/podcast/920666">Podcasting 2.0 podcast</a></li>
      <li><a href="https://podcastindex.social">Social conversations</a></li>
      <li><a href="https://github.com/Podcastindex-org">GitHub</a></li>
      <li><a href="https://github.com/Podcastindex-org/podcast-namespace">Podcast Namespace on GitHub</a></li>
    </ul>
    <p>## Accept no cheap imitations!</p>
    <hr />
    <p>Start and grow your own podcast for passion and PROFIT! Learn more and follow at https://theaudacitytopodcast.com/</p>
    <p>Know, engage, and grow your audience with the power of podcast reviews! https://mypodcastreviews.com/</p>
    <p>FEEDBACK</p>
    <p>Call (903) 231-2221<br />
    Email feedback@theaudacitytopodcast.com<br />
    Send a voice message from https://theaudacitytopodcast.com/</p>
    <p>MAILING ADDRESS</p>
    <p>The Audacity to Podcast<br />
    PO Box 739<br />
    Burlington, KY 41005</p>
  ]]>
</podcast:notes>

<content:encoded>
  <![CDATA[
    <p>The podcasting industry has grown a lot since its birth in 2004, but the core of what a podcast could be and what it could <em>do</em> hasn't changed much. Now, Podcasting 2.0 revolutionizes the industry with highly requested innovations that will help everyone on all sides of the RSS feeds.</p>

    <h2>What <em>is</em> &#8220;Podcasting 2.0&#8221;?</h2>

    <p>Podcasting was created by Adam Curry and Dave Winer. Now, Adam Curry—the only true &#8220;podfather&#8221;—and Dave Jones are leading the way to the next generation of podcasting, and I'm thrilled to be an active contributor!</p>

    <p>Podcasting 2.0 is improving the podcast experience for listeners, podcasters, developers, and even advertisers. It's creating the next generation of podcasting by making podcasts more engaging. Podcasting 2.0 introduces new technical standards, new ways to monetize, and an independently maintained podcast catalog free from corporate and government censorship. Whether you're a listener, a podcaster, a podcast-app or podcasting-service developer, and someone who advertises in podcasts, there's something to make podcasts better for you!</p>

    <p>RSS is a particular standard of the coding language called XML (&#8220;extensible markup language&#8221;). And the way to <em>extend</em> XML or RSS is by adding another namespace. You're probably a little familiar with two popular namespaces already: the &#8220;iTunes&#8221; namespace Apple created and that most podcast apps use for podcast data, and also the &#8220;content&#8221; namespace from which we get the <code>&lt;content:encoded&gt;</code> tag we use for episode notes.</p>

    [The rest of the full article …]
  ]]>
</content:encoded>

In this example, <description> would be shown as a preview of the content, before playing or opening the episode. <podcast:notes> would be shown when you open/play the episode (possibly with <description> prepended unless a duplicate of the first paragraph, like Apple Podcasts used to handle it), and <content:encoded> would be used only by RSS aggregators built for reading.

But this is a perfect-world scenario where podcasters have the resources to represent their content in three ways (summary, actionable notes, and full written content).

[theDanielJLewis]

… like Apple Podcasts used to handle it

To clarify this. Apple Podcasts used to (or maybe they still do, I always forget which is my test episode) display both the description and content in the episode notes, but only if the description was not a verbatim copy of the first part of the content. If they were different, even by one punctuation (or HTML formatting), Apple would display both. I thought this was smart behavior.

I'm looking at my actual RSS feed (which is similar to the above, except <podcast:notes> contains plaintext URLs and is the <itunes:summary> tag) and how Apple Podcasts is displaying it. Apple is actually still displaying <content:encoded> for my episode notes, but truncated. I would turn off <content:encoded> for my podcast-only RSS feed from PowerPress, but that's not an option unless I switch WordPress's entire feed mode to excerpts instead of full text. I need to talk to Blubrry support with my ideas for improving PowerPress's feed.

[theDanielJLewis]

Oh, and in the above RSS example, <content:encoded> would actually be omitted from my podcast RSS feed, but visible in my site's regular RSS feed. (This is what PowerPress doesn't let me do, as far as I know.)

[barrowclift]

But this is a perfect-world scenario where podcasters have the resources to represent their content in three ways (summary, actionable notes, and full written content).

This is a good point, my feed template was created manually, so I have blinders up to the minimal control most podcasters have to work with in their CMS of choice.

Apple Podcasts used to (or maybe they still do, I always forget which is my test episode) display both the description and content in the episode notes, but only if the description was not a verbatim copy of the first part of the content. If they were different, even by one punctuation (or HTML formatting), Apple would display both. I thought this was smart behavior.

That's wild, I had no idea they were (potentially are?) compositing feed content like that.

But back to the proposal, from your feedback it sounds like the <podcast:summary> bit was ill conceived, but the <podcast:notes> has potential merit. Would you recommend I cancel this and open up a new proposal for just the <podcast:notes> tag? Or would you rather I leave this as-is? And thanks for the detailed feedback!

[theDanielJLewis]

Maybe just edit the title and your original post, or prepend an update.

But I would like to see a <podcast:notes> tag for hosting this kind of content separate from the description and full written content.

[theDanielJLewis]

But this is a perfect-world scenario where podcasters have the resources to represent their content in three ways (summary, actionable notes, and full written content).

To clarify this, I mean that some podcasters don't have the time, money, knowledge, or interest to represent their content in three different ways. I think the order of priority would be description > notes > article > transcript.

In other words, if the podcast could do only one thing, do an episode description. If two things, then description and the concise actionable notes. If three things, description, notes, and article. And if four things, description, notes, article, and transcript (in the transcript tag).

[theDanielJLewis]

No Agenda's actionable notes (which don't display in podcast apps) would be perfect for <podcast:notes>. Knick Knack News already publishes their notes in the concise, actionable format, and that's what shows in podcast apps because that's as thorough as they get (essentially two levels deep).

[barrowclift]

⚠️ Click here to read the latest proposal in the comments ⚠️

This revision remains below for historical preservation purposes only.

---

Proposal (Rev 1)

What

A new tag <podcast:notes> is suggested to expose actionable notes for a given episode, such as an outline, links, and citations. See examples such as No Agenda's episode notes and ATP's "show notes" for kind the content this tag would expose.

Why

Today, there's no great place to expose actionable notes. The <description> tag is typically used for this as a crutch, but that tag is meant for a concise synopsis or description of the episode in question, not long lists of links, citations, etc.

<content:encoded> could in theory serve this purpose, but it's more appropriately reserved to express a full-text version of the episode, such as an article or transcript. This leaves no suitable home for actionable notes.

The community would greatly benefit from having a proper means to supply this kind of content while still leaving <description> available for the episode synopsis and <content:encoded> available for a full-length equivalent article or episode transcript.

---

Parent

<item>

Count

Single

Node values

<podcast:notes> would be a free-form String with no specified character limit.

Example

<!-- Content such as this isn't well served by either <description> or <content:encoded> -->
<podcast:notes>
  <![CDATA[
    <p>The podcasting industry has grown a lot since its birth in 2004, but the core of what a podcast could be and what it could do hasn't changed much. Now, Podcasting 2.0 revolutionizes the industry with highly requested innovations that will help everyone on all sides of the RSS feeds.</p>
    <p>Please share this episode from your podcast app or https://theaudacitytopodcast.com/podcasting20</p>
    <p>## What is "Podcasting 2.0"?</p>
    <ul>
      <li><a href="https://PodcastNamespace.org">Learn more about the Podcast Namespace</a></li>
      <li><a href="https://podcastindex.org/podcast/920666">Follow the Podcasting 2.0 podcast</a></li>
    </ul>
    <p>## Podcasting 2.0 is for audiences</p>
    <p>## Podcasting 2.0 is for podcasters</p>
    <p>## Podcasting 2.0 is for developers</p>
    <p>## Podcasting 2.0 is even for advertisers</p>
    <p>## This is the new litmus test for podcasting tools</p>
    <p>If your podcast-publishing tools do not already support Podcasting 2.0, switch!</p>
    <a href="">Retweet this</a></p>
    <p>## How to upgrade your podcast experience with Podcasting 2.0</p>
    <ul>
      <li><a href="https://github.com/Lehmancreations/Podcast-Namespace-Wordpress-Plugin/releases">WordPress with PowerPress, plus the Podcast Namespace plugin</a></li>
      <li><a href="https://theaudacitytopodcast.com/blubrry">Blubrry podcast hosting</a></li>
      <li><a href="https://theaudacitytopodcast.com/buzzsprout">Buzzsprout</a></li>
      <li><a href="https://theaudacitytopodcast.com/libsyn">Libsyn</a></li>
      <li><a href="https://theaudacitytopodcast.com/captivate">Captivate</a></li>
      <li><a href="https://podcastindex.org/apps">More options</a></li>
    </ul>
    <p>## How to get involved in Podcasting 2.0</p>
    <ul>
      <li><a href="https://podcastindex.org">Main website</a></li>
      <li><a href="https://podcastindex.org/podcast/920666">Podcasting 2.0 podcast</a></li>
      <li><a href="https://podcastindex.social">Social conversations</a></li>
      <li><a href="https://github.com/Podcastindex-org">GitHub</a></li>
      <li><a href="https://github.com/Podcastindex-org/podcast-namespace">Podcast Namespace on GitHub</a></li>
    </ul>
    <p>## Accept no cheap imitations!</p>
    <hr />
    <p>Start and grow your own podcast for passion and PROFIT! Learn more and follow at https://theaudacitytopodcast.com/</p>
    <p>Know, engage, and grow your audience with the power of podcast reviews! https://mypodcastreviews.com/</p>
    <p>FEEDBACK</p>
    <p>Call (903) 231-2221<br />
    Email feedback@theaudacitytopodcast.com<br />
    Send a voice message from https://theaudacitytopodcast.com/</p>
    <p>MAILING ADDRESS</p>
    <p>The Audacity to Podcast<br />
    PO Box 739<br />
    Burlington, KY 41005</p>
  ]]>
</podcast:notes>

[barrowclift]

Maybe just edit the title and your original post, or prepend an update.

Understood 👍🏻 Title updated and original proposal updated to link to the latest proposal below (left the original proposal as-is for a paper trail/historical preservation).

[theDanielJLewis]

Bravo! I love it!

I'm now thinking this should actually go in the episode data file (#404) instead of in the RSS feed, but in a similar format and for the exact same purpose—only inserted in a different place.

Putting it in the episode data file allows podcasters to change the notes anytime without having to refresh the RSS feed. And since I think Podcasting 2.0 apps are supposed to load the episode data file whenever the episode is played, this ensures that the latest version of the notes is always shown to the audience.

[barrowclift]

I'm now thinking this should actually go in the episode data file (#404) instead of in the RSS feed, but in a similar format and for the exact same purpose—only inserted in a different place.

I think that's a great idea! Amending the proposal now with consideration to your most recent thoughts shared here...

[barrowclift]

Proposal (Rev 2)

What

A new tag <podcast:notes> is suggested to link to the external episode data file, which could additionally contain the actionable notes for a given episode, such as an outline, links, and citations. See No Agenda's episode notes and ATP's "show notes" for examples of what this tag would expose.

Why

Today, there's no great place to expose actionable notes. The <description> tag is typically used for this as a crutch, but that tag is meant for a concise synopsis or description of the episode in question, not long lists of links, citations, etc.

<content:encoded> could in theory serve this purpose, but it's more appropriately reserved to express a full-text version of the episode, such as an article or transcript. Additionally, that requires regenerating the entire RSS feed whenever any changes to the notes are required. This leaves no suitable home for actionable notes.

The community would greatly benefit from having a proper means to supply this kind of content while still leaving <description> available for the episode synopsis and <content:encoded> available for a full-length equivalent article or episode transcript.

This data will be stored in the episode data file so the notes can be changed at any time without requiring a refresh of the RSS feed. Additionally, these notes would only be fetched whenever the given episode is viewed and/or played, so clients would have a means to ensure that the latest version of the notes is always directly fetched and displayed.

---

Parent

<item>

Count

Single

Attributes

• url (required): The URL where the episode data file is located.
• type (required): Mime type of the file - JSON preferred, application/json+episode-data (exact Mime type name subject to change based on Proposal for choosing RSS vs. episode JSON #404)

The Episode File Notes Field

The notes field is an optional string property that resides at the root of the episode data file (alongside version and chapters).

Example

<podcast:notes url="https://example.com/episode1/episode-data.json" type="application/json+episode-data" />

To keep the example simple, this episode file does not contain chapters:

{
    "version": 1.3,
    "notes": "<p>The podcasting industry has grown a lot since its birth in 2004, but the core of what a podcast could be and what it could do hasn't changed much. Now, Podcasting 2.0 revolutionizes the industry with highly requested innovations that will help everyone on all sides of the RSS feeds.</p>\n    <p>Please share this episode from your podcast app or https://theaudacitytopodcast.com/podcasting20</p>\n    <p>## What is \"Podcasting 2.0\"?</p>\n    <ul>\n      <li><a href=\"https://PodcastNamespace.org\">Learn more about the Podcast Namespace</a></li>\n      <li><a href=\"https://podcastindex.org/podcast/920666\">Follow the Podcasting 2.0 podcast</a></li>\n    </ul>\n    <p>## Podcasting 2.0 is for audiences</p>\n    <p>## Podcasting 2.0 is for podcasters</p>\n    <p>## Podcasting 2.0 is for developers</p>\n    <p>## Podcasting 2.0 is even for advertisers</p>\n    <p>## This is the new litmus test for podcasting tools</p>\n    <p>If your podcast-publishing tools do not already support Podcasting 2.0, switch!</p>\n    <a href=\"\">Retweet this</a></p>\n    <p>## How to upgrade your podcast experience with Podcasting 2.0</p>\n    <ul>\n      <li><a href=\"https://github.com/Lehmancreations/Podcast-Namespace-Wordpress-Plugin/releases\">WordPress with PowerPress, plus the Podcast Namespace plugin</a></li>\n      <li><a href=\"https://theaudacitytopodcast.com/blubrry\">Blubrry podcast hosting</a></li>\n      <li><a href=\"https://theaudacitytopodcast.com/buzzsprout\">Buzzsprout</a></li>\n      <li><a href=\"https://theaudacitytopodcast.com/libsyn\">Libsyn</a></li>\n      <li><a href=\"https://theaudacitytopodcast.com/captivate\">Captivate</a></li>\n      <li><a href=\"https://podcastindex.org/apps\">More options</a></li>\n    </ul>\n    <p>## How to get involved in Podcasting 2.0</p>\n    <ul>\n      <li><a href=\"https://podcastindex.org\">Main website</a></li>\n      <li><a href=\"https://podcastindex.org/podcast/920666\">Podcasting 2.0 podcast</a></li>\n      <li><a href=\"https://podcastindex.social\">Social conversations</a></li>\n      <li><a href=\"https://github.com/Podcastindex-org\">GitHub</a></li>\n      <li><a href=\"https://github.com/Podcastindex-org/podcast-namespace\">Podcast Namespace on GitHub</a></li>\n    </ul>\n    <p>## Accept no cheap imitations!</p>\n    <hr />\n    <p>Start and grow your own podcast for passion and PROFIT! Learn more and follow at https://theaudacitytopodcast.com/</p>\n    <p>Know, engage, and grow your audience with the power of podcast reviews! https://mypodcastreviews.com/</p>\n    <p>FEEDBACK</p>\n    <p>Call (903) 231-2221<br />\n    Email feedback@theaudacitytopodcast.com<br />\n    Send a voice message from https://theaudacitytopodcast.com/</p>\n    <p>MAILING ADDRESS</p>\n    <p>The Audacity to Podcast<br />\n    PO Box 739<br />\n    Burlington, KY 41005</p>"
}