From 605b03697b0e81fec2fbb53b03d1904cd498f2ec Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Thu, 15 Apr 2021 12:17:16 -0500 Subject: [PATCH] location in chapters - chapter v1.2 bump --- chapters/jsonChapters.md | 41 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/chapters/jsonChapters.md b/chapters/jsonChapters.md index bc560fb..30d1871 100644 --- a/chapters/jsonChapters.md +++ b/chapters/jsonChapters.md @@ -1,4 +1,5 @@ -## JSON Chapters Format (v1.1.0) +## JSON Chapters Format (v1.2.0) + This is the initial spec for a json chapters format that can be referenced in an RSS feed using the `` tag of the "podcast" namespace. This file can reside on any publicly accessible url. See the podcast namespace documentation for @@ -26,7 +27,7 @@ The chapters object is a simple JSON object with only 2 required properties:
-## "Chapter" Objects +## The "Chapter" Object The "chapter" object takes this basic form: @@ -41,6 +42,8 @@ There is only one required attribute: - `startTime` (required - float) The starting time of the chapter, expressed in seconds with float precision for fractions of a second. +
+ #### Optional Attributes: - `title` (optional - string) The title of this chapter. @@ -48,6 +51,32 @@ There is only one required attribute: - `url` (optional - string) The url of a web page or supporting document that's related to the topic of this chapter. - `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". - `endTime` (optional - float) The end time of the chapter, expressed in seconds with float precision for fractions of a second. + - `location` (optional - object) This object defines an optional location that is tied to this chapter. It follows the structure of the [location](https://github.com/Podcastindex-org/podcast-namespace/blob/main/location/location.md) tag in the XML namespace. + +
+ +## The Location Object: + +The "location" object takes this basic form: + +``` +{ + "name": "Eiffel Tower, Paris", + "geo": "geo:48.858093,2.294694" +} +``` + +It is intended to provide for rich location-based experiences tied to a point of time within a podcast episode, or other feed based media. For example, a "walking tour" may include latitude and longitude waypoints along side the image within chapters markers as someone listens to the tour podcast. This +would allow apps to show a map with markers within the UI as the tour progresses. Or, perhaps a "History of the Middle East" podcast might expose a map to highlight where certain landmarks are when being discussed. + +There are two required attributes: + + - `name` (required - string) A human readable place name. + - `geo` (required - string) A simple latitude,longitude given in geoURI format, conformant to [RFC 5870](https://tools.ietf.org/html/rfc5870). + +#### Optional Attributes: + + - `osm` (optional - string) An OpenStreetMaps query string. Please see the [location](https://github.com/Podcastindex-org/podcast-namespace/blob/main/location/location.md) XML tag specification for full details.
@@ -148,7 +177,11 @@ chapter list, but allows for different artwork to be shown: { "startTime": 4826, "img": "https://example.com/images/bostonharbor.jpg", - "toc": false + "toc": false, + "location": { + "name": "Eiffel Tower, Paris", + "geo": "geo:42.3417649,-70.9661596" + } }, { "startTime": 5510, @@ -172,4 +205,4 @@ chapter list, but allows for different artwork to be shown: 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. +podcasts can then be remembered for the future. \ No newline at end of file