Skip to content

Chapter timestamp clarifications #1015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Chapter timestamp clarifications #1015

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 15 additions & 26 deletions cellar-matroska/chapters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,48 +108,37 @@ The `ChapterAtom` is also called a `Chapter`.
`ChapterTimeStart` is the timestamp of the start of `Chapter` with nanosecond accuracy and is not scaled by `TimestampScale`.
For `Simple Chapters`, this is the position of the chapter markers in the timeline.

For `Simple Chapters`, the start timestamp **MUST** be greater than or equal to the start timestamp of the preceding `ChapterAtom`. Otherwise the Chapter **SHOULD** be ignored.

Copy link
Author

@pitdicker pitdicker Jun 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ordered Chapters are sorted by definition. I think the spec should note whether Simple Chapters should be sorted by the player, or are required to be sorted.

Copy link
Collaborator

@robUx4 robUx4 Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simple Chapters are not sorted. It's up to the player to reorder them if needed. And they should not be ignored if they are not ordered. This would break backward compatibility.

### ChapterTimeEnd
`ChapterTimeEnd` is the timestamp of the end of `Chapter`
with nanosecond accuracy and is not scaled by `TimestampScale`. The
timestamp defined by the `ChapterTimeEnd` is not part of the
`Chapter`. A `Matroska Player` calculates the duration of this
`Chapter` using the difference between the `ChapterTimeEnd` and
`ChapterTimeStart`. The end timestamp **MUST** be greater
than or equal to the start timestamp.

When the `ChapterTimeEnd` timestamp is equal to the `ChapterTimeStart` timestamp,
the timestamp is included in the `Chapter`. It can be useful to put markers in
a file or add chapter commands with ordered chapter commands without having to play anything;
see (#chapprocess-element).

Chapter | Start timestamp | End timestamp | Duration
:---------|:----------------|:--------------|:-----
Chapter 1 | 0 | 1000000000 | 1000000000
Chapter 2 | 1000000000 | 5000000000 | 4000000000
Chapter 3 | 6000000000 | 6000000000 | 0
Chapter 4 | 9000000000 | 8000000000 | Invalid (-1000000000)
Table: ChapterTimeEnd Usage Possibilities{#ChapterTimeEndUsage}
`Chapter`.

The end timestamp **MUST** be greater than or equal to the start timestamp.
Otherwise the end timestamp **SHOULD** be ignored.
Copy link
Author

@pitdicker pitdicker Jun 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can the spec say what to do if the MUST is not met?

Copy link
Collaborator

@robUx4 robUx4 Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It already says so in the element:

The value MUST be greater than or equal to the ChapterTimeStart of the same ChapterAtom.


For `Simple Chapters`, the end timestamp **MUST** be equal to or smaller than the start timestamp of the next ChapterAtom.
Otherwise the start timestamp of the next Chapter **SHOULD** be used as the end timestamp of this Chapter.
Copy link
Author

@pitdicker pitdicker Jun 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having overlapping timestamps on Simple Chapters that are on the same level (i.e. not nested) seems like something to avoid.

Copy link
Collaborator

@robUx4 robUx4 Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ChapterTimeEnd is not mandatory for Simple Chapters (non ordered). And even when it's there it's not really used. It's more informational. And overlapping chapters are OK in Simple Chapters. They are not used for playback. For example you could have a DJ mix where 2 songs overlap. You can mark each song independently (and tag anme).


Chapters with a duration of 0 are allowed, and might for example be used as markers such as bookmarks.
Copy link
Author

@pitdicker pitdicker Jun 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the ChapterTimeEnd timestamp is equal to the ChapterTimeStart timestamp, the timestamp is included in the Chapter.

The definition of a chapter as a half-open range seems quite natural. But I'm not sure what this was supposed to mean.

It can be useful to put markers in a file or add chapter commands with ordered chapter commands without having to play anything

Chapters already act as markers, but I can see how zero-length chapters could work as a different kind of marker. They would work more like points instead of segments.

To "add chapter commands with ordered chapter commands without having to play anything" is again not really an understandable sentence.

Copy link
Collaborator

@robUx4 robUx4 Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Chapter commands are only supported in Ordered Chapters. The 0 duration feature is supported there.


### Nested Chapters

A `ChapterAtom` element can contain other `ChapterAtom` elements.
That element is a `Parent Chapter`, and the `ChapterAtom` elements it contains are `Nested Chapters`.

`Nested Chapters` can be useful to tag small parts of a `Segment` that already have tags or
add Chapter Codec commands on smaller parts of a `Segment` that already have Chapter Codec commands.

The `ChapterTimeStart` of a `Nested Chapter` **MUST** be greater than or equal to the `ChapterTimeStart` of its `Parent Chapter`.

If the `Parent Chapter` of a `Nested Chapter` has a `ChapterTimeEnd`, the `ChapterTimeStart` of that `Nested Chapter`
**MUST** be smaller than or equal to the `ChapterTimeEnd` of the `Parent Chapter`.
For `Simple Chapters`, the `ChapterTimeStart` of a `Nested Chapter` **MUST** be greater than or equal to the `ChapterTimeStart` of its `Parent Chapter`, and it **MUST** be smaller than the end timestamp of the `Parent Chapter`.
Otherwise the Nested Chapter **SHOULD** be ignored.
Copy link
Author

@pitdicker pitdicker Jun 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ChapterTimeStart of a Nested Chapter should fall within the duration of its Parent Chapter, whether the Parent Chapter has an explicit ChapterTimeEnd or an implicit end timestamp because of the next chapter.

Also I don't think the start timestamp of the Nested Chapter should be allowed to be equal to the end timestamp of the parent chapter, because the definition of the ChapterTimeEnd element says: "Timestamp of the end of Chapter (timestamp excluded)".

Copy link
Collaborator

@robUx4 robUx4 Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Simple Chapters there is no mandatory duration for a Chapter. So there can't be a rule around that.


### Nested Chapters in Ordered Chapters

The `ChapterTimeEnd` of the lowest level of `Nested Chapters` **MUST** be set for `Ordered Chapters`.

When used with `Ordered Chapters`, the `ChapterTimeEnd` value of a `Parent Chapter` is useless for playback,
When used with `Ordered Chapters`, the `ChapterTimeStart` and `ChapterTimeEnd` values of a `Parent Chapter` **MUST** be ignored for playback,
as the proper playback sections are described in its `Nested Chapters`.
The `ChapterTimeEnd` **SHOULD NOT** be set in `Parent Chapters` and **MUST** be ignored for playback.
The `ChapterTimeStart` of the `Parent Chapter` **SHOULD** be equal to that of its first `Nested Chapter`, and the `ChapterTimeEnd` of the `Parent Chapter` **SHOULD NOT** be set.
Copy link
Author

@pitdicker pitdicker Jun 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems to me with Ordered Chapters not only the ChapterTimeEnd of a Parent Chapter becomes meaningless with Nested Chapters, but also the ChapterTimeStart.

Copy link
Collaborator

@robUx4 robUx4 Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can have multiple chapters inside a parent chapter. In Ordered Chapters they just cannot start at the same time (as the parent).


### ChapterFlagHidden

Expand Down