kopia lustrzana https://github.com/Podcastindex-org/podcast-namespace
Dave Jones
GitHub
commit
00717cf449
|
|
@ -1,17 +1,21 @@
|
|||
# The "podcast:recommendations" Specification
|
||||
|
||||
<small>Version 1.0 by Benjamin Bellamy - 2021.03.04</small>
|
||||
<small>Version 1.1 by Benjamin Bellamy - 2021.08.11</small>
|
||||
|
||||
<br>
|
||||
|
||||
## Purpose
|
||||
|
||||
Podcasting is a tremendous ecosystem brimming with tons of stories and ideas that go freely from any platform to any application.
|
||||
That comes with a huge drawback: finding and being found can be harsh.
|
||||
Podcast creators struggle to be found while podcast listeners struggle to find content.
|
||||
Several platforms are now implementing recommendation engines, but these features are expensive and unattainable for small players. Moreover they are slowly creating closed silos and removing power from content creators.
|
||||
- Podcasting is a tremendous ecosystem brimming with tons of stories and ideas that go freely from any platform to any application.
|
||||
That comes with a huge drawback: finding and being found can be harsh.
|
||||
Podcast creators struggle to be found while podcast listeners struggle to find content.
|
||||
Several platforms are now implementing recommendation engines, but these features are expensive and unattainable for small players. Moreover they are slowly creating closed silos and removing power from content creators.
|
||||
This specification is about giving control to content creators on the content they want to recommend, and at the same time providing a free recommendation system to all players.
|
||||
It was heavily inspired by all the work previously done by the Fellowship of the PodcastIndex on the chapters and soundbite tags. May they be thanked for it.
|
||||
- Version 1.1 adds:
|
||||
- `GUID` support for channel element,
|
||||
- a `reason` tag that explains why a specefic recommendation was included,
|
||||
- a `medium-type` tag so that this can work with any feed, including non-podcast media, an element with no URL.
|
||||
All this was heavily inspired by all the work previously done by the Fellowship of the PodcastIndex on the chapters and soundbite tags. May they be thanked for it.
|
||||
GO PODCASTING!!!
|
||||
|
||||
## Specification
|
||||
|
|
@ -34,7 +38,7 @@ GO PODCASTING!!!
|
|||
|
||||
Examples:
|
||||
- `<podcast:recommendations url="https://domain.tld/recommendation?guid=1234" type="application/json" />`
|
||||
- `<podcast:recommendations url="https://domain.tld/recommendation?guid=1234" type="application/json" language="en">Some other cool podcasts</podcast:recommendations>`
|
||||
- `<podcast:recommendations url="https://domain.tld/recommendation?guid=1234" type="application/json" language="en"/>`
|
||||
|
||||
## "Recommendations" Object
|
||||
|
||||
|
|
@ -46,10 +50,21 @@ The recommendations object is a simple JSON object with 2 required properties:
|
|||
#### Optional Attributes:
|
||||
|
||||
- `comment` (optional - string) A comment on this file.
|
||||
- `title` (optional - string) The name of the source podcast or source podcast episode. Applies to both Channel and Item.
|
||||
- `feed` (optional - string) The RSS URL of the source podcast. Applies to both Channel and Item.
|
||||
- `guid` (optional - string) The GUID of the source episode. Applies to Item only.
|
||||
- `url` (required - string) The enclosure URL of the source episode. Applies to Item only.
|
||||
- `title` (optional - string) The name of the source podcast or **source** podcast episode. Applies to both Channel and Item.
|
||||
- `feed` (optional - string) The RSS URL of the **source** podcast. Applies to both podcast Channel and podcast Item.
|
||||
- `guid` (optional - string) The GUID of the **source** element. Applies to both podcast Channel and podcast Item.
|
||||
- `url` (optionnal - string) The enclosure URL of the **source** medium.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"title": "Podnews podcasting news",
|
||||
"feed": "https://podnews.net/rss",
|
||||
"guid": "9b024349-ccf0-5f69-a609-6b82873eab3c"
|
||||
}
|
||||
```
|
||||
|
||||
## "Recommendation" Objects
|
||||
|
||||
|
|
@ -66,19 +81,21 @@ The "recommendation" object takes this basic form:
|
|||
|
||||
There are 4 required attributes:
|
||||
|
||||
- `type` (required - string) The type of this recommended content (*"page"*, *"podcast"*, *"episode"* or *"soundbite"*).
|
||||
- `type` (required - string) The type of this recommended content (*"page"*, *"feed"*, *"item"*, *"text"*).
|
||||
- `media-kind` (required - string) The media kind. It can be `podcast`, `audiobook`, `music`, `video`, `image`, `text`, `html`
|
||||
- `title` (required - string) The title for this recommended content.
|
||||
- `image` (required - string) The image URL for this recommended content. Image must have a 1:1 ratio (square).
|
||||
- `url` (required - string) The URL for this recommended content. If recommended content type is *"podcast"* this is the home page of the podcast. If recommended content type is *"episode"* or *"soundbite"* this is the enclosure URL.
|
||||
|
||||
#### Optional Attributes:
|
||||
|
||||
- `url` (optional - string) The URL for this recommended content. If recommended content type is *"feed"* this is the home page of the podcast. If recommended content type is *"item"* this is the enclosure URL.
|
||||
- `image` (optional - string) The image URL for this recommended content. Image must have a 1:1 ratio (square).
|
||||
- `displayStartTime` (optional - float) The start time (in seconds) that tells when this recommended content should start being displayed. If `displayStartTime` is omitted, recommendation will be displayed from the beginning. Applies only when called from an *Item* (not from the *Channel*).
|
||||
- `displayDuration` (optional - float) The duration (in seconds) that tells when this recommended content should stop being displayed. If `displayDuration` is omitted, recommendation will be displayed until the end. Applies only when called from an *Item* (not from the *Channel*).
|
||||
- `feed` (optional - string) The RSS URL of this recommended content. Applies to *"podcast"*, *"episode"* and *"soundbite"* types only.
|
||||
- `guid` (optional - string) The GUID of this recommended content. Applies to *"episode"* and *"soundbite"* types only.
|
||||
- `startTime` (optional - float) The start time (in seconds) of this recommended content. Applies to *"soundbite"* type only.
|
||||
- `duration` (optional - float) The duration (in seconds) of this recommended content. Applies to *"soundbite"* type only.
|
||||
- `feed` (optional - string) The RSS URL of this recommended content. Applies to *"feed"*, *"item"* types.
|
||||
- `guid` (optional - string) The GUID of this recommended content. Applies to *"feed"* and *"item"* types.
|
||||
- `startTime` (optional - float) The start time (in seconds) of this recommended content. Applies to *"item"* type only.
|
||||
- `duration` (optional - float) The duration (in seconds) of this recommended content. Applies to *"item"* type only.
|
||||
- `motive` (optional - string) The reason why this content is recommended. It can be `additional content`, `acknowledgment`, `thanking`, `advertising`, `audience exchange`, `similar content`, `also liked by the audience`, `made by the same team`, `do you want to know more`
|
||||
- `relevance` (optional - float) The relevance of this recommended content regarding this Channel or Item. Number must be in [0…1]. 0 is for irrelevant content, 1 is for contents that match perfectly.
|
||||
|
||||
## Basic example
|
||||
|
|
@ -91,20 +108,31 @@ Here is what a very basic recommendations file may look like:
|
|||
"recommendations":
|
||||
[
|
||||
{
|
||||
"type": "page",
|
||||
"title": "History of podcasting",
|
||||
"image": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e7/Podcasts_%28iOS%29.svg/440px-Podcasts_%28iOS%29.svg.png",
|
||||
"url": "https://en.wikipedia.org/wiki/History_of_podcasting"
|
||||
"type": "text",
|
||||
"media-kind": "text",
|
||||
"title": "Eat five vegetables every day.",
|
||||
"motive": "advertising"
|
||||
},
|
||||
{
|
||||
"type": "podcast",
|
||||
"type": "page",
|
||||
"media-kind": "html",
|
||||
"title": "History of podcasting",
|
||||
"image": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e7/Podcasts_%28iOS%29.svg/440px-Podcasts_%28iOS%29.svg.png",
|
||||
"url": "https://en.wikipedia.org/wiki/History_of_podcasting",
|
||||
"motive": "do you want to know more"
|
||||
},
|
||||
{
|
||||
"type": "feed",
|
||||
"media-kind": "podcast",
|
||||
"title": "Podcasting 2.0",
|
||||
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
|
||||
"url": "https://podcastindex.org/podcast/920666",
|
||||
"feed": "http://mp3s.nashownotes.com/pc20rss.xml"
|
||||
"feed": "http://mp3s.nashownotes.com/pc20rss.xml",
|
||||
"motive": "audience exchange"
|
||||
},
|
||||
{
|
||||
"type": "episode",
|
||||
"type": "item",
|
||||
"media-kind": "podcast",
|
||||
"title": "Episode 26: Manning Battlestations",
|
||||
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
|
||||
"url": "https://mp3s.nashownotes.com/PC20-26-2021-02-26-Final.mp3",
|
||||
|
|
@ -112,7 +140,8 @@ Here is what a very basic recommendations file may look like:
|
|||
"guid": "PC2026"
|
||||
},
|
||||
{
|
||||
"type": "soundbite",
|
||||
"type": "item",
|
||||
"media-kind": "podcast",
|
||||
"title": "GO PODCASTING!!!",
|
||||
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
|
||||
"url": "https://mp3s.nashownotes.com/PC20-26-2021-02-26-Final.mp3",
|
||||
|
|
@ -132,31 +161,43 @@ Here is what a very basic recommendations file may look like:
|
|||
"version": "1.0",
|
||||
"title": "Podnews podcasting news",
|
||||
"feed": "https://podnews.net/rss",
|
||||
"guid": "9b024349-ccf0-5f69-a609-6b82873eab3c",
|
||||
"recommendations":
|
||||
[
|
||||
{
|
||||
"type": "text",
|
||||
"media-kind": "text",
|
||||
"title": "Eat five vegetables every day.",
|
||||
"motive": "advertising"
|
||||
},
|
||||
{
|
||||
"displayStartTime": 0.0,
|
||||
"displayDuration": 120.0,
|
||||
"type": "page",
|
||||
"media-kind": "html",
|
||||
"title": "History of podcasting",
|
||||
"image": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e7/Podcasts_%28iOS%29.svg/440px-Podcasts_%28iOS%29.svg.png",
|
||||
"url": "https://en.wikipedia.org/wiki/History_of_podcasting",
|
||||
"motive": "do you want to know more",
|
||||
"relevance": 0.8
|
||||
},
|
||||
{
|
||||
"displayStartTime": 120.50,
|
||||
"displayDuration": 60.0,
|
||||
"type": "podcast",
|
||||
"type": "feed",
|
||||
"media-kind": "podcast",
|
||||
"title": "Podcasting 2.0",
|
||||
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
|
||||
"url": "https://podcastindex.org/podcast/920666",
|
||||
"feed": "http://mp3s.nashownotes.com/pc20rss.xml",
|
||||
"motive": "audience exchange",
|
||||
"relevance": 0.7
|
||||
},
|
||||
{
|
||||
"displayStartTime": 240.60,
|
||||
"displayDuration": 180.0,
|
||||
"type": "episode",
|
||||
"type": "item",
|
||||
"media-kind": "podcast",
|
||||
"title": "Episode 26: Manning Battlestations",
|
||||
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
|
||||
"url": "https://mp3s.nashownotes.com/PC20-26-2021-02-26-Final.mp3",
|
||||
|
|
@ -167,7 +208,8 @@ Here is what a very basic recommendations file may look like:
|
|||
{
|
||||
"displayStartTime": 3600.10,
|
||||
"displayDuration": 60.0,
|
||||
"type": "soundbite",
|
||||
"type": "item",
|
||||
"media-kind": "podcast",
|
||||
"title": "GO PODCASTING!!!",
|
||||
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
|
||||
"url": "https://mp3s.nashownotes.com/PC20-26-2021-02-26-Final.mp3",
|
||||
|
|
@ -175,6 +217,7 @@ Here is what a very basic recommendations file may look like:
|
|||
"guid": "PC2026",
|
||||
"startTime": 4737.0,
|
||||
"duration": 5.0,
|
||||
"motive": "do you want to know more",
|
||||
"relevance": 0.9
|
||||
}
|
||||
]
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue