Subject: [Cellar] Matroska Ordering Guidelines

From: Dave Rice <[email-masked]>
Date: Sat, 27 Feb 2016 16:02:10 -0500

Hi all,
I'm reviewing the documentation at https://matroska.org/technical/order/index.html <https://matroska.org/technical/order/index.html> and have some questions and comments.

The Order Guidelines say
> Matroska only needs a few level 1 elements to be playable: Segment Info, Track Info, Clusters. These elements have to be present in a Matroska file.

However, the specdata.xml lists Info as the only mandatory Level 1 Matroska Element. From specdata.xml it appears that a Matroska can be valid even without Tracks or Clusters Level 1 Elements. So are Level 1 Track and Cluster elements mandatory or not. Should there be a distinction between a “playable Matroska” and a “non-playable Matroksa”?

This sentence:
> All the other elements can be omitted although Cues (index) improve the playback experience greatly.

seems far too broad. I suspect that it should be "All the other Level 1 elements...".

Regarding,
> After a Matroska file has been created it may still be edited. For example chapters, tags or cover art attachments can be added. To do that the Meta Seek needs to be updated and also some elements may be voided or extended.

These sentences imply that if Chapters, Tags, or Attachments are aded then MetaSeek is mandatory, but is this true? Also IIRC MetaSeek doesn't need to reference all Level 1 elements, so Attachments could be added without creating or updating MetaSeek?

Regarding,
> When 1 Meta Seek Head is present, it should be the first element in a Segment…

Is this true? If MetaSeek is present a MetaSeek element MUST be the first element of the Segment? This conflicts with the rules for CRC which must also be first.

Regarding:
> The second Meta Seek is placed at the end and contains a lengthy list of all Clusters (and not the other level 1 elements).

To clarify if a second MetaSeek is used under Segment than it must be the last element of the Segment? If the second MetaSeek is used it can only reference Clusters and not any other level 1 element? I thought that a second MetaSeek could be used to list any other type of level 1 element that didn't fit in the first existing MetaSeek to avoid rewrites. Which is true? Also is a third or greater MetaSeek element ever allowed?

Regarding
> Placing the first Meta Seek Head other than the first position of the Segment would make it a lot less useful So it <em>must</em> be the first element of a Cluster.

I think this should read "be the first element of a Cluster”, right?

Regarding:
> So the Cues <em>should</em> always be written after the Clusters. However the <a href="#cues_front">Cues could also appear at the front</a>.

I'm confused by the way this is written. In what cases should Cues be written before or after Cluster?

Overall the documentation seems to suggest that multiple different elements all belong at the "end". Does the "end" mean "the last Level 1 element" or simply "after the last Cluster element”?

Best Regards,
Dave Rice

---

From: Moritz Bunkus <[email-masked]>
Date: Sun, 28 Feb 2016 12:28:00 +0100

Hey,

> I'm reviewing the documentation at
> https://matroska.org/technical/order/index.html
> <https://matroska.org/technical/order/index.html> and have some
> questions and comments.

Great, thanks! Keep in mind that these guidelines have never meant to be
read with the usual RFC terms regarding SHOULD, MUST, MAY etc.

> The Order Guidelines say
> > Matroska only needs a few level 1 elements to be playable: Segment
> > Info, Track Info, Clusters. These elements have to be present in a
> > Matroska file.

Well, the focus was on something that can be played back. Files without
Tracks and Clusters are valid, though, e.g. a file that only contains
chapters. It cannot be played back but it may be used as an additional
resource when playing other files or as an intermediate result during
muxing operations.

I don't want different requirements for »playable Matroska« and
»non-playable Matroska«. Having Info mandatory and the rest not is as it
should be. The guidelines should be re-worked considerably to reflect
that.

> seems far too broad. I suspect that it should be "All the other Level

True.

> Regarding,
> > After a Matroska file has been created it may still be edited. For
> > example chapters, tags or cover art attachments can be added. To do
> > that the Meta Seek needs to be updated and also some elements may be
> > voided or extended.
>
> These sentences imply that if Chapters, Tags, or Attachments are aded
> then MetaSeek is mandatory, but is this true? Also IIRC MetaSeek
> doesn't need to reference all Level 1 elements, so Attachments could
> be added without creating or updating MetaSeek?

No, a MetaSeek is not required in the sense that it MUST be present. The
sentence is a vague description of the process an editor implements so
that a player can always find the new or modified resources.

For example: if all attachments, chapters, tags are located before the
first cluster then no MetaSeek element is required at all. A player
that reads from the start to the first cluster can already find all
important level 1 elements without seeking.

If a MetaSeek element is present pointing to an already existing
Attachments element and that Attachments element is relocated then,
however, the editor MUST update the exiting entry in the MetaSeek
element to reflect the new position.

Another example. We only require players to be able to find elements in
two ways:

1. By reading linearly from start to the first cluster and using all
   elements found in the process (no seeking)

2. By using the information in all MetaSeek elements found by the
   method described in 1. (limitation: a player only has to follow one
   level of MetaSeek-to-MetaSeek link, no more).

We don't have similar requirements on editors, but what an editor
usually has to do in order for the elements to be found by players
derives directly from the requirements for players.

So an editor can write Attachments at the end of the file and not
include them in a MetaSeek. So far, so good. But it cannot expect all
players to find them in such a situation.

> Is this true? If MetaSeek is present a MetaSeek element MUST be the
> first element of the Segment? This conflicts with the rules for CRC
> which must also be first.

Think of it more along the lines of »should be the first level 1
element in a segment«. The intention is that all level 1 elements can be
found reading as few bytes as possible.

> Regarding:
> > The second Meta Seek is placed at the end and contains a lengthy
> > list of all Clusters (and not the other level 1 elements).
>
> To clarify if a second MetaSeek is used under Segment than it must be
> the last element of the Segment?

Nope. »At the end« simply behinds »after the clusters« which is usually
somewhere within the vicinity of the actual end of the file. The simple
reason is that it isn't known in advance how big such a MetaSeek element
will become. Therefore it doesn't make sense to reserve arbitrary
amounts of space before the clusters for this list.

The same applies to the Cues.

> If the second MetaSeek is used it can only reference Clusters and not
> any other level 1 element?

Nope, but that's usually how it's done. Remember, guidelines, not hard
rules. This is not a hard rule.

For example, mkvpropedit or my GUI's header editor will write MetaSeek
elements somewhere at the end referencing Attachments, Tracks etc. in
certain situations if it cannot place such a bit MetaSeek before the
clusters. In that case a minimal MetaSeek element is written before the
clusters pointing to that MetaSeek element behind the clusters.

That's OK – it's also a situation that an editor may find itself in
(modify only a few bytes of an existing file), but not usually a muxer
which can reserve enough space before the clusters (it re-writes the
whole file anyway).

> Regarding
> > Placing the first Meta Seek Head other than the first position of
> > the Segment would make it a lot less useful So it <em>must</em> be
> > the first element of a Cluster.
>

You mean »Segment«, I guess ;) Yes, »Cluster« is simply wrong in the
original sentence.

> > So the Cues <em>should</em> always be written after the
> > Clusters. However the <a href="#cues_front">Cues could also appear
> > at the front</a>.

> written before or after Cluster?

As I've said above Cues can become arbitrarily large and are therefore
often written at the end so that a muxer doesn't have to reserve huge
amounts of space at the front.

However, you can create a program that re-writes and optimizes a
Matroska file. In that case it already knows how many Cues there will be
and how much space is required for them. It can write the Cues at the
start.

> Overall the documentation seems to suggest that multiple different
> elements all belong at the "end". Does the "end" mean "the last Level
> 1 element" or simply "after the last Cluster element”?

The latter, »after the last Cluster element«.

Kind regards,
mosu

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 28 Feb 2016 15:58:19 +0100

>> seems far too broad. I suspect that it should be "All the other Level

Some are better than others. Tags are not going to improve much of
your playback experience.

> element to reflect the new position.

*existing.
Yes, it must be updated, but only if it exists. MetaSeek is not mandatory.

> found reading as few bytes as possible.

Yes, that's the first Matroska element. EBML parts obviously come first.

> rules. This is not a hard rule.

This raises a question. Do we want to enforce stricter rules in the
future ? If Matroska v5 has proper validator it may be a good
opportunity to add more "meta-rules" like these to ensure only nice
files are produced.

> and how much space is required for them. It can write the Cues at the

mkclean can do that. But most of the time muxers write Cues at the
end. For file streaming (via HTTP for example) it's better if it's at
the front as seeking is an expensive/slow operation (not so true in
HTTP 2.0). But for a muxer it's hard to do it in one pass and there
are many 2-pass muxers... I suppose for archival you have the same
kind of dilmena: do you want to create your files faster or do you
want future playback to be a tiny bit faster ?

>> 1 element" or simply "after the last Cluster element”?

You put at the end the things you can't predict when starting muxing.
The muxing "ending" after all audio/video data are done.

> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar
>

-- 
Steve Lhomme
Matroska association Chairman