From 70c982bdad4c44e3b5dc2b0c21425f965980aad0 Mon Sep 17 00:00:00 2001 From: "Daniel J. Lewis" Date: Sat, 7 Jun 2025 02:11:11 -0400 Subject: [PATCH 1/5] Renamed tag files for consistency and URI conventions Renamed all multi-word tag docs to lower case and hyphenated to match the title of the tag and follow standard URI conventions. Updated affected internal links. No content changes. --- docs/1.0.md | 19 +++++++++---------- ...ateEnclosure.md => alternate-enclosure.md} | 0 docs/tags/chat.md | 8 ++++---- docs/tags/{contentLink.md => content-link.md} | 6 +++--- docs/tags/funding.md | 2 +- docs/tags/integrity.md | 4 ++-- docs/tags/{liveItem.md => live-item.md} | 0 docs/tags/medium.md | 6 +++--- docs/tags/podroll.md | 2 +- docs/tags/publisher.md | 2 +- docs/tags/{remoteItem.md => remote-item.md} | 2 +- .../{socialInteract.md => social-interact.md} | 0 docs/tags/source.md | 4 ++-- ...updateFrequency.md => update-frequency.md} | 0 .../{valueRecipient.md => value-recipient.md} | 0 ...{valueTimeSplit.md => value-time-split.md} | 10 +++++----- docs/tags/value.md | 2 +- 17 files changed, 33 insertions(+), 34 deletions(-) rename docs/tags/{alternateEnclosure.md => alternate-enclosure.md} (100%) rename docs/tags/{contentLink.md => content-link.md} (76%) rename docs/tags/{liveItem.md => live-item.md} (100%) rename docs/tags/{remoteItem.md => remote-item.md} (96%) rename docs/tags/{socialInteract.md => social-interact.md} (100%) rename docs/tags/{updateFrequency.md => update-frequency.md} (100%) rename docs/tags/{valueRecipient.md => value-recipient.md} (100%) rename docs/tags/{valueTimeSplit.md => value-time-split.md} (81%) diff --git a/docs/1.0.md b/docs/1.0.md index 83c2feb..d45e00b 100644 --- a/docs/1.0.md +++ b/docs/1.0.md @@ -21,7 +21,6 @@ Each tag below exists in the podcast namespace within the specified parent. All explicitly specified as optional. Anywhere the url of a hyper-text based resource is specified, it must be given as `https:` and not `http:`. - ## Table of Contents - [Transcript](tags/transcript.md) @@ -35,23 +34,23 @@ explicitly specified as optional. Anywhere the url of a hyper-text based resourc - [Episode](tags/episode.md) - [Trailer](tags/trailer.md) - [License](tags/license.md) -- [Alternate Enclosure](tags/alternateEnclosure.md) +- [Alternate Enclosure](tags/alternate-enclosure.md) - [Source](tags/source.md) - [Integrity](tags/integrity.md) - [Guid](tags/guid.md) - [Value](tags/value.md) - - [Value Recipient](tags/valueRecipient.md) + - [Value Recipient](tags/value-recipient.md) - [Medium](tags/medium.md) - [Images](tags/images.md) -- [Live Item](tags/liveItem.md) -- [Content Link](tags/contentLink.md) -- [Social Interact](tags/socialInteract.md) +- [Live Item](tags/live-item.md) +- [Content Link](tags/content-link.md) +- [Social Interact](tags/social-interact.md) - [Block](tags/block.md) - [Txt](tags/txt.md) -- [Remote Item](tags/remoteItem.md) +- [Remote Item](tags/remote-item.md) - [Podroll](tags/podroll.md) -- [Update Frequency](tags/updateFrequency.md) +- [Update Frequency](tags/update-frequency.md) - [Podping](tags/podping.md) -- [Value Time Split](tags/valueTimeSplit.md) +- [Value Time Split](tags/value-time-split.md) - [Chat](tags/chat.md) -- [Publisher](tags/publisher.md) \ No newline at end of file +- [Publisher](tags/publisher.md) diff --git a/docs/tags/alternateEnclosure.md b/docs/tags/alternate-enclosure.md similarity index 100% rename from docs/tags/alternateEnclosure.md rename to docs/tags/alternate-enclosure.md diff --git a/docs/tags/chat.md b/docs/tags/chat.md index 3bc03df..c2906b7 100644 --- a/docs/tags/chat.md +++ b/docs/tags/chat.md @@ -2,15 +2,15 @@ `` -This element allows a podcaster to attach information to either the ``, `` or [``](liveItem.md) about where the "official" chat for either the podcast or a specific episode or live event is to be found. Just like [``](socialInteract.md) functions for social media, the `` tag will function for ephemeral chat. There are many protocols in use across the internet for chat based communication. This tag is meant to be flexible enough to adapt to whichever protocol the podcaster wants to use. +This element allows a podcaster to attach information to either the ``, `` or [``](live-item.md) about where the "official" chat for either the podcast or a specific episode or live event is to be found. Just like [``](social-interact.md) functions for social media, the `` tag will function for ephemeral chat. There are many protocols in use across the internet for chat based communication. This tag is meant to be flexible enough to adapt to whichever protocol the podcaster wants to use. -This element's presence at a particular level governs how it should be treated. If found at the `` or [``](liveItem.md) level, this should be treated as the information for that specific episode, overriding what is at the `` level. If this tag is found at the `` level, it would be considered the chat for the entire podcast and is recommended to be an "always on" chat room experience. +This element's presence at a particular level governs how it should be treated. If found at the `` or [``](live-item.md) level, this should be treated as the information for that specific episode, overriding what is at the `` level. If this tag is found at the `` level, it would be considered the chat for the entire podcast and is recommended to be an "always on" chat room experience. -If a podcast has an "always on" style chat service it is recommended to link that at the `` level and do not use the `` tag at the `` or [``](liveItem.md) level. +If a podcast has an "always on" style chat service it is recommended to link that at the `` level and do not use the `` tag at the `` or [``](live-item.md) level. ### Parent -`` or `` or [``](liveItem.md) +`` or `` or [``](live-item.md) ### Count diff --git a/docs/tags/contentLink.md b/docs/tags/content-link.md similarity index 76% rename from docs/tags/contentLink.md rename to docs/tags/content-link.md index a7738c8..5b2e406 100644 --- a/docs/tags/contentLink.md +++ b/docs/tags/content-link.md @@ -4,11 +4,11 @@ The `contentLink` tag is used to indicate that the content being delivered by the parent element can be found at an external location instead of, or in addition to, the tag itself within an app. In most instances it is used as a fallback link for the user to use when the app itself can't handle a certain content delivery directly. -For instance, perhaps a podcast feed specifies a [``](liveItem.md) to deliver a live stream to apps. The feed may also give a `` pointing to YouTube and Twitch versions of the live stream as well, just in case the listener uses an app that doesn't fully support live streaming content. +For instance, perhaps a podcast feed specifies a [``](live-item.md) to deliver a live stream to apps. The feed may also give a `` pointing to YouTube and Twitch versions of the live stream as well, just in case the listener uses an app that doesn't fully support live streaming content. ### Parent -`` or [``](liveItem.md) +`` or [``](live-item.md) ### Count @@ -30,7 +30,7 @@ The node value is a free-form string meant to explain to the user where this con Watch this episode on YouTube! ``` -(under [``](liveItem.md)) +(under [``](live-item.md)) ```xml Live on YouTube! diff --git a/docs/tags/funding.md b/docs/tags/funding.md index 373c834..c92918c 100644 --- a/docs/tags/funding.md +++ b/docs/tags/funding.md @@ -6,7 +6,7 @@ This tag lists possible donation/funding links for the podcast. The content of t ### Parent -``, `` or [``](liveItem.md) +``, `` or [``](live-item.md) ### Count diff --git a/docs/tags/integrity.md b/docs/tags/integrity.md index dc1efed..0ecccd0 100644 --- a/docs/tags/integrity.md +++ b/docs/tags/integrity.md @@ -2,11 +2,11 @@ `` -This element defines a method of verifying integrity of the media given either an [SRI-compliant integrity string](https://www.w3.org/TR/SRI/) (preferred) or a base64 encoded PGP signature. This element is optional within a [``](alternateEnclosure.md) element. It allows to ensure that the file has not been tampered with. +This element defines a method of verifying integrity of the media given either an [SRI-compliant integrity string](https://www.w3.org/TR/SRI/) (preferred) or a base64 encoded PGP signature. This element is optional within a [``](alternate-enclosure.md) element. It allows to ensure that the file has not been tampered with. ### Parent -[``](alternateEnclosure.md) +[``](alternate-enclosure.md) ### Count diff --git a/docs/tags/liveItem.md b/docs/tags/live-item.md similarity index 100% rename from docs/tags/liveItem.md rename to docs/tags/live-item.md diff --git a/docs/tags/medium.md b/docs/tags/medium.md index 530b2c6..cbaf121 100644 --- a/docs/tags/medium.md +++ b/docs/tags/medium.md @@ -25,7 +25,7 @@ The node value is a string denoting one of the following possible values: - `audiobook` - Specific types of audio with one item per feed, or where items represent chapters within the book. - `newsletter` - Describes a feed of curated written articles. Newsletter articles now sometimes have an spoken version audio enclosure attached. - `blog` - Describes a feed of informally written articles. Similar to `newsletter` but more informal as in a traditional blog platform style. -- `publisher` - Describes a feed that links to other feeds a publisher owns using the [``](remoteItem.md) element. To understand the structure of how "publisher" feeds work, please see the dedicated document [here](../../publishers/publishers.md) and the [``](publisher.md) tag [here](./publisher.md). +- `publisher` - Describes a feed that links to other feeds a publisher owns using the [``](remote-item.md) element. To understand the structure of how "publisher" feeds work, please see the dedicated document [here](../../publishers/publishers.md) and the [``](publisher.md) tag [here](./publisher.md). - `course` - A feed of training material (audio or video courses) with each item being a session or chapter of the course or conference track. ### List Mediums @@ -34,9 +34,9 @@ In addition to the above mediums, each medium also has a counterpart "list" vari There is also a dedicated list medium for mixed content: -- `mixed` - This list medium type describes a feed of [``](remoteItem.md)'s that point to different remote medium types. For instance, a single list feed might point to music, podcast and audiobook items in other feeds. An example would be a personal consumption history feed. +- `mixed` - This list medium type describes a feed of [``](remote-item.md)'s that point to different remote medium types. For instance, a single list feed might point to music, podcast and audiobook items in other feeds. An example would be a personal consumption history feed. -A "list" medium feed should not be expected to have regular ``'s,[``](liveItem.md)'s, or any future similar new item type. Rather, a "List" feed is intended to exclusively contain one or more [``](remoteItem.md)'s, allowing one to reference a feed by its [``](guid.md) and the guid of an item. +A "list" medium feed should not be expected to have regular ``'s,[``](live-item.md)'s, or any future similar new item type. Rather, a "List" feed is intended to exclusively contain one or more [``](remote-item.md)'s, allowing one to reference a feed by its [``](guid.md) and the guid of an item. ### Examples diff --git a/docs/tags/podroll.md b/docs/tags/podroll.md index 24f3cc7..f150d32 100644 --- a/docs/tags/podroll.md +++ b/docs/tags/podroll.md @@ -14,7 +14,7 @@ Single ### Node value -The node value must be one or more [``](remoteItem.md) elements. +The node value must be one or more [``](remote-item.md) elements. ### Example diff --git a/docs/tags/publisher.md b/docs/tags/publisher.md index 3457b55..667a02f 100644 --- a/docs/tags/publisher.md +++ b/docs/tags/publisher.md @@ -2,7 +2,7 @@ `` -This element allows a podcast feed to link to it's "publisher feed" parent. This is useful when a parent publishing entity wants to attest ownership over all of the podcast feeds it owns/publishes. This element must contain exactly one `` element pointing to the publisher feed. For widest compatibility, it is highly recommended to use the `feedUrl` attribute of the [``](remoteItem.md) element in this capacity. +This element allows a podcast feed to link to it's "publisher feed" parent. This is useful when a parent publishing entity wants to attest ownership over all of the podcast feeds it owns/publishes. This element must contain exactly one `` element pointing to the publisher feed. For widest compatibility, it is highly recommended to use the `feedUrl` attribute of the [``](remote-item.md) element in this capacity. For complete implementation details regarding publisher feeds and how to create them, please see the full publisher feed [documentation](../../publishers/publishers.md) and the `publisher` medium [here](./medium.md#medium). diff --git a/docs/tags/remoteItem.md b/docs/tags/remote-item.md similarity index 96% rename from docs/tags/remoteItem.md rename to docs/tags/remote-item.md index a1e1b24..418a51c 100644 --- a/docs/tags/remoteItem.md +++ b/docs/tags/remote-item.md @@ -8,7 +8,7 @@ Using the `feedGuid` attribute is the preferred way to address a remote feed sin ### Parent -`` or [``](podroll.md) or [``](valueTimeSplit.md) or [``](publisher.md) +`` or [``](podroll.md) or [``](value-time-split.md) or [``](publisher.md) ### Count diff --git a/docs/tags/socialInteract.md b/docs/tags/social-interact.md similarity index 100% rename from docs/tags/socialInteract.md rename to docs/tags/social-interact.md diff --git a/docs/tags/source.md b/docs/tags/source.md index 6e7dc61..9a4cff4 100644 --- a/docs/tags/source.md +++ b/docs/tags/source.md @@ -2,11 +2,11 @@ `` -This element defines a uri location for a [``](alternateEnclosure.md) media file. It is meant to be used as a child of the [``](alternateEnclosure.md) element. At least one `` element must be present within every [``](alternateEnclosure.md) element. +This element defines a uri location for a [``](alternate-enclosure.md) media file. It is meant to be used as a child of the [``](alternate-enclosure.md) element. At least one `` element must be present within every [``](alternate-enclosure.md) element. ### Parent -[``](alternateEnclosure.md) +[``](alternate-enclosure.md) ### Count diff --git a/docs/tags/updateFrequency.md b/docs/tags/update-frequency.md similarity index 100% rename from docs/tags/updateFrequency.md rename to docs/tags/update-frequency.md diff --git a/docs/tags/valueRecipient.md b/docs/tags/value-recipient.md similarity index 100% rename from docs/tags/valueRecipient.md rename to docs/tags/value-recipient.md diff --git a/docs/tags/valueTimeSplit.md b/docs/tags/value-time-split.md similarity index 81% rename from docs/tags/valueTimeSplit.md rename to docs/tags/value-time-split.md index 95dd296..8b2f3b6 100644 --- a/docs/tags/valueTimeSplit.md +++ b/docs/tags/value-time-split.md @@ -2,15 +2,15 @@ `` -This element allows different value splits for a certain period of time. It is a combination of the concept of [``](soundbite.md) and [``](remoteItem.md) where a start time and a duration is supplied with alternative value recipients. The alternative value recipients are not required to be remote, as the recipients may not have an RSS feed/item of their own to reference. +This element allows different value splits for a certain period of time. It is a combination of the concept of [``](soundbite.md) and [``](remote-item.md) where a start time and a duration is supplied with alternative value recipients. The alternative value recipients are not required to be remote, as the recipients may not have an RSS feed/item of their own to reference. The `` element allows time-based changes of value recipient information during playback of a feed's enclosure content. -This can either contain one or more [``](valueRecipient.md) tags _or_ exactly one [``](remoteItem.md) tag. If a [``](remoteItem.md) tag is present, the `remotePercentage` attribute can be defined to control how much the remote value block's [``](valueRecipient.md) tags will receive as a whole on top of the default, non-fee [``](valueRecipient.md) tags. +This can either contain one or more [``](value-recipient.md) tags _or_ exactly one [``](remote-item.md) tag. If a [``](remote-item.md) tag is present, the `remotePercentage` attribute can be defined to control how much the remote value block's [``](value-recipient.md) tags will receive as a whole on top of the default, non-fee [``](value-recipient.md) tags. If the remote value block contains any `` tags, they should be ignored even if the `remoteStartTime` indicates it's in a position that would invoke them. When referencing a remote value block, only the root level block splits should be used and any `` children are to be ignored. -Fees from the default [``](valueRecipient.md) tags should remain to be calculated before anything is taken out from ``. +Fees from the default [``](value-recipient.md) tags should remain to be calculated before anything is taken out from ``. ### Parent @@ -22,14 +22,14 @@ Multiple ### Node Value -A single [``](remoteItem.md) element OR one or more [``](valueRecipient.md) elements. +A single [``](remote-item.md) element OR one or more [``](value-recipient.md) elements. ### Attributes - `startTime` (required) - The time, in seconds, to stop using the currently active value recipient information and start using the value recipient information contained in this element. - `duration` (required) - How many seconds the playback app should use this element's value recipient information before switching back to the value recipient information of the parent feed. - `remoteStartTime` (optional) - The time in the remote item where the value split begins. Allows the timestamp to be set correctly in value metadata. If not defined, defaults to 0. -- `remotePercentage` (optional) - The percentage of the payment the remote recipients will receive if a [``](remoteItem.md) is present. If not defined, defaults to 100. If the value is less than 0, 0 is assumed. If the value is greater than 100, 100 is assumed. +- `remotePercentage` (optional) - The percentage of the payment the remote recipients will receive if a [``](remote-item.md) is present. If not defined, defaults to 100. If the value is less than 0, 0 is assumed. If the value is greater than 100, 100 is assumed. ### Example (Remote Item) diff --git a/docs/tags/value.md b/docs/tags/value.md index 0c879c9..32ad2cd 100644 --- a/docs/tags/value.md +++ b/docs/tags/value.md @@ -18,7 +18,7 @@ Multiple ### Node Value -The node value must be one or more [``](valueRecipient.md) elements. +The node value must be one or more [``](value-recipient.md) elements. ### Attributes From 352fba557408c3eb0a01113b54dee745e09e472a Mon Sep 17 00:00:00 2001 From: "Daniel J. Lewis" Date: Sat, 7 Jun 2025 02:36:37 -0400 Subject: [PATCH 2/5] Fixed bad markdown --- docs/other-recommendations.md | 26 +++++++------------------- 1 file changed, 7 insertions(+), 19 deletions(-) diff --git a/docs/other-recommendations.md b/docs/other-recommendations.md index 3385bdc..902cbb1 100644 --- a/docs/other-recommendations.md +++ b/docs/other-recommendations.md @@ -6,54 +6,45 @@ While the wholistic RSS namespace for podcasting is meant to synthesize the frag For all new episodes, we recommended to use -* either a permanent URI, e.g. `https://example.com/ep0003` -* or a [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) e.g. `7c029615-a810-5214-9342-eee73f58435d` - -The GUID of an episode should never change, even if a new version of the episode is being published, otherwise this episode will be duplicated downstream. +- either a permanent URI, e.g. `https://example.com/ep0003` +- or a [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) e.g. `7c029615-a810-5214-9342-eee73f58435d` +The GUID of an episode should never change, even if a new version of the episode is being published, otherwise this episode will be duplicated downstream. Consumers of podcast feeds should fall back to the enclosure URL or the namespaced UUIDv5 (SHA1 Hash with ns:URL) of the enclosure URL, if the value is not set – see https://github.com/Podcastindex-org/podcast-namespace/issues/186#issuecomment-932742468 for more details. - - #### Examples Only one entry per `` is valid: + ```xml https://example.com/ep0003 7c029615-a810-5214-9342-eee73f58435d ``` + (`isPermaLink` is optional, its default value is true –) -

- - ## Episode Description and Summary If you use ``, it should be an actual summary of the episode, in one or two sentences, and not a copy of the description. Be aware that Apple dropped `` from [their spec](https://help.apple.com/itc/podcasts_connect/#/itcb54353390) but many other clients still support it. The [original RSS specification](https://cyber.harvard.edu/rss/rss.html#hrelementsOfLtitemgt) defined `description` as follows: + > A channel may contain any number of ``s. An item may represent a "story" -- much like a story in a newspaper or magazine; if so its description is a synopsis of the story, and the link points to the full story. An item may also be complete in itself, if so, the description contains the text (entity-encoded HTML is allowed; see examples) … There also exists `` for dedicated HTML episode notes [[rssboard.org]](https://www.rssboard.org/rss-profile#namespace-elements-content-encoded), but more and more publishers switch to only having ``. When your description contains HTML, we recommend to wrap it into ``. See https://podnews.net/article/html-episode-notes-in-podcast-rss and https://podnews.net/article/how-podcast-show-notes-display for more information about supported HTML tags in different clients. Typical are `

`, `
`, ` `, `

    ` and `
  • `. - - -

    - ## Feed Paging and Archiving (RFC5005) To be able to put more metadata into RSS feeds, while keeping the full archive of all old episodes becomes a challange for some podcasters and podcast clients. A typical workaround in the industry is to only render the full metadata of the newest episodes, where there is already a proper solution since 2007: [RFC5005](https://tools.ietf.org/html/rfc5005) There are already a few players implementing RFC5005 for a while, but . Adoption from clients is sporadic. A new/different standard wouldn't help though because I'd say RFC5005 does all that's required. We need to be louder about the existence of the standard and ask for it's implementation from all sides. - - #### Examples -Excerpt from https://feeds.metaebene.me/freakshow/mp3 feed page 2, +Excerpt from https://feeds.metaebene.me/freakshow/mp3 feed page 2, parent ``: ```xml @@ -63,9 +54,6 @@ parent ``: ``` - - ## WebSub and Podping.cloud TBD - From 3e8c96a695dca831cf3d6df3ed2f8d59a76c216a Mon Sep 17 00:00:00 2001 From: "Daniel J. Lewis" Date: Fri, 13 Jun 2025 16:42:47 -0400 Subject: [PATCH 3/5] Reorganized example documents and files --- {chapters => docs/examples/chapters}/example.json | 0 {chapters => docs/examples/chapters}/exampleComplex.json | 0 {chapters => docs/examples/chapters}/jsonChapters.md | 0 {license => docs/examples/license}/license.md | 0 {license => docs/examples/license}/licenses.json | 0 {license => docs/examples/license}/licenseslugs.txt | 0 {license => docs/examples/license}/v4v-4.0.md | 0 {location => docs/examples/location}/location.md | 0 {publishers => docs/examples/publishers}/publishers.md | 0 {transcripts => docs/examples/transcripts}/example.html | 0 {transcripts => docs/examples/transcripts}/example.json | 0 {transcripts => docs/examples/transcripts}/example.srt | 0 {transcripts => docs/examples/transcripts}/example.vtt | 0 {transcripts => docs/examples/transcripts}/transcripts.md | 0 {value => docs/examples/value}/blip-0010.md | 0 {value => docs/examples/value}/lnaddress.md | 0 {value => docs/examples/value}/value.md | 0 {value => docs/examples/value}/valueslugs.txt | 0 18 files changed, 0 insertions(+), 0 deletions(-) rename {chapters => docs/examples/chapters}/example.json (100%) rename {chapters => docs/examples/chapters}/exampleComplex.json (100%) rename {chapters => docs/examples/chapters}/jsonChapters.md (100%) rename {license => docs/examples/license}/license.md (100%) rename {license => docs/examples/license}/licenses.json (100%) rename {license => docs/examples/license}/licenseslugs.txt (100%) rename {license => docs/examples/license}/v4v-4.0.md (100%) rename {location => docs/examples/location}/location.md (100%) rename {publishers => docs/examples/publishers}/publishers.md (100%) rename {transcripts => docs/examples/transcripts}/example.html (100%) rename {transcripts => docs/examples/transcripts}/example.json (100%) rename {transcripts => docs/examples/transcripts}/example.srt (100%) rename {transcripts => docs/examples/transcripts}/example.vtt (100%) rename {transcripts => docs/examples/transcripts}/transcripts.md (100%) rename {value => docs/examples/value}/blip-0010.md (100%) rename {value => docs/examples/value}/lnaddress.md (100%) rename {value => docs/examples/value}/value.md (100%) rename {value => docs/examples/value}/valueslugs.txt (100%) diff --git a/chapters/example.json b/docs/examples/chapters/example.json similarity index 100% rename from chapters/example.json rename to docs/examples/chapters/example.json diff --git a/chapters/exampleComplex.json b/docs/examples/chapters/exampleComplex.json similarity index 100% rename from chapters/exampleComplex.json rename to docs/examples/chapters/exampleComplex.json diff --git a/chapters/jsonChapters.md b/docs/examples/chapters/jsonChapters.md similarity index 100% rename from chapters/jsonChapters.md rename to docs/examples/chapters/jsonChapters.md diff --git a/license/license.md b/docs/examples/license/license.md similarity index 100% rename from license/license.md rename to docs/examples/license/license.md diff --git a/license/licenses.json b/docs/examples/license/licenses.json similarity index 100% rename from license/licenses.json rename to docs/examples/license/licenses.json diff --git a/license/licenseslugs.txt b/docs/examples/license/licenseslugs.txt similarity index 100% rename from license/licenseslugs.txt rename to docs/examples/license/licenseslugs.txt diff --git a/license/v4v-4.0.md b/docs/examples/license/v4v-4.0.md similarity index 100% rename from license/v4v-4.0.md rename to docs/examples/license/v4v-4.0.md diff --git a/location/location.md b/docs/examples/location/location.md similarity index 100% rename from location/location.md rename to docs/examples/location/location.md diff --git a/publishers/publishers.md b/docs/examples/publishers/publishers.md similarity index 100% rename from publishers/publishers.md rename to docs/examples/publishers/publishers.md diff --git a/transcripts/example.html b/docs/examples/transcripts/example.html similarity index 100% rename from transcripts/example.html rename to docs/examples/transcripts/example.html diff --git a/transcripts/example.json b/docs/examples/transcripts/example.json similarity index 100% rename from transcripts/example.json rename to docs/examples/transcripts/example.json diff --git a/transcripts/example.srt b/docs/examples/transcripts/example.srt similarity index 100% rename from transcripts/example.srt rename to docs/examples/transcripts/example.srt diff --git a/transcripts/example.vtt b/docs/examples/transcripts/example.vtt similarity index 100% rename from transcripts/example.vtt rename to docs/examples/transcripts/example.vtt diff --git a/transcripts/transcripts.md b/docs/examples/transcripts/transcripts.md similarity index 100% rename from transcripts/transcripts.md rename to docs/examples/transcripts/transcripts.md diff --git a/value/blip-0010.md b/docs/examples/value/blip-0010.md similarity index 100% rename from value/blip-0010.md rename to docs/examples/value/blip-0010.md diff --git a/value/lnaddress.md b/docs/examples/value/lnaddress.md similarity index 100% rename from value/lnaddress.md rename to docs/examples/value/lnaddress.md diff --git a/value/value.md b/docs/examples/value/value.md similarity index 100% rename from value/value.md rename to docs/examples/value/value.md diff --git a/value/valueslugs.txt b/docs/examples/value/valueslugs.txt similarity index 100% rename from value/valueslugs.txt rename to docs/examples/value/valueslugs.txt From 00c5af1cb990d8c08f021dfd3dbb763b73e5b21a Mon Sep 17 00:00:00 2001 From: "Daniel J. Lewis" Date: Fri, 13 Jun 2025 17:07:38 -0400 Subject: [PATCH 4/5] Updated internal links --- docs/examples/chapters/jsonChapters.md | 259 +++++++++++------------ docs/examples/license/license.md | 29 +-- docs/examples/publishers/publishers.md | 49 ++--- docs/examples/transcripts/transcripts.md | 43 ++-- docs/examples/value/blip-0010.md | 87 +++----- docs/examples/value/value.md | 90 ++------ docs/tags/chapters.md | 2 +- docs/tags/chat.md | 2 +- docs/tags/license.md | 4 +- docs/tags/location.md | 23 +- docs/tags/medium.md | 2 +- docs/tags/publisher.md | 2 +- docs/tags/social-interact.md | 2 +- docs/tags/transcript.md | 2 +- docs/tags/value-recipient.md | 2 +- docs/tags/value.md | 2 +- podcasting2.0.md | 95 ++++----- 17 files changed, 306 insertions(+), 389 deletions(-) diff --git a/docs/examples/chapters/jsonChapters.md b/docs/examples/chapters/jsonChapters.md index d00ddc4..b5365d4 100644 --- a/docs/examples/chapters/jsonChapters.md +++ b/docs/examples/chapters/jsonChapters.md @@ -1,34 +1,29 @@ ## JSON Chapters Format + Version 1.2 - Updated on 2021.04.15 -

    - This is the initial spec for a json chapters format that can be referenced in an RSS feed using the `` tag of -the "podcast" namespace. This file can reside on any publicly accessible url. See the podcast namespace documentation for +the "podcast" namespace. This file can reside on any publicly accessible url. See the podcast namespace documentation for details on the format of the tag. -This type of file should be served with a Content-type of 'application/json+chapters'. Chapter order is assumed to be +This type of file should be served with a Content-type of 'application/json+chapters'. Chapter order is assumed to be in ascending order based on the `startTime`. -
    - ## "Chapters" Object The chapters object is a simple JSON object with only 2 required properties: - - `version` (required - string) The version number of the format being used - - `chapters` (required - array) An array of chapter objects defined below +- `version` (required - string) The version number of the format being used +- `chapters` (required - array) An array of chapter objects defined below #### Optional Attributes: - - `author` (optional - string) The name of the author of this podcast episode. - - `title` (optional - string) The title of this podcast episode. - - `podcastName` (optional - string) The name of the podcast this episode belongs to. - - `description` (optional - string) A description of this episode. - - `fileName` (optional - string) The name of the audio file these chapters apply to. - - `waypoints` (optional - boolean) If this property is present, the locations in a chapter object should be displayed with a route between locations. - -
    +- `author` (optional - string) The name of the author of this podcast episode. +- `title` (optional - string) The title of this podcast episode. +- `podcastName` (optional - string) The name of the podcast this episode belongs to. +- `description` (optional - string) A description of this episode. +- `fileName` (optional - string) The name of the audio file these chapters apply to. +- `waypoints` (optional - boolean) If this property is present, the locations in a chapter object should be displayed with a route between locations. ## The "Chapter" Object @@ -36,27 +31,23 @@ The "chapter" object takes this basic form: ```json { - "startTime": 94, - "title": "Donation Segment" + "startTime": 94, + "title": "Donation Segment" } ``` There is only one required attribute: - - `startTime` (required - float) The starting time of the chapter, expressed in seconds with float precision for fractions of a second. - -
    +- `startTime` (required - float) The starting time of the chapter, expressed in seconds with float precision for fractions of a second. #### Optional Attributes: - - `title` (optional - string) The title of this chapter. - - `img` (optional - string) The url of an image to use as chapter art. - - `url` (optional - string) The url of a web page or supporting document that's related to the topic of this chapter. - - `toc` (optional - boolean) If this property is present and set to false, this chapter should not display visibly to the user in either the table of contents or as a jump-to point in the user interface. It should be considered a "silent" chapter marker for the purpose of meta-data only. If this property is set to `true` or not present at all, this should be considered a normal chapter for display to the user. The name "toc" is short for "table of contents". - - `endTime` (optional - float) The end time of the chapter, expressed in seconds with float precision for fractions of a second. - - `location` (optional - object) This object defines an optional location that is tied to this chapter. It follows the structure of the [location](https://github.com/Podcastindex-org/podcast-namespace/blob/main/location/location.md) tag in the XML namespace. - -
    +- `title` (optional - string) The title of this chapter. +- `img` (optional - string) The url of an image to use as chapter art. +- `url` (optional - string) The url of a web page or supporting document that's related to the topic of this chapter. +- `toc` (optional - boolean) If this property is present and set to false, this chapter should not display visibly to the user in either the table of contents or as a jump-to point in the user interface. It should be considered a "silent" chapter marker for the purpose of meta-data only. If this property is set to `true` or not present at all, this should be considered a normal chapter for display to the user. The name "toc" is short for "table of contents". +- `endTime` (optional - float) The end time of the chapter, expressed in seconds with float precision for fractions of a second. +- `location` (optional - object) This object defines an optional location that is tied to this chapter. It follows the structure of the [location](https://github.com/Podcastindex-org/podcast-namespace/blob/main/location/location.md) tag in the XML namespace. ## The Location Object: @@ -64,24 +55,22 @@ The "location" object takes this basic form: ```json { - "name": "Eiffel Tower, Paris", - "geo": "geo:48.858093,2.294694" + "name": "Eiffel Tower, Paris", + "geo": "geo:48.858093,2.294694" } ``` -It is intended to provide for rich location-based experiences tied to a point of time within a podcast episode, or other feed based media. For example, a "walking tour" may include latitude and longitude waypoints along side the image within chapters markers as someone listens to the tour podcast. This -would allow apps to show a map with markers within the UI as the tour progresses. Or, perhaps a "History of the Middle East" podcast might expose a map to highlight where certain landmarks are when being discussed. +It is intended to provide for rich location-based experiences tied to a point of time within a podcast episode, or other feed based media. For example, a "walking tour" may include latitude and longitude waypoints along side the image within chapters markers as someone listens to the tour podcast. This +would allow apps to show a map with markers within the UI as the tour progresses. Or, perhaps a "History of the Middle East" podcast might expose a map to highlight where certain landmarks are when being discussed. There are two required attributes: - - `name` (required - string) A human readable place name. - - `geo` (required - string) A simple latitude,longitude given in geoURI format, conformant to [RFC 5870](https://tools.ietf.org/html/rfc5870). +- `name` (required - string) A human readable place name. +- `geo` (required - string) A simple latitude,longitude given in geoURI format, conformant to [RFC 5870](https://tools.ietf.org/html/rfc5870). #### Optional Attributes: - - `osm` (optional - string) An OpenStreetMaps query string. Please see the [location](https://github.com/Podcastindex-org/podcast-namespace/blob/main/location/location.md) XML tag specification for full details. - -
    +- `osm` (optional - string) An OpenStreetMaps query string. Please see the [location](../../tags/location.md) XML tag specification for full details. ## Basic example @@ -89,122 +78,116 @@ Here is what a very basic chapters file may look like: ```json { - "version": "1.2.0", - "chapters": - [ - { - "startTime": 0, - "title": "Intro" - }, - { - "startTime": 168, - "title": "Hearing Aids", - "img": "https://example.com/images/hearing_aids.jpg" - }, - { - "startTime": 260, - "title": "Progress Report" - }, - { - "startTime": 410, - "title": "Namespace", - "img": "https://example.com/images/namepsace_example.jpg", - "url": "https://github.com/Podcastindex-org/podcast-namespace" - }, - { - "startTime": 3990, - "title": "Just Break Up", - "img": "https://example.com/images/justbreakuppod.png" - }, - { - "startTime": 5510, - "title": "The Big Players" - }, - { - "startTime": 5854, - "title": "Spread the Word" - }, - { - "startTime": 6089, - "title": "Outro" - } - ] + "version": "1.2.0", + "chapters": [ + { + "startTime": 0, + "title": "Intro" + }, + { + "startTime": 168, + "title": "Hearing Aids", + "img": "https://example.com/images/hearing_aids.jpg" + }, + { + "startTime": 260, + "title": "Progress Report" + }, + { + "startTime": 410, + "title": "Namespace", + "img": "https://example.com/images/namepsace_example.jpg", + "url": "https://github.com/Podcastindex-org/podcast-namespace" + }, + { + "startTime": 3990, + "title": "Just Break Up", + "img": "https://example.com/images/justbreakuppod.png" + }, + { + "startTime": 5510, + "title": "The Big Players" + }, + { + "startTime": 5854, + "title": "Spread the Word" + }, + { + "startTime": 6089, + "title": "Outro" + } + ] } ``` In this simple form, the chapter objects are treated as sequential just based on their index as a function of being -ordered in ascending fashion based on their `startTime`. In a very simple example such as this nothing is present except the `startTime`, +ordered in ascending fashion based on their `startTime`. In a very simple example such as this nothing is present except the `startTime`, `title`, and a few bits of optional meta-data. -

    - ## More complex example In this more robust example, we can bring in more meta-data about the podcast episode, and provide a way for this file to exist more easily in a web -context for something like an embedded HTML5 player on a website. Also there is an example of a "silent" chapter that has no presence in the visible +context for something like an embedded HTML5 player on a website. Also there is an example of a "silent" chapter that has no presence in the visible chapter list, but allows for different artwork to be shown: ```json { - "version": "1.2.0", - "author": "John Doe", - "title": "Episode 7 - Making Progress", - "podcastName": "John's Awesome Podcast", - "chapters": - [ - { - "startTime": 0, - "title": "Intro" - }, - { - "startTime": 168, - "title": "Hearing Aids" - }, - { - "startTime": 260, - "title": "Progress Report" - }, - { - "startTime": 410, - "title": "Namespace", - "img": "https://example.com/images/namepsace_example.jpg", - "url": "https://github.com/Podcastindex-org/podcast-namespace" - }, - { - "startTime": 3990, - "title": "Just Break Up", - "img": "https://example.com/images/justbreakuppod.png", - "url": "https://twitter.com/justbreakuppod" - }, - { - "startTime": 4826, - "img": "https://example.com/images/parisfrance.jpg", - "toc": false, - "location": { - "name": "Eiffel Tower, Paris", - "geo": "geo:42.3417649,-70.9661596" - } - }, - { - "startTime": 5510, - "title": "The Big Players" - }, - { - "startTime": 5854, - "title": "Spread the Word" - }, - { - "startTime": 6089, - "title": "Outro" - } - ] + "version": "1.2.0", + "author": "John Doe", + "title": "Episode 7 - Making Progress", + "podcastName": "John's Awesome Podcast", + "chapters": [ + { + "startTime": 0, + "title": "Intro" + }, + { + "startTime": 168, + "title": "Hearing Aids" + }, + { + "startTime": 260, + "title": "Progress Report" + }, + { + "startTime": 410, + "title": "Namespace", + "img": "https://example.com/images/namepsace_example.jpg", + "url": "https://github.com/Podcastindex-org/podcast-namespace" + }, + { + "startTime": 3990, + "title": "Just Break Up", + "img": "https://example.com/images/justbreakuppod.png", + "url": "https://twitter.com/justbreakuppod" + }, + { + "startTime": 4826, + "img": "https://example.com/images/parisfrance.jpg", + "toc": false, + "location": { + "name": "Eiffel Tower, Paris", + "geo": "geo:42.3417649,-70.9661596" + } + }, + { + "startTime": 5510, + "title": "The Big Players" + }, + { + "startTime": 5854, + "title": "Spread the Word" + }, + { + "startTime": 6089, + "title": "Outro" + } + ] } ``` -

    - ## Note about privacy -Clearly, when pulling in web based data there is the chance that this functionality could be used for tracking. As a safeguard against that, apps -using chapters are encouraged to prompt the user to acknowledge whether they trust the podcast in question before displaying the content. Trusted +Clearly, when pulling in web based data there is the chance that this functionality could be used for tracking. As a safeguard against that, apps +using chapters are encouraged to prompt the user to acknowledge whether they trust the podcast in question before displaying the content. Trusted podcasts can then be remembered for the future. diff --git a/docs/examples/license/license.md b/docs/examples/license/license.md index d8b5abb..d7f2d4d 100644 --- a/docs/examples/license/license.md +++ b/docs/examples/license/license.md @@ -31,22 +31,23 @@ This matter is very complex so this specification only intends to scratch its su ## Specification -- **\[License Slug from [License List](/license/licenseslugs.txt) or Custom Liense name]** +- **\[License Slug from [License List](licenseslugs.txt) or Custom Liense name]** - Channel (optional | single) + Channel (optional | single) - Item (optional | single) + Item (optional | single) - This element allows a podcaster to specify a license for a podcast or an episode. + This element allows a podcaster to specify a license for a podcast or an episode. - - `url` (required): This is the url to the license file. + - `url` (required): This is the url to the license file. - Examples: - - `(CC BY-ND 4.0)` - - `(CC BY-NC-ND 4.0)` - - `© My Company 2021 - All Rights Reserved` - - - Discussion here: - - (https://github.com/Podcastindex-org/podcast-namespace/issues/177) - - (https://podcastindex.social/web/statuses/105839486748529374) \ No newline at end of file + Examples: + + - `(CC BY-ND 4.0)` + - `(CC BY-NC-ND 4.0)` + - `© My Company 2021 - All Rights Reserved` + + Discussion here: + + - (https://github.com/Podcastindex-org/podcast-namespace/issues/177) + - (https://podcastindex.social/web/statuses/105839486748529374) diff --git a/docs/examples/publishers/publishers.md b/docs/examples/publishers/publishers.md index afa10bd..7c9bd46 100644 --- a/docs/examples/publishers/publishers.md +++ b/docs/examples/publishers/publishers.md @@ -1,30 +1,31 @@ # The Publisher Medium + v1.0 - April 5, 2024
    -Below, you will find implementation details about using the `publisher` value in the [``](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#medium) tag to +Below, you will find implementation details about using the `publisher` value in the [``](../../tags/medium.md) tag to create "publisher feeds".
    ## Overview -The idea of a "publisher" is that a single entity (person, organization, record label, etc) might be the responsible -party which produces multiple podcast feeds. In such a case it would be useful to be able to see all of a -publisher's podcasts collected in a single place. For instance, a news organization might produce 12 different -podcast feeds. Or, a music artist might produce 3 albums of music using the `` tag of `music`. In -those cases, having a high level feed that references these other feeds would make it easier for podcast apps to +The idea of a "publisher" is that a single entity (person, organization, record label, etc) might be the responsible +party which produces multiple podcast feeds. In such a case it would be useful to be able to see all of a +publisher's podcasts collected in a single place. For instance, a news organization might produce 12 different +podcast feeds. Or, a music artist might produce 3 albums of music using the `` tag of `music`. In +those cases, having a high level feed that references these other feeds would make it easier for podcast apps to associate those feeds with a particular publishing entity. -Likewise, it is helpful if the produced feeds link back to the "publisher feed" so that podcast apps can walk back -up the chain from a podcast feed to it's publisher in order to find other relevant content from that publishing -entity. For instance, a listener may subscribe to a music album by an artist and want to find their other +Likewise, it is helpful if the produced feeds link back to the "publisher feed" so that podcast apps can walk back +up the chain from a podcast feed to it's publisher in order to find other relevant content from that publishing +entity. For instance, a listener may subscribe to a music album by an artist and want to find their other albums and singles. -When a publisher feed links to it's "child" feeds, and those "child" feeds link back to their "parent" publisher -feeds, this provides a two-way validation that a feed is indeed a valid part of a publishing entities portfolio of -content. If a feed links to a publisher feed without the publisher feed referencing it, that association should be +When a publisher feed links to it's "child" feeds, and those "child" feeds link back to their "parent" publisher +feeds, this provides a two-way validation that a feed is indeed a valid part of a publishing entities portfolio of +content. If a feed links to a publisher feed without the publisher feed referencing it, that association should be discarded.
    @@ -33,14 +34,14 @@ discarded. A publisher feed must have the following parts in it's ``: -1. A [``](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#medium) tag with a value of `publisher`. -2. A valid [``](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid). -3. One or more [``](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#remoteItem) tags that link to podcast feeds. +1. A [``](../../tags/medium.md) tag with a value of `publisher`. +2. A valid [``](../../tags/guid.md). +3. One or more [``](../../tags/remote-item.md) tags that link to podcast feeds. ### Example The following example shows a publisher feed that links to all of the feeds published by the "AgileSet Media" entity. -This feed also makes use of the [``](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#person) tag to define a responsible person at the +This feed also makes use of the [``](../../tags/person.md) tag to define a responsible person at the publishing entity. ```xml @@ -70,16 +71,16 @@ publishing entity. ## Linking to Publisher Feeds -While not strictly required, adding a reference to the publisher feed from the "child" feeds is a good idea, as it -makes discovery of your other content much easier. Podcast apps can see this linkage and "walk back up the chain" -to your publisher feed and then recommend your other podcast content to a listener. To do this, you will need to -add a `` tag in the `` of the "child" feed that will contain a `` link to -the +While not strictly required, adding a reference to the publisher feed from the "child" feeds is a good idea, as it +makes discovery of your other content much easier. Podcast apps can see this linkage and "walk back up the chain" +to your publisher feed and then recommend your other podcast content to a listener. To do this, you will need to +add a `` tag in the `` of the "child" feed that will contain a `` link to +the publisher feed. ### Example -The following example snippet shows a podcast feed produced by "AgileSet Media" that links to the publisher feed +The following example snippet shows a podcast feed produced by "AgileSet Media" that links to the publisher feed example above. ```xml @@ -93,7 +94,7 @@ example above. 469b403f-db2d-574c-9db9-96dbb3f6561c podcast - + <![CDATA[Runnin']]> @@ -102,4 +103,4 @@ example above. -``` \ No newline at end of file +``` diff --git a/docs/examples/transcripts/transcripts.md b/docs/examples/transcripts/transcripts.md index 9ed9ad2..2488e39 100644 --- a/docs/examples/transcripts/transcripts.md +++ b/docs/examples/transcripts/transcripts.md @@ -2,13 +2,13 @@ This is the initial spec for the podcast transcript format. There are four possible formats detailed below. -Some transcript implementations are done in-browser. [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) -are required to make these files available from other websites. [A CORS tester is available here](https://cors-test.codehappy.dev/), +Some transcript implementations are done in-browser. [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) +are required to make these files available from other websites. [A CORS tester is available here](https://cors-test.codehappy.dev/), to ensure that transcripts are available within browser-based players. -* **Want to support only one format?** WebVTT is used by Apple Podcasts for ingest, and also natively supported by web browsers. Because the WebVTT format is the most flexible, it's an ideal choice if you can only support one format. +- **Want to support only one format?** WebVTT is used by Apple Podcasts for ingest, and also natively supported by web browsers. Because the WebVTT format is the most flexible, it's an ideal choice if you can only support one format. -The examples given below are just for convenience. In production you should ensure you are conforming to the actual spec for each format as defined in its own documentation. +The examples given below are just for convenience. In production you should ensure you are conforming to the actual spec for each format as defined in its own documentation. ## WebVTT @@ -21,7 +21,8 @@ While there is no defined maximum line-length, to ensure that displaying WebVTT The full specification includes formatting features; these are typically not used in podcasting applications. #### Snippet: -``` + +```vtt WEBVTT 00:00:00.000 --> 00:00:05.000 @@ -46,13 +47,13 @@ And the enhanced monetization options are a game-changer. Couldn't agree more, Tom. The future looks bright. ``` -Example file: [example.vtt](example.vtt) +Example file: [example.vtt](example.vtt) #### Web browser support example This example code will add an audio player on a web page, and display the accompanying WebVTT file as the audio plays. (Note that this basic code will not show speaker names). -``` +```html