kopia lustrzana https://github.com/Podcastindex-org/podcast-namespace
formatting cleanup done
daveajones
rodzic
05bb604306
commit
225d177a4b
188
docs/1.0.md
188
docs/1.0.md
|
|
@ -1033,9 +1033,12 @@ A complete example:
|
|||
https://example.com/images/live/pci_avatar-small.jpg 300w,
|
||||
https://example.com/images/live/pci_avatar-tiny.jpg 150w"
|
||||
/>
|
||||
<podcast:person href="https://www.podchaser.com/creators/adam-curry-107ZzmWE5f" img="https://example.com/images/adamcurry.jpg">Adam Curry</podcast:person>
|
||||
<podcast:person role="guest" href="https://github.com/daveajones/" img="https://example.com/images/davejones.jpg">Dave Jones</podcast:person>
|
||||
<podcast:person group="visuals" role="cover art designer" href="https://example.com/artist/beckysmith">Becky Smith</podcast:person>
|
||||
<podcast:person href="https://www.podchaser.com/creators/adam-curry-107ZzmWE5f"
|
||||
img="https://example.com/images/adamcurry.jpg">Adam Curry</podcast:person>
|
||||
<podcast:person role="guest" href="https://github.com/daveajones/"
|
||||
img="https://example.com/images/davejones.jpg">Dave Jones</podcast:person>
|
||||
<podcast:person group="visuals" role="cover art designer"
|
||||
href="https://example.com/artist/beckysmith">Becky Smith</podcast:person>
|
||||
<podcast:alternateEnclosure type="audio/mpeg" length="312" default="true">
|
||||
<podcast:source uri="https://example.com/pc20/livestream" />
|
||||
</podcast:alternateEnclosure>
|
||||
|
|
@ -1061,12 +1064,14 @@ A bare bones example:
|
|||
<br><br><br><br><!-- Tag block -->
|
||||
## Content Link
|
||||
`<podcast:contentLink>`<br><br>
|
||||
The `contentLink` tag is used to indicate that the content begin delivered by the parent element can be found at an external location
|
||||
instead of, or in addition to, being delivered directly 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.
|
||||
The `contentLink` tag is used to indicate that the content begin delivered by the parent element can be found at an
|
||||
external location instead of, or in addition to, being delivered directly 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 `<podcast:liveItem>` to deliver a live stream to apps. The feed may also give a `<podcast:contentLink>`
|
||||
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 `<podcast:liveItem>` to deliver a live stream to apps. The feed
|
||||
may also give a `<podcast:contentLink>` 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.
|
||||
|
||||
Currently this tag is only indicated for use in the `<podcast:liveItem>` tag. In the future, its use will be expanded.
|
||||
|
||||
|
|
@ -1077,7 +1082,8 @@ Currently this tag is only indicated for use in the `<podcast:liveItem>` tag. I
|
|||
Multiple
|
||||
|
||||
### Node Value
|
||||
The node value is a free form string meant to explain to the user where this content link points and/or the nature of it's purpose.
|
||||
The node value is a free form string meant to explain to the user where this content link points and/or the nature
|
||||
of it's purpose.
|
||||
|
||||
### Attributes
|
||||
- **href** (required) A string that is the uri pointing to content outside of the application.
|
||||
|
|
@ -1096,17 +1102,18 @@ The node value is a free form string meant to explain to the user where this con
|
|||
<br><br><br><br><!-- Tag block -->
|
||||
## Social Interact
|
||||
`<podcast:socialInteract>`<br><br>
|
||||
The `socialInteract` tag allows a podcaster to attach the url of a "root post" of a comment thread to an episode. This "root post"
|
||||
is treated as the canonical location of where the comments and discussion around this episode will take place. This can be thought
|
||||
of as the "official" social media comment space for this episode. If a protocol such as "activitypub" is used, or some other
|
||||
protocol that allows programmatic API access, these comments can be directly pulled into the app, and replies can be posted back to
|
||||
the thread from the app itself.
|
||||
The `socialInteract` tag allows a podcaster to attach the url of a "root post" of a comment thread to an episode.
|
||||
This "root post" is treated as the canonical location of where the comments and discussion around this episode will
|
||||
take place. This can be thought of as the "official" social media comment space for this episode. If a protocol
|
||||
such as "activitypub" is used, or some other protocol that allows programmatic API access, these comments can be
|
||||
directly pulled into the app, and replies can be posted back to the thread from the app itself.
|
||||
|
||||
If multiple `socialInteract` tags are given for an `<item>`, the `priority` attribute is strongly recommended to give the app an
|
||||
indication as to which comments to display first.
|
||||
If multiple `socialInteract` tags are given for an `<item>`, the `priority` attribute is strongly recommended to
|
||||
give the app an indication as to which comments to display first.
|
||||
|
||||
This tag can also be used as a signal to platforms and apps that the podcaster does not want public comments shown alongside this
|
||||
episode. For this purpose a `protocol` value of "disabled" can be specified, with no other attributes or node value present.
|
||||
This tag can also be used as a signal to platforms and apps that the podcaster does not want public comments shown
|
||||
alongside this episode. For this purpose a `protocol` value of "disabled" can be specified, with no other
|
||||
attributes or node value present.
|
||||
|
||||
### Parent
|
||||
`<item>`
|
||||
|
|
@ -1119,19 +1126,35 @@ episode. For this purpose a `protocol` value of "disabled" can be specified, wi
|
|||
- **protocol** (required) The [protocol](/socialprotocols.txt) in use for interacting with the comment root post.
|
||||
- **accountId** (recommended) The account id (on the commenting platform) of the account that created this root post.
|
||||
- **accountUrl** (optional) The public url (on the commenting platform) of the account that created this root post.
|
||||
- **priority** (optional) When multiple socialInteract tags are present, this integer gives order of priority. A
|
||||
lower number means higher priority.
|
||||
- **priority** (optional) When multiple socialInteract tags are present, this integer gives order of priority. A
|
||||
lower number means higher priority.
|
||||
|
||||
|
||||
Example (simple):
|
||||
```xml
|
||||
<podcast:socialInteract uri="https://podcastindex.social/web/@dave/108013847520053258" protocol="activitypub" accountId="@dave" />
|
||||
<podcast:socialInteract
|
||||
uri="https://podcastindex.social/web/@dave/108013847520053258"
|
||||
protocol="activitypub"
|
||||
accountId="@dave"
|
||||
/>
|
||||
```
|
||||
|
||||
Example (complex):
|
||||
```xml
|
||||
<podcast:socialInteract priority="1" uri="https://podcastindex.social/web/@dave/108013847520053258" protocol="activitypub" accountId="@dave" accountUrl="https://podcastindex.social/web/@dave" />
|
||||
<podcast:socialInteract priority="2" uri="https://twitter.com/PodcastindexOrg/status/1507120226361647115" protocol="twitter" accountId="@podcastindexorg" accountUrl="https://twitter.com/PodcastindexOrg" />
|
||||
<podcast:socialInteract
|
||||
priority="1"
|
||||
uri="https://podcastindex.social/web/@dave/108013847520053258"
|
||||
protocol="activitypub"
|
||||
accountId="@dave"
|
||||
accountUrl="https://podcastindex.social/web/@dave"
|
||||
/>
|
||||
<podcast:socialInteract
|
||||
priority="2"
|
||||
uri="https://twitter.com/PodcastindexOrg/status/1507120226361647115"
|
||||
protocol="twitter"
|
||||
accountId="@podcastindexorg"
|
||||
accountUrl="https://twitter.com/PodcastindexOrg"
|
||||
/>
|
||||
```
|
||||
|
||||
Example (disabled):
|
||||
|
|
@ -1139,18 +1162,20 @@ Example (disabled):
|
|||
<podcast:socialInteract protocol="disabled" />
|
||||
```
|
||||
|
||||
* For **activitypub**, Mastodon or Pleroma's posting API returns a URI (a fully-formed URL with a GUID in it), and a URL (the HTML page where the comment lives). While both of these are acceptable values for the `uri` field referenced in the `socialInteract` specification, we'd recommend using the URI value.
|
||||
* For **activitypub**, Mastodon or Pleroma's posting API returns a URI (a fully-formed URL with a GUID in it), and a
|
||||
URL (the HTML page where the comment lives). While both of these are acceptable values for the `uri` field
|
||||
referenced in the `socialInteract` specification, we'd recommend using the URI value.
|
||||
|
||||
<br><br><br><br><!-- Tag block -->
|
||||
## Block
|
||||
`<podcast:block>`<br><br>
|
||||
This element allows a podcaster to express which platforms are allowed to publicly display this feed and its contents.
|
||||
In its basic form, it is a direct drop-in replacement for the `<itunes:block>` tag, but allows for greater flexibility
|
||||
by the inclusion of the `id` attribute and by including multiple copies of itself in the feed.
|
||||
This element allows a podcaster to express which platforms are allowed to publicly display this feed and its
|
||||
contents. In its basic form, it is a direct drop-in replacement for the `<itunes:block>` tag, but allows for greater
|
||||
flexibility by the inclusion of the `id` attribute and by including multiple copies of itself in the feed.
|
||||
|
||||
Platforms should not ingest a feed for public display/use if their slug exists in the `id` of a `yes` block tag, or if
|
||||
an unbounded `yes` block tag exists (meaning block all public ingestion). Conversely, if a platform finds their slug in
|
||||
the `id` of a `no` block tag, they are free to ingest that feed for public display/usage.
|
||||
Platforms should not ingest a feed for public display/use if their slug exists in the `id` of a `yes` block tag, or
|
||||
if an unbounded `yes` block tag exists (meaning block all public ingestion). Conversely, if a platform finds their
|
||||
slug in the `id` of a `no` block tag, they are free to ingest that feed for public display/usage.
|
||||
|
||||
In plain language, the sequence of discovery an ingesting platform should use is as follows:
|
||||
|
||||
|
|
@ -1166,7 +1191,8 @@ In plain language, the sequence of discovery an ingesting platform should use is
|
|||
Multiple
|
||||
|
||||
### Attributes
|
||||
- **id** (optional) A single entry from the [service slug list](https://github.com/Podcastindex-org/podcast-namespace/blob/main/serviceslugs.txt).
|
||||
- **id** (optional) A single entry from the [service slug list](https://github.
|
||||
com/Podcastindex-org/podcast-namespace/blob/main/serviceslugs.txt).
|
||||
|
||||
### Node value
|
||||
The node value must be "yes" or "no".
|
||||
|
|
@ -1200,9 +1226,11 @@ In plain language, the sequence of discovery an ingesting platform should use is
|
|||
<br><br><br><br><!-- Tag block -->
|
||||
## Txt
|
||||
`<podcast:txt>`<br><br>
|
||||
This element holds free-form text and is modeled after the DNS "[TXT](https://en.wikipedia.org/wiki/TXT_record)" record. It's meant to allow for usages that might be
|
||||
niche or otherwise not rise to the level of needing a dedicated tag. Just like TXT records in DNS allowed for new things
|
||||
like [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework#Implementation) to evolve, this tag can allow novel techniques to be created and sandboxed without a formalization process.
|
||||
This element holds free-form text and is modeled after the DNS "[TXT](https://en.wikipedia.org/wiki/TXT_record)"
|
||||
record. It's meant to allow for usages that might be niche or otherwise not rise to the level of needing a
|
||||
dedicated tag. Just like TXT records in DNS allowed for new things like [SPF](https://en.wikipedia.
|
||||
org/wiki/Sender_Policy_Framework#Implementation) to evolve, this tag can allow novel techniques to be created and
|
||||
sandboxed without a formalization process.
|
||||
|
||||
### Parent
|
||||
`<channel>` or `<item>`
|
||||
|
|
@ -1211,23 +1239,23 @@ like [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework#Implementation)
|
|||
Multiple
|
||||
|
||||
### Attributes
|
||||
- **purpose** (optional) A service specific string that will be used to denote what purpose this tag serves. This could
|
||||
be something like "example.com" if it's a third party hosting platform needing to insert this
|
||||
data, or something like "verify", "release" or any other free form bit of info that is
|
||||
useful to the end consumer that needs it. The free form nature of this tag requires that this
|
||||
attribute is also free formed. This value should not exceed `128 characters`.
|
||||
- **purpose** (optional) A service specific string that will be used to denote what purpose this tag serves. This
|
||||
could be something like "example.com" if it's a third party hosting platform needing to insert this data, or
|
||||
something like "verify", "release" or any other free form bit of info that is useful to the end consumer that
|
||||
needs it. The free form nature of this tag requires that this attribute is also free formed. This value should not
|
||||
exceed `128 characters`.
|
||||
|
||||
### Purposes
|
||||
The following are a list of strings known to be in common use. This list is in no way exhaustive. As new purposes come into
|
||||
common use, this list will be updated by the community to reflect that.
|
||||
The following are a list of strings known to be in common use. This list is in no way exhaustive. As new purposes
|
||||
come into common use, this list will be updated by the community to reflect that.
|
||||
|
||||
- `verify` - The node value is expected to contain a string that is given by a third party platform to a podcaster in
|
||||
order to prove that they are the owner of the feed and are in control of it. This is meant to replace the
|
||||
need for emails to exist in feeds. See example section below.
|
||||
- `verify` - The node value is expected to contain a string that is given by a third party platform to a podcaster
|
||||
in order to prove that they are the owner of the feed and are in control of it. This is meant to replace the need
|
||||
for emails to exist in feeds. See example section below.
|
||||
|
||||
### Node value
|
||||
This is a free form string. Please do not exceed `4000 characters` for the node value or it may be truncated by
|
||||
aggregators.
|
||||
This is a free form string. Please do not exceed `4000 characters` for the node value or it may be
|
||||
truncated by aggregators.
|
||||
|
||||
### Examples
|
||||
```xml
|
||||
|
|
@ -1247,15 +1275,15 @@ common use, this list will be updated by the community to reflect that.
|
|||
<br><br><br><br><!-- Tag block -->
|
||||
## Remote Item
|
||||
`<podcast:remoteItem>`<br><br>
|
||||
This element provides a way to "point" to another feed or an `<item>` in another feed in order to obtain some sort of
|
||||
data that the other feed or feed item has. This allows a podcast app to know where to go and fetch the data being
|
||||
requested. What data is being requested is determined by the parent item. For instance, if the parent item is a
|
||||
`<podcast:podroll>` element, then the remote feed's `<channel>` metadata is needed.
|
||||
This element provides a way to "point" to another feed or an `<item>` in another feed in order to obtain some sort
|
||||
of data that the other feed or feed item has. This allows a podcast app to know where to go and fetch the data
|
||||
being requested. What data is being requested is determined by the parent item. For instance, if the parent item
|
||||
is a `<podcast:podroll>` element, then the remote feed's `<channel>` metadata is needed.
|
||||
|
||||
Using the `feedGuid` attribute is the preferred way to address a remote feed since, but there are times when an app may
|
||||
not have access to a list of resolvable `<podcast:guid>`'s. In that case, it can be beneficial to include the `feedUrl`
|
||||
attribute for those cases as a fallback. If both are present and the app is capable the `feedGuid` should be resolved
|
||||
and used.
|
||||
Using the `feedGuid` attribute is the preferred way to address a remote feed since, but there are times when an app
|
||||
may not have access to a list of resolvable `<podcast:guid>`'s. In that case, it can be beneficial to include the
|
||||
`feedUrl` attribute for those cases as a fallback. If both are present and the app is capable the `feedGuid` should
|
||||
be resolved and used.
|
||||
|
||||
### Parent
|
||||
`<channel>` or `<podcast:podroll>` or `<podcast:valueTimeSplit>`
|
||||
|
|
@ -1267,11 +1295,11 @@ and used.
|
|||
- **feedGuid** (required) The `<podcast:guid>` of the remote feed being pointed to.
|
||||
- **feedUrl** (optional) The url of the remote feed being pointed to.
|
||||
- **itemGuid** (optional) If this remote item element is intended to point to an `<item>` in the remote feed, this
|
||||
attribute should contain the value of the `<guid>` of that `<item>`.
|
||||
- **medium** (optional) If the feed being pointed to is not of medium type 'podcast', this attribute should contain it's
|
||||
`<podcast:medium>` type from the [list](#medium) of types available in this document. The
|
||||
reason this is helpful is to give the app a heads up on what type of data this is expected to be
|
||||
since that may affect the way it approaches fetch and display.
|
||||
attribute should contain the value of the `<guid>` of that `<item>`.
|
||||
- **medium** (optional) If the feed being pointed to is not of medium type 'podcast', this attribute should contain
|
||||
it's `<podcast:medium>` type from the [list](#medium) of types available in this document. The reason this is
|
||||
helpful is to give the app a heads up on what type of data this is expected to be since that may affect the way it
|
||||
approaches fetch and display.
|
||||
|
||||
### Examples
|
||||
```xml
|
||||
|
|
@ -1299,7 +1327,7 @@ and used.
|
|||
<br><br><br><br><!-- Tag block -->
|
||||
## Podroll
|
||||
`<podcast:podroll>`<br><br>
|
||||
This element allows for a podcaster to include references to one or more podcasts in it's `<channel>` as a way of
|
||||
This element allows for a podcaster to include references to one or more podcasts in it's `<channel>` as a way of
|
||||
"recommending" other podcasts to their listener.
|
||||
|
||||
### Parent
|
||||
|
|
@ -1332,42 +1360,66 @@ This element allows a podcaster to express their intended release schedule as st
|
|||
Single
|
||||
|
||||
### Node value
|
||||
The node value is a free-form string, which might be displayed alongside other information about the podcast. Please do not exceed `128 characters` for the node value or it may be truncated by aggregators.
|
||||
The node value is a free-form string, which might be displayed alongside other information about the podcast. Please
|
||||
do not exceed `128 characters` for the node value or it may be truncated by aggregators.
|
||||
|
||||
## Attributes
|
||||
* **complete (optional):** Boolean specifying if the podcast has no intention to release further episodes. If not set, this should be assumed to be false.
|
||||
* **dtstart (optional):** The `date` or `datetime` the recurrence rule begins as an [ISO8601-fornmatted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) string. If the `rrule` contains a value for `COUNT`, then this attribute is required. If the `rrule` contains a value for `UNTIL`, then the value of this attribute must be formatted to the same date/datetime standard.
|
||||
* **rrule (recommended):** A recurrence rule as defined in [iCalendar RFC 5545 Section 3.3.10](https://www.rfc-editor.org/rfc/rfc5545#section-3.3.10).
|
||||
* **complete (optional):** Boolean specifying if the podcast has no intention to release further episodes. If not
|
||||
set, this should be assumed to be false.
|
||||
* **dtstart (optional):** The `date` or `datetime` the recurrence rule begins as an [ISO8601-fornmatted]
|
||||
(https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) string. If the
|
||||
`rrule` contains a value for `COUNT`, then this attribute is required. If the `rrule` contains a value for `UNTIL`,
|
||||
then the value of this attribute must be formatted to the same date/datetime standard.
|
||||
* **rrule (recommended):** A recurrence rule as defined in [iCalendar RFC 5545 Section 3.3.10](https://www.
|
||||
rfc-editor.org/rfc/rfc5545#section-3.3.10).
|
||||
|
||||
## Examples
|
||||
Recreating most of Apple Podcasts Connect’s “Update Frequency” values is easily achieved:
|
||||
```xml
|
||||
<podcast:updateFrequency rrule="FREQ=DAILY">Daily</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY">Weekly</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY;INTERVAL=2">Biweekly</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=MONTHLY">Monthly</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=MONTHLY;INTERVAL=2">Bimonthly</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=MONTHLY">Monthly</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=YEARLY">Yearly</podcast:updateFrequency>
|
||||
```
|
||||
|
||||
However, greater precision can be easily communicated:
|
||||
```xml
|
||||
<podcast:updateFrequency rrule="FREQ=DAILY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR">Every weekday</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY;BYDAY=MO,WE">Every Monday and Wednesday</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY;BYDAY=FR;BYMONTHDAY=13">Every friday the 13th</podcast:updateFrequency>
|
||||
<podcast:updateFrequency rrule="FREQ=YEARLY;BYDAY=+4TH;BYMONTH=11">Every year on American Thanksgiving</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=YEARLY;BYDAY=+4TH;BYMONTH=11">
|
||||
Every year on American Thanksgiving
|
||||
</podcast:updateFrequency>
|
||||
```
|
||||
|
||||
Limited-run podcasts can indicate when they’ll go on hiatus by setting an UNTIL date or a COUNT:
|
||||
```xml
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY;INTERVAL=2;BYDAY=MO;COUNT=10" dtstart="2023-08-28T00:00:00.000Z">Every other Monday for 10 episodes starting on Aug 28, 2023</podcast:updateFrequency>
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY;UNTIL=2023-12-31T00:00:00.000Z;BYDAY=MO">Every Monday until Dec 31, 2023</podcast:updateFrequency>
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY;INTERVAL=2;BYDAY=MO;COUNT=10" dtstart="2023-08-28T00:00:00.000Z">
|
||||
Every other Monday for 10 episodes starting on Aug 28, 2023
|
||||
</podcast:updateFrequency>
|
||||
|
||||
<podcast:updateFrequency rrule="FREQ=WEEKLY;UNTIL=2023-12-31T00:00:00.000Z;BYDAY=MO">
|
||||
Every Monday until Dec 31, 2023
|
||||
</podcast:updateFrequency>
|
||||
```
|
||||
|
||||
Podcasts currently on hiatus can indicate their intention to resume production by setting a DTSTART value in the future:
|
||||
```xml
|
||||
<podcast:updateFrequency dtstart="2025-01-01T00:00:00.000Z" rrule="FREQ=WEEKLY">Weekly, starting in 2025</podcast:updateFrequency>
|
||||
<podcast:updateFrequency dtstart="2025-01-01T00:00:00.000Z" rrule="FREQ=WEEKLY">
|
||||
Weekly, starting in 2025
|
||||
</podcast:updateFrequency>
|
||||
```
|
||||
|
||||
Complete podcasts with no intention to release further episodes:
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue