MKV EBML encoding

Matroska is built on EBML, the Extensible Binary Meta Language, defined by RFC 8794. A file is a tree of elements, each an ID, a data size and the data. The Matroska layer is RFC 9559.

Variable-size integers

IDs and sizes are VINTs. The number of leading zero bits in the first byte, plus one, gives the length in bytes; the first set bit is the marker; the remaining bits are the value, big-endian.

Length	First byte	Value bits
1	`1xxxxxxx`	7
2	`01xxxxxx`	14
3	`001xxxxx`	21
4	`0001xxxx`	28
5	`00001xxx`	35
6 to 8	one more leading zero each	42, 49, 56

An Element ID keeps its marker bit as part of the ID, must use the shortest encoding, and may not have all value bits 0 or all 1. Matroska IDs are 1 to 4 bytes, as EBMLMaxIDLength says. An Element Data Size may use a longer encoding than needed, so a writer can overwrite it later. Its maximum is 2⁵⁶ − 2. All value bits 0 means an empty element, and all value bits 1 means the size is unknown, which only certain master elements allow (in Matroska, Segment and Cluster).

Data types

Type	Length	Value
Signed integer	0 to 8 bytes	Two’s complement, big-endian.
Unsigned integer	0 to 8 bytes	Big-endian.
Float	0, 4 or 8 bytes	IEEE 754, big-endian.
String	0 or more	Printable ASCII, `20` to `7E`.
UTF-8	0 or more	Valid Unicode text.
Date	0 or 8 bytes	Signed nanoseconds since 2001-01-01T00:00:00 UTC. Zero length means that moment.
Master	0 or more, or unknown	Other elements.
Binary	0 or more	Bytes interpreted by the element’s definition.

EBML header

The first element of the file. For Matroska, DocType is matroska and EBMLMaxIDLength is 4. DocTypeVersion and DocTypeReadVersion carry the Matroska version, 1 to 4; only version 4 is maintained.

ID	Name	Type	Meaning
`1A45DFA3`	EBML	Master	The header.
`4286`	EBMLVersion	Unsigned	EBML version used to create the file.
`42F7`	EBMLReadVersion	Unsigned	Minimum EBML version needed to read it.
`42F2`	EBMLMaxIDLength	Unsigned	Longest ID in bytes.
`42F3`	EBMLMaxSizeLength	Unsigned	Longest data size field in bytes.
`4282`	DocType	String	`matroska` (or `webm`).
`4287`	DocTypeVersion	Unsigned	Version of the document type used to create the file.
`4285`	DocTypeReadVersion	Unsigned	Minimum version needed to read it.
`4281`	DocTypeExtension	Master	Names an extension to the document type.
`4283`	DocTypeExtensionName	String	The extension’s name.
`4284`	DocTypeExtensionVersion	Unsigned	The extension’s version.

Global elements

These may appear anywhere inside a master element.

ID	Name	Type	Meaning
`BF`	CRC-32	Binary	4 bytes, the IEEE CRC-32 of the rest of the parent, stored little-endian, initial value `FFFFFFFF`.
`EC`	Void	Binary	Padding that readers discard.

Worked example

The bytes 1A 45 DF A3 9F start a file: the ID 1A45DFA3 (first byte 00011010, four bytes long), then the size byte 9F, which is 10011111: one byte long with the value 31.

.MKV File Format – EBML encoding

Variable-size integers

Data types

EBML header

Global elements

Worked example