From d16c461179df867f662135688316a9727a715b2b Mon Sep 17 00:00:00 2001 From: Benjamin Bellamy Date: Tue, 31 Aug 2021 17:01:29 +0200 Subject: [PATCH 1/2] Update recommendations.md --- .../recommendations/recommendations.md | 93 ++++++++++++------- 1 file changed, 57 insertions(+), 36 deletions(-) diff --git a/proposal-docs/recommendations/recommendations.md b/proposal-docs/recommendations/recommendations.md index 414a5c5..368830e 100644 --- a/proposal-docs/recommendations/recommendations.md +++ b/proposal-docs/recommendations/recommendations.md @@ -1,6 +1,6 @@ # The "podcast:recommendations" Specification -Version 1.1 by Benjamin Bellamy - 2021.08.11 +Version 1.2 by Benjamin Bellamy - 2021.08.31
@@ -14,7 +14,8 @@ This specification is about giving control to content creators on the content th - 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 `medium` tag so that this can work with any feed, including non-podcast medium. (See \ 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,8 +73,8 @@ The "recommendation" object takes this basic form: ```json { - "type": "page", - "title": "History of podcasting", + "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", From 095ab62fa6bc31be839ce3dd2fe17483e584596c Mon Sep 17 00:00:00 2001 From: Benjamin Bellamy Date: Tue, 31 Aug 2021 17:03:36 +0200 Subject: [PATCH 2/2] Update recommendations.md --- proposal-docs/recommendations/recommendations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposal-docs/recommendations/recommendations.md b/proposal-docs/recommendations/recommendations.md index 368830e..528dab6 100644 --- a/proposal-docs/recommendations/recommendations.md +++ b/proposal-docs/recommendations/recommendations.md @@ -13,7 +13,7 @@ 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 `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 \ 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.