Declared ID3v2 frames

The following frames are declared in this document.

3.1 CHAP Chapter
3.2 CTOC Table of contents

1. Chapter frame

The purpose of this frame is to describe a single chapter within an audio file. There may be more than one frame of this type in a tag but each must have an Element ID that is unique with respect to any other "CHAP" frame or "CTOC" frame in the tag.

<ID3v2.3 or ID3v2.4 frame header, ID: "CHAP">           (10 bytes)
Element ID      <text string> $00
Start time      $xx xx xx xx
End time        $xx xx xx xx
Start offset    $xx xx xx xx
End offset      $xx xx xx xx
<Optional embedded sub-frames>

The Element ID uniquely identifies the frame. It is not intended to be human readable and should not be presented to the end user.

The Start and End times are a count in milliseconds from the beginning of the file to the start and end of the chapter respectively.

The Start offset is a zero-based count of bytes from the beginning of the file to the first byte of the first audio frame in the chapter. If these bytes are all set to 0xFF then the value should be ignored and the start time value should be utilized.

The End offset is a zero-based count of bytes from the beginning of the file to the first byte of the audio frame following the end of the chapter. If these bytes are all set to 0xFF then the value should be ignored and the end time value should be utilized.

There then follows a sequence of optional frames that are embedded within the "CHAP" frame and which describe the content of the chapter (e.g. a "TIT2" frame representing the chapter name) or provide related material such as URLs and images. These sub-frames are contained within the bounds of the "CHAP" frame as signalled by the size field in the "CHAP" frame header. If a parser does not recognise "CHAP" frames it can skip them using the size field in the frame header. When it does this it will skip any embedded sub-frames carried within the frame.

Figure 1 shows an example of a "CHAP" frame containing two embedded sub-frames. The first is a "TIT2" sub-frame providing the chapter name; "Chapter 1 - Loomings". The second is a "TIT3" sub-frame providing a description of the chapter; "Anticipation of the hunt".

CHAPFrame-1.0.png Figure 1: Example CHAP frame

2. Table of contents frame

The purpose of "CTOC" frames is to allow a table of contents to be defined. In the simplest case, a single "CTOC" frame can be used to provide a flat (single-level) table of contents. However, multiple "CTOC" frames can also be used to define a hierarchical (multi-level) table of contents.

There may be more than one frame of this type in a tag but each must have an Element ID that is unique with respect to any other "CTOC" or "CHAP" frame in the tag.

Each "CTOC" frame represents one level or element of a table of contents by providing a list of Child Element IDs. These match the Element IDs of other "CHAP" and "CTOC" frames in the tag. {{{<ID3v2.3 or ID3v2.4 frame header, ID: "CTOC"> (10 bytes) Element ID <text string> $00 Flags %000000ab Entry count $xx (8-bit unsigned int) <Child Element ID list> <Optional embedded sub-frames> }}}

The Element ID uniquely identifies the frame. It is not intended to be human readable and should not be presented to the end-user.

Flag a - Top-level bit
This is set to 1 to identify the top-level "CTOC" frame. This frame is the root of the Table of Contents tree and is not a child of any other "CTOC" frame. Only one "CTOC" frame in an ID3v2 tag can have this bit set to 1. In all other "CTOC" frames this bit shall be set to 0.
Flag b - Ordered bit
This should be set to 1 if the entries in the Child Element ID list are ordered or set to 0 if they not are ordered. This provides a hint as to whether the elements should be played as a continuous ordered sequence or played individually. The Entry count is the number of entries in the Child Element ID list that follows and must be greater than zero. Each entry in the list consists of:

{{{Child Element ID <text string> $00

}}}

Figure 2 shows an example of a "CTOC" frame which references a sequence of chapters. It contains a single "TIT2" sub-frame which provides a name for this element of the table of contents; "Part 1".

CTOCFrame-1.0.png Figure 2: Example CTOC frame