From b89df3cfed17d0dc7a0ab34f0ff9a869efca078e Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Mon, 26 Oct 2020 16:32:29 -0500 Subject: [PATCH] chapters - remove id and hasArtwork - #91 --- chapters/example.json | 8 +++++- chapters/exampleComplex.json | 34 ++++++++++-------------- chapters/jsonChapters.md | 50 +++++++++++++++--------------------- 3 files changed, 41 insertions(+), 51 deletions(-) diff --git a/chapters/example.json b/chapters/example.json index ec1c9d7..50e6c26 100644 --- a/chapters/example.json +++ b/chapters/example.json @@ -1,6 +1,7 @@ { "version": "1.0.0", - "chapters": [ + "chapters": + [ { "startTime": 0, "title": "Intro" @@ -25,6 +26,11 @@ "title": "Just Break Up", "img": "https://example.com/images/justbreakuppod.png" }, + { + "startTime": 4600, + "title": "Donations", + "url": "https://example.com/paypal_link" + }, { "startTime": 5510, "title": "The Big Players" diff --git a/chapters/exampleComplex.json b/chapters/exampleComplex.json index 681f8b8..45e75cb 100644 --- a/chapters/exampleComplex.json +++ b/chapters/exampleComplex.json @@ -3,60 +3,54 @@ "author": "John Doe", "title": "Episode 7 - Making Progress", "podcastName": "John's Awesome Podcast", - "chapters": [ + "chapters": + [ { "startTime": 0, - "title": "Intro", - "id": "ch0" + "title": "Intro" }, { "startTime": 168, "title": "Hearing Aids", - "id": "ch1", "hasArtwork": "chapter1.jpg" }, { "startTime": 260, - "title": "Progress Report", - "id": "ch2" + "title": "Progress Report" }, { "startTime": 410, "title": "Namespace", "img": "https://example.com/images/namepsace_example.jpg", - "url": "https://github.com/Podcastindex-org/podcast-namespace", - "id": "ch3" + "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", - "id": "ch4", - "hasArtwork": false + "url": "https://twitter.com/justbreakuppod" + }, + { + "startTime": 4600, + "title": "Donations", + "url": "https://example.com/paypal_link" }, { "startTime": 4826, - "title": "Boston Harbor", "img": "https://example.com/images/bostonharbor.jpg", - "id": "ch5", "toc": false }, { "startTime": 5510, - "title": "The Big Players", - "id": "ch6" + "title": "The Big Players" }, { "startTime": 5854, - "title": "Spread the Word", - "id": "ch7", - "hasArtwork": "chapter6.jpg" + "title": "Spread the Word" }, { "startTime": 6089, - "title": "Outro", - "id": "ch8" + "title": "Outro" } ] } \ No newline at end of file diff --git a/chapters/jsonChapters.md b/chapters/jsonChapters.md index 5bfe3b0..f99e363 100644 --- a/chapters/jsonChapters.md +++ b/chapters/jsonChapters.md @@ -14,21 +14,14 @@ The "chapters" property is an array of "chapter" objects which take this basic f Chapter Object Attributes: - `startTime` (required - float) The time, expressed in seconds with float precision for fractions of a second. - - `title` (required - string) The title of this chapter. + - `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. - - `id` (optional - string) Can be useful for software that expects an "ID" value for a chapter. For example, "ch1", - "ch2", etc. - `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". - - `hasArtwork` (optional - string) This is an alternate way to specify an image for a chapter, as a relative url to the - current base. If this property is present, it's value is considered the file name of - the image file relative to the current url. For example, if the chapters.json file - was located at "example.com/podcast/chapters.json", and a value of "ch1.jpg" was given - for this property, the file "example.com/podcast/ch1.jpg" would be expected to exist. @@ -90,7 +83,7 @@ Here is what a very basic chapters file may look like: } ``` -In this simple form, the chapter objects have no ID's and are treated as sequential just based on their index as a function of being +In this simple form, the chapter objects are treated as sequential just based on their index as a function of being ordered in ascending fashing 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. @@ -99,7 +92,8 @@ ordered in ascending fashing based on their `startTime`. In a very simple examp ## 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: +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: ``` { @@ -111,58 +105,54 @@ context for something like an embedded HTML5 player on a website: [ { "startTime": 0, - "title": "Intro", - "id": "ch0" + "title": "Intro" }, { "startTime": 168, "title": "Hearing Aids", - "id": "ch1", "hasArtwork": "chapter1.jpg" }, { "startTime": 260, - "title": "Progress Report", - "id": "ch2" + "title": "Progress Report" }, { "startTime": 410, "title": "Namespace", "img": "https://example.com/images/namepsace_example.jpg", - "url": "https://github.com/Podcastindex-org/podcast-namespace", - "id": "ch3" + "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", - "id": "ch4", - "hasArtwork": false + "url": "https://twitter.com/justbreakuppod" }, { "startTime": 4826, - "title": "Boston Harbor", "img": "https://example.com/images/bostonharbor.jpg", - "id": "ch5", "toc": false }, { "startTime": 5510, - "title": "The Big Players", - "id": "ch6" + "title": "The Big Players" }, { "startTime": 5854, - "title": "Spread the Word", - "id": "ch7", - "hasArtwork": "chapter6.jpg" + "title": "Spread the Word" }, { "startTime": 6089, - "title": "Outro", - "id": "ch8" + "title": "Outro" } ] } -``` \ No newline at end of file +``` + +

+ +## 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 +podcasts can then be remembered for the future. \ No newline at end of file