Matroska Element Ordering
With the exceptions of the EBML Header
and the CRC-32
element, the EBML specification [@!RFC8794] does not require any
particular storage order for elements. However, this specification defines
mandates and recommendations for ordering certain elements to facilitate
better playback, seeking, and editing efficiency. This section describes and
offers rationale for ordering requirements and recommendations for
Matroska.
Top-Level Elements
The Info
element is the only REQUIRED Top-Level Element
in a Matroska file.
To be playable, Matroska MUST also contain at least one Tracks
element and Cluster
element.
The first Info
element and the first Tracks
element either MUST be stored before the first
Cluster
element or SHALL both be referenced by a SeekHead
element occurring before the first Cluster
element.
All Top-Level Elements
MUST use a 4-octet EBML Element ID.
When using Medium Linking, chapters are used to reference other Segments
to play in a given order (see (#medium-linking)).
A Segment
containing these Linked Chapters
does not require a Tracks
element or a Cluster
element.
It is possible to edit a Matroska file after it has been created. For
example, chapters, tags, or attachments can be added. When new Top-Level Elements
are added to a Matroska file, the SeekHead
element(s)
MUST be updated so that the SeekHead
element(s)
itemizes the identity and position of all Top-Level Elements
.
Editing, removing, or adding elements to a Matroska file often requires
that some existing elements be voided or extended. Transforming the existing
elements into Void
elements as padding can be used as a method to
avoid moving large amounts of data around.
CRC-32
As noted by the EBML specification [@!RFC8794], if a CRC-32
element is used, then the CRC-32
element
MUST be the first ordered element within its Parent Element
.
In Matroska, all Top-Level Elements
of an EBML Document SHOULD include a CRC-32
element
as their first Child Element
.
The Segment
element, which is the Root Element
, SHOULD NOT have a CRC-32
element.
SeekHead
If used, the first SeekHead
element MUST be the first non-CRC-32 Child
element
of the Segment
element. If a second SeekHead
element is used, then the first
SeekHead
element MUST reference the identity and position of the second SeekHead
element.
Additionally, the second SeekHead
element MUST only reference Cluster
elements
and not any other Top-Level Element
already contained within the first SeekHead
element.
The second SeekHead
element MAY be stored in any order relative to the other Top-Level Elements
.
Whether one or two SeekHead
elements are used, the SeekHead
element(s) MUST
collectively reference the identity and position of all Top-Level Elements
except
for the first SeekHead
element.
Cues (Index)
The Cues
element is RECOMMENDED to optimize seeking access in Matroska. It is
programmatically simpler to add the Cues
element after all Cluster
elements
have been written because this does not require a prediction of how much space to
reserve before writing the Cluster
elements. However, storing the Cues
element
before the Cluster
elements can provide some seeking advantages. If the Cues
element
is present, then it SHOULD either be stored before the first Cluster
element
or be referenced by a SeekHead
element.
Info
The first Info
element SHOULD occur before the first Tracks
element and first
Cluster
element except when referenced by a SeekHead
element.
Chapters Element
The Chapters
element SHOULD be placed before the Cluster
element(s). The
Chapters
element can be used during playback even if the user does not need to seek.
It immediately gives the user information about what section is being read and what
other sections are available.
In the case of Ordered Chapters
, it is RECOMMENDED to evaluate
the logical linking before playing. The Chapters
element SHOULD be placed before
the first Tracks
element and after the first Info
element.
Attachments
The Attachments
element is not intended to be used by default when playing the file
but could contain information relevant to the content, such as cover art or fonts.
Cover art is useful even before the file is played, and fonts could be needed before playback
starts for the initialization of subtitles. The Attachments
element MAY be placed before
the first Cluster
element; however, if the Attachments
element is likely to be edited,
then it SHOULD be placed after the last Cluster
element.
Tags
The Tags
element is most subject to changes after the file was originally created.
For easier editing, the Tags
element can be placed at the end of the Segment
element,
even after the Attachments
element. On the other hand, it is inconvenient to have to
seek in the Segment
for tags, especially for network streams; thus, it’s better if the
Tags
element is found early in the stream. When editing the Tags
element, the original
Tags
element at the beginning can be overwritten with a Void
element and a
new Tags
element written at the end of the Segment
element. The file and Segment
sizes will only marginally change.