Podcasting 2.0 · chapters

Chapters JSON generator.

Turn a list of timestamps into a valid chapters file, checked for negative and duplicate times and sorted for you. Everything runs in your browser.

Format: JSON chapters 1.2.0 (spec dated 15 April 2021), checked 30 September 2026Nothing is uploaded

Advertisement

Chapters

Format: startTime | title | url | img. Time can be seconds (94.5), mm:ss or h:mm:ss. Only startTime is required by the spec; leave url and img empty to skip them.

Result

Add at least one chapter to see the JSON.

Advertisement

How it works

The file follows the Podcast Index JSON chapters format, version 1.2.0. It has a required version and chapters array; each chapter needs only a startTime in seconds, with optional title, img and url. The spec assumes chapters are in ascending order of startTime, so this tool sorts them and reports any two chapters that share a start time or use a negative one.

This tool checks the structure against the published spec. It cannot tell whether your image and link addresses load, whether chapters match your audio, or whether a particular podcast app supports every field. Test the finished file in a player.

Host the JSON at a public address, serve it as application/json+chapters (the spec's recommended content type), and add the copied tag inside the episode's <item>. The feed's root element needs xmlns:podcast="https://podcastindex.org/namespace/1.0". The tag is optional per episode and allowed once per item.

Sources, all CC0: JSON chapters format · <podcast:chapters> tag · podcast.xsd

What a Podcasting 2.0 chapters file is

Chapters let a listener jump to the sections of an episode, and they can show a title, an image and a link for each one. The Podcast Index namespace publishes a JSON format for them. Instead of embedding chapter data inside the audio file as ID3 tags, you host a small JSON file at a public address and point to it from the episode in your RSS feed. The namespace documentation lists the benefits: chapters do not require altering the audio files, they can be edited after publishing because they are a separate file, they can be displayed by a wider range of players including web browsers, and images are fetched on playback instead of enlarging the audio file.

The anatomy of the file

The top-level object has two required properties: version, a string naming the format version, and chapters, an array. This generator writes version 1.2.0. Each chapter object has exactly one required attribute, startTime, a number of seconds that may include fractions. The optional attributes the tool writes are title, img (an image address) and url (a link). The specification defines further optional fields, for example toc to mark a chapter as metadata only, endTime, and a location object; this tool does not generate those, so add them by hand if you need them. The tool can also write top-level title, podcastName and author values.

How the tool turns your lines into JSON

  1. Each line is split on the vertical bar into startTime | title | url | img. Times can be seconds such as 94.5, mm:ss or h:mm:ss.
  2. Negative times and unreadable times are reported as errors, and links and images must be full http or https addresses.
  3. Rows are sorted by ascending start time, because the format assumes chapters are in order. If you typed them out of order you are told the output was reordered.
  4. Two chapters with the same start time are an error, since they cannot both begin at the same moment.
  5. A missing title is only a warning: the spec allows it, but listeners would see an unnamed chapter. A first chapter that starts after 0 seconds is also a warning, not an error.

Worked example

Take these lines: 0:00 | Intro, 2:48 | Hearing aids and 4:20 | Progress report. The tool converts 2:48 to 168 seconds and 4:20 to 260 seconds and produces a file with version 1.2.0 and three chapters at 0, 168 and 260. If you also type https://example.com/episode1/chapters.json as the hosting address, it produces the feed tag <podcast:chapters url="https://example.com/episode1/chapters.json" type="application/json+chapters" />. Upload the JSON to that address and paste the tag inside the episode’s <item>. Time values given as 1:02:30 become 3750 seconds.

Publishing checklist

Common mistakes

Using minutes where seconds are expected is the most frequent one: 2.48 is 2.48 seconds, not 2 minutes 48 seconds, so use the colon form. Others include timestamps beyond the real episode length, which this tool cannot know, pasting a relative image path that is not a full address, and forgetting to republish the feed after adding the tag. App support also varies: the format is a published specification, not a guarantee that every player shows every field, so test the apps your audience uses. For YouTube-style description chapters rather than a feed file, use the YouTube chapter validator.

Everything runs in your browser and nothing is uploaded; the tool also does not check whether your links and images load, or whether the chapters match your audio.

Frequently asked questions

What is a podcast chapters JSON file?

It is a separate JSON document, defined by the Podcast Index namespace, that lists the start time, and optionally the title, image and link, of each chapter in an episode. Players read it through a tag in your RSS feed instead of reading chapter data embedded in the audio.

Which version of the chapters format does this tool create?

It creates version 1.2.0, the Podcast Index JSON chapters version this page was built against. The spec requires only a version and a chapters array, with one required startTime per chapter.

How do I add the chapters file to my podcast RSS feed?

Host the JSON at a public address, then add a podcast:chapters tag with that URL and the type application/json+chapters inside the episode’s item. Declare the podcast namespace on the feed’s root element, and the tool prints the tag once you enter the hosted address.

Can chapters be in any order?

The format assumes chapters are in ascending order of start time. This tool sorts your rows for you and tells you if it had to reorder them, and it rejects two chapters that share the same start time.

Are titles, images and links required?

No. Only startTime is required for each chapter. A chapter without a title will appear unnamed to listeners, so the tool warns about it, and image and link addresses must be full http or https URLs when you supply them.

What MIME type should the chapters file use?

The specification says this type of file should be served with the content type application/json+chapters, and the same value goes in the type attribute of the feed tag.

Do all podcast apps support JSON chapters?

Support varies by app, so treat the file as a published specification rather than a guarantee. Test your episode in the players your listeners use before relying on any one field.

Sources and retrieval dates

Advertisement