diff --git a/chapters/jsonChapters.md b/chapters/jsonChapters.md
index 1b6e716..b0c67db 100644
--- a/chapters/jsonChapters.md
+++ b/chapters/jsonChapters.md
@@ -1,13 +1,14 @@
## JSON Chapters Format
-Version 1.2 - Updated on 2021.04.15
+
+Version 1.2 - Updated on 2023-04-19
-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
+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
details on the format of the tag.
-This type of file should be served with a Content-type of 'application/json+chapters'. Chapter order is assumed to be
+This type of file should be served with a content-type of `application/json`, and can be combined with other episode metadata (as shown below). Chapter order is assumed to be
in ascending order based on the `startTime`.
@@ -16,17 +17,17 @@ in ascending order based on the `startTime`.
The chapters object is a simple JSON object with only 2 required properties:
- - `version` (required - string) The version number of the format being used
- - `chapters` (required - array) An array of chapter objects defined below
+- `version` (required - string) The version number of the format being used
+- `chapters` (required - array) An array of chapter objects defined below
#### Optional Attributes:
- - `author` (optional - string) The name of the author of this podcast episode.
- - `title` (optional - string) The title of this podcast episode.
- - `podcastName` (optional - string) The name of the podcast this episode belongs to.
- - `description` (optional - string) A description of this episode.
- - `fileName` (optional - string) The name of the audio file these chapters apply to.
- - `waypoints` (optional - boolean) If this property is present, the locations in a chapter object should be displayed with a route between locations.
+- `author` (optional - string) The name of the author of this podcast episode.
+- `title` (optional - string) The title of this podcast episode.
+- `podcastName` (optional - string) The name of the podcast this episode belongs to.
+- `description` (optional - string) A description of this episode.
+- `fileName` (optional - string) The name of the audio file these chapters apply to.
+- `waypoints` (optional - boolean) If this property is present, the locations in a chapter object should be displayed with a route between locations.
@@ -36,25 +37,25 @@ The "chapter" object takes this basic form:
```json
{
- "startTime": 94,
- "title": "Donation Segment"
+ "startTime": 94,
+ "title": "Donation Segment"
}
```
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.
+- `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.
- - `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.
- - `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.
+- `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.
+- `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 metadata 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.
@@ -64,141 +65,139 @@ The "location" object takes this basic form:
```json
{
- "name": "Eiffel Tower, Paris",
- "geo": "geo:48.858093,2.294694"
+ "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.
+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).
+- `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.
+- `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.
## Basic example
-Here is what a very basic chapters file may look like:
+Here is an example of the minimal data to include chapters inside the episode's metadata file:
```json
{
- "version": "1.2.0",
- "chapters":
- [
- {
- "startTime": 0,
- "title": "Intro"
- },
- {
- "startTime": 168,
- "title": "Hearing Aids",
- "img": "https://example.com/images/hearing_aids.jpg"
- },
- {
- "startTime": 260,
- "title": "Progress Report"
- },
- {
- "startTime": 410,
- "title": "Namespace",
- "img": "https://example.com/images/namepsace_example.jpg",
- "url": "https://github.com/Podcastindex-org/podcast-namespace"
- },
- {
- "startTime": 3990,
- "title": "Just Break Up",
- "img": "https://example.com/images/justbreakuppod.png"
- },
- {
- "startTime": 5510,
- "title": "The Big Players"
- },
- {
- "startTime": 5854,
- "title": "Spread the Word"
- },
- {
- "startTime": 6089,
- "title": "Outro"
- }
- ]
+ "version": "1.2.0",
+ "chapters": [
+ {
+ "startTime": 0,
+ "title": "Intro"
+ },
+ {
+ "startTime": 168,
+ "title": "Hearing Aids",
+ "img": "https://example.com/images/hearing_aids.jpg"
+ },
+ {
+ "startTime": 260,
+ "title": "Progress Report"
+ },
+ {
+ "startTime": 410,
+ "title": "Namespace",
+ "img": "https://example.com/images/namepsace_example.jpg",
+ "url": "https://github.com/Podcastindex-org/podcast-namespace"
+ },
+ {
+ "startTime": 3990,
+ "title": "Just Break Up",
+ "img": "https://example.com/images/justbreakuppod.png"
+ },
+ {
+ "startTime": 5510,
+ "title": "The Big Players"
+ },
+ {
+ "startTime": 5854,
+ "title": "Spread the Word"
+ },
+ {
+ "startTime": 6089,
+ "title": "Outro"
+ }
+ ]
}
```
In this simple form, the chapter objects are treated as sequential just based on their index as a function of being
-ordered in ascending fashion 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.
+ordered in ascending fashion 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 metadata.
## 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. Also there is an example of a "silent" chapter that has no presence in the visible
+In this more robust example, we can bring in more metadata 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. 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:
```json
{
- "version": "1.2.0",
- "author": "John Doe",
- "title": "Episode 7 - Making Progress",
- "podcastName": "John's Awesome Podcast",
- "chapters":
- [
- {
- "startTime": 0,
- "title": "Intro"
- },
- {
- "startTime": 168,
- "title": "Hearing Aids",
- "hasArtwork": "chapter1.jpg"
- },
- {
- "startTime": 260,
- "title": "Progress Report"
- },
- {
- "startTime": 410,
- "title": "Namespace",
- "img": "https://example.com/images/namepsace_example.jpg",
- "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"
- },
- {
- "startTime": 4826,
- "img": "https://example.com/images/parisfrance.jpg",
- "toc": false,
- "location": {
- "name": "Eiffel Tower, Paris",
- "geo": "geo:42.3417649,-70.9661596"
- }
- },
- {
- "startTime": 5510,
- "title": "The Big Players"
- },
- {
- "startTime": 5854,
- "title": "Spread the Word"
- },
- {
- "startTime": 6089,
- "title": "Outro"
- }
- ]
+ "version": "1.2.0",
+ "author": "John Doe",
+ "title": "Episode 7 - Making Progress",
+ "podcastName": "John's Awesome Podcast",
+ "chapters": [
+ {
+ "startTime": 0,
+ "title": "Intro"
+ },
+ {
+ "startTime": 168,
+ "title": "Hearing Aids",
+ "hasArtwork": "chapter1.jpg"
+ },
+ {
+ "startTime": 260,
+ "title": "Progress Report"
+ },
+ {
+ "startTime": 410,
+ "title": "Namespace",
+ "img": "https://example.com/images/namepsace_example.jpg",
+ "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"
+ },
+ {
+ "startTime": 4826,
+ "img": "https://example.com/images/parisfrance.jpg",
+ "toc": false,
+ "location": {
+ "name": "Eiffel Tower, Paris",
+ "geo": "geo:42.3417649,-70.9661596"
+ }
+ },
+ {
+ "startTime": 5510,
+ "title": "The Big Players"
+ },
+ {
+ "startTime": 5854,
+ "title": "Spread the Word"
+ },
+ {
+ "startTime": 6089,
+ "title": "Outro"
+ }
+ ]
}
```
@@ -206,6 +205,6 @@ chapter list, but allows for different artwork to be shown:
## 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
+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.