RFC 9559
Matroska Media Container Format Specification
RFC 9559: Matroska Media Container Format Specification 🎀 (Part 1 of 35)
Authors: S. Lhomme, M. Bunkus, D. Rice ✨ Published by: Internet Engineering Task Force (IETF) 🌸 Category: Standards Track 💅 Date: October 2024 🍓 Updates: RFC 8794 🦋 ISSN: 2070-1721 💜
The full text is at https://www.rfc-editor.org/info/rfc9559. Matroska has been running through the IETF process, so this is the official, approved standard. Yay 👑
Abstract
okay so this doc defines the Matroska audiovisual data container structure. That covers its structural elements, terminology, vocabulary, and how it actually gets used 📼
It also updates RFC 8794 so that a previously reserved Extensible Binary Meta Language (EBML) Element ID can now be used 🔓
Status of This Memo
This is an Internet Standards Track document. It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 7841 🧚
For the current status of this document, any errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc9559 💌
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. 🔒
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they were in effect on the date of publication. Please actually read these, bestie, because they spell out your rights and restrictions for this document. Code Components pulled out of this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Revised BSD License 📜
Table of Contents
1. Introduction
2. Status of This Document
3. Notation and Conventions
4. Matroska Overview
4.1. Principles
4.2. Updates to RFC 8794
4.3. Added EBML Constraints
4.4. Design Rules
4.5. Data Layout
5. Matroska Schema
5.1. Segment Element
5.1.1. SeekHead Element
5.1.1.1. Seek Element
5.1.2. Info Element
5.1.2.1. SegmentUUID Element
5.1.2.2. SegmentFilename Element
5.1.2.3. PrevUUID Element
5.1.2.4. PrevFilename Element
5.1.2.5. NextUUID Element
5.1.2.6. NextFilename Element
5.1.2.7. SegmentFamily Element
5.1.2.8. ChapterTranslate Element
5.1.2.9. TimestampScale Element
5.1.2.10. Duration Element
5.1.2.11. DateUTC Element
5.1.2.12. Title Element
5.1.2.13. MuxingApp Element
5.1.2.14. WritingApp Element
5.1.3. Cluster Element
5.1.3.1. Timestamp Element
5.1.3.2. Position Element
5.1.3.3. PrevSize Element
5.1.3.4. SimpleBlock Element
5.1.3.5. BlockGroup Element
5.1.4. Tracks Element
5.1.4.1. TrackEntry Element
5.1.5. Cues Element
5.1.5.1. CuePoint Element
5.1.6. Attachments Element
5.1.6.1. AttachedFile Element
5.1.7. Chapters Element
5.1.7.1. EditionEntry Element
5.1.8. Tags Element
5.1.8.1. Tag Element
6. Matroska Element Ordering
6.1. Top-Level Elements
6.2. CRC-32
6.3. SeekHead
6.4. Cues (Index)
6.5. Info
6.6. Chapters Element
6.7. Attachments
6.8. Tags
7. Matroska Versioning
8. Stream Copy
9. DefaultDecodedFieldDuration
10. Cluster Blocks
10.1. Block Structure
10.2. SimpleBlock Structure
10.3. Block Lacing
10.3.1. No Lacing
10.3.2. Xiph Lacing
10.3.3. EBML Lacing
10.3.4. Fixed-size Lacing
10.3.5. Laced Frames Timestamp
10.4. Random Access Points
11. Timestamps
11.1. Timestamp Ticks
11.1.1. Matroska Ticks
11.1.2. Segment Ticks
11.1.3. Track Ticks
11.2. Block Timestamps
11.3. TimestampScale Rounding
12. Language Codes
13. Country Codes
14. Encryption
15. Image Presentation
15.1. Cropping
15.2. Rotation
16. Segment Position
16.1. Segment Position Exception
16.2. Example of Segment Position
17. Linked Segments
17.1. Hard Linking
17.2. Medium Linking
17.2.1. Linked-Duration
17.2.2. Linked-Edition
18. Track Flags
18.1. Default Flag
18.2. Forced Flag
18.3. Hearing-Impaired Flag
18.4. Visual-Impaired Flag
18.5. Descriptions Flag
18.6. Original Flag
18.7. Commentary Flag
18.8. Track Operation
18.9. Overlay Track
18.10. Multi-planar and 3D Videos
19. Default Track Selection
19.1. Audio Selection
19.2. Subtitle Selection
20. Chapters
20.1. EditionEntry
20.1.1. EditionFlagDefault
20.1.2. Default Edition
20.1.3. EditionFlagOrdered
20.1.3.1. Ordered-Edition and Matroska Segment Linking
20.2. ChapterAtom
20.2.1. ChapterTimeStart
20.2.2. ChapterTimeEnd
20.2.3. Nested Chapters
20.2.4. Nested Chapters in Ordered Chapters
20.2.5. ChapterFlagHidden
20.3. Menu Features
20.4. Physical Types
20.5. Chapter Examples
20.5.1. Example 1: Basic Chaptering
20.5.2. Example 2: Nested Chapters
20.5.2.1. The Micronauts "Bleep To Bleep"
21. Attachments
21.1. Cover Art
21.2. Font Files
22. Cues
22.1. Recommendations
23. Matroska Streaming
23.1. File Access
23.2. Livestreaming
24. Tags
24.1. Tags Precedence
24.2. Tag Levels
25. Implementation Recommendations
25.1. Cluster
25.2. SeekHead
25.3. Optimum Layouts
25.3.1. Optimum Layout for a Muxer
25.3.2. Optimum Layout after Editing Tags
25.3.3. Optimum Layout with Cues at the Front
25.3.4. Optimum Layout for Livestreaming
26. Security Considerations
27. IANA Considerations
27.1. Matroska Element IDs Registry
27.2. Matroska Compression Algorithms Registry
27.3. Matroska Encryption Algorithms Registry
27.4. Matroska AES Cipher Modes Registry
27.5. Matroska Content Encoding Scopes Registry
27.6. Matroska Content Encoding Types Registry
27.7. Matroska Stereo Modes Registry
27.8. Matroska Alpha Modes Registry
27.9. Matroska Display Units Registry
27.10. Matroska Horizontal Chroma Sitings Registry
27.11. Matroska Vertical Chroma Sitings Registry
27.12. Matroska Color Ranges Registry
27.13. Matroska Tags Target Types Registry
27.14. Matroska Chapter Codec IDs Registry
27.15. Matroska Projection Types Registry
27.16. Matroska Track Types Registry
27.17. Matroska Track Plane Types Registry
27.18. Media Types
27.18.1. For Files Containing Video Tracks
27.18.2. For Files Containing Audio Tracks with No Video
Tracks
27.18.3. For Files Containing a Stereoscopic Video Track
28. References
28.1. Normative References
28.2. Informative References
Appendix A. Historic Deprecated Elements
A.1. SilentTracks Element
A.2. SilentTrackNumber Element
A.3. BlockVirtual Element
A.4. ReferenceVirtual Element
A.5. Slices Element
A.6. TimeSlice Element
A.7. LaceNumber Element
A.8. FrameNumber Element
A.9. BlockAdditionID Element
A.10. Delay Element
A.11. SliceDuration Element
A.12. ReferenceFrame Element
A.13. ReferenceOffset Element
A.14. ReferenceTimestamp Element
A.15. EncryptedBlock Element
A.16. MinCache Element
A.17. MaxCache Element
A.18. TrackOffset Element
A.19. CodecSettings Element
A.20. CodecInfoURL Element
A.21. CodecDownloadURL Element
A.22. CodecDecodeAll Element
A.23. TrackOverlay Element
A.24. AspectRatioType Element
A.25. GammaValue Element
A.26. FrameRate Element
A.27. ChannelPositions Element
A.28. TrickTrackUID Element
A.29. TrickTrackSegmentUID Element
A.30. TrickTrackFlag Element
A.31. TrickMasterTrackUID Element
A.32. TrickMasterTrackSegmentUID Element
A.33. ContentSignature Element
A.34. ContentSigKeyID Element
A.35. ContentSigAlgo Element
A.36. ContentSigHashAlgo Element
A.37. CueRefCluster Element
A.38. CueRefNumber Element
A.39. CueRefCodecState Element
A.40. FileReferral Element
A.41. FileUsedStartTime Element
A.42. FileUsedEndTime Element
A.43. TagDefaultBogus Element
Authors' Addresses1. Introduction ✨
Matroska is an audiovisual data container format 🎬 It grew out of a project called [MCF], but it totally went its own way 💅 because it's built on EBML (Extensible Binary Meta Language) [RFC8794], which is a binary derivative of XML. EBML gives Matroska major future-proofing energy, and parsers reading the older versions don't break 🫶
Let's clear something up so nobody gets confused 🙈 What even IS an audio/video container?
- NOT a video or audio compression format (codec). 💀
- It's an envelope that can hold lots of audio, video, and subtitle streams, so you can store a whole movie or a CD in one single file 🎞️
Matroska was designed with the future in mind 🔮 It's giving main character energy with features like:
- Fast seeking in the file ⚡
- Chapter entries 📖
- Full metadata (tags) support 🏷️
- Selectable subtitle/audio/video streams 🎧
- Modularly expandable 🧩
- Error resilience (can recover playback even when the stream is damaged) 🩹
- Streamable over the Internet and local networks (HTTP [RFC9110], FTP [RFC0959], SMB [SMB-CIFS], etc.) 🌐
- Menus (like menus that DVDs have [DVD-Video]) 📀
2. Status of This Document 🌸
This document covers Matroska versions 1, 2, 3, and 4. Version 4 is the current one. Versions 1 to 3 aren't maintained anymore, and no new elements are expected in files with version numbers 1, 2, or 3 🕰️
3. Notation and Conventions 📝
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. Only the all-caps versions count, so keep that in mind, bestie 🔠
This document defines the following terms so we can define the format and how Matroska is applied:
- 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. 🔍
- Matroska Player: A Matroska Reader whose main purpose is playing audiovisual files, including Matroska documents. ▶️
- Matroska Writer: A data writer that creates Matroska documents. ✍️
4. Matroska Overview 🦋
4.1. Principles 💜
Matroska is a Document Type of EBML. This spec depends on the EBML specification [RFC8794]. If you want to understand Matroska's EBML Schema, look especially at the parts of the EBML specification that cover EBML Element Types (Section 7), EBML Schema (Section 11.1), and EBML Structure (Section 3) 🧠
4.2. Updates to RFC 8794 ✨
Okay bestie, here's the tea 🫖 Because of an oversight, [RFC8794] reserved EBML ID 0x80, and deployed Matroska implementations are already using that ID 😭 So this spec updates [RFC8794] to make 0x80 a legal EBML ID. It's a total glow-up 💖 This spec also makes these updates:
- Section 17.1 of [RFC8794] (per Erratum ID #7189 [Err7189]) 🔥
OLD:
| One-octet Element IDs MUST be between 0x81 and 0xFE. These items
| are valuable because they are short, and they need to be used for
| commonly repeated elements. Element IDs are to be allocated
| within this range according to the "RFC Required" policy
| [RFC8126].
|
| The following one-octet Element IDs are RESERVED: 0xFF and 0x80.NEW:
| One-octet Element IDs MUST be between 0x80 and 0xFE. These items
| are valuable because they are short, and they need to be used for
| commonly repeated elements. Element IDs are to be allocated
| within this range according to the "RFC Required" policy
| [RFC8126].
|
| The following one-octet Element ID is RESERVED: 0xFF.- Section 5 of [RFC8794] (per Erratum ID #7191 [Err7191]) 💅
OLD:
+=========================+================+=================+
| Element ID Octet Length | Range of Valid | Number of Valid |
| | Element IDs | Element IDs |
+=========================+================+=================+
| 1 | 0x81 - 0xFE | 126 |
+-------------------------+----------------+-----------------+NEW:
+=========================+================+=================+
| Element ID Octet Length | Range of Valid | Number of Valid |
| | Element IDs | Element IDs |
+=========================+================+=================+
| 1 | 0x80 - 0xFE | 127 |
+-------------------------+----------------+-----------------+4.3. Added EBML Constraints 🎀
Since Matroska is an EBML Document Type, it adds some extra constraints on top of the EBML specification [RFC8794], and they're very much a vibe check:
- The docType of the EBML Header MUST be "matroska". 💜
- The EBMLMaxIDLength of the EBML Header MUST be 4.
- The EBMLMaxSizeLength of the EBML Header MUST be between 1 and 8, inclusive.
4.4. Design Rules 📐
The Root Element and all Top-Level Elements MUST use 4 octets for their EBML Element ID. That means Segment and its direct children. 🧚
Okay, so the history lesson 📜 Legacy EBML/Matroska parsers did not handle Empty Elements properly. The elements were there in the file, but their length was 0. Those parsers always assumed the value was 0 for integers/dates, or 0x0p+0 for floats (that's the textual form of floats, using the format in [ISO9899]), no matter what the default value of the element was supposed to be. So 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. Not okay, not doing that 🙅♀️
When adding new elements to Matroska, these rules apply:
- A non-mandatory integer/date Element MUST NOT have a default value other than 0. 🌸
- 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 strings cannot be defined in the XML Schema.
4.5. Data Layout 🗂️
A Matroska file MUST be made up of at least one EBML Document that uses the Matroska Document Type. Each EBML Document MUST start with an EBML Header and MUST be followed by the EBML Root Element, which Matroska defines as Segment. Several Top-Level Elements can live inside that Segment. 🦋
For example, a simple Matroska file with a single EBML Document could look like this:
- EBML Header
- Segment
A more complex Matroska file, which is an EBML Stream made of two EBML Documents, could look like this:
- EBML Header
- Segment
- EBML Header
- Segment
Here's the main diagram. It shows a simple Matroska file with an EBML Document containing an EBML Header, a Segment element (the Root Element), and all eight Matroska Top-Level Elements. In the diagrams in this section, horizontal spacing shows the parent-child relationship between elements (so Info sits inside Segment), and vertical alignment shows the storage order in the file. Visual learner moment 👀
+-------------+
| EBML Header |
+---------------------------+
| Segment | SeekHead |
| |-------------|
| | Info |
| |-------------|
| | Tracks |
| |-------------|
| | Chapters |
| |-------------|
| | Cluster |
| |-------------|
| | Cues |
| |-------------|
| | Attachments |
| |-------------|
| | Tags |
+---------------------------+
Figure 1: Basic Layout of a Matroska FileThe Matroska EBML Schema defines eight Top-Level Elements:
- SeekHead (Section 6.3)
- Info (Section 6.5)
- Tracks (Section 18)
- Chapters (Section 20)
- Cluster (Section 10)
- Cues (Section 22)
- Attachments (Section 21)
- Tags (Section 6.8)
The SeekHead element (also known as MetaSeek) holds an index of where the Top-Level Elements are located within the Segment. Using a SeekHead element is RECOMMENDED 🙌 Without one, a Matroska parser would have to search the entire file to find all the other Top-Level Elements. That's because Matroska is very flexible about ordering. For instance, the Chapters element is allowed to be stored after the Cluster element(s). Chaotic but valid 🌈
+--------------------------------+
| SeekHead | Seek | SeekID |
| | |--------------|
| | | SeekPosition |
+--------------------------------+
Figure 2: Representation of a SeekHead ElementThe Info element is the one with the vital info for identifying the whole Segment. That includes the title of the Segment, a randomly generated unique identifier (UID), and the UID(s) of any linked Segment elements. It's the ID card of the file 🪪
+-------------------------+
| Info | SegmentUUID |
| |------------------|
| | SegmentFilename |
| |------------------|
| | PrevUUID |
| |------------------|
| | PrevFilename |
| |------------------|
| | NextUUID |
| |------------------|
| | NextFilename |
| |------------------|
| | SegmentFamily |
| |------------------|
| | ChapterTranslate |
| |------------------|
| | TimestampScale |
| |------------------|
| | Duration |
| |------------------|
| | DateUTC |
| |------------------|
| | Title |
| |------------------|
| | MuxingApp |
| |------------------|
| | WritingApp |
|-------------------------|
Figure 3: Representation of an Info Element and Its Child ElementsThe Tracks element defines the technical details for each track. It can store the name, number, UID, language, and type (audio, video, subtitles, etc.) of each track. For example, the Tracks element MAY store info about the resolution of a video track or the sample rate of an audio track. 🎬
The Tracks element MUST identify all the data the codec needs to decode the data of the specified track. The exact data needed depends on the codec, though. For example, a Track element for uncompressed audio only needs the audio bit rate to be present. A codec like AC-3 would require that the CodecID element be present for all tracks, because it's the main way to figure out which codec to use for decoding the track. Main character energy for CodecID ✨
+------------------------------------+
| Tracks | TrackEntry | TrackNumber |
| | |--------------|
| | | TrackUID |
| | |--------------|
| | | TrackType |
| | |--------------|
| | | Name |
| | |--------------|
| | | Language |
| | |--------------|
| | | CodecID |
| | |--------------|
| | | CodecPrivate |
| | |--------------|
| | | CodecName |
| | |----------------------------------+
| | | Video | FlagInterlaced |
| | | |-------------------|
| | | | FieldOrder |
| | | |-------------------|
| | | | StereoMode |
| | | |-------------------|
| | | | AlphaMode |
| | | |-------------------|
| | | | PixelWidth |
| | | |-------------------|
| | | | PixelHeight |
| | | |-------------------|
| | | | DisplayWidth |
| | | |-------------------|
| | | | DisplayHeight |
| | | |-------------------|
| | | | AspectRatioType |
| | | |-------------------|
| | | | Colour |
| | |----------------------------------|
| | | Audio | SamplingFrequency |
| | | |-------------------|
| | | | Channels |
| | | |-------------------|
| | | | BitDepth |
|--------------------------------------------------------|
Figure 4: Representation of the Tracks Element and a Selection of Its
Descendant ElementsThe Chapters element lists all of the chapters. Chapters are a way to set predefined points to jump to in video or audio. 🔖
+-----------------------------------------+
| Chapters | Edition | EditionUID |
| | Entry |--------------------|
| | | EditionFlagDefault |
| | |--------------------|
| | | EditionFlagOrdered |
| | |---------------------------------+
| | | ChapterAtom | ChapterUID |
| | | |-------------------|
| | | | ChapterStringUID |
| | | |-------------------|
| | | | ChapterTimeStart |
| | | |-------------------|
| | | | ChapterTimeEnd |
| | | |-------------------|
| | | | ChapterFlagHidden |
| | | |-------------------------------+
| | | | ChapterDisplay | ChapString |
| | | | |--------------|
| | | | | ChapLanguage |
+------------------------------------------------------------------+ Figure 5: Representation of the Chapters Element and a Selection
of Its Descendant Elementsokay so the Chapters tree is giving family tree energy 🌳✨ Edition at the top, then ChapterAtom hanging off it, then all the little display bits. Iconic layout, honestly 💅
Cluster elements hold the actual content for each track, like 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 Section 17. 🔗
The Cluster element is the thing that chops up SimpleBlock or BlockGroup elements, and it helps with seeking and error protection 🛡️ Every Cluster element MUST contain a Timestamp element, no cap. 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 Section 11.2. ⏱️
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 🎙️ That's a valid vibe, bestie.
A BlockGroup element MAY contain a Block of data and any information relating directly to that Block 🌸
+--------------------------+
| Cluster | Timestamp |
| |----------------|
| | Position |
| |----------------|
| | PrevSize |
| |----------------|
| | SimpleBlock |
| |----------------|
| | BlockGroup |
+--------------------------+ Figure 6: Representation of a Cluster Element and Its Immediate
Child Elements +----------------------------------+
| Block | Portion of | Data Type |
| | a Block | - Bit Flag |
| |--------------------------+
| | Header | TrackNumber |
| | |-------------|
| | | Timestamp |
| | |-------------|
| | | Flags |
| | | - Gap |
| | | - Lacing |
| | | - Reserved |
| |--------------------------|
| | Optional | FrameSize |
| |--------------------------|
| | Data | Frame |
+----------------------------------+ Figure 7: Representation of the Block Element StructureOkay, the Timestamp rules are kind of the main character here 👑 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 (Section 6.2). 🧠
Now the Block's own timestamp is an offset 🎯 If you add it to the Cluster's Timestamp value, you get the Block's effective timestamp. So the Block's number is relative to the Cluster's Timestamp. Example time: if the Cluster's Timestamp is set to 10 seconds and a Block in that Cluster is supposed to play 12 seconds into the clip, the timestamp in the Block gets set to 2 seconds. Math is mathing 🧮✨
The ReferenceBlock inside the BlockGroup is used instead of the basic "P-frame"/"B-frame" description 🦋 Instead of just saying this Block depends on the one directly before or directly after, the Timestamp of the necessary Block is used. Since there can be as many ReferenceBlock elements as necessary for a Block, it allows for some extremely complex referencing. Chaotic but iconic 😭
The Cues element is what helps you seek when you're playing back a file 🔍 It gives you a temporal index for some of the Tracks. It's similar to the SeekHead element, but it's for seeking to a specific time during playback. You can seek without it, but it's way harder, because a Matroska Reader would have to "hunt and peck" through the file looking for the right 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 is super flexible, periodt 💖 It can index every single timestamp of every Block, or it can index selectively. Your call, queen.
+-------------------------------------+
| Cues | CuePoint | CueTime |
| | |-------------------|
| | | CueTrackPositions |
| |------------------------------|
| | CuePoint | CueTime |
| | |-------------------|
| | | CueTrackPositions |
+-------------------------------------+ Figure 8: Representation of a Cues Element and Two Levels of Its
Descendant ElementsThe Attachments element is for attaching files to a Matroska file 📎 Think pictures, fonts, web pages, etc. Very scrapbook energy 🎀
+------------------------------------------------+
| Attachments | AttachedFile | FileDescription |
| | |-------------------|
| | | FileName |
| | |-------------------|
| | | FileMediaType |
| | |-------------------|
| | | FileData |
| | |-------------------|
| | | FileUID |
+------------------------------------------------+ Figure 9: Representation of an Attachments ElementThe Tags element holds metadata that describes the Segment and potentially its Tracks, Chapters, and Attachments 🏷️ Each Track or Chapter that those tags apply to has its UID listed in the Tags. The Tags contain all the extra info about the file: scriptwriters, singers, actors, directors, titles, edition, price, dates, genre, comments, etc. Tags can store their values in multiple languages, which is so cute to me 🌈 For example, a movie's "TITLE" tag value might contain both the original English title and the German title 🎬
+-------------------------------------------+
| Tags | Tag | Targets | TargetTypeValue |
| | | |------------------|
| | | | TargetType |
| | | |------------------|
| | | | TagTrackUID |
| | | |------------------|
| | | | TagEditionUID |
| | | |------------------|
| | | | TagChapterUID |
| | | |------------------|
| | | | TagAttachmentUID |
| | |------------------------------|
| | | SimpleTag | TagName |
| | | |------------------|
| | | | TagLanguage |
| | | |------------------|
| | | | TagDefault |
| | | |------------------|
| | | | TagString |
| | | |------------------|
| | | | TagBinary |
| | | |------------------|
| | | | SimpleTag |
+-------------------------------------------+ Figure 10: Representation of a Tags Element and Three Levels of
Its Children Elements5. Matroska Schema 🧬
This specification includes an EBML Schema that defines the elements and structure of Matroska, using the EBML Schema elements and attributes defined in Section 11.1 of [RFC8794] 📜
Attributes that use their default value (like minOccurs, minver, etc.) or attributes with undefined values (like length, maxver, etc.) are omitted, so don't go looking for them 🙈
The definitions for each Matroska element are provided below 💜
5.1. Segment Element 🎞️
id / type: 0x18538067 / master
unknownsizeallowed: True
path: \Segment
minOccurs / maxOccurs: 1 / 1The Root Element that contains all other Top-Level Elements; see Section 4.5. The main container, the whole vibe ✨
5.1.1. SeekHead Element
id / type: 0x114D9B74 / master
path: \Segment\SeekHead
maxOccurs: 2Contains seeking information of Top-Level Elements; see Section 4.5. It's the table of contents for the big stuff 📚
5.1.1.1. Seek Element
id / type: 0x4DBB / master
path: \Segment\SeekHead\Seek
minOccurs: 1Contains a single seek entry to an EBML Element 🔖
5.1.1.1.1. SeekID Element
id / type: 0x53AB / binary
length: 4
path: \Segment\SeekHead\Seek\SeekID
minOccurs / maxOccurs: 1 / 1The binary EBML ID of a Top-Level Element. Just the ID, no extras 🤏
5.1.1.1.2. SeekPosition Element
id / type: 0x53AC / uinteger
path: \Segment\SeekHead\Seek\SeekPosition
minOccurs / maxOccurs: 1 / 1The Segment Position (Section 16) of a Top-Level Element. It tells you where to go 📍
5.1.2. Info Element
id / type: 0x1549A966 / master
path: \Segment\Info
minOccurs / maxOccurs: 1 / 1
recurring: TrueContains general information about the Segment ℹ️
5.1.2.1. SegmentUUID Element
id / type: 0x73A4 / binary
length: 16
path: \Segment\Info\SegmentUUID
maxOccurs: 1A randomly generated UID that identifies the Segment amongst many others (128 bits). It is equivalent to a Universally Unique Identifier (UUID) v4 [RFC9562] with all bits randomly (or pseudorandomly) chosen. An actual UUID v4 value, where some bits are not random, MAY also be used. It's giving unique fingerprint 🪪
Usage notes: 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. So it can't be all zeros, bestie 🚫
5.1.2.2. SegmentFilename Element
id / type: 0x7384 / utf-8
path: \Segment\Info\SegmentFilename
maxOccurs: 1A filename corresponding to this Segment 📝
5.1.2.3. PrevUUID Element
id / type: 0x3CB923 / binary
length: 16
path: \Segment\Info\PrevUUID
maxOccurs: 1An ID that identifies the previous Segment of a Linked Segment 🔗
Usage notes: If the Segment is a part of a Linked Segment that uses Hard Linking (Section 17.1), 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. This one is kind of a plot twist, ngl 😭
5.1.2.4. PrevFilename Element ✨
okay so PrevFilename is the filename for the file of the previous Linked Segment 📁 it's basically a display thing, bestie 💖
- id / type:
0x3C83AB/ utf-8 - path:
\Segment\Info\PrevFilename - maxOccurs: 1
- definition: A filename corresponding to the file of the previous Linked Segment.
- usage notes: Provision of the previous filename is for display convenience, but
PrevUUIDSHOULD be considered authoritative for identifying the previous Segment in a Linked Segment.
ngl the vibe here is "the name is for looks, but the UUID is the real main character" 👑
5.1.2.5. NextUUID Element 🦋
this one is the ID for the next Segment in a Linked Segment, and it's binary and exactly 16 bytes long 🫶
- id / type:
0x3EB923/ binary - length: 16
- path:
\Segment\Info\NextUUID - maxOccurs: 1
- definition: An ID that identifies the next Segment of a Linked Segment.
- usage notes: If the Segment is a part of a Linked Segment that uses Hard Linking (Section 17.1), then either the
PrevUUIDor theNextUUIDelement is REQUIRED. If a Segment contains aNextUUIDbut not aPrevUUID, then it MAY be considered as the first Segment of the Linked Segment. TheNextUUIDMUST NOT be equal to theSegmentUUID.
so for Hard Linking, you need PrevUUID or NextUUID (at least one of them, it's giving "pick your fighter" 🥊). and a NextUUID can't be the same as your own SegmentUUID, no cap 🙅♀️
5.1.2.6. NextFilename Element 🌸
the next-file version of PrevFilename, lol 💅
- id / type:
0x3E83BB/ utf-8 - path:
\Segment\Info\NextFilename - maxOccurs: 1
- definition: A filename corresponding to the file of the next Linked Segment.
- usage notes: Provision of the next filename is for display convenience, but
NextUUIDSHOULD be considered authoritative for identifying the Next Segment.
same energy as before: the filename is cute, but the UUID is the one people actually look at 🎀
5.1.2.7. SegmentFamily Element 🧚
this is the big family ID that every Segment in a Linked Segment shares 👨👩👧👦 it's 128 bits, and it's basically a UUID v4 where all the bits are randomly (or pseudorandomly) picked ✨ a real UUID v4 with some non-random bits can also work, which is a nice little plot twist 🌈
- id / type:
0x4444/ binary - length: 16
- path:
\Segment\Info\SegmentFamily - definition: A UID that all Segments of a Linked Segment MUST share (128 bits). It is equivalent to a UUID v4 [RFC9562] with all bits randomly (or pseudorandomly) chosen. An actual UUID v4 value, where some bits are not random, MAY also be used.
- usage notes: If the Segment Info contains a
ChapterTranslateelement, this element is REQUIRED.
so the family ID is a MUST for everyone in the group, and if your Segment Info has a ChapterTranslate, then SegmentFamily is REQUIRED too 🙈 no exceptions, periodt 💀
5.1.2.8. ChapterTranslate Element 💜
this one is the translator between this Segment and a segment value in a given Chapter Codec 🦋 like a little dictionary, but make it cute 📖
- id / type:
0x6924/ master - path:
\Segment\Info\ChapterTranslate - definition: The mapping between this Segment and a segment value in the given Chapter Codec.
- rationale: 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 SegmentUUIDs in Matroska. This allows remuxing a file with Chapter Codec without changing the content of the codec data, just the Segment mapping.
the rationale is honestly so iconic 😭 the codec might not know how Matroska names its segments, so ChapterTranslate maps the codec's names to SegmentUUIDs. that means you can remux the file without touching the codec data, you only change the mapping 🧚✨
5.1.2.8.1. ChapterTranslateID Element 🍓
- id / type:
0x69A5/ binary - path:
\Segment\Info\ChapterTranslate\ChapterTranslateID - minOccurs / maxOccurs: 1 / 1
- definition: The binary value used to represent this Segment in the chapter codec data. The format depends on the ChapProcessCodecID used; see Section 5.1.7.1.4.15.
the format of this ID depends on the ChapProcessCodecID, so go check Section 5.1.7.1.4.15 if you want the details 📚
5.1.2.8.2. ChapterTranslateCodec Element 🌈
- id / type:
0x69BF/ uinteger - path:
\Segment\Info\ChapterTranslate\ChapterTranslateCodec - minOccurs / maxOccurs: 1 / 1
- definition: Applies to the chapter codec of the given chapter edition(s); see Section 5.1.7.1.4.15.
- defined values: See Table 31. Additional values can be registered in the "Matroska Chapter Codec IDs" registry defined in Section 27.14.
this is the codec the translation applies to 🎯 see Table 31 for the values that already exist, and the "Matroska Chapter Codec IDs" registry in Section 27.14 is where new ones can get added 🌸
5.1.2.8.3. ChapterTranslateEditionUID Element 🎀
- id / type:
0x69FC/ uinteger - path:
\Segment\Info\ChapterTranslate\ChapterTranslateEditionUID - definition: Specifies a chapter edition UID to which this ChapterTranslate applies.
- usage notes: When no
ChapterTranslateEditionUIDis specified in the ChapterTranslate, the ChapterTranslate applies to all chapter editions found in the Segment using the givenChapterTranslateCodec.
so if you don't pick an edition UID, the translation applies to every chapter edition in the Segment that uses that codec 👑 that's the whole "all the people, all the time" energy 🫶
5.1.2.9. TimestampScale Element ⭐
this is the base unit for Segment Ticks and Track Ticks, measured in nanoseconds 🕰️
- id / type / default:
0x2AD7B1/ uinteger / 1000000 - range: not 0 (1-18446744073709551615)
- path:
\Segment\Info\TimestampScale - minOccurs / maxOccurs: 1 / 1
- definition: 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 Section 11 on how to interpret timestamps.
the default of 1000000 means milliseconds, bestie 🥹 and Section 11 tells you how to read the timestamps
5.1.2.10. Duration Element 🌙
- id / type:
0x4489/ float - range:
> 0x0p+0 - path:
\Segment\Info\Duration - maxOccurs: 1
- definition: Duration of the Segment, expressed in Segment Ticks, which are based on TimestampScale; see Section 11.1.
the length of the whole Segment, counted in Segment Ticks ⏳
5.1.2.11. DateUTC Element 📅
- id / type:
0x4461/ date - path:
\Segment\Info\DateUTC - maxOccurs: 1
- definition: The date and time that the Segment was created by the muxing application or library.
when the Segment was made, courtesy of whichever muxing app did the work 📸
5.1.2.12. Title Element 🎬
- id / type:
0x7BA9/ utf-8 - path:
\Segment\Info\Title - maxOccurs: 1
- definition: General name of the Segment.
the general name, the big title energy 🎬🍿
5.1.2.13. MuxingApp Element 🧁
- id / type:
0x4D80/ utf-8 - path:
\Segment\Info\MuxingApp - minOccurs / maxOccurs: 1 / 1
- definition: Muxing application or library (example:
"libmatroska-0.4.3"). - usage notes: Include the full name of the application or library followed by the version number.
the app that did the muxing gets its name AND version in here, no shortcuts 💅
5.1.2.14. WritingApp Element 🖊️
- id / type:
0x5741/ utf-8 - path:
\Segment\Info\WritingApp - minOccurs / maxOccurs: 1 / 1
- definition: Writing application (example:
"mkvmerge-0.3.3"). - usage notes: Include the full name of the application followed by the version number.
same rule for the writing app: full name plus version, every time ✨
5.1.3. Cluster Element 🫧
- id / type:
0x1F43B675/ master - unknownsizeallowed: True
- path:
\Segment\Cluster - definition: The Top-Level Element containing the (monolithic) Block structure.
the Cluster is the Top-Level Element that holds the monolithic Block structure, so it's basically the big box of frames 📦
5.1.3.1. Timestamp Element ⏰
- id / type:
0xE7/ uinteger - path:
\Segment\Cluster\Timestamp - minOccurs / maxOccurs: 1 / 1
- definition: Absolute timestamp of the cluster, expressed in Segment Ticks, which are based on TimestampScale; see Section 11.1.
- usage notes: 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 (Section 6.2).
this one SHOULD go first in its Cluster, or second if there's a CRC-32 element hanging out up top (Section 6.2) 🙋♀️
5.1.3.2. Position Element 📍
- id / type:
0xA7/ uinteger - path:
\Segment\Cluster\Position - maxOccurs: 1
- maxver: 4
- definition: The Segment Position of the Cluster in the Segment (0 in live streams). It might help to resynchronize the offset on damaged streams.
so this is where the Cluster sits inside the Segment, and it's 0 in live streams 📡 it can help get things back in sync when a stream gets a little damaged 🩹
5.1.3.3. PrevSize Element 🐾
- id / type:
0xAB/ uinteger - path:
\Segment\Cluster\PrevSize - maxOccurs: 1
- definition: Size of the previous Cluster, in octets. Can be useful for backward playing.
the size of the previous Cluster in octets, and it's handy if you're playing things backwards ⏪🔄
5.1.3.4. SimpleBlock Element 🎈
- id / type:
0xA3/ binary - path:
\Segment\Cluster\SimpleBlock - minver: 2
- definition: Similar to Block (see Section 10.1) but without all the extra information. Mostly used to reduce overhead when no extra feature is needed; see Section 10.2 on SimpleBlock Structure.
it's the streamlined version of Block, minus the extra stuff, so it's lighter when you don't need the extras 🪶
5.1.3.5. BlockGroup Element 🧺
- id / type:
0xA0/ master - path:
\Segment\Cluster\BlockGroup - definition: Basic container of information containing a single Block and information specific to that Block.
a little basket that holds one Block plus the info that's specific to that Block 🧺✨
5.1.3.5.1. Block Element 🎞️
- id / type:
0xA1/ binary - path:
\Segment\Cluster\BlockGroup\Block - minOccurs / maxOccurs: 1 / 1
- definition: Block containing the actual data to be rendered and a timestamp relative to the Cluster Timestamp; see Section 10.1 on Block Structure.
the Block holds the actual data to be rendered, plus a timestamp that's relative to the Cluster Timestamp (Section 10.1 has the full scoop) 🎥
5.1.3.5.2. BlockAdditions Element 🎁
- id / type:
0x75A1/ master - path:
\Segment\Cluster\BlockGroup\BlockAdditions - maxOccurs: 1
- definition: Contains additional binary data to complete the Block element; see Section 4.1.5 of [MatroskaCodec] for more information. An EBML parser that has no knowledge of the Block structure could still see and use/skip these data.
extra binary data that completes the Block 🎁 even an EBML parser that doesn't know the Block structure can still spot these and use or skip them, which is so considerate 🥰
5.1.3.5.2.1. BlockMore Element 🧩
- id / type:
0xA6/ master - path:
\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore - minOccurs: 1
- definition: Contains the BlockAdditional and some parameters.
this is where the BlockAdditional lives, along with a few parameters 💫
5.1.3.5.2.2. BlockAdditional Element 🌟
- id / type:
0xA5/ binary - path:
\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAdditional - minOccurs / maxOccurs: 1 / 1
- definition: Interpreted by the codec as it wishes (using the BlockAddID).
the codec gets to decide what this data means, using the BlockAddID as the hint 🔑
5.1.3.5.2.3. BlockAddID Element 🔢
- id / type / default:
0xEE/ uinteger / 1 - range: not 0 (1-18446744073709551615)
- path:
\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAddID - minOccurs / maxOccurs: 1 / 1
- definition: An ID that identifies how to interpret the BlockAdditional data; see Section 4.1.5 of [MatroskaCodec] 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.
- usage notes: Each
BlockAddIDvalue MUST be unique between all BlockMore elements found in a BlockAdditions element. To keepMaxBlockAdditionIDas low as possible, small values SHOULD be used.
so the BlockAddID is the label that tells you how to read the BlockAdditional data 🏷️ a 1 means the codec defines it, anything else follows the BlockAddIDType in the TrackEntry 📝 every BlockAddID MUST be unique across the BlockMore elements in a BlockAdditions element, and small numbers SHOULD be used to keep MaxBlockAdditionID low 🙌
5.1.3.5.3. BlockDuration Element ⏱️
- id / type:
0x9B/ uinteger - path:
\Segment\Cluster\BlockGroup\BlockDuration - minOccurs / maxOccurs: See Table 1 / 1
- definition: The duration of the Block, expressed in Track Ticks; see Section 11.1. 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.
- notes: See Table 1.
this one's the length of the Block in Track Ticks, and it's super handy for the last frame of a Track (since there's no next Block to measure against) or for gaps like subtitle tracks 🎬 Table 1 has the fine print:
+===========+==================================================+
| attribute | note |
+===========+==================================================+
| minOccurs | BlockDuration MUST be set (minOccurs=1) if the |
| | associated TrackEntry stores a DefaultDuration |
| | value. |
+-----------+--------------------------------------------------+
| default | 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). |
+-----------+--------------------------------------------------+
Table 1: BlockDuration Implementation Notesso the big rule: if the TrackEntry has a DefaultDuration, BlockDuration MUST be set 🚨 and if it's missing with no DefaultDuration around, it's the gap between this Block's timestamp and the next Block's timestamp in "display" order, not coding order 🙃
5.1.3.5.4. ReferencePriority Element 🏆
- id / type / default:
0xFA/ uinteger / 0 - path:
\Segment\Cluster\BlockGroup\ReferencePriority - minOccurs / maxOccurs: 1 / 1
- definition: This frame is referenced and has the specified cache priority. 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.
this is the cache VIP list 👑 a frame with a higher priority is the only kind that can replace this one in the cache, and a 0 just means nobody's referencing it 🫠
5.1.3.5.5. ReferenceBlock Element
id / type: 0xFB / integer
path: \Segment\Cluster\BlockGroup\ReferenceBlockokay so this one is the ReferenceBlock 🧚 it's a timestamp, but a relative one: it's measured from the timestamp of the Block sitting in this same BlockGroup, and the unit is Track Ticks (see Section 11.1) 🎀 its whole job is pointing at the other frames this frame needs in order to get decoded 💅 the value SHOULD line up with a valid Block that this Block depends on 🫶 and bestie, lowkey the wild part is that older Matroska Writers didn't actually write the Block(s) this one depends on 💀 they wrote some Block(s) from the past instead, and that's the messy history we're dealing with 😭
the value "0" MAY also be used 🌸 to say "this Block can't be decoded on its own, but I don't know which reference Block(s) it needs" 🙈 and when that happens, other ReferenceBlock elements MUST NOT show up in the same BlockGroup 🔥 if the BlockGroup doesn't have any ReferenceBlock element at all, then the Block inside can be decoded without touching any other Block data ✨ no cap, that's the whole independence check 👑
5.1.3.5.6. CodecState Element
id / type: 0xA4 / binary
path: \Segment\Cluster\BlockGroup\CodecState
maxOccurs: 1
minver: 2this is the CodecState 🦋 it holds the new codec state to use, and the data interpretation is totally private to the codec 🌈 so nobody else gets to poke at it, periodt 💜 the information SHOULD always be referenced by a seek entry 🍓
5.1.3.5.7. DiscardPadding Element
id / type: 0x75A2 / integer
path: \Segment\Cluster\BlockGroup\DiscardPadding
maxOccurs: 1
minver: 4ooh the DiscardPadding ⭐ this is the duration of the silent data that got added to the Block, measured in Matroska Ticks (aka nanoseconds, see Section 11.1) 🧚 positive values mean the padding is at the end of the Block, and negative values mean it's at the beginning 🦋 the duration of DiscardPadding doesn't count toward the duration of the TrackEntry, and it SHOULD be discarded during playback 💖 kinda iconic honestly 👑
5.1.4. Tracks Element
id / type: 0x1654AE6B / master
path: \Segment\Tracks
maxOccurs: 1
recurring: Trueand now we're at the Tracks Element 🎀 it's a Top-Level Element of information with many tracks described inside 🌸 main character energy for sure ✨
5.1.4.1. TrackEntry Element
id / type: 0xAE / master
path: \Segment\Tracks\TrackEntry
minOccurs: 1the TrackEntry describes one track with all of its elements 🫶 it's the one-track-at-a-time card 💅
5.1.4.1.1. TrackNumber Element
id / type: 0xD7 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\TrackNumber
minOccurs / maxOccurs: 1 / 1the TrackNumber is the track number as used in the Block Header 🍓 it has to be exactly one and it can't be 0 🙈
5.1.4.1.2. TrackUID Element
id / type: 0x73C5 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\TrackUID
minOccurs / maxOccurs: 1 / 1
stream copy: True (Section 8)the TrackUID is a UID that identifies the Track 🧚 same range rule, never 0 💖 and it's marked for stream copy (see Section 8) 🦋
5.1.4.1.3. TrackType Element
id / type: 0x83 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\TrackType
minOccurs / maxOccurs: 1 / 1
stream copy: True (Section 8)the TrackType defines what kind of frames show up in the Track 🌈 the value SHOULD be stored on 1 octet 💅 for the defined values, check out Table 2 🎀 and if you need a brand new one, it can be registered in the "Matroska Track Types" registry defined in Section 27.16 ✨
+=======+==========+==========================================+
| value | label | contents of each frame |
+=======+==========+==========================================+
| 1 | video | An image. |
+-------+----------+------------------------------------------+
| 2 | audio | Audio samples. |
+-------+----------+------------------------------------------+
| 3 | complex | A mix of different other TrackType. The |
| | | codec needs to define how the Matroska |
| | | Player should interpret such data. |
+-------+----------+------------------------------------------+
| 16 | logo | An image to be rendered over the video |
| | | track(s). |
+-------+----------+------------------------------------------+
| 17 | subtitle | Subtitle or closed caption data to be |
| | | rendered over the video track(s). |
+-------+----------+------------------------------------------+
| 18 | buttons | Interactive button(s) to be rendered |
| | | over the video track(s). |
+-------+----------+------------------------------------------+
| 32 | control | Metadata used to control the player of |
| | | the Matroska Player. |
+-------+----------+------------------------------------------+
| 33 | metadata | Timed metadata that can be passed on to |
| | | the Matroska Player. |
+-------+----------+------------------------------------------+
Table 2: TrackType Values5.1.4.1.4. FlagEnabled Element
id / type / default: 0xB9 / uinteger / 1
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagEnabled
minOccurs / maxOccurs: 1 / 1
minver: 2FlagEnabled is set to 1 when the track is usable 💖 and fun fact, you can flip an unusable track into a usable one with chapter codecs or control tracks 🎀
5.1.4.1.5. FlagDefault Element
id / type / default: 0x88 / uinteger / 1
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagDefault
minOccurs / maxOccurs: 1 / 1FlagDefault is set to 1 when the track (audio, video, or subtitles) is eligible for automatic selection by the player 🧚 more details are in Section 19 🌸
5.1.4.1.6. FlagForced Element
id / type / default: 0x55AA / uinteger / 0
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagForced
minOccurs / maxOccurs: 1 / 1FlagForced only applies to subtitles 🫶 set it to 1 and the track is eligible for automatic selection if it matches the user's language preference, even when their preferences wouldn't normally turn on subtitles for the selected audio track 🙈 this is perfect for tracks that only have translations of foreign-language audio or on-screen text 🌈 see Section 19 for the deets 💅
5.1.4.1.7. FlagHearingImpaired Element
id / type: 0x55AB / uinteger
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagHearingImpaired
maxOccurs: 1
minver: 4FlagHearingImpaired is set to 1 if and only if the track is suitable for users with hearing impairments 🦋
5.1.4.1.8. FlagVisualImpaired Element
id / type: 0x55AC / uinteger
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagVisualImpaired
maxOccurs: 1
minver: 4FlagVisualImpaired is set to 1 if and only if the track is suitable for users with visual impairments 💜
5.1.4.1.9. FlagTextDescriptions Element
id / type: 0x55AD / uinteger
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagTextDescriptions
maxOccurs: 1
minver: 4FlagTextDescriptions is set to 1 if and only if the track contains textual descriptions of video content 🌸
5.1.4.1.10. FlagOriginal Element
id / type: 0x55AE / uinteger
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagOriginal
maxOccurs: 1
minver: 4FlagOriginal is set to 1 if and only if the track is in the content's original language 🧚
5.1.4.1.11. FlagCommentary Element
id / type: 0x55AF / uinteger
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagCommentary
maxOccurs: 1
minver: 4FlagCommentary is set to 1 if and only if the track contains commentary 🎀
5.1.4.1.12. FlagLacing Element
id / type / default: 0x9C / uinteger / 1
range: 0-1
path: \Segment\Tracks\TrackEntry\FlagLacing
minOccurs / maxOccurs: 1 / 1FlagLacing set to 1 means the track MAY contain blocks that use lacing 🫶 but if it's set to 0, then ALL blocks MUST have their lacing flags set to "no lacing" 🙈 see Section 10.3 on 'Block' Lacing for the full scoop 💅
5.1.4.1.13. DefaultDuration Element
id / type: 0x23E383 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\DefaultDuration
maxOccurs: 1
stream copy: True (Section 8)DefaultDuration is the number of nanoseconds per frame, measured in Matroska Ticks (aka nanoseconds, see Section 11.1) 🌈 "frame" here means the Matroska sense, one element put into a (Simple)Block 🧚 can't be 0, and it's stream copy too 💖
5.1.4.1.14. DefaultDecodedFieldDuration Element
id / type: 0x234E7A / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\DefaultDecodedFieldDuration
maxOccurs: 1
minver: 4
stream copy: True (Section 8)DefaultDecodedFieldDuration is the period between two successive fields at the output of the decoding process 🍓 it's measured in Matroska Ticks (aka nanoseconds, see Section 11.1) ✨ for more info, see Section 9 🫶
5.1.4.1.15. TrackTimestampScale Element
id / type / default: 0x23314F / float / 0x1p+0
range: > 0x0p+0
path: \Segment\Tracks\TrackEntry\TrackTimestampScale
minOccurs / maxOccurs: 1 / 1
maxver: 3
stream copy: True (Section 8)TrackTimestampScale is the scale applied on this track so it plays at normal speed next to the other tracks 🔥 it's mostly used to adjust video speed when the audio length is different 👑
5.1.4.1.16. MaxBlockAdditionID Element
id / type / default: 0x55EE / uinteger / 0
path: \Segment\Tracks\TrackEntry\MaxBlockAdditionID
minOccurs / maxOccurs: 1 / 1MaxBlockAdditionID is the maximum value of BlockAddID (Section 5.1.3.5.2.3) 💖 a value of 0 means there are no BlockAdditions (Section 5.1.3.5.2) for this track 🦋
5.1.4.1.17. BlockAdditionMapping Element
id / type: 0x41E4 / master
path: \Segment\Tracks\TrackEntry\BlockAdditionMapping
minver: 4BlockAdditionMapping holds elements that extend the track format by adding content either to each frame, using BlockAddID (Section 5.1.3.5.2.3), or to the track as a whole using BlockAddIDExtraData 🌸 bestie this one is so layered 🧚
5.1.4.1.17.1. BlockAddIDValue Element
id / type: 0x41F0 / uinteger
range: >=2
path: \Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDValue
maxOccurs: 1
minver: 4BlockAddIDValue: if the track format extension needs content beside frames, this value refers to the BlockAddID (Section 5.1.3.5.2.3) value being described 🎀 usage notes: to keep MaxBlockAdditionID as low as possible, small values SHOULD be used 💅
5.1.4.1.17.2. BlockAddIDName Element
id / type: 0x41A4 / string
path: \Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDName
maxOccurs: 1
minver: 4BlockAddIDName is a human-friendly name describing the type of BlockAdditional data, as defined by the associated Block Additional Mapping ⭐
5.1.4.1.17.3. BlockAddIDType Element
id / type / default: 0x41E7 / uinteger / 0
path: \Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDType
minOccurs / maxOccurs: 1 / 1
minver: 4BlockAddIDType stores the registered identifier of the Block Additional Mapping, which defines how the BlockAdditional data should be handled 🧚 usage notes: if BlockAddIDType is 0, the BlockAddIDValue and corresponding BlockAddID values MUST be 1 🌈
5.1.4.1.17.4. BlockAddIDExtraData Element
id / type: 0x41ED / binary
path: \Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDExtraData
maxOccurs: 1
minver: 4BlockAddIDExtraData is extra binary data that BlockAddIDType can use to interpret the BlockAdditional data 💜 the way it's interpreted depends on the BlockAddIDType value and the matching Block Additional Mapping, so it's a whole team effort 👑 🫶
5.1.4.1.18. Name Element 🎀
id / type: 0x536E / utf-8
path: \Segment\Tracks\TrackEntry\Name
maxOccurs: 1Okay bestie, this is just the human-readable name for the track. Cute and simple 🌸
5.1.4.1.19. Language Element 🌍
id / type / default: 0x22B59C / string / eng
path: \Segment\Tracks\TrackEntry\Language
minOccurs / maxOccurs: 1 / 1This one tells you the language of the track, written in the Matroska languages form. Check Section 12 for the language codes 💅 Also, the vibe check: this element MUST be ignored if the LanguageBCP47 element is used in the same TrackEntry. So if LanguageBCP47 is there, Language just steps aside 🫶
5.1.4.1.20. LanguageBCP47 Element 🗣️
id / type: 0x22B59D / string
path: \Segment\Tracks\TrackEntry\LanguageBCP47
maxOccurs: 1
minver: 4Same job as Language, but this one uses the form defined in [RFC5646] (see Section 12 on language codes). ngl, it's the upgraded version ✨ If you use this element, then any Language elements in the same TrackEntry MUST be ignored. Main character energy, no sharing the spotlight 👑
5.1.4.1.21. CodecID Element 🎞️
id / type: 0x86 / string
path: \Segment\Tracks\TrackEntry\CodecID
minOccurs / maxOccurs: 1 / 1
stream copy: True (Section 8)This is an ID that matches up with the codec. For more info, check [MatroskaCodec] 🧚
5.1.4.1.22. CodecPrivate Element 🔒
id / type: 0x63A2 / binary
path: \Segment\Tracks\TrackEntry\CodecPrivate
maxOccurs: 1
stream copy: True (Section 8)Private data that only the codec knows about. Top secret, iykyk 🤫
5.1.4.1.23. CodecName Element 🏷️
id / type: 0x258688 / utf-8
path: \Segment\Tracks\TrackEntry\CodecName
maxOccurs: 1A human-readable string that names the codec. It's giving name tag energy 💖
5.1.4.1.24. AttachmentLink Element 📎
id / type: 0x7446 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\AttachmentLink
maxOccurs: 1
maxver: 3This is the UID of an attachment that the codec uses. Here's the important bit: the value MUST match the FileUID value of an attachment found in this Segment. No matching, no link 🙅♀️
5.1.4.1.25. CodecDelay Element ⏱️
id / type / default: 0x56AA / uinteger / 0
path: \Segment\Tracks\TrackEntry\CodecDelay
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)Okay this one is a whole vibe. CodecDelay is the built-in delay for the codec, measured in Matroska Ticks, which are nanoseconds (see Section 11.1). It's the number of codec samples the decoder throws away during playback. So this timestamp value MUST be subtracted from each frame timestamp to get the timestamp that actually gets played 🎬 The value SHOULD be small, so that tracks muxed with the same actual timestamp end up in the same Cluster. Keep it tidy, bestie 🧹
5.1.4.1.26. SeekPreRoll Element 🌀
id / type / default: 0x56BB / uinteger / 0
path: \Segment\Tracks\TrackEntry\SeekPreRoll
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)After a discontinuity, this tells you how long the data is that the decoder MUST decode before the decoded data is valid. It's also in Matroska Ticks (nanoseconds, see Section 11.1). Warm-up lap, but make it count 🏃♀️💨
5.1.4.1.27. TrackTranslate Element 🗺️
id / type: 0x6624 / master
path: \Segment\Tracks\TrackEntry\TrackTranslateTrackTranslate is the mapping between this TrackEntry and a track value in the given Chapter Codec. The why behind it is so iconic 🦋 Chapter Codecs may need to point at content in a specific track, but they might not know how Matroska identifies tracks. This element and its children add a way to map the internal tracks the Chapter Codec knows about onto the track IDs in Matroska. The payoff: you can remux a file with a Chapter Codec without touching the codec data, only the track mapping. Efficient and slay 💅
5.1.4.1.27.1. TrackTranslateTrackID Element 🔢
id / type: 0x66A5 / binary
path: \Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateTrackID
minOccurs / maxOccurs: 1 / 1This is the binary value that represents this TrackEntry inside the chapter codec data. The format depends on the ChapProcessCodecID you're using, so see Section 5.1.7.1.4.15 🧩
5.1.4.1.27.2. TrackTranslateCodec Element 🎯
id / type: 0x66BF / uinteger
path: \Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateCodec
minOccurs / maxOccurs: 1 / 1This applies to the chapter codec of the given chapter edition(s). See Section 5.1.7.1.4.15 for the details 🌈
defined values: See Table 31. Additional values can be registered in
the "Matroska Chapter Codec IDs" registry defined in Section 27.14.Table 31 has the defined values. Want more? You can register them in the "Matroska Chapter Codec IDs" registry from Section 27.14 ✨
5.1.4.1.27.3. TrackTranslateEditionUID Element 📖
id / type: 0x66FC / uinteger
path: \Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateEditionUIDThis specifies a chapter edition UID that this TrackTranslate applies to 🎀 Usage note: if you don't specify a TrackTranslateEditionUID in the TrackTranslate, then it applies to all chapter editions in the Segment that use the given TrackTranslateCodec. Universal coverage, no notes 🌍
5.1.4.1.28. Video Element 📺
id / type: 0xE0 / master
path: \Segment\Tracks\TrackEntry\Video
maxOccurs: 1Video settings, all in one place 🎥
5.1.4.1.28.1. FlagInterlaced Element 🎞️
id / type / default: 0x9A / uinteger / 0
path: \Segment\Tracks\TrackEntry\Video\FlagInterlaced
minOccurs / maxOccurs: 1 / 1
minver: 2
restrictions: See Table 3.
stream copy: True (Section 8)This tells you whether the video frames in this track are interlaced. Check out the possible values in Table 3 👀
+=======+==============+==========================+
| value | label | definition |
+=======+==============+==========================+
| 0 | undetermined | Unknown status. This |
| | | value SHOULD be avoided. |
+-------+--------------+--------------------------+
| 1 | interlaced | Interlaced frames. |
+-------+--------------+--------------------------+
| 2 | progressive | No interlacing. |
+-------+--------------+--------------------------+
Table 3: FlagInterlaced ValuesValue 0 means undetermined, and it's a SHOULD be avoided situation 🙈 Value 1 is interlaced, and value 2 is progressive, which means no interlacing 💖
5.1.4.1.28.2. FieldOrder Element 🧭
id / type / default: 0x9D / uinteger / 2
path: \Segment\Tracks\TrackEntry\Video\FieldOrder
minOccurs / maxOccurs: 1 / 1
minver: 4
restrictions: See Table 4.
usage notes: If FlagInterlaced is not set to 1, this element MUST be
ignored.
stream copy: True (Section 8)This sets the field ordering of video frames in the track. Real talk, it's only relevant when things are interlaced: if FlagInterlaced is not set to 1, this element MUST be ignored 🫠 The options live in Table 4 🦋
+=======+===============+=========================================+
| value | label | definition |
+=======+===============+=========================================+
| 0 | progressive | Interlaced frames. This value SHOULD |
| | | be avoided; setting FlagInterlaced to 2 |
| | | is sufficient. |
+-------+---------------+-----------------------------------------+
| 1 | tff | Top field displayed first. Top field |
| | | stored first. |
+-------+---------------+-----------------------------------------+
| 2 | undetermined | Unknown field order. This value SHOULD |
| | | be avoided. |
+-------+---------------+-----------------------------------------+
| 6 | bff | Bottom field displayed first. Bottom |
| | | field stored first. |
+-------+---------------+-----------------------------------------+
| 9 | tff | Top field displayed first. Fields are |
| | (interleaved) | interleaved in storage with the top |
| | | line of the top field stored first. |
+-------+---------------+-----------------------------------------+
| 14 | bff | Bottom field displayed first. Fields |
| | (interleaved) | are interleaved in storage with the top |
| | | line of the top field stored first. |
+-------+---------------+-----------------------------------------+
Table 4: FieldOrder ValuesValue 0 is progressive, but that label is confusing: it's listed as interlaced frames, and it SHOULD be avoided. Setting FlagInterlaced to 2 is enough instead 🙃 Value 1 is tff (top field displayed first, top field stored first). Value 2 is undetermined, which SHOULD be avoided too. Value 6 is bff, bottom field displayed first and stored first. Values 9 and 14 are the interleaved versions of tff and bff, so the fields are interleaved in storage with the top line of the top field stored first 🌊
5.1.4.1.28.3. StereoMode Element 👀
id / type / default: 0x53B8 / uinteger / 0
path: \Segment\Tracks\TrackEntry\Video\StereoMode
minOccurs / maxOccurs: 1 / 1
minver: 3
defined values: See Table 5. Additional values can be registered in
the "Matroska Stereo Modes" registry defined in Section 27.7.
stream copy: True (Section 8)This is the Stereo-3D video mode. For more details, see Section 18.10 🥽 The defined values are in Table 5, and you can register extra values in the "Matroska Stereo Modes" registry from Section 27.7 ✨
+=======+===================================================+
| value | label |
+=======+===================================================+
| 0 | mono |
+-------+---------------------------------------------------+
| 1 | side by side (left eye first) |
+-------+---------------------------------------------------+
| 2 | top - bottom (right eye is first) |
+-------+---------------------------------------------------+
| 3 | top - bottom (left eye is first) |
+-------+---------------------------------------------------+
| 4 | checkboard (right eye is first) |
+-------+---------------------------------------------------+
| 5 | checkboard (left eye is first) |
+-------+---------------------------------------------------+
| 6 | row interleaved (right eye is first) |
+-------+---------------------------------------------------+
| 7 | row interleaved (left eye is first) |
+-------+---------------------------------------------------+
| 8 | column interleaved (right eye is first) |
+-------+---------------------------------------------------+
| 9 | column interleaved (left eye is first) |
+-------+---------------------------------------------------+
| 10 | anaglyph (cyan/red) |
+-------+---------------------------------------------------+
| 11 | side by side (right eye first) |
+-------+---------------------------------------------------+
| 12 | anaglyph (green/magenta) |
+-------+---------------------------------------------------+
| 13 | both eyes laced in one Block (left eye is first) |
+-------+---------------------------------------------------+
| 14 | both eyes laced in one Block (right eye is first) |
+-------+---------------------------------------------------+
Table 5: StereoMode ValuesThat's the whole lineup, from mono (0) through to both eyes laced in one Block with the right eye first (14) 😭🎀
5.1.4.1.28.4. AlphaMode Element 🫧
- id / type / default:
0x53C0 / uinteger / 0 - path:
\Segment\Tracks\TrackEntry\Video\AlphaMode - minOccurs / maxOccurs:
1 / 1 - minver:
3 - definition: okay so this one tells you whether the
BlockAdditionalelement withBlockAddIDof"1"holds alpha data, as defined by the Codec Mapping for theCodecID. Undefined values (so anything that isn't 0 or 1) SHOULD NOT be used, bc the known implementations act differently about them 💀 - defined values: See Table 6. Additional values can be registered in the "Matroska Alpha Modes" registry defined in Section 27.8.
- stream copy: True (Section 8)
+=======+=========+============================================+
| value | label | definition |
+=======+=========+============================================+
| 0 | none | The BlockAdditional element with |
| | | BlockAddID of "1" does not exist or SHOULD |
| | | NOT be considered as containing such data. |
+-------+---------+--------------------------------------------+
| 1 | present | The BlockAdditional element with |
| | | BlockAddID of "1" contains alpha channel |
| | | data. |
+-------+---------+--------------------------------------------+
Table 6: AlphaMode Values5.1.4.1.28.5. OldStereoMode Element 🙈
- id / type:
0x53B9 / uinteger - path:
\Segment\Tracks\TrackEntry\Video\OldStereoMode - maxOccurs:
1 - maxver:
2 - definition: a bogus StereoMode value that old versions of [libmatroska] used. Yikes 😭
- restrictions: See Table 7.
- usage notes: This element MUST NOT be used. It was an incorrect value used in libmatroska up to 0.9.0. 🚫
+=======+===========+
| value | label |
+=======+===========+
| 0 | mono |
+-------+-----------+
| 1 | right eye |
+-------+-----------+
| 2 | left eye |
+-------+-----------+
| 3 | both eyes |
+-------+-----------+
Table 7: OldStereoMode
Values5.1.4.1.28.6. PixelWidth Element 🌸
- id / type:
0xB0 / uinteger - range:
not 0 (1-18446744073709551615) - path:
\Segment\Tracks\TrackEntry\Video\PixelWidth - minOccurs / maxOccurs:
1 / 1 - definition: Width of the encoded video frames in pixels.
- stream copy: True (Section 8)
5.1.4.1.28.7. PixelHeight Element 🦋
- id / type:
0xBA / uinteger - range:
not 0 (1-18446744073709551615) - path:
\Segment\Tracks\TrackEntry\Video\PixelHeight - minOccurs / maxOccurs:
1 / 1 - definition: Height of the encoded video frames in pixels.
- stream copy: True (Section 8)
5.1.4.1.28.8. PixelCropBottom Element ✂️
- id / type / default:
0x54AA / uinteger / 0 - path:
\Segment\Tracks\TrackEntry\Video\PixelCropBottom - minOccurs / maxOccurs:
1 / 1 - definition: The number of video pixels to remove at the bottom of the image.
- stream copy: True (Section 8)
5.1.4.1.28.9. PixelCropTop Element ✂️
- id / type / default:
0x54BB / uinteger / 0 - path:
\Segment\Tracks\TrackEntry\Video\PixelCropTop - minOccurs / maxOccurs:
1 / 1 - definition: The number of video pixels to remove at the top of the image.
- stream copy: True (Section 8)
5.1.4.1.28.10. PixelCropLeft Element ✂️
- id / type / default:
0x54CC / uinteger / 0 - path:
\Segment\Tracks\TrackEntry\Video\PixelCropLeft - minOccurs / maxOccurs:
1 / 1 - definition: The number of video pixels to remove on the left of the image.
- stream copy: True (Section 8)
5.1.4.1.28.11. PixelCropRight Element ✂️
- id / type / default:
0x54DD / uinteger / 0 - path:
\Segment\Tracks\TrackEntry\Video\PixelCropRight - minOccurs / maxOccurs:
1 / 1 - definition: The number of video pixels to remove on the right of the image.
- stream copy: True (Section 8)
5.1.4.1.28.12. DisplayWidth Element 📐
- id / type:
0x54B0 / uinteger - range:
not 0 (1-18446744073709551615) - path:
\Segment\Tracks\TrackEntry\Video\DisplayWidth - maxOccurs:
1 - definition: Width of the video frames to display. Applies to the video frame after cropping (
PixelCrop*Elements). - notes: See Table 8.
- stream copy: True (Section 8)
+===========+==================================================+
| attribute | note |
+===========+==================================================+
| default | 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. |
+-----------+--------------------------------------------------+
Table 8: DisplayWidth Implementation Notes5.1.4.1.28.13. DisplayHeight Element 📐
- id / type:
0x54BA / uinteger - range:
not 0 (1-18446744073709551615) - path:
\Segment\Tracks\TrackEntry\Video\DisplayHeight - maxOccurs:
1 - definition: Height of the video frames to display. Applies to the video frame after cropping (
PixelCrop*Elements). - notes: See Table 9.
- stream copy: True (Section 8)
+===========+===================================================+
| attribute | note |
+===========+===================================================+
| default | 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. |
+-----------+---------------------------------------------------+
Table 9: DisplayHeight Implementation Notes5.1.4.1.28.14. DisplayUnit Element 🧚
- id / type / default:
0x54B2 / uinteger / 0 - path:
\Segment\Tracks\TrackEntry\Video\DisplayUnit - minOccurs / maxOccurs:
1 / 1 - definition: How DisplayWidth and DisplayHeight are interpreted.
- defined values: See Table 10. Additional values can be registered in the "Matroska Display Units" registry defined in Section 27.9.
+=======+======================+
| value | label |
+=======+======================+
| 0 | pixels |
+-------+----------------------+
| 1 | centimeters |
+-------+----------------------+
| 2 | inches |
+-------+----------------------+
| 3 | display aspect ratio |
+-------+----------------------+
| 4 | unknown |
+-------+----------------------+
Table 10: DisplayUnit Values5.1.4.1.28.15. UncompressedFourCC Element 🎞️
- id / type:
0x2EB524 / binary - length:
4 - path:
\Segment\Tracks\TrackEntry\Video\UncompressedFourCC - minOccurs / maxOccurs: See Table 11 /
1 - definition: Specifies the uncompressed pixel format used for the Track's data as a FourCC. This value is similar in scope to the
biCompressionvalue 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]. No official list, so we're all just vibing with the common ones 🌈 - notes: See Table 11.
- stream copy: True (Section 8)
+===========+==============================================+
| attribute | note |
+===========+==============================================+
| minOccurs | UncompressedFourCC MUST be set (minOccurs=1) |
| | in TrackEntry when the CodecID element of |
| | the TrackEntry is set to "V_UNCOMPRESSED". |
+-----------+----------------------------------------------+
Table 11: UncompressedFourCC Implementation Notes5.1.4.1.28.16. Colour Element 🎨
- id / type:
0x55B0 / master - path:
\Segment\Tracks\TrackEntry\Video\Colour - maxOccurs:
1 - minver:
4 - definition: Settings describing the color format.
- stream copy: True (Section 8)
5.1.4.1.28.17. MatrixCoefficients Element 🌈
- id / type / default:
0x55B1 / uinteger / 2 - path:
\Segment\Tracks\TrackEntry\Video\Colour\MatrixCoefficients - minOccurs / maxOccurs:
1 / 1 - minver:
4 - definition: 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].
- restrictions: See Table 12.
- stream copy: True (Section 8)
+=======+=======================================+
| value | label |
+=======+=======================================+
| 0 | Identity |
+-------+---------------------------------------+
| 1 | ITU-R BT.709 |
+-------+---------------------------------------+
| 2 | unspecified |
+-------+---------------------------------------+
| 3 | reserved |
+-------+---------------------------------------+
| 4 | US FCC 73.682 |
+-------+---------------------------------------+
| 5 | ITU-R BT.470BG |
+-------+---------------------------------------+
| 6 | SMPTE 170M |
+-------+---------------------------------------+
| 7 | SMPTE 240M |
+-------+---------------------------------------+
| 8 | YCoCg |
+-------+---------------------------------------+
| 9 | BT2020 Non-constant Luminance |
+-------+---------------------------------------+
| 10 | BT2020 Constant Luminance |
+-------+---------------------------------------+
| 11 | SMPTE ST 2085 |
+-------+---------------------------------------+
| 12 | Chroma-derived Non-constant Luminance |
+-------+---------------------------------------+
| 13 | Chroma-derived Constant Luminance |
+-------+---------------------------------------+
| 14 | ITU-R BT.2100-0 |
+-------+---------------------------------------+
Table 12: MatrixCoefficients Values5.1.4.1.28.18. BitsPerChannel Element 🍓
- id / type / default:
0x55B2 / uinteger / 0 - path:
\Segment\Tracks\TrackEntry\Video\Colour\BitsPerChannel - minOccurs / maxOccurs:
1 / 1 - minver:
4 - definition: Number of decoded bits per channel. A value of 0 indicates that the BitsPerChannel is unspecified.
- stream copy: True (Section 8)
5.1.4.1.28.19. ChromaSubsamplingHorz Element 💖
id / type: 0x55B3 / uinteger
path: \Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingHorz
maxOccurs: 1
minver: 4
stream copy: True (Section 8)okay so ChromaSubsamplingHorz counts how many pixels get dropped from the Cr and Cb channels for every pixel that isn't dropped horizontally. 🎀 For example, with 4:2:0 chroma subsampling, ChromaSubsamplingHorz SHOULD be set to 1 ✨
5.1.4.1.28.20. ChromaSubsamplingVert Element 🌸
id / type: 0x55B4 / uinteger
path: \Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingVert
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this one is the vertical version of the same vibe 🦋 It counts how many pixels get dropped from the Cr and Cb channels for every pixel that isn't dropped vertically. Same example energy: with 4:2:0 chroma subsampling, ChromaSubsamplingVert SHOULD be set to 1 💅
5.1.4.1.28.21. CbSubsamplingHorz Element 🧚
id / type: 0x55B5 / uinteger
path: \Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingHorz
maxOccurs: 1
minver: 4
stream copy: True (Section 8)ngl this one is a little plot twist 🙈 CbSubsamplingHorz counts the pixels dropped from the Cb channel only, for every pixel not dropped horizontally. It's additive with ChromaSubsamplingHorz, so the two stack. For 4:2:1 chroma subsampling, ChromaSubsamplingHorz SHOULD be set to 1, and CbSubsamplingHorz SHOULD be set to 1 💜
5.1.4.1.28.22. CbSubsamplingVert Element 🍓
id / type: 0x55B6 / uinteger
path: \Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingVert
maxOccurs: 1
minver: 4
stream copy: True (Section 8)the vertical sibling of the last one 🌈 It counts the pixels dropped from the Cb channel for every pixel not dropped vertically, and it's additive with ChromaSubsamplingVert. Stacking energy, periodt ✨
5.1.4.1.28.23. ChromaSitingHorz Element 🎀
id / type / default: 0x55B7 / uinteger / 0
path: \Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingHorz
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)this one tells you how chroma gets subsampled horizontally 🦋 The defined values are in Table 13 below. You can also register extra values in the "Matroska Horizontal Chroma Sitings" registry from Section 27.10 if you need them 💖
+=======+=================+
| value | label |
+=======+=================+
| 0 | unspecified |
+-------+-----------------+
| 1 | left collocated |
+-------+-----------------+
| 2 | half |
+-------+-----------------+
Table 13:
ChromaSitingHorz Values5.1.4.1.28.24. ChromaSitingVert Element 🌷
id / type / default: 0x55B8 / uinteger / 0
path: \Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingVert
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)the vertical version of chroma siting 🌸 Check Table 14 for the defined values. More can be registered in the "Matroska Vertical Chroma Sitings" registry from Section 27.11 ✨
+=======+================+
| value | label |
+=======+================+
| 0 | unspecified |
+-------+----------------+
| 1 | top collocated |
+-------+----------------+
| 2 | half |
+-------+----------------+
Table 14:
ChromaSitingVert
Values5.1.4.1.28.25. Color Range Element 🌈
id / type / default: 0x55B9 / uinteger / 0
path: \Segment\Tracks\TrackEntry\Video\Colour\Range
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)this is all about clipping of the color ranges 💅 Table 15 lists the defined values. More can be added to the "Matroska Color Ranges" registry from Section 27.12 🫶
+=======+=========================================================+
| value | label |
+=======+=========================================================+
| 0 | unspecified |
+-------+---------------------------------------------------------+
| 1 | broadcast range |
+-------+---------------------------------------------------------+
| 2 | full range (no clipping) |
+-------+---------------------------------------------------------+
| 3 | defined by MatrixCoefficients / TransferCharacteristics |
+-------+---------------------------------------------------------+
Table 15: Range Values5.1.4.1.28.26. TransferCharacteristics Element 👑
id / type / default: 0x55BA / uinteger / 2
path: \Segment\Tracks\TrackEntry\Video\Colour\TransferCharacteristic
s
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)this one describes the transfer characteristics of the video 🧚 To keep things clear, the values and their meanings are borrowed from Table 3 of [ITU-H.273]. The restrictions are in Table 16 ✨
+=======+=======================================+
| value | label |
+=======+=======================================+
| 0 | reserved |
+-------+---------------------------------------+
| 1 | ITU-R BT.709 |
+-------+---------------------------------------+
| 2 | unspecified |
+-------+---------------------------------------+
| 3 | reserved2 |
+-------+---------------------------------------+
| 4 | Gamma 2.2 curve - BT.470M |
+-------+---------------------------------------+
| 5 | Gamma 2.8 curve - BT.470BG |
+-------+---------------------------------------+
| 6 | SMPTE 170M |
+-------+---------------------------------------+
| 7 | SMPTE 240M |
+-------+---------------------------------------+
| 8 | Linear |
+-------+---------------------------------------+
| 9 | Log |
+-------+---------------------------------------+
| 10 | Log Sqrt |
+-------+---------------------------------------+
| 11 | IEC 61966-2-4 |
+-------+---------------------------------------+
| 12 | ITU-R BT.1361 Extended Colour Gamut |
+-------+---------------------------------------+
| 13 | IEC 61966-2-1 |
+-------+---------------------------------------+
| 14 | ITU-R BT.2020 10 bit |
+-------+---------------------------------------+
| 15 | ITU-R BT.2020 12 bit |
+-------+---------------------------------------+
| 16 | ITU-R BT.2100 Perceptual Quantization |
+-------+---------------------------------------+
| 17 | SMPTE ST 428-1 |
+-------+---------------------------------------+
| 18 | ARIB STD-B67 (HLG) |
+-------+---------------------------------------+
Table 16: TransferCharacteristics Values5.1.4.1.28.27. Primaries Element 💖
id / type / default: 0x55BB / uinteger / 2
path: \Segment\Tracks\TrackEntry\Video\Colour\Primaries
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)the color primaries of the video, bestie 🎨 Their values and meanings are adopted from Table 2 of [ITU-H.273] so everyone's on the same page. The restrictions are in Table 17 🦋
+=======+========================================+
| value | label |
+=======+========================================+
| 0 | reserved |
+-------+----------------------------------------+
| 1 | ITU-R BT.709 |
+-------+----------------------------------------+
| 2 | unspecified |
+-------+----------------------------------------+
| 3 | reserved2 |
+-------+----------------------------------------+
| 4 | ITU-R BT.470M |
+-------+----------------------------------------+
| 5 | ITU-R BT.470BG - BT.601 625 |
+-------+----------------------------------------+
| 6 | ITU-R BT.601 525 - SMPTE 170M |
+-------+----------------------------------------+
| 7 | SMPTE 240M |
+-------+----------------------------------------+
| 8 | FILM |
+-------+----------------------------------------+
| 9 | ITU-R BT.2020 |
+-------+----------------------------------------+
| 10 | SMPTE ST 428-1 |
+-------+----------------------------------------+
| 11 | SMPTE RP 432-2 |
+-------+----------------------------------------+
| 12 | SMPTE EG 432-2 |
+-------+----------------------------------------+
| 22 | EBU Tech. 3213-E - JEDEC P22 phosphors |
+-------+----------------------------------------+
Table 17: Primaries Values5.1.4.1.28.28. MaxCLL Element 🔥
id / type: 0x55BC / uinteger
path: \Segment\Tracks\TrackEntry\Video\Colour\MaxCLL
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this is the Maximum Content Light Level 💡 It's the brightness of a single pixel, measured in candelas per square meter (cd/m^2). Very bright, very iconic ✨
5.1.4.1.28.29. MaxFALL Element 🌟
id / type: 0x55BD / uinteger
path: \Segment\Tracks\TrackEntry\Video\Colour\MaxFALL
maxOccurs: 1
minver: 4
stream copy: True (Section 8)the sibling of MaxCLL 🌙 This one is the Maximum Frame-Average Light Level, which is the brightness of a single full frame, also in candelas per square meter (cd/m^2). MaxCLL checks one pixel, MaxFALL checks the whole frame, lowkey genius 🧠💜
5.1.4.1.28.30. MasteringMetadata Element 🎬
id / type: 0x55D0 / master
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this is a master element that holds the SMPTE 2086 mastering data 🎀 Think of it as the color-grading diary for the video 📖✨
5.1.4.1.28.31. PrimaryRChromaticityX Element 🦩
id / type: 0x55D1 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim
aryRChromaticityX
maxOccurs: 1
minver: 4
stream copy: True (Section 8)okay this one is the red X chromaticity coordinate, as defined by [CIE-1931] 🔴 It lives inside MasteringMetadata and its value sits in the range 0x0p+0 to 0x1p+0 💖
5.1.4.1.28.32. PrimaryRChromaticityY Element 💖
id / type: 0x55D2 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim
aryRChromaticityY
maxOccurs: 1
minver: 4
stream copy: True (Section 8)okay so this one is the red Y chromaticity coordinate 🔴✨ It's defined using [CIE-1931], and it only shows up once per MasteringMetadata. It's giving precision!! 💅
5.1.4.1.28.33. PrimaryGChromaticityX Element 🍀
id / type: 0x55D3 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim
aryGChromaticityX
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this is the green X chromaticity coordinate, also defined by [CIE-1931] 💚 Same deal as red: one per MasteringMetadata, and it's the green twin of the red one. Iconic pairing 🫶
5.1.4.1.28.34. PrimaryGChromaticityY Element 🌿
id / type: 0x55D4 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim
aryGChromaticityY
maxOccurs: 1
minver: 4
stream copy: True (Section 8)and the green Y chromaticity coordinate completes the green pair 🍏 It's also measured per [CIE-1931], and it's allowed exactly once. No extra copies, bestie 🙅♀️
5.1.4.1.28.35. PrimaryBChromaticityX Element 💙
id / type: 0x55D5 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim
aryBChromaticityX
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this is the blue X chromaticity coordinate, using [CIE-1931] 🦋 Blue is the last of the three primaries on the X side, so it's giving main character energy 👑
5.1.4.1.28.36. PrimaryBChromaticityY Element 🫐
id / type: 0x55D6 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim
aryBChromaticityY
maxOccurs: 1
minver: 4
stream copy: True (Section 8)and the blue Y chromaticity coordinate finishes off the RGB primaries 🌈 Same [CIE-1931] reference, same once-only rule. The three primaries are now fully accounted for, so we're cooking 🔥
5.1.4.1.28.37. WhitePointChromaticityX Element ☁️
id / type: 0x55D7 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Whit
ePointChromaticityX
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this one is the white X chromaticity coordinate 🤍 Also measured per [CIE-1931], also once only. White point gets its own pair because it's its own thing, and honestly it's the vibe that sets everything else off ✨
5.1.4.1.28.38. WhitePointChromaticityY Element 🕊️
id / type: 0x55D8 / float
range: 0x0p+0-0x1p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Whit
ePointChromaticityY
maxOccurs: 1
minver: 4
stream copy: True (Section 8)and the white Y chromaticity coordinate is the other half of the white point pair 🫧 It's [CIE-1931] again, and it shows up at most once. Two numbers, one white, zero drama 💅
5.1.4.1.28.39. LuminanceMax Element ☀️
id / type: 0x55D9 / float
range: >= 0x0p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Lumi
nanceMax
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this is the maximum luminance, and it's measured in candelas per square meter (cd/m^2) 💡 It can't be negative (it's >= 0x0p+0), and it's allowed once. Bright, bold, and literally the brightest thing in the group chat 🌟
5.1.4.1.28.40. LuminanceMin Element 🌙
id / type: 0x55DA / float
range: >= 0x0p+0
path: \Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Lumi
nanceMin
maxOccurs: 1
minver: 4
stream copy: True (Section 8)and this is the minimum luminance, also in candelas per square meter (cd/m^2) 🌑 Same rules as LuminanceMax: non-negative, once only. It's the dark-side partner, and honestly the contrast between the two is so iconic 🖤
5.1.4.1.28.41. Projection Element 🔮
id / type: 0x7670 / master
path: \Segment\Tracks\TrackEntry\Video\Projection
maxOccurs: 1
minver: 4
stream copy: True (Section 8)okay so Projection is the master element that holds the video projection details 🌐 It's used when you're rendering spherical or VR videos, and it's also used when you need to flip a video horizontally or vertically 🙃 Think of it as the little container that keeps all the projection stuff tidy, no cap 🎀
5.1.4.1.28.42. ProjectionType Element 🗺️
id / type / default: 0x7671 / uinteger / 0
path: \Segment\Tracks\TrackEntry\Video\Projection\ProjectionType
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)this one describes which projection is used for this video track 🧭 It's required exactly once, and the default is 0. The allowed values are listed in Table 18 below. If you need more values, they can be registered in the "Matroska Projection Types" registry defined in Section 27.15, so the list isn't frozen forever ✨
+=======+=================+
| value | label |
+=======+=================+
| 0 | rectangular |
+-------+-----------------+
| 1 | equirectangular |
+-------+-----------------+
| 2 | cubemap |
+-------+-----------------+
| 3 | mesh |
+-------+-----------------+
Table 18:
ProjectionType Values5.1.4.1.28.43. ProjectionPrivate Element 🧩
id / type: 0x7672 / binary
path: \Segment\Tracks\TrackEntry\Video\Projection\ProjectionPrivate
maxOccurs: 1
minver: 4
stream copy: True (Section 8)this is the private data that only applies to one specific projection 🔐 Whether it's needed (and what goes in it) depends on which ProjectionType you picked, so here's the breakdown, bestie:
- If ProjectionType equals 0 (rectangular), then this element MUST NOT be present. 🙅♀️
- If ProjectionType equals 1 (equirectangular), then this element MUST be present and contain the same binary data that would be stored inside an ISOBMFF Equirectangular Projection Box ("equi"). 🌍
- If ProjectionType equals 2 (cubemap), then this element MUST be present and contain the same binary data that would be stored 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"). 🕸️
usage note: the ISOBMFF box size and FourCC fields are NOT part of this binary data, but the FullBox version and flag fields ARE. The point is to skip the duplicate framing info while still keeping the versioning and semantics matching between the two container formats 💜
5.1.4.1.28.44. ProjectionPoseYaw Element 🔄
id / type / default: 0x7673 / float / 0x0p+0
range: >= -0xB4p+0, <= 0xB4p+0
path: \Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseYaw
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)this is a yaw rotation for the projection 🎡 The value is a clockwise rotation, in degrees, around the up vector. It has to be applied before any ProjectionPosePitch or ProjectionPoseRoll rotations, so the order matters, babe 🧠 The value MUST be in the -180 to 180 degree range, both inclusive.
Setting ProjectionPoseYaw to 180 or -180 degrees, with ProjectionPoseRoll and ProjectionPosePitch both set to 0 degrees, flips the image horizontally 🪞✨
5.1.4.1.28.45. ProjectionPosePitch Element 🎢
id / type / default: 0x7674 / float / 0x0p+0
range: >= -0x5Ap+0, <= 0x5Ap+0
path: \Segment\Tracks\TrackEntry\Video\Projection\ProjectionPosePitc
h
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)this is the pitch rotation 🌊 The value is a counter-clockwise rotation, in degrees, around the right vector. It has to come after the ProjectionPoseYaw rotation and before the ProjectionPoseRoll rotation, so it's basically the middle child of the rotation trio 👧 The value MUST be in the -90 to 90 degree range, both inclusive.
5.1.4.1.28.46. ProjectionPoseRoll Element 🌀
id / type / default: 0x7675 / float / 0x0p+0
range: >= -0xB4p+0, <= 0xB4p+0
path: \Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseRoll
minOccurs / maxOccurs: 1 / 1
minver: 4
stream copy: True (Section 8)last but not least, this is the roll rotation 🎠 The value is a counter-clockwise rotation, in degrees, around the forward vector. It has to be applied after ProjectionPoseYaw and ProjectionPosePitch, so it always comes last in the line-up 🏁 The value MUST be in the -180 to 180 degree range, both inclusive.
Setting ProjectionPoseRoll to 180 or -180 degrees, with ProjectionPoseYaw at 180 or -180 degrees and ProjectionPosePitch at 0 degrees, flips the image vertically 🙃 Setting ProjectionPoseRoll to 180 or -180 degrees, with ProjectionPoseYaw and ProjectionPosePitch both at 0 degrees, flips the image horizontally AND vertically. Double flip, double slay 💖
5.1.4.1.29. Audio Element 🎧
id / type: 0xE1 / master
path: \Segment\Tracks\TrackEntry\Audio
maxOccurs: 1this is the Audio master element 🎶 It holds the audio settings for the track, and it can only show up once. Everything sound-related lives in here, periodt 🔊
5.1.4.1.29.1. SamplingFrequency Element 🎵
id / type / default: 0xB5 / float / 0x1.f4p+12
range: > 0x0p+0
path: \Segment\Tracks\TrackEntry\Audio\SamplingFrequency
minOccurs / maxOccurs: 1 / 1
stream copy: True (Section 8)this is the sampling frequency in Hz 📈 It's required exactly once, it has to be greater than zero, and the default is 0x1.f4p+12. It's the core number for how many samples per second you're getting, so it's kind of a big deal ngl 💅
5.1.4.1.29.2. OutputSamplingFrequency Element 🎚️
id / type: 0x78B5 / float
range: > 0x0p+0
path: \Segment\Tracks\TrackEntry\Audio\OutputSamplingFrequency
maxOccurs: 1
notes: See Table 19.this is the real output sampling frequency in Hz that gets used for Spectral Band Replication (SBR) techniques 🪄 It has to be greater than zero, it's allowed once, and the notes are in Table 19 below 👇
+===========+======================================================+
| attribute | note |
+===========+======================================================+
| default | The default value for OutputSamplingFrequency of the |
| | same TrackEntry is equal to the SamplingFrequency. |
+-----------+------------------------------------------------------+
Table 19: OutputSamplingFrequency Implementation Notes5.1.4.1.29.3. Channels Element 🔊
id / type / default: 0x9F / uinteger / 1
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\Audio\Channels
minOccurs / maxOccurs: 1 / 1
stream copy: True (Section 8)this is the number of channels in the track 🎛️ It's required exactly once, the default is 1, and it can be anything from 1 up to 18446744073709551615, just not 0. Mono, stereo, or something bigger, it's all valid, besties 🫶
5.1.4.1.29.4. BitDepth Element 🎼
id / type: 0x6264 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\Audio\BitDepth
maxOccurs: 1
stream copy: True (Section 8)this is the bits per sample, and it's mostly used for PCM 🎙️ It's allowed once, and the value can be anything from 1 up to 18446744073709551615, just not 0 ✨
5.1.4.1.30. TrackOperation Element 🧪
id / type: 0xE2 / master
path: \Segment\Tracks\TrackEntry\TrackOperation
maxOccurs: 1
minver: 3
stream copy: True (Section 8)this is the operation that needs to be applied to tracks to create this virtual track 🪄 It's a master element that shows up at most once. If you want the full scoop, check out Section 18.8 💕
5.1.4.1.30.1. TrackCombinePlanes Element 🧱
id / type: 0xE3 / master
path: \Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes
maxOccurs: 1
minver: 3
stream copy: True (Section 8)this is the list of all the video plane tracks that get combined to make this 3D track 🎲 It's another master, allowed once, and it's the container that holds the TrackPlane entries (we're getting there, I promise) 💜
5.1.4.1.30.2. TrackPlane Element 🪟
id / type: 0xE4 / master
path: \Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\T
rackPlane
minOccurs: 1
minver: 3
stream copy: True (Section 8)this is one video plane track that needs to be combined to create this 3D track 🧚 It's required at least once (minOccurs: 1), so every combined 3D track has to have at least one of these in the mix 🌸
5.1.4.1.30.3. TrackPlaneUID Element 🆔
id / type: 0xE5 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\T
rackPlane\TrackPlaneUID
minOccurs / maxOccurs: 1 / 1
minver: 3
stream copy: True (Section 8)last one in this batch! This is the TrackUID number of the track representing the plane 🪪 It's required exactly once, and the value can be anything from 1 up to 18446744073709551615, not 0. It's basically the ID card that tells you which track is the plane ✨
5.1.4.1.30.4. TrackPlaneType Element 👀🦋
Okay bestie, this is the "which eye is this?" element 🥹 It tells you what kind of plane the track is. Here are the specs:
id / type: 0xE6 / uinteger
path: \Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\T
rackPlane\TrackPlaneType
minOccurs / maxOccurs: 1 / 1
minver: 3
definition: The kind of plane this track corresponds to.
defined values: See Table 20. Additional values can be registered
in the "Matroska Track Plane Types" registry defined in
Section 27.17.
stream copy: True (Section 8)The possible values are in Table 20 🌸 and you can register new ones in the "Matroska Track Plane Types" registry from Section 27.17 if you need them ✨
+=======+============+
| value | label |
+=======+============+
| 0 | left eye |
+-------+------------+
| 1 | right eye |
+-------+------------+
| 2 | background |
+-------+------------+
Table 20:
TrackPlaneType Values5.1.4.1.30.5. TrackJoinBlocks Element 🧚
This one is basically the guest list 💅 It holds every track whose Blocks need to get combined to make this virtual track. Super cute and very organized 🎀
id / type: 0xE9 / master
path: \Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks
maxOccurs: 1
minver: 3
definition: Contains the list of all tracks whose Blocks need to be
combined to create this virtual track.
stream copy: True (Section 8)5.1.4.1.30.6. TrackJoinUID Element 🍓
Each guest on that list gets a TrackJoinUID 🫶 It's the TrackUID number of a track whose blocks get used to build the virtual track. The value can be anything from 1 up to 18446744073709551615, so 0 is a no-go 🙈
id / type: 0xED / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks\Trac
kJoinUID
minOccurs: 1
minver: 3
definition: The TrackUID number of a track whose blocks are used to
create this virtual track.
stream copy: True (Section 8)5.1.4.1.31. ContentEncodings Element 🔐
Okay, ContentEncodings is the settings hub for all the content-encoding stuff, like compression or encryption 💜 It's a master element and you can only have one of these per TrackEntry (maxOccurs is 1). Here's the metadata:
id / type: 0x6D80 / master
path: \Segment\Tracks\TrackEntry\ContentEncodings
maxOccurs: 1
definition: Settings for several content encoding mechanisms like
compression or encryption.
stream copy: True (Section 8)5.1.4.1.31.1. ContentEncoding Element 🌈
Each ContentEncoding holds the settings for one encoding, like one compression or one encryption step. You need at least one of these, since minOccurs is 1 ✨
id / type: 0x6240 / master
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding
minOccurs: 1
definition: Settings for one content encoding like compression or
encryption.
stream copy: True (Section 8)5.1.4.1.31.2. ContentEncodingOrder Element 🔢
This is the ordering vibe check 💅 It says the order to apply each ContentEncoding in ContentEncodings. The decoder or demuxer MUST start with the ContentEncoding that has the highest ContentEncodingOrder and then work its way down to the one with the lowest. Every ContentEncodingOrder MUST be unique within the ContentEncodings of that TrackEntry, so no twins allowed 👯
id / type / default: 0x5031 / uinteger / 0
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncodingOrder
minOccurs / maxOccurs: 1 / 1
definition: 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.
stream copy: True (Section 8)5.1.4.1.31.3. ContentEncodingScope Element 🎯
This one is a bit field that tells you which elements got modified by this encoding 🧁 The values are big-endian and can be OR'ed together. The range is not 0 (0x1-0x8000000000000000), and the defined values are in Table 21 🦋 More can be registered in the "Matroska Content Encoding Scopes" registry from Section 27.5.
id / type / default: 0x5032 / uinteger / 1
range: not 0 (0x1-0x8000000000000000)
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncodingScope
minOccurs / maxOccurs: 1 / 1
definition: A bit field that describes which elements have been
modified in this way. Values (big-endian) can be OR'ed.
defined values: See Table 21. Additional values can be registered
in the "Matroska Content Encoding Scopes" registry defined in
Section 27.5.
stream copy: True (Section 8)
+=======+=========+============================================+
| value | label | definition |
+=======+=========+============================================+
| 0x1 | Block | All frame contents, excluding lacing data. |
+-------+---------+--------------------------------------------+
| 0x2 | Private | The track's CodecPrivate data. |
+-------+---------+--------------------------------------------+
| 0x4 | Next | The next ContentEncoding (next |
| | | ContentEncodingOrder; the data inside |
| | | ContentCompression and/or |
| | | ContentEncryption). This value SHOULD NOT |
| | | be used, as it's not supported by players. |
+-------+---------+--------------------------------------------+
Table 21: ContentEncodingScope Values5.1.4.1.31.4. ContentEncodingType Element 🧩
This is the "what kind of transformation is it?" element ✨ It describes the kind of transformation applied. The defined values are in Table 22, and extra ones can be registered in the "Matroska Content Encoding Types" registry from Section 27.6 🌸
id / type / default: 0x5033 / uinteger / 0
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncodingType
minOccurs / maxOccurs: 1 / 1
definition: A value describing the kind of transformation that is
applied.
defined values: See Table 22. Additional values can be registered
in the "Matroska Content Encoding Types" registry defined in
Section 27.6.
stream copy: True (Section 8)
+=======+=============+
| value | label |
+=======+=============+
| 0 | Compression |
+-------+-------------+
| 1 | Encryption |
+-------+-------------+
Table 22:
ContentEncodingType
Values5.1.4.1.31.5. ContentCompression Element 🗜️
Here's the compression settings element 💖 It MUST be present if ContentEncodingType is 0, and it MUST be absent otherwise. Also, each block MUST be decompressable even when no previous block is available, so seeking doesn't get blocked 🦋
id / type: 0x5034 / master
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentCompression
maxOccurs: 1
definition: Settings describing the compression used. 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.
stream copy: True (Section 8)5.1.4.1.31.6. ContentCompAlgo Element 📦
This is the compression algorithm picker 💅 The defined values are in Table 23, and you can register more in the "Matroska Compression Algorithms" registry from Section 27.2.
Now the spicy part 🌶️ Compression methods "1" (bzlib) and "2" (lzo1x) don't have proper format documentation, which limits what implementers can do. Also, because of licensing conflicts on commonly available libraries, "2" (lzo1x) doesn't have widespread interoperability. So a Matroska Writer SHOULD NOT use these by default. A Matroska Reader MAY support methods "1" and "2", and it SHOULD support the other methods 💜
id / type / default: 0x4254 / uinteger / 0
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentCompression\ContentCompAlgo
minOccurs / maxOccurs: 1 / 1
definition: The compression algorithm used.
defined values: See Table 23. Additional values can be registered
in the "Matroska Compression Algorithms" registry defined in
Section 27.2.
usage notes: 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" and SHOULD support other methods.
stream copy: True (Section 8)
+=======+===========+========================================+
| value | label | definition |
+=======+===========+========================================+
| 0 | zlib | zlib compression [RFC1950]. |
+-------+-----------+----------------------------------------+
| 1 | bzlib | bzip2 compression [BZIP2] SHOULD NOT |
| | | be used; see usage notes. |
+-------+-----------+----------------------------------------+
| 2 | lzo1x | Lempel-Ziv-Oberhumer compression [LZO] |
| | | SHOULD NOT be used; see usage notes. |
+-------+-----------+----------------------------------------+
| 3 | Header | Octets in ContentCompSettings |
| | Stripping | (Section 5.1.4.1.31.7) have been |
| | | stripped from each frame. |
+-------+-----------+----------------------------------------+
Table 23: ContentCompAlgo Values5.1.4.1.31.7. ContentCompSettings Element ⚙️
These are the little extras the decompressor might need 🎁 For Header Stripping (ContentCompAlgo=3), it holds the bytes that were removed from the beginning of each frame of the track. Very specific, very iconic 👑
id / type: 0x4255 / binary
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentCompression\ContentCompSettings
maxOccurs: 1
definition: Settings that might be needed by the decompressor. For
Header Stripping (ContentCompAlgo=3), the bytes that were removed
from the beginning of each frame of the track.
stream copy: True (Section 8)5.1.4.1.31.8. ContentEncryption Element 🔒
This is the encryption settings element 🫶 It MUST be present if ContentEncodingType is 1 (encryption), and it MUST be ignored otherwise. A Matroska Player MAY support encryption.
id / type: 0x5035 / master
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption
maxOccurs: 1
definition: 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.
stream copy: True (Section 8)5.1.4.1.31.9. ContentEncAlgo Element 🗝️
This picks the encryption algorithm 💅 The defined values are in Table 24, and more can be registered in the "Matroska Encryption Algorithms" registry from Section 27.3. Some of these have warnings attached, so read the table closely 👀
id / type / default: 0x47E1 / uinteger / 0
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentEncAlgo
minOccurs / maxOccurs: 1 / 1
definition: The encryption algorithm used.
defined values: See Table 24. Additional values can be registered
in the "Matroska Encryption Algorithms" registry defined in
Section 27.3.
stream copy: True (Section 8)
+=======+===========+============================================+
| value | label | definition |
+=======+===========+============================================+
| 0 | Not | The data are not encrypted. |
| | encrypted | |
+-------+-----------+--------------------------------------------+
| 1 | DES | Data Encryption Standard (DES) [FIPS46-3]. |
| | | This value SHOULD be avoided. |
+-------+-----------+--------------------------------------------+
| 2 | 3DES | Triple Data Encryption Algorithm |
| | | [SP800-67]. This value SHOULD be avoided. |
+-------+-----------+--------------------------------------------+
| 3 | Twofish | Twofish Encryption Algorithm [Twofish]. |
+-------+-----------+--------------------------------------------+
| 4 | Blowfish | Blowfish Encryption Algorithm [Blowfish]. |
| | | This value SHOULD be avoided. |
+-------+-----------+--------------------------------------------+
| 5 | AES | Advanced Encryption Standard (AES) |
| | | [FIPS197]. |
+-------+-----------+--------------------------------------------+
Table 24: ContentEncAlgo Values5.1.4.1.31.10. ContentEncKeyID Element 🔑
Last one for this batch! 🎉 For public key algorithms, this is the ID of the public key that the data was encrypted with. It's binary, maxOccurs is 1, and it gets copied on stream copy (Section 8) 💖
id / type: 0x47E2 / binary
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentEncKeyID
maxOccurs: 1
definition: For public key algorithms, the ID of the public key that
the data was encrypted with.
stream copy: True (Section 8)okay bestie, picking up right where we left off with the ContentEncAESSettings stuff 🦋✨
5.1.4.1.31.11. ContentEncAESSettings Element 🎀
5.1.4.1.31.11. ContentEncAESSettings Element
okay so this one is the settings master for the encryption algorithm, and it's giving very "describe your cipher" energy 💅
id / type: 0x47E7 / master
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentEncAESSettings
maxOccurs: 1
minver: 4
definition: Settings describing the encryption algorithm used.
notes: See Table 25.
stream copy: True (Section 8)the big rule here is that this element is only for AES, so if ContentEncAlgo isn't AES (5), it MUST NOT be set (maxOccurs=0) 🙈 no sneaking it in for other algorithms, periodt 💀
+===========+=================================================+
| attribute | note |
+===========+=================================================+
| maxOccurs | ContentEncAESSettings MUST NOT be set |
| | (maxOccurs=0) if ContentEncAlgo is not AES (5). |
+-----------+-------------------------------------------------+
Table 25: ContentEncAESSettings Implementation Notes5.1.4.1.31.12. AESSettingsCipherMode Element
this is where you pick how the AES cipher runs, and there are two options on the menu 🌸
id / type: 0x47E8 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentEncAESSettings\AESSettingsCipherMode
minOccurs / maxOccurs: 1 / 1
minver: 4
definition: The AES cipher mode used in the encryption.
defined values: See Table 26. Additional values can be registered
in the "Matroska AES Cipher Modes" registry defined in
Section 27.4.
notes: See Table 27.
stream copy: True (Section 8)so the value has to be anything from 1 up to 18446744073709551615 (not 0, sorry zero, you're not invited 🙅♀️), and the defined ones are in Table 26. new modes can also get registered in the "Matroska AES Cipher Modes" registry in Section 27.4 🧚
+=======+=========+===================================+
| value | label | definition |
+=======+=========+===================================+
| 1 | AES-CTR | Counter [SP800-38A] |
+-------+---------+-----------------------------------+
| 2 | AES-CBC | Cipher Block Chaining [SP800-38A] |
+-------+---------+-----------------------------------+
Table 26: AESSettingsCipherMode Valuesvalue 1 is AES-CTR (Counter), and value 2 is AES-CBC (Cipher Block Chaining), both pointing to [SP800-38A] 🍓
+===========+=================================================+
| attribute | note |
+===========+=================================================+
| maxOccurs | AESSettingsCipherMode MUST NOT be set |
| | (maxOccurs=0) if ContentEncAlgo is not AES (5). |
+-----------+-------------------------------------------------+
Table 27: AESSettingsCipherMode Implementation Notesand yep, same deal as the parent: if ContentEncAlgo isn't AES (5), this one MUST NOT be set either (maxOccurs=0) 😭 the AES stuff only shows up when AES is actually the algorithm, iykyk 🫶
5.1.5. Cues Element 🌈
okay the Cues element is basically the seek cheat sheet 🧚✨ it's a Top-Level Element to speed up seeking, and all entries are local to the Segment 💜
id / type: 0x1C53BB6B / master
path: \Segment\Cues
minOccurs / maxOccurs: See Table 28 / 1
definition: A Top-Level Element to speed seeking access. All
entries are local to the Segment.
notes: See Table 28. +===========+====================================================+
| attribute | note |
+===========+====================================================+
| minOccurs | This element SHOULD be set when the Segment is not |
| | transmitted as a live stream; see Section 23.2. |
+-----------+----------------------------------------------------+
Table 28: Cues Implementation Notesthe Cues element SHOULD be set when the Segment isn't being sent as a live stream (see Section 23.2) 💖 so for live streams it's more of a "eh, optional" moment, but for regular playback, you want it 🎀
5.1.5.1. CuePoint Element 🦋
a CuePoint is one seek point in the Segment, and it holds all the info for that spot 💅
id / type: 0xBB / master
path: \Segment\Cues\CuePoint
minOccurs: 1
definition: Contains all information relative to a seek point in the
Segment.5.1.5.1.1. CueTime Element ⭐
this is the absolute timestamp of the seek point 🕰️ it's expressed in Segment Ticks, which are based on TimestampScale (see Section 11.1) 🌸
id / type: 0xB3 / uinteger
path: \Segment\Cues\CuePoint\CueTime
minOccurs / maxOccurs: 1 / 1
definition: Absolute timestamp of the seek point, expressed in
Segment Ticks, which are based on TimestampScale; see
Section 11.1.5.1.5.1.2. CueTrackPositions Element 🍓
this one holds the positions for the different tracks at that timestamp, so it's like a little map for each track 🗺️💜
id / type: 0xB7 / master
path: \Segment\Cues\CuePoint\CueTrackPositions
minOccurs: 1
definition: Contains positions for different tracks corresponding to
the timestamp.5.1.5.1.2.1. CueTrack Element 🎀
the track this position is for, and it's a uinteger that can't be 0 (range 1-18446744073709551615) 🙅♀️
id / type: 0xF7 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Cues\CuePoint\CueTrackPositions\CueTrack
minOccurs / maxOccurs: 1 / 1
definition: The track for which a position is given.5.1.5.1.2.2. CueClusterPosition Element 🧚
this is the Segment Position (Section 16) of the Cluster that holds the matching Block 💫
id / type: 0xF1 / uinteger
path: \Segment\Cues\CuePoint\CueTrackPositions\CueClusterPosition
minOccurs / maxOccurs: 1 / 1
definition: The Segment Position (Section 16) of the Cluster
containing the associated Block.5.1.5.1.2.3. CueRelativePosition Element 🌈
this one is the relative position inside that Cluster, where 0 means the very first possible spot in there 🦋 it's version 4+ only (minver 4)
id / type: 0xF0 / uinteger
path: \Segment\Cues\CuePoint\CueTrackPositions\CueRelativePosition
maxOccurs: 1
minver: 4
definition: 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.5.1.5.1.2.4. CueDuration Element 💅
the duration of the block, in Segment Ticks based on TimestampScale (Section 11.1) ⏱️ if it's missing, the track's DefaultDuration doesn't apply, and there's no duration info available in the cues 💀 (also minver 4 👑)
id / type: 0xB2 / uinteger
path: \Segment\Cues\CuePoint\CueTrackPositions\CueDuration
maxOccurs: 1
minver: 4
definition: The duration of the block, expressed in Segment Ticks,
which are based on TimestampScale; see Section 11.1. If missing,
the track's DefaultDuration does not apply and no duration
information is available in terms of the cues.5.1.5.1.2.5. CueBlockNumber Element 🎀
this is the number of the Block in the specified Cluster, and it's a uinteger that can't be 0 (range 1-18446744073709551615) 🙈
id / type: 0x5378 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Cues\CuePoint\CueTrackPositions\CueBlockNumber
maxOccurs: 1
definition: Number of the Block in the specified Cluster.5.1.5.1.2.6. CueCodecState Element 🌸
the Segment Position (Section 16) of the Codec State that goes with this Cues element 🧚 a value of 0 means the data comes from the initial TrackEntry 💖 (version 2+)
id / type / default: 0xEA / uinteger / 0
path: \Segment\Cues\CuePoint\CueTrackPositions\CueCodecState
minOccurs / maxOccurs: 1 / 1
minver: 2
definition: The Segment Position (Section 16) of the Codec State
corresponding to this Cues element. 0 means that the data is taken
from the initial TrackEntry.5.1.5.1.2.7. CueReference Element 🦋
this is a master that holds the Clusters with the referenced Blocks, and it's version 2+ 🫶
id / type: 0xDB / master
path: \Segment\Cues\CuePoint\CueTrackPositions\CueReference
minver: 2
definition: The Clusters containing the referenced Blocks.5.1.5.1.2.8. CueRefTime Element 💜
the timestamp of the referenced Block, in Segment Ticks based on TimestampScale (Section 11.1) ⏰ (also version 2+ ✨)
id / type: 0x96 / uinteger
path: \Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefTi
me
minOccurs / maxOccurs: 1 / 1
minver: 2
definition: Timestamp of the referenced Block, expressed in Segment
Ticks which is based on TimestampScale; see Section 11.1.5.1.6. Attachments Element 📎
the Attachments element holds the attached files, and there can be at most one of these per Segment 🎀
id / type: 0x1941A469 / master
path: \Segment\Attachments
maxOccurs: 1
definition: Contains attached files.5.1.6.1. AttachedFile Element 🌈
this is one attached file, and you need at least one of these 💅
id / type: 0x61A7 / master
path: \Segment\Attachments\AttachedFile
minOccurs: 1
definition: An attached file.5.1.6.1.1. FileDescription Element 🧚
a human-friendly name for the file, so the vibes are readable 🌸
id / type: 0x467E / utf-8
path: \Segment\Attachments\AttachedFile\FileDescription
maxOccurs: 1
definition: A human-friendly name for the attached file.5.1.6.1.2. FileName Element 🍓
the filename of the attached file, and it's required, no skipping 📁
id / type: 0x466E / utf-8
path: \Segment\Attachments\AttachedFile\FileName
minOccurs / maxOccurs: 1 / 1
definition: Filename of the attached file.5.1.6.1.3. FileMediaType Element 💖
the media type of the file, following the format in [RFC6838] 🦋 and it's stream copy True (Section 8) 🫶
id / type: 0x4660 / string
path: \Segment\Attachments\AttachedFile\FileMediaType
minOccurs / maxOccurs: 1 / 1
definition: Media type of the file following the format described in
[RFC6838].
stream copy: True (Section 8)5.1.6.1.4. FileData Element 💜
the actual data of the file, so the payload itself 📦 also stream copy True (Section 8)
id / type: 0x465C / binary
path: \Segment\Attachments\AttachedFile\FileData
minOccurs / maxOccurs: 1 / 1
definition: The data of the file.
stream copy: True (Section 8)5.1.6.1.5. FileUID Element ⭐
the UID for the file, which should be as random as possible 🎲 range is 1-18446744073709551615 (not 0 🙅♀️) and it's stream copy True (Section 8) 💫
id / type: 0x46AE / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Attachments\AttachedFile\FileUID
minOccurs / maxOccurs: 1 / 1
definition: UID representing the file, as random as possible.
stream copy: True (Section 8)5.1.7. Chapters Element 🌈
the Chapters element is the menu-and-partition system for the Segment, basically how you split up your data into chapters 📖 there's at most one, it recurs, and for the detailed stuff check out Section 20 ✨
id / type: 0x1043A770 / master
path: \Segment\Chapters
maxOccurs: 1
recurring: True
definition: A system to define basic menus and partition data. For
more detailed information, see Section 20.5.1.7.1. EditionEntry Element 🦋
this one contains all the info about a Segment edition, and you need at least one 💅
id / type: 0x45B9 / master
path: \Segment\Chapters\EditionEntry
minOccurs: 1
definition: Contains all information about a Segment edition.5.1.7.1.1. EditionUID Element 🎀
a UID that identifies the edition, which is super useful for tagging 🏷️ it's a uinteger that can't be 0 (range 1-18446744073709551615) and stream copy True (Section 8) 💖
id / type: 0x45BC / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Chapters\EditionEntry\EditionUID
maxOccurs: 1
definition: A UID that identifies the edition. It's useful for
tagging an edition.
stream copy: True (Section 8)5.1.7.1.2. EditionFlagDefault Element 🌸
this is a 0-or-1 flag, and if it's set to 1 the edition SHOULD be used as the default one 🧚 default is 0 🍓
id / type / default: 0x45DB / uinteger / 0
range: 0-1
path: \Segment\Chapters\EditionEntry\EditionFlagDefault
minOccurs / maxOccurs: 1 / 1
definition: Set to 1 if the edition SHOULD be used as the default
one.5.1.7.1.3. EditionFlagOrdered Element 💜
another 0-or-1 flag: set it to 1 if the chapters can be defined multiple times AND the playback order is enforced (see Section 20.1.3) 🌈 default is 0 💅
id / type / default: 0x45DD / uinteger / 0
range: 0-1
path: \Segment\Chapters\EditionEntry\EditionFlagOrdered
minOccurs / maxOccurs: 1 / 1
definition: Set to 1 if the chapters can be defined multiple times
and the order to play them is enforced; see Section 20.1.3.5.1.7.1.4. ChapterAtom Element 🧚
this is the chapter atom, the info that applies to all tracks, and it's recursive so chapters can hold chapters 🪆 you need at least one
id / type: 0xB6 / master
path: \Segment\Chapters\EditionEntry\+ChapterAtom
minOccurs: 1
recursive: True
definition: Contains the atom information to use as the chapter atom
(applies to all tracks).5.1.7.1.4.1. ChapterUID Element 🌸
a UID that identifies the Chapter, range 1-18446744073709551615 (so not 0 🙅♀️), and it's required, minOccurs 1 / maxOccurs 1 🫶 plus stream copy True (Section 8) ✨
id / type: 0x73C4 / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterUID
minOccurs / maxOccurs: 1 / 1
definition: A UID that identifies the Chapter.
stream copy: True (Section 8)5.1.7.1.4.2. ChapterStringUID Element 🦋
a unique string ID for the Chapter, and it's version 3+ 🎀 the example is that it's used as the storage for cue identifier values [WebVTT] 💖
id / type: 0x5654 / utf-8
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterStringUID
maxOccurs: 1
minver: 3
definition: A unique string ID that identifies the Chapter. For
example, it is used as the storage for cue identifier values
[WebVTT].5.1.7.1.4.3. ChapterTimeStart Element 🌈
the start timestamp of the Chapter, in Matroska Ticks (aka nanoseconds, see Section 11.1) ⏱️
id / type: 0x91 / uinteger
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTimeStart
minOccurs / maxOccurs: 1 / 1
definition: Timestamp of the start of Chapter, expressed in Matroska
Ticks -- i.e., in nanoseconds; see Section 11.1.5.1.7.1.4.4. ChapterTimeEnd Element 💅
the end timestamp of the Chapter, with the end itself excluded, also in Matroska Ticks (nanoseconds, Section 11.1) 🌙 the value MUST be greater than or equal to the ChapterTimeStart of the same ChapterAtom 🙌
id / type: 0x92 / uinteger
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTimeEnd
minOccurs / maxOccurs: See Table 29 / 1
definition: Timestamp of the end of Chapter (timestamp excluded),
expressed in Matroska Ticks -- i.e., in nanoseconds; see
Section 11.1. The value MUST be greater than or equal to the
ChapterTimeStart of the same ChapterAtom.
usage notes: 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.
notes: See Table 29.ngl the usage note is the important bit here: since the end is excluded, the ChapterTimeEnd MUST account for the duration of the last frame included, especially for the ChapterAtom covering the last frames of the Segment 🎬💀
+===========+====================================================+
| attribute | note |
+===========+====================================================+
| minOccurs | ChapterTimeEnd MUST be set (minOccurs=1) if the |
| | Edition is an ordered edition; see Section 20.1.3. |
| | If it's a Parent Chapter, see Section 20.2.3. |
+-----------+----------------------------------------------------+
Table 29: ChapterTimeEnd Implementation Notesand last but not least, Table 29 says ChapterTimeEnd MUST be set (minOccurs=1) if the Edition is an ordered edition (Section 20.1.3), and if it's a Parent Chapter, check Section 20.2.3 🌈👑
5.1.7.1.4.5. ChapterFlagHidden Element ✨
id / type / default: 0x98 / uinteger / 0
range: 0-1
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterFlagHidden
minOccurs / maxOccurs: 1 / 1Okay so this one's a simple on/off switch 🙈 Set it to 1 if a chapter is hidden. Hidden chapters SHOULD NOT show up in the user interface, but they're still available to Control Tracks (see Section 20.2.5 on Chapter flags) 🦋
5.1.7.1.4.6. ChapterSegmentUUID Element 🌸
id / type: 0x6E67 / binary
length: 16
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterSegmentUUID
minOccurs / maxOccurs: See Table 30 / 1This is the SegmentUUID of another Segment you play during this chapter, bestie 🎀 The value MUST NOT be the SegmentUUID of the Segment it belongs to. No self-linking, no cap 💅
+===========+==============================================+
| attribute | note |
+===========+==============================================+
| minOccurs | ChapterSegmentUUID MUST be set (minOccurs=1) |
| | if ChapterSegmentEditionUID is used; see |
| | Section 17.2 on Medium-Linking Segments. |
+-----------+----------------------------------------------+
Table 30: ChapterSegmentUUID Implementation NotesTable 30 is the cheat sheet for that minOccurs situation. If you're using ChapterSegmentEditionUID, ChapterSegmentUUID MUST be set. It's giving "dependent field" energy 💜
5.1.7.1.4.7. ChapterSegmentEditionUID Element ✨
id / type: 0x6EBC / uinteger
range: not 0 (1-18446744073709551615)
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterSegmentEditionUID
maxOccurs: 1This is the EditionUID to play from the Segment linked in ChapterSegmentUUID. If ChapterSegmentEditionUID is undeclared, then no Edition of the Linked Segment is used (see Section 17.2 on Medium-Linking Segments) 🧚
5.1.7.1.4.8. ChapterPhysicalEquiv Element 🍓
id / type: 0x63C3 / uinteger
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterPhysicalEquiv
maxOccurs: 1This tells you the physical equivalent of this ChapterAtom, like "DVD" (60) or "SIDE" (50). For the full list, check Section 20.4 📀
5.1.7.1.4.9. ChapterDisplay Element 💖
id / type: 0x80 / master
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplayThis is the container with all the possible strings you can use for the chapter display. Think of it as the closet of outfits for a chapter 👗
5.1.7.1.4.10. ChapString Element 🫶
id / type: 0x85 / utf-8
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\ChapString
minOccurs / maxOccurs: 1 / 1This is the string you use as the chapter atom. Required, babe, one per display ✨
5.1.7.1.4.11. ChapLanguage Element 🌈
id / type / default: 0x437C / string / eng
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\ChapLanguage
minOccurs: 1This is the language of the string, in the Matroska languages form (see Section 12 on language codes). Lowkey important: this element MUST be ignored if a ChapLanguageBCP47 element is used in the same ChapterDisplay element. The newer one wins, periodt 👑
5.1.7.1.4.12. ChapLanguageBCP47 Element 🦋
id / type: 0x437D / string
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\ChapLanguageBCP47
minver: 4This is the language of the ChapString, in the form defined in [RFC5646] (see Section 12 on language codes). If you use ChapLanguageBCP47, then any ChapLanguage and ChapCountry elements in the same ChapterDisplay MUST be ignored. The BCP 47 one is the main character here 💅
5.1.7.1.4.13. ChapCountry Element 🌸
id / type: 0x437E / string
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\ChapCountryThis is the country of the string, in the Matroska countries form (see Section 13 on country codes). Same drama as ChapLanguage: this element MUST be ignored if a ChapLanguageBCP47 element is used within the same ChapterDisplay element 🙄
5.1.7.1.4.14. ChapProcess Element 🎀
id / type: 0x6944 / master
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcessThis is the container for all the commands tied to the Atom. Commands, commands everywhere 🧚
5.1.7.1.4.15. ChapProcessCodecID Element 💜
id / type / default: 0x6955 / uinteger / 0
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapProcessCodecID
minOccurs / maxOccurs: 1 / 1This says what type of codec does the processing. Check Table 31 for the defined values. You can also register more in the "Matroska Chapter Codec IDs" registry (Section 27.14) 🔥
+=======+=================+============================+
| value | label | definition |
+=======+=================+============================+
| 0 | Matroska Script | Chapter commands using the |
| | | Matroska Script codec. |
+-------+-----------------+----------------------------+
| 1 | DVD-menu | Chapter commands using the |
| | | DVD-like codec. |
+-------+-----------------+----------------------------+
Table 31: ChapProcessCodecID Values5.1.7.1.4.16. ChapProcessPrivate Element 🌙
id / type: 0x450D / binary
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapProcessPrivate
maxOccurs: 1This is optional data attached to the ChapProcessCodecID info. When ChapProcessCodecID = 1, it's the "DVD level" equivalent (see Section 20.3 on DVD menus) 📀
5.1.7.1.4.17. ChapProcessCommand Element ⭐
id / type: 0x6911 / master
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapProcessCommandThis is another container, holding all the commands tied to the Atom. Yes, a container inside a container, it's a whole vibe 💅
5.1.7.1.4.18. ChapProcessTime Element 🍓
id / type: 0x6922 / uinteger
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapProcessCommand\ChapProcessTime
minOccurs / maxOccurs: 1 / 1This defines when the process command SHOULD be handled. Check Table 32 for the restrictions 🫶
+=======+===============================+
| value | label |
+=======+===============================+
| 0 | during the whole chapter |
+-------+-------------------------------+
| 1 | before starting playback |
+-------+-------------------------------+
| 2 | after playback of the chapter |
+-------+-------------------------------+
Table 32: ChapProcessTime Values5.1.7.1.4.19. ChapProcessData Element 🦋
id / type: 0x6933 / binary
path: \Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapProcessCommand\ChapProcessData
minOccurs / maxOccurs: 1 / 1This is the command info. The data SHOULD be interpreted based on the ChapProcessCodecID value. For ChapProcessCodecID = 1, the data is the binary DVD cell pre/post commands (see Section 20.3 on DVD menus) 🎬
5.1.8. Tags Element 🌈
id / type: 0x1254C367 / master
path: \Segment\TagsThis is where the metadata lives! It describes Tracks, Editions, Chapters, Attachments, or the Segment as a whole. A list of valid tags can be found in [MatroskaTags] 🏷️
5.1.8.1. Tag Element 💖
id / type: 0x7373 / master
path: \Segment\Tags\Tag
minOccurs: 1This is one single metadata descriptor, a little sticky note for your file ✨
5.1.8.1.1. Targets Element 🧚
id / type: 0x63C0 / master
path: \Segment\Tags\Tag\Targets
minOccurs / maxOccurs: 1 / 1This specifies which other elements the metadata in the tag value applies to. If it's empty or omitted, then the tag value describes everything in the Segment. Main character energy 👑
5.1.8.1.1.1. TargetTypeValue Element 🎀
id / type / default: 0x68CA / uinteger / 50
range: not 0 (1-18446744073709551615)
path: \Segment\Tags\Tag\Targets\TargetTypeValue
minOccurs / maxOccurs: 1 / 1This is a number showing the logical level of the target. Check Table 33 for the defined values, and you can register more in the "Matroska Tags Target Types" registry (Section 27.13). The values are meant to be compared, so higher values MUST correspond to a logical level that contains the lower-level TargetTypeValue values. It's like nesting dolls, iykyk 🪆
+=======+==========================+================================+
| value | label | definition |
+=======+==========================+================================+
| 70 | COLLECTION | The highest hierarchical level |
| | | that tags can describe. |
+-------+--------------------------+--------------------------------+
| 60 | EDITION / ISSUE / | A list of lower levels grouped |
| | VOLUME / OPUS / | together. |
| | SEASON / SEQUEL | |
+-------+--------------------------+--------------------------------+
| 50 | ALBUM / OPERA / | The most common grouping level |
| | CONCERT / MOVIE / | of music and video (e.g., an |
| | EPISODE | episode for TV series). |
+-------+--------------------------+--------------------------------+
| 40 | PART / SESSION | When an album or episode has |
| | | different logical parts. |
+-------+--------------------------+--------------------------------+
| 30 | TRACK / SONG / | The common parts of an album |
| | CHAPTER | or movie. |
+-------+--------------------------+--------------------------------+
| 20 | SUBTRACK / | Corresponds to parts of a |
| | MOVEMENT / SCENE | track for audio, such as a |
| | | movement or scene in a movie. |
+-------+--------------------------+--------------------------------+
| 10 | SHOT | The lowest hierarchy found in |
| | | music or movies. |
+-------+--------------------------+--------------------------------+
Table 33: TargetTypeValue Values5.1.8.1.1.2. TargetType Element ✨
- id / type:
0x63CA/string - path:
\Segment\Tags\Tag\Targets\TargetType - maxOccurs:
1 - definition: okay so this is the human-readable label that says what level the target is at, like "ALBUM", "TRACK", "MOVIE", "CHAPTER", etc. 🎀 It's purely informational, so it's there for display vibes 💅
- restrictions: check out Table 34 for the allowed values 👀
+============+====================+
| value | label |
+============+====================+
| COLLECTION | TargetTypeValue 70 |
+------------+--------------------+
| EDITION | TargetTypeValue 60 |
+------------+--------------------+
| ISSUE | TargetTypeValue 60 |
+------------+--------------------+
| VOLUME | TargetTypeValue 60 |
+------------+--------------------+
| OPUS | TargetTypeValue 60 |
+------------+--------------------+
| SEASON | TargetTypeValue 60 |
+------------+--------------------+
| SEQUEL | TargetTypeValue 60 |
+------------+--------------------+
| ALBUM | TargetTypeValue 50 |
+------------+--------------------+
| OPERA | TargetTypeValue 50 |
+------------+--------------------+
| CONCERT | TargetTypeValue 50 |
+------------+--------------------+
| MOVIE | TargetTypeValue 50 |
+------------+--------------------+
| EPISODE | TargetTypeValue 50 |
+------------+--------------------+
| PART | TargetTypeValue 40 |
+------------+--------------------+
| SESSION | TargetTypeValue 40 |
+------------+--------------------+
| TRACK | TargetTypeValue 30 |
+------------+--------------------+
| SONG | TargetTypeValue 30 |
+------------+--------------------+
| CHAPTER | TargetTypeValue 30 |
+------------+--------------------+
| SUBTRACK | TargetTypeValue 20 |
+------------+--------------------+
| MOVEMENT | TargetTypeValue 20 |
+------------+--------------------+
| SCENE | TargetTypeValue 20 |
+------------+--------------------+
| SHOT | TargetTypeValue 10 |
+------------+--------------------+
Table 34: TargetType Values5.1.8.1.1.3. TagTrackUID Element ✨
- id / type / default:
0x63C5/uinteger/0 - path:
\Segment\Tags\Tag\Targets\TagTrackUID - definition: a UID that tells you which Track(s) the tags belong to 🎵
- usage notes: if the value is
0at this level, the tags apply to all tracks in the Segment 🌈 If it's set to any other value, it MUST match theTrackUIDvalue of a track found in this Segment 💖
5.1.8.1.1.4. TagEditionUID Element ✨
- id / type / default:
0x63C9/uinteger/0 - path:
\Segment\Tags\Tag\Targets\TagEditionUID - definition: a UID that identifies the EditionEntry(s) the tags belong to 📚
- usage notes: if the value is
0at this level, the tags apply to all editions in the Segment 🦋 If it's set to any other value, it MUST match theEditionUIDvalue of an edition found in this Segment 🫶
5.1.8.1.1.5. TagChapterUID Element ✨
- id / type / default:
0x63C4/uinteger/0 - path:
\Segment\Tags\Tag\Targets\TagChapterUID - definition: a UID that identifies the Chapter(s) the tags belong to 🧚
- usage notes: if the value is
0at this level, the tags apply to all chapters in the Segment 🌸 If it's set to any other value, it MUST match theChapterUIDvalue of a chapter found in this Segment ✨
5.1.8.1.1.6. TagAttachmentUID Element ✨
- id / type / default:
0x63C6/uinteger/0 - path:
\Segment\Tags\Tag\Targets\TagAttachmentUID - definition: a UID that identifies the Attachment(s) the tags belong to 📎
- usage notes: if the value is
0at this level, the tags apply to all the attachments in the Segment 💅 If it's set to any other value, it MUST match theFileUIDvalue of an attachment found in this Segment 🔥
5.1.8.1.2. SimpleTag Element ✨
- id / type:
0x67C8/master - path:
\Segment\Tags\Tag\+SimpleTag - minOccurs:
1 - recursive:
True - definition: holds the general info about the target 🍓
5.1.8.1.2.1. TagName Element ✨
- id / type:
0x45A3/utf-8 - path:
\Segment\Tags\Tag\+SimpleTag\TagName - minOccurs / maxOccurs:
1/1 - definition: the name of the tag value that's about to get stored 🏷️
5.1.8.1.2.2. TagLanguage Element ✨
- id / type / default:
0x447A/string/und - path:
\Segment\Tags\Tag\+SimpleTag\TagLanguage - minOccurs / maxOccurs:
1/1 - definition: tells you the language of the tag, written in the Matroska languages form (check Section 12 on language codes 🌍) This element MUST be ignored if the
TagLanguageBCP47element is used within the same SimpleTag element 🙈
5.1.8.1.2.3. TagLanguageBCP47 Element ✨
- id / type:
0x447B/string - path:
\Segment\Tags\Tag\+SimpleTag\TagLanguageBCP47 - maxOccurs:
1 - minver:
4 - definition: the language used in the
TagString, in the form defined in [RFC5646] (see Section 12 on language codes) 🌷 If this element is used, then anyTagLanguageelements used in the same SimpleTag MUST be ignored 💜
5.1.8.1.2.4. TagDefault Element ✨
- id / type / default:
0x4484/uinteger/1 - range:
0-1 - path:
\Segment\Tags\Tag\+SimpleTag\TagDefault - minOccurs / maxOccurs:
1/1 - definition: a boolean that says whether this is the default/original language for the given tag 🎀
5.1.8.1.2.5. TagString Element ✨
- id / type:
0x4487/utf-8 - path:
\Segment\Tags\Tag\+SimpleTag\TagString - maxOccurs:
1 - definition: the tag value itself 💖
5.1.8.1.2.6. TagBinary Element ✨
- id / type:
0x4485/binary - path:
\Segment\Tags\Tag\+SimpleTag\TagBinary - maxOccurs:
1 - definition: the tag value if it's binary 🧲 Heads up, this cannot be used in the same SimpleTag as
TagString🚫
6. Matroska Element Ordering ✨
Okay so, besides the EBML Header and the CRC-32 element, the EBML specification [RFC8794] doesn't ask for any particular storage order for elements 🦋 This spec does lay out mandates and recommendations for ordering certain elements, though, so playback, seeking, and editing run smoother 🚀 This section walks through those ordering requirements and recommendations for Matroska, and explains why they exist 💅
6.1. 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 they SHALL both be referenced by a SeekHead element that shows up before the first Cluster element 🧩
All Top-Level Elements MUST use a 4-octet EBML Element ID 🔢
When you're using Medium Linking, chapters are used to reference other Segments to play in a given order (see Section 17.2) 🔗 A Segment with these Linked Chapters doesn't need a Tracks element or a Cluster element ✨
It's possible to edit a Matroska file after it's been created 🛠️ For example, chapters, tags, or attachments can be added 🎀 When new Top-Level Elements get added to a Matroska file, the SeekHead element(s) MUST be updated so that they itemize the identity and position of all Top-Level Elements 📍
Editing, removing, or adding elements to a Matroska file often means some existing elements have to be voided or extended 😭 Turning the existing elements into Void elements as padding can be used as a way to avoid moving big chunks of data around 🫶
6.2. 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 🔐
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 🙅♀️
6.3. SeekHead ✨
If it's 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 🌟
Also, 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 collectively reference the identity and position of all Top-Level Elements except for the first SeekHead element 💫
6.4. Cues (Index) ✨
The Cues element is RECOMMENDED to optimize seeking access in Matroska 🔍 It's programmatically simpler to add the Cues element after all Cluster elements have been written, because that doesn't require predicting how much space to reserve before writing the Cluster elements 🧠 Storing the Cues element before the Cluster elements can give some seeking advantages, though 🏃♀️ If the Cues element is present, then it SHOULD either be stored before the first Cluster element or be referenced by a SeekHead element 💖
6.5. Info ✨
The first Info element SHOULD occur before the first Tracks element and first Cluster element, except when it's referenced by a SeekHead element 📖
6.6. 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 doesn't need to seek, because it immediately tells the user 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 🌸
6.7. Attachments ✨
The Attachments element isn't meant to be used by default when playing the file, but it could hold info relevant to the content, like cover art or fonts 🖼️ Cover art is useful even before the file is played, and fonts could be needed before playback starts so subtitles can be initialized 🔤 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 🧁
6.8. Tags ✨
The Tags element is the most likely to change 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's inconvenient to have to seek through the Segment for tags, especially for network streams, so 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 can be written at the end of the Segment element ✍️ The file and Segment sizes will only change marginally 💅✨
7. Matroska Versioning ✨
Okay so the big idea here is that Matroska is built on the principle that a reading app does not have to support 100% of the specs to play the file 💅 Which is honestly so relatable. So a Matroska file carries version indicators that basically tell the reading app what to expect 🦋
It's totally possible (and valid!) for the version fields to say the file has Matroska elements from a higher spec version, while also 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 file can be a little extra, as long as the player can handle the basics 🙈
The EBML Header of each Matroska document is where the reading app finds out what version of Matroska to expect. The elements inside the EBML Header with jurisdiction over this info 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 (Section 5.1.3.4) MUST have a DocTypeVersion equal to or greater than 2. A file containing CueRelativePosition elements (Section 5.1.5.1.2.3) 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 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. Main character energy for that element, no cap 🎀
A reading application supporting Matroska version V MUST NOT refuse to read a file with DocReadTypeVersion equal to or lower than V, even if DocTypeVersion is greater than V. Not me refusing a file just because the version number looks spicy 💀
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 but does not know about, if that unknown element fits into the size constraints set by the current Parent Element. So it just politely scrolls past the stuff it doesn't get 🦋
8. Stream Copy 🌸
It's sometimes necessary to create a Matroska file from another Matroska file, for example, to add subtitles in a language or to edit out a portion of the content. Some values from the original Matroska file need to be kept the same in the destination file. 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. If that property is not set, elements may or may not keep the same value between the source and destination files. Basically, if there's no stream copy tag, it's a free-for-all 💜
9. DefaultDecodedFieldDuration 🌈
The DefaultDecodedFieldDuration element can signal to the displaying application how often fields of a video sequence will be available for displaying. It works for both interlaced and progressive content, so it's super versatile ⭐
If the video sequence is signaled as interlaced (Section 5.1.4.1.28.1), then DefaultDecodedFieldDuration equals the period between two successive fields at the output of the decoding process. For video sequences signaled as progressive, DefaultDecodedFieldDuration is half of the period between two successive frames at the output of the decoding process.
These values are valid at the end of the decoding process before post-processing (such as deinterlacing or inverse telecine) is applied. So they're the numbers before any extra cleanup happens 🍓
Examples, because I love a good example 😭
- Blu-ray movie:
1000000000 ns/(48/1.001) = 20854167 ns - PAL broadcast/DVD:
1000000000 ns/(50/1.000) = 20000000 ns - N/ATSC broadcast:
1000000000 ns/(60/1.001) = 16683333 ns - Hard-telecined DVD:
1000000000 ns/(60/1.001) = 16683333 ns (60 encoded interlaced fields per second) - Soft-telecined DVD:
1000000000 ns/(60/1.001) = 16683333 ns (48 encoded interlaced fields per second, with "repeat_first_field = 1")
10. Cluster Blocks 🎀
Okay this part is giving organization. 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, which is fine, because 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:
- in a Block that is contained inside a BlockGroup
- 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, no exceptions 👑
Each block contains the same parts in the following order:
- a variable-length header
- the lacing information (optional)
- the consecutive frame(s)
The block header starts with the number of the Track it corresponds to. The value MUST correspond to the TrackNumber (Section 5.1.4.1.1) of a TrackEntry of the Segment.
The TrackNumber is coded using the Variable-Size Integer (VINT) mechanism described in Section 4 of [RFC8794]. 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 Section 11.1. The value is stored as a signed value on 16 bits.
10.1. Block Structure 🦋
This section describes the binary data contained in the Block element (Section 5.1.3.5.1). 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; the other variants can be deduced by extending the size of the TrackNumber by multiples of 8 bits. Math bestie, we love a pattern ✨
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| | | |I|LAC|U|
| Track Number | Timestamp | Rsvrd |N|ING|N|
| | | |V| |U|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 11: Block Header with 1-Octet TrackNumber
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Track Number | Timestamp |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |I|LAC|U|
| Rsvrd |N|ING|N| ...
| |V| |U|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 12: Block Header with 2-Octet TrackNumber
where:
- Track Number: 8, 16, 24, 32, 40, 48, or 56 bits. An EBML VINT-coded track number.
- Timestamp: 16 bits. Signed timestamp in Track Ticks.
- Rsvrd: 4 bits. Reserved bits MUST be set to 0.
- INV: 1 bit. Invisible; The codec SHOULD decode this frame but not display it.
- LACING: 2 bits. Uses lacing mode.
00b: no lacing (Section 10.3.1)01b: Xiph lacing (Section 10.3.2)11b: EBML lacing (Section 10.3.3)10b: fixed-size lacing (Section 10.3.4)
- UNU: 1 bit. Unused bit.
The remaining data in the Block corresponds to the lacing data and frames usage as described in each respective lacing mode (see Section 10.3).
10.2. SimpleBlock Structure 🌸
This section describes the binary data contained in the SimpleBlock element (Section 5.1.3.4). Bit 0 is the most significant bit.
The SimpleBlock structure is inspired by the Block structure; see Section 10.1. The main differences are the added Keyframe flag and Discardable flag. Otherwise, everything is the same. Iconic copy-paste energy 💅
As the TrackNumber size can vary between 1 and 8 octets, there are 8 different sizes for the SimpleBlock header. The definitions for TrackNumber sizes of 1 and 2 are provided; the other variants can be deduced by extending the size of the TrackNumber by multiples of 8 bits.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| | |K| |I|LAC|D|
| Track Number | Timestamp |E|Rsvrd|N|ING|I|
| | |Y| |V| |S|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 13: SimpleBlock Header with 1-Octet TrackNumber
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Track Number | Timestamp |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|K| |I|LAC|D|
|E|Rsvrd|N|ING|I| ...
|Y| |V| |S|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 14: SimpleBlock Header with 2-Octet TrackNumber
where:
- Track Number: 8, 16, 24, 32, 40, 48, or 56 bits. An EBML VINT-coded track number.
- Timestamp: 16 bits. Signed timestamp in Track Ticks.
- KEY: 1 bit. Keyframe; Set when the Block contains only keyframes.
- Rsvrd: 3 bits. Reserved bits MUST be set to 0.
- INV: 1 bit. Invisible; the codec SHOULD decode this frame but not display it.
- LACING: 2 bits. Uses lacing mode.
00b: no lacing (Section 10.3.1)01b: Xiph lacing (Section 10.3.2)11b: EBML lacing (Section 10.3.3)10b: fixed-size lacing (Section 10.3.4)
- DIS: 1 bit. Discardable; The frames of the Block can be discarded during playing if needed.
The remaining data in the SimpleBlock corresponds to the lacing data and frames usage as described in each respective lacing mode (see Section 10.3).
10.3. Block Lacing 🍓
Lacing is a mechanism to save space when storing data. It is typically used for small blocks of data (referred to as frames in Matroska). It packs multiple frames into a single Block or SimpleBlock. Tiny frames, one big lace, very efficient 🧺
Lacing MUST NOT be used to store a single frame in a Block or SimpleBlock.
There are three types of lacing:
- Xiph, which is inspired by what is found in the Ogg container [RFC3533]
- EBML, which is the same with sizes coded differently
- Fixed-size, where the size is not coded
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. 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 (Section 5.1.4.1.12) is set to 0, all blocks of that track MUST NOT use lacing. So if the track's FlagLacing says no, the answer is no, periodt 💅
10.3.1. No Lacing 🎀
okay so when there's no lacing going on, there's no frame count stored at all, and the Block can only hold ONE frame. 💅 the LACING bits in the Block Header flags are set to 00b, bestie.
Here's what a Block for an 800-octet frame looks like:
+=============+=========+===================+
| Block Octet | Value | Description |
+=============+=========+===================+
| 4-803 | <frame> | Single frame data |
+-------------+---------+-------------------+Table 35: No Lacing 🦋
When a Block contains a single frame, it MUST use this "no lacing" mode. 😭 No exceptions, iykyk!
10.3.2. Xiph Lacing 🌈
okay Xiph lacing is giving Ogg container vibes because it uses the same size coding as the Ogg container [RFC3533]. ✨ The LACING bits of the Block Header flags get set to 01b here.
The Block data with laced frames is stored like this:
- Lacing Head on 1 Octet: Number of frames in the lace minus 1. 🍓
- Lacing size of each frame except the last one. 🧚
- Binary data of each frame consecutively. 💖
The lacing size gets split into 255 values, stored as unsigned octets. 🫶 For example, 500 is coded 255;245 or [0xFF 0xF5]. And a frame whose size is a multiple of 255 gets a 0 tacked on at the end of its size. 💀 For example, 765 is coded 255;255;255;0 or [0xFF 0xFF 0xFF 0x00].
The size of the last frame is deduced from whatever is left in the Block after the other frames. 👑
Because big sizes need big coding for the sizes, it is RECOMMENDED to use Xiph lacing only with small frames. 🙈
In our example, the 800-, 500-, and 1000-octet frames get stored with Xiph lacing in a Block like so:
+==============+=====================+==========================+
| Block Octets | Value | Description |
+==============+=====================+==========================+
| 4 | 0x02 | Number of frames minus 1 |
+--------------+---------------------+--------------------------+
| 5-8 | 0xFF 0xFF 0xFF 0x23 | Size of the first frame |
| | | (255;255;255;35) |
+--------------+---------------------+--------------------------+
| 9-10 | 0xFF 0xF5 | Size of the second frame |
| | | (255;245) |
+--------------+---------------------+--------------------------+
| 11-810 | | First frame data |
+--------------+---------------------+--------------------------+
| 811-1310 | | Second frame data |
+--------------+---------------------+--------------------------+
| 1311-2310 | | Third frame data |
+--------------+---------------------+--------------------------+Table 36: Xiph Lacing Example 🔥
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. ✨ Math is slay, periodt.
10.3.3. EBML Lacing 🌸
the EBML lacing encodes the frame size with an EBML-like encoding [RFC8794]. ✨ The LACING bits of the Block Header flags are set to 11b.
The Block data with laced frames is stored like this:
- Lacing Head on 1 Octet: Number of frames in the lace minus 1. 🍓
- Lacing size of each frame except the last one. 🧚
- Binary data of each frame consecutively. 💖
The first frame size is encoded as an EBML VINT value. 🦋 The remaining frame sizes are encoded as signed values, using the difference between each frame size and the previous frame size. These signed values are encoded as VINT, with a mapping from signed to unsigned numbers. To decode the unsigned number stored in the VINT back into a signed number, you subtract 2^((7*n)-1)-1, where n is the octet size of the VINT. 🤓
+===================================+======================+
| Bit Representation of Signed VINT | Possible Value Range |
+===================================+======================+
| 1xxx xxxx | 2^7 values from |
| | -(2^6-1) to 2^6 |
+-----------------------------------+----------------------+
| 01xx xxxx xxxx xxxx | 2^14 values from |
| | -(2^13-1) to 2^13 |
+-----------------------------------+----------------------+
| 001x xxxx xxxx xxxx xxxx xxxx | 2^21 values from |
| | -(2^20-1) to 2^20 |
+-----------------------------------+----------------------+
| 0001 xxxx xxxx xxxx xxxx xxxx | 2^28 values from |
| xxxx xxxx | -(2^27-1) to 2^27 |
+-----------------------------------+----------------------+
| 0000 1xxx xxxx xxxx xxxx xxxx | 2^35 values from |
| xxxx xxxx xxxx xxxx | -(2^34-1) to 2^34 |
+-----------------------------------+----------------------+Table 37: EBML Lacing Signed VINT Bits Usage 💜
In our example, the 800-, 500-, and 1000-octet frames get stored with EBML lacing in a Block like so:
+==============+===========+=====================================+
| Block Octets | Value | Description |
+==============+===========+=====================================+
| 4 | 0x02 | Number of frames minus 1 |
+--------------+-----------+-------------------------------------+
| 5-6 | 0x43 0x20 | Size of the first frame (800 = |
| | | 0x320 + 0x4000) |
+--------------+-----------+-------------------------------------+
| 7-8 | 0x5E 0xD3 | Size of the second frame (500 - 800 |
| | | = -300 = - 0x12C + 0x1FFF + 0x4000) |
+--------------+-----------+-------------------------------------+
| 8-807 | <frame1> | First frame data |
+--------------+-----------+-------------------------------------+
| 808-1307 | <frame2> | Second frame data |
+--------------+-----------+-------------------------------------+
| 1308-2307 | <frame3> | Third frame data |
+--------------+-----------+-------------------------------------+Table 38: EBML Lacing Example 🌈
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. 💅
10.3.4. Fixed-size Lacing 🧁
fixed-size lacing doesn't store the frame size at all. ✨ It only stores the number of frames in the lace. Each frame MUST have the same size, and 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 like this:
- Lacing Head on 1 Octet: Number of frames in the lace minus 1. 🍓
- Binary data of each frame consecutively. 💖
For example, for three frames that are 800 octets each:
+==============+==========+==========================+
| Block Octets | Value | Description |
+==============+==========+==========================+
| 4 | 0x02 | Number of frames minus 1 |
+--------------+----------+--------------------------+
| 5-804 | <frame1> | First frame data |
+--------------+----------+--------------------------+
| 805-1604 | <frame2> | Second frame data |
+--------------+----------+--------------------------+
| 1605-2404 | <frame3> | Third frame data |
+--------------+----------+--------------------------+Table 39: Fixed-Size Lacing Example 🎀
This gives a Block of 2405 octets. When reading the Block, we find that there are three frames (Octet 4). The data starts at Octet 5, so the size of each frame is (2405 - 5) / 3 = 800. 🫶
10.3.5. Laced Frames Timestamp 💜
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. 😭
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). For audio, there is usually a fixed output sampling frequency for the whole track, so the decoder should be able to recover the timestamp of each sample, knowing each output sample is contiguous with a fixed frequency. ✨ For subtitles, this is usually not the case, so lacing SHOULD NOT be used. 🥺
10.4. Random Access Points 🦋
okay so Random Access Points (RAPs) are basically the spots where a parser can seek to and just start playing, no need to decode everything that came before 🙌 In Matroska, BlockGroups and SimpleBlocks can be RAPs. Seeking to one is still a two-step thing tho: you seek to the Cluster that holds it, read the Cluster Timestamp, and then start playback from the BlockGroup or SimpleBlock that is the RAP ✨
Here's the lowkey tricky part 🥺 A Matroska File is usually juggling multiple tracks at once (video, audio, and subtitles), so to seek properly to a RAP, you have to account for every selected track 💅 Usually all the audio and subtitle BlockGroups or SimpleBlocks are RAPs, because they're independent of each other and can be played randomly 🎶
Video is the diva of the group 💀 Video tracks often reference 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 as non-keyframe in a SimpleBlock; see Section 10.2 🔥
<Cluster>
<Timestamp>123456</Timestamp>
<BlockGroup>
<!-- References a Block 40 Track Ticks before this one -->
<ReferenceBlock>-40</ReferenceBlock>
<Block/>
</BlockGroup>
...
</Cluster>Figure 15: BlockGroup with a Frame That References Another Frame, with the EBML Tree Shown as XML
<Cluster>
<Timestamp>123456</Timestamp>
<SimpleBlock/> (octet 3 bit 0 not set)
...
</Cluster>Figure 16: 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 🌸
<Cluster>
<Timestamp>123456</Timestamp>
<BlockGroup>
<!-- No ReferenceBlock allowed in this BlockGroup -->
<Block/>
</BlockGroup>
...
</Cluster>Figure 17: BlockGroup with a Frame That References No Other Frame, with the EBML Tree Shown as XML
<Cluster>
<Timestamp>123456</Timestamp>
<SimpleBlock/> (octet 3 bit 0 set)
...
</Cluster>Figure 18: SimpleBlock with a Frame That References No Other Frame, with the EBML Tree Shown as XML
There may be cases where you NEED a BlockGroup, bestie 😭 like when the frame needs a BlockDuration, BlockAdditions, CodecState, or DiscardPadding element. For those cases, a SimpleBlock MUST NOT be used; the reference information SHOULD be recovered for non-RAP frames 🧚
<Cluster>
<Timestamp>123456</Timestamp>
<SimpleBlock/> (octet 3 bit 0 not set)
...
</Cluster>Figure 19: SimpleBlock with a Frame That References Another Frame, with the EBML Tree Shown as XML
<Cluster>
<Timestamp>123456</Timestamp>
<BlockGroup>
<!-- ReferenceBlock value recovered based on the codec -->
<ReferenceBlock>-40</ReferenceBlock>
<BlockDuration>20</BlockDuration>
<Block/>
</BlockGroup>
...
</Cluster>Figure 20: 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 ReferenceBlocks MUST be used in one of the following ways: 💖
- each reference frame listed as a ReferenceBlock,
- some referenced frames listed as a ReferenceBlock, even if the timestamp value is accurate, or
- one ReferenceBlock with the timestamp value "0" corresponding to a self or unknown reference.
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. 💀 So like, don't skip it!!
<Cluster>
<Timestamp>123456</Timestamp>
<BlockGroup>
<!-- ReferenceBlock value not recovered from the codec -->
<ReferenceBlock>0</ReferenceBlock>
<BlockDuration>20</BlockDuration>
<Block/>
</BlockGroup>
...
</Cluster>Figure 21: Same Frame That References Another Frame Put inside a BlockGroup, but the Reference Could Not Be Recovered, with the EBML Tree Shown as XML
<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 22: BlockGroup with a Frame That References Two Other Frames, with the EBML Tree Shown as XML
Intra-only video frames, like the ones found in AV1 or VP9, can be decoded without any other frame, but they don't reset the codec state 🙈 So seeking to these frames is not possible, because the next frames may need frames that aren't known from that seeking point. Such intra-only frames MUST NOT be considered as keyframes, so the keyframe flag MUST NOT be set in the SimpleBlock, or a ReferenceBlock MUST be used to signify the frame is not a RAP. The timestamp value of the ReferenceBlock MUST be "0", meaning it's referencing itself 🪞
<Cluster>
<Timestamp>123456</Timestamp>
<BlockGroup>
<!-- References itself to mark it should not be used as RAP -->
<ReferenceBlock>0</ReferenceBlock>
<Block/>
</BlockGroup>
...
</Cluster>Figure 23: 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's possible to remux a video track using BlockGroup into a SimpleBlock, as long as it doesn't use any other BlockGroup features than ReferenceBlock 🎀
11. Timestamps ⏰
okay so 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. Oops, naming moment 🙃
11.1. Timestamp Ticks ⏱️
All timestamp values in Matroska are expressed in multiples of a tick. They are usually stored as integers. There are three types of ticks possible: Matroska Ticks, Segment Ticks, and Track Ticks. 🍓
11.1.1. Matroska Ticks 💜
The timestamp value is stored directly in nanoseconds.
The elements storing values in Matroska Ticks/nanoseconds are:
- TrackEntry\DefaultDuration; defined in Section 5.1.4.1.13
- TrackEntry\DefaultDecodedFieldDuration; defined in Section 5.1.4.1.14
- TrackEntry\SeekPreRoll; defined in Section 5.1.4.1.26
- TrackEntry\CodecDelay; defined in Section 5.1.4.1.25
- BlockGroup\DiscardPadding; defined in Section 5.1.3.5.7
- ChapterAtom\ChapterTimeStart; defined in Section 5.1.7.1.4.3
- ChapterAtom\ChapterTimeEnd; defined in Section 5.1.7.1.4.4
11.1.2. Segment Ticks 🌈
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 * TimestampScaleThis allows for storage of smaller integer values in the elements.
When using the default value of "1,000,000" for TimestampScale, one Segment Tick represents one millisecond. ⭐
The elements storing values in Segment Ticks are:
- Cluster\Timestamp; defined in Section 5.1.3.1
- Info\Duration is stored as a floating-point, but the same formula applies; defined in Section 5.1.2.10
- CuePoint\CueTime; defined in Section 5.1.5.1.1
- CuePoint\CueTrackPositions\CueDuration; defined in Section 5.1.5.1.2.4
- CueReference\CueRefTime; defined in Section 5.1.5.1.1
11.1.3. Track Ticks 🦋
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 =
element value * TrackTimestampScale * TimestampScaleThis allows for storage of smaller integer values in the elements. The resulting floating-point values of the timestamps are still expressed in nanoseconds.
When using the default values of "1,000,000" for TimestampScale and "1.0" for TrackTimestampScale, one Track Tick represents one millisecond. 🫶
The elements storing values in Track Ticks are:
- Cluster\BlockGroup\Block and Cluster\SimpleBlock timestamps; detailed in Section 11.2
- Cluster\BlockGroup\BlockDuration; defined in Section 5.1.3.5.3
- Cluster\BlockGroup\ReferenceBlock; defined in Section 5.1.3.5.5
When the TrackTimestampScale is interpreted as "1.0", Track Ticks are equivalent to Segment Ticks 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. Thus, using a value other than "1.0" might not work in many places. 👑
11.2. 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. This is also known as the Presentation Timestamp (PTS). ✨
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 ) ) *
TimestampScaleThe 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 subtracted 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 ) ) *
TimestampScale ) - CodecDelayThe resulting frame timestamp SHOULD NOT be negative. 🙃
During playback, when a frame has a negative timestamp, the content MUST be decoded by the decoder but not played to the user. 🤫
11.3. TimestampScale Rounding 🔢
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. 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 to have a more refined timestamp precision per frame. 🧚
12. Language Codes ✨
okay so 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 that same 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 the 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 [RFC5646] form is RECOMMENDED 💖. The Language elements in the [RFC5646] form are the 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 👑. Main character energy for the newer form, ngl 💅.
In this document, "BCP47" in element names refers specifically to [RFC5646], which is part of BCP 47 🧚.
13. Country Codes
Country codes are the [RFC5646] two-letter region subtags, without the UK exception 🌍✨.
14. Encryption 🔐
okay this one is serious bestie, so read carefully 🫶. This Matroska specification provides no interoperable solution for securing the data container with any assurances of confidentiality, integrity, authenticity, or authorization 💀. The ContentEncryption element (Section 5.1.4.1.31.8) and its associated sub-fields (Section 5.1.4.1.31.9 to Section 5.1.4.1.31.12) 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 fields to secure a Matroska data container is out of scope, as are any related 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 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 🌸.
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 💜.
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 🫶.
The algorithms described in Table 24 support different modes of operations and key sizes. The specification of these 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) 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]. It uses AES-CTR, ContentEncAlgo = 5 (Section 5.1.4.1.31.9), and AESSettingsCipherMode = 1 (Section 5.1.4.1.31.12) 💅.
A Matroska Writer MUST NOT use insecure cryptographic algorithms to create new archives or streams, but a Matroska Reader MAY support these algorithms to read previously made archives or streams. 💀 Do not make new archives with insecure crypto, periodt!
15. Image Presentation 📺
15.1. Cropping ✂️
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 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 🌈.
For example, a pillar-boxed video that stores a 1440x1080 visual image within the center of a padded 1920x1080 encoded image may set both PixelCropLeft and PixelCropRight to "240", so a Matroska Player should crop off 240 columns of pixels from the left and right of the encoded image to present the image with the pillar-boxes hidden 🧚.
Cropping has to be performed before resizing, and the display dimensions given by DisplayWidth, DisplayHeight, and DisplayUnit apply to the already-cropped image 💖.
15.2. Rotation 🔄
The ProjectionPoseRoll element (Section 5.1.4.1.28.46) 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 (Section 5.1.4.1.28.41) 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 🌸:
<Projection>
<ProjectionPoseRoll>90</ProjectionPoseRoll>
</Projection>Figure 24: Rotation Example 🎀
16. 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 EBML Header, do not have a Segment Position 🙃.
16.1. Segment Position Exception
Elements that are defined to store a Segment Position MAY define reserved values to indicate a special meaning 🎈.
16.2. 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" ✨.
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
0 |1A|45|DF|A3|8B|42|82|88|6D|61|74|72|6F|73|6B|61|
^ EBML Header
0 | |18|53|80|67|
^ Segment ID
20 |93|
^ Segment Data Size
20 | |15|49|A9|66|8E|4D|80|84|69|65|74|66|57|41|84|69|65|74|66|
^ Start of Segment data
20 | |4D|80|84|69|65|74|66|57|41|84|69|65|74|66|
^ MuxingApp startIn 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" 🧮💖.
17. Linked Segments 🔗
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 🦋.
All Segments within a Linked Segment MUST have a SegmentUUID 🆔.
All Segments within a Linked Segment SHOULD be stored within the same directory or be quickly accessible based on their SegmentUUID in order to have a seamless transition between segments 🏃♀️💨.
All Segments within a Linked Segment MAY set a SegmentFamily with a common value to make 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 🩹💅.
17.1. Hard Linking ✨
okay so Hard Linking (also called "splitting" 🔪🍰) is how you make a Linked Segment by tying several Segment elements together using the NextUUID and PrevUUID elements. bestie, this is giving puzzle-piece energy 🧩
All Segments in a Hard Linked Segment MUST use the same Tracks list and TimestampScale. no cap, they have to match 💅
Inside a Linked Segment, the timestamps of Block and SimpleBlock MUST pick up right where the previous Segment's Block and SimpleBlock left off, following the linking order. it's a whole relay race 🏃♀️💨
With Hard Linking, the chapters of any Segment in the Linked Segment MUST only reference the current Segment. The NextUUID and PrevUUID elements are the ones that point at the SegmentUUID values of the next and previous Segments. so the chapters stay in their lane and the links do the talking 🦋
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 ends of the chain are literally the ends, periodt 💀
For each node in the chain of Segments in a Linked Segment, at least one Segment MUST reference the other Segment in the chain. everybody needs a buddy in the chain 🫶
In a chain of Segments, NextUUID always takes precedence over PrevUUID. so if SegmentA has a NextUUID pointing at SegmentB, and SegmentB has a PrevUUID pointing at SegmentC, the link you use is the NextUUID between SegmentA and SegmentB, and SegmentC is not part of the Linked Segment. the NextUUID is the main character here 👑
If SegmentB has a PrevUUID pointing at SegmentA, but SegmentA has no NextUUID, then the Matroska Player MAY consider the two Segments linked as SegmentA followed by SegmentB. it's optional vibes, not a must 🌸
As an example, three Segments can be Hard Linked into one Linked Segment by cross-referencing each other with SegmentUUID, PrevUUID, and NextUUID. here's the lineup 🍓
+==========+================+==================+==================+
|file name |SegmentUUID | PrevUUID | NextUUID |
+==========+================+==================+==================+
|start.mkv |71000c23cd310998| Invalid | a77b3598941cb803 |
| |53fbc94dd984a5dd| | eac0fcdafe44fac9 |
+----------+----------------+------------------+------------------+
|middle.mkv|a77b3598941cb803| 71000c23cd310998 | 6c92285fa6d3e827 |
| |eac0fcdafe44fac9| 53fbc94dd984a5dd | b198d120ea3ac674 |
+----------+----------------+------------------+------------------+
|end.mkv |6c92285fa6d3e827| a77b3598941cb803 | Invalid |
| |b198d120ea3ac674| eac0fcdafe44fac9 | |
+----------+----------------+------------------+------------------+
Table 40: Usual Hard Linking UIDshere's one where only NextUUID is used, so the chain only goes forwards 🏃♀️➡️
+============+==================+==========+==================+
| file name | SegmentUUID | PrevUUID | NextUUID |
+============+==================+==========+==================+
| start.mkv | 71000c23cd310998 | Invalid | a77b3598941cb803 |
| | 53fbc94dd984a5dd | | eac0fcdafe44fac9 |
+------------+------------------+----------+------------------+
| middle.mkv | a77b3598941cb803 | n/a | 6c92285fa6d3e827 |
| | eac0fcdafe44fac9 | | b198d120ea3ac674 |
+------------+------------------+----------+------------------+
| end.mkv | 6c92285fa6d3e827 | n/a | Invalid |
| | b198d120ea3ac674 | | |
+------------+------------------+----------+------------------+
Table 41: Hard Linking without PrevUUIDand here's one where only PrevUUID is used, so the chain only goes backwards 🔙
+============+==================+==================+==========+
| file name | SegmentUUID | PrevUUID | NextUUID |
+============+==================+==================+==========+
| start.mkv | 71000c23cd310998 | Invalid | n/a |
| | 53fbc94dd984a5dd | | |
+------------+------------------+------------------+----------+
| middle.mkv | a77b3598941cb803 | 71000c23cd310998 | n/a |
| | eac0fcdafe44fac9 | 53fbc94dd984a5dd | |
+------------+------------------+------------------+----------+
| end.mkv | 6c92285fa6d3e827 | a77b3598941cb803 | Invalid |
| | b198d120ea3ac674 | eac0fcdafe44fac9 | |
+------------+------------------+------------------+----------+
Table 42: Hard Linking without NextUUIDlast one, and it's a mix 🌈 only middle.mkv is using both PrevUUID and NextUUID:
+==========+================+==================+==================+
|file name |SegmentUUID | PrevUUID | NextUUID |
+==========+================+==================+==================+
|start.mkv |71000c23cd310998| Invalid | n/a |
| |53fbc94dd984a5dd| | |
+----------+----------------+------------------+------------------+
|middle.mkv|a77b3598941cb803| 71000c23cd310998 | 6c92285fa6d3e827 |
| |eac0fcdafe44fac9| 53fbc94dd984a5dd | b198d120ea3ac674 |
+----------+----------------+------------------+------------------+
|end.mkv |6c92285fa6d3e827| n/a | Invalid |
| |b198d120ea3ac674| | |
+----------+----------------+------------------+------------------+
Table 43: Hard Linking with Mixed UID Links17.2. Medium Linking 🎬
Medium Linking is about making relationships between Segments with Ordered Chapters (Section 20.1.3) and the ChapterSegmentUUID element. a Chapter Edition with Ordered Chapters MAY have Chapters elements that point at timestamp ranges from other Segments. the Segment that an Ordered Chapter points at through ChapterSegmentUUID SHOULD be played as part of a Linked Segment. it's giving collab energy 🤝
The timestamps of Segment content referenced by Ordered Chapters MUST be adjusted by the cumulative duration of the previous Ordered Chapters. the clock keeps running across the chapters, bestie ⏱️
Here's an example. a file called intro.mkv could have a SegmentUUID of "0xb16a58609fc7e60653a60c984fc11ead". Another file called program.mkv could use a Chapter Edition with two Ordered Chapters. The first chapter points at the intro.mkv Segment using ChapterSegmentUUID, ChapterSegmentEditionUID, ChapterTimeStart, and an optional ChapterTimeEnd. The second chapter points at content inside the program.mkv Segment. A Matroska Player SHOULD recognize the Linked Segment made by ChapterSegmentUUID in an enabled Edition and present the referenced content from both Segments as one presentation 🍿✨
The ChapterSegmentUUID stands for 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. no pointing at yourself, that's just awkward 🙈
There are two ways to use a chapter link:
- Linked-Duration linking
- Linked-Edition linking
17.2.1. Linked-Duration ⏳
A Matroska Player MUST play the content of the Linked Segment from the ChapterTimeStart until the ChapterTimeEnd timestamp, in place of the Linked Chapter. slice and play 🍰
ChapterTimeStart and ChapterTimeEnd are timestamps in the Linked Segment that matches the value of ChapterSegmentUUID. Their values MUST be in the range of the Linked Segment duration. they can't wander off outside the Segment, no cap 🚫
The ChapterTimeEnd value MUST be set when you use Linked-Duration chapter linking. ChapterSegmentEditionUID MUST NOT be set. so for this one, ChapterTimeEnd is required and the Edition ID stays empty 💅
17.2.2. Linked-Edition 📚
A Matroska Player MUST play the whole Linked Edition of the Linked Segment in place of the Linked Chapter. the entire season, not just one episode 📺
ChapterSegmentEditionUID represents a valid Edition from the Linked Segment that matches the value of ChapterSegmentUUID. valid is the keyword here ✔️
When you use Linked-Edition chapter linking, ChapterTimeEnd is OPTIONAL. so you can skip it if you want, no drama 🌷
18. Track Flags 🚩
18.1. Default Flag 💖
The Default flag is a hint for a Matroska Player saying that a given track SHOULD be eligible to be picked automatically as the default track for a given 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 is the "regular service" flag, the everyday track that works for people on default settings, as opposed to specialized stuff like commentary, captions for users with hearing impairments, or descriptive audio 🎧
The Matroska Player MAY override the Default flag for any reason, including user preferences that favour tracks providing accessibility services. user choice always wins, babe 🫶
18.2. Forced Flag 🗣️
The Forced flag tells the Matroska Player that it SHOULD display this subtitle track, even when user preferences usually wouldn't call for any subtitles alongside the audio track that's currently selected. this one is for translations of on-screen text or dialogue spoken in a different language from the track's main language. the "wait, what did they say" saver 😭
18.3. Hearing-Impaired Flag 👂
The Hearing-Impaired flag tells the Matroska Player that it SHOULD prefer this track when choosing a default track for a user with a hearing impairment, and that it MAY prefer a different track when choosing a default track for a user who is not hearing impaired. accessibility is giving main character energy 🌈
18.4. Visual-Impaired Flag 👁️
The Visual-Impaired flag tells the Matroska Player that it SHOULD prefer this track when choosing a default track for a user with a visual impairment, and that it MAY prefer a different track when choosing a default track for a user who is not visually impaired. same vibe, different sense 💜
18.5. Descriptions Flag 🔊
The Descriptions flag tells the Matroska Player that this track is suitable to play through a text-to-speech system for a user with a visual impairment. It also tells the player that it SHOULD NOT automatically select this track when choosing a default track for a user who is not visually impaired. so no, this one doesn't just jump in uninvited 🙅♀️
18.6. Original Flag 🎞️
The Original flag tells the Matroska Player that this track is in the original language, and that it SHOULD prefer this track if it's set up to prefer original-language tracks of this track's type. the OG track, iconic 👑
18.7. Commentary Flag 🎙️
The Commentary flag tells the Matroska Player that this track contains commentary on the content. director's cut chat, basically 🍿
18.8. Track Operation 🧩
TrackOperation lets you combine multiple tracks to make a virtual one. It uses two separate systems to do this. One creates a 3D "composition" (left, right, and background planes), and the other simply joins two tracks together to make a single track. two mechanisms, one glow-up ✨
A track made with TrackOperation is a proper track, with its own UID and all of 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 codec ID is basically a placeholder here, not the real deal 🙃 The Cues elements for such a virtual track SHOULD be the union of the Cues elements for each of the tracks it's made from (when the Cues are defined per track). it's the group photo of all the Cues 📸
For 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 system to either drop some of these frames or render them the way they overlap. This situation SHOULD be avoided when creating such tracks, because you can never be sure of the end result on different platforms. overlapping blocks are a little chaotic, so just don't create that mess 😅💀
18.9. Overlay Track 🪄
An overlay track SHOULD be rendered in the same channel as the track it's linked to. When content shows up in such a track, it SHOULD be played on the rendering channel instead of the original track. it's a picture-in-picture moment, and it takes the spotlight 🦋💫
18.10. Multi-planar and 3D Videos ✨
okay so there are two ways to compress 3D videos 🎬: either each eye gets its own track, or one track has both eyes squished together inside (which is more efficient compression-wise 🧠). Matroska supports both, bestie 💖
For the single-track variant, there's the StereoMode element 🎀. It defines how the planes get assembled in the track (mono or left-right combined). Odd values of StereoMode mean the left plane comes first, which is more convenient for reading 👀. The pixel count of the track (PixelWidth/PixelHeight) is the raw number of pixels (like 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 🕶️), so for compatibility with those, there's a value of StereoMode that corresponds to anaglyph.
There's also a "packed" mode (values 13 and 14) that's giving main character energy 🦋. It packs two frames together in a Block that uses lacing. The first frame is the left eye and the other frame is the right eye (or vice versa). The frames SHOULD be decoded in that order, and they're possibly dependent on each other (P and B frames) 🔥.
For separate tracks, Matroska needs to define exactly which track does what 🧚. That's what TrackOperation with TrackCombinePlanes is for. For more details, see Section 18.8 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 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 (Section 5.1.4.1.28.5). 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, so don't mix them up, babe 🙈.
19. Default Track Selection 🎬
this section gives some example sets of Tracks and hypothetical user settings, plus indications of which ones a similarly configured Matroska Player SHOULD automatically select for playback by default 👑. A player MAY provide additional settings with more detailed controls for more nuanced scenarios. These examples are guidelines that show 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 in the language of each track, or provide titles in multiple languages 🌈.
19.1. Audio Selection 🎧
Example track set:
+===+=====+====+======+========+=======+===============+===========+
|No.|Type |Lang|Layout|Original|Default|Other Flags |Name |
+===+=====+====+======+========+=======+===============+===========+
|1 |Video|und |N/A |N/A |N/A |None | |
+---+-----+----+------+--------+-------+---------------+-----------+
|2 |Audio|eng |5.1 |1 |1 |None | |
+---+-----+----+------+--------+-------+---------------+-----------+
|3 |Audio|eng |2.0 |1 |1 |None | |
+---+-----+----+------+--------+-------+---------------+-----------+
|4 |Audio|eng |2.0 |1 |0 |Visual-Impaired|Descriptive|
| | | | | | | |audio |
+---+-----+----+------+--------+-------+---------------+-----------+
|5 |Audio|esp |5.1 |0 |1 |None | |
+---+-----+----+------+--------+-------+---------------+-----------+
|6 |Audio|esp |2.0 |0 |0 |Visual-Impaired|Descriptive|
| | | | | | | |audio |
+---+-----+----+------+--------+-------+---------------+-----------+
|7 |Audio|eng |2.0 |1 |0 |Commentary |Director's |
| | | | | | | |Commentary |
+---+-----+----+------+--------+-------+---------------+-----------+
|8 |Audio|eng |2.0 |1 |0 |None |Karaoke |
+---+-----+----+------+--------+-------+---------------+-----------+
Table 44: Audio Tracks for Default Selectionthe table above shows a file with seven audio tracks, five in English and two in Spanish 🇪🇸🇬🇧. (Yes, there are eight rows, but row 4 and row 6 are wrapped, so count the vibes, not the rows 😅.)
The English tracks all have the Original flag, which means English is the original content language 🎞️.
Generally, the player will first look at 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 the user has configured the player to specifically prefer audio tracks in English or Spanish, the player should select one of the tracks in that 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 🌸.
Two of the tracks have the Visual-Impaired flag. If the player has been configured to prefer such tracks, it should select one. Otherwise, it should avoid them if possible 🫶.
If you're selecting an English track and other settings still leave multiple options, it may be useful to exclude the tracks that lack the Default flag ✨. Here's the breakdown: one track provides descriptive service for individuals with visual impairments. That one has its own flag and may be automatically selected by user configuration, but it's unsuitable for users with default-configured players 🙈. One track is a commentary track, which has its own flag, and the player may or may not have specialized handling for it 🎙️. The last one contains karaoke versions of the music that plays during the film. That's an unusual specialized audio service, and Matroska has no built-in support for indicating it, so it's indicated in the track name instead 🎤. By not setting the Default flag on these specialized tracks, the file's author hints that they should not be automatically selected by a default-configured player 💅.
Having narrowed its choices down, the example player may now have to choose between tracks 2 and 3. The only difference between these tracks is their channel layouts: 2 is 5.1 surround, while 3 is stereo. If the player knows the output device is a pair of headphones or stereo speakers, it may wish to prefer the stereo mix automatically 🎧. On the other hand, if it knows the device is a surround system, it may wish to prefer the surround mix 🔊.
If the player finishes analyzing all of the available audio tracks and finds that more than one seems equally and maximally preferable, it SHOULD default to the first of the group 🏁.
19.2. Subtitle Selection 💬
Example track set:
+===+=========+====+========+=======+======+========+==============+
|No.|Type |Lang|Original|Default|Forced|Other | Name |
| | | | | | |Flags | |
+===+=========+====+========+=======+======+========+==============+
|1 |Video |und |N/A |N/A |N/A |None | |
+---+---------+----+--------+-------+------+--------+--------------+
|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-| Captions for |
| | | | | | |Impaired| 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-| SDH |
| | | | | | |Impaired| |
+---+---------+----+--------+-------+------+--------+--------------+
Table 45: Subtitle Tracks for Default Selectionthe table above shows two audio tracks and five subtitle tracks. As we can see, French is the original language 🥖.
Let's start with the case where the user prefers French (or original-language) audio, or has explicitly selected the French audio track, and also prefers French subtitles 🇫🇷.
In this case, if the player isn't configured to display captions when the audio matches their preferred subtitle languages, the player doesn't need to select a subtitle track at all 🙌.
If the user _has_ indicated that they want captions displayed, the selection simply comes down to whether hearing-impaired subtitles are preferred 🦻.
The situation for a user who prefers Portuguese subtitles starts out somewhat analogous. If they select the original French audio (through an explicit audio language preference, a preference for original-language tracks, or by explicitly selecting that track), then the selection once again comes down to the hearing-impaired preference 🔁.
However, the case where the Portuguese audio track is selected has an important catch: a Forced track in Portuguese is present 👀. It may contain translations of on-screen text from the video track, or of portions of the audio that are not translated (music, for instance) 🎶. This means that even if the user's preferences wouldn't normally call for captions here, the Forced track should be selected anyway, rather than selecting no track at all 💡. On the other hand, if the user's preferences _do_ call for captions, the non-Forced tracks should be preferred, because the Forced track will not contain captioning for the dialogue 🫠.
20. Chapters 📖
The Matroska Chapters system can have multiple Editions. Each Edition can consist of Simple Chapters, where a chapter start time is used only as a marker in the timeline. 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 structure borrowed from the DVD-menu system [DVD-Video], or have its own built-in Matroska menu structure 📺.
20.1. 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 💜.
20.1.1. EditionFlagDefault 🌟
Only one Edition SHOULD have an EditionFlagDefault flag set to true ✅.
20.1.2. Default Edition
okay so the Default Edition is the Edition a Matroska Player SHOULD use for playback by default 💖 it's the one that gets picked first, bestie 🎀
The first Edition with the EditionFlagDefault flag set to true is the Default Edition ✨
When every EditionFlagDefault flag is set to false, the first Edition becomes the Default Edition. that's the fallback, and it's lowkey iconic 💅
+===========+=============+=================+
| Edition | FlagDefault | Default Edition |
+===========+=============+=================+
| Edition 1 | true | X |
+-----------+-------------+-----------------+
| Edition 2 | true | |
+-----------+-------------+-----------------+
| Edition 3 | true | |
+-----------+-------------+-----------------+
Table 46: Default Edition, All Default
+===========+=============+=================+
| Edition | FlagDefault | Default Edition |
+===========+=============+=================+
| Edition 1 | false | X |
+-----------+-------------+-----------------+
| Edition 2 | false | |
+-----------+-------------+-----------------+
| Edition 3 | false | |
+-----------+-------------+-----------------+
Table 47: Default Edition, No Default
+===========+=============+=================+
| Edition | FlagDefault | Default Edition |
+===========+=============+=================+
| Edition 1 | false | |
+-----------+-------------+-----------------+
| Edition 2 | true | X |
+-----------+-------------+-----------------+
| Edition 3 | false | |
+-----------+-------------+-----------------+
Table 48: Default Edition, With Default20.1.3. EditionFlagOrdered
the EditionFlagOrdered flag is a big deal 🦋 it turns on an Edition of Ordered Chapters, which builds and arranges a virtual timeline instead of just dropping labels on points in the timeline. so picture this: one Matroska file can show off multiple cuts of a film without copying the content over and over 🎬
or say you digitized a whole videotape. one Ordered Edition could play everything (colorbars, countdown, slate, the feature, black frames), while another Ordered Edition uses Chapters that skip the colorbars and other extra visuals and only cover the actual presentation 🌸
if an Edition of Ordered Chapters is enabled, the Matroska Player MUST play those Chapters in their stored order, starting from the timestamp marked in the ChapterTimeStart element and ending at the timestamp marked in to ChapterTimeEnd element 🫶
if the EditionFlagOrdered flag evaluates to "0", then Simple Chapters are used, and only the ChapterTimeStart of a Chapter gets used as a chapter mark, which is basically a jump to a predefined point in the timeline ⭐ with Simple Chapters, a Matroska Player MUST ignore certain elements inside a Chapters element. those elements are informational only, so they're just vibes 🙈
these are the Chapters elements that only show up in Ordered Chapters 👑
ChapterAtom\ChapterSegmentUUIDChapterAtom\ChapterSegmentEditionUIDChapterAtom\ChapProcessInfo\ChapterTranslateTrackEntry\TrackTranslate
and there are other EBML elements that can be used when EditionFlagOrdered evaluates to "1" too 🧚
20.1.3.1. Ordered-Edition and Matroska Segment Linking
- Hard Linking: Ordered Chapters supersede the Hard Linking. ooh, so Ordered Chapters take over here 👑
- Medium Linking: Ordered Chapters are used in a normal way and can be combined with the
ChapterSegmentUUIDelement, which establishes a link to another Segment 🦋
check out Section 17 on Linked Segments for more on Hard Linking and Medium Linking 💜
20.2. ChapterAtom
the ChapterAtom is also called a Chapter 🍓
20.2.1. ChapterTimeStart
ChapterTimeStart is the timestamp of the start of a Chapter, with nanosecond accuracy 🌈 it is not scaled by TimestampScale. for Simple Chapters, this is where the chapter markers sit on the timeline ⭐
20.2.2. ChapterTimeEnd
ChapterTimeEnd is the timestamp of the end of a Chapter, also with nanosecond accuracy, and it's not scaled by TimestampScale either 💅 the timestamp defined by ChapterTimeEnd is NOT part of the Chapter (okay that's a little plot twist 😭). a Matroska Player works out the duration of this Chapter by taking the difference between ChapterTimeEnd and ChapterTimeStart. the end timestamp MUST be greater than or equal to the start timestamp, no exceptions 🔥
when ChapterTimeEnd is equal to ChapterTimeStart, the timestamp is included in the Chapter. this is handy for dropping markers into a file or adding chapter commands in Ordered Chapters without having to play anything 🙈 see Section 5.1.7.1.4.14 for that.
+===========+=================+===============+===============+
| Chapter | Start timestamp | End timestamp | Duration |
+===========+=================+===============+===============+
| Chapter 1 | 0 | 1000000000 | 1000000000 |
+-----------+-----------------+---------------+---------------+
| Chapter 2 | 1000000000 | 5000000000 | 4000000000 |
+-----------+-----------------+---------------+---------------+
| Chapter 3 | 6000000000 | 6000000000 | 0 |
+-----------+-----------------+---------------+---------------+
| Chapter 4 | 9000000000 | 8000000000 | Invalid |
| | | | (-1000000000) |
+-----------+-----------------+---------------+---------------+
Table 49: ChapterTimeEnd Usage Possibilities20.2.3. Nested Chapters
a ChapterAtom element can hold other ChapterAtom elements inside it 🪆 the outer one is a Parent Chapter, and the ChapterAtom elements it holds are Nested Chapters.
Nested Chapters are great for tagging tiny parts of a Segment that already have tags, or for adding Chapter Codec commands to smaller bits 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 ✨
if the Parent Chapter of a Nested Chapter has a ChapterTimeEnd, then the ChapterTimeStart of that Nested Chapter MUST be smaller than or equal to the ChapterTimeEnd of the Parent Chapter 🎀
20.2.4. Nested Chapters in Ordered Chapters
the ChapterTimeEnd of the lowest level of Nested Chapters MUST be set for Ordered Chapters 🫶
when Ordered Chapters are involved, the ChapterTimeEnd of a Parent Chapter is useless for playback, because the real playback sections are described in its Nested Chapters 🙄 so the ChapterTimeEnd SHOULD NOT be set in Parent Chapters, and a Matroska Player MUST ignore it for playback. bye bye, Parent end time 👋
20.2.5. ChapterFlagHidden
each Chapter's ChapterFlagHidden flag works independently of its Parent Chapters 🦋 a Nested Chapter whose ChapterFlagHidden flag evaluates to "0" stays visible in the user interface, even if the Parent Chapter's ChapterFlagHidden flag is set to "1". main character energy for the kid 👑
+==========================+===================+=========+
| Chapter + Nested Chapter | ChapterFlagHidden | visible |
+==========================+===================+=========+
| Chapter 1 | 0 | yes |
+--------------------------+-------------------+---------+
| Nested Chapter 1.1 | 0 | yes |
+--------------------------+-------------------+---------+
| Nested Chapter 1.2 | 1 | no |
+--------------------------+-------------------+---------+
| Chapter 2 | 1 | no |
+--------------------------+-------------------+---------+
| Nested Chapter 2.1 | 0 | yes |
+--------------------------+-------------------+---------+
| Nested Chapter 2.2 | 1 | no |
+--------------------------+-------------------+---------+
Table 50: ChapterFlagHidden Nested Visibility20.3. Menu Features
the menu features are handled just like a chapter codec 💜 so each codec has a type, 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 stored in ChapProcessPrivate and ChapProcessData depends on what ChapProcessCodecID is set to.
the menu system, along with Chapter Codecs in general, can do stuff to the Matroska Player, like jumping to another Chapter or Edition, selecting different tracks, and possibly more 🧚 the full scope of what Chapter Codecs can do isn't covered in this document, since it depends on the Chapter Codec features and how they're integrated into a Matroska Player 🌸
20.4. Physical Types
each level can mean something different for audio and video 🎧 the ORIGINAL_MEDIA_TYPE tag [MatroskaTags] can be used to specify a string for ChapterPhysicalEquiv = 60. here's the list of possible levels for both audio and video 🍓
+=======+=======================+=============+=====================+
| Value | Audio | Video | Comment |
+=======+=======================+=============+=====================+
| 70 | SET / PACKAGE | SET / | the collection of |
| | | PACKAGE | different media |
+-------+-----------------------+-------------+---------------------+
| 60 | CD / 12" / 10" / 7" / | DVD / VHS | the physical medium |
| | TAPE / MINIDISC / DAT | / | like a CD or a DVD |
| | | LASERDISC | |
+-------+-----------------------+-------------+---------------------+
| 50 | SIDE | SIDE | when the original |
| | | | medium (LP/DVD) has |
| | | | different sides |
+-------+-----------------------+-------------+---------------------+
| 40 | - | LAYER | another physical |
| | | | level on DVDs |
+-------+-----------------------+-------------+---------------------+
| 30 | SESSION | SESSION | as found on CDs and |
| | | | DVDs |
+-------+-----------------------+-------------+---------------------+
| 20 | TRACK | - | as found on audio |
| | | | CDs |
+-------+-----------------------+-------------+---------------------+
| 10 | INDEX | - | the first logical |
| | | | level of the side/ |
| | | | medium |
+-------+-----------------------+-------------+---------------------+
Table 51: ChapterPhysicalEquiv Meaning per Track Type20.5. Chapter Examples
20.5.1. Example 1: Basic Chaptering ✨
Okay bestie, picture a movie chopped into chapters 🎬. It could also just be an audio file (an album) where every track is its own chapter 🎵.
- 00000 ms - 05000 ms: Intro
- 05000 ms - 25000 ms: Before the crime
- 25000 ms - 27500 ms: The crime
- 27500 ms - 38000 ms: After the crime
- 38000 ms - 43000 ms: Credits
Here's how that looks in Matroska form, with the EBML tree written out in XML 🧚:
<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 25: Basic Chapters Example
20.5.2. Example 2: Nested Chapters 🪆
This one's a little spicier 🌶️: an (existing) album gets split into chapters, and one of those chapters has its own splitting going on inside it.
20.5.2.1. The Micronauts "Bleep To Bleep" 🎀
- 00:00 - 12:28: Baby wants to Bleep/Rock
- 00:00 - 04:38: Baby wants to bleep (pt.1)
- 04:38 - 07:12: Baby wants to rock
- 07:12 - 10:33: Baby wants to bleep (pt.2)
- 10:33 - 12:28: Baby wants to bleep (pt.3)
- 12:30 - 19:38: Bleeper_O+2
- 19:40 - 22:20: Baby wants to bleep (pt.4)
- 22:22 - 25:18: Bleep to bleep
- 25:20 - 33:35: Baby wants to bleep (k)
- 33:37 - 44:28: Bleeper
Now the Matroska version, with the EBML tree in XML again 💜:
<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 26: Nested Chapters Example
21. Attachments 📎
Matroska has a whole cute spot for related files and data: the Attachments element (a Top-Level Element) 🗂️. Attachments elements can hold cover art, font files, transcripts, reports, error recovery files, pictures, text-based annotations, copies of specifications, or other ancillary files related to the Segment. So much stuff, bestie 🥹.
Matroska Readers MUST NOT execute files stored as Attachments elements. Please don't run anything you find in there 🙅♀️💀
21.1. Cover Art 🖼️
This section is all about the guidelines for storing cover art in Matroska files 💅. A Matroska Reader MAY use embedded cover art to display a representational still-image depiction of the multimedia contents of the Matroska file ✨.
Only [JPEG] and PNG [RFC2083] image formats SHOULD be used for cover art pictures 📸.
There can be two different covers for a movie or album: a portrait style (like a DVD case) and a landscape style (like a wide banner ad) 🎞️.
There can also be two versions of the same cover: the normal cover and the small cover. The dimension of the normal cover SHOULD be 600 pixels on the smallest side (for example 960x600 for landscape, 600x800 for portrait, or 600x600 for square). The dimension of the small cover SHOULD be 120 pixels on the smallest side (for example 192x120 or 120x160) 🌸.
Versions of cover art can be told apart 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 Attachments element in storage order. The small cover SHOULD be prefixed with "small_", like small_cover.(jpg|png). The landscape variant SHOULD be suffixed with "_land", like cover_land.(jpg|png). The filenames are case-sensitive, so be careful with your capitals 🔠💖.
The following table gives examples of file names for cover art in Attachments 🦋:
+======================+===================+=================+
| File Name | Image Orientation | Pixel Length of |
| | | Smallest Side |
+======================+===================+=================+
| cover.jpg | Portrait or | 600 |
| | square | |
+----------------------+-------------------+-----------------+
| small_cover.png | Portrait or | 120 |
| | square | |
+----------------------+-------------------+-----------------+
| cover_land.png | Landscape | 600 |
+----------------------+-------------------+-----------------+
| small_cover_land.jpg | Landscape | 120 |
+----------------------+-------------------+-----------------+Table 52: Cover Art Filenames
21.2. Font Files ✨
Okay bestie, so font files 🎀 A font file MAY be added to a Matroska file as an Attachment, so the subtitle track can show it. That keeps the presentation looking the same in different environments, even when the needed fonts aren't installed on the local system. Consistency is everything 💅
Depending on the font format, one font file can hold multiple font variants 🌈 Each variant has a name we'll call the Font Name from here on. The Font Name can be different from the Attachment's FileName, even if you ignore the extension. To pick a font for display, a Matroska Player SHOULD look at both the Font Name and the base name of the Attachment's FileName, and it should prefer the Font Name when there are multiple matches 🧚
Subtitle codecs like SubStation Alpha (SSA) and Advanced SubStation Alpha (ASS) usually refer to a font by its Font Name, not its filename 🙈 So if none of the Attachments match the Font Name, the Matroska Player SHOULD try to find a system font whose Font Name matches the one the subtitle track uses.
Loading fonts temporarily can take a while, so a Matroska Player usually loads or installs all the fonts found in attachments so they're ready during playback 🫶 Skipping the font attachment might mess up how the subtitles get rendered 😭
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:
font/sfnt: Generic SFNT Font Typefont/ttf: TrueType Font (TTF) Font Typefont/otf: OpenType Layout (OTF) Font Typefont/collection: Collection Font Typefont/woff: WOFF 1.0font/woff2: WOFF 2.0
Fonts in Matroska existed long before [RFC8081] 🕰️ A few unofficial media types for fonts showed up in existing files. 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 tofont/ttfand sometimesfont/otfapplication/x-font-ttf: TrueType fonts, equivalent tofont/ttfapplication/vnd.ms-opentype: OpenType Layout fonts, equivalent tofont/otfapplication/font-sfnt: Generic SFNT Font Type, equivalent tofont/sfntapplication/font-woff: WOFF 1.0, equivalent tofont/woff
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. Common file extensions for fonts are:
.ttffor TrueType fonts, equivalent tofont/ttf.otffor OpenType Layout fonts, equivalent tofont/otf.ttcfor Collection fonts, equivalent tofont/collection
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. They MAY use the media types found in older files when compatibility with older players is necessary 💜
22. Cues
The Cues element is basically an index of certain Cluster elements, so seeking to absolute timestamps within the Segment can be optimized 🔥 The Cues element contains one or many CuePoint elements, and each of them 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 live in the CuePoint element too, like CueDuration, CueRelativePosition, CueCodecState, and others. These give any Matroska Reader extra info to make seeking faster ⭐
22.1. Recommendations
Here are the recommendations for making Matroska perform its best 🌸
- 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.
- It is RECOMMENDED to not reference non-keyframes of video tracks in Cues unless it references a Cluster element that contains a
CodecStateelement but no keyframes. - For each subtitle track present, each subtitle frame SHOULD be referenced by a CuePoint element with a
CueDurationelement. - 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
CueRelativePositionelement 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
CodecStateelement, then that CuePoint element MUST use aCueCodecStateelement. - CuePoint elements SHOULD be numerically sorted in storage order by the value of the
CueTimeelement.
23. Matroska Streaming
In Matroska, there are two kinds of streaming: file access and livestreaming 🎬
23.1. File Access
File access can be as simple as reading a file on your computer, but it also covers accessing a file from an HTTP (web) server or a Common Internet File System (CIFS) (Windows share) server. These protocols are usually safe from reading errors, and seeking in the stream is possible. However, when a file is stored far away or on a slow server, seeking can be expensive and should be avoided 🐢 If you follow the guidelines in Section 25, you can cut down on seeking for regular playback, and playback starts quickly without reading a lot of data first (like a Cues element, Attachments element, or SeekHead element) ⚡
Matroska has a small overhead, so it's well suited for storing music and videos on file servers without a big impact on bandwidth 🎶 Matroska does not require the index to be loaded before playing, which means playback can start super fast. The index can be loaded only when seeking is requested the first time 🦋
23.2. Livestreaming
Livestreaming is basically the TV broadcasting of the Internet 📺 There are two families of servers for livestreaming: RTP / Real-Time Streaming Protocol (RTSP) and HTTP. Matroska is not meant to be used over RTP, since RTP already has timing and channel mechanisms that would be wasted if doubled in Matroska. Having the same information at both the RTP and Matroska level would also be a source of confusion if they don't match 🙃 Livestreaming Matroska over file-like protocols like HTTP, QUIC, etc. is possible.
A live Matroska stream is different from a file because it usually has no known end (it only ends 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 with known sizes, one after the other. This solution allows a change of codec or resolution between each segment, so you can switch between 4:3 and 16:9 in a television program 📺✨
When Segment elements are continuous, certain elements (like SeekHead, Cues, Chapters, and Attachments) MUST NOT be used.
A Matroska Player can detect that a stream is not seekable 👀 If the stream has neither a SeekHead list nor a Cues list at the beginning of the stream, it SHOULD be considered non-seekable. Even though it is possible to seek forward in the stream, it is NOT RECOMMENDED.
In live radio or web TV, it's possible to "tag" the content while it's playing 🎙️ The Tags element can be placed between Clusters each time it's needed. In that case, the new Tags element MUST reset the previously encountered Tags elements and use the new values instead.
24. Tags
24.1. Tags Precedence
Tags let you tag 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 element (Section 5.1.4.1.18) or the ChapString element (Section 5.1.7.1.4.10).
The following Matroska elements can also be defined with tags:
- The track
Nameelement (Section 5.1.4.1.18) corresponds to a tag with theTagTrackUID(Section 5.1.8.1.1.3) set to the given track, aTagNameofTITLE(Section 5.1.8.1.2.1), and aTagLanguage(Section 5.1.8.1.2.2) orTagLanguageBCP47(Section 5.1.8.1.2.3) of"und". - The
ChapStringelement (Section 5.1.7.1.4.10) corresponds to a tag with theTagChapterUID(Section 5.1.8.1.1.5) set to the same chapter UID, aTagNameofTITLE(Section 5.1.8.1.2.1), and aTagLanguage(Section 5.1.8.1.2.2) orTagLanguageBCP47(Section 5.1.8.1.2.3) matching theChapLanguage(Section 5.1.7.1.4.11) orChapLanguageBCP47(Section 5.1.7.1.4.12), respectively. - The
FileDescriptionelement (Section 5.1.6.1.1) of an attachment corresponds to a tag with theTagAttachmentUID(Section 5.1.8.1.1.6) set to the given attachment, aTagNameofTITLE(Section 5.1.8.1.2.1), and aTagLanguage(Section 5.1.8.1.2.2) orTagLanguageBCP47(Section 5.1.8.1.2.3) 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 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 don't handle it, so they won't use the tag value when it's there 😭 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 💖
24.2. Tag Levels
Tag elements let you tag information on multiple levels, and each level has a TargetTypeValue (Section 5.1.8.1.1.1). An element for a given TargetTypeValue also applies to the lower levels, which are denoted by smaller TargetTypeValue values 🪜 If an upper value doesn't apply to a level but the actual value to use isn't known, an empty TagString (Section 5.1.8.1.2.5) or an empty TagBinary (Section 5.1.8.1.2.6) MUST be used as the tag value for this level.
See [MatroskaTags] for more details on common tag names, types, and descriptions 📚
25. Implementation Recommendations
25.1. Cluster
It is RECOMMENDED that each individual Cluster element contain no more than five seconds or five megabytes of content 🧁
25.2. SeekHead
It is RECOMMENDED that the first SeekHead element be followed by a Void element. That lets the SeekHead element expand 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 Tags, Chapters, and Attachments elements in the Matroska file.
25.3. Optimum Layouts
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.
25.3.1. Optimum Layout for a Muxer ✨
Okay bestie, this is the basic layout muxers should be using for an efficient playback experience 🎀
SeekHeadInfoTracksChaptersAttachmentsTagsClustersCues
25.3.2. Optimum Layout after Editing Tags 🧚
So when tags from the previous layout need to get extended, they get moved to the end with the extra info 💅 The spot where the old tags used to live gets voided, so it's a whole glow-up.
SeekHeadInfoTracksChaptersAttachmentsVoidClustersCuesTags
25.3.3. Optimum Layout with Cues at the Front 🦋
Cues are usually a big chunk of data that references a lot of locations in the file, and it's giving heavy 😭 Players that want to seek have to go all the way to the end of the file to reach those locations, so it's often better to put them early in the file. BUT 🙈 that means players that don't plan on seeking will have to read or skip that data no matter what.
Also, because the Cues point to locations further in the file, it's often complicated to allocate the right amount of space for that element before all the locations are known. So this layout is rarely used 💀
SeekHeadInfoTracksChaptersAttachmentsTagsCuesClusters
25.3.4. Optimum Layout for Livestreaming 🌈
In livestreaming (Section 23.2), only a few elements make sense. For example, SeekHead and Cues are useless here 😭 All elements other than the Clusters MUST be placed before the Clusters, no exceptions, periodt 👑
InfoTracksAttachments(rare)TagsClusters
26. Security Considerations 🔥
Matroska inherits security considerations from EBML [RFC8794].
Attacks on a Matroska Reader could include:
- Storage of arbitrary and potentially executable data within an
Attachmentselement. 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.
- Damage to the Encryption and Compression fields (Section 14) that would result in bogus binary data interpreted by the decoder.
Chapter Codecsrunning unwanted commands on the host system.
The same error handling done for EBML applies to Matroska files. Particular error handling is not covered in this specification, as this depends on the goal of the Matroska Readers. Matroska Readers decide how to handle the errors, whether or not they are recoverable, in their own 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 🙈
Matroska Reader implementations need to be robust against malicious payloads. Those related to denial of service are outlined in Section 2.1 of [RFC4732] 🛡️
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 to transcoding gateways. Not okay 😤
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 ✨
27. IANA Considerations 🌸
27.1. Matroska Element IDs Registry
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 Name, a Change Controller, and an optional Reference to a document describing the Element ID.
Element IDs are encoded using the VINT mechanism described in Section 4 of [RFC8794] and can be between one and five octets long. Five-octet Element IDs are possible only if declared in the EBML Header.
Element IDs are described in Section 5 of [RFC8794], with the changes in [Err7189] and [Err7191].
One-octet Matroska Element IDs (range 0x80-0xFE) are to be allocated according to the "RFC Required" policy [RFC8126].
Two-octet Matroska Element IDs (range 0x407F-0x7FFE) are to be allocated according to the "Specification Required" policy [RFC8126].
Two-octet Matroska Element IDs between 0x0100 and 0x407E are not valid for use as an Element ID.
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 Section 17.1 of [RFC8794].
EBML Element IDs defined for the EBML Header, as defined in Section 17.1 of [RFC8794], MUST NOT be used as Matroska Element IDs 🚫
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 🧸
Elements found in Appendix A have an assigned Matroska Element ID for historical reasons. These elements are not in use and SHOULD NOT be reused unless there are no other IDs available with the desired size. Such IDs are marked as "Reclaimed" in the "Matroska Element IDs" registry, as they could be used for other things in the future 🦄
Table 53 shows the initial contents of the "Matroska Element IDs" registry. The Change Controller for the initial entries is the IETF 💜
+=====================+=============================+==============+
| Element ID | Element Name | Reference |
+=====================+=============================+==============+
| 0x80 | ChapterDisplay | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.7.1.4.9 |
+---------------------+-----------------------------+--------------+
| 0x83 | TrackType | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.3 |
+---------------------+-----------------------------+--------------+
| 0x85 | ChapString | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.7.1.4.10 |
+---------------------+-----------------------------+--------------+
| 0x86 | CodecID | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.21 |
+---------------------+-----------------------------+--------------+
| 0x88 | FlagDefault | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.5 |
+---------------------+-----------------------------+--------------+
| 0x8E | Slices | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.5) |
+---------------------+-----------------------------+--------------+
| 0x91 | ChapterTimeStart | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.7.1.4.3 |
+---------------------+-----------------------------+--------------+
| 0x92 | ChapterTimeEnd | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.7.1.4.4 |
+---------------------+-----------------------------+--------------+
| 0x96 | CueRefTime | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.5.1.2.8 |
+---------------------+-----------------------------+--------------+
| 0x97 | CueRefCluster | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.37) |
+---------------------+-----------------------------+--------------+
| 0x98 | ChapterFlagHidden | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.7.1.4.5 |
+---------------------+-----------------------------+--------------+
| 0x9A | FlagInterlaced | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.1 |
+---------------------+-----------------------------+--------------+
| 0x9B | BlockDuration | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5.3 |
+---------------------+-----------------------------+--------------+
| 0x9C | FlagLacing | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.12 |
+---------------------+-----------------------------+--------------+
| 0x9D | FieldOrder | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.2 |
+---------------------+-----------------------------+--------------+
| 0x9F | Channels | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.29.3 |
+---------------------+-----------------------------+--------------+
| 0xA0 | BlockGroup | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5 |
+---------------------+-----------------------------+--------------+
| 0xA1 | Block | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5.1 |
+---------------------+-----------------------------+--------------+
| 0xA2 | BlockVirtual | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.3) |
+---------------------+-----------------------------+--------------+
| 0xA3 | SimpleBlock | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.4 |
+---------------------+-----------------------------+--------------+
| 0xA4 | CodecState | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5.6 |
+---------------------+-----------------------------+--------------+
| 0xA5 | BlockAdditional | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5.2.2 |
+---------------------+-----------------------------+--------------+
| 0xA6 | BlockMore | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5.2.1 |
+---------------------+-----------------------------+--------------+
| 0xA7 | Position | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.2 |
+---------------------+-----------------------------+--------------+
| 0xAA | CodecDecodeAll | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.22) |
+---------------------+-----------------------------+--------------+
| 0xAB | PrevSize | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.3 |
+---------------------+-----------------------------+--------------+
| 0xAE | TrackEntry | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1 |
+---------------------+-----------------------------+--------------+
| 0xAF | EncryptedBlock | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.15) |
+---------------------+-----------------------------+--------------+
| 0xB0 | PixelWidth | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.6 |
+---------------------+-----------------------------+--------------+
| 0xB2 | CueDuration | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.5.1.2.4 |
+---------------------+-----------------------------+--------------+
| 0xB3 | CueTime | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.5.1.1 |
+---------------------+-----------------------------+--------------+
| 0xB5 | SamplingFrequency | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.29.1 |
+---------------------+-----------------------------+--------------+
| 0xB6 | ChapterAtom | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.7.1.4 |
+---------------------+-----------------------------+--------------+
| 0xB7 | CueTrackPositions | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.5.1.2 |
+---------------------+-----------------------------+--------------+
| 0xB9 | FlagEnabled | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.4 |
+---------------------+-----------------------------+--------------+
| 0xBA | PixelHeight | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.7 |
+---------------------+-----------------------------+--------------+
| 0xBB | CuePoint | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.5.1 |
+---------------------+-----------------------------+--------------+
| 0xC0 | TrickTrackUID | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.28) |
+---------------------+-----------------------------+--------------+
| 0xC1 | TrickTrackSegmentUID | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.29) |
+---------------------+-----------------------------+--------------+
| 0xC4 | TrickMasterTrackSegmentUID | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.32) |
+---------------------+-----------------------------+--------------+
| 0xC6 | TrickTrackFlag | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.30) |
Okay bestie, the ID list keeps going and it's giving tables 📋✨ Every single entry is exactly as the spec has it, so we're good to go 💅
+---------------------+-----------------------------+--------------+
| 0xC7| TrickMasterTrackUID |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.31)|
+---------------------+-----------------------------+--------------+
| 0xC8| ReferenceFrame |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.12)|
+---------------------+-----------------------------+--------------+
| 0xC9| ReferenceOffset |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.13)|
+---------------------+-----------------------------+--------------+
| 0xCA| ReferenceTimestamp |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.14)|
+---------------------+-----------------------------+--------------+
| 0xCB| BlockAdditionID |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.9) |
+---------------------+-----------------------------+--------------+
| 0xCC| LaceNumber |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.7) |
+---------------------+-----------------------------+--------------+
| 0xCD| FrameNumber |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.8) |
+---------------------+-----------------------------+--------------+
| 0xCE| Delay |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.10)|
+---------------------+-----------------------------+--------------+
| 0xCF| SliceDuration |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.11)|
+---------------------+-----------------------------+--------------+
| 0xD7| TrackNumber |RFC 9559, |
| | |Section |
| | |5.1.4.1.1 |
+---------------------+-----------------------------+--------------+
| 0xDB| CueReference |RFC 9559, |
| | |Section |
| | |5.1.5.1.2.7 |
+---------------------+-----------------------------+--------------+
| 0xE0| Video |RFC 9559, |
| | |Section |
| | |5.1.4.1.28 |
+---------------------+-----------------------------+--------------+
| 0xE1| Audio |RFC 9559, |
| | |Section |
| | |5.1.4.1.29 |
+---------------------+-----------------------------+--------------+
| 0xE2| TrackOperation |RFC 9559, |
| | |Section |
| | |5.1.4.1.30 |
+---------------------+-----------------------------+--------------+
| 0xE3| TrackCombinePlanes |RFC 9559, |
| | |Section |
| | |5.1.4.1.30.1 |
+---------------------+-----------------------------+--------------+
| 0xE4| TrackPlane |RFC 9559, |
| | |Section |
| | |5.1.4.1.30.2 |
+---------------------+-----------------------------+--------------+
| 0xE5| TrackPlaneUID |RFC 9559, |
| | |Section |
| | |5.1.4.1.30.3 |
+---------------------+-----------------------------+--------------+
| 0xE6| TrackPlaneType |RFC 9559, |
| | |Section |
| | |5.1.4.1.30.4 |
+---------------------+-----------------------------+--------------+
| 0xE7| Timestamp |RFC 9559, |
| | |Section |
| | |5.1.3.1 |
+---------------------+-----------------------------+--------------+
| 0xE8| TimeSlice |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.6) |
+---------------------+-----------------------------+--------------+
| 0xE9| TrackJoinBlocks |RFC 9559, |
| | |Section |
| | |5.1.4.1.30.5 |
+---------------------+-----------------------------+--------------+
| 0xEA| CueCodecState |RFC 9559, |
| | |Section |
| | |5.1.5.1.2.6 |
+---------------------+-----------------------------+--------------+
| 0xEB| CueRefCodecState |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.39)|
+---------------------+-----------------------------+--------------+
| 0xED| TrackJoinUID |RFC 9559, |
| | |Section |
| | |5.1.4.1.30.6 |
+---------------------+-----------------------------+--------------+
| 0xEE| BlockAddID |RFC 9559, |
| | |Section |
| | |5.1.3.5.2.3 |
+---------------------+-----------------------------+--------------+
| 0xF0| CueRelativePosition |RFC 9559, |
| | |Section |
| | |5.1.5.1.2.3 |
+---------------------+-----------------------------+--------------+
| 0xF1| CueClusterPosition |RFC 9559, |
| | |Section |
| | |5.1.5.1.2.2 |
+---------------------+-----------------------------+--------------+
| 0xF7| CueTrack |RFC 9559, |
| | |Section |
| | |5.1.5.1.2.1 |
+---------------------+-----------------------------+--------------+
| 0xFA| ReferencePriority |RFC 9559, |
| | |Section |
| | |5.1.3.5.4 |
+---------------------+-----------------------------+--------------+
| 0xFB| ReferenceBlock |RFC 9559, |
| | |Section |
| | |5.1.3.5.5 |
+---------------------+-----------------------------+--------------+
| 0xFD| ReferenceVirtual |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.4) |
+---------------------+-----------------------------+--------------+
| 0xFF| Reserved |RFC 9559 |
+---------------------+-----------------------------+--------------+
| 0x0100-0x407E| Not valid for use as an |RFC 9559, |
| | Element ID |Section 27.1 |
+---------------------+-----------------------------+--------------+
| 0x41A4| BlockAddIDName |RFC 9559, |
| | |Section |
| | |5.1.4.1.17.2 |
+---------------------+-----------------------------+--------------+
| 0x41E4| BlockAdditionMapping |RFC 9559, |
| | |Section |
| | |5.1.4.1.17 |
+---------------------+-----------------------------+--------------+
| 0x41E7| BlockAddIDType |RFC 9559, |
| | |Section |
| | |5.1.4.1.17.3 |
+---------------------+-----------------------------+--------------+
| 0x41ED| BlockAddIDExtraData |RFC 9559, |
| | |Section |
| | |5.1.4.1.17.4 |
+---------------------+-----------------------------+--------------+
| 0x41F0| BlockAddIDValue |RFC 9559, |
| | |Section |
| | |5.1.4.1.17.1 |
+---------------------+-----------------------------+--------------+
| 0x4254| ContentCompAlgo |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.6 |
+---------------------+-----------------------------+--------------+
| 0x4255| ContentCompSettings |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.7 |
+---------------------+-----------------------------+--------------+
| 0x437C| ChapLanguage |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.11 |
+---------------------+-----------------------------+--------------+
| 0x437D| ChapLanguageBCP47 |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.12 |
+---------------------+-----------------------------+--------------+okay so the registry table is still going, and we're in the Element IDs list now 💅✨ these are the reclaimed ones and the ones still in use, lined up by ID 🎀
| 0x437E| ChapCountry |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.13 |
+---------------------+-----------------------------+--------------+
| 0x4444| SegmentFamily |RFC 9559, |
| | |Section |
| | |5.1.2.7 |
+---------------------+-----------------------------+--------------+
| 0x4461| DateUTC |RFC 9559, |
| | |Section |
| | |5.1.2.11 |
+---------------------+-----------------------------+--------------+
| 0x447A| TagLanguage |RFC 9559, |
| | |Section |
| | |5.1.8.1.2.2 |
+---------------------+-----------------------------+--------------+
| 0x447B| TagLanguageBCP47 |RFC 9559, |
| | |Section |
| | |5.1.8.1.2.3 |
+---------------------+-----------------------------+--------------+
| 0x4484| TagDefault |RFC 9559, |
| | |Section |
| | |5.1.8.1.2.4 |
+---------------------+-----------------------------+--------------+
| 0x4485| TagBinary |RFC 9559, |
| | |Section |
| | |5.1.8.1.2.6 |
+---------------------+-----------------------------+--------------+
| 0x4487| TagString |RFC 9559, |
| | |Section |
| | |5.1.8.1.2.5 |
+---------------------+-----------------------------+--------------+
| 0x4489| Duration |RFC 9559, |
| | |Section |
| | |5.1.2.10 |
+---------------------+-----------------------------+--------------+
| 0x44B4| TagDefaultBogus |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.43)|
+---------------------+-----------------------------+--------------+
| 0x450D| ChapProcessPrivate |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.16 |
+---------------------+-----------------------------+--------------+
| 0x45A3| TagName |RFC 9559, |
| | |Section |
| | |5.1.8.1.2.1 |
+---------------------+-----------------------------+--------------+
| 0x45B9| EditionEntry |RFC 9559, |
| | |Section |
| | |5.1.7.1 |
+---------------------+-----------------------------+--------------+
| 0x45BC| EditionUID |RFC 9559, |
| | |Section |
| | |5.1.7.1.1 |
+---------------------+-----------------------------+--------------+
| 0x45DB| EditionFlagDefault |RFC 9559, |
| | |Section |
| | |5.1.7.1.2 |
+---------------------+-----------------------------+--------------+
| 0x45DD| EditionFlagOrdered |RFC 9559, |
| | |Section |
| | |5.1.7.1.3 |
+---------------------+-----------------------------+--------------+
| 0x465C| FileData |RFC 9559, |
| | |Section |
| | |5.1.6.1.4 |
+---------------------+-----------------------------+--------------+
| 0x4660| FileMediaType |RFC 9559, |
| | |Section |
| | |5.1.6.1.3 |
+---------------------+-----------------------------+--------------+
| 0x4661| FileUsedStartTime |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.41)|
+---------------------+-----------------------------+--------------+
| 0x4662| FileUsedEndTime |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.42)|
+---------------------+-----------------------------+--------------+
| 0x466E| FileName |RFC 9559, |
| | |Section |
| | |5.1.6.1.2 |
+---------------------+-----------------------------+--------------+
| 0x4675| FileReferral |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.40)|
+---------------------+-----------------------------+--------------+
| 0x467E| FileDescription |RFC 9559, |
| | |Section |
| | |5.1.6.1.1 |
+---------------------+-----------------------------+--------------+
| 0x46AE| FileUID |RFC 9559, |
| | |Section |
| | |5.1.6.1.5 |
+---------------------+-----------------------------+--------------+
| 0x47E1| ContentEncAlgo |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.9 |
+---------------------+-----------------------------+--------------+
| 0x47E2| ContentEncKeyID |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.10 |
+---------------------+-----------------------------+--------------+
| 0x47E3| ContentSignature |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.33)|
+---------------------+-----------------------------+--------------+
| 0x47E4| ContentSigKeyID |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.34)|
+---------------------+-----------------------------+--------------+
| 0x47E5| ContentSigAlgo |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.35)|
+---------------------+-----------------------------+--------------+
| 0x47E6| ContentSigHashAlgo |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.36)|
+---------------------+-----------------------------+--------------+
| 0x47E7| ContentEncAESSettings |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.11 |
+---------------------+-----------------------------+--------------+
| 0x47E8| AESSettingsCipherMode |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.12 |
+---------------------+-----------------------------+--------------+
| 0x4D80| MuxingApp |RFC 9559, |
| | |Section |
| | |5.1.2.13 |
+---------------------+-----------------------------+--------------+
| 0x4DBB| Seek |RFC 9559, |
| | |Section |
| | |5.1.1.1 |
+---------------------+-----------------------------+--------------+
| 0x5031| ContentEncodingOrder |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.2 |
+---------------------+-----------------------------+--------------+
| 0x5032| ContentEncodingScope |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.3 |
+---------------------+-----------------------------+--------------+
| 0x5033| ContentEncodingType |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.4 |
+---------------------+-----------------------------+--------------+
| 0x5034| ContentCompression |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.5 |
+---------------------+-----------------------------+--------------+
| 0x5035| ContentEncryption |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.8 |
+---------------------+-----------------------------+--------------+
| 0x535F| CueRefNumber |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.38)|
+---------------------+-----------------------------+--------------+
| 0x536E| Name |RFC 9559, |
| | |Section |
| | |5.1.4.1.18 |
+---------------------+-----------------------------+--------------+
| 0x5378| CueBlockNumber |RFC 9559, |
| | |Section |okay so this is the registry doing its thing 🦋 here's the next stretch of Element IDs, bestie 💅
| | |5.1.5.1.2.5 |
+---------------------+-----------------------------+--------------+
| 0x537F| TrackOffset |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.18)|
+---------------------+-----------------------------+--------------+
| 0x53AB| SeekID |RFC 9559, |
| | |Section |
| | |5.1.1.1.1 |
+---------------------+-----------------------------+--------------+
| 0x53AC| SeekPosition |RFC 9559, |
| | |Section |
| | |5.1.1.1.2 |
+---------------------+-----------------------------+--------------+
| 0x53B8| StereoMode |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.3 |
+---------------------+-----------------------------+--------------+
| 0x53B9| OldStereoMode |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.5 |
+---------------------+-----------------------------+--------------+
| 0x53C0| AlphaMode |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.4 |
+---------------------+-----------------------------+--------------+
| 0x54AA| PixelCropBottom |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.8 |
+---------------------+-----------------------------+--------------+
| 0x54B0| DisplayWidth |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.12 |
+---------------------+-----------------------------+--------------+
| 0x54B2| DisplayUnit |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.14 |
+---------------------+-----------------------------+--------------+
| 0x54B3| AspectRatioType |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.24)|
+---------------------+-----------------------------+--------------+
| 0x54BA| DisplayHeight |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.13 |
+---------------------+-----------------------------+--------------+
| 0x54BB| PixelCropTop |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.9 |
+---------------------+-----------------------------+--------------+
| 0x54CC| PixelCropLeft |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.10 |
+---------------------+-----------------------------+--------------+
| 0x54DD| PixelCropRight |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.11 |
+---------------------+-----------------------------+--------------+
| 0x55AA| FlagForced |RFC 9559, |
| | |Section |
| | |5.1.4.1.6 |
+---------------------+-----------------------------+--------------+
| 0x55AB| FlagHearingImpaired |RFC 9559, |
| | |Section |
| | |5.1.4.1.7 |
+---------------------+-----------------------------+--------------+
| 0x55AC| FlagVisualImpaired |RFC 9559, |
| | |Section |
| | |5.1.4.1.8 |
+---------------------+-----------------------------+--------------+
| 0x55AD| FlagTextDescriptions |RFC 9559, |
| | |Section |
| | |5.1.4.1.9 |
+---------------------+-----------------------------+--------------+
| 0x55AE| FlagOriginal |RFC 9559, |
| | |Section |
| | |5.1.4.1.10 |
+---------------------+-----------------------------+--------------+
| 0x55AF| FlagCommentary |RFC 9559, |
| | |Section |
| | |5.1.4.1.11 |
+---------------------+-----------------------------+--------------+
| 0x55B0| Colour |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.16 |
+---------------------+-----------------------------+--------------+
| 0x55B1| MatrixCoefficients |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.17 |
+---------------------+-----------------------------+--------------+
| 0x55B2| BitsPerChannel |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.18 |
+---------------------+-----------------------------+--------------+
| 0x55B3| ChromaSubsamplingHorz |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.19 |
+---------------------+-----------------------------+--------------+
| 0x55B4| ChromaSubsamplingVert |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.20 |
+---------------------+-----------------------------+--------------+
| 0x55B5| CbSubsamplingHorz |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.21 |
+---------------------+-----------------------------+--------------+
| 0x55B6| CbSubsamplingVert |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.22 |
+---------------------+-----------------------------+--------------+
| 0x55B7| ChromaSitingHorz |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.23 |
+---------------------+-----------------------------+--------------+
| 0x55B8| ChromaSitingVert |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.24 |
+---------------------+-----------------------------+--------------+
| 0x55B9| Range |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.25 |
+---------------------+-----------------------------+--------------+
| 0x55BA| TransferCharacteristics |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.26 |
+---------------------+-----------------------------+--------------+
| 0x55BB| Primaries |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.27 |
+---------------------+-----------------------------+--------------+
| 0x55BC| MaxCLL |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.28 |
+---------------------+-----------------------------+--------------+
| 0x55BD| MaxFALL |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.29 |
+---------------------+-----------------------------+--------------+
| 0x55D0| MasteringMetadata |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.30 |
+---------------------+-----------------------------+--------------+
| 0x55D1| PrimaryRChromaticityX |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.31 |
+---------------------+-----------------------------+--------------+
| 0x55D2| PrimaryRChromaticityY |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.32 |
+---------------------+-----------------------------+--------------+
| 0x55D3| PrimaryGChromaticityX |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.33 |
+---------------------+-----------------------------+--------------+
| 0x55D4| PrimaryGChromaticityY |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.34 |
+---------------------+-----------------------------+--------------+
| 0x55D5| PrimaryBChromaticityX |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.35 |
+---------------------+-----------------------------+--------------+
| 0x55D6| PrimaryBChromaticityY |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.36 |
+---------------------+-----------------------------+--------------+Okay bestie, the Element IDs registry is still serving 🦋✨ Every ID here has a home, and the reclaimed ones are giving "retired but iconic" 👑
| 0x55D7| WhitePointChromaticityX |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.37 |
+---------------------+-----------------------------+--------------+
| 0x55D8| WhitePointChromaticityY |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.38 |
+---------------------+-----------------------------+--------------+
| 0x55D9| LuminanceMax |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.39 |
+---------------------+-----------------------------+--------------+
| 0x55DA| LuminanceMin |RFC 9559, |
| | |Section |
| | |5.1.4.1.28.40 |
+---------------------+-----------------------------+--------------+
| 0x55EE| MaxBlockAdditionID |RFC 9559, |
| | |Section |
| | |5.1.4.1.16 |
+---------------------+-----------------------------+--------------+
| 0x5654| ChapterStringUID |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.2 |
+---------------------+-----------------------------+--------------+
| 0x56AA| CodecDelay |RFC 9559, |
| | |Section |
| | |5.1.4.1.25 |
+---------------------+-----------------------------+--------------+
| 0x56BB| SeekPreRoll |RFC 9559, |
| | |Section |
| | |5.1.4.1.26 |
+---------------------+-----------------------------+--------------+
| 0x5741| WritingApp |RFC 9559, |
| | |Section |
| | |5.1.2.14 |
+---------------------+-----------------------------+--------------+
| 0x5854| SilentTracks |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.1) |
+---------------------+-----------------------------+--------------+
| 0x58D7| SilentTrackNumber |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.2) |
+---------------------+-----------------------------+--------------+
| 0x61A7| AttachedFile |RFC 9559, |
| | |Section |
| | |5.1.6.1 |
+---------------------+-----------------------------+--------------+
| 0x6240| ContentEncoding |RFC 9559, |
| | |Section |
| | |5.1.4.1.31.1 |
+---------------------+-----------------------------+--------------+
| 0x6264| BitDepth |RFC 9559, |
| | |Section |
| | |5.1.4.1.29.4 |
+---------------------+-----------------------------+--------------+
| 0x63A2| CodecPrivate |RFC 9559, |
| | |Section |
| | |5.1.4.1.22 |
+---------------------+-----------------------------+--------------+
| 0x63C0| Targets |RFC 9559, |
| | |Section |
| | |5.1.8.1.1 |
+---------------------+-----------------------------+--------------+
| 0x63C3| ChapterPhysicalEquiv |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.8 |
+---------------------+-----------------------------+--------------+
| 0x63C4| TagChapterUID |RFC 9559, |
| | |Section |
| | |5.1.8.1.1.5 |
+---------------------+-----------------------------+--------------+
| 0x63C5| TagTrackUID |RFC 9559, |
| | |Section |
| | |5.1.8.1.1.3 |
+---------------------+-----------------------------+--------------+
| 0x63C6| TagAttachmentUID |RFC 9559, |
| | |Section |
| | |5.1.8.1.1.6 |
+---------------------+-----------------------------+--------------+
| 0x63C9| TagEditionUID |RFC 9559, |
| | |Section |
| | |5.1.8.1.1.4 |
+---------------------+-----------------------------+--------------+
| 0x63CA| TargetType |RFC 9559, |
| | |Section |
| | |5.1.8.1.1.2 |
+---------------------+-----------------------------+--------------+
| 0x6624| TrackTranslate |RFC 9559, |
| | |Section |
| | |5.1.4.1.27 |
+---------------------+-----------------------------+--------------+
| 0x66A5| TrackTranslateTrackID |RFC 9559, |
| | |Section |
| | |5.1.4.1.27.1 |
+---------------------+-----------------------------+--------------+
| 0x66BF| TrackTranslateCodec |RFC 9559, |
| | |Section |
| | |5.1.4.1.27.2 |
+---------------------+-----------------------------+--------------+
| 0x66FC| TrackTranslateEditionUID |RFC 9559, |
| | |Section |
| | |5.1.4.1.27.3 |
+---------------------+-----------------------------+--------------+
| 0x67C8| SimpleTag |RFC 9559, |
| | |Section |
| | |5.1.8.1.2 |
+---------------------+-----------------------------+--------------+
| 0x68CA| TargetTypeValue |RFC 9559, |
| | |Section |
| | |5.1.8.1.1.1 |
+---------------------+-----------------------------+--------------+
| 0x6911| ChapProcessCommand |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.17 |
+---------------------+-----------------------------+--------------+
| 0x6922| ChapProcessTime |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.18 |
+---------------------+-----------------------------+--------------+
| 0x6924| ChapterTranslate |RFC 9559, |
| | |Section |
| | |5.1.2.8 |
+---------------------+-----------------------------+--------------+
| 0x6933| ChapProcessData |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.19 |
+---------------------+-----------------------------+--------------+
| 0x6944| ChapProcess |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.14 |
+---------------------+-----------------------------+--------------+
| 0x6955| ChapProcessCodecID |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.15 |
+---------------------+-----------------------------+--------------+
| 0x69A5| ChapterTranslateID |RFC 9559, |
| | |Section |
| | |5.1.2.8.1 |
+---------------------+-----------------------------+--------------+
| 0x69BF| ChapterTranslateCodec |RFC 9559, |
| | |Section |
| | |5.1.2.8.2 |
+---------------------+-----------------------------+--------------+
| 0x69FC| ChapterTranslateEditionUID |RFC 9559, |
| | |Section |
| | |5.1.2.8.3 |
+---------------------+-----------------------------+--------------+
| 0x6D80| ContentEncodings |RFC 9559, |
| | |Section |
| | |5.1.4.1.31 |
+---------------------+-----------------------------+--------------+
| 0x6DE7| MinCache |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.16)|
+---------------------+-----------------------------+--------------+
| 0x6DF8| MaxCache |Reclaimed (RFC|
| | |9559, |
| | |Appendix A.17)|
+---------------------+-----------------------------+--------------+
| 0x6E67| ChapterSegmentUUID |RFC 9559, |
| | |Section |
| | |5.1.7.1.4.6 |
+---------------------+-----------------------------+--------------+
| 0x6EBC| ChapterSegmentEditionUID |RFC 9559, |
| | |Section |The table keeps going in the next part, so hold onto your snacks 🍓🧚
| 5.1.7.1.4.7 |
+---------------------+-----------------------------+--------------+
| 0x6FAB | TrackOverlay | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.23) |
+---------------------+-----------------------------+--------------+
| 0x7373 | Tag | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.8.1 |
+---------------------+-----------------------------+--------------+
| 0x7384 | SegmentFilename | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.2 |
+---------------------+-----------------------------+--------------+
| 0x73A4 | SegmentUUID | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.1 |
+---------------------+-----------------------------+--------------+
| 0x73C4 | ChapterUID | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.7.1.4.1 |
+---------------------+-----------------------------+--------------+
| 0x73C5 | TrackUID | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.2 |
+---------------------+-----------------------------+--------------+
| 0x7446 | AttachmentLink | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.24 |
+---------------------+-----------------------------+--------------+
| 0x75A1 | BlockAdditions | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5.2 |
+---------------------+-----------------------------+--------------+
| 0x75A2 | DiscardPadding | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.3.5.7 |
+---------------------+-----------------------------+--------------+
| 0x7670 | Projection | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.41 |
+---------------------+-----------------------------+--------------+
| 0x7671 | ProjectionType | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.42 |
+---------------------+-----------------------------+--------------+
| 0x7672 | ProjectionPrivate | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.43 |
+---------------------+-----------------------------+--------------+
| 0x7673 | ProjectionPoseYaw | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.44 |
+---------------------+-----------------------------+--------------+
| 0x7674 | ProjectionPosePitch | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.45 |
+---------------------+-----------------------------+--------------+
| 0x7675 | ProjectionPoseRoll | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.46 |
+---------------------+-----------------------------+--------------+
| 0x78B5 | OutputSamplingFrequency | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.29.2 |
+---------------------+-----------------------------+--------------+
| 0x7BA9 | Title | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.12 |
+---------------------+-----------------------------+--------------+
| 0x7D7B | ChannelPositions | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.27) |
+---------------------+-----------------------------+--------------+
| 0x7FFF | Reserved | RFC 9559 |
+---------------------+-----------------------------+--------------+
| 0x010000-0x203FFE | Not valid for use as an | RFC 9559, |
|---|---|---|
| Element ID | Section 27.1 |
+---------------------+-----------------------------+--------------+
| 0x22B59C | Language | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.19 |
+---------------------+-----------------------------+--------------+
| 0x22B59D | LanguageBCP47 | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.20 |
+---------------------+-----------------------------+--------------+
| 0x23314F | TrackTimestampScale | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.15 |
+---------------------+-----------------------------+--------------+
| 0x234E7A | DefaultDecodedFieldDuration | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.14 |
+---------------------+-----------------------------+--------------+
| 0x2383E3 | FrameRate | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.26) |
+---------------------+-----------------------------+--------------+
| 0x23E383 | DefaultDuration | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.13 |
+---------------------+-----------------------------+--------------+
| 0x258688 | CodecName | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.23 |
+---------------------+-----------------------------+--------------+
| 0x26B240 | CodecDownloadURL | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.21) |
+---------------------+-----------------------------+--------------+
| 0x2AD7B1 | TimestampScale | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.9 |
+---------------------+-----------------------------+--------------+
| 0x2EB524 | UncompressedFourCC | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.4.1.28.15 |
+---------------------+-----------------------------+--------------+
| 0x2FB523 | GammaValue | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.25) |
+---------------------+-----------------------------+--------------+
| 0x3A9697 | CodecSettings | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.19) |
+---------------------+-----------------------------+--------------+
| 0x3B4040 | CodecInfoURL | Reclaimed (RFC |
|---|---|---|
| 9559, | ||
| Appendix A.20) |
+---------------------+-----------------------------+--------------+
| 0x3C83AB | PrevFilename | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.4 |
+---------------------+-----------------------------+--------------+
| 0x3CB923 | PrevUUID | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.3 |
+---------------------+-----------------------------+--------------+
| 0x3E83BB | NextFilename | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.6 |
+---------------------+-----------------------------+--------------+
| 0x3EB923 | NextUUID | RFC 9559, |
|---|---|---|
| Section | ||
| 5.1.2.5 |
+---------------------+-----------------------------+--------------+
| 0x3FFFFF | Reserved | RFC 9559 |
+---------------------+-----------------------------+--------------+
| 0x01000000-0x101FFFFE | Not valid for use as an | RFC 9559, |
|---|---|---|
| Element ID | Section 27.1 |
+---------------------+-----------------------------+--------------+
| 0x1043A770 | Chapters | RFC 9559, |
|---|---|---|
| Section 5.1.7 |
+---------------------+-----------------------------+--------------+
| 0x114D9B74 | SeekHead | RFC 9559, |
|---|---|---|
| Section 5.1.1 |
+---------------------+-----------------------------+--------------+
| 0x1254C367 | Tags | RFC 9559, |
|---|---|---|
| Section 5.1.8 |
+---------------------+-----------------------------+--------------+
| 0x1549A966 | Info | RFC 9559, |
|---|---|---|
| Section 5.1.2 |
+---------------------+-----------------------------+--------------+
| 0x1654AE6B | Tracks | RFC 9559, |
|---|---|---|
| Section 5.1.4 |
27.2. Matroska Compression Algorithms Registry 🗜️✨
Okay so IANA made a brand new registry called the "Matroska Compression Algorithms" registry 💖 The numbers in it match up with the unsigned integer ContentCompAlgo value from Section 5.1.4.1.31.6, so they're basically the same thing.
If you want to add a new compression algorithm, you need a Compression Algorithm value, a description, a Change Controller, and a Reference to a document that describes the algorithm 📝
New entries get allocated under the "Specification Required" policy [RFC8126]. The available values run from 4-18446744073709551615 🔢
Table 54 shows what's already in the registry. The IETF is the Change Controller for all the initial entries 🎀
+=======================+=============+===================+
| Compression Algorithm | Description | Reference |
+=======================+=============+===================+
| 0 | zlib | RFC 9559, Section |
| | | 5.1.4.1.31.6 |
+-----------------------+-------------+-------------------+
| 1 | bzlib | RFC 9559, Section |
| | | 5.1.4.1.31.6 |
+-----------------------+-------------+-------------------+
| 2 | lzo1x | RFC 9559, Section |
| | | 5.1.4.1.31.6 |
+-----------------------+-------------+-------------------+
| 3 | Header | RFC 9559, Section |
| | Stripping | 5.1.4.1.31.6 |
+-----------------------+-------------+-------------------+
Table 54: Initial Contents of "Matroska Compression
Algorithms" Registry27.3. Matroska Encryption Algorithms Registry 🔐
Next up is the "Matroska Encryption Algorithms" registry 🦋 Its values correspond to the unsigned integer ContentEncAlgo value from Section 5.1.4.1.31.9, so they line up with that field.
To register a new Encryption Algorithm, you need an Encryption Algorithm value, a description, a Change Controller, and an optional Reference to a document that describes the algorithm 💜
These get allocated under the "First Come First Served" policy [RFC8126], and the available values range from 6-18446744073709551615 🌸
Table 55 lists the initial contents, and once again the Change Controller for those entries is the IETF 🫶
+======================+===============+===================+
| Encryption Algorithm | Description | Reference |
+======================+===============+===================+
| 0 | Not encrypted | RFC 9559, Section |
| | | 5.1.4.1.31.9 |
+----------------------+---------------+-------------------+
| 1 | DES | RFC 9559, Section |
| | | 5.1.4.1.31.9 |
+----------------------+---------------+-------------------+
| 2 | 3DES | RFC 9559, Section |
| | | 5.1.4.1.31.9 |
+----------------------+---------------+-------------------+
| 3 | Twofish | RFC 9559, Section |
| | | 5.1.4.1.31.9 |
+----------------------+---------------+-------------------+
| 4 | Blowfish | RFC 9559, Section |
| | | 5.1.4.1.31.9 |
+----------------------+---------------+-------------------+
| 5 | AES | RFC 9559, Section |
| | | 5.1.4.1.31.9 |
+----------------------+---------------+-------------------+
Table 55: Initial Contents of "Matroska Encryption
Algorithms" Registry27.4. Matroska AES Cipher Modes Registry 🎀
Here's the "Matroska AES Cipher Modes" registry 🍓 Its values correspond to the unsigned integer AESSettingsCipherMode value from Section 5.1.4.1.31.12.
To register a new AES Cipher Mode, you need an AES Cipher Mode value, a description, a Change Controller, and an optional Reference to a document describing the mode 🧚
New modes get allocated under the "First Come First Served" policy [RFC8126], with available values running from 3-18446744073709551615.
Heads up, the value 0 is not valid for use as an AES Cipher Mode 🙈
Table 56 shows the initial contents, and the IETF is the Change Controller for the initial entries ✨
+=================+======================+===================+
| AES Cipher Mode | Description | Reference |
+=================+======================+===================+
| 0 | Not valid for use as | RFC 9559, Section |
| | an AES Cipher Mode | 5.1.4.1.31.12 |
+-----------------+----------------------+-------------------+
| 1 | AES-CTR | RFC 9559, Section |
| | | 5.1.4.1.31.12 |
+-----------------+----------------------+-------------------+
| 2 | AES-CBC | RFC 9559, Section |
| | | 5.1.4.1.31.12 |
+-----------------+----------------------+-------------------+
Table 56: Initial Contents of "Matroska AES Cipher Modes"
Registry27.5. Matroska Content Encoding Scopes Registry 🌈
The "Matroska Content Encoding Scopes" registry is next 💅 Its values correspond to the unsigned integer ContentEncodingScope value from Section 5.1.4.1.31.3.
To register a new Content Encoding Scope, you need a Content Encoding Scope value, a description, a Change Controller, and a Reference to a document describing the scope 🫧
These get allocated under the "Specification Required" policy [RFC8126], and the available values range from 0x8-0x8000000000000000 🔥
Here's a fun one: the Content Encoding Scope is a bit-field value, so only power of 2 values can be registered 🧮
Also, the value 0 is not valid for use as a Content Encoding Scope 💀
Table 57 lists the initial contents, with the IETF as Change Controller for the initial entries 👑
+================+========================+===================+
| Content | Description | Reference |
| Encoding Scope | | |
+================+========================+===================+
| 0x0 | Not valid for use as a | RFC 9559, Section |
| | Content Encoding Scope | 5.1.4.1.31.3 |
+----------------+------------------------+-------------------+
| 0x1 | Block | RFC 9559, Section |
| | | 5.1.4.1.31.3 |
+----------------+------------------------+-------------------+
| 0x2 | Private | RFC 9559, Section |
| | | 5.1.4.1.31.3 |
+----------------+------------------------+-------------------+
| 0x4 | Next | RFC 9559, Section |
| | | 5.1.4.1.31.3 |
+----------------+------------------------+-------------------+
Table 57: Initial Contents of "Matroska Content Encoding
Scopes" Registry27.6. Matroska Content Encoding Types Registry 🧁
Last but not least, the "Matroska Content Encoding Types" registry 🎉 Its values correspond to the unsigned integer ContentEncodingType value from Section 5.1.4.1.31.4, so they match up with that field.
To register a new Content Encoding Type, you need a Content Encoding Type value, a description, a Change Controller, and a Reference to a document describing the type 💖
These get allocated under the "Specification Required" policy [RFC8126], and the available values range from 2-18446744073709551615 ✨
Table 58 shows the initial contents, and the IETF is the Change Controller for the initial entries 🦋
+=======================+=============+===================+
| Content Encoding Type | Description | Reference |
+=======================+=============+===================+
| 0 | Compression | RFC 9559, Section |
| | | 5.1.4.1.31.4 |
+-----------------------+-------------+-------------------+
| 1 | Encryption | RFC 9559, Section |
| | | 5.1.4.1.31.4 |
+-----------------------+-------------+-------------------+
Table 58: Initial Contents of "Matroska Content
Encoding Types" Registry27.7. Matroska Stereo Modes Registry 🎀
okay so bestie, this is the registry for stereo modes, which is basically how a 3D video packs both eyes' pictures into one frame 👀✨ IANA made a brand new registry called the "Matroska Stereo Modes" registry, and its values match the unsigned integer StereoMode value from Section 5.1.4.1.28.3. no cap, that's the source of truth 💅
to add a new Stereo Mode here, you need four things: a Stereo Mode value, a description, a Change Controller, and a Reference to a document describing the mode 📝 the Reference is REQUIRED here, so no skipping it, periodt 🫶
the Stereo Modes get handed out under the "Specification Required" policy [RFC8126] 🔥 and the values you can use run from 15 up to 18446744073709551615 🌈 yep, 0 through 14 are already taken by the initial entries, so the new ones start at 15 🧚
Table 59 shows the starting lineup for the "Matroska Stereo Modes" registry, and the IETF is the Change Controller for all of these 👑 every single one points back to RFC 9559, Section 5.1.4.1.28.3, which is so iconic of them 🦋
+=============+============================+===================+
| Stereo Mode | Description | Reference |
+=============+============================+===================+
| 0 | mono | RFC 9559, Section |
| | | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 1 | side by side (left eye | RFC 9559, Section |
| | first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 2 | top - bottom (right eye is | RFC 9559, Section |
| | first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 3 | top - bottom (left eye is | RFC 9559, Section |
| | first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 4 | checkboard (right eye is | RFC 9559, Section |
| | first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 5 | checkboard (left eye is | RFC 9559, Section |
| | first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 6 | row interleaved (right eye | RFC 9559, Section |
| | is first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 7 | row interleaved (left eye | RFC 9559, Section |
| | is first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 8 | column interleaved (right | RFC 9559, Section |
| | eye is first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 9 | column interleaved (left | RFC 9559, Section |
| | eye is first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 10 | anaglyph (cyan/red) | RFC 9559, Section |
| | | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 11 | side by side (right eye | RFC 9559, Section |
| | first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 12 | anaglyph (green/magenta) | RFC 9559, Section |
| | | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 13 | both eyes laced in one | RFC 9559, Section |
| | Block (left eye is first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+
| 14 | both eyes laced in one | RFC 9559, Section |
| | Block (right eye is first) | 5.1.4.1.28.3 |
+-------------+----------------------------+-------------------+Table 59: Initial Contents of "Matroska Stereo Modes" Registry
27.8. Matroska Alpha Modes Registry 🌸
this one is for alpha modes, which tell you whether a video has a transparency channel 🫧 IANA created a new registry called the "Matroska Alpha Modes" registry, and the values line up with the unsigned integer AlphaMode value from Section 5.1.4.1.28.4 🦋
to register a new Alpha Mode, you need an Alpha Mode value, a description, a Change Controller, and an optional Reference to a document describing it 💖 so the Reference is OPTIONAL here, which is a whole different vibe from the stereo one ngl 🙈
Alpha Modes are allocated under the "First Come First Served" policy [RFC8126] ✨ the usable values go from 2 up to 18446744073709551615 💜 since 0 and 1 are already claimed, you start at 2 🧚
Table 60 has the starting entries for the "Matroska Alpha Modes" registry, with the IETF as the Change Controller 👑 both of them point back to RFC 9559, Section 5.1.4.1.28.4 🌈
+============+=============+================================+
| Alpha Mode | Description | Reference |
+============+=============+================================+
| 0 | none | RFC 9559, Section 5.1.4.1.28.4 |
+------------+-------------+--------------------------------+
| 1 | present | RFC 9559, Section 5.1.4.1.28.4 |
+------------+-------------+--------------------------------+Table 60: Initial Contents of "Matroska Alpha Modes" Registry
27.9. Matroska Display Units Registry 🍓
okay this one is all about display units, so you know what unit a video's display size is measured in 📏 IANA made a new registry called the "Matroska Display Units" registry, and its values match the unsigned integer DisplayUnit value from Section 5.1.4.1.28.14 🎀
registering a new Display Unit needs a Display Unit value, a description, a Change Controller, and a Reference to a document describing it 📝 the Reference is REQUIRED, so don't forget it bestie 🫶
these get allocated under the "Specification Required" policy [RFC8126] 🔥 and the values can run from 5 up to 18446744073709551615 🌈 since 0 through 4 are already in use, you start at 5 ⭐
Table 61 is the initial lineup for the "Matroska Display Units" registry, IETF is the Change Controller, and every entry references RFC 9559, Section 5.1.4.1.28.14 💖
+==============+==============+=================================+
| Display Unit | Description | Reference |
+==============+==============+=================================+
| 0 | pixels | RFC 9559, Section 5.1.4.1.28.14 |
+--------------+--------------+---------------------------------+
| 1 | centimeters | RFC 9559, Section 5.1.4.1.28.14 |
+--------------+--------------+---------------------------------+
| 2 | inches | RFC 9559, Section 5.1.4.1.28.14 |
+--------------+--------------+---------------------------------+
| 3 | display | RFC 9559, Section 5.1.4.1.28.14 |
| | aspect ratio | |
+--------------+--------------+---------------------------------+
| 4 | unknown | RFC 9559, Section 5.1.4.1.28.14 |
+--------------+--------------+---------------------------------+Table 61: Initial Contents of "Matroska Display Units" Registry
27.10. Matroska Horizontal Chroma Sitings Registry 🦋
this registry is for horizontal chroma sitings, which is about where the colour info sits horizontally compared to the brightness info 🌈 IANA created the "Matroska Horizontal Chroma Sitings" registry, and its values correspond to the unsigned integer ChromaSitingHorz value from Section 5.1.4.1.28.23 ✨
to register a new Horizontal Chroma Siting, you need a Horizontal Chroma Siting value, a description, a Change Controller, and an optional Reference to a document describing it 💜 so the Reference is OPTIONAL in this one 🙈
these are allocated under the "First Come First Served" policy [RFC8126] 💅 usable values go from 3 up to 18446744073709551615 🧚 since 0 through 2 are already taken, you begin at 3 🌸
Table 62 has the starting contents for the "Matroska Horizontal Chroma Sitings" registry, with the IETF as Change Controller 👑 all three entries point to RFC 9559, Section 5.1.4.1.28.23 🫶
+==========================+=============+===================+
| Horizontal Chroma Siting | Description | Reference |
+==========================+=============+===================+
| 0 | unspecified | RFC 9559, Section |
| | | 5.1.4.1.28.23 |
+--------------------------+-------------+-------------------+
| 1 | left | RFC 9559, Section |
| | collocated | 5.1.4.1.28.23 |
+--------------------------+-------------+-------------------+
| 2 | half | RFC 9559, Section |
| | | 5.1.4.1.28.23 |
+--------------------------+-------------+-------------------+Table 62: Initial Contents of "Matroska Horizontal Chroma Sitings" Registry
27.11. Matroska Vertical Chroma Sitings Registry 💜
last registry in this batch, and it's the vertical twin of the one we just did 🪞 IANA made the "Matroska Vertical Chroma Sitings" registry, and its values correspond to the unsigned integer ChromaSitingVert value from Section 5.1.4.1.28.24 🌷
registering a new Vertical Chroma Siting needs a Vertical Chroma Siting value, a description, a Change Controller, and an optional Reference to a document describing it 🫧 the Reference is OPTIONAL here too, so no pressure 💖
these use the "First Come First Served" policy [RFC8126] 🔥 and the values run from 3 up to 18446744073709551615 🌈 0 through 2 are taken, so you start at 3 ⭐
Table 63 shows the initial contents of the "Matroska Vertical Chroma Sitings" registry, with the IETF as Change Controller 👑 every entry references RFC 9559, Section 5.1.4.1.28.24 🦋
+========================+=============+===================+
| Vertical Chroma Siting | Description | Reference |
+========================+=============+===================+
| 0 | unspecified | RFC 9559, Section |
| | | 5.1.4.1.28.24 |
+------------------------+-------------+-------------------+
| 1 | top | RFC 9559, Section |
| | collocated | 5.1.4.1.28.24 |
+------------------------+-------------+-------------------+
| 2 | half | RFC 9559, Section |
| | | 5.1.4.1.28.24 |
+------------------------+-------------+-------------------+Table 63: Initial Contents of "Matroska Vertical Chroma Sitings" Registry
27.12. Matroska Color Ranges Registry 🌈
okay so bestie, this one is the registry for Color Ranges 🎨✨ IANA made a brand new registry called the "Matroska Color Ranges" registry, and the numbers in it match up with the unsigned integer Range value from Section 5.1.4.1.28.25. it's giving organization fr fr 💅
to add a new Color Range to this registry, you need four things: a Color Range value, a description, a Change Controller, and a Reference to a document that explains the Color Range. no cap, that's the whole checklist 🫶
the Color Ranges get handed out under the "Specification Required" policy [RFC8126]. the values you can use run from 4-18446744073709551615. yes, that's a very big number 😭
Table 64 shows the starter entries in the "Matroska Color Ranges" registry. the Change Controller for all of these is the IETF, because they were there from the start 🌸
+=============+===============================+===================+
| Color Range | Description | Reference |
+=============+===============================+===================+
| 0 | unspecified | RFC 9559, Section |
| | | 5.1.4.1.28.25 |
+-------------+-------------------------------+-------------------+
| 1 | broadcast range | RFC 9559, Section |
| | | 5.1.4.1.28.25 |
+-------------+-------------------------------+-------------------+
| 2 | full range (no clipping) | RFC 9559, Section |
| | | 5.1.4.1.28.25 |
+-------------+-------------------------------+-------------------+
| 3 | defined by MatrixCoefficients | RFC 9559, Section |
| | / TransferCharacteristics | 5.1.4.1.28.25 |
+-------------+-------------------------------+-------------------+Table 64: Initial Contents of "Matroska Color Ranges" Registry
27.13. Matroska Tags Target Types Registry 🎯
next up is the Tags Target Types registry 🦋 IANA made this one too, and the values match the unsigned integer TargetTypeValue from Section 5.1.8.1.1.1. it's giving very organized energy, ngl 💜
to register a new Tags Target Type, you need a Tags Target Type value, a description, a Change Controller, and a Reference to a document that describes it. same vibe as before, iykyk 🙈
these get allocated under the "Specification Required" policy [RFC8126]. the available values are 1-9, 11-19, 21-29, 31-39, 41-49, 51-59, 61-69, and 71-18446744073709551615. notice how the tens-digit ranges skip the multiples of ten, the way that it's organized is kinda iconic ✨
the value 0 is not valid for use as a Tags Target Type. not me being dramatic, that one is literally forbidden 💀
Table 65 shows the starter entries in the "Matroska Tags Target Types" registry. the Change Controller for these is the IETF 🌈
+==================+==========================+===================+
| Tags Target Type | Description | Reference |
+==================+==========================+===================+
| 70 | COLLECTION | RFC 9559, Section |
| | | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+
| 60 | EDITION / ISSUE / VOLUME | RFC 9559, Section |
| | / OPUS / SEASON / SEQUEL | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+
| 50 | ALBUM / OPERA / CONCERT | RFC 9559, Section |
| | / MOVIE / EPISODE | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+
| 40 | PART / SESSION | RFC 9559, Section |
| | | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+
| 30 | TRACK / SONG / CHAPTER | RFC 9559, Section |
| | | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+
| 20 | SUBTRACK / MOVEMENT / | RFC 9559, Section |
| | SCENE | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+
| 10 | SHOT | RFC 9559, Section |
| | | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+
| 0 | Not valid for use as a | RFC 9559, Section |
| | Tags Target Type | 5.1.8.1.1.1 |
+------------------+--------------------------+-------------------+Table 65: Initial Contents of "Matroska Tags Target Types" Registry
27.14. Matroska Chapter Codec IDs Registry 📚
okay now we're on the Chapter Codec IDs registry 🎀 IANA made this one as a new registry called the "Matroska Chapter Codec IDs" registry. the values match up with the unsigned integer ChapProcessCodecID, ChapterTranslateCodec, and TrackTranslateCodec values from Section 5.1.7.1.4.15. three names, one registry, slay 👑
to add a Chapter Codec ID, you need a Chapter Codec ID value, a description, a Change Controller, and a Reference to a document describing it 🫶
the Chapter Codec IDs are allocated under the "Specification Required" policy [RFC8126]. the available values run from 2-18446744073709551615. so 0 and 1 are not up for grabs here, they're already taken by the starter entries 🙈
Table 66 shows those starter entries. the Change Controller is the IETF for the initial ones 🍓
+==================+=================+===================+
| Chapter Codec ID | Description | Reference |
+==================+=================+===================+
| 0 | Matroska Script | RFC 9559, Section |
| | | 5.1.7.1.4.15 |
+------------------+-----------------+-------------------+
| 1 | DVD-menu | RFC 9559, Section |
| | | 5.1.7.1.4.15 |
+------------------+-----------------+-------------------+Table 66: Initial Contents of "Matroska Chapter Codec IDs" Registry
27.15. Matroska Projection Types Registry 🌍
now for the Projection Types registry 🧚 IANA created this as a new registry called the "Matroska Projection Types" registry. the values correspond to the unsigned integer ProjectionType value from Section 5.1.4.1.28.42. it's literally about how a 360 video gets laid out, and that's so cool 😭
to register a new Projection Type, you need a Projection Type value, a description, a Change Controller, and an optional Reference to a document describing it. the "optional" part is the key difference here 💖
these are allocated under the "First Come First Served" policy [RFC8126]. the values you can use run from 4-18446744073709551615. first come, first served, very fair vibes ✨
Table 67 shows the starter entries in the "Matroska Projection Types" registry. the Change Controller for the initial entries is the IETF 🌈
+=================+=================+===================+
| Projection Type | Description | Reference |
+=================+=================+===================+
| 0 | rectangular | RFC 9559, Section |
| | | 5.1.4.1.28.42 |
+-----------------+-----------------+-------------------+
| 1 | equirectangular | RFC 9559, Section |
| | | 5.1.4.1.28.42 |
+-----------------+-----------------+-------------------+
| 2 | cubemap | RFC 9559, Section |
| | | 5.1.4.1.28.42 |
+-----------------+-----------------+-------------------+
| 3 | mesh | RFC 9559, Section |
| | | 5.1.4.1.28.42 |
+-----------------+-----------------+-------------------+Table 67: Initial Contents of "Matroska Projection Types" Registry
27.16. Matroska Track Types Registry 🎬
last registry for this part: the Track Types registry 💅 IANA created it as the "Matroska Track Types" registry, and the values match the unsigned integer TrackType value from Section 5.1.4.1.3. track types are the kinds of tracks you get in a file, so video, audio, all that good stuff 🎧
to register a new Track Type, you need a Track Type value, a description, a Change Controller, and a Reference to a document describing it. you know the drill by now 🦋
Track Types are allocated under the "Specification Required" policy [RFC8126]. the available values are 4-15, 19-31, and 34-18446744073709551615. the value 0 is not valid for use as a Track Type, so don't even try 💀
Table 68 shows the starter entries in the "Matroska Track Types" registry. the Change Controller for the initial entries is the IETF 🫶
+============+===================+===================+
| Track Type | Description | Reference |
+============+===================+===================+
| 0 | Not valid for use | RFC 9559, |
| | as a Track Type | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 1 | video | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 2 | audio | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 3 | complex | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 16 | logo | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 17 | subtitle | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 18 | buttons | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 32 | control | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+
| 33 | metadata | RFC 9559, |
| | | Section 5.1.4.1.3 |
+------------+-------------------+-------------------+Table 68: Initial Contents of "Matroska Track Types" Registry
27.17. Matroska Track Plane Types Registry 🎀
Okay so IANA made a brand new registry called the "Matroska Track Plane Types" registry 💜. It holds the unsigned integer TrackPlaneType values from Section 5.1.4.1.30.4, so it's giving organization energy.
To add a new Track Plane Type, you need a Track Plane Type value, a description, a Change Controller, and an optional Reference to a document that describes the type 📝.
New Track Plane Types get handed out on a "First Come First Served" basis [RFC8126]. The available values run from 3-18446744073709551615 🔢.
Table 69 shows what's already in the "Matroska Track Plane Types" registry. The Change Controller for those starter entries is the IETF 🌸.
+==================+=============+================================+
| Track Plane Type | Description | Reference |
+==================+=============+================================+
| 0 | left eye | RFC 9559, Section 5.1.4.1.30.4 |
+------------------+-------------+--------------------------------+
| 1 | right eye | RFC 9559, Section 5.1.4.1.30.4 |
+------------------+-------------+--------------------------------+
| 2 | background | RFC 9559, Section 5.1.4.1.30.4 |
+------------------+-------------+--------------------------------+Table 69: Initial Contents of "Matroska Track Plane Types" Registry
27.18. Media Types 🦋
Matroska files and streams come in three main flavors: audio-video, audio-only, and (every now and then) stereoscopic video 🎬.
Historically, Matroska files and streams 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 that follows the format in [RFC6838] instead 💅.
IANA registered three media types using the templates (see [RFC6838]). Each one gets its own subsection below 🧚.
27.18.1. For Files Containing Video Tracks 📼
Type name: video
Subtype name: matroska
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: As per RFCs 9559 and 8794
Security considerations: See Section 26 of RFC 9559.
Interoperability considerations: Due to the extensibility of
Matroska, it is possible to encounter files with unknown but valid
EBML Elements. Readers should be ready to handle this case. The
fixed byte order, octet boundaries, and UTF-8 usage allow for
broad interoperability.
Published specification: RFC 9559
Applications that use this media type: FFmpeg, VLC, etc.
Fragment identifier considerations: N/A
Additional information:
Deprecated alias names for this type: video/x-matroska
Magic number(s): N/A
File extension(s): mkv
Macintosh file type code(s): N/A
Person & email address to contact for further information: IETF
CELLAR WG (cellar@ietf.org)
Intended usage: COMMON
Restrictions on usage: None
Author: IETF CELLAR WG
Change controller: IETF27.18.2. For Files Containing Audio Tracks with No Video Tracks 🎧
Type name: audio
Subtype name: matroska
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: As per RFCs 9559 and 8794
Security considerations: See Section 26 of RFC 9559.
Interoperability considerations: Due to the extensibility of
Matroska, it is possible to encounter files with unknown but valid
EBML Elements. Readers should be ready to handle this case. The
fixed byte order, octet boundaries, and UTF-8 usage allow for
broad interoperability.
Published specification: RFC 9559
Applications that use this media type: FFmpeg, VLC, etc.
Fragment identifier considerations: N/A
Additional information:
Deprecated alias names for this type: audio/x-matroska
Magic number(s): N/A
File extension(s): mka
Macintosh file type code(s): N/A
Person & email address to contact for further information: IETF
CELLAR WG (cellar@ietf.org)
Intended usage: COMMON
Restrictions on usage: None
Author: IETF CELLAR WG
Change controller: IETF27.18.3. For Files Containing a Stereoscopic Video Track 👀
Type name: video
Subtype name: matroska-3d
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: As per RFCs 9559 and 8794
Security considerations: See Section 26 of RFC 9559.
Interoperability considerations: Due to the extensibility of
Matroska, it is possible to encounter files with unknown but valid
EBML Elements. Readers should be ready to handle this case. The
fixed byte order, octet boundaries, and UTF-8 usage allow for
broad interoperability.
Published specification: RFC 9559
Applications that use this media type: FFmpeg, VLC, etc.
Fragment identifier considerations: N/A
Additional information:
Deprecated alias names for this type: video/x-matroska-3d
Magic number(s): N/A
File extension(s): mk3d
Macintosh file type code(s): N/A
Person & email address to contact for further information: IETF
CELLAR WG (cellar@ietf.org)
Intended usage: COMMON
Restrictions on usage: None
Author: IETF CELLAR WG
Change controller: IETF28. References 📚
28.1. Normative References 🔥
[CIE-1931] Wikipedia, "CIE 1931 color space", <https://en.wikipedia.org/w/index.php?title=CIE_1931_color_space&oldid=1242811504>.
[ISO639-2] International Organization for Standardization, "Codes for the Representation of Names of Languages", ISO 639-2, December 2017, <https://www.loc.gov/standards/iso639-2/php/code_list.php>.
[ISO9899] International Organization for Standardization, "Information technology -- Programming languages -- C", ISO/IEC 9899:2018, June 2018, <https://www.iso.org/standard/74528.html>.
[ITU-H.273] ITU-T, "Coding-independent code points for video signal type identification", ITU-T Recommendation H.273, September 2023, <https://www.itu.int/rec/T-REC-H.273-202309-P/en>.
[RFC1950] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format Specification version 3.3", RFC 1950, DOI 10.17487/RFC1950, May 1996, <https://www.rfc-editor.org/info/rfc1950>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <https://www.rfc-editor.org/info/rfc6838>.
[RFC8081] Lilley, C., "The "font" Top-Level Media Type", RFC 8081, DOI 10.17487/RFC8081, February 2017, <https://www.rfc-editor.org/info/rfc8081>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8794] Lhomme, S., Rice, D., and M. Bunkus, "Extensible Binary Meta Language", RFC 8794, DOI 10.17487/RFC8794, July 2020, <https://www.rfc-editor.org/info/rfc8794>.
[RFC9562] Davis, K., Peabody, B., and P. Leach, "Universally Unique IDentifiers (UUIDs)", RFC 9562, DOI 10.17487/RFC9562, May 2024, <https://www.rfc-editor.org/info/rfc9562>.
28.2. Informative References 📚✨
okay bestie, these are the "for more context" receipts 🧾 that the spec points to. Here they are, all of them, no cap 💅
- [AVIFormat] Microsoft Corporation, "AVI RIFF File Reference", June 2023,
https://docs.microsoft.com/en-us/windows/win32/directshow/avi-riff-file-reference. - [Blowfish] Schneier, B., "The Blowfish Encryption Algorithm", 1993,
https://www.schneier.com/academic/blowfish/. - [BZIP2] Seward, J., "bzip2", July 2019,
https://sourceware.org/bzip2/. - [DivXTrickTrack] "Smooth FF/RW", December 2010,
https://web.archive.org/web/20101222001148/http://labs.divx.com/node/16601. - [DivXWorldFonts] "World Fonts", December 2010,
https://web.archive.org/web/20110214132246/http://labs.divx.com/node/16602. - [DVD-Video] DVD Forum, "DVD-Books: Part 3 DVD-Video Book", November 1995,
http://www.dvdforum.org/. - [Err7189] RFC Errata, Erratum ID 7189, RFC 8794,
https://www.rfc-editor.org/errata/eid7189. - [Err7191] RFC Errata, Erratum ID 7191, RFC 8794,
https://www.rfc-editor.org/errata/eid7191. - [FIPS197] National Institute of Standards and Technology (NIST), "Advanced Encryption Standard (AES)", FIPS PUB 197, DOI 10.6028/NIST.FIPS.197, November 2001,
https://csrc.nist.gov/publications/detail/fips/197/final. - [FIPS46-3] National Institute of Standards and Technology (NIST), "Data Encryption Standard (DES)", FIPS PUB 46, October 1999,
https://csrc.nist.gov/publications/detail/fips/46/3/archive/1999-10-25. - [FourCC-RGB] FOURCC, "RGB pixel formats",
https://web.archive.org/web/20160609214806/https://www.fourcc.org/rgb.php. - [FourCC-YUV] FOURCC, "YUV pixel formats",
https://web.archive.org/web/20160609214806/https://www.fourcc.org/yuv.php. - [JPEG] ITU-T, "INFORMATION TECHNOLOGY - DIGITAL COMPRESSION AND CODING OF CONTINUOUS-TONE STILL IMAGES - REQUIREMENTS AND GUIDELINES", ITU-T Recommendation T.81, September 1992,
https://www.w3.org/Graphics/JPEG/itu-t81.pdf. - [libmatroska] "libmatroska", March 2024,
https://github.com/Matroska-Org/libmatroska. - [LZO] Tarreau, W. and R. Rodgman, "LZO stream format as understood by Linux's LZO decompressor", October 2018,
https://www.kernel.org/doc/Documentation/lzo.txt. - [MatroskaCodec] Lhomme, S., Bunkus, M., and D. Rice, "Matroska Media Container Codec Specifications", Work in Progress, Internet-Draft, draft-ietf-cellar-codec-13, 5 May 2024,
https://datatracker.ietf.org/doc/html/draft-ietf-cellar-codec-13. - [MatroskaTags] Lhomme, S., Bunkus, M., and D. Rice, "Matroska Media Container Tag Specifications", Work in Progress, Internet-Draft, draft-ietf-cellar-tags-13, 5 May 2024,
https://datatracker.ietf.org/doc/html/draft-ietf-cellar-tags-13. - [MCF] "MCF specification, introduction",
http://mukoli.free.fr/mcf/. - [MSRGB] Microsoft Corporation, "Compression Enumeration", June 2021,
https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-wmf/4e588f70-bd92-4a6f-b77f-35d0feaf7a57. - [MSYUV16] Microsoft Corporation, "10-bit and 16-bit YUV Video Formats", November 2022,
https://learn.microsoft.com/en-us/windows/win32/medfound/10-bit-and-16-bit-yuv-video-formats. - [MSYUV8] Microsoft Corporation, "Recommended 8-Bit YUV Formats for Video Rendering", January 2021,
https://learn.microsoft.com/en-us/windows/win32/medfound/recommended-8-bit-yuv-formats-for-video-rendering. - [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC 959, DOI 10.17487/RFC0959, October 1985,
https://www.rfc-editor.org/info/rfc959. - [RFC2083] Boutell, T., "PNG (Portable Network Graphics) Specification Version 1.0", RFC 2083, DOI 10.17487/RFC2083, March 1997,
https://www.rfc-editor.org/info/rfc2083. - [RFC3533] Pfeiffer, S., "The Ogg Encapsulation Format Version 0", RFC 3533, DOI 10.17487/RFC3533, May 2003,
https://www.rfc-editor.org/info/rfc3533. - [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet Denial-of-Service Considerations", RFC 4732, DOI 10.17487/RFC4732, December 2006,
https://www.rfc-editor.org/info/rfc4732. - [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022,
https://www.rfc-editor.org/info/rfc9110. - [SMB-CIFS] Microsoft Corporation, "[MS-CIFS]: Common Internet File System (CIFS) Protocol", October 2020,
https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/MS-CIFS/%5bMS-CIFS%5d.pdf. - [SP800-38A] National Institute of Standards and Technology (NIST), "Recommendation for Block Cipher Modes of Operation: Methods and Techniques", DOI 10.6028/NIST.SP.800-38A, NIST Special Publication 800-38A, December 2001,
https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf. - [SP800-67] National Institute of Standards and Technology (NIST), "Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher", DOI 10.6028/NIST.SP.800-67r2, NIST Special Publication 800-67, November 2017,
https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-67r2.pdf. - [Twofish] Schneier, B., Kelsey, J., Whiting, D., Wagner, D., Hall, C., and N. Ferguson, "Twofish: A 128-Bit Block Cipher", June 1998,
https://www.schneier.com/academic/archives/1998/06/twofish_a_128-bit_bl.html. - [WebM-Enc] Galligan, F., "WebM Encryption", September 2016,
https://www.webmproject.org/docs/webm-encryption/. - [WebVTT] Pieters, S., Pfeiffer, S., Ed., Jaegenstedt, P., and I. Hickson, "WebVTT: The Web Video Text Tracks Format", W3C Candidate Recommendation, April 2019,
https://www.w3.org/TR/2019/CR-webvtt1-20190404/.
Appendix A. Historic Deprecated Elements 🕰️💜
okay so Matroska has been glowing up since 2002 🌸, and a lot of the parts people considered for the format never actually got used. Plenty of them were honestly designed kinda wonky 😭. Lots of the elements defined back then don't show up in any known files, even though they were in public specs. DivX also had a few custom elements for its own custom features 💅
In this appendix we list the elements that have a known ID that SHOULD NOT be reused, so you don't collide with existing files 🚫. IANA might reassign these IDs in the future if there are no more IDs left for a given size 🔄. Each one gets a quick note about what it was used for, but that text is not normative 🙈
A.1. SilentTracks Element 🤫
type / id: master / 0x5854
path: \Segment\Cluster\SilentTracksSilentTracks is the list of tracks that aren't being used in that part of the stream. It's useful when you're using overlay tracks for seeking or deciding which track to use 🎀
A.2. SilentTrackNumber Element 🔢
type / id: uinteger / 0x58D7
path: \Segment\Cluster\SilentTracks\SilentTrackNumberThis is one of the track numbers that isn't used from now on in the stream. It could change later if it isn't specified as silent in a further Cluster 🦋
A.3. BlockVirtual Element 🫥
type / id: binary / 0xA2
path: \Segment\Cluster\BlockGroup\BlockVirtualBlockVirtual is a Block with no data. It must be stored in the stream at the place the real Block would be in display order 🎬
A.4. ReferenceVirtual Element 👻
type / id: integer / 0xFD
path: \Segment\Cluster\BlockGroup\ReferenceVirtualReferenceVirtual holds the Segment Position of the data that would otherwise be in the position of the virtual block 📍
A.5. Slices Element 🍰
type / id: master / 0x8E
path: \Segment\Cluster\BlockGroup\SlicesSlices contains the slices description ✂️
A.6. TimeSlice Element ⏱️
type / id: master / 0xE8
path: \Segment\Cluster\BlockGroup\Slices\TimeSliceTimeSlice contains extra time information about the data contained in the Block. Being able to interpret this element is not required for playback 🙌
A.7. LaceNumber Element 🔁
type / id: uinteger / 0xCC
path: \Segment\Cluster\BlockGroup\Slices\TimeSlice\LaceNumberLaceNumber is 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 💫
A.8. FrameNumber Element 🎞️
type / id: uinteger / 0xCD
path: \Segment\Cluster\BlockGroup\Slices\TimeSlice\FrameNumberFrameNumber is the number of the frame to generate from this lace with this delay. It allows for the generation of many frames from the same Block/Frame 🌈
A.9. BlockAdditionID Element 🆔
type / id: uinteger / 0xCB
path: \Segment\Cluster\BlockGroup\Slices\TimeSlice\BlockAdditionIDBlockAdditionID is the ID of the BlockAdditional element (0 is the main Block) 👑
A.10. Delay Element ⏳
type / id: uinteger / 0xCE
path: \Segment\Cluster\BlockGroup\Slices\TimeSlice\DelayDelay is the delay to apply to the element, expressed in Track Ticks. See Section 11.1 🧮
A.11. SliceDuration Element 🕰️
type / id: uinteger / 0xCF
path: \Segment\Cluster\BlockGroup\Slices\TimeSlice\SliceDurationSliceDuration is the duration to apply to the element, expressed in Track Ticks. See Section 11.1 ✨
A.12. ReferenceFrame Element 🖼️
type / id: master / 0xC8
path: \Segment\Cluster\BlockGroup\ReferenceFrameReferenceFrame contains information about the last reference frame. See [DivXTrickTrack] 🔍
A.13. ReferenceOffset Element ↪️
type / id: uinteger / 0xC9
path: \Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceOffsetReferenceOffset is the relative offset, in bytes, from the previous BlockGroup element for this Smooth FF/RW video track to the containing BlockGroup element. See [DivXTrickTrack] 🎢
A.14. ReferenceTimestamp Element 🕒
type / id: uinteger / 0xCA
path: \Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceTimestampReferenceTimestamp is the timestamp of the BlockGroup pointed to by ReferenceOffset, expressed in Track Ticks. See Section 11.1 and [DivXTrickTrack] 💖
A.15. EncryptedBlock Element 🔐
type / id: binary / 0xAF
path: \Segment\Cluster\EncryptedBlockEncryptedBlock is similar to SimpleBlock (see Section 10.2), but the data inside the Block are Transformed (encrypted and/or signed) 🛡️
A.16. MinCache Element 🧠
type / id: uinteger / 0x6DE7
path: \Segment\Tracks\TrackEntry\MinCacheMinCache is the minimum number of frames a player should be able to cache during playback. If it's set to 0, the reference pseudo-cache system is not used 🍓
A.17. MaxCache Element 📦
type / id: uinteger / 0x6DF8
path: \Segment\Tracks\TrackEntry\MaxCacheMaxCache is the maximum cache size necessary to store referenced frames in and the current frame. 0 means no cache is needed 🧚
A.18. TrackOffset Element ✨
type / id: integer / 0x537F
path: \Segment\Tracks\TrackEntry\TrackOffsetokay bestie, this one adds a value onto the Block's Timestamp 🕰️ The value is measured in Matroska Ticks, which means nanoseconds (see Section 11.1). It's how you nudge a track's playback offset 🎀
A.19. CodecSettings Element 💖
type / id: utf-8 / 0x3A9697
path: \Segment\Tracks\TrackEntry\CodecSettingsthis is a string that describes the encoding setting that got used 📝
A.20. CodecInfoURL Element 🔗
type / id: string / 0x3B4040
path: \Segment\Tracks\TrackEntry\CodecInfoURLa URL where you can find info about the codec that was used 🧚
A.21. CodecDownloadURL Element 🌸
type / id: string / 0x26B240
path: \Segment\Tracks\TrackEntry\CodecDownloadURLanother URL, but this one is for downloading info about the codec that was used 📥
A.22. CodecDecodeAll Element 🙈
type / id: uinteger / 0xAA
path: \Segment\Tracks\TrackEntry\CodecDecodeAllset this to 1 if the codec can decode data that might be damaged 💀 it's giving resilient 💪
A.23. TrackOverlay Element 🦋
type / id: uinteger / 0x6FAB
path: \Segment\Tracks\TrackEntry\TrackOverlaythis marks a track as an overlay track for the track whose number is given in the uinteger. So when this track has a gap on SilentTracks, the overlay track should be used instead 🍓 If you have more than one TrackOverlay, the order matters: the first one is the one that should be used. If the first one can't be found, it should be the second, and so on 🔥
A.24. AspectRatioType Element 📐
type / id: uinteger / 0x54B3
path: \Segment\Tracks\TrackEntry\Video\AspectRatioTypethis one specifies the possible modifications to the aspect ratio 🎬
A.25. GammaValue Element 🌈
type / id: float / 0x2FB523
path: \Segment\Tracks\TrackEntry\Video\GammaValuethe gamma value, plain and simple ✨
A.26. FrameRate Element 🎞️
type / id: float / 0x2383E3
path: \Segment\Tracks\TrackEntry\Video\FrameRatethis is the number of frames per second 🤍 It's informational only, so don't treat it as gospel. It's meant for constant frame rate streams and should not be used for a variable frame rate TrackEntry. Not me using it on a VFR track 😭
A.27. ChannelPositions Element 🎧
type / id: binary / 0x7D7B
path: \Segment\Tracks\TrackEntry\Audio\ChannelPositionsthis is a table of horizontal angles, one for each channel in order 🎶
A.28. TrickTrackUID Element 👑
type / id: uinteger / 0xC0
path: \Segment\Tracks\TrackEntry\TrickTrackUIDthis is the TrackUID of the Smooth FF/RW video that lives in the paired EBML structure matching this video track. Go check [DivXTrickTrack] for the full tea 🍵
A.29. TrickTrackSegmentUID Element 🫶
type / id: binary / 0xC1
path: \Segment\Tracks\TrackEntry\TrickTrackSegmentUIDthis is the SegmentUUID of the Segment that holds the track named by TrickTrackUID. See [DivXTrickTrack] 🧩
A.30. TrickTrackFlag Element 🚩
type / id: uinteger / 0xC6
path: \Segment\Tracks\TrackEntry\TrickTrackFlagset this to 1 if the video track is a Smooth FF/RW track. When it's set to 1, MasterTrackUID and MasterTrackSegUID should be present, and BlockGroups for this track must contain ReferenceFrame structures 💅 If it's not set that way, then TrickTrackUID and TrickTrackSegUID must be present, but only when this track has a matching Smooth FF/RW track. See [DivXTrickTrack] 🎀
A.31. TrickMasterTrackUID Element 🌟
type / id: uinteger / 0xC7
path: \Segment\Tracks\TrackEntry\TrickMasterTrackUIDthis is the TrackUID of the video track in the paired EBML structure that matches this Smooth FF/RW track. See [DivXTrickTrack] 💜
A.32. TrickMasterTrackSegmentUID Element 🪄
type / id: binary / 0xC4
path: \Segment\Tracks\TrackEntry\TrickMasterTrackSegmentUIDthis is the SegmentUUID of the Segment that holds the track identified by MasterTrackUID. See [DivXTrickTrack] 🫧
A.33. ContentSignature Element 🔏
type / id: binary / 0x47E3
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentSignaturethis is a cryptographic signature of the contents 🔐 very secure, very serious, very iconic 💅
A.34. ContentSigKeyID Element 🗝️
type / id: binary / 0x47E4
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentSigKeyIDthis is the ID of the private key that the data was signed with 🔑
A.35. ContentSigAlgo Element 🧮
type / id: uinteger / 0x47E5
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentSigAlgothis is the algorithm that got used for the signature 🤓
A.36. ContentSigHashAlgo Element 🍯
type / id: uinteger / 0x47E6
path: \Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co
ntentEncryption\ContentSigHashAlgoand this is the hash algorithm that got used for the signature 🌷
A.37. CueRefCluster Element 🗂️
type / id: uinteger / 0x97
path: \Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefCl
usterthis is the Segment Position of the Cluster that holds the referenced Block 📍
A.38. CueRefNumber Element 🔢
type / id: uinteger / 0x535F
path: \Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefNu
mberthis is the number of the referenced Block of Track X in the specified Cluster 🎯
A.39. CueRefCodecState Element 🧠
type / id: uinteger / 0xEB
path: \Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefCo
decStatethis is the Segment Position of the Codec State that matches this referenced element. A 0 means the data is taken from the initial TrackEntry 🌱
A.40. FileReferral Element 📎
type / id: binary / 0x4675
path: \Segment\Attachments\AttachedFile\FileReferralthis is a binary value that a track or codec can point to when it needs the attachment 🧸
A.41. FileUsedStartTime Element ⏱️
type / id: uinteger / 0x4661
path: \Segment\Attachments\AttachedFile\FileUsedStartTimethis is the timestamp when this optimized font attachment comes into context. It's expressed in Segment Ticks, which are based on TimestampScale. See [DivXWorldFonts] 🔤
A.42. FileUsedEndTime Element ⏳
type / id: uinteger / 0x4662
path: \Segment\Attachments\AttachedFile\FileUsedEndTimeand this is the timestamp when this optimized font attachment goes out of context. It's also expressed in Segment Ticks, based on TimestampScale. See [DivXWorldFonts] 🌙
A.43. TagDefaultBogus Element 🫠
type / id: uinteger / 0x44B4
path: \Segment\Tags\Tag\+SimpleTag\TagDefaultBogusthis is a variant of the TagDefault element that has a bogus element ID, so it's a little chaotic 🙃 See Section 5.1.8.1.2.4 for the details 📖
Authors' Addresses 🎀
Steve Lhomme Email: slhomme@matroska.org
Moritz Bunkus Email: moritz@bunkus.org
Dave Rice Email: dave@dericed.com
📦 where this page comes from
- ietf: rfc9559 2024-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms