Matroska Media Container Format Specification

ChapterTranslate and TrackTranslate elements map Matroska SegmentUUIDs and track IDs to the internal identifiers used by Chapter Codecs (e.g., DVD/Blu-ray menu systems), enabling remuxing without modifying the chapter codec payload.

ReferenceBlock uses relative timestamps rather than a simple P-frame/B-frame flag because this allows arbitrary inter-frame reference graphs; multiple ReferenceBlock elements in one BlockGroup express dependencies on any previously decoded frames.

RFC 8794 erroneously reserved EBML ID 0x80, which was already in use by deployed Matroska implementations. RFC 9559 updates RFC 8794 to un-reserve 0x80, expanding valid one-octet EBML Element IDs from 0x81–0xFE to 0x80–0xFE (127 values instead of 126).

registry

OldStereoMode (EBML ID 0x53B9, maxver=2) was an incorrect stereo-mode field written by libmatroska up to version 0.9.0 and MUST NOT be used in new files. Readers may encounter it in legacy content.

The legacy Language element uses a 3-character ISO 639-2 bibliographic code and MUST be ignored when the LanguageBCP47 element (RFC 5646 tag) is present in the same TrackEntry. Implementations should prefer LanguageBCP47 (minver=4) for new content.

A Matroska file MUST be composed of at least one EBML Document using the Matroska Document Type. Each EBML Document MUST start with an EBML Header and MUST be followed by the Segment Root Element.

Every Cluster element MUST contain exactly one Timestamp element, and that Timestamp MUST be stored once per Cluster. The Timestamp SHOULD be the first child of the Cluster it belongs to, or the second if that Cluster begins with a CRC-32 element.

In a Hard-Linked Segment, either PrevUUID or NextUUID MUST be present in Info. PrevUUID and NextUUID MUST NOT equal the Segment's own SegmentUUID. The SegmentFamily element MUST be shared by all Segments of a Linked Segment.

Matroska Writers MUST NOT use EBML Empty Elements if the element has a default value that is not 0 for integers/dates or 0x0p+0 for floats, because legacy parsers assumed 0 regardless of the declared default.

SeekPreRoll (EBML ID 0x56BB) specifies the duration in nanoseconds of data a decoder MUST decode after a discontinuity before its output is valid. This timestamp MUST be accounted for by the player during seeking for codecs requiring priming (e.g., Opus).

The docType of the EBML Header MUST be "matroska", EBMLMaxIDLength MUST be 4, and EBMLMaxSizeLength MUST be between 1 and 8 inclusive.

The Root Element (Segment) and all Top-Level Elements (direct children of Segment) MUST use 4 octets for their EBML Element ID.

The Tracks element MUST identify all data needed by each codec to decode the track. CodecID MUST be present for all tracks as the primary codec identifier. Additional codec initialization data is carried in CodecPrivate.

When FlagLacing in a TrackEntry is set to 0, all blocks in that track MUST have their lacing flags set to "no lacing". This allows readers to skip lacing parsing for tracks where it is never used.

Linked Segments support two modes: Hard Linking chains Segment files via PrevUUID/NextUUID in the Info element for sequential playback; Medium Linking uses Ordered Edition chapters with ChapterSegmentUUID to splice content from external Segments non-linearly.

ReferenceBlock (EBML ID 0xFB) stores the relative timestamp in Track Ticks of a Block that the current Block depends on for decoding. Multiple ReferenceBlock elements per BlockGroup are permitted for complex inter-frame dependencies. A value of 0 signals unknown dependencies.

The Cues element provides a temporal index for random access, containing CuePoint elements each pairing a CueTime timestamp with CueTrackPositions that identify the Cluster position. Without Cues, seeking requires a sequential scan.

The SeekHead element (EBML ID 0x114D9B74) contains Seek entries mapping Top-Level Element IDs (SeekID, 4-byte binary) to their Segment Positions (SeekPosition, uinteger). Its use is RECOMMENDED; without it, a parser must scan the entire file to locate Top-Level Elements.

The Segment element (EBML ID 0x18538067, master type) is the Root Element containing all other Top-Level Elements. It allows unknown size and must occur exactly once per EBML Document. Eight Top-Level child elements are defined: SeekHead, Info, Tracks, Chapters, Cluster, Cues, Attachments, and Tags.

Three timestamp scales are defined: Matroska Ticks (nanoseconds, used for CodecDelay, SeekPreRoll, DiscardPadding), Segment Ticks (nanoseconds × TimestampScale, used in Cluster Timestamp and Block offsets), and Track Ticks (Segment Ticks × TrackTimestampScale, used in BlockDuration and ReferenceBlock).

TimestampScale (EBML ID 0x2AD7B1, default 1000000, minOccurs=1) is the base unit in nanoseconds for Segment Ticks and Track Ticks. A value of 1000000 makes timestamps milliseconds. The value MUST NOT be 0.

RFC 9559 establishes 17 IANA registries for Matroska enumerated values: Element IDs, Compression Algorithms, Encryption Algorithms, AES Cipher Modes, Content Encoding Scopes, Content Encoding Types, Stereo Modes, Alpha Modes, Display Units, Horizontal Chroma Sitings, Vertical Chroma Sitings, Color Ranges, Tags Target Types, Chapter Codec IDs, Projection Types, Track Types, and Track Plane Types.

registry

Three media types are registered: video/x-matroska (.mkv) for files with video tracks, audio/x-matroska (.mka) for audio-only files, and video/x-matroska-3d (.mk3d) for stereoscopic video tracks.

registry

Matroska files may embed encrypted blocks (ContentEncryption), executable chapter codecs, and arbitrary attachments. Implementations must validate all element sizes, VINT encodings, and nesting depth to avoid buffer overflows, infinite loops, and resource exhaustion from malformed or malicious files.

security

A Block header consists of a VINT-encoded TrackNumber, a signed 16-bit Timestamp relative to the Cluster Timestamp, and a Flags byte encoding Gap (1 bit), Lacing mode (2 bits: 00=none, 01=Xiph, 11=EBML, 10=fixed-size), and reserved bits.

Block lacing packs multiple frames into one Block using four modes: no lacing (single frame), Xiph lacing (Xiph-encoded frame sizes), EBML lacing (EBML-encoded sizes with delta encoding after the first), and fixed-size lacing (all frames equal, no per-frame size field).

SegmentUUID is a 16-byte binary field (EBML ID 0x73A4) equivalent to UUID v4 with all bits randomly chosen. The value MUST contain at least one bit set to 1 and is required when the Segment participates in a Linked Segment.

SimpleBlock (EBML ID 0xA3) shares the Block header structure but adds Keyframe and Discardable flags in the Flags byte. It omits the BlockGroup wrapper and is used to minimize overhead when no per-block metadata is needed.