Podlove Simple Chapters

Podlove Simple Chapters

Podlove Simple Chapters is an XML 1.0 based format meant to extend file formats like Atom Syndication [1] and RSS 2.0 [2] that reference enclosures (podcasts). As the name implies, this format defines simple chapter structures in media files.

Change Log

2013-05-18: Removed Atom Example. Fixed some typos.
2013-03-31: Replaced time format spec with Normal Play Time
2012-11-18: Add option to link external file in feed.
            XML namespace prefix changed to "psc:"
            Added optional image attribute, bumped spec to version 1.1
2012-03-26: 1.0 - Initial Release

Motivation and Scope

Chapters are an increasingly asked-for feature for long media files. Talk shows and interviews spanning multiple hours and addressing lots of different topics are very common these days and chapters make things easier for the listener to either fast forward to certain topics or to recap stuff already listened to.

However, chapter marks are currently only available in MPEG–4 media files, the only “standard” being Apple’s way of tagging media files that has been reengineered by some developers but is still officially undocumented. Chapter marks are also supported in MP3 [3] and Ogg [4] media files but support for these is close to nonexistent.

Placing the information in podcast feeds not only allows easy extraction of chapter information for podcast clients regardless of the media file types in use, but also enables systems to display this information before the media files themselves have been downloaded.

Simple Chapters does not try to be a comprehensive solution for all kinds of possible timeline meta data. It neither allows links to be placed independent from chapters nor does it reference images in the timeline (both features that would be supported by popular media players like iPod or iPhone).

The format simply expresses a straightforward, non-hierarchical linear structure by linking chapter titles and an optional hypertext reference to specific points in time. It is intended to be easy to author, easy to parse and easy to present to the user.

XML Namespace

The XML namespace URI for this format is

http://podlove.org/simple-chapters/

Please note: Examples included here use the namespace prefix “psc:” but the XML standard allows you to use any namespace prefix you prefer.

Structure

The Simple Chapters specification defines two elements: <psc:chapters> and <psc:chapter>.

<psc:chapters>

The <psc:chapters> element defines a simple chapter list within an <atom:entry> element in an Atom [1] feed or within an <item> element within an RSS 2.0 [2] channel.

There must be only one <psc:chapters> element. Clients should ignore extra <psc:chapters> elements. The <psc:chapters> elements contains one or more <psc:chapter> elements.

The <psc:chapters> element accepts one attribute:

version=“number”
Specifies the version of this specification (current version is 1.1). This enables future enhancements of this standard. This attribute is optional and defaults to “1.0”.

<psc:chapter>

The <psc:chapter> element defines a single chapter mark within an associated media file. It does so by stating the absolute time. It does not contain any media file dependent links to specific byte ranges within that file.

The <psc:chapter> element accepts the following attributes:

start="time"
Refers to a single point in time relative to the beginning of the media file. The syntax of time is defined below. This attribute is mandatory.
title="name"
Defines name to be the title of the chapter. The title could be any length, but authors should consider the titles to be displayed on small devices with limited screen estate. Also, shorter titles are easier to grasp. This attribute is mandatory.
href="link"
This is an additional hypertext reference as an extension of the title that refers to a resource that provides related information. This link should be presented to the user only in context with the chapter and it’s title. This attribute is optional.
image="url"
This is an URL pointing to an image to be associated with the chapter. This attribute is optional.

The list of <psc:chapter> elements within an <psc:chapters> element should be in the order of the value of their time attribute but clients must be able to  resort the list based on time when presenting it to the user.

Time

The time is expressed in Normal Play Time [5] which allows for a flexible input of time markers.

Here are some examples that show how the time field can be used:

01:35:52
1 hour 35 minutes 52 seconds
7:48
7 minutes, 48 seconds
35:12.250
35 minutes, 12 seconds, 250 ms
05:12:03.5
5 hours, 12 minutes, 3 seconds, 500 ms
37
37 seconds

Embedding Example

This is an simple example of a RSS podcast feed with embedded chapter information in Podlove Simple Chapter format:

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
    <channel>
        <title>Podlove Podcast</title>
        <atom:link type="text/html" href="http://podlove.org/" />

        <item>
            <title>Fiat Lux</title>
            <link href="http://podlove.org/podcast/1"/>
            <guid isPermaLink="false">urn:uuid:3241ace2-ca21-dd12-2341-1412ce31fad2</guid>
            <pubDate>Fri, 23 Mar 2012 23:25:19 +0000</pubDate>
            <description>First episode</description>
            <link rel="enclosure" type="audio/mpeg" length="12345" href="http://podlove.org/files/fiatlux.mp3"/>

            <!-- specify chapter information -->
            <psc:chapters version="1.2" xmlns:psc="http://podlove.org/simple-chapters">
                <psc:chapter start="0" title="Welcome" />
                <psc:chapter start="3:07" title="Introducing Podlove" href="http://podlove.org/" />
                <psc:chapter start="8:26.250" title="Podlove WordPress Plugin" href="http://podlove.org/podlove-podcast-publisher" />
                <psc:chapter start="12:42" title="Resumée" />
            </psc:chapters>
        </item>
    </channel>
</feed>

External Chapter Information

Instead of embedding the chapter information as described above, you can also use an <atom:link> Element to link to an external resource containing the chapter information. If you want to do this, replace the chapter information in the examples above simply by including the following in the <feed> (Atom) or <channel> (RSS 2.0) element of the feed:

<atom:link rel="http://podlove.org/simple-chapters" href="http://podlove.org/examples/chapters.psc" />

This is especially practicable to keep the feed size down or in situations where feed and chapter information are generated and/or updated separately.

  1. The Atom Syndication Format: http://www.atomenabled.org/developers/syndication/atom-format-spec.php  ↩
  2. RSS 2.0 Specification: http://cyber.law.harvard.edu/rss/rss.html  ↩
  3.  ID3v2 Chapter Frame Addendum: http://www.id3.org/id3v2-chapters-1.0  ↩
  4. VorbisComment Chapter Extension: http://wiki.xiph.org/Chapter_Extension  ↩
  5. Media Fragments URI 1.0 (basic): Temporal Dimension http://www.w3.org/TR/media-frags/#naming-time  ↩

66 thoughts on “Podlove Simple Chapters”

  1. Great Idea! – I am a fan of the argument pro separate file description to have the information about what will be in the file without having to download it. Hope that many podcast supporting implementations will include that definition to get a wide standard.
    Keep the whole project rolling in that sense!

    nx

    Reply ↓

  2. “The element accepts one attribute:”
    should be
    “The element accepts one attribute:”

    Here is a machine readable definition of it (DTD):

    Reply ↓

  4. little mistakes:
    Time-Exaples should be:
    – 7 minutes, 48 seconds
    – 35 minutes, 12 seconds, 250 milliseconds
    __________________________________________
    was this:
    01:35:62 – 1 hour 35 minutes 62 seconds
    07:48 – 7 minutes
    35:12.250 – 35 minutes, 12 minutes, 250 milliseconds
    05:12:03.500 – 5 hours, 12 minutes, 3 seconds, 500 milliseconds
    37 – 37 seconds

    Reply ↓

  5. I hate to bloat this nice and simple specification, but I’ve got 2 small comments:

    1) What will happen if more than one uses the same start time code? Either the specification should explicitly say that this is an error and clients are free to do whatever they like or it should define an error handling mechanism.

    2) I can imagine some (rare) cases where one would like to specify a language (e.g. for language specific reference links). If multiple sc:chapters were allowed with different xml:lang attributes, then a language sensitive reader could select the appropriate chapters listing for a user-specified languages. If the fallback would be the very first sc:chapters element, then this even would be compatible with the current specification.

    Reply ↓

    • You bring up interesting points

      1) I think this should be avoided and we can put this in the spec. I’d say the client behavior is undefined.
      2) A recording usually has a defined language and I’d assume chapter titles to be in the same language. So does it really make sense to provide alternative names in another language that isn’t really spoken in the recording? I don’t think so.

      Keep in mind we want this spec to be really, really simple. That’s why it’s called Simple Chapters.

      Reply ↓

  6. I once made up chapter marks for a couple of mobilemacs.de episodes and while doing that I found myself wanting a possibility of setting an end time for a chapter.
    I often simply couldn’t come up with a good chapter name for a certain “time span” in the media file and therefore wanted to let this area “unchaptered”, which is not possible when there is only a start time to set.

    I propose to extend the spec with this addendum to the -attributes section:

    end=”time“
    Refers to a single point in time relative to the beginning of the media file. The syntax of time is defined below. This attribute defines the end point for the chapter. This attribute is optional.

    Also, I propose to extend the spec in order to make clear for clients what to do with time spans that are “unchaptered” (which can also happen without an “end” attribute; eg. when only one chapter is set from the middle of the file to the end of it).

    Reply ↓

    • Hi!
      It seems plausible to not-mark the probably not interesting parts, but if I have got content between the chapters, how do I jump to that point in time whre a boring chapter ends an the content builds up before the next chapter.. by jumping to the next chapter i would miss the unchapterd content, which could be interesting to me anyway…
      On Live Albums (music) there are tracks like “moderation” etc., so I would suggest to name the parts you dont want to categorize with some analog name -> interludium :)

      If a “end” would be introduced, also all players have to adept, and bring up a separation between “next chapter” and “end of this chapter” – which is more confusing and overloading than helping imho.

      Reply ↓

      • Per default, an audio player should handle an unchaptered area like a chaptered one – If you click “next”, jump to the beginning of the unchaptered area.
        I could also think of situations where it would be better to always jump to the next “real” chapter, eg. when the unchaptered area is simply 30 seconds of silence or noise.
        I would use an unchaptered area either for noise and silence or for areas where the “tagger” can’t come up with a good name for the chapter.
        (In the MobileMacs podcast, the speakers would often wander from one topic to another or sometimes into nowhere and I could neither find a good point to separate between two chapters nor could I find a fitting chapter name. I then tagged from the moment of the moderator saying “Now we go to the next topic: …”, but I had always a few minutes of meandering in the last chapter.)

        Reply ↓

  7. I think we need to go deeper: a chapter inside a chapter.

    Wouldn’t be that hard to add it, regarding that we’re dealing with XML here: a chapter in a chapter is represented by an sc:chapter-element inside another sc:chapter-element. The attributes would be exactly the same.
    I don’t know about an audio file format that supports nested chapters, so this simple chapter format would be a pioneer, but I think the need for them is definitely there. (For example you could have a topic and could then tag the topic with a top-level chapter, tag the intro to the topic with a subchapter inside the topic chapter, then subchapters until you get to the outro-subchapter.)

    Also, I would recommend that audio players that crash inside a subchapter continue in the parent chapter. (Yes, this was another Inception joke, sorry.)

    Reply ↓

    • I hear you complaints but I want to remember you about one thing: this is the _simple_ chapter specification. It won’t be the last. It’s a quick and easy solution for podcasts that have their content structured in a simple and straightforwatd way. There are not many podcasts doing chapters right now, but those who provide chapters have usually a simple, flat layout and have all areas covered.

      The intention of this spec is to make it easy to integrate these kinds of chapters in feed so that the information is independent from the media file and can be displayed before any media file is actually loaded.

      Things like sub-chapters, open-ended chapters and many, many more things have been discussed on the recent Podlove Developer Meeting but we decided to put all this in the big “episode manifest” file format we are working on.

      Meanwhile, Simple Chapters should encourage both podcasters and client developers to think about chapters at all. Once the concepts of a structured timeline is in the heads and the programs, we can move on. If we make it too complicated from the start there will be a steep implementation hurdle that many won’t pass initially blocking general progress.

      Reply ↓

  8. I did some work on the my app “Simple Chapters”. Check out https://github.com/schultyy/Simple-Chapters

    Current status:
    I changed the UI layout, there is an detail view at the right instead of an sheet. Now you are able to add chapter marks to an episode and save them, but the app is not able to read them from xml at the moment. That is the next task I want to work on.

    Reply ↓

  9. Hi Podlove people,

    Does anyone have any tips as to how to get the chapters working as links?
    Right now, clicking on the chapter name does not cause the player to jump to the correct place. It seems to do nothing at all.

    Any tips would be welcome!!

    Joel, Radio Spaetkauf, Berlin

    Reply ↓

  12. Pingback: Zu Podlove Simple Chapters | Die Welt ist gar nicht so.

  14. Pingback: der firtz geht um | die Hörsuppe

  15. Just need a MIME-type for my project, I’d guess it’s just application/xml but maybe you want to define a more specific one?

    Reply ↓

    • Good point. We haven’t thought about that yet. I guess you’ll be safe by returning “application/xml” for now. We’ll discuss how to deal with this later on.

      Reply ↓

  16. I’m the maintainer of the feedparser project and after accepting a code submission for psc support I’ve now received a bug report that a feed is causing a crash. Upon investigating it appears that the code is broken because it’s checking for psc version 1.1, while the feed is using 1.0.

    While there may not be an incompatibility between 1.0 and 1.1 in this particular case I’ve discovered that three different versions have been released but there appears to be no way to review the previous versions. Developers such as myself must have access to previous versions of the spec.

    Can you please post versions 1.0 and 1.1 (and so on as the specification changes) so that developers can correctly handle feeds that use the old versions? As it stands I cannot move forward with a fix because I cannot ensure that the code will match the 1.0 and 1.1 specification correctly.

    Thanks for your help!

    Reply ↓

  17. Are you aware that by referencing Normal Play Time you’ve introduced the requirement that clients must now handle start and end times? The format for npt is:

    npttimedef = [ deftimeformat “:”] ( npttime [ “,” npttime ] ) / ( “,” npttime )

    so now clients must be able to handle all of the following literals:

    npt:10 # start=10 seconds
    10 # start=10 seconds
    10,20 # start=10 seconds, end=20 seconds
    ,20 # start=0 seconds, end=20 seconds
    npt:0:02:00,130.007 # start=120 seconds, end=130 seconds, 7 milliseconds

    I know that this will address concerns elsewhere in the comments (specifically the request to add an ‘end’ attribute) but my opinion is that referencing the Media Fragments spec has complicated the psc spec, so I wanted to ask if that was intentional.

    Reply ↓

  19. The “Embedding Example” section has three small errors:

    1. & 2.) Two typos in both introductions starting with “This is an simple example of…”: I’m no native speaker but I think “an” should be changed to “a”.

    3.) The second example states it is an Atom example, too, but in fact it is RSS.

    Reply ↓

  20. Pingback: Auphonic Blog: Chapter Marks for MP3, MP4 Audio and Vorbis Comment (Enhanced Podcasts)

  21. Sehr schön. Ich freue mich schon auf eine flächendeckende Verbreitung des standards.

    Btw: Im Beispiel-Feed sollte zumindestens eines der Chapter ein Image attribut aufweisen.

    Ansonsten.. meine Implementation von PSC ist fertig :).

    …Jetzt müssen sich nurnoch die Podcastpublizisten überwinden die nötigen Metadaten zusammen zutragen und auszuliefern.
    Außer Tim macht das nämlich noch niemand.

    Reply ↓

    • It is an URI, not a URL. Feed Validator simply does not “know” about this namespace. But it could if it want to do so.

      in general I dislike this error message as XML is generally extensible via namespaces and it is not an error to do so.

      Reply ↓

  23. Hey

    to provide an easy start into Chaptermarks I’ve built this simple HTML/Javascript based application: https://github.com/jpraetorius/chaptertool (directly usable here: http://jpraetorius.github.io/chaptertool/index.html) which allows a user to create chaptermarks while listening (or better – the producer while recording) simply by repeatedly clicking the button on the page. When the show is finished you simply add some more comments and then get the data in your preferred format (PSC, Auphonic, Shownotes) for download and local usage.

    I hope it is helpful for one or the other project that doesn’t have the active community of live-shownotes writers.

    Reply ↓

  24. Pingback: Podlove | Metaebene Personal Media

  25. Pingback: Simple Chapter Specification | Podlove

  26. Pingback: Podlove Simple Chapters 1.2 | Podlove

  28. Pingback: Podcast Addict mit Flattr-Integration - Herr Thees

  29. Something about the version number is odd. It says in the specification that the current version is 1.1, but the embedding example uses version 1.2.

    Is there a changelog where I can follow the version differences in detail?

    Reply ↓
Add Comment Register

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>