This document is meant to explain how Chapters work in matroska, using examples.

Elements semantic

Element Name	Level	Class-ID	Mand.	Multi.	Range	Default	Element Type	Description
Chapters	1	[10][43][A7][70]	-	-	-	-	sub-elements	A system to define basic menus and partition data. For more detailed information, look at the Chapters Explanation.
EditionEntry	2	[45][B9]	*	*	-	-	sub-elements	Contains all information about a segment edition.
EditionUID	3	[45][BC]	-	-	> 0	-	u-integer	A unique ID to identify the edition. It's useful for tagging an edition.
EditionFlagHidden	3	[45][BD]	*	-	0-1	0	u-integer (1 bit)	If an edition is hidden (1), it should not be available to the user interface (but still to Control Tracks).
EditionFlagDefault	3	[45][DB]	*	-	0-1	0	u-integer (1 bit)	If a flag is set (1) the edition should be used as the default one.
EditionFlagOrdered	3	[45][DD]	-	-	0-1	0	u-integer (1 bit)	Specify if the chapters can be defined multiple times and the order to play them is enforced.
ChapterAtom	3+	[B6]	*	*	-	-	sub-elements	Contains the atom information to use as the chapter atom (apply to all tracks).
ChapterUID	4+	[73][C4]	*	-	> 0	-	u-integer	A unique ID to identify the Chapter.
ChapterTimeStart	4+	[91]	*	-	-	-	u-integer	Timecode of the start of Chapter (not scaled).
ChapterTimeEnd	4+	[92]	-	-	-	-	u-integer	Timecode of the end of Chapter (timecode excluded, not scaled).
ChapterFlagHidden	4+	[98]	*	-	0-1	0	u-integer (1 bit)	If a chapter is hidden (1), it should not be available to the user interface (but still to Control Tracks).
ChapterFlagEnabled	4+	[45][98]	*	-	0-1	1	u-integer (1 bit)	Specify wether the chapter is enabled. It can be enabled/disabled by a Control Track. When disabled, the movie should skip all the content between the TimeStart and TimeEnd of this chapter.
ChapterSegmentUID	4+	[6E][67]	-	-	>0	-	binary	A segment to play in place of this chapter. Edition ChapterSegmentEditionUID should be used for this segment, otherwise no edition is used.
ChapterSegmentEditionUID	4+	[6E][BC]	-	-	>> 0	-	binary	The edition to play from the segment linked in ChapterSegmentUID.
ChapterTrack	4+	[8F]	-	-	-	-	sub-elements	List of tracks on which the chapter applies. If this element is not present, all tracks apply
ChapterTrackNumber	5+	[89]	*	*	> 0	-	u-integer	UID of the Track to apply this chapter too. In the absense of a control track, choosing this chapter will select the listed Tracks and deselect unlisted tracks. Absense of this element indicates that the Chapter should be applied to any currently used Tracks.
ChapterDisplay	4+	[80]	-	*	-	-	sub-elements	Contains all possible strings to use for the chapter display.
ChapString	5+	[85]	*	-	-	-	UTF-8	Contains the string to use as the chapter atom.
ChapLanguage	5+	[43][7C]	*	*	-	eng	string	The languages corresponding to the string, in the bibliographic ISO-639-2 form.
ChapCountry	5+	[43][7E]	-	*	-	-	string	The countries corresponding to the string, same 2 octets as in Internet domains.
ChapProcess	4+	[69][44]	-	*	-	-	sub-elements	Contains all the commands associated to the Atom.
ChapProcessCodecID	5+	[69][55]	*	-	-	0	u-integer	Contains the type of the codec used for the processing. A value of 0 means native Matroska processing, a value of 1 means the DVD command set is used. More codec IDs can be added later.
ChapProcessPrivate	5+	[45][0D]	-	-	-	-	binary	Some optional data attached to the ChapProcessCodecID information. For ChapProcessCodecID = 1, it is the "DVD level" equivalent.
ChapProcessCommand	5+	[69][11]	-	*	-	-	sub-elements	Contains all the commands associated to the Atom.
ChapProcessTime	6+	[69][22]	*	-	-	-	u-integer	Defines when the process command should be handled (0: during the whole chapter, 1: before starting playback, 2: after playback of the chapter).
ChapProcessData	6+	[69][33]	*	-	-	-	binary	Contains the command information. The data should be interpreted depending on the ChapProcessCodecID value. For ChapProcessCodecID = 1, the data correspond to the binary DVD cell pre/post commands.

Example 1 : basic chaptering

In this example a movie is split in different chapters. It could also just be an audio file (album) on which each track corresponds to a chapter.

00000ms - 05000ms : Intro
05000ms - 25000ms : Before the crime
25000ms - 27500ms : The crime
27500ms - 38000ms : The killer arrested
38000ms - 43000ms : Credits

This would translate in the following matroska form :

Chapters
	EditionEntry
		ChapterAtom
			ChapterUID		0x123456
			ChapterTimeStart		0 ns
			ChapterTimeEnd		5,000,000 ns
			ChapterDisplay
				ChapterString	Intro
				ChapterLanguage	eng
		ChapterAtom
			ChapterUID		0x234567
			ChapterTimeStart		5,000,000 ns
			ChapterTimeEnd		25,000,000 ns
			ChapterDisplay
				ChapterString	Before the crime
				ChapterLanguage	eng
			ChapterDisplay
				ChapterString	Avant le crime
				ChapterLanguage	fra
		ChapterAtom
			ChapterUID		0x345678
			ChapterTimeStart		25,000,000 ns
			ChapterTimeEnd		27,500,000 ns
			ChapterDisplay
				ChapterString	The crime
				ChapterLanguage	eng
			ChapterDisplay
				ChapterString	Le crime
				ChapterLanguage	fra
		ChapterAtom
			ChapterUID		0x456789
			ChapterTimeStart		27,500,000 ns
			ChapterTimeEnd		38,000,000 ns
			ChapterDisplay
				ChapterString	After the crime
				ChapterLanguage	eng
			ChapterDisplay
				ChapterString	Après le crime
				ChapterLanguage	fra
		ChapterAtom
			ChapterUID		0x456789
			ChapterTimeStart		38,000,000 ns
			ChapterTimeEnd		43,000,000 ns
			ChapterDisplay
				ChapterString	Credits
				ChapterLanguage	eng
			ChapterDisplay
				ChapterString	Générique
				ChapterLanguage	fra

Example 2 : nested chapters

In this example an (existing) album is split into different chapters, and one of them contain another splitting.

The Micronauts "Bleep To Bleep"

00:00 - 12:28 : Baby Wants To Bleep/Rock
- 00:00 - 04:38 : Baby wants to bleep (pt.1)
- 04:38 - 07:12 : Baby wants to rock
- 07:12 - 10:33 : Baby wants to bleep (pt.2)
- 10:33 - 12:28 : Baby wants to bleep (pt.3)
12:30 - 19:38 : Bleeper_O+2
19:40 - 22:20 : Baby wants to bleep (pt.4)
22:22 - 25:18 : Bleep to bleep
25:20 - 33:35 : Baby wants to bleep (k)
33:37 - 44:28 : Bleeper

Chapters
	EditionEntry
		ChapterAtom
			ChapterUID			0x654321
			ChapterTimeStart			0 ns
			ChapterTimeEnd			748,000,000 ns
			ChapterDisplay
				ChapterString		Baby wants to bleep/rock
			ChapterAtom
				ChapterUID		0x123456
				ChapterTimeStart		0 ns
				ChapterTimeEnd		278,000,000 ns
				ChapterDisplay
					ChapterString	Baby wants to bleep (pt.1)
			ChapterAtom
				ChapterUID		0x234567
				ChapterTimeStart		278,000,000 ns
				ChapterTimeEnd		432,000,000 ns
				ChapterDisplay
					ChapterString	Baby wants to rock
			ChapterAtom
				ChapterUID		0x345678
				ChapterTimeStart		432,000,000 ns
				ChapterTimeEnd		633,000,000 ns
				ChapterDisplay
					ChapterString	Baby wants to bleep (pt.2)
			ChapterAtom
				ChapterUID		0x456789
				ChapterTimeStart		633,000,000 ns
				ChapterTimeEnd		748,000,000 ns
				ChapterDisplay
					ChapterString	Baby wants to bleep (pt.3)
		ChapterAtom
			ChapterUID			0x567890
			ChapterTimeStart			750,000,000 ns
			ChapterTimeEnd			1,178,500,000 ns
			ChapterDisplay
				ChapterString		Bleeper_O+2
		ChapterAtom
			ChapterUID			0x678901
			ChapterTimeStart			1,180,500,000 ns
			ChapterTimeEnd			1,340,000,000 ns
			ChapterDisplay
				ChapterString		Baby wants to bleep (pt.4)
		ChapterAtom
			ChapterUID			0x789012
			ChapterTimeStart			1,342,000,000 ns
			ChapterTimeEnd			1,518,000,000 ns
			ChapterDisplay
				ChapterString		Bleep to bleep
		ChapterAtom
			ChapterUID			0x890123
			ChapterTimeStart			1,520,000,000 ns
			ChapterTimeEnd			2,015,000,000 ns
			ChapterDisplay
				ChapterString		Baby wants to bleep (k)
		ChapterAtom
			ChapterUID			0x901234
			ChapterTimeStart			2,017,000,000 ns
			ChapterTimeEnd			2,668,000,000 ns
			ChapterDisplay
				ChapterString		Bleeper

The menu features are handled like a chapter codec. That means each codec has a type, some private data and some data in the chapters.

The type of the menu system is defined by the ChapProcessCodecID parameter. For now only 2 values are supported : 0 matroska script, 1 menu borrowed from the DVD. The private data depend on the type of menu system (stored in ChapProcessPrivate), idem for the data in the chapters (stored in ChapProcessData).

Matroska Script (0)

This is the case when ChapProcessCodecID = 0. This is a script language build for Matroska purposes. The inspiration comes from ActionScript, javascript and other similar scripting languages. The commands are stored as text commands, in UTF-8. The syntax is C like, with commands spanned on many lines, each terminating with a ";". You can also include comments at the end of lines with "//" or comment many lines using "/* */". The scripts are stored in ChapProcessData. For the moment ChapProcessPrivate is not used.

The one and only command existing for the moment is GotoAndPlay( ChapterUID );. As the same suggests, it means that when this command is encountered, the playback should jump to the Chapter specified by the UID and play it.

DVD menu (1)

This is the case when ChapProcessCodecID = 1. Each level of a chapter corresponds to a logical level in the DVD system that is stored in the first octet of the ChapProcessPrivate. This DVD hierarchy is as follows:

ChapProcessPrivate	DVD Name	Hierarchy						Commands Possible	Comment
0x30	SS	DVD domain						-	First Play, Video Manager, Video Title
0x2A	LU	Language Unit						-	Contains only PGCs
0x28	TT	Title						-	Contains only PGCs
0x20	PGC	Program Group Chain (PGC)						*
0x18	PG	Program 1			Program 2	Program 3		-
0x10	PTT	Part Of Title 1				Part Of Title 2		-	Equivalent to the chapters on the sleeve.
0x08	CN	Cell 1	Cell 2	Cell 3	Cell 4	Cell 5	Cell 6	-

You can also recover wether a Segment is a Video Manager (VMG), Video Title Set (VTS) or Video Title Set Menu (VTSM) from the ChapterTranslateID element found in the Segment Info. This field uses 2 octets as follows:

Domain Type: 0 for VMG, the domain number for VTS and VTSM
Domain Value: 0 for VMG and VTSM, 1 for the VTS source.

For instance, the menu part from VTS_01_0.VOB would be coded [1,0] and the content part from VTS_02_3.VOB would be [2,1]. The VMG is always [0,0]

The following octets of ChapProcessPrivate are as follows:

Octet 1	DVD Name	Following Octets
0x30	SS	Domain name code (1: 0x00= First play, 0xC0= VMG, 0x40= VTSM, 0x80= VTS) + VTS(M) number (2)
0x2A	LU	Language code (2) + Language extension (1)
0x28	TT	global Title number (2) + corresponding TTN of the VTS (1)
0x20	PGC	PGC number (2) + Playback Type (1) + Disabled User Operations (4)
0x18	PG	Program number (2)
0x10	PTT	PTT-chapter number (1)
0x08	CN	Cell number [VOB ID(2)][Cell ID(1)][Angle Num(1)]

If the level specified in ChapProcessPrivate is a PGC (0x20), there is an octet called the Playback Type, specifying the kind of PGC defined:

0x00: entry only/basic PGC
0x82: Title+Entry Menu (only found in the Video Manager domain)
0x83: Root Menu (only found in the VTSM domain)
0x84: Subpicture Menu (only found in the VTSM domain)
0x85: Audio Menu (only found in the VTSM domain)
0x86: Angle Menu (only found in the VTSM domain)
0x87: Chapter Menu (only found in the VTSM domain)

The next 4 following octets correspond to the User Operation flags in the standard PGC. When a bit is set, the command should be disabled.

ChapProcessData contains the pre/post/cell commands in binary format as there are stored on a DVD. There is just an octet preceeding these data to specify the number of commands in the element. As follows: [# of commands(1)][command 1 (8)][command 2 (8)][command 3 (8)].

More information on the DVD commands and format on DVD-replica, where we got most of the info about it. You can also get information on DVD from the DVDinfo project.

Main Menu

Contact