mirror
/
podcast-namespace
kopia lustrzana https://github.com/Podcastindex-org/podcast-namespace
1
0
Forkuj 0
Kod Zgłoszenia Packages Projekty Wydania Wiki Aktywność

Merge pull request #290 from benjaminbellamy/patch-13 

Minor <podcast:recommendations> corrections
pull/294/head
Dave Jones 2021-08-31 10:15:37 -05:00 zatwierdzone przez GitHub
rodzic 0404e7ddc0 095ab62fa6
commit 3b6c0845d9
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: 4AEE18F83AFDEB23
1 zmienionych plików z 58 dodań i 37 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

93
proposal-docs/recommendations/recommendations.md
Wyświetl plik

@ -1,6 +1,6 @@
# The "podcast:recommendations" Specification
<small>Version 1.1 by Benjamin Bellamy - 2021.08.11</small>
<small>Version 1.2 by Benjamin Bellamy - 2021.08.31</small>
<br>
@ -13,8 +13,9 @@ Several platforms are now implementing recommendation engines, but these feature
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.
- 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.
- a `motive` tag that explains why a specific recommendation was included,
- a `medium` tag so that this can work with any feed, including non-podcast medium. (See \<podcast:medium> for more information.)
- Version 1.2 brings minor corrections.
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!!!
@ -59,7 +60,7 @@ Example:
```json
{
"version": "1.0",
"version": "1.2",
"title": "Podnews podcasting news",
"feed": "https://podnews.net/rss",
"guid": "9b024349-ccf0-5f69-a609-6b82873eab3c"
@ -72,7 +73,7 @@ The "recommendation" object takes this basic form:
```json
{
"type": "page",
"link-type": "generic",
"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"
@ -81,21 +82,41 @@ The "recommendation" object takes this basic form:
There are 4 required attributes:
- `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`
- `link-type` (required - string) The link type of this recommended content, it can be:
- 'generic',
- 'feed',
- 'feed-item',
- 'none'
- `medium` (required - string) The medium kind. It can be:
- `podcast`,
- `audiobook`,
- `music`,
- `video`,
- `film`,
- `image`,
- `text`,
- `html`
- `title` (required - string) The title for this recommended content.
#### 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.
- `url` (optional - string) The URL for this recommended content. If recommended content type is *"feed"* this is the home page of the podcast/medium. If recommended content type is *"feed-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 *"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`
- `feed` (optional - string) The RSS URL of this recommended content. Applies to *"feed"*, *"feed-item"* types.
- `guid` (optional - string) The GUID of this recommended content. Applies to *"feed"* and *"feed-item"* types.
- `startTime` (optional - float) The start time (in seconds) of this recommended content. Applies to *"feed-item"* type only.
- `duration` (optional - float) The duration (in seconds) of this recommended content. Applies to *"feed-item"* type only.
- `motive` (optional - string) The reason why this content is recommended. It can be:
- `references`,
- `additional content`,
- `acknowledgment`,
- `advertising`,
- `audience exchange`,
- `similar content`,
- `also liked by the audience`,
- `made by the same people`
- `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
@ -104,26 +125,26 @@ Here is what a very basic recommendations file may look like:
```json
{
"version": "1.0",
"version": "1.2",
"recommendations":
[
{
"type": "text",
"media-kind": "text",
"link-type": "none",
"medium": "text",
"title": "Eat five vegetables every day.",
"motive": "advertising"
},
{
"type": "page",
"media-kind": "html",
"link-type": "generic",
"medium": "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"
"motive": "additional content"
},
{
"type": "feed",
"media-kind": "podcast",
"link-type": "feed",
"medium": "podcast",
"title": "Podcasting 2.0",
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
"url": "https://podcastindex.org/podcast/920666",
@ -131,8 +152,8 @@ Here is what a very basic recommendations file may look like:
"motive": "audience exchange"
},
{
"type": "item",
"media-kind": "podcast",
"link-type": "item",
"medium": "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",
@ -140,8 +161,8 @@ Here is what a very basic recommendations file may look like:
"guid": "PC2026"
},
{
"type": "item",
"media-kind": "podcast",
"link-type": "item",
"medium": "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",
@ -158,23 +179,23 @@ Here is what a very basic recommendations file may look like:
```json
{
"version": "1.0",
"version": "1.2",
"title": "Podnews podcasting news",
"feed": "https://podnews.net/rss",
"guid": "9b024349-ccf0-5f69-a609-6b82873eab3c",
"recommendations":
[
{
"type": "text",
"media-kind": "text",
"link-type": "none",
"medium": "text",
"title": "Eat five vegetables every day.",
"motive": "advertising"
},
{
"displayStartTime": 0.0,
"displayDuration": 120.0,
"type": "page",
"media-kind": "html",
"link-type": "generic",
"medium": "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",
@ -184,8 +205,8 @@ Here is what a very basic recommendations file may look like:
{
"displayStartTime": 120.50,
"displayDuration": 60.0,
"type": "feed",
"media-kind": "podcast",
"link-type": "feed",
"medium": "podcast",
"title": "Podcasting 2.0",
"image": "https://noagendaassets.com/enc/1601061118.678_pciavatar.jpg",
"url": "https://podcastindex.org/podcast/920666",
@ -196,8 +217,8 @@ Here is what a very basic recommendations file may look like:
{
"displayStartTime": 240.60,
"displayDuration": 180.0,
"type": "item",
"media-kind": "podcast",
"link-type": "feed-item",
"medium": "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",
@ -208,8 +229,8 @@ Here is what a very basic recommendations file may look like:
{
"displayStartTime": 3600.10,
"displayDuration": 60.0,
"type": "item",
"media-kind": "podcast",
"link-type": "item",
"medium": "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",