I suggest adding a CONTRIBUTING.md file to promote contribution, explain what is happening in this repo, and reference the Cellar working group. Possibly we could add some issues suitable to new contributors.

I can't assign in this repo, but will at @ablwr anyway.

We need to define the mapping from the original codec, not some other framework.

A chunk of the spec seems to be missing -- from MatrixCoefficients to LuminanceMin. Is this intentional? Should I add them into the page?

Please add opus and HEVC in CodecID spec

codec_specs.md says (or used to say):

As an additional resource to this page Haali has created a list of codec IDs in a PDF.

This resource should be reviewed to determine what, if any, content should be incorporated into codec_specs.md.

Right now the Markdown code has a lot of {{site.baseurl}}/index.html#Cluster links. But they fail to link properly in the code.
I'm not sure how to fix this properly. Also I'm not sure it is good pratice to put links inside an RFC at all.

IIUC IEEE754 is the best citation for this. https://xml2rfc.tools.ietf.org/public/rfc/bibxml2/reference.IEEE.754.1985.xml

I noticed I couldn't locally build the RFC. I narrowed it down to the merging in of this commit 0250d60 refactoring ordered_guidelines. There's nothing wrong with the update in theory, but rather the Makefile is determined to occasionally turn the last paragraph of each file into a section heading. WHY!?

So the last sentence or ordered_guidelines.md was set up to quote the elements like so:

The `Timecode Element` MUST occur as in storage order before any `SimpleBlock`, `BlockGroup`, or `EncryptedBlock` within the `Cluster Element`.

Which causes the break. The same occurs if modifying the last line in notes.md, which precedes it.

Working on sorting out this bug since I unintentionally caused it to rise up!

And possibly make them unique.

I'm not sure what these are official called but I see the use of many tags that are prefixed with an underscore, such as _DURATION. From what I can tell these are internal and intended to be hidden from the user in some cases. If this is so, the pattern of hidden tags (vs official and unofficial tags) should be documented.

matroska.org included an article about overhead as part of the spec, which in the repo is represented in markdown at this page. Many of the tables in the markdown version are missing data (only the first column is migrated).

Relatedly, should this article be considered part of the format specification?

For the moment there is no limitation, every edition entry could have the EditionFlagDefault set to true.

My opinion is we should have one default edition only.

Not sure if we have an IETF style notations section yet, but both Matroska Player and Matroska Reader should be defined. Related comment: #190 (comment)

See this thread for more info https://www.ietf.org/mail-archive/web/cellar/current/msg00769.html
And also https://www.ietf.org/mail-archive/web/cellar/current/msg00155.html

Impacted elements are /Tracks/TrackEntry/Language, /Chapters/EditionEntry/ChapterAtom/ChapterDisplay/ChapLanguage and /Tags/Tag/SimpleTag/TagLanguage.

Hello,

currently, for PCM tracks only the endianess (via Codec ID), the channel count, the sampling frequency and the bitdepth (via the audio header elements) are explicitly stored; the signedness is not so that it is completely unspecified and hence ambiguous. This should be changed. Given that 8-bit PCM is usually unsigned while the higher bitdepths are usually signed (that is how it is done in wav), we should specify it as such. This is also how FFmpeg treats 8-bit audio inside Matroska.

Greetings
Andi

If you want some sample code for all these calculations you can have a look at this small C program.

Maybe the tool you created is located elsewhere these days.

See #192 and #142. Currently Matroska only describes default values for the signedness of PCM audio. I propose defining a method to clarify signedness, so for instance signed 8 bit or unsigned 24 bit could be supported.

Need some language here https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/attachments.md#font-files

A few sections in Matroska's draft specification seem fully redundant to the EBML specification. EBML should be a normative reference of Matroska and the redundancy should be reviewed and likely reduced.

Particularly these sections:
https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/notes.md#ebml-class
https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/matroska_schema_section_header.md#ebml-schema-element-attributes

I found in DVDMenuXtrator's(DMX) output-xml files, smaller end times than start times.
I have try to understand the Matroska-DVD-Menu logic but it is very hard. I think the end times in DVD-Matroska Menu are not every time needed.
TNG-S6-D1.zip
I hope Steve Lohmme can explain this a bit.

I know, DMX is not really in use and the support in VLC is not 100% working.
But we should mention such things to complete the specs.

Chapter times are dependent on two things:

1. ordered edition

• without an ordered edition, only start times are used and relevant (end times can be written but without an effect to the mkv/splitter).

2. linking system (we have 3 linking systems (hard; soft; medium))

• hard linking: this linking is independent from the chapter times and all end times must be greater than
  the start times. In my tests with hard linking, the hard linking system will be "overwritten"
  by medium linking when ordered editions are defined.

• soft linking: this linking is used by Matroska-DVD-Menu system and the chapter times seems to have
  her own rules.

• medium linking: this linking is used by Chapter-Segment-Linking with an ordered edition
  chapter time rules are:

  • end times greater than start times (normal behavior)
  • end times equal to start times: in this case a nested chapter with a start time equal to the parent
    start/end time sould be used otherwise is such a chapter only a chapter mark.
    With such a behaviour is it possible to build more complex medium-linking structures and in
    combination with the Matroska-Native-Menu(and VOB-Butons) we could have almost unlimited
    possibility for own Matroska menus.

We have the unknownsizeallowed attribute defined, we should use it. What Matroska elements are unknownsizeallowed?

Where are the elements that are supposed to be executed by the player (e.g. the LUTs) documented?

Hello, is it too early to include mapping for Dolby AC4 in the Matroska specification? The core elements were defined in 2014 and subsequently standardized with the European Telecommunications Standards Institute (TS 103 190) and adopted for DVB (TS 101 154) in 2015. Please advise, thank you.

Bitstream syntax and frame documentation...

ETSI Digital Audio Compression (AC-4) Standard Part 1 v1.2.1 (2015-06)

• http://www.etsi.org/deliver/etsi_ts/103100_103199/10319001/01.02.01_60/ts_10319001v010201p.pdf

ETSI Digital Audio Compression (AC-4) Standard Part 2 v1.1.1 (2015-09)

• http://www.etsi.org/deliver/etsi_ts/103100_103199/10319002/01.01.01_60/ts_10319002v010101p.pdf

Digital Video Broadcasting (DVB) Specification for the use of Video and Audio Coding in Broadcasting Applications v2.2.1 (2015-06)

• http://www.etsi.org/deliver/etsi_ts/101100_101199/101154/02.02.01_60/ts_101154v020201p.pdf

Audio has A_, Video has V_, etc

let Matroska support VR/360-degree Video

Except for the ones used for DRM already in use in WebM.

As suggested by @dericed here #39 (comment)

Currently a few section names are repeated in different context which breaks the TOC in the IETF html output, such as:

• Matroska Element Ordering Guidelines / Chapters
• Chapters

The section should be renamed to be unique regardless of context.

It may just be running some Jekyll commands as a Makefile target (like website).

That would help keep our Markdown and website generator happy together for longer.

The pages 178–180 are rendered as… miniatures.

For instance to explain the examples in here https://github.com/Matroska-Org/matroska-specification/blob/3e689519b9a84e508d98b1dcbd97d17744e144a3/chapters.md#example-1--basic-chaptering. This issue supersedes this discussion.

Recently GitHub allows naming the master branch for Github Pages. I think renaming gh-pages to master and setting GitHub Pages to read from master would simplify the repo. See https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#enabling-github-pages-to-publish-your-site-from-master-or-gh-pages.

In attachments.md, it says "Matroska Readers MUST NOT execute files stored as Attachments."

In the index.md under security considerations, it says Matroska Readers that extract or use data from Matroska Attachments SHOULD check that the data adheres to expectations.

Which is correct? More importantly, what scope of governance can the Matroska specification have on software that reads it? I understand this as a good recommendation in general, but not implementable.

The logic of the Chapter Flag section was very confusing. For instance it claimed that:

There are two important flags that apply to chapter atoms: enabled and hidden. The effect of those flags always applies to child atoms of an atom affected by that flag.

But then it describes Hidden flag as affecting the Child ChapterAtom only if the parent ChapterAtom has the flag set to true. IIUC, the Hidden Flag "always applies to child atoms" ONLY if true, otherwise the ChapterAtom's own flags are used.

Currently https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/ebml_matroska.xml uses an attribute called bytesize but per the ebml spec it should be called size.

There is a section on EncryptedBlock Structure in https://github.com/Matroska-Org/matroska-specification/blob/gh-pages/index.md#encryptedblock-structure, but in the matroska.org source it is greyed out. Should this section be removed?

In tagging.md, under Target types, there is this sentence (after the table):

That means if a CD has the same artist for all tracks, you just need to set the ARTIST tag at level 40 (ALBUM) and not to each TRACK (but you can).

However, the table shows that ALBUM should be level 50 instead.

In line 17 of codec_specs.md you link to http://www.corecodec.com/modules.php?op=modload&name=PNphpBB2&file=viewtopic&t=227 which returns a 404.

I don't know how if there is still a resource that could be included instead or if the section would have to be reworked.

I see some Matroska apps prefixing tag names with underscores but this behavior and associated expectations is not yet in the specification.

For instance

<Tags>
   <!-- ... -->
  <Tag>
    <Simple>
      <Name>_STATISTICS_WRITING_APP</Name>
      <String>mkvmerge v8.4.0 ('A better way to fly') 32bit</String>
    </Simple>
    <Simple>
      <Name>_STATISTICS_WRITING_APP</Name>
      <TagLanguage>eng</TagLanguage>
      <String>mkvmerge v8.4.0 ('A better way to fly') 32bit</String>
    </Simple>
    <Simple>
      <Name>_STATISTICS_WRITING_DATE_UTC</Name>
      <String>2015-10-23 09:54:30</String>
    </Simple>
    <Simple>
      <Name>_STATISTICS_WRITING_DATE_UTC</Name>
      <TagLanguage>eng</TagLanguage>
      <String>2015-10-23 09:54:30</String>
    </Simple>
    <Simple>
      <Name>_STATISTICS_TAGS</Name>
      <String>BPS DURATION NUMBER_OF_FRAMES NUMBER_OF_BYTES</String>
    </Simple>
    <Simple>
      <Name>_STATISTICS_TAGS</Name>
      <TagLanguage>eng</TagLanguage>
      <String>BPS DURATION NUMBER_OF_FRAMES NUMBER_OF_BYTES</String>
    </Simple>
    <Simple>
      <Name>ENCODER</Name>
      <String>Lavc56.41.100 libmp3lame</String>
    </Simple>
  </Tag>
</Tags>

Here `ENCODER` is an `official` tag. The rest (prefixed by underscores) are not represented in the specification but commonly used.

The nest table in https://matroska.org/technical/specs/codecid/index.html is broken in the RFC output. The nested form, for instance under V_MPEG4/ISO/??? and V_REAL/????, is challenging to replicate in the simpler formatting of the RFC.
Can these tables be restructured without nesting?

Also the structure of the table in codec spec implies that only four pieces of information are needed to define a codec for use in Matroska:

• Codec ID
• Name
• Description
• Track Type (currently Video, Audio, Subtitle, and ... Button)

Is any more data needed to define an encoding for use in Matroska?

Also the TrackType Element also supports complex, logo, and control track types although none appear to be defined in the codec specs page.

Copy https://matroska.org/technical/order/index.html as is into the repo so that we can start editing.

The deprecated recursive attribute still exists in a few elements.

I have a faint memory of reading somewhere that official mkv tags should be in all uppercase letters (and numbers) while anything else is an un-official tag. I like the part in the tags document about official tags but the use of un-official tags should be documented.

Referencing: https://github.com/dericed/matroska-specification/blob/gh-pages/tagging.md

The lines below are from the make process with line numbers referring to the xml output. It seems the subtitle examples in particular use very long lines. Should move this out of a code block or break the lines up somehow.

WARNING: Output line (from source around line 549) is 83 characters; longer than 72. Excess characters: '----------+':
'| | | |----------------------------------+'

WARNING: Output line (from source around line 550) is 83 characters; longer than 72. Excess characters: 'pString |':
'| | | | ChapterDisplay | ChapString |'

WARNING: Output line (from source around line 551) is 83 characters; longer than 72. Excess characters: '----------|':
'| | | | |--------------|'

WARNING: Output line (from source around line 552) is 83 characters; longer than 72. Excess characters: 'pLanguage |':
'| | | | | ChapLanguage |'

WARNING: Output line (from source around line 553) is 83 characters; longer than 72. Excess characters: '----------+':
'+---------------------------------------------------------------------------------+'

WARNING: Output line (from source around line 6988) is 196 characters; longer than 72. Excess characters: 'ryColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, AlphaLevel, Encoding':
'Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, TertiaryColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, AlphaLevel, Encoding'

WARNING: Output line (from source around line 6989) is 87 characters; longer than 72. Excess characters: ',2,2,5,5,30,0,0':
'Style: Wolf main,Wolf_Rain,56,15724527,15724527,15724527,4144959,0,0,1,1,2,2,5,5,30,0,0'

WARNING: Output line (from source around line 6995) is 80 characters; longer than 72. Excess characters: 'ct, Text':
'Format: Marked, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text'

WARNING: Output line (from source around line 6996) is 115 characters; longer than 72. Excess characters: 'Et les enregistrements de ses ondes delta ?':
'Dialogue: Marked=0,0:02:40.65,0:02:41.79,Wolf main,Cher,0000,0000,0000,,Et les enregistrements de ses ondes delta ?'

WARNING: Output line (from source around line 6997) is 87 characters; longer than 72. Excess characters: ',Toujours rien.':
'Dialogue: Marked=0,0:02:42.42,0:02:44.15,Wolf main,autre,0000,0000,0000,,Toujours rien.'

WARNING: Output line (from source around line 7027) is 76 characters; longer than 72. Excess characters: '.wav':
'Wav: 0, 128697,D:\Alex\Anime- Fansub -- TAFF -\Wolf's Rain\WR_-_02_Wav.wav'

WARNING: Output line (from source around line 7034) is 196 characters; longer than 72. Excess characters: 'ryColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, AlphaLevel, Encoding':
'Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, TertiaryColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, AlphaLevel, Encoding'

WARNING: Output line (from source around line 7035) is 79 characters; longer than 72. Excess characters: ',30,0,0':
'Style: Default,Arial,20,65535,65535,65535,-2147483640,-1,0,1,3,0,2,30,30,30,0,0'

WARNING: Output line (from source around line 7036) is 84 characters; longer than 72. Excess characters: '30,30,30,0,0':
'Style: Titre_episode,Akbar,140,15724527,65535,65535,986895,-1,0,1,1,0,3,30,30,30,0,0'

WARNING: Output line (from source around line 7037) is 87 characters; longer than 72. Excess characters: ',2,2,5,5,30,0,0':
'Style: Wolf main,Wolf_Rain,56,15724527,15724527,15724527,4144959,0,0,1,1,2,2,5,5,30,0,0'

WARNING: Output line (from source around line 7040) is 80 characters; longer than 72. Excess characters: 'ct, Text':
'Format: Marked, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text'

WARNING: Output line (from source around line 7041) is 115 characters; longer than 72. Excess characters: 'Et les enregistrements de ses ondes delta ?':
'Dialogue: Marked=0,0:02:40.65,0:02:41.79,Wolf main,Cher,0000,0000,0000,,Et les enregistrements de ses ondes delta ?'

WARNING: Output line (from source around line 7042) is 87 characters; longer than 72. Excess characters: ',Toujours rien.':
'Dialogue: Marked=0,0:02:42.42,0:02:44.15,Wolf main,autre,0000,0000,0000,,Toujours rien.'

WARNING: Output line (from source around line 7063) is 76 characters; longer than 72. Excess characters: '.wav':
'Wav: 0, 128697,D:\Alex\Anime- Fansub -- TAFF -\Wolf's Rain\WR_-_02_Wav.wav'

WARNING: Output line (from source around line 7070) is 196 characters; longer than 72. Excess characters: 'ryColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, AlphaLevel, Encoding':
'Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, TertiaryColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, AlphaLevel, Encoding'

WARNING: Output line (from source around line 7071) is 79 characters; longer than 72. Excess characters: ',30,0,0':
'Style: Default,Arial,20,65535,65535,65535,-2147483640,-1,0,1,3,0,2,30,30,30,0,0'

WARNING: Output line (from source around line 7072) is 84 characters; longer than 72. Excess characters: '30,30,30,0,0':
'Style: Titre_episode,Akbar,140,15724527,65535,65535,986895,-1,0,1,1,0,3,30,30,30,0,0'

WARNING: Output line (from source around line 7073) is 87 characters; longer than 72. Excess characters: ',2,2,5,5,30,0,0':
'Style: Wolf main,Wolf_Rain,56,15724527,15724527,15724527,4144959,0,0,1,1,2,2,5,5,30,0,0'

WARNING: Output line (from source around line 7082) is 77 characters; longer than 72. Excess characters: 'lta ?':
'1,,Wolf main,Cher,0000,0000,0000,,Et les enregistrements de ses ondes delta ?'

WARNING: Output line (from source around line 7203) is 76 characters; longer than 72. Excess characters: 'ngs.':
'Example entry 3: That stuff to the right of the timestamps are cue settings.'

WARNING: Output line (from source around line 7286) is 76 characters; longer than 72. Excess characters: 'ngs.':
'Example entry 3: That stuff to the right of the timestamps are cue settings.'

The colour element definitions were written with reference to ISO/IEC 23001-8:2013/DCOR1 but now the 2016 version is available. I suggest we review and see if we can reference to the new version and if that addresses any of the proposed values that we were anticipating.

The link to the Diagram page on index.md is broken.

• Matroska core specification
• codec definitions
• tags definitions

The agreement clearly defines the terms under which intellectual property has been contributed to the Matroska.

This is either missing a word like 'project' (or 'non-profit' or whatever else) or if Matroska is standing for its own, the 'the' should not be there.

see range attributes in https://github.com/Matroska-Org/matroska-specification/blob/fce29626d0c7d7d7b0a0543f82cb3da924bce8d4/ebml_matroska.xml#L548-L553

As of 2009, the SV8 specification seems to be complete; can the Mastroka framing for it be defined now? Please advise, thank you.

Codec ID: A_MPC
Codec Name: MPC (musepack) SV8
Description: The main developer for musepack has requested that we wait until the SV8 framing has been fully defined for musepack before defining how to store it in Matroska.