diff --git a/attachments.md b/attachments.md index f317ebc8e..ac1fabb8e 100644 --- a/attachments.md +++ b/attachments.md @@ -1,11 +1,11 @@ # Attachments -Matroska supports storage of related files and data in the `Attachments Element` -(a `Top-Level Element`). `Attachment Elements` can be used to store related cover art, +Matroska supports storage of related files and data in the `Attachments` element +(a `Top-Level Element`). `Attachments` elements can be used to store related cover art, font files, transcripts, reports, error recovery files, pictures, text-based annotations, copies of specifications, or other ancillary files related to the `Segment`. -`Matroska Readers` **MUST NOT** execute files stored as `Attachment Elements`. +`Matroska Readers` **MUST NOT** execute files stored as `Attachments` elements. ## Cover Art @@ -24,13 +24,13 @@ The dimension of the `normal cover` **SHOULD** be 600 pixels on the smallest sid the `small cover` **SHOULD** be 120 pixels on the smallest side (e.g., 192x120 or 120x160). Versions of cover art can be differentiated by the filename, which is stored in the -`FileName Element`. The default filename of the `normal cover` in square or portrait mode -is `cover.(jpg|png)`. When stored, the `normal cover` **SHOULD** be the first Attachment in +`FileName` element. The default filename of the `normal cover` in square or portrait mode +is `cover.(jpg|png)`. When stored, the `normal cover` **SHOULD** be the first `Attachments` element in storage order. The `small cover` **SHOULD** be prefixed with "small_", such as `small_cover.(jpg|png)`. The landscape variant **SHOULD** be suffixed with "\_land", such as `cover_land.(jpg|png)`. The filenames are case-sensitive. -The following table provides examples of file names for cover art in Attachments. +The following table provides examples of file names for cover art in `Attachments`. | File Name | Image Orientation | Pixel Length of Smallest Side | |----------------------|--------------------|-------------------------------| @@ -49,21 +49,21 @@ consistent in various environments where the needed fonts might not be available Depending on the font format in question, each font file can contain multiple font variants. Each font variant has a name that will be referred to as Font Name from now on. This Font Name can be different from the Attachment's `FileName`, even when disregarding the extension. -In order to select a font for display, a Matroska Player **SHOULD** consider both the Font Name -and the base name of the Attachment's FileName, preferring the former when there are multiple matches. +In order to select a font for display, a `Matroska Player` **SHOULD** consider both the Font Name +and the base name of the Attachment's `FileName`, preferring the former when there are multiple matches. Subtitle codecs, such as SubStation Alpha (SSA) and Advanced SubStation Alpha (ASS), usually refer to a font by its Font Name, not by its filename. -If none of the Attachments are a match for the Font Name, the Matroska Player **SHOULD** +If none of the Attachments are a match for the Font Name, the `Matroska Player` **SHOULD** attempt to find a system font whose Font Name matches the one used in the subtitle track. -Since loading fonts temporarily can take a while, a Matroska Player usually +Since loading fonts temporarily can take a while, a `Matroska Player` usually loads or installs all the fonts found in attachments so they are ready to be used during playback. Failure to use the font attachment might result in incorrect rendering of the subtitles. If a selected subtitle track has some `AttachmentLink` elements, the player **MAY** restrict its font rendering to use only these fonts. -A Matroska Player **SHOULD** handle the official font media types from [@!RFC8081] when the system can handle the type: +A `Matroska Player` **SHOULD** handle the official font media types from [@!RFC8081] when the system can handle the type: * font/sfnt: Generic SFNT Font Type @@ -78,7 +78,7 @@ A Matroska Player **SHOULD** handle the official font media types from [@!RFC808 * font/woff2: WOFF 2.0 Fonts in Matroska existed long before [@!RFC8081]. A few unofficial media types for fonts were used in existing files. -Therefore, it is **RECOMMENDED** for a Matroska Player to support the following legacy media types for font attachments: +Therefore, it is **RECOMMENDED** for a `Matroska Player` to support the following legacy media types for font attachments: * application/x-truetype-font: TrueType fonts, equivalent to `font/ttf` and sometimes `font/otf` @@ -92,7 +92,7 @@ Therefore, it is **RECOMMENDED** for a Matroska Player to support the following There may also be some font attachments with the `application/octet-stream` media type. -In that case, the Matroska Player **MAY** try to guess the font type by checking the file extension of the `AttachedFile\FileName` string. +In that case, the `Matroska Player` **MAY** try to guess the font type by checking the file extension of the `AttachedFile\FileName` string. Common file extensions for fonts are: * `.ttf` for TrueType fonts, equivalent to `font/ttf` @@ -103,7 +103,7 @@ Common file extensions for fonts are: The file extension check **MUST** be case-insensitive. -Matroska Writers **SHOULD** use a valid font media type from [@!RFC8081] in the `AttachedFile\FileMediaType` of the font attachment. +`Matroska Writers` **SHOULD** use a valid font media type from [@!RFC8081] in the `AttachedFile\FileMediaType` of the font attachment. They **MAY** use the media types found in older files when compatibility with older players is necessary. diff --git a/block_additional_mappings/smpte-st12-1-timecode.md b/block_additional_mappings/smpte-st12-1-timecode.md index d32f61915..fb84c4d1f 100644 --- a/block_additional_mappings/smpte-st12-1-timecode.md +++ b/block_additional_mappings/smpte-st12-1-timecode.md @@ -2,11 +2,11 @@ ### Timecode Description -SMPTE ST 12-1 timecode values can be stored in the `BlockMore Element` to associate +SMPTE ST 12-1 timecode values can be stored in the `BlockMore` element to associate the content of a Matroska Block with a particular timecode value. If the Block uses Lacing, the timecode value is associated with the first frame of the Lace. -The Block Additional Mapping contains a full binary representation of a 64 bit SMPTE timecode +The `Block Additional Mapping` contains a full binary representation of a 64 bit SMPTE timecode value stored in big-endian format and expressed exactly as defined in Section 8 and 9 of SMPTE 12M [@!ST12]. For convenience, here are the bit assignments for a SMPTE ST 12-1 binary representation as described in [@?RFC5484, section 6.2]: @@ -45,12 +45,12 @@ For example, a timecode value of "07:32:54;18" can be expressed as a 64 bit SMPT ### BlockAddIDType -The BlockAddIDType value reserved for timecode is "121". +The `BlockAddIDType` value reserved for timecode is "121". ### BlockAddIDName -The BlockAddIDName value reserved for timecode is "SMPTE ST 12-1 timecode". +The `BlockAddIDName` value reserved for timecode is "SMPTE ST 12-1 timecode". ### BlockAddIDExtraData -BlockAddIDExtraData is unused within this block additional mapping. +`BlockAddIDExtraData` is unused within this block additional mapping. diff --git a/block_additional_mappings_intro.md b/block_additional_mappings_intro.md index a694d1ba0..7b9a7251e 100644 --- a/block_additional_mappings_intro.md +++ b/block_additional_mappings_intro.md @@ -2,61 +2,61 @@ Extra data or metadata can be added to each `Block` using `BlockAdditional` data. Each `BlockAdditional` contains a `BlockAddID` that identifies the kind of data it contains. -When the `BlockAddID` is set to "1" the contents of the `BlockAdditional Element` +When the `BlockAddID` is set to "1" the contents of the `BlockAdditional` element are define by the Codec Mappings defines; see (#codec-blockadditions). When the `BlockAddID` is set a value greater than "1", then the contents of the -`BlockAdditional Element` are defined by the `BlockAdditionalMapping Element`, within -the associated `Track Element`, where the `BlockAddID Element` of `BlockAdditional Element` -equals the `BlockAddIDValue` of the associated Track's `BlockAdditionalMapping Element`. -That `BlockAdditionalMapping Element` identifies a particular Block Additional Mapping by the `BlockAddIDType`. +`BlockAdditional` element are defined by the `BlockAdditionalMapping` element, within +the associated `Track` element, where the `BlockAddID` element of `BlockAdditional` element +equals the `BlockAddIDValue` of the associated `Track`'s `BlockAdditionalMapping` element. +That `BlockAdditionalMapping` element identifies a particular `Block Additional Mapping` by the `BlockAddIDType`. -The following XML depicts a use of a Block Additional Mapping to associate a timecode value with a `Block`: +The following XML depicts a use of a `Block Additional Mapping` to associate a timecode value with a `Block`: ```xml - - - - - 1 - 568001708 - 1 - - 2 - timecode - 12 - - V_FFV1 - - - - - 3000 - - {binary video frame} - - - 2 - 01:00:00:00 - - - - - +<Segment> + <!--Mandatory elements ommitted for readability--> + <Tracks> + <TrackEntry> + <TrackNumber>1</TrackNumber> + <TrackUID>568001708</TrackUID> + <TrackType>1</TrackType> + <BlockAdditionalMapping> + <BlockAddIDValue>2</BlockAddIDValue><!--arbitrary value + used in BlockAddID--> + <BlockAddIDName>timecode</BlockAddIDName> + <BlockAddIDType>12</BlockAddIDType> + </BlockAdditionalMapping> + <CodecID>V_FFV1</CodecID> + <Video> + <PixelWidth>1920</PixelWidth> + <PixelHeight>1080</PixelHeight> + </Video> + </TrackEntry> + </Tracks> + <Cluster> + <Timestamp>3000</Timestamp> + <BlockGroup> + <Block>{binary video frame}</Block> + <BlockAdditions> + <BlockMore> + <BlockAddID>2</BlockAddID><!--arbitrary value from + BlockAdditionalMapping--> + <BlockAdditional>01:00:00:00</BlockAdditional> + </BlockMore> + </BlockAdditions> + </BlockGroup> + </Cluster> +</Segment> ``` -Block Additional Mappings detail how additional data **MAY** be stored in the `BlockMore Element` -with a `BlockAdditionMapping Element`, within the `Track Element`, which identifies the `BlockAdditional` content. -Block Additional Mappings define the `BlockAddIDType` value reserved to identify that -type of data as well as providing an optional label stored within the `BlockAddIDName Element`. -When the Block Additional Mapping is dependent on additional contextual information, -then the Mapping **SHOULD** describe how such additional contextual information is stored within the `BlockAddIDExtraData Element`. +`Block Additional Mappings` detail how additional data **MAY** be stored in the `BlockMore` element +with a `BlockAdditionMapping` element, within the `Track` element, which identifies the `BlockAdditional` content. +`Block Additional Mappings` define the `BlockAddIDType` value reserved to identify that +type of data as well as providing an optional label stored within the `BlockAddIDName` element. +When the `Block Additional Mapping` is dependent on additional contextual information, +then the Mapping **SHOULD** describe how such additional contextual information is stored within the `BlockAddIDExtraData` element. -The following Block Additional Mappings are defined. +The following `Block Additional Mappings` are defined. ## Summary of Assigned BlockAddIDType Values diff --git a/chapter_codecs.md b/chapter_codecs.md index 66dd99526..be993122e 100644 --- a/chapter_codecs.md +++ b/chapter_codecs.md @@ -26,8 +26,8 @@ between the chapter codec values and the actual segment it targets. # Matroska Chapter Codecs and Nested Chapters -When `Nested Chapters` contain chapters codecs -- via the `ChapProcess` Element -- -the enter/leave commands -- ChapProcessTime Element -- **MUST** be executed in a specific order, +When `Nested Chapters` contain chapters codecs -- via the `ChapProcess` element -- +the enter/leave commands -- `ChapProcessTime` element -- **MUST** be executed in a specific order, if the Matroska Player supports the chapter codecs included in the chapters. When starting playback, the `Matroska Player` **MUST** start at the `ChapterTimeStart` of the first chapter of the ordered chapter. diff --git a/chapters.md b/chapters.md index ff1ecc220..01cf9e509 100644 --- a/chapters.md +++ b/chapters.md @@ -1,17 +1,17 @@ # Chapters -The Matroska Chapters system can have multiple `Editions`, and each `Edition` can consist of +The Matroska `Chapters` system can have multiple `Editions`, and each `Edition` can consist of `Simple Chapters` where a chapter start time is used as a marker in the timeline only. An `Edition` can be more complex with `Ordered Chapters` where a chapter end timestamp is additionally -used or much more complex with `Linked Chapters`. The Matroska Chapters system can also have a menu +used or much more complex with `Linked Chapters`. The Matroska `Chapters` system can also have a menu structure borrowed from the DVD-menu system [@?DVD-Video] or have its own built-in Matroska menu structure. ## EditionEntry The `EditionEntry` is also called an `Edition`. -An `Edition` contains a set of `Edition` flags and **MUST** contain at least one `ChapterAtom Element`. -Chapters are always inside an `Edition` (or a Chapter itself is part of an `Edition`). -Multiple Editions are allowed. Some of these Editions **MAY** be ordered and others not. +An `Edition` contains a set of `Edition` flags and **MUST** contain at least one `ChapterAtom` element. +`Chapters` are always inside an `Edition` (or a `Chapter` itself is part of an `Edition`). +Multiple `Editions` are allowed. Some of these `Editions` **MAY** be ordered and others not. ### EditionFlagDefault @@ -58,29 +58,27 @@ the full content (including colorbars, countdown, slate, a feature presentation, black frames), while another `Edition` of `Ordered Chapters` can use `Chapters` that only mark the intended presentation with the colorbars and other ancillary visual information excluded. If an `Edition` of `Ordered Chapters` is enabled, then the `Matroska Player` **MUST** -play those Chapters in their stored order from the timestamp marked in the -`ChapterTimeStart Element` to the timestamp marked in to `ChapterTimeEnd Element`. +play those `Chapters` in their stored order from the timestamp marked in the +`ChapterTimeStart` element to the timestamp marked in to `ChapterTimeEnd` element. If the `EditionFlagOrdered` flag evaluates to "0", `Simple Chapters` are used and only the `ChapterTimeStart` of a `Chapter` is used as a chapter mark to jump to the predefined point in the timeline. With `Simple Chapters`, a `Matroska Player` **MUST** -ignore certain `Chapter Elements`. In that case, these elements are informational only. +ignore certain elements inside a `Chapters` element. In that case, these elements are informational only. -The following list shows the different Chapter elements only found in `Ordered Chapters`. +The following list shows the different `Chapters` elements only found in `Ordered Chapters`. -* ChapterAtom/ChapterSegmentUUID +* `ChapterAtom\ChapterSegmentUUID` -* ChapterAtom/ChapterSegmentEditionUID +* `ChapterAtom\ChapterSegmentEditionUID` -* ChapterAtom/ChapterTrack +* `ChapterAtom\ChapProcess` -* ChapterAtom/ChapProcess +* `Info\ChapterTranslate` -* Info/ChapterTranslate +* `TrackEntry\TrackTranslate` -* TrackEntry/TrackTranslate - -Furthermore, there are other EBML `Elements` that could be used if the `EditionFlagOrdered` +Furthermore, there are other EBML elements that could be used if the `EditionFlagOrdered` evaluates to "1". #### Ordered-Edition and Matroska Segment Linking @@ -92,20 +90,20 @@ Hard Linking: Medium Linking: : `Ordered Chapters` are used in a normal way and can be combined -with the `ChapterSegmentUUID` element, which establishes a link to another Segment. +with the `ChapterSegmentUUID` element, which establishes a link to another `Segment`. -See (#linked-segments) on Linked Segments for more information +See (#linked-segments) on `Linked Segment`s for more information about `Hard Linking` and `Medium Linking`. ## ChapterAtom The `ChapterAtom` is also called a `Chapter`. ### ChapterTimeStart -`ChapterTimeStart` is the timestamp of the start of `Chapter` with nanosecond accuracy and is not scaled by TimestampScale. +`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. ### ChapterTimeEnd -`ChapterTimeEnd` is the timestamp of the end of `Chapter` with nanosecond accuracy and is not scaled by TimestampScale. +`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`. @@ -129,8 +127,8 @@ Table: ChapterTimeEnd Usage Possibilities{#ChapterTimeEndUsage} 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. +`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`. @@ -139,18 +137,18 @@ If the `Parent Chapter` of a `Nested Chapter` has a `ChapterTimeEnd`, the `Chapt ### Nested Chapters in Ordered Chapters -The `ChapterTimeEnd` of the lowest level of `Nested Chapters` **MUST** be set for 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 `ChapterTimeEnd` value of a `Parent Chapter` is useless 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. ### ChapterFlagHidden -Each Chapter -`ChapterFlagHidden` flag works independently of Parent Chapters. +Each `Chapter`'s +`ChapterFlagHidden` flag works independently of `Parent Chapters`. A `Nested Chapter` with a `ChapterFlagHidden` flag that evaluates to "0" remains visible in the user interface even if the -`Parent Chapter` `ChapterFlagHidden` flag is set to "1". +`Parent Chapter`'s `ChapterFlagHidden` flag is set to "1". Chapter + Nested Chapter | ChapterFlagHidden | visible :------------------------|:------------------|:------- @@ -169,11 +167,11 @@ some private data, and some data in the chapters. The type of the menu system is defined by the `ChapProcessCodecID` parameter. For now, only two values are supported: 0 (Matroska Script) and 1 (menu borrowed from the DVD [@?DVD-Video]). -The private data depend on the type of menu system (stored in `ChapProcessPrivate`), -idem for the data in the chapters (stored in `ChapProcessData`). +The private data stored in `ChapProcessPrivate` and +`ChapProcessData` depends on the `ChapProcessCodecID` value. The menu system, as well as Chapter Codecs in general, can perform actions on the `Matroska Player`, -such as jumping to another Chapter or Edition, selecting different tracks, and possibly more. +such as jumping to another `Chapter` or `Edition`, selecting different tracks, and possibly more. The scope of all the possibilities of Chapter Codecs is not covered in this document, as it depends on the Chapter Codec features and its integration in a `Matroska Player`. @@ -203,73 +201,73 @@ audio file (album) in which each track corresponds to a chapter. * 00000 ms - 05000 ms: Intro * 05000 ms - 25000 ms: Before the crime * 25000 ms - 27500 ms: The crime -* 27500 ms - 38000 ms: The killer arrested +* 27500 ms - 38000 ms: After the crime * 38000 ms - 43000 ms: Credits -This would translate in the following Matroska form, with the EBML tree shown as XML: +This translates to Matroska form, with the EBML tree shown as follows in XML: ```xml - - - 16603393396715046047 - - 1193046 - 0 - 5000000000 - - Intro - - - - 2311527 - 5000000000 - 25000000000 - - Before the crime - - - Avant le crime - fra - - - - 3430008 - 25000000000 - 27500000000 - - The crime - - - Le crime - fra - - - - 4548489 - 27500000000 - 38000000000 - - After the crime - - - Apres le crime - fra - - - - 5666960 - 38000000000 - 43000000000 - - Credits - - - Generique - fra - - - - +<Chapters> + <EditionEntry> + <EditionUID>16603393396715046047</EditionUID> + <ChapterAtom> + <ChapterUID>1193046</ChapterUID> + <ChapterTimeStart>0</ChapterTimeStart> + <ChapterTimeEnd>5000000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Intro</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>2311527</ChapterUID> + <ChapterTimeStart>5000000000</ChapterTimeStart> + <ChapterTimeEnd>25000000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Before the crime</ChapString> + </ChapterDisplay> + <ChapterDisplay> + <ChapString>Avant le crime</ChapString> + <ChapLanguage>fra</ChapLanguage> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>3430008</ChapterUID> + <ChapterTimeStart>25000000000</ChapterTimeStart> + <ChapterTimeEnd>27500000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>The crime</ChapString> + </ChapterDisplay> + <ChapterDisplay> + <ChapString>Le crime</ChapString> + <ChapLanguage>fra</ChapLanguage> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>4548489</ChapterUID> + <ChapterTimeStart>27500000000</ChapterTimeStart> + <ChapterTimeEnd>38000000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>After the crime</ChapString> + </ChapterDisplay> + <ChapterDisplay> + <ChapString>Apres le crime</ChapString> + <ChapLanguage>fra</ChapLanguage> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>5666960</ChapterUID> + <ChapterTimeStart>38000000000</ChapterTimeStart> + <ChapterTimeEnd>43000000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Credits</ChapString> + </ChapterDisplay> + <ChapterDisplay> + <ChapString>Generique</ChapString> + <ChapLanguage>fra</ChapLanguage> + </ChapterDisplay> + </ChapterAtom> + </EditionEntry> +</Chapters> ``` Figure: Basic Chapters Example @@ -291,94 +289,94 @@ of them contains another splitting. * 25:20 - 33:35: Baby wants to bleep (k) * 33:37 - 44:28: Bleeper -This would translate in the following Matroska form, with the EBML tree shown as XML: +This translates to Matroska form, with the EBML tree shown as follows in XML: ```xml - - - 1281690858003401414 - - 1 - 0 - 748000000 - - Baby wants to Bleep/Rock - - - 2 - 0 - 278000000 - - Baby wants to bleep (pt.1) - - - - 3 - 278000000 - 432000000 - - Baby wants to rock - - - - 4 - 432000000 - 633000000 - - Baby wants to bleep (pt.2) - - - - 5 - 633000000 - 748000000 - - Baby wants to bleep (pt.3) - - - - - 6 - 750000000 - 1178500000 - - Bleeper_O+2 - - - - 7 - 1180500000 - 1340000000 - - Baby wants to bleep (pt.4) - - - - 8 - 1342000000 - 1518000000 - - Bleep to bleep - - - - 9 - 1520000000 - 2015000000 - - Baby wants to bleep (k) - - - - 10 - 2017000000 - 2668000000 - - Bleeper - - - - +<Chapters> + <EditionEntry> + <EditionUID>1281690858003401414</EditionUID> + <ChapterAtom> + <ChapterUID>1</ChapterUID> + <ChapterTimeStart>0</ChapterTimeStart> + <ChapterTimeEnd>748000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Baby wants to Bleep/Rock</ChapString> + </ChapterDisplay> + <ChapterAtom> + <ChapterUID>2</ChapterUID> + <ChapterTimeStart>0</ChapterTimeStart> + <ChapterTimeEnd>278000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Baby wants to bleep (pt.1)</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>3</ChapterUID> + <ChapterTimeStart>278000000</ChapterTimeStart> + <ChapterTimeEnd>432000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Baby wants to rock</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>4</ChapterUID> + <ChapterTimeStart>432000000</ChapterTimeStart> + <ChapterTimeEnd>633000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Baby wants to bleep (pt.2)</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>5</ChapterUID> + <ChapterTimeStart>633000000</ChapterTimeStart> + <ChapterTimeEnd>748000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Baby wants to bleep (pt.3)</ChapString> + </ChapterDisplay> + </ChapterAtom> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>6</ChapterUID> + <ChapterTimeStart>750000000</ChapterTimeStart> + <ChapterTimeEnd>1178500000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Bleeper_O+2</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>7</ChapterUID> + <ChapterTimeStart>1180500000</ChapterTimeStart> + <ChapterTimeEnd>1340000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Baby wants to bleep (pt.4)</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>8</ChapterUID> + <ChapterTimeStart>1342000000</ChapterTimeStart> + <ChapterTimeEnd>1518000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Bleep to bleep</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>9</ChapterUID> + <ChapterTimeStart>1520000000</ChapterTimeStart> + <ChapterTimeEnd>2015000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Baby wants to bleep (k)</ChapString> + </ChapterDisplay> + </ChapterAtom> + <ChapterAtom> + <ChapterUID>10</ChapterUID> + <ChapterTimeStart>2017000000</ChapterTimeStart> + <ChapterTimeEnd>2668000000</ChapterTimeEnd> + <ChapterDisplay> + <ChapString>Bleeper</ChapString> + </ChapterDisplay> + </ChapterAtom> + </EditionEntry> +</Chapters> ``` Figure: Nested Chapters Example diff --git a/codec_specs.md b/codec_specs.md index c09152712..9abd39bb8 100644 --- a/codec_specs.md +++ b/codec_specs.md @@ -3,10 +3,10 @@ A `Codec Mapping` is a set of attributes to identify, name, and contextualize the format and characteristics of encoded data that can be contained within Matroska Clusters. -Each TrackEntry used within Matroska **MUST** reference a defined `Codec Mapping` using the +Each `TrackEntry` used within Matroska **MUST** reference a defined `Codec Mapping` using the `Codec ID` to identify and describe the format of the encoded data in its associated Clusters. This `Codec ID` is a unique registered identifier that represents the encoding stored within -the Track. Certain encodings **MAY** also require some form of codec initialization +the `Track`. Certain encodings **MAY** also require some form of codec initialization to provide its decoder with context and technical metadata. The intention behind this list is not to list all existing audio and video codecs, @@ -63,18 +63,18 @@ An optional description for the encoding. This value is only intended for human Each encoding supported for storage in Matroska **MUST** have a defined Initialization. The Initialization **MUST** describe the storage of data necessary to initialize the decoder, -which **MUST** be stored within the `CodecPrivate Element`. When the Initialization is updated -within a track, then that updated Initialization data **MUST** be written into the `CodecState Element` +which **MUST** be stored within the `CodecPrivate` element. When the Initialization is updated +within a track, then that updated Initialization data **MUST** be written into the `CodecState` element of the first `Cluster` to require it. If the encoding does not require any form of Initialization, -then `none` **MUST** be used to define the Initialization and the `CodecPrivate Element` +then `none` **MUST** be used to define the Initialization and the `CodecPrivate` element **SHOULD NOT** be written and **MUST** be ignored. Data that is defined Initialization to be -stored in the `CodecPrivate Element` is known as `Private Data`. +stored in the `CodecPrivate` element is known as `Private Data`. ### Codec BlockAdditions Additional data that contextualizes or supplements a `Block` can be stored within -the `BlockAdditional Element` of a `BlockMore Element`. This `BlockAdditional` data **MAY** -be passed to the associated decoder along with the content of the `Block Element`. +the `BlockAdditional` element of a `BlockMore` element. This `BlockAdditional` data **MAY** +be passed to the associated decoder along with the content of the `Block` element. Each `BlockAdditional` is coupled with a `BlockAddID` that identifies the kind of data it contains. The following table defines the meanings of `BlockAddID` values. @@ -82,13 +82,13 @@ BlockAddID Value | Definition -----------------|:--------------- 0 | Invalid. 1 | Indicates that the context of the `BlockAdditional` data is defined by the corresponding `Codec Mapping`. -2 or greater | `BlockAddID` values of 2 and greater are mapped to the `BlockAddIDValue` of the `BlockAdditionMapping` of the associated Track. +2 or greater | `BlockAddID` values of 2 and greater are mapped to the `BlockAddIDValue` of the `BlockAdditionMapping` of the associated `Track`. The values of `BlockAddID` that are 2 of greater have no semantic meaning, but simply -associate the `BlockMore Element` with a `BlockAdditionMapping` of the associated Track. -See (#block-additional-mapping) on Block Additional Mappings for more information. +associate the `BlockMore` element with a `BlockAdditionMapping` of the associated `Track`. +See (#block-additional-mapping) on `Block Additional Mappings` for more information. -The following XML depicts the nested Elements of a `BlockGroup Element` with an example of BlockAdditions: +The following XML depicts the nested elements of a `BlockGroup` element with an example of `BlockAdditions`: ```xml @@ -242,7 +242,7 @@ Codec Name: AVC/H.264 Description: Individual pictures (which could be a frame, a field, or 2 fields having the same timestamp) of AVC/H.264 stored as described in [@!ISO.14496-15]. Initialization: The `Private Data` contains a `AVCDecoderConfigurationRecord` structure, as defined in [@!ISO.14496-15]. -For legacy reasons, because Block Addition Mappings are preferred; see (#block-addition-mappings), +For legacy reasons, because `Block Additional Mappings` are preferred; see (#block-addition-mappings), the `AVCDecoderConfigurationRecord` structure **MAY** be followed by an extension block beginning with a 4-byte extension block size field in big-endian byte order which is the size of the extension block minus 4 (excluding the size of the extension block size field) and a 4-byte field corresponding @@ -445,7 +445,7 @@ Codec ID: A_PCM/INT/BIG Codec Name: PCM Integer Big Endian -Description: The audio bit depth **MUST** be read and set from the `BitDepth Element`. Audio samples **MUST** be considered as signed values, +Description: The audio bit depth **MUST** be read and set from the `BitDepth` element. Audio samples **MUST** be considered as signed values, except if the audio bit depth is 8 which **MUST** be interpreted as unsigned values. Corresponding ACM wFormatTag : ??? Initialization: none @@ -456,7 +456,7 @@ Codec ID: A_PCM/INT/LIT Codec Name: PCM Integer Little Endian -Description: The audio bit depth **MUST** be read and set from the `BitDepth Element`. Audio samples **MUST** be considered as signed values, +Description: The audio bit depth **MUST** be read and set from the `BitDepth` element. Audio samples **MUST** be considered as signed values, except if the audio bit depth is 8 which **MUST** be interpreted as unsigned values. Corresponding ACM wFormatTag : 0x0001 Initialization: none @@ -467,7 +467,7 @@ Codec ID: A_PCM/FLOAT/IEEE Codec Name: Floating-Point, IEEE compatible -Description: The audio bit depth **MUST** be read and set from the `BitDepth Element` (32 bit in most cases). +Description: The audio bit depth **MUST** be read and set from the `BitDepth` element (32 bit in most cases). The floats are stored as defined in [@!IEEE.754] and in little-endian order. Corresponding ACM wFormatTag : 0x0003 Initialization: none @@ -804,7 +804,7 @@ Codec ID: A_TTA1 Codec Name: [The True Audio](http://tausoft.org/) lossless audio compressor Description: [TTA format description](http://tausoft.org/wiki/True_Audio_Codec_Format) -Each frame is kept intact, including the CRC32. The header and seektable are dropped. SamplingFrequency, Channels and BitDepth are used in the TrackEntry. wFormatTag = 0x77A1 +Each frame is kept intact, including the CRC32. The header and seektable are dropped. `SamplingFrequency`, `Channels` and `BitDepth` are used in the `TrackEntry`. wFormatTag = 0x77A1 Initialization: none @@ -849,7 +849,7 @@ Codec ID: S_TEXT/SSA Codec Name: Subtitles Format -Description: The [Script Info] and [V4 Styles] sections are stored in the codecprivate. Each event is stored in its own Block. +Description: The [Script Info] and [V4 Styles] sections are stored in the codecprivate. Each event is stored in its own `Block`. For more information see (#ssa-ass-subtitles) on SSA/ASS. ### S_TEXT/ASS @@ -858,7 +858,7 @@ Codec ID: S_TEXT/ASS Codec Name: Advanced Subtitles Format -Description: The [Script Info] and [V4 Styles] sections are stored in the codecprivate. Each event is stored in its own Block. +Description: The [Script Info] and [V4 Styles] sections are stored in the codecprivate. Each event is stored in its own `Block`. For more information see (#ssa-ass-subtitles) on SSA/ASS. ### S_TEXT/WEBVTT diff --git a/control.md b/control.md index e0bf7c5db..9b1d0841c 100644 --- a/control.md +++ b/control.md @@ -4,7 +4,7 @@ When the `EditionFlagHidden` flag is set to `false` it means the `Edition` is visible and selectable in a `Matroska Player`. -All `ChapterAtoms Elements` **MUST** be interpreted with their own `ChapterFlagHidden` flags. +All `ChapterAtoms` elements **MUST** be interpreted with their own `ChapterFlagHidden` flags. ChapterFlagHidden | False | True | visible :-----------------|:------|:-----|:------- @@ -15,7 +15,7 @@ Table: ChapterAtom Visibility To The User{#chapterVisibility} When the `EditionFlagHidden` flag is set to `true` the `Edition` is hidden and **SHOULD NOT** be selectable in a `Matroska Player`. If all `Editions` `EditionFlagHidden` flags are set to `true`, there is no visible `Edition`. -In this case all `ChapterAtoms Elements` **MUST** also be interpreted as if their `ChapterFlagHidden` +In this case all `ChapterAtoms` elements **MUST** also be interpreted as if their `ChapterFlagHidden` flag is also set to `true`, regardless with their own `ChapterFlagHidden` flags. ChapterFlagHidden | False | True | visible @@ -120,7 +120,7 @@ Chapter 2 | false | no # Matroska Schema -Extra elements used to handle Control Tracks and advanced selection features: +Extra elements used to handle Control `Tracks` and advanced selection features: ## Segment ### Chapters diff --git a/cues.md b/cues.md index 663042517..21dfb6dfc 100644 --- a/cues.md +++ b/cues.md @@ -1,11 +1,11 @@ # Cues -The `Cues Element` provides an index of certain `Cluster Elements` to allow for optimized -seeking to absolute timestamps within the `Segment`. The `Cues Element` contains one or -many `CuePoint Elements`, each of which **MUST** reference an absolute timestamp (via the -`CueTime Element`), a `Track` (via the `CueTrack Element`), and a `Segment Position` -(via the `CueClusterPosition Element`). Additional non-mandated Elements are part of -the `CuePoint Element`, such as `CueDuration`, `CueRelativePosition`, `CueCodecState`, +The `Cues` element provides an index of certain `Cluster` elements to allow for optimized +seeking to absolute timestamps within the `Segment`. The `Cues` element contains one or +many `CuePoint` elements, each of which **MUST** reference an absolute timestamp (via the +`CueTime` element), a `Track` (via the `CueTrack` element), and a `Segment Position` +(via the `CueClusterPosition` element). Additional non-mandated elements are part of +the `CuePoint` element, such as `CueDuration`, `CueRelativePosition`, `CueCodecState`, and others that provide any `Matroska Reader` with additional information to use in the optimization of seeking performance. @@ -13,26 +13,26 @@ the optimization of seeking performance. The following recommendations are provided to optimize Matroska performance. -- Unless Matroska is used as a live stream, it **SHOULD** contain a `Cues Element`. +- Unless Matroska is used as a live stream, it **SHOULD** contain a `Cues` element. -- For each video track, each keyframe **SHOULD** be referenced by a `CuePoint Element`. +- For each video track, each keyframe **SHOULD** be referenced by a `CuePoint` element. - It is **RECOMMENDED** to not reference non-keyframes of video tracks in `Cues` unless - it references a `Cluster Element` that contains a `CodecState Element` but no keyframes. + it references a `Cluster` element that contains a `CodecState` element but no keyframes. - For each subtitle track present, each subtitle frame **SHOULD** be referenced by a - `CuePoint Element` with a `CueDuration Element`. + `CuePoint` element with a `CueDuration` element. -- References to audio tracks **MAY** be skipped in `CuePoint Elements` if a video track - is present. When included, the `CuePoint Elements` **SHOULD** reference audio keyframes +- References to audio tracks **MAY** be skipped in `CuePoint` elements if a video track + is present. When included, the `CuePoint` elements **SHOULD** reference audio keyframes once every 500 milliseconds at most. - If the referenced frame is not stored within the first `SimpleBlock` or first - `BlockGroup` within its `Cluster Element`, then the `CueRelativePosition Element` + `BlockGroup` within its `Cluster` element, then the `CueRelativePosition` element **SHOULD** be written to reference where in the `Cluster` the reference frame is stored. -- If a `CuePoint Element` references a `Cluster Element` that includes a `CodecState Element`, - then that `CuePoint Element` **MUST** use a `CueCodecState Element`. +- If a `CuePoint` element references a `Cluster` element that includes a `CodecState` element, + then that `CuePoint` element **MUST** use a `CueCodecState` element. -- `CuePoint Elements` **SHOULD** be numerically sorted in storage order by the value of the `CueTime Element`. +- `CuePoint` elements **SHOULD** be numerically sorted in storage order by the value of the `CueTime` element. diff --git a/diagram.md b/diagram.md index 2836fec3e..989efc2cd 100644 --- a/diagram.md +++ b/diagram.md @@ -18,10 +18,10 @@ A more complex Matroska file consisting of an `EBML Stream` (consisting of two ` - `Segment` The following diagram represents a simple Matroska file, comprised of an `EBML Document` -with an `EBML Header`, a `Segment Element` (the `Root Element`), and all eight Matroska +with an `EBML Header`, a `Segment` element (the `Root Element`), and all eight Matroska `Top-Level Elements`. In the diagrams in this section, horizontal spacing expresses -a parent-child relationship between Matroska Elements (e.g., the `Info Element` is contained within -the `Segment Element`), whereas vertical alignment represents the storage order within the file. +a parent-child relationship between Matroska elements (e.g., the `Info` element is contained within +the `Segment` element), whereas vertical alignment represents the storage order within the file. ``` +-------------+ @@ -64,11 +64,11 @@ The Matroska `EBML Schema` defines eight `Top-Level Elements`: - `Tags` ((#tags)) -The `SeekHead Element` (also known as `MetaSeek`) contains an index of `Top-Level Elements` -locations within the `Segment`. Use of the `SeekHead Element` is **RECOMMENDED**. Without a `SeekHead Element`, +The `SeekHead` element (also known as `MetaSeek`) contains an index of `Top-Level Elements` +locations within the `Segment`. Use of the `SeekHead` element is **RECOMMENDED**. Without a `SeekHead` element, a Matroska parser would have to search the entire file to find all of the other `Top-Level Elements`. This is due to Matroska's flexible ordering requirements; for instance, it is acceptable for -the `Chapters Element` to be stored after the `Cluster Elements`. +the `Chapters` element to be stored after the `Cluster ` element(s). ``` +--------------------------------+ @@ -77,11 +77,11 @@ the `Chapters Element` to be stored after the `Cluster Elements`. | | | SeekPosition | +--------------------------------+ ``` -Figure: Representation of a `SeekHead Element` +Figure: Representation of a `SeekHead` Element -The `Info Element` contains vital information for identifying the whole `Segment`. +The `Info` element contains vital information for identifying the whole `Segment`. This includes the title for the `Segment`, a randomly generated unique identifier (UID), -and the UID(s) of any linked `Segment Elements`. +and the UID(s) of any linked `Segment` elements. ``` +-------------------------+ @@ -114,17 +114,17 @@ and the UID(s) of any linked `Segment Elements`. | | WritingApp | |-------------------------| ``` -Figure: Representation of an `Info Element` and Its `Child Elements` +Figure: Representation of an `Info` Element and Its `Child Elements` -The `Tracks Element` defines the technical details for each track and can store the name, +The `Tracks` element defines the technical details for each track and can store the name, number, UID, language, and type (audio, video, subtitles, etc.) of each track. -For example, the `Tracks Element` **MAY** store information about the resolution of a video track +For example, the `Tracks` element **MAY** store information about the resolution of a video track or sample rate of an audio track. -The `Tracks Element` **MUST** identify all the data needed by the codec to decode the data of the +The `Tracks` element **MUST** identify all the data needed by the codec to decode the data of the specified track. However, the data required is contingent on the codec used for the track. -For example, a `Track Element` for uncompressed audio only requires the audio bit rate to be present. -A codec such as AC-3 would require that the `CodecID Element` be present for all tracks, +For example, a `Track` element for uncompressed audio only requires the audio bit rate to be present. +A codec such as AC-3 would require that the `CodecID` element be present for all tracks, as it is the primary way to identify which codec to use to decode the track. ``` @@ -163,7 +163,7 @@ as it is the primary way to identify which codec to use to decode the track. | | | |-------------------| | | | | AspectRatioType | | | | |-------------------| -| | | | Color | +| | | | Colour | | | |----------------------------------| | | | Audio | SamplingFrequency | | | | |-------------------| @@ -173,9 +173,9 @@ as it is the primary way to identify which codec to use to decode the track. |--------------------------------------------------------| ``` -Figure: Representation of the `Tracks Element` and a Selection of Its `Descendant Elements` +Figure: Representation of the `Tracks` Element and a Selection of Its `Descendant` Elements -The `Chapters Element` lists all of the chapters. Chapters are a way to set predefined +The `Chapters` element lists all of the chapters. `Chapters` are a way to set predefined points to jump to in video or audio. ``` @@ -201,23 +201,24 @@ points to jump to in video or audio. | | | | | ChapLanguage | +------------------------------------------------------------------+ ``` -Figure: Representation of the `Chapters Element` and a Selection of Its `Descendant Elements` +Figure: Representation of the `Chapters` Element and a Selection of Its `Descendant` Elements -`Cluster Elements` contain the content for each track, e.g., video frames. A Matroska file -**SHOULD** contain at least one `Cluster Element`. -In the rare case it doesn't, there should be a form of Segment linking with other Segments, possibly using Chapters; see (#linked-segments). +`Cluster` elements contain the content for each track, e.g., video frames. A Matroska file +**SHOULD** contain at least one `Cluster` element. +In the rare case it doesn't, there should be a method for `Segments` to link +together, possibly using `Chapters`; see (#linked-segments). -The `Cluster Element` helps to break up -`SimpleBlock` or `BlockGroup Elements` and helps with seeking and error protection. -Every `Cluster Element` **MUST** contain a `Timestamp Element`. -This **SHOULD** be the `Timestamp Element` used to play the first `Block` in the `Cluster Element`, -unless a different value is needed to accommodate for more Blocks; see (#block-timestamps). +The `Cluster` element helps to break up +`SimpleBlock` or `BlockGroup` elements and helps with seeking and error protection. +Every `Cluster` element **MUST** contain a `Timestamp` element. +This **SHOULD** be the `Timestamp` element used to play the first `Block` in the `Cluster` element, +unless a different value is needed to accommodate for more `Blocks`; see (#block-timestamps). -`Cluster Elements` contain one or more block element, such as `BlockGroup` or `SimpleBlock` elements. -In some situations, a `Cluster Element` **MAY** contain no block element, for example, in a live recording +`Cluster` elements contain one or more `Block` element, such as `BlockGroup` or `SimpleBlock` elements. +In some situations, a `Cluster` element **MAY** contain no `Block` element, for example, in a live recording when no data has been collected. - A `BlockGroup Element` **MAY** contain a `Block` of data and any information relating directly to that `Block`. + A `BlockGroup` element **MAY** contain a `Block` of data and any information relating directly to that `Block`. ``` +--------------------------+ @@ -232,7 +233,7 @@ when no data has been collected. | | BlockGroup | +--------------------------+ ``` -Figure: Representation of a `Cluster Element` and Its Immediate `Child Elements` +Figure: Representation of a `Cluster` Element and Its Immediate `Child Elements` ``` +----------------------------------+ @@ -253,35 +254,35 @@ Figure: Representation of a `Cluster Element` and Its Immediate `Child Elements` | | Data | Frame | +----------------------------------+ ``` -Figure: Representation of the `Block Element` Structure +Figure: Representation of the `Block` Element Structure -Each `Cluster` **MUST** contain exactly one `Timestamp Element`. The `Timestamp Element` value **MUST** -be stored once per `Cluster`. The `Timestamp Element` in the `Cluster` is relative to the entire `Segment`. -The `Timestamp Element` **SHOULD** be the first `Element` in the `Cluster` it belongs to -or the second `Element` if that Cluster contains a CRC-32 element ((#crc-32)) +Each `Cluster` **MUST** contain exactly one `Timestamp` element. The `Timestamp` element value **MUST** +be stored once per `Cluster`. The `Timestamp` element in the `Cluster` is relative to the entire `Segment`. +The `Timestamp` element **SHOULD** be the first element in the `Cluster` it belongs to +or the second element if that `Cluster` contains a `CRC-32` element ((#crc-32)). -Additionally, the `Block` contains an offset that, when added to the `Cluster`'s `Timestamp Element` value, +Additionally, the `Block` contains an offset that, when added to the `Cluster`'s `Timestamp` element value, yields the `Block`'s effective timestamp. Therefore, the timestamp in the `Block` itself is relative to -the `Timestamp Element` in the `Cluster`. For example, if the `Timestamp Element` in the `Cluster` +the `Timestamp` element in the `Cluster`. For example, if the `Timestamp` element in the `Cluster` is set to 10 seconds and a `Block` in that `Cluster` is supposed to be played 12 seconds into the clip, the timestamp in the `Block` would be set to 2 seconds. The `ReferenceBlock` in the `BlockGroup` is used instead of the basic "P-frame"/"B-frame" description. Instead of simply saying that this `Block` depends on the `Block` directly before or directly after, -the `Timestamp` of the necessary `Block` is used. Because there can be as many `ReferenceBlock Elements` +the `Timestamp` of the necessary `Block` is used. Because there can be as many `ReferenceBlock` elements as necessary for a `Block`, it allows for some extremely complex referencing. -The `Cues Element` is used to seek when playing back a file by providing a temporal index -for some of the `Tracks`. It is similar to the `SeekHead Element` but is used for seeking to +The `Cues` element is used to seek when playing back a file by providing a temporal index +for some of the `Tracks`. It is similar to the `SeekHead` element but is used for seeking to a specific time when playing back the file. It is possible to seek without this element, but it is much more difficult because a `Matroska Reader` would have to "hunt and peck" through the file to look for the correct timestamp. -The `Cues Element` **SHOULD** contain at least one `CuePoint Element`. Each `CuePoint Element` -stores the position of the `Cluster` that contains the `BlockGroup` or `SimpleBlock Element`. -The timestamp is stored in the `CueTime Element`, and the location is stored in the `CueTrackPositions Element`. +The `Cues` element **SHOULD** contain at least one `CuePoint` element. Each `CuePoint` element +stores the position of the `Cluster` that contains the `BlockGroup` or `SimpleBlock` element. +The timestamp is stored in the `CueTime` element, and the location is stored in the `CueTrackPositions` element. -The `Cues Element` is flexible. For instance, the `Cues Element` can be used to index every +The `Cues` element is flexible. For instance, the `Cues` element can be used to index every single timestamp of every `Block` or they can be indexed selectively. ``` @@ -295,9 +296,9 @@ single timestamp of every `Block` or they can be indexed selectively. | | | CueTrackPositions | +-------------------------------------+ ``` -Figure: Representation of a `Cues Element` and Two Levels of Its `Descendant Elements` +Figure: Representation of a `Cues` Element and Two Levels of Its `Descendant` Elements -The `Attachments Element` is for attaching files to a Matroska file, such as pictures, +The `Attachments` element is for attaching files to a Matroska file, such as pictures, fonts, web pages, etc. ``` @@ -311,24 +312,15 @@ fonts, web pages, etc. | | | FileData | | | |-------------------| | | | FileUID | -| | |-------------------| -| | | FileName | -| | |-------------------| -| | | FileReferral | -| | |-------------------| -| | | FileUsedStartTime | -| | |-------------------| -| | | FileUsedEndTime | +------------------------------------------------+ ``` -Figure: Representation of an `Attachments Element` +Figure: Representation of an `Attachments` Element -The `Tags Element` contains metadata that describes the `Segment` and potentially +The `Tags` element contains metadata that describes the `Segment` and potentially its `Tracks`, `Chapters`, and `Attachments`. Each `Track` or `Chapter` that those tags applies to has its UID listed in the `Tags`. The `Tags` contain all extra information about the file: scriptwriters, singers, actors, directors, titles, edition, price, dates, genre, comments, -etc. Tags can contain their values in multiple languages. For example, a movie's "title" `Tag` -might contain both the original English title as well as the title it was released as in Germany. +etc. `Tags` can contain their values in multiple languages. For example, a movie's "TITLE" tag value might contain both the original English title as well as the German title. ``` +-------------------------------------------+ @@ -357,5 +349,5 @@ might contain both the original English title as well as the title it was releas | | | | SimpleTag | +-------------------------------------------+ ``` -Figure: Representation of a `Tags Element` and Three Levels of Its `Children Elements` +Figure: Representation of a `Tags` Element and Three Levels of Its `Children Elements` diff --git a/ebml_matroska.xml b/ebml_matroska.xml index 8f888bcc6..916bdce34 100644 --- a/ebml_matroska.xml +++ b/ebml_matroska.xml @@ -4,11 +4,11 @@ - The Root Element that contains all other Top-Level Elements; see (#data-layout). + The `Root Element` that contains all other `Top-Level Elements`; see (#data-layout). - Contains seeking information of Top-Level Elements; see (#data-layout). + Contains seeking information of `Top-Level Elements`; see (#data-layout). @@ -16,66 +16,67 @@ - The binary EBML ID of a Top-Level Element. + The binary EBML ID of a `Top-Level Element`. - The Segment Position ((#segment-position)) of a Top-Level Element. + The `Segment Position` ((#segment-position)) of a `Top-Level Element`. - Contains general information about the Segment. + Contains general information about the `Segment`. - A randomly generated UID that identifies the Segment amongst many others (128 bits). It is equivalent to a Universally Unique Identifier (UUID) v4 [@!RFC4122] with all bits randomly (or pseudorandomly) chosen. An actual UUID v4 value, where some bits are not random, **MAY** also be used. - If the Segment is a part of a Linked Segment, then this Element is **REQUIRED**. + A randomly generated UID that identifies the `Segment` amongst many others (128 bits). It is equivalent to a Universally Unique Identifier (UUID) v4 [@!RFC4122] with all bits randomly (or pseudorandomly) chosen. An actual UUID v4 value, where some bits are not random, **MAY** also be used. + If the `Segment` is a part of a `Linked Segment`, then this element is **REQUIRED**. The value of the UID **MUST** contain at least one bit set to 1. - A filename corresponding to this Segment. + A filename corresponding to this `Segment`. - An ID that identifies the previous Segment of a Linked Segment. - If the Segment is a part of a Linked Segment that uses Hard Linking ((#hard-linking)), -then either the PrevUUID or the NextUUID Element is **REQUIRED**. If a Segment contains a PrevUUID but not a NextUUID, -then it **MAY** be considered as the last Segment of the Linked Segment. The PrevUUID **MUST NOT** be equal to the SegmentUUID. + An ID that identifies the previous `Segment` of a `Linked Segment`. + If the `Segment` is a part of a `Linked Segment` that uses +Hard Linking ((#hard-linking)), +then either the `PrevUUID` or the `NextUUID` element is **REQUIRED**. If a `Segment` contains a `PrevUUID` but not a `NextUUID`, +then it **MAY** be considered as the last `Segment` of the `Linked Segment`. The `PrevUUID` **MUST NOT** be equal to the `SegmentUUID`. - A filename corresponding to the file of the previous Linked Segment. + A filename corresponding to the file of the previous `Linked Segment`. Provision of the previous filename is for display convenience, -but PrevUUID **SHOULD** be considered authoritative for identifying the previous Segment in a Linked Segment. +but `PrevUUID` **SHOULD** be considered authoritative for identifying the previous `Segment` in a `Linked Segment`. - An ID that identifies the next Segment of a Linked Segment. - If the Segment is a part of a Linked Segment that uses Hard Linking ((#hard-linking)), -then either the PrevUUID or the NextUUID Element is **REQUIRED**. If a Segment contains a NextUUID but not a PrevUUID, -then it **MAY** be considered as the first Segment of the Linked Segment. The NextUUID **MUST NOT** be equal to the SegmentUUID. + An ID that identifies the next `Segment` of a `Linked Segment`. + If the `Segment` is a part of a `Linked Segment` that uses Hard Linking ((#hard-linking)), +then either the `PrevUUID` or the `NextUUID` element is **REQUIRED**. If a `Segment` contains a `NextUUID` but not a `PrevUUID`, +then it **MAY** be considered as the first `Segment` of the `Linked Segment`. The `NextUUID` **MUST NOT** be equal to the `SegmentUUID`. - A filename corresponding to the file of the next Linked Segment. + A filename corresponding to the file of the next `Linked Segment`. Provision of the next filename is for display convenience, -but NextUUID **SHOULD** be considered authoritative for identifying the Next Segment. +but `NextUUID` **SHOULD** be considered authoritative for identifying the Next `Segment`. - A UID that all Segments of a Linked Segment **MUST** share (128 bits). It is equivalent to a UUID v4 [@!RFC4122] with all bits randomly (or pseudorandomly) chosen. An actual UUID v4 value, where some bits are not random, **MAY** also be used. - If the Segment Info contains a `ChapterTranslate` element, this Element is **REQUIRED**. + A UID that all `Segments` of a `Linked Segment` **MUST** share (128 bits). It is equivalent to a UUID v4 [@!RFC4122] with all bits randomly (or pseudorandomly) chosen. An actual UUID v4 value, where some bits are not random, **MAY** also be used. + If the `Segment` `Info` contains a `ChapterTranslate` element, this element is **REQUIRED**. The mapping between this `Segment` and a segment value in the given Chapter Codec. - Chapter Codec may need to address different segments, but they may not know of the way to identify such segments when stored in Matroska. -This element and its child elements add a way to map the internal segments known to the Chapter Codec to the Segment IDs in Matroska. -This allows remuxing a file with Chapter Codec without changing the content of the codec data, just the Segment mapping. + Chapter Codecs may need to address different segments, but they may not know of the way to identify such segments when stored in Matroska. +This element and its child elements add a way to map the internal segments known to the Chapter Codec to the `SegmentUUID`s in Matroska. +This allows remuxing a file with Chapter Codec without changing the content of the codec data, just the `Segment` mapping. - The binary value used to represent this Segment in the chapter codec data. -The format depends on the ChapProcessCodecID used; see (#chapprocesscodecid-element). + The binary value used to represent this `Segment` in the chapter codec data. +The format depends on the `ChapProcessCodecID` used; see (#chapprocesscodecid-element). - This `ChapterTranslate` applies to the chapter codec of the given chapter edition(s); see (#chapprocesscodecid-element). + Applies to the chapter codec of the given chapter edition(s); see (#chapprocesscodecid-element). Chapter commands using the Matroska Script codec. @@ -87,23 +88,23 @@ The format depends on the ChapProcessCodecID used; see (#chapprocesscodecid-elem Specifies a chapter edition UID to which this `ChapterTranslate` applies. - When no `ChapterTranslateEditionUID` is specified in the `ChapterTranslate`, the `ChapterTranslate` applies to all chapter editions found in the Segment using the given `ChapterTranslateCodec`. + When no `ChapterTranslateEditionUID` is specified in the `ChapterTranslate`, the `ChapterTranslate` applies to all chapter editions found in the `Segment` using the given `ChapterTranslateCodec`. - Base unit for Segment Ticks and Track Ticks, in nanoseconds. A TimestampScale value of 1000000 means scaled timestamps in the Segment are expressed in milliseconds; see (#timestamps) on how to interpret timestamps. + Base unit for Segment Ticks and Track Ticks, in nanoseconds. A `TimestampScale` value of 1000000 means scaled timestamps in the `Segment` are expressed in milliseconds; see (#timestamps) on how to interpret timestamps. - Duration of the Segment, expressed in Segment Ticks, which are based on TimestampScale; see (#timestamp-ticks). + Duration of the `Segment`, expressed in `Segment` Ticks, which are based on `TimestampScale`; see (#timestamp-ticks). - The date and time that the Segment was created by the muxing application or library. + The date and time that the `Segment` was created by the muxing application or library. - General name of the Segment. + General name of the `Segment`. @@ -117,13 +118,13 @@ The format depends on the ChapProcessCodecID used; see (#chapprocesscodecid-elem - The Top-Level Element containing the (monolithic) Block structure. + The `Top-Level Element` containing the (monolithic) `Block` structure. - Absolute timestamp of the cluster, expressed in Segment Ticks, which are based on TimestampScale; see (#timestamp-ticks). - This element **SHOULD** be the first child element of the Cluster it belongs to -or the second if that Cluster contains a CRC-32 element ((#crc-32)). + Absolute timestamp of the cluster, expressed in Segment Ticks, which are based on `TimestampScale`; see (#timestamp-ticks). + This element **SHOULD** be the first child element of the `Cluster` it belongs to +or the second if that `Cluster` contains a `CRC-32` element ((#crc-32)). @@ -134,66 +135,66 @@ It is useful when using overlay tracks for seeking or deciding what track to use One of the track numbers that is not used from now on in the stream. -It could change later if not specified as silent in a further Cluster. +It could change later if not specified as silent in a further `Cluster`. - The Segment Position of the Cluster in the Segment (0 in live streams). + The `Segment Position` of the `Cluster` in the `Segment` (0 in live streams). It might help to resynchronize the offset on damaged streams. - Size of the previous Cluster, in octets. Can be useful for backward playing. + Size of the previous `Cluster`, in octets. Can be useful for backward playing. - Similar to Block (see (#block-structure)) but without all the extra information. -Mostly used to reduce overhead when no extra feature is needed; see (#simpleblock-structure) on SimpleBlock Structure. + Similar to `Block` (see (#block-structure)) but without all the extra information. +Mostly used to reduce overhead when no extra feature is needed; see (#simpleblock-structure) on `SimpleBlock` Structure. - Basic container of information containing a single Block and information specific to that Block. + Basic container of information containing a single `Block` and information specific to that `Block`. - Block containing the actual data to be rendered and a timestamp relative to the Cluster Timestamp; -see (#block-structure) on Block Structure. + `Block` containing the actual data to be rendered and a timestamp relative to the `Cluster` Timestamp; +see (#block-structure) on `Block` Structure. - A Block with no data. It must be stored in the stream at the place the real Block would be in display order. + A `Block` with no data. It must be stored in the stream at the place the real `Block` would be in display order. - Contains additional binary data to complete the main one; see [@?I-D.ietf-cellar-codec, section 4.1.5] for more information. -An EBML parser that has no knowledge of the Block structure could still see and use/skip these data. + Contains additional binary data to complete the `Block` element; see [@?I-D.ietf-cellar-codec, section 4.1.5] for more information. +An EBML parser that has no knowledge of the `Block` structure could still see and use/skip these data. - Contains the BlockAdditional and some parameters. + Contains the `BlockAdditional` and some parameters. - Interpreted by the codec as it wishes (using the BlockAddID). + Interpreted by the codec as it wishes (using the `BlockAddID`). - An ID that identifies how to interpret the BlockAdditional data; see [@?I-D.ietf-cellar-codec, section 4.1.5] for more information. -A value of 1 indicates that the meaning of the BlockAdditional data is defined by the codec. -Any other value indicates the meaning of the BlockAdditional data is found in the BlockAddIDType found in the TrackEntry. - Each BlockAddID value **MUST** be unique between all BlockMore elements found in a BlockAdditions. - To keep MaxBlockAdditionID as low as possible, small values **SHOULD** be used. + An ID that identifies how to interpret the `BlockAdditional` data; see [@?I-D.ietf-cellar-codec, section 4.1.5] for more information. +A value of 1 indicates that the `BlockAdditional` data is defined by the codec. +Any other value indicates that the `BlockAdditional` data should be handled according to the `BlockAddIDType` that is located in the +`TrackEntry`. + Each `BlockAddID` value **MUST** be unique between all `BlockMore` elements found in a `BlockAdditions` element. To keep `MaxBlockAdditionID` as low as possible, small values **SHOULD** be used. - The duration of the Block, expressed in Track Ticks; see (#timestamp-ticks). -The BlockDuration Element can be useful at the end of a Track to define the duration of the last frame (as there is no subsequent Block available) + The duration of the `Block`, expressed in Track Ticks; see (#timestamp-ticks). +The `BlockDuration` element can be useful at the end of a `Track` to define the duration of the last frame (as there is no subsequent `Block` available) or when there is a break in a track like for subtitle tracks. - BlockDuration **MUST** be set (minOccurs=1) if the associated TrackEntry stores a DefaultDuration value. - When not written and with no DefaultDuration, the value is assumed to be the difference between the timestamp of this Block and the timestamp of the next Block in "display" order (not coding order). + `BlockDuration` **MUST** be set (minOccurs=1) if the associated `TrackEntry` stores a `DefaultDuration` value. + If a value is not present and no `DefaultDuration` is defined, the value is assumed to be the difference between the timestamp of this `Block` and the timestamp of the next `Block` in "display" order (not coding order). @@ -201,39 +202,39 @@ or when there is a break in a track like for subtitle tracks. In the cache, only a frame of the same or higher priority can replace this frame. A value of 0 means the frame is not referenced. - A timestamp value, relative to the timestamp of the Block in this BlockGroup, expressed in Track Ticks; see (#timestamp-ticks). + A timestamp value, relative to the timestamp of the `Block` in this `BlockGroup`, expressed in Track Ticks; see (#timestamp-ticks). This is used to reference other frames necessary to decode this frame. The relative value **SHOULD** correspond to a valid `Block` that this `Block` depends on. -Historically, Matroska Writers didn't write the actual `Block(s)` that this `Block` depends on, but they did write *some* `Block(s)` in the past. +Historically, `Matroska Writers` didn't write the actual `Block(s)` that this `Block` depends on, but they did write *some* `Block(s)` in the past. -The value "0" **MAY** also be used to signify that this `Block` cannot be decoded on its own, but without knowledge of which `Block` is necessary. In this case, other `ReferenceBlock` Elements **MUST NOT** be found in the same `BlockGroup`. +The value "0" **MAY** also be used to signify that this `Block` cannot be decoded on its own, but the necessary reference `Block(s)` is unknown. In this case, other `ReferenceBlock` elements **MUST NOT** be found in the same `BlockGroup`. If the `BlockGroup` doesn't have a `ReferenceBlock` element, then the `Block` it contains can be decoded without using any other `Block` data. - The Segment Position of the data that would otherwise be in position of the virtual block. + The `Segment Position` of the data that would otherwise be in position of the virtual block. The new codec state to use. Data interpretation is private to the codec. This information **SHOULD** always be referenced by a seek entry. - Duration of the silent data added to the Block, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks) -(padding at the end of the Block for positive values and at the beginning of the Block for negative values). -The duration of DiscardPadding is not calculated in the duration of the TrackEntry and **SHOULD** be discarded during playback. + Duration of the silent data added to the `Block`, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks) +(padding at the end of the `Block` for positive values and at the beginning of the `Block` for negative values). +The duration of `DiscardPadding` is not calculated in the duration of the `TrackEntry` and **SHOULD** be discarded during playback. Contains slices description. - Contains extra time information about the data contained in the Block. -Being able to interpret this Element is not required for playback. + Contains extra time information about the data contained in the `Block`. +Being able to interpret this element is not required for playback. The reverse number of the frame in the lace (0 is the last frame, 1 is the next to last, etc.). -Being able to interpret this Element is not required for playback. +Being able to interpret this element is not required for playback. @@ -242,52 +243,53 @@ Being able to interpret this Element is not required for playback. - The ID of the BlockAdditional Element (0 is the main Block). + The ID of the `BlockAdditional` element (0 is the main `Block`). - The delay to apply to the Element, expressed in Track Ticks; see (#timestamp-ticks). + The delay to apply to the element, expressed in Track Ticks; see (#timestamp-ticks). - The duration to apply to the Element, expressed in Track Ticks; see (#timestamp-ticks). + The duration to apply to the element, expressed in Track Ticks; see (#timestamp-ticks). Contains information about the last reference frame. See [@?DivXTrickTrack]. - The relative offset, in bytes, from the previous BlockGroup element for this Smooth FF/RW video track to the containing BlockGroup element. See [@?DivXTrickTrack]. + The relative offset, in bytes, from the previous `BlockGroup` element for this Smooth FF/RW video track to the containing `BlockGroup` +element. See [@?DivXTrickTrack]. - The timestamp of the BlockGroup pointed to by ReferenceOffset, expressed in Track Ticks; see (#timestamp-ticks). See [@?DivXTrickTrack]. + The timestamp of the `BlockGroup` pointed to by ReferenceOffset, expressed in Track Ticks; see (#timestamp-ticks). See [@?DivXTrickTrack]. - Similar to SimpleBlock (see (#simpleblock-structure)), -but the data inside the Block are Transformed (encrypted and/or signed). + Similar to `SimpleBlock` (see (#simpleblock-structure)), +but the data inside the `Block` are Transformed (encrypted and/or signed). - A Top-Level Element of information with many tracks described. + A `Top-Level Element` of information with many tracks described. - Describes a track with all Elements. + Describes a track with all elements. - The track number as used in the Block Header. + The track number as used in the `Block` Header. - A UID that identifies the Track. + A UID that identifies the `Track`. - The `TrackType` defines the type of each frame found in the Track. + The `TrackType` defines the type of each frame found in the `Track`. The value **SHOULD** be stored on 1 octet. @@ -297,7 +299,7 @@ The value **SHOULD** be stored on 1 octet. Audio samples. - A mix of different other TrackType. The codec needs to define how the `Matroska Player` should interpret such data. + A mix of different other `TrackType`. The codec needs to define how the `Matroska Player` should interpret such data. An image to be rendered over the video track(s). @@ -324,12 +326,12 @@ The value **SHOULD** be stored on 1 octet. - Set if the track (audio, video, or subs) is eligible for automatic selection by the player; see (#default-track-selection) for more details. + Set to 1 if the track (audio, video, or subtitles) is eligible for automatic selection by the player; see (#default-track-selection) for more details. - Applies only to subtitles. Set if the track is eligible for automatic selection by the player if it matches the user's language preference, + Applies only to subtitles. Set to 1 if the track is eligible for automatic selection by the player if it matches the user's language preference, even if the user's preferences would not normally enable subtitles with the selected audio track; this can be used for tracks containing only translations of audio in foreign languages or on-screen text. See (#default-track-selection) for more details. @@ -352,7 +354,7 @@ See (#default-track-selection) for more details. Set to 1 if and only if the track contains commentary. - Set to 1 if the track **MAY** contain blocks that use lacing. When set to 0, all blocks **MUST** have their lacing flags set to "no lacing"; see (#block-lacing) on Block Lacing. + Set to 1 if the track **MAY** contain blocks that use lacing. When set to 0, all blocks **MUST** have their lacing flags set to "no lacing"; see (#block-lacing) on `Block` Lacing. @@ -368,7 +370,7 @@ If set to 0, the reference pseudo-cache system is not used. Number of nanoseconds per frame, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks) -("frame" in the Matroska sense -- one Element put into a (Simple)Block). +("frame" in the Matroska sense -- one element put into a (Simple)Block). @@ -386,36 +388,36 @@ See (#defaultdecodedfieldduration) for more information. - A value to add to the Block's Timestamp, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks). + A value to add to the `Block`'s Timestamp, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks). This can be used to adjust the playback offset of a track. - The maximum value of BlockAddID ((#blockaddid-element)). -A value of 0 means there is no BlockAdditions ((#blockadditions-element)) for this track. + The maximum value of `BlockAddID` ((#blockaddid-element)). +A value of 0 means there is no `BlockAdditions` ((#blockadditions-element)) for this track. Contains elements that extend the track format by adding content either to each frame, -with BlockAddID ((#blockaddid-element)), or to the track as a whole -with BlockAddIDExtraData. +with `BlockAddID` ((#blockaddid-element)), or to the track as a whole +with `BlockAddIDExtraData`. If the track format extension needs content beside frames, -the value refers to the BlockAddID ((#blockaddid-element)) value being described. - To keep MaxBlockAdditionID as low as possible, small values **SHOULD** be used. +the value refers to the `BlockAddID` ((#blockaddid-element)) value being described. + To keep `MaxBlockAdditionID` as low as possible, small values **SHOULD** be used. - A human-friendly name describing the type of BlockAdditional data, -as defined by the associated Block Additional Mapping. + A human-friendly name describing the type of `BlockAdditional` data, +as defined by the associated `Block Additional Mapping`. - Stores the registered identifier of the Block Additional Mapping -to define how the BlockAdditional data should be handled. - If BlockAddIDType is 0, the BlockAddIDValue and corresponding BlockAddID values **MUST** be 1. + Stores the registered identifier of the `Block Additional Mapping` +to define how the `BlockAdditional` data should be handled. + If `BlockAddIDType` is 0, the `BlockAddIDValue` and corresponding `BlockAddID` values **MUST** be 1. - Extra binary data that the BlockAddIDType can use to interpret the BlockAdditional data. -The interpretation of the binary data depends on the BlockAddIDType value and the corresponding Block Additional Mapping. + Extra binary data that the `BlockAddIDType` can use to interpret the `BlockAdditional` data. +The interpretation of the binary data depends on the `BlockAddIDType` value and the corresponding `Block Additional Mapping`. A human-readable track name. @@ -425,14 +427,14 @@ The interpretation of the binary data depends on the BlockAddIDType value and th The language of the track, in the Matroska languages form; see (#language-codes) on language codes. -This Element **MUST** be ignored if the LanguageBCP47 Element is used in the same TrackEntry. +This element **MUST** be ignored if the `LanguageBCP47` element is used in the same `TrackEntry`. The language of the track, in the form defined in [@!RFC5646]; see (#language-codes) on language codes. -If this Element is used, then any Language Elements used in the same TrackEntry **MUST** be ignored. +If this element is used, then any `Language` elements used in the same `TrackEntry` **MUST** be ignored. @@ -452,7 +454,7 @@ see [@?I-D.ietf-cellar-codec] for more info. The UID of an attachment that is used by this codec. - The value **MUST** match the `FileUID` value of an attachment found in this Segment. + The value **MUST** match the `FileUID` value of an attachment found in this `Segment`. @@ -462,22 +464,22 @@ see [@?I-D.ietf-cellar-codec] for more info. A URL to find information about the codec used. - A URL to download about the codec used. + A URL to download information about the codec used. Set to 1 if the codec can decode potentially damaged data. - Specify that this track is an overlay track for the Track specified (in the u-integer). -This means that when this track has a gap on SilentTracks, -the overlay track should be used instead. The order of multiple TrackOverlay matters; the first one is the one that should be used. + Specify that this track is an overlay track for the `Track` specified (in the u-integer). +This means that when this track has a gap on `SilentTracks`, +the overlay track should be used instead. The order of multiple `TrackOverlay` matters; the first one is the one that should be used. If the first one is not found, it should be the second, etc. The built-in delay for the codec, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks). It represents the number of codec samples that will be discarded by the decoder during playback. This timestamp value **MUST** be subtracted from each frame timestamp in order to get the timestamp that will be actually played. -The value **SHOULD** be small so the muxing of tracks with the same actual timestamp are in the same Cluster. +The value **SHOULD** be small so the muxing of tracks with the same actual timestamp are in the same `Cluster`. @@ -489,7 +491,7 @@ that the decoder **MUST** decode before the decoded data is valid, expressed in The mapping between this `TrackEntry` and a track value in the given Chapter Codec. - Chapter Codec may need to address content in a specific track, but they may not know of the way to identify tracks in Matroska. + Chapter Codecs may need to address content in a specific track, but they may not know of the way to identify tracks in Matroska. This element and its child elements add a way to map the internal tracks known to the Chapter Codec to the track IDs in Matroska. This allows remuxing a file with Chapter Codec without changing the content of the codec data, just the track mapping. @@ -498,7 +500,7 @@ This allows remuxing a file with Chapter Codec without changing the content of t The format depends on the `ChapProcessCodecID` used; see (#chapprocesscodecid-element). - This `TrackTranslate` applies to the chapter codec of the given chapter edition(s); see (#chapprocesscodecid-element). + Applies to the chapter codec of the given chapter edition(s); see (#chapprocesscodecid-element). Chapter commands using the Matroska Script codec. @@ -510,7 +512,7 @@ The format depends on the `ChapProcessCodecID` used; see (#chapprocesscodecid-el Specifies a chapter edition UID to which this `TrackTranslate` applies. - When no `TrackTranslateEditionUID` is specified in the `TrackTranslate`, the `TrackTranslate` applies to all chapter editions found in the Segment using the given `TrackTranslateCodec`. + When no `TrackTranslateEditionUID` is specified in the `TrackTranslate`, the `TrackTranslate` applies to all chapter editions found in the `Segment` using the given `TrackTranslateCodec`. Video settings. @@ -537,11 +539,11 @@ The format depends on the `ChapProcessCodecID` used; see (#chapprocesscodecid-el Specifies the field ordering of video frames in this track. - If FlagInterlaced is not set to 1, this Element **MUST** be ignored. + If `FlagInterlaced` is not set to 1, this element **MUST** be ignored. Interlaced frames. - This value **SHOULD** be avoided; setting FlagInterlaced to 2 is sufficient. + This value **SHOULD** be avoided; setting `FlagInterlaced` to 2 is sufficient. Top field displayed first. Top field stored first. @@ -587,14 +589,14 @@ The format depends on the `ChapProcessCodecID` used; see (#chapprocesscodecid-el - Indicates whether the BlockAdditional Element with BlockAddID of "1" contains Alpha data, as defined by the Codec Mapping for the `CodecID`. -Undefined values **SHOULD NOT** be used, as the behavior of known implementations is different (considered either as 0 or 1). + Indicates whether the `BlockAdditional` element with `BlockAddID` of "1" contains Alpha data as defined by the Codec Mapping for the `CodecID`. + Undefined values (i.e., values other than 0 or 1) **SHOULD NOT** be used, as the behavior of known implementations is different. - The BlockAdditional Element with BlockAddID of "1" does not exist or **SHOULD NOT** be considered as containing such data. + The `BlockAdditional` element with `BlockAddID` of "1" does not exist or **SHOULD NOT** be considered as containing such data. - The BlockAdditional Element with BlockAddID of "1" contains alpha channel data. + The `BlockAdditional` element with `BlockAddID` of "1" contains alpha channel data. @@ -603,8 +605,8 @@ Undefined values **SHOULD NOT** be used, as the behavior of known implementation - Bogus StereoMode value used in old versions of [@?libmatroska]. - This Element **MUST NOT** be used. It was an incorrect value used in libmatroska up to 0.9.0. + Bogus `StereoMode` value used in old versions of [@?libmatroska]. + This element **MUST NOT** be used. It was an incorrect value used in libmatroska up to 0.9.0. @@ -650,20 +652,20 @@ Undefined values **SHOULD NOT** be used, as the behavior of known implementation Width of the video frames to display. Applies to the video frame after cropping (PixelCrop* Elements). - If the DisplayUnit of the same TrackEntry is 0, then the default value for DisplayWidth is equal to PixelWidth - PixelCropLeft - PixelCropRight; else, there is no default value. + If the DisplayUnit of the same `TrackEntry` is 0, then the default value for `DisplayWidth` is equal to `PixelWidth` - `PixelCropLeft` - `PixelCropRight`; else, there is no default value. Height of the video frames to display. Applies to the video frame after cropping (PixelCrop* Elements). - If the DisplayUnit of the same TrackEntry is 0, then the default value for DisplayHeight is equal to PixelHeight - PixelCropTop - PixelCropBottom; else, there is no default value. + If the DisplayUnit of the same `TrackEntry` is 0, then the default value for `DisplayHeight` is equal to `PixelHeight` - `PixelCropTop` - `PixelCropBottom`; else, there is no default value. - How DisplayWidth and DisplayHeight are interpreted. + How `DisplayWidth` and `DisplayHeight` are interpreted. @@ -684,9 +686,9 @@ Undefined values **SHOULD NOT** be used, as the behavior of known implementation - Specifies the uncompressed pixel format used for the Track's data as a FourCC. + Specifies the uncompressed pixel format used for the `Track`'s data as a FourCC. This value is similar in scope to the biCompression value of AVI's `BITMAPINFO` [@?AVIFormat]. There is neither a definitive list of FourCC values nor an official registry. Some common values for YUV pixel formats can be found at [@?MSYUV8], [@?MSYUV16], and [@?FourCC-YUV]. Some common values for uncompressed RGB pixel formats can be found at [@?MSRGB] and [@?FourCC-RGB]. - UncompressedFourCC **MUST** be set (minOccurs=1) in TrackEntry when the CodecID Element of the TrackEntry is set to "V_UNCOMPRESSED". + UncompressedFourCC **MUST** be set (minOccurs=1) in `TrackEntry` when the `CodecID` element of the `TrackEntry` is set to "V_UNCOMPRESSED". @@ -695,7 +697,7 @@ This value is similar in scope to the biCompression value of AVI's `BITMAPINFO` - Number of frames per second. This value is informational only. It is intended for constant frame rate streams and should not be used for a variable frame rate TrackEntry. + Number of frames per second. This value is informational only. It is intended for constant frame rate streams and should not be used for a variable frame rate `TrackEntry`. @@ -706,7 +708,7 @@ This value is similar in scope to the biCompression value of AVI's `BITMAPINFO` The Matrix Coefficients of the video used to derive luma and chroma values from red, green, and blue color primaries. -For clarity, the value and meanings for MatrixCoefficients are adopted from Table 4 of [@!ITU-H.273]. +For clarity, the value and meanings for `MatrixCoefficients` are adopted from Table 4 of [@!ITU-H.273]. @@ -729,36 +731,36 @@ For clarity, the value and meanings for MatrixCoefficients are adopted from Tabl - Number of decoded bits per channel. A value of 0 indicates that the BitsPerChannel is unspecified. + Number of decoded bits per channel. A value of 0 indicates that the `BitsPerChannel` is unspecified. The number of pixels to remove in the Cr and Cb channels for every pixel not removed horizontally. -Example: For video with 4:2:0 chroma subsampling, the ChromaSubsamplingHorz **SHOULD** be set to 1. +Example: For video with 4:2:0 chroma subsampling, the `ChromaSubsamplingHorz` **SHOULD** be set to 1. The number of pixels to remove in the Cr and Cb channels for every pixel not removed vertically. -Example: For video with 4:2:0 chroma subsampling, the ChromaSubsamplingVert **SHOULD** be set to 1. +Example: For video with 4:2:0 chroma subsampling, the `ChromaSubsamplingVert` **SHOULD** be set to 1. The number of pixels to remove in the Cb channel for every pixel not removed horizontally. -This is additive with ChromaSubsamplingHorz. Example: For video with 4:2:1 chroma subsampling, -the ChromaSubsamplingHorz **SHOULD** be set to 1, and CbSubsamplingHorz **SHOULD** be set to 1. +This is additive with `ChromaSubsamplingHorz`. Example: For video with 4:2:1 chroma subsampling, +the `ChromaSubsamplingHorz` **SHOULD** be set to 1, and `CbSubsamplingHorz` **SHOULD** be set to 1. The number of pixels to remove in the Cb channel for every pixel not removed vertically. -This is additive with ChromaSubsamplingVert. +This is additive with `ChromaSubsamplingVert`. @@ -799,7 +801,7 @@ This is additive with ChromaSubsamplingVert. The transfer characteristics of the video. For clarity, -the value and meanings for TransferCharacteristics are adopted from Table 3 of [@!ITU-H.273]. +the value and meanings for `TransferCharacteristics` are adopted from Table 3 of [@!ITU-H.273]. @@ -827,7 +829,7 @@ the value and meanings for TransferCharacteristics are adopted from Table 3 of [ The color primaries of the video. For clarity, -the value and meanings for Primaries are adopted from Table 2 of [@!ITU-H.273]. +the value and meanings for `Primaries` are adopted from Table 2 of [@!ITU-H.273]. @@ -956,7 +958,7 @@ in candelas per square meter (cd/m^2^). inside an ISOBMFF Cubemap Projection Box ("cbmp"). * If `ProjectionType` equals 3 (mesh), then this element **MUST** be present and contain the same binary data that would be stored inside an ISOBMFF Mesh Projection Box ("mshp"). -ISOBMFF box size and fourcc fields are not included in the binary data, +ISOBMFF box size and FourCC fields are not included in the binary data, but the FullBox version and flag fields are. This is to avoid redundant framing information while preserving versioning and semantics between the two container formats. @@ -968,7 +970,7 @@ redundant framing information while preserving versioning and semantics between Value represents a clockwise rotation, in degrees, around the up vector. This rotation must be applied before any `ProjectionPosePitch` or `ProjectionPoseRoll` rotations. -The value of this element **MUST** be in the -180 to 180 degree range, both included. +The value of this element **MUST** be in the -180 to 180 degree range, both inclusive. Setting `ProjectionPoseYaw` to 180 or -180 degrees with `ProjectionPoseRoll` and `ProjectionPosePitch` set to 0 degrees flips the image horizontally. @@ -980,7 +982,7 @@ Setting `ProjectionPoseYaw` to 180 or -180 degrees with `ProjectionPoseRoll` and Value represents a counter-clockwise rotation, in degrees, around the right vector. This rotation must be applied after the `ProjectionPoseYaw` rotation and before the `ProjectionPoseRoll` rotation. -The value of this element **MUST** be in the -90 to 90 degree range, both included. +The value of this element **MUST** be in the -90 to 90 degree range, both inclusive. @@ -990,7 +992,7 @@ The value of this element **MUST** be in the -90 to 90 degree range, both includ Value represents a counter-clockwise rotation, in degrees, around the forward vector. This rotation must be applied after the `ProjectionPoseYaw` and `ProjectionPosePitch` rotations. -The value of this element **MUST** be in the -180 to 180 degree range, both included. +The value of this element **MUST** be in the -180 to 180 degree range, both inclusive. Setting `ProjectionPoseRoll` to 180 or -180 degrees and `ProjectionPoseYaw` to 180 or -180 degrees with `ProjectionPosePitch` set to 0 degrees flips the image vertically. @@ -1011,8 +1013,8 @@ Setting `ProjectionPoseRoll` to 180 or -180 degrees with `ProjectionPoseYaw` and - Real output sampling frequency in Hz (used for SBR techniques). - The default value for OutputSamplingFrequency of the same TrackEntry is equal to the SamplingFrequency. + Real output sampling frequency in Hz that is used for Spectral Band Replication (SBR) techniques. + The default value for `OutputSamplingFrequency` of the same `TrackEntry` is equal to the `SamplingFrequency`. @@ -1087,7 +1089,7 @@ For more details, see (#track-operation). - The trackUID number of the track representing the plane. + The `TrackUID` number of the track representing the plane. @@ -1100,32 +1102,32 @@ For more details, see (#track-operation). - Contains the list of all tracks whose Blocks need to be combined to create this virtual track. + Contains the list of all tracks whose `Blocks` need to be combined to create this virtual track. - The trackUID number of a track whose blocks are used to create this virtual track. + The `TrackUID` number of a track whose blocks are used to create this virtual track. - The TrackUID of the Smooth FF/RW video in the paired EBML structure corresponding to this video track. See [@?DivXTrickTrack]. + The `TrackUID` of the Smooth FF/RW video in the paired EBML structure corresponding to this video track. See [@?DivXTrickTrack]. - The SegmentUID of the Segment containing the track identified by TrickTrackUID. See [@?DivXTrickTrack]. + The `SegmentUUID` of the `Segment` containing the track identified by TrickTrackUID. See [@?DivXTrickTrack]. - Set to 1 if this video track is a Smooth FF/RW track. If set to 1, MasterTrackUID and MasterTrackSegUID should be present, and BlockGroups for this track must contain ReferenceFrame structures. + Set to 1 if this video track is a Smooth FF/RW track. If set to 1, `MasterTrackUID` and `MasterTrackSegUID` should be present, and `BlockGroups` for this track must contain ReferenceFrame structures. Otherwise, TrickTrackUID and TrickTrackSegUID must be present if this track has a corresponding Smooth FF/RW track. See [@?DivXTrickTrack]. - The TrackUID of the video track in the paired EBML structure that corresponds to this Smooth FF/RW track. See [@?DivXTrickTrack]. + The `TrackUID` of the video track in the paired EBML structure that corresponds to this Smooth FF/RW track. See [@?DivXTrickTrack]. - The SegmentUID of the Segment containing the track identified by MasterTrackUID. See [@?DivXTrickTrack]. + The `SegmentUUID` of the `Segment` containing the track identified by MasterTrackUID. See [@?DivXTrickTrack]. @@ -1139,14 +1141,14 @@ Otherwise, TrickTrackUID and TrickTrackSegUID must be present if this track has - Tell in which order to apply each `ContentEncoding` of the `ContentEncodings`. + Defines the order to apply each `ContentEncoding` of the `ContentEncodings`. The decoder/demuxer **MUST** start with the `ContentEncoding` with the highest `ContentEncodingOrder` and work its way down to the `ContentEncoding` with the lowest `ContentEncodingOrder`. This value **MUST** be unique for each `ContentEncoding` found in the `ContentEncodings` of this `TrackEntry`. - A bit field that describes which Elements have been modified in this way. + A bit field that describes which elements have been modified in this way. Values (big-endian) can be OR'ed. @@ -1174,7 +1176,7 @@ Values (big-endian) can be OR'ed. Settings describing the compression used. -This Element **MUST** be present if the value of ContentEncodingType is 0 and absent otherwise. +This element **MUST** be present if the value of `ContentEncodingType` is 0 and absent otherwise. Each block **MUST** be decompressable, even if no previous block is available in order to not prevent seeking. @@ -1182,8 +1184,8 @@ Each block **MUST** be decompressable, even if no previous block is available in The compression algorithm used. Compression method "1" (bzlib) and "2" (lzo1x) lack proper documentation on the format, which limits implementation possibilities. Due to licensing conflicts on commonly available libraries' compression methods, "2" (lzo1x) does not offer widespread interoperability. -A Matroska Writer **SHOULD NOT** use these compression methods by default. -A Matroska Reader **MAY** support methods "1" and "2" as possible and **SHOULD** support other methods. +A `Matroska Writer` **SHOULD NOT** use these compression methods by default. +A `Matroska Reader` **MAY** support methods "1" and "2" and **SHOULD** support other methods. zlib compression [@!RFC1950]. @@ -1207,8 +1209,8 @@ the bytes that were removed from the beginning of each frame of the track. Settings describing the encryption used. -This Element **MUST** be present if the value of `ContentEncodingType` is 1 (encryption) and **MUST** be ignored otherwise. -A Matroska Player **MAY** support encryption. +This element **MUST** be present if the value of `ContentEncodingType` is 1 (encryption) and **MUST** be ignored otherwise. +A `Matroska Player` **MAY** support encryption. @@ -1256,10 +1258,10 @@ A Matroska Player **MAY** support encryption. AESSettingsCipherMode **MUST NOT** be set (maxOccurs=0) if ContentEncAlgo is not AES (5). - Counter [@?SP800-38A]. + Counter [@?SP800-38A] - Cipher Block Chaining [@?SP800-38A]. + Cipher Block Chaining [@?SP800-38A] @@ -1287,17 +1289,17 @@ A Matroska Player **MAY** support encryption. - A Top-Level Element to speed seeking access. -All entries are local to the Segment. - This Element **SHOULD** be set when the Segment is not transmitted as a live stream; see (#livestreaming). + A `Top-Level Element` to speed seeking access. +All entries are local to the `Segment`. + This element **SHOULD** be set when the `Segment` is not transmitted as a live stream; see (#livestreaming). - Contains all information relative to a seek point in the Segment. + Contains all information relative to a seek point in the `Segment`. - Absolute timestamp of the seek point, expressed in Segment Ticks, which are based on TimestampScale; see (#timestamp-ticks). + Absolute timestamp of the seek point, expressed in Segment Ticks, which are based on `TimestampScale`; see (#timestamp-ticks). @@ -1309,42 +1311,42 @@ All entries are local to the Segment. - The Segment Position ((#segment-position)) of the Cluster containing the associated Block. + The `Segment Position` ((#segment-position)) of the `Cluster` containing the associated `Block`. - The relative position inside the Cluster of the referenced SimpleBlock or BlockGroup -with 0 being the first possible position for an Element inside that Cluster. + The relative position inside the `Cluster` of the referenced `SimpleBlock` or `BlockGroup` +with 0 being the first possible position for an element inside that `Cluster`. - The duration of the block, expressed in Segment Ticks, which are based on TimestampScale; see (#timestamp-ticks). -If missing, the track's DefaultDuration does not apply and no duration information is available in terms of the cues. + The duration of the block, expressed in Segment Ticks, which are based on `TimestampScale`; see (#timestamp-ticks). +If missing, the track's `DefaultDuration` does not apply and no duration information is available in terms of the cues. - Number of the Block in the specified Cluster. + Number of the `Block` in the specified `Cluster`. - The Segment Position ((#segment-position)) of the Codec State corresponding to this Cue Element. -0 means that the data is taken from the initial Track Entry. + The `Segment Position` ((#segment-position)) of the Codec State corresponding to this `Cues` element. +0 means that the data is taken from the initial `TrackEntry`. - The Clusters containing the referenced Blocks. + The `Clusters` containing the referenced `Blocks`. - Timestamp of the referenced Block, expressed in Segment Ticks which is based on TimestampScale; see (#timestamp-ticks). + Timestamp of the referenced `Block`, expressed in Segment Ticks which is based on `TimestampScale`; see (#timestamp-ticks). - The Segment Position of the Cluster containing the referenced Block. + The `Segment Position` of the `Cluster` containing the referenced `Block`. - Number of the referenced Block of Track X in the specified Cluster. + Number of the referenced `Block` of Track X in the specified `Cluster`. - The Segment Position of the Codec State corresponding to this referenced Element. -0 means that the data is taken from the initial Track Entry. + The `Segment Position` of the Codec State corresponding to this referenced element. +0 means that the data is taken from the initial `TrackEntry`. Contains attached files. @@ -1376,12 +1378,12 @@ If missing, the track's DefaultDuration does not apply and no duration informati A binary value that a track/codec can refer to when the attachment is needed. - The timestamp at which this optimized font attachment comes into context, expressed in Segment Ticks, which are based on TimestampScale. See [@?DivXWorldFonts]. + The timestamp at which this optimized font attachment comes into context, expressed in Segment Ticks, which are based on `TimestampScale`. See [@?DivXWorldFonts]. This element is reserved for future use and if written **MUST** be the segment start timestamp. - The timestamp at which this optimized font attachment goes out of context, expressed in Segment Ticks, which are based on TimestampScale. See [@?DivXWorldFonts]. + The timestamp at which this optimized font attachment goes out of context, expressed in Segment Ticks, which are based on `TimestampScale`. See [@?DivXWorldFonts]. This element is reserved for future use and if written **MUST** be the segment end timestamp. @@ -1391,7 +1393,7 @@ For more detailed information, see (#chapters). - Contains all information about a Segment edition. + Contains all information about a `Segment` edition. @@ -1400,7 +1402,7 @@ For more detailed information, see (#chapters). Set to 1 if an edition is hidden. Hidden editions **SHOULD NOT** be available to the user interface -(but still to Control Tracks; see (#chapter-flags) on Chapter flags). +(but still be available to Control Tracks; see (#chapter-flags) on `Chapter` flags). @@ -1424,44 +1426,44 @@ in the form defined in [@!RFC5646]; see (#language-codes) on language codes. - A UID that identifies the Chapter. + A UID that identifies the `Chapter`. - A unique string ID that identifies the Chapter. + A unique string ID that identifies the `Chapter`. For example, it is used as the storage for cue identifier values [@?WebVTT]. - Timestamp of the start of Chapter, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks). + Timestamp of the start of `Chapter`, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks). - Timestamp of the end of Chapter timestamp excluded, expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks). + Timestamp of the end of `Chapter` (timestamp excluded), expressed in Matroska Ticks -- i.e., in nanoseconds; see (#timestamp-ticks). The value **MUST** be greater than or equal to the `ChapterTimeStart` of the same `ChapterAtom`. With the `ChapterTimeEnd` timestamp value being excluded, it **MUST** take into account the duration of the last frame it includes, especially for the `ChapterAtom` using the last frames of the `Segment`. - ChapterTimeEnd **MUST** be set (minOccurs=1) if the Edition is an ordered edition; see (#editionflagordered). If it's a `Parent Chapter`, see (#nested-chapters). + ChapterTimeEnd **MUST** be set (minOccurs=1) if the `Edition` is an ordered edition; see (#editionflagordered). If it's a `Parent Chapter`, see (#nested-chapters). Set to 1 if a chapter is hidden. Hidden chapters **SHOULD NOT** be available to the user interface -(but still to Control Tracks; see (#chapterflaghidden) on Chapter flags). +(but still be available to Control Tracks; see (#chapterflaghidden) on `Chapter` flags). Set to 1 if the chapter is enabled. It can be enabled/disabled by a Control Track. -When disabled, the movie **SHOULD** skip all the content between the TimeStart and TimeEnd of this chapter; see (#chapter-flags) on Chapter flags. +When disabled, the movie **SHOULD** skip all the content between the TimeStart and TimeEnd of this chapter; see (#chapter-flags) on `Chapter` flags. - The SegmentUUID of another Segment to play during this chapter. + The `SegmentUUID` of another `Segment` to play during this chapter. The value **MUST NOT** be the `SegmentUUID` value of the `Segment` it belongs to. - ChapterSegmentUUID **MUST** be set (minOccurs=1) if ChapterSegmentEditionUID is used; see (#medium-linking) on Medium-Linking Segments. + `ChapterSegmentUUID` **MUST** be set (minOccurs=1) if `ChapterSegmentEditionUID` is used; see (#medium-linking) on Medium-Linking `Segments`. - Indicates what type of content the ChapterAtom contains and might be skipped. It can be used to automatically skip content based on the type. + Indicates what type of content the `ChapterAtom` contains and might be skipped. It can be used to automatically skip content based on the type. If a `ChapterAtom` is inside a `ChapterAtom` that has a `ChapterSkipType` set, it **MUST NOT** have a `ChapterSkipType` or have a `ChapterSkipType` with the same value as it's parent `ChapterAtom`. If the `ChapterAtom` doesn't contain a `ChapterTimeEnd`, the value of the `ChapterSkipType` is only valid until the next `ChapterAtom` with a `ChapterSkipType` value or the end of the file. @@ -1491,21 +1493,21 @@ If the `ChapterAtom` doesn't contain a `ChapterTimeEnd`, the value of the `Chapt - The EditionUID to play from the Segment linked in ChapterSegmentUUID. -If ChapterSegmentEditionUID is undeclared, then no Edition of the linked Segment is used; see (#medium-linking) on Medium-Linking Segments. + The `EditionUID` to play from the `Segment` linked in `ChapterSegmentUUID`. +If `ChapterSegmentEditionUID` is undeclared, then no `Edition` of the `Linked Segment` is used; see (#medium-linking) on Medium-Linking `Segments`. - Specifies the physical equivalent of this ChapterAtom, e.g., "DVD" (60) or "SIDE" (50); + Specifies the physical equivalent of this `ChapterAtom`, e.g., "DVD" (60) or "SIDE" (50); see (#physical-types) for a complete list of values. - List of tracks on which the chapter applies. If this Element is not present, all tracks apply. + List of tracks on which the chapter applies. If this element is not present, all tracks apply. - UID of the Track to apply this chapter to. -In the absence of a control track, choosing this chapter will select the listed Tracks and deselect unlisted tracks. -Absence of this Element indicates that the Chapter **SHOULD** be applied to any currently used Tracks. + UID of the `Track` to apply this chapter to. +In the absence of a control track, choosing this chapter will select the listed `Tracks` and deselect unlisted tracks. +Absence of this element indicates that the `Chapter` **SHOULD** be applied to any currently used `Tracks`. @@ -1521,20 +1523,20 @@ Absence of this Element indicates that the Chapter **SHOULD** be applied to any A language corresponding to the string, in the Matroska languages form; see (#language-codes) on language codes. -This Element **MUST** be ignored if a ChapLanguageBCP47 Element is used within the same ChapterDisplay Element. +This element **MUST** be ignored if a `ChapLanguageBCP47` element is used within the same `ChapterDisplay` element. - A language corresponding to the ChapString, + A language corresponding to the `ChapString`, in the form defined in [@!RFC5646]; see (#language-codes) on language codes. -If a ChapLanguageBCP47 Element is used, then any ChapLanguage and ChapCountry Elements used in the same ChapterDisplay **MUST** be ignored. +If a `ChapLanguageBCP47` element is used, then any `ChapLanguage` and `ChapCountry` elements used in the same `ChapterDisplay` **MUST** be ignored. A country corresponding to the string, in the Matroska countries form; see (#country-codes) on country codes. -This Element **MUST** be ignored if a ChapLanguageBCP47 Element is used within the same ChapterDisplay Element. +This element **MUST** be ignored if a `ChapLanguageBCP47` element is used within the same `ChapterDisplay` element. @@ -1549,8 +1551,8 @@ More codec IDs can be added later. - Optional data attached to the ChapProcessCodecID information. - For ChapProcessCodecID = 1, it is the "DVD level" equivalent; see (#menu-features) on DVD menus. + Optional data attached to the `ChapProcessCodecID` information. + For `ChapProcessCodecID` = 1, it is the "DVD level" equivalent; see (#menu-features) on DVD menus. @@ -1568,12 +1570,12 @@ More codec IDs can be added later. Contains the command information. -The data **SHOULD** be interpreted depending on the ChapProcessCodecID value. For ChapProcessCodecID = 1, +The data **SHOULD** be interpreted depending on the `ChapProcessCodecID` value. For `ChapProcessCodecID` = 1, the data correspond to the binary DVD cell pre/post commands; see (#menu-features) on DVD menus. - Element containing metadata describing Tracks, Editions, Chapters, Attachments, or the Segment as a whole. + Element containing metadata describing `Tracks`, `Editions`, `Chapters`, `Attachments`, or the `Segment` as a whole. A list of valid tags can be found in [@?I-D.ietf-cellar-tags]. @@ -1582,8 +1584,8 @@ A list of valid tags can be found in [@?I-D.ietf-cellar-tags]. - Specifies which other elements the metadata represented by the Tag applies to. -If empty or omitted, then the Tag describes everything in the Segment. + Specifies which other elements the metadata represented by the tag value applies to. +If empty or omitted, then the tag value describes everything in the `Segment`. @@ -1644,25 +1646,25 @@ If empty or omitted, then the Tag describes everything in the Segment. - A UID that identifies the Track(s) that the tags belong to. - If the value is 0 at this level, the tags apply to all tracks in the Segment. -If set to any other value, it **MUST** match the `TrackUID` value of a track found in this Segment. + A UID that identifies the `Track(s)` that the tags belong to. + If the value is 0 at this level, the tags apply to all tracks in the `Segment`. +If set to any other value, it **MUST** match the `TrackUID` value of a track found in this `Segment`. - A UID that identifies the EditionEntry(s) that the tags belong to. - If the value is 0 at this level, the tags apply to all editions in the Segment. -If set to any other value, it **MUST** match the `EditionUID` value of an edition found in this Segment. + A UID that identifies the `EditionEntry(s)` that the tags belong to. + If the value is 0 at this level, the tags apply to all editions in the `Segment`. +If set to any other value, it **MUST** match the `EditionUID` value of an edition found in this `Segment`. - A UID that identifies the Chapter(s) that the tags belong to. - If the value is 0 at this level, the tags apply to all chapters in the Segment. -If set to any other value, it **MUST** match the `ChapterUID` value of a chapter found in this Segment. + A UID that identifies the `Chapter(s)` that the tags belong to. + If the value is 0 at this level, the tags apply to all chapters in the `Segment`. +If set to any other value, it **MUST** match the `ChapterUID` value of a chapter found in this `Segment`. A UID that identifies the Attachment(s) that the tags belong to. - If the value is 0 at this level, the tags apply to all the attachments in the Segment. -If set to any other value, it **MUST** match the `FileUID` value of an attachment found in this Segment. + If the value is 0 at this level, the tags apply to all the attachments in the `Segment`. +If set to any other value, it **MUST** match the `FileUID` value of an attachment found in this `Segment`. Contains general information about the target. @@ -1670,20 +1672,20 @@ If set to any other value, it **MUST** match the `FileUID` value of an attachmen - The name of the Tag that is going to be stored. + The name of the tag value that is going to be stored. Specifies the language of the specified tag in the Matroska languages form; see (#language-codes) on language codes. -This Element **MUST** be ignored if the TagLanguageBCP47 Element is used within the same SimpleTag Element. +This element **MUST** be ignored if the `TagLanguageBCP47` element is used within the same `SimpleTag` element. - The language used in the TagString, + The language used in the `TagString`, in the form defined in [@!RFC5646]; see (#language-codes) on language codes. -If this Element is used, then any TagLanguage Elements used in the same SimpleTag **MUST** be ignored. +If this element is used, then any `TagLanguage` elements used in the same `SimpleTag` **MUST** be ignored. @@ -1691,14 +1693,14 @@ If this Element is used, then any TagLanguage Elements used in the same SimpleTa - A variant of the TagDefault element with a bogus Element ID; see (#tagdefault-element). + A variant of the `TagDefault` element with a bogus element ID; see (#tagdefault-element). - The value of the Tag. + The tag value. - The values of the Tag if it is binary. Note that this cannot be used in the same SimpleTag as TagString. + The tag value if it is binary. Note that this cannot be used in the same `SimpleTag` as `TagString`. diff --git a/iana.md b/iana.md index 63efc9cca..f57636939 100644 --- a/iana.md +++ b/iana.md @@ -7,7 +7,7 @@ IANA has created a new registry called the "Matroska Chapter Codec IDs" registry The values correspond to the unsigned integer `ChapProcessCodecID` value described in (#chapprocesscodecid-element). To register a new Chapter Codec ID in this registry, one needs -a Chapter Codec ID, +a Chapter Codec ID, description, a Change Controller (IETF or email of registrant), and an optional Reference to a document describing the Chapter Codec ID. @@ -17,11 +17,11 @@ Values of "0" and "1" are reserved for future use (with the IETF as the Change C ## Media Types -Matroska files and streams are found in three main forms: audio-video files, audio-only, and occasionally with stereoscopic video tracks. +Matroska files and streams are found in three main forms: audio-video, audio-only, and (occasionally) stereoscopic video. Historically, Matroska files and streams have used the following media types with an "x-" prefix. For better compatibility, a system **SHOULD** be able to handle both formats. -Newer systems **SHOULD NOT** use the historic format and use the format defined in [@!RFC6838] instead. +Newer systems **SHOULD NOT** use the historic format and use the format that follows the format in [@!RFC6838] instead. IANA has registered three media types per the templates (see [@!RFC6838]) in the following subsections. @@ -52,7 +52,7 @@ Published specification: : RFC 9559 Applications that use this media type: -: FFmpeg, VLC, ... +: FFmpeg, VLC, etc. Fragment identifier considerations: : N/A @@ -113,7 +113,7 @@ Published specification: : RFC 9559 Applications that use this media type: -: FFmpeg, VLC, ... +: FFmpeg, VLC, etc. Fragment identifier considerations: : N/A @@ -175,7 +175,7 @@ Published specification: : RFC 9559 Applications that use this media type: -: FFmpeg, VLC, ... +: FFmpeg, VLC, etc. Fragment identifier considerations: : N/A diff --git a/iana_matroska_ids.md b/iana_matroska_ids.md index b9bca6ad4..7e33fc73b 100644 --- a/iana_matroska_ids.md +++ b/iana_matroska_ids.md @@ -6,7 +6,7 @@ IANA has created a new registry called the "Matroska Element IDs" registry. To register a new Element ID in this registry, one needs -an Element ID, +an Element ID, an Element Name, a Change Controller (IETF or email of registrant), and an optional Reference to a document describing the Element ID. @@ -17,20 +17,26 @@ only if declared in the EBML Header. Element IDs are described in [@!RFC8794, section 5], with the changes in [@Err7189] and [@Err7191]. -One-octet Matroska Element IDs are to be allocated according to the "RFC Required" policy [@!RFC8126]. +One-octet Matroska Element IDs (range 0x80-0xFE) are to be allocated according to the "RFC Required" policy [@!RFC8126]. -Two-octet Matroska Element IDs are to be allocated according to the "Specification Required" policy [@!RFC8126]. +Two-octet Matroska Element IDs (range 0x407F-0x7FFE) are to be allocated according to the "Specification Required" policy [@!RFC8126]. -Three-octet and four-octet Matroska Element IDs are to be allocated according to the "First Come First Served" policy [@!RFC8126]. +Two-octet Matroska Element IDs between 0x0100 and 0x407E are not valid for use as an Element ID. -The allowed values in the "Matroska Elements IDs" registry are similar to the ones found +Three-octet (range 0x203FFF-0x3FFFFE) and four-octet Matroska Element IDs (range 0x101FFFFF-0x1FFFFFFE) are to be allocated according to the "First Come First Served" policy [@!RFC8126]. + +Three-octet Matroska Element IDs between 0x010000 and 0x203FFE are not valid for use as an Element ID. + +Four-octet Matroska Element IDs between 0x01000000 and 0x101FFFFE are not valid for use as an Element ID. + +The allowed values in the "Matroska Element IDs" registry are similar to the ones found in the "EBML Element IDs" registry defined in [@!RFC8794, section 17.1]. EBML Element IDs defined for the EBML Header -- as defined in [@!RFC8794, section 17.1] -- **MUST NOT** be used as Matroska Element IDs. -Given the scarcity of the one-octet Element IDs, they should only be created to save space for elements found many times in a file -(for example, within a BlockGroup or Chapters). The four-octet Element IDs are mostly for synchronization of large elements. +Given the scarcity of one-octet Element IDs, they should only be created to save space for elements found many times in a file +(for example, `BlockGroup` or `Chapters`). The four-octet Element IDs are mostly for synchronization of large elements. They should only be used for such high-level elements. Elements that are not expected to be used often should use three-octet Element IDs. @@ -39,4 +45,5 @@ These elements are not in use and **SHOULD NOT** be reused unless there are no o Such IDs are marked as "Reclaimed" in the "Matroska Element IDs" registry, as they could be used for other things in the future. (#iana-table) shows the initial contents of the "Matroska Element IDs" registry. +Note that the Change Controller for all entries in (#iana-table) is "IETF". diff --git a/index_codec.md b/index_codec.md index a9125a3b7..961ae2398 100644 --- a/index_codec.md +++ b/index_codec.md @@ -39,7 +39,7 @@ fullname="Dave Rice" .# Abstract This document defines the Matroska codec mappings, including the codec ID, layout of data -in a `Block Element` and in an optional `CodecPrivate Element`. +in a `Block` element and in an optional `CodecPrivate` element. {mainmatter} diff --git a/index_matroska.md b/index_matroska.md index 07cc14748..2e70baacb 100644 --- a/index_matroska.md +++ b/index_matroska.md @@ -1,5 +1,5 @@ %%% -title = "Matroska Media Container Format Specifications" +title = "Matroska Media Container Format Specification" abbrev = "Matroska Format" ipr= "trust200902" area = "art" @@ -52,7 +52,7 @@ but diverges from it significantly because it is based on EBML (Extensible Binar a binary derivative of XML. EBML provides significant advantages in terms of future format extensibility, without breaking file support in parsers reading the previous versions. -To avoid any misunderstandings, it is essential to clarify exactly what an audiovisual container is: +To avoid any misunderstandings, it is essential to clarify exactly what an audio/video container is: - It is NOT a video or audio compression format (codec). @@ -92,23 +92,23 @@ The key words "**MUST**", "**MUST NOT**", described in BCP 14 [@!RFC2119] [@!RFC8174] when, and only when, they appear in all capitals, as shown here. -This document defines the following terms in order to define the format and application of `Matroska`: +This document defines the following terms in order to define the format and application of Matroska: -`Matroska`: +Matroska: : A multimedia container format based on EBML (Extensible Binary Meta Language). `Matroska Reader`: -: A data parser that interprets the semantics of a Matroska document and creates a way for programs to use `Matroska`. +: A data parser that interprets the semantics of a Matroska document and creates a way for programs to use Matroska. `Matroska Player`: -: A `Matroska Reader` with the primary purpose of playing audiovisual files, including `Matroska` documents. +: A `Matroska Reader` with the primary purpose of playing audiovisual files, including Matroska documents. `Matroska Writer`: -: A data writer that creates `Matroska` documents. +: A data writer that creates Matroska documents. # Matroska Overview @@ -179,11 +179,11 @@ As an EBML Document Type, Matroska adds the following constraints to the EBML sp ## Design Rules -The Root Element and all Top-Level Elements **MUST** use 4 octets for their EBML Element ID -- i.e., Segment and direct children of Segment. +The `Root Element` and all `Top-Level Elements` **MUST** use 4 octets for their EBML Element ID -- i.e., `Segment` and direct children of `Segment`. Legacy EBML/Matroska parsers did not handle Empty Elements properly; elements were present in the file but had a length of 0. They always assumed the value was 0 for integers/dates or 0x0p+0, the textual expression of floats using the format in [@!ISO9899], no matter the default value of the element that should have been used instead. -Therefore, Matroska Writers **MUST NOT** use EBML Empty Elements if the element has a default value that is not 0 for integers/dates and 0x0p+0 for floats. +Therefore, `Matroska Writers` **MUST NOT** use EBML Empty Elements if the element has a default value that is not 0 for integers/dates and 0x0p+0 for floats. When adding new elements to Matroska, these rules apply: @@ -191,5 +191,5 @@ When adding new elements to Matroska, these rules apply: * A non-mandatory float Element **MUST NOT** have a default value other than 0x0p+0. -* A non-mandatory string Element **MUST NOT** have a default value, as empty string cannot be defined in the XML Schema. +* A non-mandatory string Element **MUST NOT** have a default value, as empty strings cannot be defined in the XML Schema. diff --git a/index_tags.md b/index_tags.md index 18443211b..329b75d96 100644 --- a/index_tags.md +++ b/index_tags.md @@ -45,8 +45,8 @@ This document defines the Matroska tags, namely the tag names and their respecti # Introduction Matroska is a multimedia container format defined in [@!Matroska]. It can store timestamped multimedia data -but also chapters and tags. The `Tag Elements` add important metadata to identify and classify the information found -in a `Matroska Segment`. It can tag a whole `Segment`, separate `Track Elements`, individual `Chapter Elements` or `Attachment Elements`. +but also chapters and tags. The `Tag` elements add important metadata to identify and classify the information found +in a Matroska `Segment`. It can tag a whole `Segment`, separate `Tracks` elements, individual `Chapter` elements or `Attachments` elements. While the Matroska tagging framework allows anyone to create their own custom tags, it's important to have a common set of values for interoperability. This document intends to define a set of common tag names used in Matroska. diff --git a/matroska_implement.md b/matroska_implement.md index ea141ec8a..694a7d563 100644 --- a/matroska_implement.md +++ b/matroska_implement.md @@ -2,80 +2,80 @@ ## Cluster -It is **RECOMMENDED** that each individual `Cluster Element` contain no more than +It is **RECOMMENDED** that each individual `Cluster` element contain no more than five seconds or five megabytes of content. ## SeekHead -It is **RECOMMENDED** that the first `SeekHead Element` be followed by a `Void Element` to -allow for the `SeekHead Element` to be expanded to cover new `Top-Level Elements` -that could be added to the Matroska file, such as `Tags`, `Chapters`, and `Attachments` Elements. +It is **RECOMMENDED** that the first `SeekHead` element be followed by a `Void` element to +allow for the `SeekHead` element to be expanded to cover new `Top-Level Elements` +that could be added to the Matroska file, such as `Tags`, `Chapters`, and `Attachments` elements. -The size of this `Void Element` should be adjusted depending on the Matroska file already having -`Tags`, `Chapters`, and `Attachments` Elements. +The size of this `Void` element should be adjusted depending on the +`Tags`, `Chapters`, and `Attachments` elements in the Matroska file. ## Optimum Layouts -While there can be `Top-Level Elements` in any order, some orderings of Elements are better than others. +While there can be `Top-Level Elements` in any order, some orderings of elements are better than others. The following subsections detail optimum layouts for different use cases. ### Optimum Layout for a Muxer This is the basic layout muxers should be using for an efficient playback experience: -* SeekHead -* Info -* Tracks -* Chapters -* Attachments -* Tags -* Clusters -* Cues +* `SeekHead` +* `Info` +* `Tracks` +* `Chapters` +* `Attachments` +* `Tags` +* `Clusters` +* `Cues` ### Optimum Layout after Editing Tags When tags from the previous layout need to be extended, they are moved to the end with the extra information. The location where the old tags were located is voided. -* SeekHead -* Info -* Tracks -* Chapters -* Attachments -* Void -* Clusters -* Cues -* Tags +* `SeekHead` +* `Info` +* `Tracks` +* `Chapters` +* `Attachments` +* `Void` +* `Clusters` +* `Cues` +* `Tags` ### Optimum Layout with Cues at the Front -Cues are usually a big chunk of data referencing a lot of locations in the file. +`Cues` are usually a big chunk of data referencing a lot of locations in the file. Players that want to seek in the file need to seek to the end of the file to access these locations. It is often better if they are placed early in the file. On the other hand, that means players that don't intend to seek will have to read/skip these data no matter what. -Because the Cues reference locations further in the file, it's often complicated to +Because the `Cues` reference locations further in the file, it's often complicated to allocate the proper space for that element before all the locations are known. Therefore, this layout is rarely used: -* SeekHead -* Info -* Tracks -* Chapters -* Attachments -* Tags -* Cues -* Clusters +* `SeekHead` +* `Info` +* `Tracks` +* `Chapters` +* `Attachments` +* `Tags` +* `Cues` +* `Clusters` ### Optimum Layout for Livestreaming -In livestreaming ((#livestreaming)), only a few elements make sense. For example, SeekHead and Cues are useless. -All elements other than the Clusters **MUST** be placed before the Clusters. +In livestreaming ((#livestreaming)), only a few elements make sense. For example, `SeekHead` and `Cues` are useless. +All elements other than the `Clusters` **MUST** be placed before the `Clusters`. -* Info -* Tracks -* Attachments (rare) -* Tags -* Clusters +* `Info` +* `Tracks` +* `Attachments` (rare) +* `Tags` +* `Clusters` diff --git a/matroska_schema_section_header.md b/matroska_schema_section_header.md index 4a7aba32f..291a25a66 100644 --- a/matroska_schema_section_header.md +++ b/matroska_schema_section_header.md @@ -1,11 +1,10 @@ # Matroska Schema -This specification includes an `EBML Schema` that defines the Elements and structure +This specification includes an `EBML Schema` that defines the elements and structure of Matroska using the EBML Schema elements and attributes defined in [@!RFC8794, section 11.1]. -The EBML Schema defines every valid Matroska element in a manner defined by the EBML specification [@!RFC8794]. Attributes using their default value (like `minOccurs`, `minver`, etc.) or attributes with undefined values (like `length`, `maxver`, etc.) are omitted. -The definitions for each Matroska Element are provided below. +The definitions for each Matroska element are provided below. diff --git a/matroska_security.md b/matroska_security.md index cf9913517..80362f793 100644 --- a/matroska_security.md +++ b/matroska_security.md @@ -1,11 +1,11 @@ # Security Considerations -Matroska inherits security considerations from EBML. +Matroska inherits security considerations from EBML [@!RFC8794]. Attacks on a `Matroska Reader` could include: -* Storage of an arbitrary and potentially executable data within an `Attachment Element`. - `Matroska Readers` that extract or use data from Matroska Attachments **SHOULD** +* Storage of an arbitrary and potentially executable data within an `Attachments` element. + `Matroska Readers` that extract or use data from `Matroska Attachments` **SHOULD** check that the data adheres to expectations or not use the attachment. * A `Matroska Attachment` with an inaccurate media type. @@ -17,7 +17,7 @@ Attacks on a `Matroska Reader` could include: The same error handling done for EBML applies to Matroska files. Particular error handling is not covered in this specification, as this is depends on the goal of the `Matroska Readers`. -It is up to the decision of the `Matroska Readers` on how to handle the errors if they are recoverable in their code or not. +`Matroska Readers` decide how to handle the errors whether or not they are recoverable in their code. For example, if the checksum of the `\Segment\Tracks` is invalid, some could decide to try to read the data anyway, some will just reject the file, and most will not even check it. @@ -25,10 +25,10 @@ some will just reject the file, and most will not even check it. Those related to denial of service are outlined in [@RFC4732, section 2.1]. Although rarer, the same may apply to a `Matroska Writer`. Malicious stream data -must not cause the Matroska Writer to misbehave, as this might allow an attacker access +must not cause the `Matroska Writer` to misbehave, as this might allow an attacker access to transcoding gateways. -As an audio and visual container format, a Matroska file or stream will +As an audio/video container format, a Matroska file or stream will potentially encapsulate numerous byte streams created with a variety of codecs. Implementers will need to consider the security considerations of these encapsulated formats. diff --git a/matroska_tags.xml b/matroska_tags.xml index 0a19d497d..50cdbacc9 100644 --- a/matroska_tags.xml +++ b/matroska_tags.xml @@ -289,7 +289,7 @@ Other rating systems with different ranges will have to be scaled. A list of the settings used for encoding this item. No specific format. - The average bits per second of the specified item. This is only the data in the Blocks, + The average bits per second of the specified item. This is only the data in the `Block(s)`, and excludes headers and any container overhead. diff --git a/notes.md b/notes.md index 8e000bc2e..db5c8eb58 100644 --- a/notes.md +++ b/notes.md @@ -5,23 +5,23 @@ Matroska is based on the principle that a reading application does not have to s contains version indicators that tell a reading application what to expect. It is possible and valid to have the version fields indicate that the file contains -Matroska `Elements` from a higher specification version number while signaling that a +Matroska elements from a higher specification version number while signaling that a reading application **MUST** only support a lower version number properly in order to play it back (possibly with a reduced feature set). The `EBML Header` of each Matroska document informs the reading application on what -version of Matroska to expect. The `Elements` within the `EBML Header` with jurisdiction +version of Matroska to expect. The elements within the `EBML Header` with jurisdiction over this information are `DocTypeVersion` and `DocTypeReadVersion`. `DocTypeVersion` **MUST** be equal to or greater than the highest Matroska version number of -any `Element` present in the Matroska file. For example, a file using the `SimpleBlock Element` ((#simpleblock-element)) +any element present in the Matroska file. For example, a file using the `SimpleBlock` element ((#simpleblock-element)) **MUST** have a `DocTypeVersion` equal to or greater than 2. A file containing `CueRelativePosition` -Elements ((#cuerelativeposition-element)) **MUST** have a `DocTypeVersion` equal to or greater than 4. +elements ((#cuerelativeposition-element)) **MUST** have a `DocTypeVersion` equal to or greater than 4. The `DocTypeReadVersion` **MUST** contain the minimum version number that a reading application can minimally support in order to play the file back -- optionally with a reduced feature -set. For example, if a file contains only `Elements` of version 2 or lower except for -`CueRelativePosition` (which is a version 4 Matroska `Element`), then `DocTypeReadVersion` +set. For example, if a file contains only elements of version 2 or lower except for +`CueRelativePosition` (which is a version 4 Matroska element), then `DocTypeReadVersion` **SHOULD** still be set to 2 and not 4 because evaluating `CueRelativePosition` is not necessary for standard playback -- it makes seeking more precise if used. @@ -31,7 +31,7 @@ is greater than `V`. A reading application supporting at least Matroska version `V` and reading a file whose `DocTypeReadVersion` -field is equal to or lower than `V` **MUST** skip Matroska/EBML `Elements` it encounters +field is equal to or lower than `V` **MUST** skip Matroska/EBML elements it encounters but does not know about if that unknown element fits into the size constraints set by the current `Parent Element`. @@ -43,12 +43,12 @@ Some values from the original Matroska file need to be kept the same in the dest For example, the SamplingFrequency of an audio track wouldn't change between the two files. Some other values may change between the two files, for example, the TrackNumber of an audio track when another track has been added. -An Element is marked with a property: `stream copy: True` when the values of that Element need to be kept identical between the source and destination files. +An element is marked with a property "`stream copy: True`" when the values of that element need to be kept identical between the source and destination files. If that property is not set, elements may or may not keep the same value between the source and destination files. # DefaultDecodedFieldDuration -The `DefaultDecodedFieldDuration Element` can signal to the displaying application how +The `DefaultDecodedFieldDuration` element can signal to the displaying application how often fields of a video sequence will be available for displaying. It can be used for both interlaced and progressive content. @@ -74,9 +74,9 @@ Examples: # Cluster Blocks -Frames using references **SHOULD** be stored in "coding order" (i.e., the references first, and then +Frames using references **SHOULD** be stored in "coding order" (i.e., the references first and then the frames referencing them). A consequence is that timestamps might not be consecutive. -However, a frame with a past timestamp **MUST** reference a frame already known; otherwise it is considered bad/void. +However, a frame with a past timestamp **MUST** reference a frame already known; otherwise, it is considered bad/void. Matroska has two similar ways to store frames in a block: @@ -85,7 +85,7 @@ Matroska has two similar ways to store frames in a block: * in a `SimpleBlock` that is directly in the `Cluster` The `SimpleBlock` is usually preferred unless some extra elements of the `BlockGroup` need to be used. -A Matroska Reader **MUST** support both types of blocks. +A `Matroska Reader` **MUST** support both types of blocks. Each block contains the same parts in the following order: @@ -95,11 +95,11 @@ Each block contains the same parts in the following order: * the consecutive frame(s) -The block header starts with the number of the Track it corresponds to. +The block header starts with the number of the `Track` it corresponds to. The value **MUST** correspond to the `TrackNumber` ((#tracknumber-element)) of a `TrackEntry` of the `Segment`. The `TrackNumber` is coded using the Variable-Size Integer (VINT) mechanism described in [@!RFC8794, section 4]. -To save space, the shortest VINT form **SHOULD** be used. The value can be coded on up to 8 octets. +To save space, the shortest VINT form **SHOULD** be used. The value can be coded using up to 8 octets. This is the only element with a variable size in the block header. The timestamp is expressed in Track Ticks; see (#timestamp-ticks). @@ -107,7 +107,7 @@ The value is stored as a signed value on 16 bits. ## Block Structure -This section describes the binary data contained in the `Block` Element ((#block-element)). Bit 0 is the most significant bit. +This section describes the binary data contained in the `Block` element ((#block-element)). Bit 0 is the most significant bit. As the `TrackNumber` size can vary between 1 and 8 octets, there are 8 different sizes for the `Block` header. The definitions for `TrackNumber` sizes of 1 and 2 are provided; @@ -150,7 +150,7 @@ Rsvrd: : 4 bits. Reserved bits **MUST** be set to 0. INV: -: 1 bit. Invisible. The codec **SHOULD** decode this frame but not display it. +: 1 bit. Invisible, The codec **SHOULD** decode this frame but not display it. LACING: : 2 bits. Uses lacing mode. @@ -169,13 +169,13 @@ LACING: UNU: : 1 bit. Unused bit. -The following data in the `Block` corresponds to the lacing data and frames usage as described in each respective lacing mode. +The remaining data in the `Block` corresponds to the lacing data and frames usage as described in each respective lacing mode (see (#block-lacing)). ## SimpleBlock Structure -This section describes the binary data contained in the `SimpleBlock` Element ((#simpleblock-element)). Bit 0 is the most significant bit. +This section describes the binary data contained in the `SimpleBlock` element ((#simpleblock-element)). Bit 0 is the most significant bit. -The `SimpleBlock` structure is inspired by the Block structure; see (#block-structure). +The `SimpleBlock` structure is inspired by the `Block` structure; see (#block-structure). The main differences are the added Keyframe flag and Discardable flag. Otherwise, everything is the same. As the `TrackNumber` size can vary between 1 and 8 octets, there are 8 different sizes for the `SimpleBlock` header. @@ -216,7 +216,7 @@ Timestamp: : 16 bits. Signed timestamp in Track Ticks. KEY: -: 1 bit. Keyframe. Set when the Block contains only keyframes. +: 1 bit. Keyframe. Set when the `Block` contains only keyframes. Rsvrd: : 3 bits. Reserved bits **MUST** be set to 0. @@ -239,9 +239,9 @@ LACING: : fixed-size lacing ((#fixed-size-lacing)) DIS: -: 1 bit. Discardable. The frames of the Block can be discarded during playing if needed. +: 1 bit. Discardable. The frames of the `Block` can be discarded during playing if needed. -The following data in the `SimpleBlock` corresponds to the lacing data and frames usage as described in each respective lacing mode. +The remaining data in the `SimpleBlock` corresponds to the lacing data and frames usage as described in each respective lacing mode (see (#block-lacing)). ## Block Lacing @@ -256,9 +256,9 @@ There are three types of lacing: * EBML, which is the same with sizes coded differently -* fixed-size, where the size is not coded +* Fixed-size, where the size is not coded -When lacing is not used, i.e., to store a single frame, lacing bits 5 and 6 of the `Block` or `SimpleBlock` **MUST** be set to 0. +When lacing is not used, i.e., to store a single frame, the lacing bits (bits 5 and 6) of the `Block` or `SimpleBlock` **MUST** be set to zero. For example, a user wants to store three frames of the same track. The first frame is 800 octets long, the second is 500 octets long, and the third is 1000 octets long. @@ -266,31 +266,31 @@ Because these frames are small, they can be stored in a lace to save space. It is possible to not use lacing at all and just store a single frame without any extra data. -When the FlagLacing ((#flaglacing-element)) is set to 0, all blocks of that track **MUST NOT** use lacing. +When the `FlagLacing` ((#flaglacing-element)) is set to 0, all blocks of that track **MUST NOT** use lacing. ### No Lacing -When no lacing is used, the number of frames in the lace is ommitted, and only one frame can be stored in the Block. -Bits 5 and 6 of the Block Header flags are set to `0b00`. +When no lacing is used, the number of frames in the lace is ommitted, and only one frame can be stored in the `Block`. +The LACING bits of the `Block` Header flags are set to `00b`. -The Block for an 800-octet frame is as follows: +The `Block` for an 800-octet frame is as follows: | Block Octet | Value | Description | |:-------------|:--------|:------------------------| | 4-803 | | Single frame data | Table: No Lacing{#blockNoLacing} -When a Block contains a single frame, it **MUST** use this "no lacing" mode. +When a `Block` contains a single frame, it **MUST** use this "no lacing" mode. ### Xiph Lacing The Xiph lacing uses the same coding of size as found in the Ogg container [@?RFC3533]. -Bits 5 and 6 of the Block Header flags are set to `0b01`. +The LACING bits of the `Block` Header flags are set to `01b`. -The Block data with laced frames is stored as follows: +The `Block` data with laced frames is stored as follows: -* Lacing Head on 1 octet: Number of frames in the lace minus 1. +* Lacing Head on 1 Octet: Number of frames in the lace minus 1. * Lacing size of each frame except the last one. @@ -299,11 +299,11 @@ The Block data with laced frames is stored as follows: The lacing size is split into 255 values, stored as unsigned octets -- for example, 500 is coded 255;245 or [0xFF 0xF5]. A frame with a size multiple of 255 is coded with a 0 at the end of the size -- for example, 765 is coded 255;255;255;0 or [0xFF 0xFF 0xFF 0x00]. -The size of the last frame is deduced from the size remaining in the Block after the other frames. +The size of the last frame is deduced from the size remaining in the `Block` after the other frames. Because large sizes result in large coding of the sizes, it is **RECOMMENDED** to use Xiph lacing only with small frames. -In our example, the 800-, 500-, and 1000-octet frames are stored with Xiph lacing in a Block as follows: +In our example, the 800-, 500-, and 1000-octet frames are stored with Xiph lacing in a `Block` as follows: | Block Octets| Value | Description | |:------------|:------|:------------------------| @@ -315,17 +315,17 @@ In our example, the 800-, 500-, and 1000-octet frames are stored with Xiph lacin | 1311-2310 | | Third frame data | Table: Xiph Lacing Example{#blockXiphLacing} -The Block is 2311 octets, and the last frame starts at 1311, so we can deduce that the size of the last frame is 2311 - 1311 = 1000. +The `Block` is 2311 octets, and the last frame starts at 1311, so we can deduce that the size of the last frame is 2311 - 1311 = 1000. ### EBML Lacing The EBML lacing encodes the frame size with an EBML-like encoding [@!RFC8794]. -Bits 5 and 6 of the Block Header flags are set to `0b11`. +The LACING bits of the `Block` Header flags are set to `11b`. -The Block data with laced frames is stored as follows: +The `Block` data with laced frames is stored as follows: -* Lacing Head on 1 octet: Number of frames in the lace minus 1. +* Lacing Head on 1 Octet: Number of frames in the lace minus 1. * Lacing size of each frame except the last one. @@ -346,7 +346,7 @@ Bit Representation of Signed VINT | Possible Value Range 0000 1xxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx | 2^35 values from -(2^34^-1) to 2^34^ Table: EBML Lacing Signed VINT Bits Usage{#ebmlLacingBits} -In our example, the 800-, 500-, and 1000-octet frames are stored with EBML lacing in a Block as follows: +In our example, the 800-, 500-, and 1000-octet frames are stored with EBML lacing in a `Block` as follows: | Block Octets | Value | Description | |:-------------|:------|:------------------------| @@ -358,18 +358,18 @@ In our example, the 800-, 500-, and 1000-octet frames are stored with EBML lacin | 1308-2307 | | Third frame data | Table: EBML Lacing Example{#blockEbmlLacing} -The Block is 2308 octets, and the last frame starts at 1308, so we can deduce that the size of the last frame is 2308 - 1308 = 1000. +The `Block` is 2308 octets, and the last frame starts at 1308, so we can deduce that the size of the last frame is 2308 - 1308 = 1000. ### Fixed-size Lacing Fixed-size lacing doesn't store the frame size; rather, it only stores the number of frames in the lace. -Each frame **MUST** have the same size. The frame size of each frame is deduced from the total size of the Block. -Bits 5 and 6 of the Block Header flags are set to `0b10`. +Each frame **MUST** have the same size. The frame size of each frame is deduced from the total size of the `Block`. +The LACING bits of the `Block` Header flags are set to `10b`. -The Block data with laced frames is stored as follows: +The `Block` data with laced frames is stored as follows: -* Lacing Head on 1 octet: Number of frames in the lace minus 1. +* Lacing Head on 1 Octet: Number of frames in the lace minus 1. * Binary data of each frame consecutively. @@ -383,19 +383,19 @@ For example, for three frames that are 800 octets each: | 1605-2404 | | Third frame data | Table: Fixed-Size Lacing Example{#blockFixedSizeLacing} -This gives a Block of 2405 octets. When reading the Block, we find that there are three frames (Octet 4). +This gives a `Block` of 2405 octets. When reading the `Block`, we find that there are three frames (Octet 4). The data start at Octet 5, so the size of each frame is (2405 - 5) / 3 = 800. ### Laced Frames Timestamp -A Block only contains a single timestamp value. But when lacing is used, it contains more than one frame. +A `Block` only contains a single timestamp value. But when lacing is used, it contains more than one frame. Each frame originally has its own timestamp, or Presentation Timestamp (PTS). That timestamp applies to the first frame in the lace. In the lace, each frame after the first one has an underdetermined timestamp. However, each of these frames **MUST** be contiguous -- i.e., the decoded data **MUST NOT** contain any gap -between them. If there is a gap in the stream, the frames around the gap **MUST NOT** be in the same Block. +between them. If there is a gap in the stream, the frames around the gap **MUST NOT** be in the same `Block`. Lacing is only useful for small contiguous data to save space. This is usually the case for audio tracks and not the case for video (which use a lot of data) or subtitle tracks (which have long gaps). @@ -411,7 +411,7 @@ For subtitles, this is usually not the case, so lacing **SHOULD NOT** be used. Random Access Points (RAPs) are positions where the parser can seek to and start playback without decoding what was before. In Matroska, `BlockGroups` and `SimpleBlocks` can be RAPs. To seek to these elements, it is still necessary to seek to the `Cluster` containing them, -read the Cluster Timestamp, +read the `Cluster` Timestamp, and start playback from the `BlockGroup` or `SimpleBlock` that is a RAP. Because a Matroska File is usually composed of multiple tracks playing at the same time @@ -421,60 +421,55 @@ They are independent of each other and can be played randomly. On the other hand, video tracks often use references to previous and future frames for better coding efficiency. Frames with such references **MUST** either contain one or more -`ReferenceBlock` Elements in their `BlockGroup` or **MUST** be marked +`ReferenceBlock` elements in their `BlockGroup` or **MUST** be marked as non-keyframe in a `SimpleBlock`; see (#simpleblock-structure). -BlockGroup with a frame that references another frame, with the EBML tree shown as XML: - ```xml - - 123456 - - - -40 - - +<Cluster> + <Timestamp>123456</Timestamp> + <BlockGroup> + <!-- References a Block 40 Track Ticks before this one --> + <ReferenceBlock>-40</ReferenceBlock> + <Block/> + </BlockGroup> ... - +</Cluster> ``` - -SimpleBlock with a frame that references another frame, with the EBML tree shown as XML: +Figure: BlockGroup with a Frame That References Another Frame, with the EBML Tree Shown as XML ```xml - - 123456 - (octet 3 bit 0 not set) +<Cluster> + <Timestamp>123456</Timestamp> + <SimpleBlock/> (octet 3 bit 0 not set) ... - +</Cluster> ``` - +Figure: SimpleBlock with a Frame That References Another Frame, with the EBML Tree Shown as XML Frames that are RAPs (i.e., frames that don't depend on other frames) **MUST** set the keyframe flag if they are in a `SimpleBlock` or their parent `BlockGroup` **MUST NOT** contain a `ReferenceBlock`. -BlockGroup with a frame that references no other frame, with the EBML tree shown as XML: - ```xml - - 123456 - - - - +<Cluster> + <Timestamp>123456</Timestamp> + <BlockGroup> + <!-- No ReferenceBlock allowed in this BlockGroup --> + <Block/> + </BlockGroup> ... - +</Cluster> ``` - -SimpleBlock with a frame that references no other frame, with the EBML tree shown as XML: +Figure: BlockGroup with a Frame That References No Other Frame, with the EBML Tree Shown as XML ```xml - - 123456 - (octet 3 bit 0 set) +<Cluster> + <Timestamp>123456</Timestamp> + <SimpleBlock/> (octet 3 bit 0 set) ... - +</Cluster> ``` +Figure: SimpleBlock with a Frame That References No Other Frame, with the EBML Tree Shown as XML There may be cases where the use of `BlockGroup` is necessary, as the frame may need a @@ -482,30 +477,28 @@ There may be cases where the use of `BlockGroup` is necessary, as the frame may For thoses cases, a `SimpleBlock` **MUST NOT** be used; the reference information **SHOULD** be recovered for non-RAP frames. -SimpleBlock with a frame that references another frame, with the EBML tree shown as XML: - ```xml - - 123456 - (octet 3 bit 0 not set) +<Cluster> + <Timestamp>123456</Timestamp> + <SimpleBlock/> (octet 3 bit 0 not set) ... - +</Cluster> ``` - -Same frame that references another frame put inside a BlockGroup to add `BlockDuration`, with the EBML tree shown as XML: +Figure: SimpleBlock with a Frame That References Another Frame, with the EBML Tree Shown as XML ```xml - - 123456 - - - -40 - 20 - - +<Cluster> + <Timestamp>123456</Timestamp> + <BlockGroup> + <!-- ReferenceBlock value recovered based on the codec --> + <ReferenceBlock>-40</ReferenceBlock> + <BlockDuration>20</BlockDuration> + <Block/> + </BlockGroup> ... - +</Cluster> ``` +Figure: Same Frame That References Another Frame Put inside a `BlockGroup` to Add `BlockDuration`, with the EBML Tree Shown as XML When a frame in a `BlockGroup` is not a RAP, the `BlockGroup` **MUST** contain at least a `ReferenceBlock`. The `ReferenceBlock`s **MUST** be used in one of the following ways: @@ -519,36 +512,34 @@ The `ReferenceBlock`s **MUST** be used in one of the following ways: The lack of `ReferenceBlock` would mean such a frame is a RAP, and seeking on that frame that actually depends on other frames may create a bogus output or even crash. -* Same frame that references another frame put inside a BlockGroup but the reference could not be recovered, with the EBML tree shown as XML: - ```xml - - 123456 - - - 0 - 20 - - +<Cluster> + <Timestamp>123456</Timestamp> + <BlockGroup> + <!-- ReferenceBlock value not recovered from the codec --> + <ReferenceBlock>0</ReferenceBlock> + <BlockDuration>20</BlockDuration> + <Block/> + </BlockGroup> ... - +</Cluster> ``` - -* BlockGroup with a frame that references two other frames, with the EBML tree shown as XML: +Figure: Same Frame That References Another Frame Put inside a `BlockGroup`, but the Reference Could Not Be Recovered, with the EBML Tree Shown as XML ```xml - - 123456 - - - -80 - - 40 - - +<Cluster> + <Timestamp>123456</Timestamp> + <BlockGroup> + <!-- References a Block 80 Track Ticks before this one --> + <ReferenceBlock>-80</ReferenceBlock> + <!-- References a Block 40 Track Ticks after this one --> + <ReferenceBlock>40</ReferenceBlock> + <Block/> + </BlockGroup> ... - +</Cluster> ``` +Figure: `BlockGroup` with a Frame That References Two Other Frames, with the EBML Tree Shown as XML Intra-only video frames, such as the ones found in AV1 or VP9, can be decoded without any other frame, but they don't reset the codec state. Thus, seeking to these frames is not possible, @@ -558,19 +549,18 @@ Such intra-only frames **MUST NOT** be considered as keyframes, so the keyframe to signify the frame is not a RAP. The timestamp value of the `ReferenceBlock` **MUST** be "0", meaning it's referencing itself. -* Intra-only frame not an RAP, with the EBML tree shown as XML: - ```xml - - 123456 - - - 0 - - +<Cluster> + <Timestamp>123456</Timestamp> + <BlockGroup> + <!-- References itself to mark it should not be used as RAP --> + <ReferenceBlock>0</ReferenceBlock> + <Block/> + </BlockGroup> ... - +</Cluster> ``` +Figure: Intra-Only Frame (Not a RAP), with the EBML Tree Shown as XML Because a video `SimpleBlock` has less information on references than a video `BlockGroup`, it is possible to remux a video track using `BlockGroup` into a `SimpleBlock`, @@ -579,10 +569,10 @@ as long as it doesn't use any other `BlockGroup` features than `ReferenceBlock`. # Timestamps -Historically, timestamps in Matroska were mistakenly called timecodes. The `Timestamp Element` -was called Timecode, the `TimestampScale Element` was called TimecodeScale, the -`TrackTimestampScale Element` was called TrackTimecodeScale, and the -`ReferenceTimestamp Element` was called ReferenceTimeCode. +Historically, timestamps in Matroska were mistakenly called timecodes. The `Timestamp` element +was called Timecode, the `TimestampScale` element was called TimecodeScale, the +`TrackTimestampScale` element was called TrackTimecodeScale, and the +`ReferenceTimestamp` element was called ReferenceTimeCode. ## Timestamp Ticks @@ -592,7 +582,7 @@ There are three types of ticks possible: Matroska Ticks, Segment Ticks, and Trac ### Matroska Ticks -For such elements, the timestamp value is stored directly in nanoseconds. +The timestamp value is stored directly in nanoseconds. The elements storing values in Matroska Ticks/nanoseconds are: @@ -612,7 +602,7 @@ The elements storing values in Matroska Ticks/nanoseconds are: ### Segment Ticks -Elements in Segment Ticks involve the use of the `TimestampScale Element` of the Segment to get the timestamp +Elements in Segment Ticks involve the use of the `TimestampScale` element of the `Segment` to get the timestamp in nanoseconds of the element, with the following formula: timestamp in nanosecond = element value * TimestampScale @@ -635,7 +625,7 @@ The elements storing values in Segment Ticks are: ### Track Ticks -Elements in Track Ticks involve the use of the `TimestampScale Element` of the Segment and the `TrackTimestampScale Element` of the Track +Elements in Track Ticks involve the use of the `TimestampScale` element of the `Segment` and the `TrackTimestampScale` element of the `Track` to get the timestamp in nanoseconds of the element, with the following formula: timestamp in nanoseconds = @@ -658,28 +648,28 @@ When the `TrackTimestampScale` is interpreted as "1.0", Track Ticks are equivale and give an integer value in nanoseconds. This is the most common case as `TrackTimestampScale` is usually omitted. A value of `TrackTimestampScale` other than "1.0" **MAY** be used -to scale the timestamps more in tune with each Track sampling frequency. -For historical reasons, a lot of Matroska Readers don't take the `TrackTimestampScale` value into account. +to scale the timestamps more in tune with each `Track` sampling frequency. +For historical reasons, a lot of `Matroska Readers` don't take the `TrackTimestampScale` value into account. Thus, using a value other than "1.0" might not work in many places. ## Block Timestamps -A `Block Element` and `SimpleBlock Element` timestamp is the time when the decoded data of the first -frame in the Block/SimpleBlock **MUST** be presented if the track of that Block/SimpleBlock is selected for playback. +A `Block` element and `SimpleBlock` element timestamp is the time when the decoded data of the first +frame in the `Block`/`SimpleBlock` **MUST** be presented if the track of that `Block`/`SimpleBlock` is selected for playback. This is also known as the Presentation Timestamp (PTS). -The `Block Element` and `SimpleBlock Element` store their timestamps as signed integers, relative +The `Block` element and `SimpleBlock` element store their timestamps as signed integers, relative to the `Cluster\Timestamp` value of the `Cluster` they are stored in. To get the timestamp of a `Block` or `SimpleBlock` in nanoseconds, the following formula is used: ( Cluster\Timestamp + ( block timestamp * TrackTimestampScale ) ) * TimestampScale -The `Block Element` and `SimpleBlock Element` store their timestamps as 16-bit signed integers, +The `Block` element and `SimpleBlock` element store their timestamps as 16-bit signed integers, allowing a range from "-32768" to "+32767" Track Ticks. Although these values can be negative, when added to the `Cluster\Timestamp`, the resulting frame timestamp **SHOULD NOT** be negative. -When a `CodecDelay Element` is set, its value **MUST** be substracted from each Block timestamp of that track. +When a `CodecDelay` element is set, its value **MUST** be substracted from each `Block` timestamp of that track. To get the timestamp in nanoseconds of the first frame in a `Block` or `SimpleBlock`, the formula becomes: ( ( Cluster\Timestamp + ( block timestamp * TrackTimestampScale ) ) * @@ -694,22 +684,25 @@ During playback, when a frame has a negative timestamp, the content **MUST** be The default Track Tick duration is one millisecond. The `TimestampScale` is a floating-point value that is usually "1.0". But when it's not, the multiplied -Block Timestamp is a floating-point value in nanoseconds. +`Block` Timestamp is a floating-point value in nanoseconds. The `Matroska Reader` **SHOULD** use the nearest rounding value in nanoseconds to get -the proper nanosecond timestamp of a Block. This allows some clever `TimestampScale` values +the proper nanosecond timestamp of a `Block`. This allows some clever `TimestampScale` values to have a more refined timestamp precision per frame. # Language Codes -Matroska versions 1 through 3 uses language codes that can be either the three-letter +Matroska versions 1 through 3 use language codes that can be either the three-letter bibliographic ISO 639-2 form [@!ISO639-2] (like "fre" for French) or such a language code followed by a dash and a country code for specialities in languages (like "fre-ca" for Canadian French). -The `ISO 639-2 Language Elements` are "Language Element", "TagLanguage Element", and "ChapLanguage Element". +The `ISO 639-2 Language` elements are `Language` element, `TagLanguage` element, and `ChapLanguage` element. + +Starting in Matroska version 4, the forms defined in either [@!ISO639-2] or [@!RFC5646] **MAY** be used, +although the form in [@!RFC5646] is **RECOMMENDED**. The `Language` elements in the [@!RFC5646] form are `LanguageBCP47` element, +`TagLanguageBCP47` element, and `ChapLanguageBCP47` element. If both an [@!ISO639-2] Language element and an [@!RFC5646] Language element +are used within the same `Parent Element`, then the `Language` element in the [@!ISO639-2] form **MUST** be ignored and precedence given to the `Language` element in the [@!RFC5646] form. -Starting in Matroska version 4, either [@!ISO639-2] or [@!RFC5646] **MAY** be used, -although `BCP 47` is **RECOMMENDED**. The `BCP 47 Language Elements` are "LanguageBCP47 Element", -"TagLanguageBCP47 Element", and "ChapLanguageBCP47 Element". If a `BCP 47 Language Element` and an `ISO 639-2 Language Element` -are used within the same `Parent Element`, then the `ISO 639-2 Language Element` **MUST** be ignored and precedence given to the `BCP 47 Language Element`. +In this document, "BCP47" in element names refers specifically to +[@!RFC5646], which is part of BCP 47. # Country Codes @@ -720,7 +713,7 @@ Country codes are the [@!RFC5646] two-letter region subtags, without the UK exce This Matroska specification provides no interoperable solution for securing the data container with any assurances of confidentiality, integrity, authenticity, -or to provide authorization. The `ContentEncryption Element` ((#contentencryption-element)) +or authorization. The `ContentEncryption` element ((#contentencryption-element)) and associated sub-fields ((#contentencalgo-element) to (#aessettingsciphermode-element)) are defined only for the benefit of implementers to construct their own proprietary solution or as the basis for further standardization activities. How to use these @@ -730,7 +723,7 @@ issues such as key management and distribution. A `Matroska Reader` who encounters containers that use the fields defined in this section **MUST** rely on out-of-scope guidance to decode the associated content. -Because encryption occurs within the `Block Element`, it is possible to manipulate +Because encryption occurs within the `Block` element, it is possible to manipulate encrypted streams without decrypting them. The streams could potentially be copied, deleted, cut, appended, or any number of other possible editing techniques without decryption. The data can be used without having to expose it or go through the decrypting process. @@ -738,7 +731,7 @@ decryption. The data can be used without having to expose it or go through the d Encryption can also be layered within Matroska. This means that two completely different types of encryption can be used, requiring two separate keys to be able to decrypt a stream. -Encryption information is stored in the `ContentEncodings Element` under the `ContentEncryption Element`. +Encryption information is stored in the `ContentEncodings` element under the `ContentEncryption` element. For encryption systems sharing public/private keys, the creation of the keys and the exchange of keys are not covered by this document. They have to be handled by the system using Matroska. @@ -749,8 +742,8 @@ parameters is required for a complete solution but is out of scope of this document and left to the proprietary implementations using them or subsequent profiles of this document. -The `ContentEncodingScope Element` gives an idea of which part of the track is encrypted, -but each `ContentEncAlgo Element` and its sub-elements (like `AESSettingsCipherMode`) +The `ContentEncodingScope` element gives an idea of which part of the track is encrypted, +but each `ContentEncAlgo` element and its sub-elements (like `AESSettingsCipherMode`) define exactly how the encrypted track should be interpreted. An example of an extension that builds upon these security-related fields in this specification is [@?WebM-Enc]. @@ -764,11 +757,10 @@ previously made archives or streams. ## Cropping -The `PixelCrop Elements` (`PixelCropTop`, `PixelCropBottom`, `PixelCropRight`, and `PixelCropLeft`) +The `PixelCrop` elements (`PixelCropTop`, `PixelCropBottom`, `PixelCropRight`, and `PixelCropLeft`) indicate when, and by how much, encoded video frames **SHOULD** be cropped for display. -These Elements allow edges of the frame that are not intended for display (such as the -sprockets of a full-frame film scan or the VANC area of a digitized analog videotape) -to be stored but hidden. `PixelCropTop` and `PixelCropBottom` store an integer of how many +These elements allow edges of the frame that are not intended for display (such as the +sprockets of a full-frame film scan or the Video ANCillary (VANC) area of a digitized analog videotape) to be stored but hidden. `PixelCropTop` and `PixelCropBottom` store an integer of how many rows of pixels **SHOULD** be cropped from the top and bottom of the image, respectively. `PixelCropLeft` and `PixelCropRight` store an integer of how many columns of pixels **SHOULD** be cropped from the left and right of the image, respectively. @@ -784,40 +776,40 @@ Cropping has to be performed before resizing and the display dimensions given by ## Rotation -The ProjectionPoseRoll Element ((#projectionposeroll-element)) can be used to indicate +The `ProjectionPoseRoll` element ((#projectionposeroll-element)) can be used to indicate that the image from the associated video track **SHOULD** be rotated for presentation. -For instance, the following example of the Projection Element ((#projection-element)) -and the ProjectionPoseRoll Element represents a video track where the image **SHOULD** be +For instance, the following example of the `Projection` element ((#projection-element)) +and the `ProjectionPoseRoll` element represents a video track where the image **SHOULD** be presented with a 90-degree counter-clockwise rotation, with the EBML tree shown as XML: ```xml - - 90 - +<Projection> + <ProjectionPoseRoll>90</ProjectionPoseRoll> +</Projection> ``` Figure: Rotation Example # Segment Position -The `Segment Position` of an `Element` refers to the position of the first octet of the -`Element ID` of that `Element`, measured in octets, from the beginning of the `Element Data` -section of the containing `Segment Element`. In other words, the `Segment Position` of an -`Element` is the distance in octets from the beginning of its containing `Segment Element` -minus the size of the `Element ID` and `Element Data Size` of that `Segment Element`. -The `Segment Position` of the first `Child Element` of the `Segment Element` is 0. -An `Element` that is not stored within a `Segment Element`, such as the `Elements` of +The `Segment Position` of an element refers to the position of the first octet of the +`Element ID` of that element, measured in octets, from the beginning of the `Element Data` +section of the containing `Segment` element. In other words, the `Segment Position` of an +element is the distance in octets from the beginning of its containing `Segment` element +minus the size of the `Element ID` and `Element Data Size` of that `Segment` element. +The `Segment Position` of the first `Child Element` of the `Segment` element is 0. +An element that is not stored within a `Segment` element, such as the elements of the `EBML Header`, do not have a `Segment Position`. ## Segment Position Exception -`Elements` that are defined to store a `Segment Position` **MAY** define reserved values to +Elements that are defined to store a `Segment Position` **MAY** define reserved values to indicate a special meaning. ## Example of Segment Position This table presents an example of `Segment Position` by showing a hexadecimal representation of a very small Matroska file with labels to show the offsets in octets. The file contains -a `Segment Element` with an `Element ID` of "0x18538067" and a `MuxingApp Element` with an `Element ID` of "0x4D80". +a `Segment` element with an `Element ID` of "0x18538067" and a `MuxingApp` element with an `Element ID` of "0x4D80". 0 1 2 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 @@ -833,20 +825,20 @@ a `Segment Element` with an `Element ID` of "0x18538067" and a `MuxingApp Elemen 20 | |4D|80|84|69|65|74|66|57|41|84|69|65|74|66| ^ MuxingApp start -In the above example, the `Element ID` of the `Segment Element` is stored at offset 16, -the `Element Data Size` of the `Segment Element` is stored at offset 20, and the -`Element Data` of the `Segment Element` is stored at offset 21. +In the above example, the `Element ID` of the `Segment` element is stored at offset 16, +the `Element Data Size` of the `Segment` element is stored at offset 20, and the +`Element Data` of the `Segment` element is stored at offset 21. -The `MuxingApp Element` is stored at offset 26. Since the `Segment Position` of -an `Element` is calculated by subtracting the position of the `Element Data` of -the containing `Segment Element` from the position of that `Element`, the `Segment Position` -of the `MuxingApp Element` in the above example is "26 - 21" or "5". +The `MuxingApp` element is stored at offset 26. Since the `Segment Position` of +an element is calculated by subtracting the position of the `Element Data` of +the containing `Segment` element from the position of that element, the `Segment Position` +of the `MuxingApp` element in the above example is "26 - 21" or "5". # Linked Segments -Matroska provides several methods to link two or more `Segment Elements` together to create +Matroska provides several methods to link two or more `Segment` elements together to create a `Linked Segment`. A `Linked Segment` is a set of multiple `Segments` linked together into a single presentation by using Hard Linking or Medium Linking. @@ -860,12 +852,12 @@ All `Segments` within a `Linked Segment` **MAY** set a `SegmentFamily` with a co it easier for a `Matroska Player` to know which `Segments` are meant to be played together. The `SegmentFilename`, `PrevFilename`, and `NextFilename` elements **MAY** also give hints on -the original filenames that were used when the Segment links were created, in case some `SegmentUUIDs` are damaged. +the original filenames that were used when the `Segment` links were created, in case some `SegmentUUIDs` are damaged. ## Hard Linking Hard Linking, also called "splitting", is the process of creating a `Linked Segment` -by linking multiple `Segment Elements` using the `NextUUID` and `PrevUUID` Elements. +by linking multiple `Segment` elements using the `NextUUID` and `PrevUUID` elements. All `Segments` within a `Hard Linked Segment` **MUST** use the same `Tracks` list and `TimestampScale`. @@ -875,17 +867,17 @@ the timestamps of `Block` and `SimpleBlock` from the previous `Segment` in linki With Hard Linking, the chapters of any `Segment` within the `Linked Segment` **MUST** only reference the current `Segment`. The `NextUUID` and `PrevUUID` reference the respective `SegmentUUID` values of the next and previous `Segments`. -The first `Segment` of a `Linked Segment` **MUST NOT** have a `PrevUUID Element`. -The last `Segment` of a `Linked Segment` **MUST NOT** have a `NextUUID Element`. +The first `Segment` of a `Linked Segment` **MUST NOT** have a `PrevUUID` element. +The last `Segment` of a `Linked Segment` **MUST NOT** have a `NextUUID` element. -For each node of the chain of `Segments` of a `Linked Segment`; at least one `Segment` **MUST** reference the other `Segment` within the chain. +For each node of the chain of `Segments` of a `Linked Segment`, at least one `Segment` **MUST** reference the other `Segment` within the chain. In a chain of `Segments` of a `Linked Segment`, the `NextUUID` always takes precedence over the `PrevUUID`. Thus, if SegmentA has a `NextUUID` to SegmentB and SegmentB has a `PrevUUID` to SegmentC, -the link to use is `NextUUID` between SegmentA and SegmentB, and SegmentC is not part of the Linked Segment. +the link to use is `NextUUID` between SegmentA and SegmentB, and SegmentC is not part of the `Linked Segment`. -If SegmentB has a `PrevUUID` to SegmentA, but SegmentA has no `NextUUID`, then the Matroska Player -**MAY** consider these two Segments linked as SegmentA followed by SegmentB. +If SegmentB has a `PrevUUID` to SegmentA, but SegmentA has no `NextUUID`, then the `Matroska Player` +**MAY** consider these two `Segments` linked as SegmentA followed by SegmentB. As an example, three `Segments` can be Hard Linked as a `Linked Segment` through cross-referencing each other with `SegmentUUID`, `PrevUUID`, and `NextUUID` as shown in this table: @@ -897,7 +889,7 @@ file name | `SegmentUUID` | `PrevUUID` `end.mkv` | 6c92285fa6d3e827 b198d120ea3ac674 | a77b3598941cb803 eac0fcdafe44fac9 | Invalid Table: Usual Hard Linking UIDs{#hardLinkingUIDs} -An example where only the `NextUUID` Element is used: +An example where only the `NextUUID` element is used: file name | `SegmentUUID` | `PrevUUID` | `NextUUID` :-----------|:----------------------------------|:----------------------------------|:--------- @@ -906,7 +898,7 @@ file name | `SegmentUUID` | `PrevUUID` `end.mkv` | 6c92285fa6d3e827 b198d120ea3ac674 | n/a | Invalid Table: Hard Linking without PrevUUID{#hardLinkingWoPrevUUID} -An example where only the `PrevUUID` Element is used: +An example where only the `PrevUUID` element is used: file name | `SegmentUUID` | `PrevUUID` | `NextUUID` :-----------|:----------------------------------|:----------------------------------|:--------- @@ -915,7 +907,7 @@ file name | `SegmentUUID` | `PrevUUID` `end.mkv` | 6c92285fa6d3e827 b198d120ea3ac674 | a77b3598941cb803 eac0fcdafe44fac9 | Invalid Table: Hard Linking without NextUUID{#hardLinkingWoNextUUID} -An example where only the `middle.mkv` is using the `PrevUUID` and `NextUUID` Elements: +An example where only the `middle.mkv` is using the `PrevUUID` and `NextUUID` elements: file name | `SegmentUUID` | `PrevUUID` | `NextUUID` :-----------|:----------------------------------|:----------------------------------|:--------- @@ -926,24 +918,24 @@ Table: Hard Linking with Mixed UID Links{#hardLinkingMixedUIDs} ## Medium Linking -Medium Linking creates relationships between `Segments` using Ordered Chapters ((#editionflagordered)) and the -`ChapterSegmentUUID Element`. A `Chapter Edition` with Ordered Chapters **MAY** contain -Chapter elements that reference timestamp ranges from other `Segments`. The `Segment` -referenced by the Ordered Chapter via the `ChapterSegmentUUID Element` **SHOULD** be played as -part of a Linked Segment. +Medium Linking creates relationships between `Segments` using `Ordered Chapters` ((#editionflagordered)) and the +`ChapterSegmentUUID` element. A `Chapter Edition` with `Ordered Chapters` **MAY** contain +`Chapters` elements that reference timestamp ranges from other `Segments`. The `Segment` +referenced by the `Ordered Chapter` via the `ChapterSegmentUUID` element **SHOULD** be played as +part of a `Linked Segment`. -The timestamps of Segment content referenced by Ordered Chapters -**MUST** be adjusted according to the cumulative duration of the previous Ordered Chapters. +The timestamps of `Segment` content referenced by `Ordered Chapters` +**MUST** be adjusted according to the cumulative duration of the previous `Ordered Chapters`. As an example, a file named `intro.mkv` could have a `SegmentUUID` of "0xb16a58609fc7e60653a60c984fc11ead". -Another file called `program.mkv` could use a Chapter Edition that contains two Ordered Chapters. +Another file called `program.mkv` could use a `Chapter Edition` that contains two `Ordered Chapters`. The first chapter references the `Segment` of `intro.mkv` with the use of a `ChapterSegmentUUID`, `ChapterSegmentEditionUID`, `ChapterTimeStart`, and an optional `ChapterTimeEnd` element. The second chapter references content within the `Segment` of `program.mkv`. A `Matroska Player` **SHOULD** recognize the `Linked Segment` created by the use of `ChapterSegmentUUID` in an enabled `Edition` and present the reference content of the two `Segments` as a single presentation. -The `ChapterSegmentUUID` represents the Segment that holds the content to play in place of the `Linked Chapter`. +The `ChapterSegmentUUID` represents the `Segment` that holds the content to play in place of the `Linked Chapter`. The `ChapterSegmentUUID` **MUST NOT** be the `SegmentUUID` of its own `Segment`. There are two ways to use a chapter link: @@ -954,20 +946,20 @@ There are two ways to use a chapter link: ### Linked-Duration -A `Matroska Player` **MUST** play the content of the linked Segment +A `Matroska Player` **MUST** play the content of the `Linked Segment` from the `ChapterTimeStart` until the `ChapterTimeEnd` timestamp in place of the `Linked Chapter`. -`ChapterTimeStart` and `ChapterTimeEnd` represent timestamps in the Linked Segment matching the value of `ChapterSegmentUUID`. -Their values **MUST** be in the range of the linked Segment duration. +`ChapterTimeStart` and `ChapterTimeEnd` represent timestamps in the `Linked Segment` matching the value of `ChapterSegmentUUID`. +Their values **MUST** be in the range of the `Linked Segment` duration. The `ChapterTimeEnd` value **MUST** be set when using Linked-Duration chapter linking. `ChapterSegmentEditionUID` **MUST NOT** be set. ### Linked-Edition -A `Matroska Player` **MUST** play the whole Linked `Edition` of the linked Segment in place of the `Linked Chapter`. +A `Matroska Player` **MUST** play the whole `Linked Edition` of the `Linked Segment` in place of the `Linked Chapter`. -`ChapterSegmentEditionUID` represents a valid Edition from the Linked Segment matching the value of `ChapterSegmentUUID`. +`ChapterSegmentEditionUID` represents a valid `Edition` from the `Linked Segment` matching the value of `ChapterSegmentUUID`. When using Linked-Edition chapter linking, `ChapterTimeEnd` is **OPTIONAL**. @@ -982,7 +974,7 @@ The Default flag is a hint for a `Matroska Player` indicating that a given track language. If no tracks in a given language have the Default flag set, then all tracks in that language are eligible for automatic selection. This can be used to indicate that a track provides "regular service" that is suitable for users with default settings, as opposed to -specialized services, such as commentary, hearing-impaired captions, or descriptive audio. +specialized services, such as commentary, captions for users with hearing impairments, or descriptive audio. The `Matroska Player` **MAY** override the Default flag for any reason, including user preferences to prefer tracks providing accessibility services. @@ -997,19 +989,19 @@ of on-screen text or dialogue spoken in a different language than the track's pr ## Hearing-Impaired Flag The Hearing-Impaired flag tells the `Matroska Player` that it **SHOULD** prefer this track -when selecting a default track for a hearing-impaired user and that it **MAY** prefer to select -a different track when selecting a default track for a user that is not hearing-impaired. +when selecting a default track for a user with a hearing impairment and that it **MAY** prefer to select +a different track when selecting a default track for a user that is not hearing impaired. ## Visual-Impaired Flag The Visual-Impaired flag tells the `Matroska Player` that it **SHOULD** prefer this track -when selecting a default track for a visually impaired user and that it **MAY** prefer to select +when selecting a default track for a user with a visual impairment and that it **MAY** prefer to select a different track when selecting a default track for a user that is not visually impaired. ## Descriptions Flag The Descriptions flag tells the `Matroska Player` that this track is suitable to play via -a text-to-speech system for a visually impaired user and that it **SHOULD NOT** automatically +a text-to-speech system for a user with a visual impairment and that it **SHOULD NOT** automatically select this track when selecting a default track for a user that is not visually impaired. ## Original Flag @@ -1031,19 +1023,19 @@ and one to simplify join two tracks together to make a single track. A track created with `TrackOperation` is a proper track with a UID and all its flags. However, the codec ID is meaningless because each "sub" track needs to be decoded by its -own decoder before the "operation" is applied. The `Cues Elements` corresponding to such -a virtual track **SHOULD** be the union of the `Cues Elements` for each of the tracks it's composed of (when the `Cues` are defined per track). +own decoder before the "operation" is applied. The `Cues` elements corresponding to such +a virtual track **SHOULD** be the union of the `Cues` elements for each of the tracks it's composed of (when the `Cues` are defined per track). -In the case of `TrackJoinBlocks`, the `Block Elements` (from `BlockGroup` and `SimpleBlock`) +In the case of `TrackJoinBlocks`, the `Block` elements (from `BlockGroup` and `SimpleBlock`) of all the tracks **SHOULD** be used as if they were defined for this new virtual `Track`. -When two `Block Elements` have overlapping start or end timestamps, it's up to the underlying +When two `Block` elements have overlapping start or end timestamps, it's up to the underlying system to either drop some of these frames or render them the way they overlap. This situation **SHOULD** be avoided when creating such tracks, as you can never be sure of the end result on different platforms. ## Overlay Track -Overlay tracks **SHOULD** be rendered in the same channel as the track it's linked to. +An overlay track **SHOULD** be rendered in the same channel as the track it's linked to. When content is found in such a track, it **SHOULD** be played on the rendering channel instead of the original track. @@ -1053,13 +1045,14 @@ There are two different ways to compress 3D videos: have each eye track in a sep and have one track have both eyes combined inside (which is more efficient compression-wise). Matroska supports both ways. -For the single-track variant, there is the `StereoMode Element`, which defines how planes are -assembled in the track (mono or left-right combined). Odd values of StereoMode means the left +For the single-track variant, there is the `StereoMode` element, which defines how planes are +assembled in the track (mono or left-right combined). Odd values of `StereoMode` means the left plane comes first for more convenient reading. The pixel count of the track (`PixelWidth`/`PixelHeight`) -is the raw amount of pixels (for example, 3840x1080 for full HD side by side), and the `DisplayWidth`/`DisplayHeight` -in pixels is the amount of pixels for one plane (1920x1080 for that full HD stream). -Old stereo 3D were displayed using anaglyph (cyan and red colors separated). -For compatibility with such movies, there is a value of the StereoMode that corresponds to AnaGlyph. +is the raw number of pixels (for example, 3840x1080 for full HD side by side), and the +`DisplayWidth`/`DisplayHeight` +in pixels is the number of pixels for one plane (1920x1080 for that full HD stream). +Old stereo 3D movies were displayed using anaglyph (cyan and red colors separated). +For compatibility with such movies, there is a value of the `StereoMode` that corresponds to anaglyph. There is also a "packed" mode (values 13 and 14) that consists of packing two frames together in a `Block` that uses lacing. The first frame is the left eye and the other frame is the right eye @@ -1068,27 +1061,27 @@ on each other (P and B frames). For separate tracks, Matroska needs to define exactly which track does what. `TrackOperation` with `TrackCombinePlanes` does that. For more details, see -(#track-operation) on how TrackOperation works. +(#track-operation) on how `TrackOperation` works. The 3D support is still in infancy and may evolve to support more features. -The StereoMode used to be part of Matroska v2, but it didn't meet the requirement +The `StereoMode` used to be part of Matroska v2, but it didn't meet the requirement for multiple tracks. There was also a bug in [@?libmatroska] prior to 0.9.0 that would save/read -it as `0x53B9` instead of `0x53B8`; see OldStereoMode ((#oldstereomode-element)). `Matroska Readers` **MAY** support these legacy files by checking +it as `0x53B9` instead of `0x53B8`; see `OldStereoMode` ((#oldstereomode-element)). `Matroska Readers` **MAY** support these legacy files by checking Matroska v2 or `0x53B9`. -The older values of StereoMode were 0 (mono), 1 (right eye), 2 (left eye), and 3 (both eyes); these are the only values that can be found in OldStereoMode. -They are not compatible with the StereoMode values found in Matroska v3 and above. +The older values of `StereoMode` were 0 (mono), 1 (right eye), 2 (left eye), and 3 (both eyes); these are the only values that can be found in `OldStereoMode`. +They are not compatible with the `StereoMode` values found in Matroska v3 and above. # Default Track Selection -This section provides some example sets of Tracks and hypothetical user settings, along with +This section provides some example sets of `Tracks` and hypothetical user settings, along with indications of which ones a similarly configured `Matroska Player` **SHOULD** automatically select for playback by default in such a situation. A player **MAY** provide additional settings with more detailed controls for more nuanced scenarios. These examples are provided as guidelines -to illustrate the intended usages of the various supported Track flags and their expected behaviors. +to illustrate the intended usages of the various supported `Track` flags and their expected behaviors. -Track names are shown in English for illustrative purposes; actual files may have titles +`Track` names are shown in English for illustrative purposes; actual files may have titles in the language of each track or provide titles in multiple languages. ## Audio Selection @@ -1113,7 +1106,7 @@ The English tracks all have the Original flag, indicating that English is the or Generally, the player will first consider the track languages. If the player has an option to prefer original-language audio and the user has enabled it, then it should prefer one of the tracks with the Original flag. -If configured to specifically prefer audio tracks in English or Spanish, the player should select one of +If the user has configured to specifically prefer audio tracks in English or Spanish, the player should select one of the tracks in the corresponding language. The player may also wish to prefer a track with the Original flag if no tracks matching any of the user's explicitly preferred languages are available. @@ -1122,7 +1115,7 @@ it should select one; otherwise, it should avoid them if possible. If selecting an English track, when other settings have left multiple possible options, it may be useful to exclude the tracks that lack the Default flag. Here, one provides descriptive service for -the visually impaired (which has its own flag and may be automatically selected by user configuration +individuals with visual impairments (which has its own flag and may be automatically selected by user configuration but is unsuitable for users with default-configured players), one is a commentary track (which has its own flag and the player may or may not have specialized handling for), and the last contains karaoke versions of the music that plays during the film (which is an unusual @@ -1149,7 +1142,7 @@ Example track set: | 2 | Audio | fra | 1 | 1 | N/A | None | | | 3 | Audio | por | 0 | 1 | N/A | None | | | 4 | Subtitles | fra | 1 | 1 | 0 | None | | -| 5 | Subtitles | fra | 1 | 0 | 0 | Hearing-Impaired | Captions for the hearing-impaired | +| 5 | Subtitles | fra | 1 | 0 | 0 | Hearing-Impaired | Captions for users with hearing impairments | | 6 | Subtitles | por | 0 | 1 | 0 | None | | | 7 | Subtitles | por | 0 | 0 | 1 | None | Signs | | 8 | Subtitles | por | 0 | 0 | 0 | Hearing-Impaired | SDH | diff --git a/ordering.md b/ordering.md index 440de27ac..3c4d31982 100644 --- a/ordering.md +++ b/ordering.md @@ -1,99 +1,99 @@ # 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 +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`. +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 `Track` Element or a `Cluster` Element. +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 `Track` 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 `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 +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 +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`. +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` +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`. +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`. +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`. +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** +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`. +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` +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`. +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`. +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. +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`. +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 +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`. +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 +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. +`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. diff --git a/rfc_backmatter_matroska.md b/rfc_backmatter_matroska.md index 388be66a1..dd44e10b6 100644 --- a/rfc_backmatter_matroska.md +++ b/rfc_backmatter_matroska.md @@ -51,7 +51,7 @@ RFC Errata - + RFC 8794 @@ -61,7 +61,7 @@ RFC Errata - + RFC 8794 @@ -155,7 +155,7 @@ International Organization for Standardization - + @@ -217,9 +217,8 @@ libmatroska - Matroska.org - Matroska.org - + + @@ -234,7 +233,7 @@ - + Twofish: A 128-Bit Block Cipher diff --git a/streaming.md b/streaming.md index 63da713ee..3ef4d3cbc 100644 --- a/streaming.md +++ b/streaming.md @@ -10,7 +10,7 @@ are usually safe from reading errors, and seeking in the stream is possible. How when a file is stored far away or on a slow server, seeking can be an expensive operation and should be avoided. When followed, the guidelines in (#implementation-recommendations) help reduce the number of seeking operations for regular playback and also have the playback start quickly without -a lot of data needed to read first (like a `Cues Element`, `Attachment Element`, or `SeekHead Element`). +needing to read lot of data first (like a `Cues` element, `Attachments` element, or `SeekHead` element). Matroska, having a small overhead, is well suited for storing music/videos on file servers without a big impact on the bandwidth used. Matroska does not require the index @@ -28,11 +28,11 @@ Livestreaming of Matroska over file-like protocols like HTTP, QUIC, etc., is pos A live Matroska stream is different from a file because it usually has no known end (only ending when the client disconnects). For this, all bits of the "size" portion -of the `Segment Element` **MUST** be set to 1. Another option is to concatenate `Segment Elements` +of the `Segment` element **MUST** be set to 1. Another option is to concatenate `Segment` elements with known sizes, one after the other. This solution allows a change of codec/resolution between each segment. For example, this allows for a switch between 4:3 and 16:9 in a television program. -When `Segment Elements` are continuous, certain `Elements` (like `SeekHead`, `Cues`, +When `Segment` elements are continuous, certain elements (like `SeekHead`, `Cues`, `Chapters`, and `Attachments`) **MUST NOT** be used. It is possible for a `Matroska Player` to detect that a stream is not seekable. @@ -41,6 +41,6 @@ it **SHOULD** be considered non-seekable. Even though it is possible to seek for in the stream, it is **NOT RECOMMENDED**. In the context of live radio or web TV, it is possible to "tag" the content while it is -playing. The `Tags Element` can be placed between `Clusters` each time it is necessary. -In that case, the new `Tags Element` **MUST** reset the previously encountered `Tags Elements` +playing. The `Tags` element can be placed between `Clusters` each time it is necessary. +In that case, the new `Tags` element **MUST** reset the previously encountered `Tags` elements and use the new values instead. diff --git a/subtitles.md b/subtitles.md index 575199c95..43d114ffe 100644 --- a/subtitles.md +++ b/subtitles.md @@ -171,7 +171,7 @@ It consists of four parts, all in text: When placing SRT in Matroska, part 3 is converted to UTF-8 (S_TEXT/UTF8) and placed in the data portion of the Block. Part 2 is used to set the timestamp of the Block, -and BlockDuration element. Nothing else is used. +and `BlockDuration` element. Nothing else is used. Here is an example SRT file: @@ -188,7 +188,7 @@ Very good, Lieutenant. In this example, the text "Senator, we're making our final approach into Coruscant." would be converted into UTF-8 and placed in the Block. The timestamp of the block would -be set to "00:02:17,440". And the BlockDuration element would be set to "00:00:02,935". +be set to "00:02:17,440". And the `BlockDuration` element would be set to "00:00:02,935". The same is repeated for the next subtitle. @@ -255,7 +255,7 @@ Now, how are they stored in Matroska? * All the headers are stored in CodecPrivate (Script Info and the Styles list) * Start & End field are used to set TimeStamp - and the BlockDuration element. the data stored is: + and the `BlockDuration` element. the data stored is: * Events are stored in the Block in this order: ReadOrder, Layer, Style, Name, MarginL, MarginR, MarginV, Effect, Text (Layer comes from ASS specs ... it's empty for SSA.) "ReadOrder field is needed @@ -404,7 +404,7 @@ the Matroska Block's duration. #### BlockAdditions: storing non-global WebVTT blocks, Cue Settings Lists and Cue identifiers -Each Matroska Block may be accompanied by one BlockAdditions element. Its format is as follows: +Each Matroska Block may be accompanied by one `BlockAdditions` element. Its format is as follows: 1. The first line contains the WebVTT Cue Text's optional Cue Settings List followed by one line feed character (U+0x000a). The Cue Settings List may be empty, in which case @@ -617,7 +617,7 @@ in the document "Blu-ray Disc Read-Only Format; Part 3 — Audio Visual Basic Sp The CodecID to use is `S_HDMV/TEXTST`. -A CodecPrivate Element is required. It **MUST** contain the stream's Dialog Style Segment +A CodecPrivate element is required. It **MUST** contain the stream's Dialog Style Segment as described in section 9.15.4.2 "Dialog Style Segment" of the Blu-ray specifications. #### Storage of HDMV TextST Dialog Presentation Segments in Matroska Blocks diff --git a/tagging.md b/tagging.md index 57a62425f..fa0743fbe 100644 --- a/tagging.md +++ b/tagging.md @@ -17,8 +17,8 @@ then your tag tree would look something like this: In this way, it becomes possible to store any Tag as attributes of another tag. -Multiple items **SHOULD** never be stored as a list in a single TagString. If there is more -than one tag of a certain type to be stored, then more than one SimpleTag **SHOULD** be used. +Multiple items **SHOULD** never be stored as a list in a single `TagString`. If there is more +than one tag of a certain type to be stored, then more than one `SimpleTag` **SHOULD** be used. ## Why Official Tags Matter diff --git a/tagging_end.md b/tagging_end.md index 2e89b90c2..bab841977 100644 --- a/tagging_end.md +++ b/tagging_end.md @@ -1,6 +1,6 @@ ## Notes In the Target list, a logical OR is applied on all tracks, a logical OR is applied on all chapters. -Then a logical AND is applied between the Tracks list and the Chapters list to know +Then a logical AND is applied between the `Tracks` list and the Chapters list to know if an element belongs to this Target. diff --git a/tags-precedence.md b/tags-precedence.md index 678227bc1..c942e87cb 100644 --- a/tags-precedence.md +++ b/tags-precedence.md @@ -4,21 +4,21 @@ Tags allow tagging all kinds of Matroska parts with very detailed metadata in multiple languages. -Some Matroska elements also contain their own string value, like the Track Name ((#name-element)) or the Chapter String ((#chapstring-element)). +Some Matroska elements also contain their own string value, like the track `Name` element ((#name-element)) or the `ChapString` element ((#chapstring-element)). The following Matroska elements can also be defined with tags: -* The Track Name Element ((#name-element)) corresponds to a tag with the TagTrackUID ((#tagtrackuid-element)) set to the given track, a TagName of `TITLE` ((#tagname-element)), and a TagLanguage ((#taglanguage-element)) or TagLanguageBCP47 ((#taglanguagebcp47-element)) of "und". +* The track `Name` element ((#name-element)) corresponds to a tag with the `TagTrackUID` ((#tagtrackuid-element)) set to the given track, a `TagName` of `TITLE` ((#tagname-element)), and a `TagLanguage` ((#taglanguage-element)) or `TagLanguageBCP47` ((#taglanguagebcp47-element)) of "und". -* The Chapter String Element ((#chapstring-element)) corresponds to a tag with the TagChapterUID ((#tagchapteruid-element)) set to the same chapter UID, a TagName of `TITLE` ((#tagname-element)), and a TagLanguage ((#taglanguage-element)) or TagLanguageBCP47 ((#taglanguagebcp47-element)) matching the ChapLanguage ((#chaplanguage-element)) or ChapLanguageBCP47 ((#chaplanguagebcp47-element)), respectively. +* The `ChapString` element ((#chapstring-element)) corresponds to a tag with the `TagChapterUID` ((#tagchapteruid-element)) set to the same chapter UID, a `TagName` of `TITLE` ((#tagname-element)), and a `TagLanguage` ((#taglanguage-element)) or `TagLanguageBCP47` ((#taglanguagebcp47-element)) matching the `ChapLanguage` ((#chaplanguage-element)) or `ChapLanguageBCP47` ((#chaplanguagebcp47-element)), respectively. -* The FileDescription Element ((#filedescription-element)) of an attachment corresponds to a tag with the TagAttachmentUID ((#tagattachmentuid-element)) set to the given attachment, a TagName of `TITLE` ((#tagname-element)), and a TagLanguage ((#taglanguage-element)) or TagLanguageBCP47 ((#taglanguagebcp47-element)) of "und". +* The `FileDescription` element ((#filedescription-element)) of an attachment corresponds to a tag with the `TagAttachmentUID` ((#tagattachmentuid-element)) set to the given attachment, a `TagName` of `TITLE` ((#tagname-element)), and a `TagLanguage` ((#taglanguage-element)) or `TagLanguageBCP47` ((#taglanguagebcp47-element)) of "und". When both values exist in the file, the value found in Tags takes precedence over the value found in the original location of the element. -For example, if you have a `TrackEntry\Name` element and Tag `TITLE` for that track in a Matroska Segment, the Tag string **SHOULD** be used instead of the `TrackEntry\Name` string to identify the track. +For example, if you have a `TrackEntry\Name` element and a tag value `TITLE` for that track in a Matroska `Segment`, the tag value string **SHOULD** be used instead of the `TrackEntry\Name` string to identify the track. As the Tag element is optional, a lot of `Matroska Readers` do not handle it and will not use the tags value when it's found. -Thus, for maximum compatibility, it's usually better to put the strings in the `TrackEntry`, `ChapterAtom`, and `Attachment` +Thus, for maximum compatibility, it's usually better to put the strings in the `TrackEntry`, `ChapterAtom`, and `Attachments` elements and keep the tags matching these values if tags are also used. ## Tag Levels diff --git a/tags_iana.md b/tags_iana.md index 2a185d360..83b3a4bc1 100644 --- a/tags_iana.md +++ b/tags_iana.md @@ -10,7 +10,7 @@ a Name, a Type, a Change Controller (IETF or email of registrant), and an optional Reference to a document describing the Element ID. -The Name corresponds to the value stored in the `TagName` Element. +The Name corresponds to the value stored in the `TagName` element. The Name **SHOULD** always be written in all capital letters and contain no space as defined in (#tag-formatting), diff --git a/transforms/ebml_schema2markdown4rfc.xsl b/transforms/ebml_schema2markdown4rfc.xsl index 49d8e116b..98449f014 100644 --- a/transforms/ebml_schema2markdown4rfc.xsl +++ b/transforms/ebml_schema2markdown4rfc.xsl @@ -58,7 +58,7 @@ : : - see implementation notes + See (#Notes)