Permalink
May 4, 2015
Jul 12, 2020
Jun 28, 2020
Jun 28, 2020
May 4, 2015
Feb 27, 2019
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Feb 17, 2019
May 4, 2015
Jul 12, 2020
Jul 12, 2020
Jun 28, 2020
Jul 12, 2020
Jul 12, 2020
Jul 12, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Mar 4, 2019
Jun 30, 2020
Jul 16, 2020
Dec 20, 2019
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Dec 20, 2019
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jul 12, 2020
Oct 21, 2019
Jun 28, 2020
Oct 21, 2019
May 8, 2019
Jun 28, 2020
Jun 30, 2020
Dec 27, 2019
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Jan 22, 2019
May 4, 2015
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Oct 21, 2019
Jun 28, 2020
Feb 17, 2019
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Feb 17, 2019
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Feb 17, 2019
Feb 17, 2019
Apr 4, 2021
May 4, 2015
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jul 17, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Jun 14, 2020
Jun 14, 2020
Jun 14, 2020
Jun 28, 2020
Jan 26, 2020
Jan 21, 2020
Jun 28, 2020
Jan 26, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Jun 30, 2020
Jul 13, 2020
Jul 13, 2020
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jul 12, 2020
Jun 30, 2020
Jun 30, 2020
Oct 24, 2019
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Jun 30, 2020
Dec 10, 2019
Jun 30, 2020
Dec 10, 2019
Jul 13, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Oct 24, 2019
Oct 24, 2019
Oct 24, 2019
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2016
Jul 7, 2016
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Jun 30, 2020
Jun 28, 2020
Dec 5, 2015
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
Nov 3, 2019
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Oct 24, 2019
Jun 30, 2020
Jun 28, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
May 27, 2019
Jun 28, 2020
May 27, 2019
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 30, 2020
May 27, 2019
Jun 28, 2020
Jun 30, 2020
May 27, 2019
Jul 13, 2020
Jun 28, 2020
Jun 30, 2020
May 27, 2019
Jul 13, 2020
Jun 28, 2020
May 27, 2019
Jun 28, 2020
Jun 28, 2020
Feb 17, 2019
Jun 28, 2020
Jun 28, 2020
Feb 17, 2019
Feb 17, 2019
Jun 30, 2020
Jun 30, 2020
Jun 30, 2020
Aug 25, 2019
Jan 5, 2020
Jun 30, 2020
Jun 14, 2020
Mar 10, 2019
Jun 30, 2020
Jun 30, 2020
Jul 12, 2020
Jun 30, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Jun 28, 2020
Feb 27, 2019
Dec 17, 2019
Sep 25, 2018
Oct 15, 2019
Jun 30, 2020
Jun 28, 2020
Newer
100644
2014 lines (1510 sloc)
82.9 KB
2
3
EBML, short for Extensible Binary Meta Language, specifies a binary format
4
aligned with octets (bytes) and inspired by the principle of XML (a framework for
5
structuring data).
6
7
The goal of this document is to define a generic, binary, space-efficient
8
format that can be used to define more complex formats using an EBML
9
Schema. EBML is used by the multimedia container, Matroska
11
use cases is beyond the scope of this document.
12
13
The definition of the EBML format recognizes the idea behind HTML and XML
14
as a good one: separate structure and semantics allowing the same structural
15
layer to be used with multiple, possibly widely differing, semantic
16
layers. Except for the EBML Header and a few Global Elements, this
17
specification does not define particular EBML format semantics; however, this
18
specification is intended to define how other EBML-based formats can be
19
defined, such as the audio/video container formats Matroska and WebM [@?WebM].
20
21
EBML uses a simple approach of building Elements upon three pieces of data (tag, length, and value), as this approach is well known, easy to parse, and allows selective data parsing. The EBML structure additionally allows for hierarchical arrangement to support complex structural formats in an efficient manner.
22
23
A typical EBML file has the following structure:
24
25
~~~
26
EBML Header (master)
27
+ DocType (string)
28
+ DocTypeVersion (unsigned integer)
29
EBML Body Root (master)
30
+ ElementA (utf-8)
31
+ Parent (master)
32
+ ElementB (integer)
33
+ Parent (master)
34
+ ElementB (integer)
35
~~~
36
39
The key words "**MUST**", "**MUST NOT**",
40
"**REQUIRED**", "**SHALL**", "**SHALL NOT**",
41
"**SHOULD**", "**SHOULD NOT**",
42
"**RECOMMENDED**", "**NOT RECOMMENDED**",
43
"**MAY**", and "**OPTIONAL**" in this document are to be interpreted as
44
described in BCP 14 [@!RFC2119] [@!RFC8174]
45
when, and only when, they appear in all capitals, as shown here.
47
This document defines specific terms in order to define the format and
48
application of `EBML`. Specific terms are defined below:
92
used to uniquely identify a defined `EBML Element` within a specific
93
`EBML Schema`.
107
`Element ID` and `Element Data Size`. The form of the `Element Data` is
108
defined by this document and the corresponding `EBML Schema` of the
109
Element's `EBML Document Type`.
116
level of the path hierarchy within an `EBML Body` and contains all other
117
`EBML Elements` of the `EBML Body`, excepting optional `Void Elements`.
132
specified element. For any specified `EBML Element` that is not at
133
`Root Level`, the `Parent Element` refers to the `Master Element`
134
in which that `EBML Element` is directly contained.
138
`Master Element`, including any of the `Child Elements` of its
139
`Child Elements`, and so on.
149
: The hierarchy of `Parent Element` where the `EBML Element`
150
is expected to be found in the `EBML Body`.
154
`VINT_DATA` bits set to zero, which indicates
155
that the `Element Data` of the `Element` is zero octets in
156
length.
160
EBML uses a system of Elements to compose an EBML Document. EBML Elements incorporate three parts: an Element ID, an Element Data Size, and Element Data. The Element Data, which is described by the Element ID, includes either binary data, one or more other EBML Elements, or both.
161
164
The Element ID and Element Data Size are both encoded as a Variable-Size
165
Integer. The Variable-Size Integer is composed of a VINT\_WIDTH, VINT\_MARKER,
167
left-pad the VINT\_DATA value with zero bits so that the whole Variable-Size
168
Integer is octet aligned. The Variable-Size Integer will be referred to as
175
and is terminated by the VINT\_MARKER, which is a single bit of value
176
`1`. The total length in bits of both VINT\_WIDTH and VINT\_MARKER is the
179
The single bit `1` starts a Variable-Size Integer with a length of
180
one octet. The sequence of bits `01` starts a Variable-Size Integer
181
with a length of two octets. `001` starts a Variable-Size Integer with
187
The VINT\_MARKER serves as a separator between the VINT\_WIDTH and VINT\_DATA. Each Variable-Size Integer **MUST** contain exactly one VINT\_MARKER. The VINT\_MARKER is one bit in length and contain a bit with a value of one. The first bit with a value of one within the Variable-Size Integer is the VINT\_MARKER.
191
The VINT\_DATA portion of the Variable-Size Integer includes all data following
192
(but not including) the VINT\_MARKER until end of the Variable-Size
193
Integer whose length is derived from the VINT\_WIDTH. The bits required for the
194
VINT\_WIDTH and the VINT\_MARKER use one out of every eight bits of the total
196
length supplies 7 bits for VINT\_DATA, a 2-octet length supplies 14 bits for
197
VINT\_DATA, and a 3-octet length supplies 21 bits for VINT\_DATA. If the number
199
VINT\_DATA **MUST** be zero-padded to the left to a size that
200
fits. The VINT\_DATA value **MUST** be expressed as a big-endian
206
Integers with lengths from 1 to 5 octets. The "Usable Bits" column refers to the
207
number of bits that can be used in the VINT\_DATA. The "Representation" column
211
212
Octet Length | Usable Bits | Representation
213
-------------|-------------|:-------------------------------------------------
214
1 | 7 | 1xxx xxxx
215
2 | 14 | 01xx xxxx xxxx xxxx
216
3 | 21 | 001x xxxx xxxx xxxx xxxx xxxx
217
4 | 28 | 0001 xxxx xxxx xxxx xxxx xxxx xxxx xxxx
218
5 | 35 | 0000 1xxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
223
date -- e.g., when its final size isn't known in advance. In
224
[@tableVariousSizes], an integer `2` (with a
225
corresponding binary value of 0b10) is shown encoded as different Variable-Size
226
Integers with lengths from one octet to four octets. All four encoded
230
Integer | Octet Length | As Represented in VINT (binary) | As Represented in VINT (hexadecimal)
231
--------|--------------|----------------------------------------:|------------------------------------:
232
2 | 1 | 1000 0010 | 0x82
233
2 | 2 | 0100 0000 0000 0010 | 0x4002
234
2 | 3 | 0010 0000 0000 0000 0000 0010 | 0x200002
235
2 | 4 | 0001 0000 0000 0000 0000 0000 0000 0010 | 0x10000002
244
is set to a value greater than four (see
245
(#ebmlmaxidlength-element)). The bits of the VINT\_DATA component
249
Element ID with binary encoding of `1011 1111` is valid, whereas an
250
Element ID with binary encoding of `0100 0000 0011 1111` stores a
262
| | 1 | 0000000 | Invalid: VINT_DATA **MUST NOT** be set to all 0
263
0 | 1 | 00000000000000 | Invalid: VINT_DATA **MUST NOT** be set to all 0
272
The range and count of possible Element IDs are determined by their
273
octet length. Examples of this are provided in
274
[@tableElementIDRanges].
276
Element ID Octet Length | Range of Valid Element IDs | Number of Valid Element IDs
277
:----------------------:|:----------------------------:|-------------:
278
1 | 0x81 - 0xFE | 126
279
2 | 0x407F - 0x7FFE | 16,256
280
3 | 0x203FFF - 0x3FFFFE | 2,080,768
281
4 | 0x101FFFFF - 0x1FFFFFFE | 268,338,304
293
the octet length of the longest Element Data Size of the EBML Document is
294
declared in the EBMLMaxSizeLength Element of the EBML Header (see
295
(#ebmlmaxsizelength-element)). Unlike the VINT\_DATA of the
296
Element ID, the VINT\_DATA component of the Element Data Size is not mandated
297
to be encoded at the shortest valid length. For example, an Element Data Size
298
with binary encoding of 1011 1111 or a binary encoding of 0100 0000 0011 1111
299
are both valid Element Data Sizes and both store a semantically equal value
300
(both 0b00000000111111 and 0b0111111, the VINT\_DATA sections of the examples,
301
represent the integer 63).
302
303
Although an Element ID with all VINT\_DATA bits set to zero is invalid, an
304
Element Data Size with all VINT\_DATA bits set to zero is allowed for EBML
306
(#ebml-element-types)). An Element Data Size with all VINT\_DATA
307
bits set to zero indicates that the Element Data is zero octets in
308
length. Such an EBML Element is referred to as an Empty Element. If an Empty
312
use the value of the Empty Element for the corresponding EBML Element Type of
313
the Element ID, 0 for numbers and an empty string for strings.
317
An Element Data Size with all VINT\_DATA bits set to one is reserved as an
318
indicator that the size of the EBML Element is unknown. The only reserved
319
value for the VINT\_DATA of Element Data Size is all bits set to one. An EBML
320
Element with an unknown Element Data Size is referred to as an Unknown-Sized
321
Element. Only a Master Element is allowed to be of unknown size, and it can
325
The use of Unknown-Sized Elements allows an EBML Element to be written and read before the size of the EBML Element is known. Unknown-Sized Elements **MUST** only be used if the Element Data Size is not known before the Element Data is written, such as in some cases of datastreaming. The end of an Unknown-Sized Element is determined by whichever comes first:
327
- Any EBML Element that is a valid Parent Element of the Unknown-Sized Element according to the EBML Schema, Global Elements excluded.
328
- Any valid EBML Element according to the EBML Schema, Global Elements
329
excluded, that is not a Descendant Element of the Unknown-Sized Element but
331
- Any EBML Element that is a valid Root Element according to the EBML Schema, Global Elements excluded.
333
- The end of the EBML Document, either when reaching the end of the file or because a new EBML Header started.
336
`\root\level1\level2\elt`. When reading a new Element ID, assuming the
337
EBML Path of that new Element is valid, here are some possible and impossible
338
ways that this new Element is ending `elt`:
342
`\root\level1\level2` | Ends the Unknown-Sized Element, as it is a new Parent Element
343
`\root\level1` | Ends the Unknown-Sized Element, as it is a new Parent Element
344
`\root` | Ends the Unknown-Sized Element, as it is a new Root Element
345
`\root2` | Ends the Unknown-Sized Element, as it is a new Root Element
346
`\root\level1\level2\other` | Ends the Unknown-Sized Element, as they share the same parent
347
`\root\level1\level2\elt` | Ends the Unknown-Sized Element, as they share the same parent
348
`\root\level1\level2\elt\inside` | Doesn't end the Unknown-Sized Element; it's a child of `elt`
349
`\root\level1\level2\elt\<global>` | Global Element is valid; it's a child of `elt`
350
`\root\level1\level2\<global>` | Global Element cannot be interpreted with this path; while parsing `elt`, a Global Element can only be a child of `elt`
355
For Element Data Sizes encoded at octet lengths from one to eight,
356
[@tableVintRangePerLength] depicts the range of possible values
357
that can be encoded as an Element Data Size. An Element Data Size with an
359
72,057,594,037,927,934 octets (or about 72 petabytes). The maximum possible
360
value that can be stored as Element Data Size is referred to as VINTMAX.
364
1 | 0 to 2^7^ - 2
365
2 | 0 to 2^14^ - 2
366
3 | 0 to 2^21^ - 2
367
4 | 0 to 2^28^ - 2
368
5 | 0 to 2^35^ - 2
369
6 | 0 to 2^42^ - 2
370
7 | 0 to 2^49^ - 2
371
8 | 0 to 2^56^ - 2
378
value. [@tableVintReservation] clarifies this rule by
379
showing a valid and invalid expression of an Element Data Size with a
380
VINT\_DATA of 127 (which is equal to 2^1\*7^-1) and 16,383 (which is equal to
381
2^2\*7^-1).
383
VINT_WIDTH | VINT_MARKER | VINT_DATA | Element Data Size Status
384
-----------:|-------------:|----------------------:|---------------------------
385
| | 1 | 1111111 | Reserved (meaning Unknown)
386
0 | 1 | 00000001111111 | Valid (meaning 127 octets)
387
00 | 1 | 000000000000001111111 | Valid (meaning 127 octets)
388
0 | 1 | 11111111111111 | Reserved (meaning Unknown)
389
00 | 1 | 000000011111111111111 | Valid (16,383 octets)
392
397
following EBML Element Types for each EBML Element. An EBML Element Type
398
defines a concept of storing data within an EBML Element that describes such
399
characteristics as length, endianness, and definition.
406
A Signed Integer Element **MUST** declare a length from zero to eight octets. If the EBML Element is not defined to have a default value, then a Signed Integer Element with a zero-octet length represents an integer value of zero.
410
zero. Signed Integers are stored with two's complement notation with the
411
leftmost bit being the sign bit. Because EBML limits Signed Integers to 8
417
An Unsigned Integer Element **MUST** declare a length from zero to eight octets. If the EBML Element is not defined to have a default value, then an Unsigned Integer Element with a zero-octet length represents an integer value of zero.
428
is not defined to have a default value, then a Float Element with a zero-octet
429
length represents a numerical value of zero.
436
A String Element **MUST** declare a length in octets from zero to VINTMAX. If the EBML Element is not defined to have a default value, then a String Element with a zero-octet length represents an empty string.
438
A String Element **MUST** either be empty (zero-length) or contain printable ASCII characters [@!RFC0020] in the range of 0x20 to 0x7E, with an exception made for termination (see (#terminating-elements)).
442
A UTF-8 Element **MUST** declare a length in octets from zero to VINTMAX. If the EBML Element is not defined to have a default value, then a UTF-8 Element with a zero-octet length represents an empty string.
444
A UTF-8 Element contains only a valid Unicode string as defined in [@!RFC3629], with an exception made for termination (see (#terminating-elements)).
448
A Date Element **MUST** declare a length of either zero octets or eight octets. If the EBML Element is not defined to have a default value, then a Date Element with a zero-octet length represents a timestamp of 2001-01-01T00:00:00.000000000 UTC [@!RFC3339].
450
The Date Element stores an integer in the same format as the Signed Integer Element that expresses a point in time referenced in nanoseconds from the precise beginning of the third millennium of the Gregorian Calendar in Coordinated Universal Time (also known as 2001-01-01T00:00:00.000000000 UTC). This provides a possible expression of time from 1708-09-11T00:12:44.854775808 UTC to 2293-04-11T11:47:16.854775807 UTC.
454
A Master Element **MUST** declare a length in octets from zero to VINTMAX or be of unknown length. See (#element-data-size) for rules that apply to elements of unknown length.
456
The Master Element contains zero or more other elements. EBML Elements contained within a Master Element **MUST** have the EBMLParentPath of their Element Path equal to the EBMLFullPath of the Master Element Element Path (see (#path)). Element Data stored within Master Elements **SHOULD** only consist of EBML Elements and **SHOULD NOT** contain any data that is not part of an EBML Element. The EBML Schema identifies what Element IDs are valid within the Master Elements for that version of the EBML Document Type. Any data contained within a Master Element that is not part of a Child Element **MUST** be ignored.
466
An EBML Document is composed of only two components, an EBML Header and an EBML Body. An EBML Document **MUST** start with an EBML Header that declares significant characteristics of the entire EBML Body. An EBML Document consists of EBML Elements and **MUST NOT** contain any data that is not part of an EBML Element.
470
The EBML Header is a declaration that provides processing instructions and identification of the EBML Body. The EBML Header of an EBML Document is analogous to the XML Declaration of an XML Document.
472
The EBML Header documents the EBML Schema (also known as the EBML DocType)
473
that is used to semantically interpret the structure and meaning of the EBML
475
and the EBML Schema that were used to write the EBML Document and the versions
476
required to read the EBML Document.
492
All data of an EBML Document following the EBML Header is the EBML Body. The end of the EBML Body, as well as the end of the EBML Document that contains the EBML Body, is reached at whichever comes first: the beginning of a new EBML Header at the Root Level or the end of the file. This document defines precisely which EBML Elements are to be used within the EBML Header but does not name or define which EBML Elements are to be used within the EBML Body. The definition of which EBML Elements are to be used within the EBML Body is defined by an EBML Schema.
496
length allowed for any Element Data Size is set by the EBMLMaxSizeLength
497
Element of the EBML Header.
501
An EBML Stream is a file that consists of one or more EBML Documents that are concatenated together. An occurrence of an EBML Header at the Root Level marks the beginning of an EBML Document.
505
An EBML Document handles 2 different versions: the version of the EBML Header and the version of the EBML Body. Both versions are meant to be backward compatible.
509
The version of the EBML Header is found in EBMLVersion. An EBML parser can read an EBML Header if it can read either the EBMLVersion version or a version equal or higher than the one found in EBMLReadVersion.
513
The version of the EBML Body is found in DocTypeVersion. A parser for the particular DocType format can read the EBML Document if it can read either the DocTypeVersion version of that format or a version equal or higher than the one found in DocTypeReadVersion.
516
521
arrangement, and usage of EBML Elements that compose a specific EBML Document
522
Type. The relationship of an EBML Schema to an EBML Document is analogous to
523
the relationship of an XML Schema [@!XML-SCHEMA] to an XML
524
Document [@!XML]. An EBML Schema
532
An EBML Schema **MUST** declare exactly one EBML Element at Root Level (referred to as the Root Element) that occurs exactly once within an EBML Document. The Void Element **MAY** also occur at Root Level but is not a Root Element (see (#void-element)).
543
(see (#ebml-header-elements)) by adding or constraining
544
that Element's `range` attribute. For example, an EBML Schema
545
**MAY** constrain the EBMLMaxSizeLength to a maximum value of
546
`8` or **MAY** constrain the EBMLVersion to only support a
548
then it is not required to document that Element within the EBML Schema. If an
549
EBML Schema constrains the range of an EBML Header Element, then that Element
568
### `<EBMLSchema>` Namespace
569
570
The namespace URI for elements of the EBML Schema is a URN as defined by
584
The docType lists the official name of the EBML Document Type that is
585
defined by the EBML Schema; for example,
586
`<EBMLSchema docType="matroska">`.
597
docType documented by the EBML Schema. Unlike XML Schemas, an EBML Schema
598
documents all versions of a docType's definition rather than using separate
599
EBML Schemas for each version of a docType. EBML Elements may be introduced
620
Each `<element>` defines one EBML Element through the use of
621
several attributes that are defined in
622
(#element-attributes). EBML Schemas **MAY** contain
623
additional attributes to extend the semantics but **MUST NOT**
624
conflict with the definitions of the `<element>` attributes
625
defined within this document.
627
The `<element>` nodes contain a description of the meaning and use of the EBML Element stored within one or more `<documentation>` subelements, followed by optional `<implementation_note>` subelements, followed by zero or one `<restriction>` subelement, followed by optional `<extension>` subelements. All `<element>` nodes **MUST** be subelements of the `<EBMLSchema>`.
668
EBMLParents = 0*IntermediatePathAtom EBMLLastParent
669
IntermediatePathAtom = EBMLPathAtom / GlobalPlaceholder
670
EBMLLastParent = EBMLPathAtom / GlobalPlaceholder
672
EBMLPathAtom = [IsRecursive] EBMLAtomName PathDelimiter
673
EBMLElement = [IsRecursive] EBMLAtomName
680
GlobalPlaceholder = "(" GlobalParentOccurrence "\)"
681
GlobalParentOccurrence = [PathMinOccurrence] "-" [PathMaxOccurrence]
682
PathMinOccurrence = 1*DIGIT ; no upper limit
683
PathMaxOccurrence = 1*DIGIT ; no upper limit
688
The EBMLAtomName of the EBMLElement part **MUST** be equal to the `@name` attribute of the EBML Schema.
689
If the EBMLElement part contains an IsRecursive part, the EBML Element can occur within itself recursively (see (#recursive)).
691
The starting PathDelimiter of EBMLParentPath corresponds to the root of the EBML Document.
693
The `@path` value **MUST** be unique within the EBML Schema. The `@id` value corresponding to this `@path` **MUST NOT** be defined for use within another EBML Element with the same EBMLParentPath as this `@path`.
695
A path with a GlobalPlaceholder as the EBMLLastParent defines a Global Element; see (#global-elements).
696
If the element has no EBMLLastParent part, or the EBMLLastParent part is not a
697
GlobalPlaceholder, then the Element is not a Global Element.
701
PathMinOccurrence represents the minimum number of EBMLPathAtoms required to
702
replace the GlobalPlaceholder. PathMaxOccurrence represents the maximum number
709
PathMaxOccurrence **MUST NOT** have the value 0, as it would mean
710
no EBMLPathAtom can replace the GlobalPlaceholder, and the EBMLFullPath would
716
`\a\x\global` corresponds to an EBMLPathAtom occurrence of 1. The
717
Element `\a\x\y\global` corresponds to an EBMLPathAtom occurrence of 2,
722
least one EBMLPathAtom between the `\a\` part and `global`.
723
So the `global` EBML Element cannot be found inside the `\a`
727
Element, because the resulting path, `\a\b\global`, has one EBMLPathAtom
728
between the `\a\` and `global`. Alternatively, it can be found
729
inside the `\a\b\c` EBML Element (two EBMLPathAtom), or inside the
730
`\a\b\c\d` EBML Element (three EBMLPathAtom), etc.
731
734
So the `global` EBML Element can be found inside either the `\a`
735
EBML Element (0 EBMLPathAtom replacing GlobalPlaceholder) or the
737
But it cannot be found inside the `\a\b\c` EBML Element, because the
738
resulting path, `\a\b\c\global`, has two EBMLPathAtom between
747
The Element ID is encoded as a Variable-Size Integer. It is read and stored in big-endian
749
hexadecimal notation prefixed by a 0x. To reduce the risk of false positives while parsing EBML Streams, the
757
The Element ID of any Element found within an EBML Document **MUST** only match a single `@path` value of its corresponding EBML Schema, but a separate instance of that Element ID value defined by the EBML Schema **MAY** occur within a different `@path`. If more than one Element is defined to use the same `@id` value, then the `@path` values of those Elements **MUST NOT** share the same EBMLParentPath. Elements **MUST NOT** be defined to use the same `@id` value if one of their common Parent Elements could be an Unknown-Sized Element.
769
Each instance of the Parent Element **MUST** contain at least this many instances of this EBML Element.
781
The `minOccurs` attribute is **OPTIONAL**. If the `minOccurs`
782
attribute is not present, then that EBML Element has a `minOccurs` value of
785
The semantic meaning of `minOccurs` within an EBML Schema is analogous to the meaning of `minOccurs` within an XML Schema.
806
the EBML Document, depending on whether or not the EBMLParentPath of the EBML Element
807
is empty.
809
The semantic meaning of `maxOccurs` within an EBML Schema is analogous to the
810
meaning of `maxOccurs` within an XML Schema; when it is not present, it's
824
The `range` attribute is **OPTIONAL**. If the
825
`range` attribute is
826
not present, then any value legal for the `type` attribute is valid.
833
Element and optionally an upper boundary value combined with a lower
834
boundary. The range expression may contain whitespace (using the ASCII 0x20
845
`>=` sign is used for an inclusive lower boundary. For example,
846
`>3` means the Element value **MUST** be greater than 3,
847
and `>=0x1p+0` means the Element value **MUST** be
851
The `<` sign is used for an exclusive upper boundary, and the
852
`<=` sign is used for an inclusive upper boundary. For example,
853
`<-2` means the Element value **MUST** be less than -2,
854
and `<=10` means the Element value **MUST** be less than
858
closed boundary. The lower boundary comes first, followed by the upper
859
boundary, separated by a comma. For example, `>3,<= 20` means the
865
the first value and **MUST** be less than or equal to the
866
second value. For example, `1-10` is equivalent to
867
`>=1,<=10`. If the upper boundary is negative, the `range` attribute
868
**MUST** only use the latter form.
880
nonnegative integer or a range (see
881
(#expression-of-range)) that consists of only nonnegative
894
If an Element is mandatory (has a `minOccurs` value greater than zero) but not written within its Parent Element or stored as an Empty Element, then the EBML Reader of the EBML Document **MUST** semantically interpret the EBML Element as present with this specified default value for the EBML Element.
895
An unwritten mandatory Element with a declared default value is semantically equivalent to that Element if written with the default value stored as the Element Data.
897
EBML Elements with a `minOccurs` value greater than 1 **MUST NOT** declare a default value.
907
`integer` (signed integer), `uinteger` (unsigned integer),
908
`float`, `string`, `date`, `utf-8`,
909
`master`, or `binary`. The content of each type is defined
922
`unknownsizeallowed` to true. An EBML Element that is defined with an
923
`unknownsizeallowed` attribute set to 1 **MUST** also have the
924
`unknownsizeallowed` attribute of its Parent Element set to 1.
926
An EBML Element with the `unknownsizeallowed` attribute set to 1
927
**MUST NOT** have its `recursive` attribute set to 1.
929
The `unknownsizeallowed` attribute is **OPTIONAL**. If the
930
`unknownsizeallowed` attribute is not used, then that EBML Element is not
949
An EBML Element with the `recursive` attribute set to 1 **MUST NOT**
950
have its `unknownsizeallowed` attribute set to 1.
961
This attribute is a boolean to express whether or not an EBML Element is defined as an
962
Identically Recurring Element; see
997
elements are `/EBMLSchema/element/documentation` and `/EBMLSchema/element/restriction/enum/documentation`.
1000
about EBML Elements or enumeration values. Within the `<documentation>` element, the
1028
| definition | A "definition" is recommended for every defined EBML Element. This documentation explains the semantic meaning of the EBML Element.
1029
| rationale | An explanation about the reason or catalyst for the definition of the Element.
1030
| usage notes | Recommended practices or guidelines for both reading, writing, or interpreting the Element.
1031
| references | Informational references to support the contextualization and understanding of the value of the Element.
1033
values for the `purpose` attribute of the documentation Element{#tablePurposeDefinitions}
1040
element is `/EBMLSchema/element/implementation_note`.
1041
1042
In some cases within an EBML Document Type, the attributes of the
1043
`<element>` element are not sufficient to clearly communicate how
1044
the defined EBML Element is intended to be implemented.
1045
For instance, one EBML Element might only be mandatory if another EBML Element
1046
is present. As another example, the default value of an EBML Element might
1047
be derived from a related Element's content. In these cases where the Element's
1048
definition is conditional or advanced implementation notes are needed, one or many
1049
`<implementation_note>` elements can be used to store that
1050
information.
1065
following values (corresponding to that attribute of the parent
1066
`<element>`): `minOccurs`, `maxOccurs`,
1067
`range`, `length`, `default`, `minver`, or
1069
supersede the parent `<element>`'s attribute that is named in the
1070
`note_attribute` attribute.
1071
An `<element>` **SHALL NOT** have more than one `<implementation_note>` of the same `note_attribute`.
1079
documents a list of items that are described with an optional cost. The
1080
Currency Element uses an `<implementation_note>` to say that the
1092
type="master">
1093
<documentation lang="en" purpose="definition">
1094
An item.
1095
</documentation>
1096
</element>
1099
<documentation lang="en" purpose="definition">
1100
The cost of the item, if any.
1101
</documentation>
1102
</element>
1104
type="string" maxOccurs="1">
1105
<documentation lang="en" purpose="definition">
1106
The currency of the item's cost.
1107
</documentation>
1108
<implementation_note note_attribute="minOccurs">
1109
Currency MUST be set (minOccurs=1) if the associated Item stores
1181
project or authority associated with the contents of the
1182
`<extension>` element.
1199
and semantics. Identically Recurring Elements are permitted to be stored
1200
multiple times within the same Parent Element in order to increase data
1206
especially recommended when EBML is used for long-term storage or
1207
transmission. If a Parent Element contains more than one copy of an
1213
then the first instance of the Identically Recurring Element should be used
1214
for interpretation.
1222
Constants). [@tableFloatExamples] provides examples of
1223
expressions of float ranges.
1225
| as decimal | as Hexadecimal Floating-Point Constants |
1226
|:------------------|:----------------------------------------|
1228
| 0.0-1.0 | `0x0p+1-0x1p+0` |
1229
| 1.0-256.0 | `0x1p+0-0x1p+8` |
1230
| 0.857421875 | `0x1.b7p-1` |
1231
| -1.0--0.857421875 | `-0x1p+0--0x1.b7p-1` |
1237
permitted by the range. Hexadecimal Floating-Point Constants also use a -
1238
(hyphen) when indicating a negative binary power. Within a float range, when a
1239
- (hyphen) is immediately preceded by a letter p, then the - (hyphen) is a
1249
that EBML Element is not required to be present within the EBML Document if
1250
its Parent Element is present. In this case, the default value of the
1252
although the EBML Element is not present within its Parent Element.
1253
1254
If a Mandatory EBML Element has no default value declared by an EBML Schema
1255
and its Parent Element is present, then the EBML Element **MUST**
1256
be present, as well. If a Mandatory EBML Element has a default value declared
1257
by an EBML Schema, and its Parent Element is present, and the value of the EBML
1258
Element is NOT equal to the declared default value, then the EBML Element
1261
[@tableVintRequirements] clarifies whether a Mandatory
1262
EBML Element **MUST** be written, according to whether the default value
1263
is declared, the value of the EBML Element is equal to the declared default
1264
value, and/or the Parent Element is used.
1266
| Is the default value declared? | Is the value equal to default? | Is the Parent Element present? | Then is storing the EBML Element **REQUIRED**? |
1267
|:-----------------:|:-----------------------:|:--------------------:|:------------------------------------------:|
1268
| Yes | Yes | Yes | No |
1269
| Yes | Yes | No | No |
1270
| Yes | No | Yes | Yes |
1271
| Yes | No | No | No |
1272
| No | n/a | Yes | Yes |
1273
| No | n/a | No | No |
1364
Document. The EBMLReadVersion Element **MUST** be less than or equal to EBMLVersion.
1394
of the Element IDs to be found within the EBML Body. An EBMLMaxIDLength Element value of four
1425
octets of the expressions of all Element Data Sizes to be found within the EBML Body. The
1426
EBMLMaxSizeLength Element documents an upper bound for the `length` of
1427
all Element Data Size expressions within the EBML Body and not an upper bound
1428
for the `value` of all Element Data Size expressions
1429
within the EBML Body. EBML Elements that have an Element Data Size expression that is larger in octets
1538
tuple it's attached to. An EBML Reader **MAY** know these extra Elements and how
1539
to use them. A DocTypeExtension **MAY** be used to iterate between
1541
DocTypeVersion. Reading one DocTypeExtension version of a
1542
DocType+DocTypeVersion tuple doesn't imply one should be able to read upper
1543
versions of this DocTypeExtension.
1570
DocTypeExtensions of the same DocType+DocTypeVersion tuple. A DocTypeExtensionName value
1599
**MAY** contain completely different sets of extra Elements. An
1600
EBML Reader **MAY** support multiple versions
1601
of the same tuple, only one version of the tuple, or not support the tuple at all.
1605
EBML allows some special Elements to be found within more than one parent
1606
in an EBML Document or optionally at the Root Level of an EBML Body. These
1610
defines. These extra elements apply only to the EBML Body, not the EBML
1611
Header.
1613
Global Elements are EBML Elements whose EBMLLastParent part of the path has
1614
a GlobalPlaceholder. Because it is the last Parent part of the path, a Global
1615
Element might also have EBMLParentPath parts in its path. In this case, the
1616
Global Element can only be found within this EBMLParentPath path -- i.e., it's
1619
A Global Element can be found in many Parent Elements, allowing the same number of occurrences in each Parent where this Element is found.
1646
the Element Data of the Parent Element as stored except for the CRC-32 Element
1647
itself. When the CRC-32 Element is present, the CRC-32 Element
1654
**MUST** be computed on a little-endian bytestream and
1655
**MUST** use little-endian storage.
1688
In the following XML representation of a simple, hypothetical EBML
1689
fragment, a Master Element called CONTACT contains two Child Elements, NAME
1690
and ADDRESS. In this example, some data within the NAME Element had been
1692
Ancestor Element with a CRC-32 would therefore also no longer
1693
validate. However, even though the CONTACT Element has a CRC-32 that does not
1694
validate (because of the changed data within the NAME Element), the CRC-32 of
1697
1698
```xml
1699
<CONTACT>
1700
<CRC-32>c119a69b</CRC-32><!-- does not validate -->
1701
<NAME>
1702
<CRC-32>1f59ee2b</CRC-32><!-- does not validate -->
1703
<FIRST-NAME>invalid data</FIRST-NAME>
1704
<LAST-NAME>invalid data</LAST-NAME>
1705
</NAME>
1706
<ADDRESS>
1707
<CRC-32>df941cc9</CRC-32><!-- validates -->
1708
<STREET>valid data</STREET>
1709
<CITY>valid data</CITY>
1710
</ADDRESS>
1711
</CONTACT>
1712
```
1713
1714
1722
permitted according to the `maxOccurs` attribute of the definition of that
1723
Element, then all instances of that Element after the first `maxOccurs`
1729
Null Octets, which are octets with all bits set to zero, **MAY** follow the value of a String Element or UTF-8 Element to serve as a terminator.
1730
An EBML Writer **MAY** terminate a String Element or UTF-8 Element
1732
lesser length while maintaining the same Element Data Size; this can prevent
1733
the need to rewrite large portions of an EBML Document. Otherwise, the use of
1734
Null Octets within a String Element or UTF-8 Element is **NOT RECOMMENDED**.
1735
The Element Data of a UTF-8 Element **MUST**
1736
be a valid UTF-8 string up to whichever comes first: the end of the Element or
1737
the first occurring Null octet. Within the Element Data of a String or UTF-8 Element,
1738
any Null octet itself and any following data within that Element
1740
value terminated by one or more Null Octets are semantically equal.
1741
1742
[@tableNullOctetSemantics] shows examples of semantics
1743
and validation for the use of Null Octets. Values to represent Stored Values
1747
:-------------------|:-------------------
1748
0x65 0x62 0x6D 0x6C | 0x65 0x62 0x6D 0x6C
1749
0x65 0x62 0x00 0x6C | 0x65 0x62
1750
0x65 0x62 0x00 0x00 | 0x65 0x62
1751
0x65 0x62 | 0x65 0x62
1759
the Element Data of a written EBML Element with minimal disruption to the rest
1760
of the EBML Document.
1763
1764
There are three methods to reduce the size of Element Data of a written EBML Element.
1765
1766
### Adding a Void Element
1767
1768
When an EBML Element is changed to reduce its total length by more than one octet, an EBML Writer **SHOULD** fill the freed space with a Void Element.
1772
The same value for Element Data Size **MAY** be written in various lengths, so for minor reductions of the Element Data, the Element Size **MAY** be written to a longer octet length to fill the freed space.
1774
For example, the first row of
1775
[@tableShortenVintOneOctet] depicts a String Element that stores
1776
an Element ID (3 octets), Element Data Size (1 octet), and Element Data (4
1778
if the current length of the Element Data Size is less than its maximum
1779
permitted length, then the Element Data Size of that Element
1780
**MAY** be rewritten to increase its length by one octet. Thus,
1781
before and after the change, the EBML Element maintains the same length of 8
1782
octets, and data around the Element does not need to be moved.
1783
1784
| Status | Element ID | Element Data Size | Element Data |
1785
|-------------|------------|-------------------|--------------------|
1786
| Before edit | 0x3B4040 | 0x84 | 0x65626D6C |
1787
| After edit | 0x3B4040 | 0x4003 | 0x6D6B76 |
1798
shorter, shorten the Element Data by one octet, and follow that Element with a
1799
Void Element. For example,
1800
[@tableShortenVintMoreThanOneOctet] depicts a String Element
1801
that stores an Element ID (3 octets), Element Data Size (2 octets, but could
1802
be rewritten in one octet), and Element Data (3 octets). If the Element Data
1803
is to be rewritten to a two-octet length, then another octet can be taken from
1804
Element Data Size so that there is enough space to add a two-octet Void
1806
1807
Status | Element ID | Element Data Size | Element Data | Void Element
1808
-------|------------|-------------------|--------------|-------------
1809
Before | 0x3B4040 | 0x4003 | 0x6D6B76 |
1810
After | 0x3B4040 | 0x82 | 0x6869 | 0xEC80
1812
VINT to reduce VINT_DATA length by more than one octet{#tableShortenVintMoreThanOneOctet}
1817
reduced by adding Null Octets to terminate the Element Data (see
1818
(#terminating-elements)).
1822
Element Data Size includes any Null Octets used to terminate Element Data and therefore
1824
1825
| Status | Element ID | Element Data Size | Element Data |
1826
|-------------|------------|-------------------|--------------------|
1827
| Before edit | 0x3B4040 | 0x84 | 0x65626D6C |
1828
| After edit | 0x3B4040 | 0x84 | 0x6D6B7600 |
1830
with a Null Octet when reducing VINT length during an edit{#tableExampleNullPadding}
1834
**SHOULD** be used. For reduction by more than one octet, the
1835
method for Adding a Void Element **SHOULD** be used.
1836
1837
## Considerations when Updating Elements with Cyclic Redundancy Check (CRC)
1838
1847
Elements of an EBML format **SHOULD** be designed with backward and forward compatibility in mind.
1851
Backward compatibility of new EBML Elements can be achieved by using default values for mandatory elements. The default value **MUST** represent the state that was assumed for previous versions of the EBML Schema, without this new EBML Element. If such a state doesn't make sense for previous versions, then the new EBML Element **SHOULD NOT** be mandatory.
1867
EBML itself does not offer any kind of security and does not provide confidentiality. EBML does not provide any kind of authorization. EBML only offers marginally useful and effective data integrity options, such as CRC elements.
1869
Even if the semantic layer offers any kind of encryption, EBML itself could
1870
leak information at both the semantic layer (as declared via the DocType
1871
Element) and within the EBML structure (the presence of EBML Elements can be
1875
An EBML Document that has the following issues may still be handled by the
1876
EBML Reader and the data accepted as such, depending on how strict the EBML
1877
Reader wants to be:
1879
- Invalid Element IDs that are longer than the limit stated in the EBMLMaxIDLength Element of the EBML Header.
1880
- Invalid Element IDs that are not encoded in the shortest-possible way.
1881
- Invalid Element Data Size values that are longer than the limit stated in the EBMLMaxSizeLength Element of the EBML Header.
1890
An EBML Reader may discard some or all data if the following errors are found in the EBML Document:
1892
- Invalid Element Data Size values (e.g., extending the length of the EBML Element beyond the scope of the Parent Element, possibly triggering access-out-of-bounds issues).
1893
- Very high lengths in order to force out-of-memory situations resulting in a denial of service, access-out-of-bounds issues, etc.
1894
- Missing EBML Elements that are mandatory in a Master Element and have no declared default value, making the semantic invalid at that Master Element level.
1895
- Usage of invalid UTF-8 encoding in EBML Elements of UTF-8 type (e.g., in order to trigger access-out-of-bounds or buffer-overflow issues).
1896
- Usage of invalid data in EBML Elements with a date type, triggering bogus date accesses.
1897
- The CRC-32 Element (see (#crc-32-element)) of a Master Element doesn't match the rest of the content of that Master Element.
1901
- The semantic equivalence of the same string stored in a String Element or UTF-8 Element with and without zero-bit padding, making comparison at the semantic level invalid.
1902
- The semantic equivalence of VINT\_DATA within Element Data Size with two different lengths due to left-padding zero bits, making comparison at the semantic level invalid.
1903
- Data contained within a Master Element that is not itself part of a Child Element, which can trigger incorrect parsing behavior in EBML Readers.
1904
- Extraneous copies of Identically Recurring Element, making parsing unnecessarily slow to the point of not being usable.
1905
- Copies of Identically Recurring Element within a Parent Element that contain invalid CRC-32 Elements. EBML Readers not checking the CRC-32 might use the version of the element with mismatching CRC-32s.
1906
- Use of Void Elements that could be used to hide content or create bogus resynchronization points seen by some EBML Readers and not others.
1912
This document creates a new IANA registry called the
1913
"EBML Element IDs" registry.
1915
Element IDs are described in (#element-id). Element
1916
IDs are encoded using the VINT mechanism described in
1922
in the EBML Header, thus including Global Elements. Elements only
1923
found in the EBML Body have their own set of independent Element IDs
1928
to be used for commonly repeated elements. Element IDs are to be
1929
allocated within this range according to the "RFC Required"
1930
policy [@!RFC8126].
1938
0x7FFE. Element IDs are to be allocated within this range according to
1939
the "Specification Required" policy
1940
[@!RFC8126].
1947
Three-octet Element IDs **MUST** be between 0x203FFF and 0x3FFFFE. Element IDs are to be allocated within this range according to the "First Come First Served" policy [@!RFC8126].
1952
0x400000 to 0xFFFFFF are not valid for use as an Element ID.
1953
1954
Four-octet Element IDs **MUST** be between 0x101FFFFF
1955
and 0x1FFFFFFE. Four-octet Element IDs are somewhat special in that
1956
they are useful for resynchronizing to major structures in the event
1958
into two categories. Four-octet Element IDs whose lower three octets
1959
(as encoded) would make printable 7-bit ASCII values (0x20 to 0x7E,
1964
1965
To be clear about the above category: four-octet Element IDs always start
1966
with hex 0x10 to 0x1F, and that octet may be chosen so that the entire VINT
1967
has some desirable property, such as a specific CRC. The other three octets,
1968
when ALL having values between 0x20 (32, ASCII Space) and 0x7E (126, ASCII
1969
"~"), fall into this category.
1971
Other four-octet Element IDs may be allocated by the "First Come First Served" policy.
1978
Five-octet Element IDs (values from 0x080FFFFFFF to 0x0FFFFFFFFE) are RESERVED according to the "Experimental Use" policy [@!RFC8126]: they may be used by anyone at any time, but there is no coordination.
1983
----------:|:------------------------|:-------------------------------------------
1984
0x1A45DFA3 | EBML | Described in (#ebml-element)
1985
0x4286 | EBMLVersion | Described in (#ebmlversion-element)
1986
0x42F7 | EBMLReadVersion | Described in (#ebmlreadversion-element)
1987
0x42F2 | EBMLMaxIDLength | Described in (#ebmlmaxidlength-element)
1988
0x42F3 | EBMLMaxSizeLength | Described in (#ebmlmaxsizelength-element)
1989
0x4282 | DocType | Described in (#doctype-element)
1990
0x4287 | DocTypeVersion | Described in (#doctypeversion-element)
1991
0x4285 | DocTypeReadVersion | Described in (#doctypereadversion-element)
1992
0x4281 | DocTypeExtension | Described in (#doctypeextension-element)
1993
0x4283 | DocTypeExtensionName | Described in (#doctypeextensionname-element)
1994
0x4284 | DocTypeExtensionVersion | Described in (#doctypeextensionversion-element)
1995
0xBF | CRC-32 | Described in (#crc-32-element)
1996
0xEC | Void | Described in (#void-element)
2003
To register a new DocType in this registry, one needs a DocType name, a Description of the DocType, a Change Controller (IESG or email of registrant), and an optional Reference to a document describing the DocType.
2005
DocType values are described in (#doctype). DocTypes
2006
are ASCII strings, defined in (#string-element), which
2007
label the official name of the EBML Document Type. The strings may be
2008
allocated according to the "First Come First Served" policy.