Subject: [Cellar] presentation of the Matroska schema

From: Dave Rice <[email-masked]>
Date: Sat, 25 Jun 2016 22:05:19 -0400

Hi all,

I'm looking for feedback on how to present Matroska Elements in the specification. Currently the definitions of the Matroska elements are at https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/ebml_matroska.xml. This xml defines the elements as an EBML Schema which is defined in the EBML spec. Currently the human readable presentation of the Matroska Elements is in a big table at https://matroska.org/technical/specs/index.html#LevelEBML.

With the current displays of Matroska elements I think we have a few issues:

- Only very sparse descriptions are used for the elements. I think a long description would be the table unwieldy.
- The hierarchy of elements is hard to understand in the table (would have to scroll back up to the element of the lower level, with some exceptions for global elements).
- This form of the table won't fit well into an RFC style document.

From the ebml_matroska.xml we have an XSL file that can convert it to an HTML table to replicate the existing presentation. I've been working on another XSL that converts the ebml_matroska.xml file into a markdown document which presents each element in its own table. A draft of the output is here: https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac. In this style of presentation there is more room per element so I added data to show the parent element, child element(s), and element in hierarchical context. Markdown like this could be used when at RFC is built.

I think a markdown output of the matroska elements (with a table per element) also allows up to add more types of descriptions. For example in the ebml_matroska.xml, we currently only have one description, but this could be extended in order to have different types such as:
- definition
- rationale
- usage notes
- references (could optionally link to test files that demonstrate the element)

Each element would require a definition (a short description) which would be used in outputs such as https://matroska.org/technical/specs/index.html#LevelEBML, but the markdown output for the RFC or more verbose displays of element data could include the additional descriptions.

So I'd like feedback on:

- impressions of https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac
- is it worthwhile to add new data to element definitions such as rationale and usage notes?

Best Regards,
Dave Rice

---

From: hubblec4 <[email-masked]>
Date: Sun, 26 Jun 2016 22:11:24 +0200

Hi all

This is my first post here.

My name is Martin Below and I'm from germany and 38 years old.
In 2008, I came across Matroska.
I am very interested in the specs, especially for the Chapters, and the 
Tags.
In my chapterEditor <http://forum.doom9.org/showthread.php?t=169984> 
project there is a Chapter- Tags- and (first simple) Menu editor.
I found the specs was a good help, but not perfect and sometimes I was a 
bit confused.

Mosu helps me a lot with infos which I can't find on the Matroska page.

@Dave Rice

The new style 
<https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac> looks 
pretty good.
Maybe you can use "Level-colors" like in the old style (maybe the deeper 
levels(gray) should have other colors).

I like the new data's(parent element, child element(s), and element in 
hierarchical context) and the structure.

Extended description "usage notes" is very important in my eye's.
In the beginning at my project I decided users can enter valid settings 
and values only.
But what is valid?
The element ChapterTimeEnd(CTE) has no description that it can used with 
EditionFlagOrdered=true only.
If an edition is not ordered the CTE has no effect and a splitter will 
ignore them.
Is a CTE allowed in a non-ordered edition?
The same for ChapterSegementUID and ChapterSegmentEditionUID.
More complex is the question of nested-ordered-chapters.

Extended description "references" a is a great idea. Nothing is better 
as samples!!!

I found in the old style 2 elements marked with a "+". ChapterAtom and 
SimpleTag.
This elements can be a child element of its own.
You should add the ChapterAtom element in the "Child Elements"-section 
of the ChapterAtom(same with SimpleTag).

Some element names do not match to the specs-element names.
Starting from "ChapString" to "ChapProcessData".
I waste lot of time until Mosu told me that "Chap" is not correct.
The element names should change to the correct form. (ChapterString - 
ChapterProcessData).

I hope it helps you.

At the moment I have not much time, but I will help to improve Matroska.
I know many about Chapters and Tags, but I know there are many more and 
it will takes time to learn everything.

Best Regards,
Martin Below

Am 26.06.2016 um 04:05 schrieb Dave Rice:
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar

---

From: Dave Rice <[email-masked]>
Date: Sun, 26 Jun 2016 18:41:32 -0400

Hi Martin,

> On Jun 26, 2016, at 4:11 PM, hubblec4 <[email-masked]> wrote:
> 
> Hi all
> 

Welcome!!! btw since you are in Germany have you seen https://mediaarea.net/MediaConch/notimetowait.html ?

> I am very interested in the specs, especially for the Chapters, and the Tags.
> In my chapterEditor <http://forum.doom9.org/showthread.php?t=169984> project there is a Chapter- Tags- and (first simple) Menu editor.
> I found the specs was a good help, but not perfect and sometimes I was a bit confused.
> 

If in turn you could help get such info into the matroska or ebml specifications it would improve their quality.
> @Dave Rice
> 
> The new style <https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac> looks pretty good. 
> Maybe you can use "Level-colors" like in the old style (maybe the deeper levels(gray) should have other colors).

Well the Markdown in particular is prepped to be transformed into an RFC where everything in fixed width and plain text so in that case there's no options for colors or much formatting, but I think the same markdown could be used to make an alternate presentation to the current element table, so that maybe we could have a condensed table version and then a larger one like the markdown draft where more details can be given for each element.

> I like the new data's(parent element, child element(s), and element in hierarchical context) and the structure.

Thanks.

> In the beginning at my project I decided users can enter valid settings and values only.
> But what is valid?

Well I'm hoping to judge if there's enough volunteer energy for this. Currently each Matroska element has an average definition word count of 17. Then more extensive descriptions are sometimes interspersed into the rest of the narrative. But if we extended the structure in https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/ebml_matroska.xml to include additional descriptions we could communicate more effective about how this is to be used. 

For instance, whereas we currently define an element with

<element name="MuxingApp" level="2" id="0x4D80" type="utf-8" minOccurs="1" minver="1">
    <documentation lang="en">Muxing application or library ("libmatroska-0.4.3").</documentation>
</element>

we could have something like:

<element name="MuxingApp" level="2" id="0x4D80" type="utf-8" minOccurs="1" minver="1">
    <documentation lang="en" type="definition">Muxing application or library ("libmatroska-0.4.3").</documentation>
    <documentation lang="en" type="rationale">The Muxing application should be documented in order to allow a Matroska file to be associated with the software that created the file.</documentation>
    <documentation lang="en" type="usage notes">It is recommended to include the full name of the muxing application followed by the version number.</documentation>
</element>

Then the table could only use the documentation[@type='definition'] whereas other renditions such as the RFC could use all the documentation values.

> The element ChapterTimeEnd(CTE) has no description that it can used with EditionFlagOrdered=true only.
> If an edition is not ordered the CTE has no effect and a splitter will ignore them.

Thanks for bringing these up. I think we can agree on how to structure and store element descriptions then we can start new threads to draft extended documentation for each element so that the questions and scenarios you bring up can be better clarified by the documentation.

> Extended description "references" a is a great idea. Nothing is better as samples!!!
> 
> I found in the old style 2 elements marked with a "+". ChapterAtom and SimpleTag.
> You should add the ChapterAtom element in the "Child Elements"-section of the ChapterAtom(same with SimpleTag).

Thanks for pointing this out. I'll add handling of recursion into my draft and send a pull request.

> The element names should change to the correct form. (ChapterString - ChapterProcessData).

Moritz, can you verify this. From google search I see that "ChapterString"+matroska is more popular than "ChapString"+matroska but I am hesitant to change names in an official document too quickly.

> I hope it helps you.

Yes, very much.

> I know many about Chapters and Tags, but I know there are many more and it will takes time to learn everything.
> 
> 
> Best Regards,
> Martin Below

Best Regards,
Dave Rice

>> I'm looking for feedback on how to present Matroska Elements in the specification. Currently the definitions of the Matroska elements are at https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/ebml_matroska.xml <https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/ebml_matroska.xml>. This xml defines the elements as an EBML Schema which is defined in the EBML spec. Currently the human readable presentation of the Matroska Elements is in a big table at https://matroska.org/technical/specs/index.html#LevelEBML <https://matroska.org/technical/specs/index.html#LevelEBML>.
>> 
>> >From the ebml_matroska.xml we have an XSL file that can convert it to an HTML table to replicate the existing presentation. I've been working on another XSL that converts the ebml_matroska.xml file into a markdown document which presents each element in its own table. A draft of the output is here: https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac <https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac>. In this style of presentation there is more room per element so I added data to show the parent element, child element(s), and element in hierarchical context. Markdown like this could be used when at RFC is built.
>> 
>> Each element would require a definition (a short description) which would be used in outputs such as https://matroska.org/technical/specs/index.html#LevelEBML <https://matroska.org/technical/specs/index.html#LevelEBML>, but the markdown output for the RFC or more verbose displays of element data could include the additional descriptions.
>> 
>> So I'd like feedback on:
>> 
>> - impressions of https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac <https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac>
>> [email-masked] <mailto:[email-masked]>
>> https://www.ietf.org/mailman/listinfo/cellar <https://www.ietf.org/mailman/listinfo/cellar>
>

---

From: Dave Rice <[email-masked]>
Date: Sun, 26 Jun 2016 19:20:24 -0400

> On Jun 25, 2016, at 10:05 PM, Dave Rice <[email-masked]> wrote:
> 

I provided a pull request at https://github.com/Matroska-Org/ebml-specification/pull/68 which extends the use of the <documentation> element in the EBML Schema to classify what types of documentation are provided in element definitions.
Best Regards,
Dave Rice

---

From: hubblec4 <[email-masked]>
Date: Wed, 29 Jun 2016 21:34:38 +0200

Hi all

I have discovered an inaccuracy at ChapterTimeStart/End element type.
Type is "uinteger" that means 1, 2, 3, ond so on.
But the time format looks like this 00:00:00.123456789.
Exists an element type "Time"?

Best Regards,
Martin Below

>> I'm looking for feedback on how to present Matroska Elements in the specification. Currently the definitions of the Matroska elements are athttps://github.com/Matroska-Org/matroska-specification/blob/gh-pages/ebml_matroska.xml. This xml defines the elements as an EBML Schema which is defined in the EBML spec. Currently the human readable presentation of the Matroska Elements is in a big table athttps://matroska.org/technical/specs/index.html#LevelEBML.
>>
>> >From the ebml_matroska.xml we have an XSL file that can convert it to an HTML table to replicate the existing presentation. I've been working on another XSL that converts the ebml_matroska.xml file into a markdown document which presents each element in its own table. A draft of the output is here:https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac. In this style of presentation there is more room per element so I added data to show the parent element, child element(s), and element in hierarchical context. Markdown like this could be used when at RFC is built.
>>
>> Each element would require a definition (a short description) which would be used in outputs such ashttps://matroska.org/technical/specs/index.html#LevelEBML, but the markdown output for the RFC or more verbose displays of element data could include the additional descriptions.
>>
>> So I'd like feedback on:
>>
>> - impressions ofhttps://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac

---

From: Dave Rice <[email-masked]>
Date: Wed, 29 Jun 2016 15:38:30 -0400

> On Jun 29, 2016, at 3:34 PM, hubblec4 <[email-masked]> wrote:
> 
> Hi all
> 

I suspect that it is uinteger, but that it uses nanoseconds as a unit of measurement which the definition doesn't convey. The examples at https://matroska.org/technical/specs/chapters/index.html use the 'ns' unit of measurement for the examples, but a reference to the unit of measurement should really be in the definition of usage notes of the elements.
Dave

---

From: Moritz Bunkus <[email-masked]>
Date: Wed, 29 Jun 2016 21:48:05 +0200

Hey,

> Type is "uinteger" that means 1, 2, 3, ond so on.  But the time format
> looks like this 00:00:00.123456789.  Exists an element type "Time"?

There's no time type. ChapterTimeStart and End are stored as
nanoseconds. However, for human consumption they're usually written as
timestamps as that's easier to grasp. This also applies to mkvmerge's
XML chapter file format.

The on-disc storage is still a normal EBML unsigned integer, just like
e.g. the number of audio channels in the track headers and countless
other elements.

I agree with Dave that this should be made clear(er).

Kind regards,
mosu

---

From: Dave Rice <[email-masked]>
Date: Wed, 29 Jun 2016 15:50:41 -0400

> On Jun 29, 2016, at 3:48 PM, Moritz Bunkus <[email-masked]> wrote:
> 
> Hey,
> 

Is the concept of "unit of measurement" a prominent enough issue that it should be its own attribute in element definitions? Or should units of measurements simply be documented in the definition?
Dave

---

From: Moritz Bunkus <[email-masked]>
Date: Wed, 29 Jun 2016 21:58:51 +0200

Hey,

> Is the concept of "unit of measurement" a prominent enough issue that
> it should be its own attribute in element definitions? Or should units
> of measurements simply be documented in the definition?

My 2c:

It should simply be part of the human-readable documentation, I think. I
don't see big advantages in declaring them as attributes, especially for
elements where other elements determine the actual unit
(e.g. DisplayUnit for DisplayWidth/DisplayHeight). Declaraing that as
machine-readable attributes is probably more work than it's worth.

Just state something like "the chapter's start time in ns, relative to
the beginning of the segment". The notes could then also mention that
the preferred form of display for human consumption is some kind of
timestamp format instead of the raw number (similar to how sampling
frequencies are often written as 48 kHz instead of 48000 – it's just way
more obvious and useful in the case of timestamps vs. ns).

Kind regards,
mosu