idnits 2.17.1 draft-ietf-cellar-matroska-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (17 April 2020) is 1462 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 6518 -- Looks like a reference, but probably isn't: '0' on line 6519 -- Looks like a reference, but probably isn't: '2' on line 6518 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 cellar S. Lhomme 3 Internet-Draft 4 Intended status: Informational M. Bunkus 5 Expires: 19 October 2020 6 D. Rice 7 17 April 2020 9 Matroska Media Container Format Specifications 10 draft-ietf-cellar-matroska-05 12 Abstract 14 This document defines the Matroska audiovisual container, including 15 definitions of its structural elements, as well as its terminology, 16 vocabulary, and application. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on 19 October 2020. 35 Copyright Notice 37 Copyright (c) 2020 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 42 license-info) in effect on the date of publication of this document. 43 Please review these documents carefully, as they describe your rights 44 and restrictions with respect to this document. Code Components 45 extracted from this document must include Simplified BSD License text 46 as described in Section 4.e of the Trust Legal Provisions and are 47 provided without warranty as described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 52 2. Status of this document . . . . . . . . . . . . . . . . . . . 5 53 3. Security Considerations . . . . . . . . . . . . . . . . . . . 6 54 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 55 5. Notation and Conventions . . . . . . . . . . . . . . . . . . 6 56 6. Basis in EBML . . . . . . . . . . . . . . . . . . . . . . . . 7 57 6.1. Added Constraints on EBML . . . . . . . . . . . . . . . . 7 58 6.2. Matroska Design . . . . . . . . . . . . . . . . . . . . . 7 59 6.2.1. Language Codes . . . . . . . . . . . . . . . . . . . 7 60 6.2.2. Physical Types . . . . . . . . . . . . . . . . . . . 8 61 6.2.3. Block Structure . . . . . . . . . . . . . . . . . . . 9 62 6.2.4. Lacing . . . . . . . . . . . . . . . . . . . . . . . 10 63 7. Matroska Structure . . . . . . . . . . . . . . . . . . . . . 15 64 8. Matroska Additions to Schema Element Attributes . . . . . . . 23 65 9. Matroska Schema . . . . . . . . . . . . . . . . . . . . . . . 24 66 9.1. EBMLMaxIDLength Element . . . . . . . . . . . . . . . . . 24 67 9.2. EBMLMaxSizeLength Element . . . . . . . . . . . . . . . . 24 68 10. Segment Element . . . . . . . . . . . . . . . . . . . . . . . 25 69 10.1. SeekHead Element . . . . . . . . . . . . . . . . . . . . 25 70 10.1.1. Seek Element . . . . . . . . . . . . . . . . . . . . 25 71 10.2. Info Element . . . . . . . . . . . . . . . . . . . . . . 26 72 10.2.1. SegmentUID Element . . . . . . . . . . . . . . . . . 27 73 10.2.2. SegmentFilename Element . . . . . . . . . . . . . . 27 74 10.2.3. PrevUID Element . . . . . . . . . . . . . . . . . . 27 75 10.2.4. PrevFilename Element . . . . . . . . . . . . . . . . 28 76 10.2.5. NextUID Element . . . . . . . . . . . . . . . . . . 28 77 10.2.6. NextFilename Element . . . . . . . . . . . . . . . . 29 78 10.2.7. SegmentFamily Element . . . . . . . . . . . . . . . 29 79 10.2.8. ChapterTranslate Element . . . . . . . . . . . . . . 29 80 10.2.9. TimestampScale Element . . . . . . . . . . . . . . . 31 81 10.2.10. Duration Element . . . . . . . . . . . . . . . . . . 31 82 10.2.11. DateUTC Element . . . . . . . . . . . . . . . . . . 32 83 10.2.12. Title Element . . . . . . . . . . . . . . . . . . . 32 84 10.2.13. MuxingApp Element . . . . . . . . . . . . . . . . . 32 85 10.2.14. WritingApp Element . . . . . . . . . . . . . . . . . 33 86 10.3. Cluster Element . . . . . . . . . . . . . . . . . . . . 33 87 10.3.1. Timestamp Element . . . . . . . . . . . . . . . . . 33 88 10.3.2. SilentTracks Element . . . . . . . . . . . . . . . . 34 89 10.3.3. Position Element . . . . . . . . . . . . . . . . . . 34 90 10.3.4. PrevSize Element . . . . . . . . . . . . . . . . . . 35 91 10.3.5. SimpleBlock Element . . . . . . . . . . . . . . . . 35 92 10.3.6. BlockGroup Element . . . . . . . . . . . . . . . . . 35 93 10.3.7. EncryptedBlock Element . . . . . . . . . . . . . . . 45 94 10.4. Tracks Element . . . . . . . . . . . . . . . . . . . . . 45 95 10.4.1. TrackEntry Element . . . . . . . . . . . . . . . . . 45 96 10.5. Cues Element . . . . . . . . . . . . . . . . . . . . . . 106 97 10.5.1. CuePoint Element . . . . . . . . . . . . . . . . . . 106 98 10.6. Attachments Element . . . . . . . . . . . . . . . . . . 112 99 10.6.1. AttachedFile Element . . . . . . . . . . . . . . . . 112 100 10.7. Chapters Element . . . . . . . . . . . . . . . . . . . . 115 101 10.7.1. EditionEntry Element . . . . . . . . . . . . . . . . 116 102 10.8. Tags Element . . . . . . . . . . . . . . . . . . . . . . 126 103 10.8.1. Tag Element . . . . . . . . . . . . . . . . . . . . 127 104 11. Matroska Element Ordering . . . . . . . . . . . . . . . . . . 134 105 11.1. Top-Level Elements . . . . . . . . . . . . . . . . . . . 134 106 11.2. CRC-32 . . . . . . . . . . . . . . . . . . . . . . . . . 134 107 11.3. SeekHead . . . . . . . . . . . . . . . . . . . . . . . . 135 108 11.4. Cues (index) . . . . . . . . . . . . . . . . . . . . . . 135 109 11.5. Info . . . . . . . . . . . . . . . . . . . . . . . . . . 135 110 11.6. Chapters Element . . . . . . . . . . . . . . . . . . . . 135 111 11.7. Attachments . . . . . . . . . . . . . . . . . . . . . . 136 112 11.8. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 136 113 11.9. Optimum layout from a muxer . . . . . . . . . . . . . . 136 114 11.10. Optimum layout after editing tags . . . . . . . . . . . 136 115 11.11. Optimum layout with Cues at the front . . . . . . . . . 137 116 11.12. Cluster Timestamp . . . . . . . . . . . . . . . . . . . 137 117 12. Chapters . . . . . . . . . . . . . . . . . . . . . . . . . . 137 118 12.1. Edition and Chapter Flags . . . . . . . . . . . . . . . 137 119 12.1.1. Chapter Flags . . . . . . . . . . . . . . . . . . . 137 120 12.1.2. Edition Flags . . . . . . . . . . . . . . . . . . . 138 121 12.2. Menu features . . . . . . . . . . . . . . . . . . . . . 141 122 12.2.1. Matroska Script (0) . . . . . . . . . . . . . . . . 141 123 12.2.2. DVD menu (1) . . . . . . . . . . . . . . . . . . . . 142 124 12.3. Example 1 : basic chaptering . . . . . . . . . . . . . . 144 125 12.4. Example 2 : nested chapters . . . . . . . . . . . . . . 146 126 12.4.1. The Micronauts "Bleep To Bleep" . . . . . . . . . . 146 127 13. Attachments . . . . . . . . . . . . . . . . . . . . . . . . . 149 128 13.1. Cover Art . . . . . . . . . . . . . . . . . . . . . . . 149 129 14. Cues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 130 14.1. Recommendations . . . . . . . . . . . . . . . . . . . . 151 131 15. Matroska Streaming . . . . . . . . . . . . . . . . . . . . . 151 132 15.1. File Access . . . . . . . . . . . . . . . . . . . . . . 152 133 15.2. Livestreaming . . . . . . . . . . . . . . . . . . . . . 152 134 16. Menu Specifications . . . . . . . . . . . . . . . . . . . . . 153 135 16.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 153 136 16.1.1. Highlights/Hotspots . . . . . . . . . . . . . . . . 153 137 16.1.2. Playback features . . . . . . . . . . . . . . . . . 154 138 16.1.3. Player requirements . . . . . . . . . . . . . . . . 155 139 16.2. Working Graph . . . . . . . . . . . . . . . . . . . . . 155 140 17. Unknown elements . . . . . . . . . . . . . . . . . . . . . . 155 141 18. Default Values . . . . . . . . . . . . . . . . . . . . . . . 155 142 19. DefaultDecodedFieldDuration . . . . . . . . . . . . . . . . . 155 143 20. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 156 144 21. Image Presentation . . . . . . . . . . . . . . . . . . . . . 156 145 21.1. Cropping . . . . . . . . . . . . . . . . . . . . . . . . 157 146 21.2. Rotation . . . . . . . . . . . . . . . . . . . . . . . . 157 147 22. Matroska versioning . . . . . . . . . . . . . . . . . . . . . 157 148 23. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . 158 149 24. Segment Position . . . . . . . . . . . . . . . . . . . . . . 158 150 24.1. Segment Position Exception . . . . . . . . . . . . . . . 158 151 24.2. Example of Segment Position . . . . . . . . . . . . . . 159 152 25. Linked Segments . . . . . . . . . . . . . . . . . . . . . . . 159 153 25.1. Hard Linking . . . . . . . . . . . . . . . . . . . . . . 159 154 25.2. Medium Linking . . . . . . . . . . . . . . . . . . . . . 161 155 25.3. Soft Linking . . . . . . . . . . . . . . . . . . . . . . 162 156 26. Track Flags . . . . . . . . . . . . . . . . . . . . . . . . . 162 157 26.1. Default flag . . . . . . . . . . . . . . . . . . . . . . 162 158 26.2. Forced flag . . . . . . . . . . . . . . . . . . . . . . 162 159 26.3. Track Operation . . . . . . . . . . . . . . . . . . . . 163 160 26.4. Overlay Track . . . . . . . . . . . . . . . . . . . . . 163 161 26.5. Multi-planar and 3D videos . . . . . . . . . . . . . . . 163 162 27. Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . 164 163 27.1. Timestamp Types . . . . . . . . . . . . . . . . . . . . 164 164 27.2. Block Timestamps . . . . . . . . . . . . . . . . . . . . 165 165 27.3. Raw Timestamp . . . . . . . . . . . . . . . . . . . . . 165 166 27.4. TimestampScale . . . . . . . . . . . . . . . . . . . . . 165 167 27.5. TimestampScale Rounding . . . . . . . . . . . . . . . . 166 168 27.6. TrackTimestampScale . . . . . . . . . . . . . . . . . . 168 169 28. Normative References . . . . . . . . . . . . . . . . . . . . 169 170 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 170 172 1. Introduction 174 Matroska aims to become THE standard of multimedia container formats. 175 It was derived from a project called MCF (http://mukoli.free.fr/mcf/ 176 mcf.html), but differentiates from it significantly because it is 177 based on EBML (https://github.com/Matroska-Org/ebml- 178 specification/blob/master/specification.markdown) (Extensible Binary 179 Meta Language), a binary derivative of XML. EBML enables significant 180 advantages in terms of future format extensibility, without breaking 181 file support in old parsers. 183 First, it is essential to clarify exactly "What an Audio/Video 184 container is", to avoid any misunderstandings: 186 * It is NOT a video or audio compression format (codec) 188 * It is an envelope for which there can be many audio, video and 189 subtitles streams, allowing the user to store a complete movie or 190 CD in a single file. 192 Matroska is designed with the future in mind. It incorporates 193 features like: 195 * Fast seeking in the file 197 * Chapter entries 199 * Full metadata (tags) support 201 * Selectable subtitle/audio/video streams 203 * Modularly expandable 205 * Error resilience (can recover playback even when the stream is 206 damaged) 208 * Streamable over the internet and local networks (HTTP, CIFS, FTP, 209 etc) 211 * Menus (like DVDs have) 213 Matroska is an open standards project. This means for personal use 214 it is absolutely free to use and that the technical specifications 215 describing the bitstream are open to everybody, even to companies 216 that would like to support it in their products. 218 2. Status of this document 220 This document is a work-in-progress specification defining the 221 Matroska file format as part of the IETF Cellar working group 222 (https://datatracker.ietf.org/wg/cellar/charter/). But since it's 223 quite complete it is used as a reference for the development of 224 libmatroska. Legacy versions of the specification can be found here 225 (https://matroska.org/files/matroska.pdf) (PDF doc by Alexander 226 Noé -- outdated). 228 For a simplified diagram of the layout of a Matroska file, see the 229 Diagram page (diagram.md). 231 A more refined and detailed version of the EBML specifications is 232 being worked on here (https://github.com/Matroska-Org/ebml- 233 specification/blob/master/specification.markdown). 235 The table found below is now generated from the "source" of the 236 Matroska specification. This XML file (https://github.com/Matroska- 237 Org/foundation-source/blob/master/spectool/specdata.xml) is also used 238 to generate the semantic data used in libmatroska and libmatroska2. 239 We encourage anyone to use and monitor its changes so your code is 240 spec-proof and always up to date. 242 Note that versions 1, 2 and 3 have been finalized. Version 4 is 243 currently work in progress. There MAY be further additions to v4. 245 3. Security Considerations 247 Matroska inherits security considerations from EBML. 249 Attacks on a "Matroska Reader" could include: 251 * Storage of a arbitrary and potentially executable data within an 252 "Attachment Element". "Matroska Readers" that extract or use data 253 from Matroska Attachments SHOULD check that the data adheres to 254 expectations. 256 * A "Matroska Attachment" with an inaccurate mime-type. 258 4. IANA Considerations 260 To be determined. 262 5. Notation and Conventions 264 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 265 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 266 "OPTIONAL" in this document are to be interpreted as described in BCP 267 14 [RFC2119] [RFC8174] when, and only when, they appear in all 268 capitals, as shown here. 270 This document defines specific terms in order to define the format 271 and application of "Matroska". Specific terms are defined below: 273 "Matroska": a multimedia container format based on EBML (Extensible 274 Binary Meta Language) 276 "Matroska Reader": A "Matroska Reader" is a data parser that 277 interprets the semantics of a Matroska document and creates a way for 278 programs to use "Matroska". 280 "Matroska Player": A "Matroska Player" is a "Matroska Reader" with a 281 primary purpose of playing audiovisual files, including "Matroska" 282 documents. 284 6. Basis in EBML 286 Matroska is a Document Type of EBML (Extensible Binary Meta 287 Language). This specification is dependent on the EBML Specification 288 (https://github.com/Matroska-Org/ebml-specification/blob/master/ 289 specification.markdown). For an understanding of Matroska's EBML 290 Schema, see in particular the sections of the EBML Specification 291 covering EBML Element Types (https://github.com/Matroska-Org/ebml- 292 specification/blob/master/specification.markdown#ebml-element-types), 293 EBML Schema (https://github.com/Matroska-Org/ebml- 294 specification/blob/master/specification.markdown#ebml-schema), and 295 EBML Structure (https://github.com/Matroska-Org/ebml- 296 specification/blob/master/specification.markdown#structure). 298 6.1. Added Constraints on EBML 300 As an EBML Document Type, Matroska adds the following constraints to 301 the EBML specification. 303 * The "docType" of the "EBML Header" MUST be 'matroska'. 305 * The "EBMLMaxIDLength" of the "EBML Header" MUST be "4". 307 * The "EBMLMaxSizeLength" of the "EBML Header" MUST be between "1" 308 and "8" inclusive. 310 6.2. Matroska Design 312 All top-levels elements (Segment and direct sub-elements) are coded 313 on 4 octets, i.e. class D elements. 315 6.2.1. Language Codes 317 Matroska from version 1 through 3 uses language codes that can be 318 either the 3 letters bibliographic ISO-639-2 319 (https://www.loc.gov/standards/iso639-2/php/English_list.php) form 320 (like "fre" for french), or such a language code followed by a dash 321 and a country code for specialities in languages (like "fre-ca" for 322 Canadian French). The "ISO 639-2 Language Elements" are "Language 323 Element", "TagLanguage Element", and "ChapLanguage Element". 325 Starting in Matroska version 4, either "ISO 639-2" or BCP 47 326 (https://tools.ietf.org/html/bcp47) MAY be used, although "BCP 47" is 327 RECOMMENDED. The "BCP 47 Language Elements" are "LanguageIETF 328 Element", "TagLanguageIETF Element", and "ChapLanguageIETF Element". 329 If a "BCP 47 Language Element" and an "ISO 639-2 Language Element" 330 are used within the same "Parent Element", then the "ISO 639-2 331 Language Element" MUST be ignored and precedence given to the "BCP 47 332 Language Element". 334 Country codes are the same as used for internet domains 335 (https://www.iana.org/domains/root/db). 337 6.2.2. Physical Types 339 Each level can have different meanings for audio and video. The 340 ORIGINAL_MEDIUM tag can be used to specify a string for 341 ChapterPhysicalEquiv = 60. Here is the list of possible levels for 342 both audio and video : 344 +----------------------+------------+-----------+-----------------+ 345 | ChapterPhysicalEquiv | Audio | Video | Comment | 346 +======================+============+===========+=================+ 347 | 70 | SET / | SET / | the collection | 348 | | PACKAGE | PACKAGE | of different | 349 | | | | media | 350 +----------------------+------------+-----------+-----------------+ 351 | 60 | CD / 12" / | DVD / VHS | the physical | 352 | | 10" / 7" / | / | medium like a | 353 | | TAPE / | LASERDISC | CD or a DVD | 354 | | MINIDISC / | | | 355 | | DAT | | | 356 +----------------------+------------+-----------+-----------------+ 357 | 50 | SIDE | SIDE | when the | 358 | | | | original medium | 359 | | | | (LP/DVD) has | 360 | | | | different sides | 361 +----------------------+------------+-----------+-----------------+ 362 | 40 | - | LAYER | another | 363 | | | | physical level | 364 | | | | on DVDs | 365 +----------------------+------------+-----------+-----------------+ 366 | 30 | SESSION | SESSION | as found on CDs | 367 | | | | and DVDs | 368 +----------------------+------------+-----------+-----------------+ 369 | 20 | TRACK | - | as found on | 370 | | | | audio CDs | 371 +----------------------+------------+-----------+-----------------+ 372 | 10 | INDEX | - | the first | 373 | | | | logical level | 374 | | | | of the side/ | 375 | | | | medium | 376 +----------------------+------------+-----------+-----------------+ 378 Table 1 380 6.2.3. Block Structure 382 Bit 0 is the most significant bit. 384 Frames using references SHOULD be stored in "coding order". That 385 means the references first and then the frames referencing them. A 386 consequence is that timestamps might not be consecutive. But a frame 387 with a past timestamp MUST reference a frame already known, otherwise 388 it's considered bad/void. 390 6.2.3.1. Block Header 392 +--------+--------+---------------------------------------------+ 393 | Offset | Player | Description | 394 +========+========+=============================================+ 395 | 0x00+ | MUST | Track Number (Track Entry). It is coded in | 396 | | | EBML like form (1 octet if the value is < | 397 | | | 0x80, 2 if < 0x4000, etc) (most significant | 398 | | | bits set to increase the range). | 399 +--------+--------+---------------------------------------------+ 400 | 0x01+ | MUST | Timestamp (relative to Cluster timestamp, | 401 | | | signed int16) | 402 +--------+--------+---------------------------------------------+ 404 Table 2 406 6.2.3.2. Block Header Flags 408 +--------+-----+--------+------------------------------------+ 409 | Offset | Bit | Player | Description | 410 +========+=====+========+====================================+ 411 | 0x03+ | 0-3 | - | Reserved, set to 0 | 412 +--------+-----+--------+------------------------------------+ 413 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode | 414 | | | | this frame but not display it | 415 +--------+-----+--------+------------------------------------+ 416 | 0x03+ | 5-6 | MUST | Lacing | 417 +--------+-----+--------+------------------------------------+ 418 | | | | * 00 : no lacing | 419 +--------+-----+--------+------------------------------------+ 420 | | | | * 01 : Xiph lacing | 421 +--------+-----+--------+------------------------------------+ 422 | | | | * 11 : EBML lacing | 423 +--------+-----+--------+------------------------------------+ 424 | | | | * 10 : fixed-size lacing | 425 +--------+-----+--------+------------------------------------+ 426 | 0x03+ | 7 | - | not used | 427 +--------+-----+--------+------------------------------------+ 429 Table 3 431 6.2.4. Lacing 433 Lacing is a mechanism to save space when storing data. It is 434 typically used for small blocks of data (referred to as frames in 435 Matroska). There are 3 types of lacing: 437 1. Xiph, inspired by what is found in the Ogg container 438 2. EBML, which is the same with sizes coded differently 440 3. fixed-size, where the size is not coded 442 For example, a user wants to store 3 frames of the same track. The 443 first frame is 800 octets long, the second is 500 octets long and the 444 third is 1000 octets long. As these data are small, they can be 445 stored in a lace to save space. They will then be stored in the same 446 block as follows: 448 6.2.4.1. Xiph lacing 450 * Block head (with lacing bits set to 01) 452 * Lacing head: Number of frames in the lace -1, i.e. 2 (the 800 and 453 500 octets one) 455 * Lacing sizes: only the 2 first ones will be coded, 800 gives 456 255;255;255;35, 500 gives 255;245. The size of the last frame is 457 deduced from the total size of the Block. 459 * Data in frame 1 461 * Data in frame 2 463 * Data in frame 3 465 A frame with a size multiple of 255 is coded with a 0 at the end of 466 the size, for example 765 is coded 255;255;255;0. 468 6.2.4.2. EBML lacing 470 In this case, the size is not coded as blocks of 255 bytes, but as a 471 difference with the previous size and this size is coded as in EBML. 472 The first size in the lace is unsigned as in EBML. The others use a 473 range shifting to get a sign on each value: 475 +--------------------------+---------------------------------------+ 476 | Bit Representation | Value | 477 +==========================+=======================================+ 478 | 1xxx xxxx | value -(2^6-1) to 2^6-1 (ie 0 to | 479 | | 2^7-2 minus 2^6-1, half of the range) | 480 +--------------------------+---------------------------------------+ 481 | 01xx xxxx xxxx xxxx | value -(2^13-1) to 2^(13-1) | 482 +--------------------------+---------------------------------------+ 483 | 001x xxxx xxxx xxxx xxxx | value -(2^20-1) to 2^(20-1) | 484 | xxxx | | 485 +--------------------------+---------------------------------------+ 486 | 0001 xxxx xxxx xxxx xxxx | value -(2^27-1) to 2^(27-1) | 487 | xxxx xxxx xxxx | | 488 +--------------------------+---------------------------------------+ 489 | 0000 1xxx xxxx xxxx xxxx | value -(2^34-1) to 2^(34-1) | 490 | xxxx xxxx xxxx xxxx xxxx | | 491 +--------------------------+---------------------------------------+ 492 | 0000 01xx xxxx xxxx xxxx | value -(2^41-1) to 2^(41-1) | 493 | xxxx xxxx xxxx xxxx xxxx | | 494 | xxxx xxxx | | 495 +--------------------------+---------------------------------------+ 496 | 0000 001x xxxx xxxx xxxx | value -(2^48-1) to 2^(48-1) | 497 | xxxx xxxx xxxx xxxx xxxx | | 498 | xxxx xxxx xxxx xxxx | | 499 +--------------------------+---------------------------------------+ 501 Table 4 503 * Block head (with lacing bits set to 11) 505 * Lacing head: Number of frames in the lace -1, i.e. 2 (the 800 and 506 500 octets one) 508 * Lacing sizes: only the 2 first ones will be coded, 800 gives 0x320 509 0x4000 = 0x4320, 500 is coded as -300 : - 0x12C + 0x1FFF + 0x4000 510 = 0x5ED3. The size of the last frame is deduced from the total 511 size of the Block. 513 * Data in frame 1 515 * Data in frame 2 517 * Data in frame 3 519 6.2.4.3. Fixed-size lacing 521 In this case, only the number of frames in the lace is saved, the 522 size of each frame is deduced from the total size of the Block. For 523 example, for 3 frames of 800 octets each: 525 * Block head (with lacing bits set to 10) 527 * Lacing head: Number of frames in the lace -1, i.e. 2 529 * Data in frame 1 531 * Data in frame 2 533 * Data in frame 3 535 6.2.4.4. SimpleBlock Structure 537 The "SimpleBlock" is inspired by the Block structure (#block- 538 structure). The main differences are the added Keyframe flag and 539 Discardable flag. Otherwise everything is the same. 541 Bit 0 is the most significant bit. 543 Frames using references SHOULD be stored in "coding order". That 544 means the references first and then the frames referencing them. A 545 consequence is that timestamps might not be consecutive. But a frame 546 with a past timestamp MUST reference a frame already known, otherwise 547 it's considered bad/void. 549 6.2.4.4.1. SimpleBlock Header 551 +--------+--------+---------------------------------------------+ 552 | Offset | Player | Description | 553 +========+========+=============================================+ 554 | 0x00+ | MUST | Track Number (Track Entry). It is coded in | 555 | | | EBML like form (1 octet if the value is < | 556 | | | 0x80, 2 if < 0x4000, etc) (most significant | 557 | | | bits set to increase the range). | 558 +--------+--------+---------------------------------------------+ 559 | 0x01+ | MUST | Timestamp (relative to Cluster timestamp, | 560 | | | signed int16) | 561 +--------+--------+---------------------------------------------+ 563 Table 5 565 6.2.4.4.2. SimpleBlock Header Flags 567 +--------+-----+--------+------------------------------------------+ 568 | Offset | Bit | Player | Description | 569 +========+=====+========+==========================================+ 570 | 0x03+ | 0 | - | Keyframe, set when the Block contains | 571 | | | | only keyframes | 572 +--------+-----+--------+------------------------------------------+ 573 | 0x03+ | 1-3 | - | Reserved, set to 0 | 574 +--------+-----+--------+------------------------------------------+ 575 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode this | 576 | | | | frame but not display it | 577 +--------+-----+--------+------------------------------------------+ 578 | 0x03+ | 5-6 | MUST | Lacing | 579 +--------+-----+--------+------------------------------------------+ 580 | | | | * 00 : no lacing | 581 +--------+-----+--------+------------------------------------------+ 582 | | | | * 01 : Xiph lacing | 583 +--------+-----+--------+------------------------------------------+ 584 | | | | * 11 : EBML lacing | 585 +--------+-----+--------+------------------------------------------+ 586 | | | | * 10 : fixed-size lacing | 587 +--------+-----+--------+------------------------------------------+ 588 | 0x03+ | 7 | - | Discardable, the frames of the Block can | 589 | | | | be discarded during playing if needed | 590 +--------+-----+--------+------------------------------------------+ 592 Table 6 594 6.2.4.5. Laced Data 596 When lacing bit is set. 598 +--------+--------+---------------------------------------------+ 599 | Offset | Player | Description | 600 +========+========+=============================================+ 601 | 0x00 | MUST | Number of frames in the lace-1 (uint8) | 602 +--------+--------+---------------------------------------------+ 603 | 0x01 / | MUST* | Lace-coded size of each frame of the lace, | 604 | 0xXX | | except for the last one (multiple uint8). | 605 | | | *This is not used with Fixed-size lacing as | 606 | | | it is calculated automatically from (total | 607 | | | size of lace) / (number of frames in lace). | 608 +--------+--------+---------------------------------------------+ 610 Table 7 612 For (possibly) Laced Data 613 +--------+--------+--------------------------+ 614 | Offset | Player | Description | 615 +========+========+==========================+ 616 | 0x00 | MUST | Consecutive laced frames | 617 +--------+--------+--------------------------+ 619 Table 8 621 7. Matroska Structure 623 A Matroska file MUST be composed of at least one "EBML Document" 624 using the "Matroska Document Type". Each "EBML Document" MUST start 625 with an "EBML Header" and MUST be followed by the "EBML Root 626 Element", defined as "Segment" in Matroska. Matroska defines several 627 "Top Level Elements" which MAY occur within the "Segment". 629 As an example, a simple Matroska file consisting of a single "EBML 630 Document" could be represented like this: 632 * "EBML Header" 634 * "Segment" 636 A more complex Matroska file consisting of an "EBML Stream" 637 (consisting of two "EBML Documents") could be represented like this: 639 * "EBML Header" 641 * "Segment" 643 * "EBML Header" 645 * "Segment" 647 The following diagram represents a simple Matroska file, comprised of 648 an "EBML Document" with an "EBML Header", a "Segment Element" (the 649 "Root Element"), and all eight Matroska "Top Level Elements". In the 650 following diagrams of this section, horizontal spacing expresses a 651 parent-child relationship between Matroska Elements (e.g. the "Info 652 Element" is contained within the "Segment Element") whereas vertical 653 alignment represents the storage order within the file. 655 +-------------+ 656 | EBML Header | 657 +---------------------------+ 658 | Segment | SeekHead | 659 | |-------------| 660 | | Info | 661 | |-------------| 662 | | Tracks | 663 | |-------------| 664 | | Chapters | 665 | |-------------| 666 | | Cluster | 667 | |-------------| 668 | | Cues | 669 | |-------------| 670 | | Attachments | 671 | |-------------| 672 | | Tags | 673 +---------------------------+ 675 The Matroska "EBML Schema" defines eight "Top Level Elements": 676 "SeekHead", "Info", "Tracks", "Chapters", "Cluster", "Cues", 677 "Attachments", and "Tags". 679 The "SeekHead Element" (also known as "MetaSeek") contains an index 680 of "Top Level Elements" locations within the "Segment". Use of the 681 "SeekHead Element" is RECOMMENDED. Without a "SeekHead Element", a 682 Matroska parser would have to search the entire file to find all of 683 the other "Top Level Elements". This is due to Matroska's flexible 684 ordering requirements; for instance, it is acceptable for the 685 "Chapters Element" to be stored after the "Cluster Elements". 687 +--------------------------------+ 688 | SeekHead | Seek | SeekID | 689 | | |--------------| 690 | | | SeekPosition | 691 +--------------------------------+ 693 Figure 1: Representation of a "SeekHead Element". 695 The "Info Element" contains vital information for identifying the 696 whole "Segment". This includes the title for the "Segment", a 697 randomly generated unique identifier, and the unique identifier(s) of 698 any linked "Segment Elements". 700 +-------------------------+ 701 | Info | SegmentUID | 702 | |------------------| 703 | | SegmentFilename | 704 | |------------------| 705 | | PrevUID | 706 | |------------------| 707 | | PrevFilename | 708 | |------------------| 709 | | NextUID | 710 | |------------------| 711 | | NextFilename | 712 | |------------------| 713 | | SegmentFamily | 714 | |------------------| 715 | | ChapterTranslate | 716 | |------------------| 717 | | TimestampScale | 718 | |------------------| 719 | | Duration | 720 | |------------------| 721 | | DateUTC | 722 | |------------------| 723 | | Title | 724 | |------------------| 725 | | MuxingApp | 726 | |------------------| 727 | | WritingApp | 728 |-------------------------| 730 Figure 2: Representation of an "Info Element" and its "Child 731 Elements". 733 The "Tracks Element" defines the technical details for each track and 734 can store the name, number, unique identifier, language and type 735 (audio, video, subtitles, etc.) of each track. For example, the 736 "Tracks Element" MAY store information about the resolution of a 737 video track or sample rate of an audio track. 739 The "Tracks Element" MUST identify all the data needed by the codec 740 to decode the data of the specified track. However, the data 741 required is contingent on the codec used for the track. For example, 742 a "Track Element" for uncompressed audio only requires the audio bit 743 rate to be present. A codec such as AC-3 would require that the 744 "CodecID Element" be present for all tracks, as it is the primary way 745 to identify which codec to use to decode the track. 747 +------------------------------------+ 748 | Tracks | TrackEntry | TrackNumber | 749 | | |--------------| 750 | | | TrackUID | 751 | | |--------------| 752 | | | TrackType | 753 | | |--------------| 754 | | | Name | 755 | | |--------------| 756 | | | Language | 757 | | |--------------| 758 | | | CodecID | 759 | | |--------------| 760 | | | CodecPrivate | 761 | | |--------------| 762 | | | CodecName | 763 | | |----------------------------------+ 764 | | | Video | FlagInterlaced | 765 | | | |-------------------| 766 | | | | FieldOrder | 767 | | | |-------------------| 768 | | | | StereoMode | 769 | | | |-------------------| 770 | | | | AlphaMode | 771 | | | |-------------------| 772 | | | | PixelWidth | 773 | | | |-------------------| 774 | | | | PixelHeight | 775 | | | |-------------------| 776 | | | | DisplayWidth | 777 | | | |-------------------| 778 | | | | DisplayHeight | 779 | | | |-------------------| 780 | | | | AspectRatioType | 781 | | | |-------------------| 782 | | | | Color | 783 | | |----------------------------------| 784 | | | Audio | SamplingFrequency | 785 | | | |-------------------| 786 | | | | Channels | 787 | | | |-------------------| 788 | | | | BitDepth | 789 |--------------------------------------------------------| 791 Figure 3: Representation of the "Tracks Element" and a selection 792 of its "Descendant Elements". 794 The "Chapters Element" lists all of the chapters. Chapters are a way 795 to set predefined points to jump to in video or audio. 797 +-----------------------------------------+ 798 | Chapters | Edition | EditionUID | 799 | | Entry |--------------------| 800 | | | EditionFlagHidden | 801 | | |--------------------| 802 | | | EditionFlagDefault | 803 | | |--------------------| 804 | | | EditionFlagOrdered | 805 | | |---------------------------------+ 806 | | | ChapterAtom | ChapterUID | 807 | | | |-------------------| 808 | | | | ChapterStringUID | 809 | | | |-------------------| 810 | | | | ChapterTimeStart | 811 | | | |-------------------| 812 | | | | ChapterTimeEnd | 813 | | | |-------------------| 814 | | | | ChapterFlagHidden | 815 | | | |-------------------------------+ 816 | | | | ChapterDisplay | ChapString | 817 | | | | |--------------| 818 | | | | | ChapLanguage | 819 +------------------------------------------------------------------+ 821 Figure 4: Representation of the "Chapters Element" and a 822 selection of its "Descendant Elements". 824 "Cluster Elements" contain the content for each track, e.g. video 825 frames. A Matroska file SHOULD contain at least one "Cluster 826 Element". The "Cluster Element" helps to break up "SimpleBlock" or 827 "BlockGroup Elements" and helps with seeking and error protection. 828 It is RECOMMENDED that the size of each individual "Cluster Element" 829 be limited to store no more than 5 seconds or 5 megabytes. Every 830 "Cluster Element" MUST contain a "Timestamp Element". This SHOULD be 831 the "Timestamp Element" used to play the first "Block" in the 832 "Cluster Element". There SHOULD be one or more "BlockGroup" or 833 "SimpleBlock Element" in each "Cluster Element". A "BlockGroup 834 Element" MAY contain a "Block" of data and any information relating 835 directly to that "Block". 837 +--------------------------+ 838 | Cluster | Timestamp | 839 | |----------------| 840 | | SilentTracks | 841 | |----------------| 842 | | Position | 843 | |----------------| 844 | | PrevSize | 845 | |----------------| 846 | | SimpleBlock | 847 | |----------------| 848 | | BlockGroup | 849 | |----------------| 850 | | EncryptedBlock | 851 +--------------------------+ 853 Figure 5: Representation of a "Cluster Element" and its immediate 854 "Child Elements". 856 +----------------------------------+ 857 | Block | Portion of | Data Type | 858 | | a Block | - Bit Flag | 859 | |--------------------------+ 860 | | Header | TrackNumber | 861 | | |-------------| 862 | | | Timestamp | 863 | | |-------------| 864 | | | Flags | 865 | | | - Gap | 866 | | | - Lacing | 867 | | | - Reserved | 868 | |--------------------------| 869 | | Optional | FrameSize | 870 | |--------------------------| 871 | | Data | Frame | 872 +----------------------------------+ 874 Figure 6: Representation of the "Block Element" structure. 876 Each "Cluster" MUST contain exactly one "Timestamp Element". The 877 "Timestamp Element" value MUST be stored once per "Cluster". The 878 "Timestamp Element" in the "Cluster" is relative to the entire 879 "Segment". The "Timestamp Element" SHOULD be the first "Element" in 880 the "Cluster". 882 Additionally, the "Block" contains an offset that, when added to the 883 "Cluster"'s "Timestamp Element" value, yields the "Block"'s effective 884 timestamp. Therefore, timestamp in the "Block" itself is relative to 885 the "Timestamp Element" in the "Cluster". For example, if the 886 "Timestamp Element" in the "Cluster" is set to 10 seconds and a 887 "Block" in that "Cluster" is supposed to be played 12 seconds into 888 the clip, the timestamp in the "Block" would be set to 2 seconds. 890 The "ReferenceBlock" in the "BlockGroup" is used instead of the basic 891 "P-frame"/"B-frame" description. Instead of simply saying that this 892 "Block" depends on the "Block" directly before, or directly 893 afterwards, the "Timestamp" of the necessary "Block" is used. 894 Because there can be as many "ReferenceBlock Elements" as necessary 895 for a "Block", it allows for some extremely complex referencing. 897 The "Cues Element" is used to seek when playing back a file by 898 providing a temporal index for some of the "Tracks". It is similar 899 to the "SeekHead Element", but used for seeking to a specific time 900 when playing back the file. It is possible to seek without this 901 element, but it is much more difficult because a "Matroska Reader" 902 would have to 'hunt and peck' through the file looking for the 903 correct timestamp. 905 The "Cues Element" SHOULD contain at least one "CuePoint Element". 906 Each "CuePoint Element" stores the position of the "Cluster" that 907 contains the "BlockGroup" or "SimpleBlock Element". The timestamp is 908 stored in the "CueTime Element" and location is stored in the 909 "CueTrackPositions Element". 911 The "Cues Element" is flexible. For instance, "Cues Element" can be 912 used to index every single timestamp of every "Block" or they can be 913 indexed selectively. For video files, it is RECOMMENDED to index at 914 least the keyframes of the video track. 916 +-------------------------------------+ 917 | Cues | CuePoint | CueTime | 918 | | |-------------------| 919 | | | CueTrackPositions | 920 | |------------------------------| 921 | | CuePoint | CueTime | 922 | | |-------------------| 923 | | | CueTrackPositions | 924 +-------------------------------------+ 926 Figure 7: Representation of a "Cues Element" and two levels of 927 its "Descendant Elements". 929 The "Attachments Element" is for attaching files to a Matroska file 930 such as pictures, webpages, programs, or even the codec needed to 931 play back the file. 933 +------------------------------------------------+ 934 | Attachments | AttachedFile | FileDescription | 935 | | |-------------------| 936 | | | FileName | 937 | | |-------------------| 938 | | | FileMimeType | 939 | | |-------------------| 940 | | | FileData | 941 | | |-------------------| 942 | | | FileUID | 943 | | |-------------------| 944 | | | FileName | 945 | | |-------------------| 946 | | | FileReferral | 947 | | |-------------------| 948 | | | FileUsedStartTime | 949 | | |-------------------| 950 | | | FileUsedEndTime | 951 +------------------------------------------------+ 953 Figure 8: Representation of a "Attachments Element". 955 The "Tags Element" contains metadata that describes the "Segment" and 956 potentially its "Tracks", "Chapters", and "Attachments". Each 957 "Track" or "Chapter" that those tags applies to has its UID listed in 958 the "Tags". The "Tags" contain all extra information about the file: 959 scriptwriter, singer, actors, directors, titles, edition, price, 960 dates, genre, comments, etc. Tags can contain their values in 961 multiple languages. For example, a movie's "title" "Tag" might 962 contain both the original English title as well as the title it was 963 released as in Germany. 965 +-------------------------------------------+ 966 | Tags | Tag | Targets | TargetTypeValue | 967 | | | |------------------| 968 | | | | TargetType | 969 | | | |------------------| 970 | | | | TagTrackUID | 971 | | | |------------------| 972 | | | | TagEditionUID | 973 | | | |------------------| 974 | | | | TagChapterUID | 975 | | | |------------------| 976 | | | | TagAttachmentUID | 977 | | |------------------------------| 978 | | | SimpleTag | TagName | 979 | | | |------------------| 980 | | | | TagLanguage | 981 | | | |------------------| 982 | | | | TagDefault | 983 | | | |------------------| 984 | | | | TagString | 985 | | | |------------------| 986 | | | | TagBinary | 987 | | | |------------------| 988 | | | | SimpleTag | 989 +-------------------------------------------+ 991 Figure 9: Representation of a "Tags Element" and three levels of 992 its "Children Elements". 994 8. Matroska Additions to Schema Element Attributes 996 In addition to the EBML Schema definition provided by the EBML 997 Specification, Matroska adds the following additional attributes: 999 +-----------+----------+----------------------------------------+ 1000 | attribute | required | definition | 1001 | name | | | 1002 +===========+==========+========================================+ 1003 | webm | No | A boolean to express if the Matroska | 1004 | | | Element is also supported within | 1005 | | | version 2 of the "webm" specification. | 1006 | | | Please consider the webm specification | 1007 | | | (http://www.webmproject.org/docs/ | 1008 | | | container/) as the authoritative on | 1009 | | | "webm". | 1010 +-----------+----------+----------------------------------------+ 1012 Table 9 1014 9. Matroska Schema 1016 This specification includes an "EBML Schema" which defines the 1017 Elements and structure of Matroska as an EBML Document Type. The 1018 EBML Schema defines every valid Matroska element in a manner defined 1019 by the EBML specification. 1021 Here the definition of each Matroska Element is provided. 1023 9.1. EBMLMaxIDLength Element 1025 name: "EBMLMaxIDLength" 1027 path: "\EBML\EBMLMaxIDLength" 1029 id: "0x42F2" 1031 minOccurs: "1" 1033 maxOccurs: "1" 1035 range: "4" 1037 default: "4" 1039 type: "uinteger" 1041 9.2. EBMLMaxSizeLength Element 1043 name: "EBMLMaxSizeLength" 1045 path: "\EBML\EBMLMaxSizeLength" 1047 id: "0x42F3" 1049 minOccurs: "1" 1051 maxOccurs: "1" 1053 range: "1-8" 1055 default: "8" 1057 type: "uinteger" 1059 10. Segment Element 1061 name: "Segment" 1063 path: "\Segment" 1065 id: "0x18538067" 1067 minOccurs: "1" 1069 maxOccurs: "1" 1071 type: "master" 1073 unknownsizeallowed: "1" 1075 definition: The Root Element that contains all other Top-Level 1076 Elements (Elements defined only at Level 1). A Matroska file is 1077 composed of 1 Segment. 1079 10.1. SeekHead Element 1081 name: "SeekHead" 1083 path: "\Segment\SeekHead" 1085 id: "0x114D9B74" 1087 maxOccurs: "2" 1089 type: "master" 1091 definition: Contains the Segment Position of other Top-Level 1092 Elements. 1094 10.1.1. Seek Element 1096 name: "Seek" 1098 path: "\Segment\SeekHead\Seek" 1100 id: "0x4DBB" 1102 minOccurs: "1" 1104 type: "master" 1106 definition: Contains a single seek entry to an EBML Element. 1108 10.1.1.1. SeekID Element 1110 name: "SeekID" 1112 path: "\Segment\SeekHead\Seek\SeekID" 1114 id: "0x53AB" 1116 minOccurs: "1" 1118 maxOccurs: "1" 1120 type: "binary" 1122 definition: The binary ID corresponding to the Element name. 1124 10.1.1.2. SeekPosition Element 1126 name: "SeekPosition" 1128 path: "\Segment\SeekHead\Seek\SeekPosition" 1130 id: "0x53AC" 1132 minOccurs: "1" 1134 maxOccurs: "1" 1136 type: "uinteger" 1138 definition: The Segment Position of the Element. 1140 10.2. Info Element 1142 name: "Info" 1144 path: "\Segment\Info" 1146 id: "0x1549A966" 1148 minOccurs: "1" 1150 type: "master" 1152 recurring: "1" 1154 definition: Contains general information about the Segment. 1156 10.2.1. SegmentUID Element 1158 name: "SegmentUID" 1160 path: "\Segment\Info\SegmentUID" 1162 id: "0x73A4" 1164 maxOccurs: "1" 1166 range: "not 0" 1168 type: "binary" 1170 definition: A randomly generated unique ID to identify the Segment 1171 amongst many others (128 bits). 1173 usage notes: If the Segment is a part of a Linked Segment then this 1174 Element is REQUIRED. 1176 10.2.2. SegmentFilename Element 1178 name: "SegmentFilename" 1180 path: "\Segment\Info\SegmentFilename" 1182 id: "0x7384" 1184 maxOccurs: "1" 1186 type: "utf-8" 1188 definition: A filename corresponding to this Segment. 1190 10.2.3. PrevUID Element 1192 name: "PrevUID" 1194 path: "\Segment\Info\PrevUID" 1196 id: "0x3CB923" 1198 maxOccurs: "1" 1200 type: "binary" 1202 definition: A unique ID to identify the previous Segment of a Linked 1203 Segment (128 bits). 1205 usage notes: If the Segment is a part of a Linked Segment that uses 1206 Hard Linking then either the PrevUID or the NextUID Element is 1207 REQUIRED. If a Segment contains a PrevUID but not a NextUID then it 1208 MAY be considered as the last Segment of the Linked Segment. The 1209 PrevUID MUST NOT be equal to the SegmentUID. 1211 10.2.4. PrevFilename Element 1213 name: "PrevFilename" 1215 path: "\Segment\Info\PrevFilename" 1217 id: "0x3C83AB" 1219 maxOccurs: "1" 1221 type: "utf-8" 1223 definition: A filename corresponding to the file of the previous 1224 Linked Segment. 1226 usage notes: Provision of the previous filename is for display 1227 convenience, but PrevUID SHOULD be considered authoritative for 1228 identifying the previous Segment in a Linked Segment. 1230 10.2.5. NextUID Element 1232 name: "NextUID" 1234 path: "\Segment\Info\NextUID" 1236 id: "0x3EB923" 1238 maxOccurs: "1" 1240 type: "binary" 1242 definition: A unique ID to identify the next Segment of a Linked 1243 Segment (128 bits). 1245 usage notes: If the Segment is a part of a Linked Segment that uses 1246 Hard Linking then either the PrevUID or the NextUID Element is 1247 REQUIRED. If a Segment contains a NextUID but not a PrevUID then it 1248 MAY be considered as the first Segment of the Linked Segment. The 1249 NextUID MUST NOT be equal to the SegmentUID. 1251 10.2.6. NextFilename Element 1253 name: "NextFilename" 1255 path: "\Segment\Info\NextFilename" 1257 id: "0x3E83BB" 1259 maxOccurs: "1" 1261 type: "utf-8" 1263 definition: A filename corresponding to the file of the next Linked 1264 Segment. 1266 usage notes: Provision of the next filename is for display 1267 convenience, but NextUID SHOULD be considered authoritative for 1268 identifying the Next Segment. 1270 10.2.7. SegmentFamily Element 1272 name: "SegmentFamily" 1274 path: "\Segment\Info\SegmentFamily" 1276 id: "0x4444" 1278 type: "binary" 1280 definition: A randomly generated unique ID that all Segments of a 1281 Linked Segment MUST share (128 bits). 1283 usage notes: If the Segment is a part of a Linked Segment that uses 1284 Soft Linking then this Element is REQUIRED. 1286 10.2.8. ChapterTranslate Element 1288 name: "ChapterTranslate" 1290 path: "\Segment\Info\ChapterTranslate" 1292 id: "0x6924" 1294 type: "master" 1296 definition: A tuple of corresponding ID used by chapter codecs to 1297 represent this Segment. 1299 10.2.8.1. ChapterTranslateEditionUID Element 1301 name: "ChapterTranslateEditionUID" 1303 path: "\Segment\Info\ChapterTranslate\ChapterTranslateEditionUID" 1305 id: "0x69FC" 1307 type: "uinteger" 1309 definition: Specify an edition UID on which this correspondence 1310 applies. When not specified, it means for all editions found in the 1311 Segment. 1313 10.2.8.2. ChapterTranslateCodec Element 1315 name: "ChapterTranslateCodec" 1317 path: "\Segment\Info\ChapterTranslate\ChapterTranslateCodec" 1319 id: "0x69BF" 1321 minOccurs: "1" 1323 maxOccurs: "1" 1325 type: "uinteger" 1327 definition: The chapter codec 1329 restrictions: 1331 +-------+-----------------+ 1332 | value | label | 1333 +=======+=================+ 1334 | "0" | Matroska Script | 1335 +-------+-----------------+ 1336 | "1" | DVD-menu | 1337 +-------+-----------------+ 1339 Table 10 1341 10.2.8.3. ChapterTranslateID Element 1343 name: "ChapterTranslateID" 1345 path: "\Segment\Info\ChapterTranslate\ChapterTranslateID" 1346 id: "0x69A5" 1348 minOccurs: "1" 1350 maxOccurs: "1" 1352 type: "binary" 1354 definition: The binary value used to represent this Segment in the 1355 chapter codec data. The format depends on the ChapProcessCodecID 1356 used. 1358 10.2.9. TimestampScale Element 1360 name: "TimestampScale" 1362 path: "\Segment\Info\TimestampScale" 1364 id: "0x2AD7B1" 1366 minOccurs: "1" 1368 maxOccurs: "1" 1370 range: "not 0" 1372 default: "1000000" 1374 type: "uinteger" 1376 definition: Timestamp scale in nanoseconds (1.000.000 means all 1377 timestamps in the Segment are expressed in milliseconds). 1379 10.2.10. Duration Element 1381 name: "Duration" 1383 path: "\Segment\Info\Duration" 1385 id: "0x4489" 1387 maxOccurs: "1" 1389 range: "> 0x0p+0" 1391 type: "float" 1392 definition: Duration of the Segment in nanoseconds based on 1393 TimestampScale. 1395 10.2.11. DateUTC Element 1397 name: "DateUTC" 1399 path: "\Segment\Info\DateUTC" 1401 id: "0x4461" 1403 maxOccurs: "1" 1405 type: "date" 1407 definition: The date and time that the Segment was created by the 1408 muxing application or library. 1410 10.2.12. Title Element 1412 name: "Title" 1414 path: "\Segment\Info\Title" 1416 id: "0x7BA9" 1418 maxOccurs: "1" 1420 type: "utf-8" 1422 definition: General name of the Segment. 1424 10.2.13. MuxingApp Element 1426 name: "MuxingApp" 1428 path: "\Segment\Info\MuxingApp" 1430 id: "0x4D80" 1432 minOccurs: "1" 1434 maxOccurs: "1" 1436 type: "utf-8" 1438 definition: Muxing application or library (example: "libmatroska- 1439 0.4.3"). 1441 usage notes: Include the full name of the application or library 1442 followed by the version number. 1444 10.2.14. WritingApp Element 1446 name: "WritingApp" 1448 path: "\Segment\Info\WritingApp" 1450 id: "0x5741" 1452 minOccurs: "1" 1454 maxOccurs: "1" 1456 type: "utf-8" 1458 definition: Writing application (example: "mkvmerge-0.3.3"). 1460 usage notes: Include the full name of the application followed by the 1461 version number. 1463 10.3. Cluster Element 1465 name: "Cluster" 1467 path: "\Segment\Cluster" 1469 id: "0x1F43B675" 1471 type: "master" 1473 unknownsizeallowed: "1" 1475 definition: The Top-Level Element containing the (monolithic) Block 1476 structure. 1478 10.3.1. Timestamp Element 1480 name: "Timestamp" 1482 path: "\Segment\Cluster\Timestamp" 1484 id: "0xE7" 1486 minOccurs: "1" 1488 maxOccurs: "1" 1489 type: "uinteger" 1491 definition: Absolute timestamp of the cluster (based on 1492 TimestampScale). 1494 10.3.2. SilentTracks Element 1496 name: "SilentTracks" 1498 path: "\Segment\Cluster\SilentTracks" 1500 id: "0x5854" 1502 maxOccurs: "1" 1504 type: "master" 1506 definition: The list of tracks that are not used in that part of the 1507 stream. It is useful when using overlay tracks on seeking or to 1508 decide what track to use. 1510 10.3.2.1. SilentTrackNumber Element 1512 name: "SilentTrackNumber" 1514 path: "\Segment\Cluster\SilentTracks\SilentTrackNumber" 1516 id: "0x58D7" 1518 type: "uinteger" 1520 definition: One of the track number that are not used from now on in 1521 the stream. It could change later if not specified as silent in a 1522 further Cluster. 1524 10.3.3. Position Element 1526 name: "Position" 1528 path: "\Segment\Cluster\Position" 1530 id: "0xA7" 1532 maxOccurs: "1" 1534 type: "uinteger" 1535 definition: The Segment Position of the Cluster in the Segment (0 in 1536 live streams). It might help to resynchronise offset on damaged 1537 streams. 1539 10.3.4. PrevSize Element 1541 name: "PrevSize" 1543 path: "\Segment\Cluster\PrevSize" 1545 id: "0xAB" 1547 maxOccurs: "1" 1549 type: "uinteger" 1551 definition: Size of the previous Cluster, in octets. Can be useful 1552 for backward playing. 1554 10.3.5. SimpleBlock Element 1556 name: "SimpleBlock" 1558 path: "\Segment\Cluster\SimpleBlock" 1560 id: "0xA3" 1562 type: "binary" 1564 minver: "2" 1566 definition: Similar to Block but without all the extra information, 1567 mostly used to reduced overhead when no extra feature is needed. (see 1568 SimpleBlock Structure) 1570 10.3.6. BlockGroup Element 1572 name: "BlockGroup" 1574 path: "\Segment\Cluster\BlockGroup" 1576 id: "0xA0" 1578 type: "master" 1580 definition: Basic container of information containing a single Block 1581 and information specific to that Block. 1583 10.3.6.1. Block Element 1585 name: "Block" 1587 path: "\Segment\Cluster\BlockGroup\Block" 1589 id: "0xA1" 1591 minOccurs: "1" 1593 maxOccurs: "1" 1595 type: "binary" 1597 definition: Block containing the actual data to be rendered and a 1598 timestamp relative to the Cluster Timestamp. (see Block Structure) 1600 10.3.6.2. BlockVirtual Element 1602 name: "BlockVirtual" 1604 path: "\Segment\Cluster\BlockGroup\BlockVirtual" 1606 id: "0xA2" 1608 maxOccurs: "1" 1610 type: "binary" 1612 minver: "0" 1614 maxver: "0" 1616 definition: A Block with no data. It MUST be stored in the stream at 1617 the place the real Block would be in display order. (see Block 1618 Virtual) 1620 10.3.6.3. BlockAdditions Element 1622 name: "BlockAdditions" 1624 path: "\Segment\Cluster\BlockGroup\BlockAdditions" 1626 id: "0x75A1" 1628 maxOccurs: "1" 1630 type: "master" 1631 definition: Contain additional blocks to complete the main one. An 1632 EBML parser that has no knowledge of the Block structure could still 1633 see and use/skip these data. 1635 10.3.6.3.1. BlockMore Element 1637 name: "BlockMore" 1639 path: "\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore" 1641 id: "0xA6" 1643 minOccurs: "1" 1645 type: "master" 1647 definition: Contain the BlockAdditional and some parameters. 1649 10.3.6.3.1.1. BlockAddID Element 1651 name: "BlockAddID" 1653 path: 1654 "\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAddID" 1656 id: "0xEE" 1658 minOccurs: "1" 1660 maxOccurs: "1" 1662 range: "not 0" 1664 default: "1" 1666 type: "uinteger" 1668 definition: An ID to identify the BlockAdditional level. A value of 1669 1 means the BlockAdditional data is interpreted as additional data 1670 passed to the codec with the Block data. 1672 10.3.6.3.1.2. BlockAdditional Element 1674 name: "BlockAdditional" 1676 path: "\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAddi 1677 tional" 1678 id: "0xA5" 1680 minOccurs: "1" 1682 maxOccurs: "1" 1684 type: "binary" 1686 definition: Interpreted by the codec as it wishes (using the 1687 BlockAddID). 1689 10.3.6.4. BlockDuration Element 1691 name: "BlockDuration" 1693 path: "\Segment\Cluster\BlockGroup\BlockDuration" 1695 id: "0x9B" 1697 minOccurs: see implementation notes 1699 maxOccurs: "1" 1701 default: see implementation notes 1703 type: "uinteger" 1705 definition: The duration of the Block (based on TimestampScale). The 1706 BlockDuration Element can be useful at the end of a Track to define 1707 the duration of the last frame (as there is no subsequent Block 1708 available), or when there is a break in a track like for subtitle 1709 tracks. 1711 implementation notes: 1713 +-----------+---------------------------------------------------+ 1714 | attribute | note | 1715 +===========+===================================================+ 1716 | minOccurs | BlockDuration MUST be set (minOccurs=1) if the | 1717 | | associated TrackEntry stores a DefaultDuration | 1718 | | value. | 1719 +-----------+---------------------------------------------------+ 1720 | default | When not written and with no DefaultDuration, the | 1721 | | value is assumed to be the difference between the | 1722 | | timestamp of this Block and the timestamp of the | 1723 | | next Block in "display" order (not coding order). | 1724 +-----------+---------------------------------------------------+ 1726 Table 11 1728 10.3.6.5. ReferencePriority Element 1730 name: "ReferencePriority" 1732 path: "\Segment\Cluster\BlockGroup\ReferencePriority" 1734 id: "0xFA" 1736 minOccurs: "1" 1738 maxOccurs: "1" 1740 default: "0" 1742 type: "uinteger" 1744 definition: This frame is referenced and has the specified cache 1745 priority. In cache only a frame of the same or higher priority can 1746 replace this frame. A value of 0 means the frame is not referenced. 1748 10.3.6.6. ReferenceBlock Element 1750 name: "ReferenceBlock" 1752 path: "\Segment\Cluster\BlockGroup\ReferenceBlock" 1754 id: "0xFB" 1756 type: "integer" 1758 definition: Timestamp of another frame used as a reference (ie: B or 1759 P frame). The timestamp is relative to the block it's attached to. 1761 10.3.6.7. ReferenceVirtual Element 1763 name: "ReferenceVirtual" 1765 path: "\Segment\Cluster\BlockGroup\ReferenceVirtual" 1767 id: "0xFD" 1769 maxOccurs: "1" 1771 type: "integer" 1773 minver: "0" 1775 maxver: "0" 1777 definition: The Segment Position of the data that would otherwise be 1778 in position of the virtual block. 1780 10.3.6.8. CodecState Element 1782 name: "CodecState" 1784 path: "\Segment\Cluster\BlockGroup\CodecState" 1786 id: "0xA4" 1788 maxOccurs: "1" 1790 type: "binary" 1792 minver: "2" 1794 definition: The new codec state to use. Data interpretation is 1795 private to the codec. This information SHOULD always be referenced 1796 by a seek entry. 1798 10.3.6.9. DiscardPadding Element 1800 name: "DiscardPadding" 1802 path: "\Segment\Cluster\BlockGroup\DiscardPadding" 1804 id: "0x75A2" 1806 maxOccurs: "1" 1808 type: "integer" 1809 minver: "4" 1811 definition: Duration in nanoseconds of the silent data added to the 1812 Block (padding at the end of the Block for positive value, at the 1813 beginning of the Block for negative value). The duration of 1814 DiscardPadding is not calculated in the duration of the TrackEntry 1815 and SHOULD be discarded during playback. 1817 10.3.6.10. Slices Element 1819 name: "Slices" 1821 path: "\Segment\Cluster\BlockGroup\Slices" 1823 id: "0x8E" 1825 maxOccurs: "1" 1827 type: "master" 1829 definition: Contains slices description. 1831 10.3.6.10.1. TimeSlice Element 1833 name: "TimeSlice" 1835 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice" 1837 id: "0xE8" 1839 type: "master" 1841 maxver: "1" 1843 definition: Contains extra time information about the data contained 1844 in the Block. Being able to interpret this Element is not REQUIRED 1845 for playback. 1847 10.3.6.10.1.1. LaceNumber Element 1849 name: "LaceNumber" 1851 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\LaceNumber" 1853 id: "0xCC" 1855 maxOccurs: "1" 1856 default: "0" 1858 type: "uinteger" 1860 maxver: "1" 1862 definition: The reverse number of the frame in the lace (0 is the 1863 last frame, 1 is the next to last, etc). Being able to interpret 1864 this Element is not REQUIRED for playback. 1866 10.3.6.10.1.2. FrameNumber Element 1868 name: "FrameNumber" 1870 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\FrameNumber" 1872 id: "0xCD" 1874 maxOccurs: "1" 1876 default: "0" 1878 type: "uinteger" 1880 minver: "0" 1882 maxver: "0" 1884 definition: The number of the frame to generate from this lace with 1885 this delay (allow you to generate many frames from the same Block/ 1886 Frame). 1888 10.3.6.10.1.3. BlockAdditionID Element 1890 name: "BlockAdditionID" 1892 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\BlockAdditionID" 1894 id: "0xCB" 1896 maxOccurs: "1" 1898 default: "0" 1900 type: "uinteger" 1902 minver: "0" 1903 maxver: "0" 1905 definition: The ID of the BlockAdditional Element (0 is the main 1906 Block). 1908 10.3.6.10.1.4. Delay Element 1910 name: "Delay" 1912 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\Delay" 1914 id: "0xCE" 1916 maxOccurs: "1" 1918 default: "0" 1920 type: "uinteger" 1922 minver: "0" 1924 maxver: "0" 1926 definition: The (scaled) delay to apply to the Element. 1928 10.3.6.10.1.5. SliceDuration Element 1930 name: "SliceDuration" 1932 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\SliceDuration" 1934 id: "0xCF" 1936 maxOccurs: "1" 1938 default: "0" 1940 type: "uinteger" 1942 minver: "0" 1944 maxver: "0" 1946 definition: The (scaled) duration to apply to the Element. 1948 10.3.6.11. ReferenceFrame Element 1950 name: "ReferenceFrame" 1952 path: "\Segment\Cluster\BlockGroup\ReferenceFrame" 1954 id: "0xC8" 1956 maxOccurs: "1" 1958 type: "master" 1960 minver: "0" 1962 maxver: "0" 1964 definition: DivX trick track extensions 1966 10.3.6.11.1. ReferenceOffset Element 1968 name: "ReferenceOffset" 1970 path: "\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceOffset" 1972 id: "0xC9" 1974 minOccurs: "1" 1976 maxOccurs: "1" 1978 type: "uinteger" 1980 minver: "0" 1982 maxver: "0" 1984 definition: DivX trick track extensions 1986 10.3.6.11.2. ReferenceTimestamp Element 1988 name: "ReferenceTimestamp" 1990 path: "\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceTimestamp" 1992 id: "0xCA" 1994 minOccurs: "1" 1995 maxOccurs: "1" 1997 type: "uinteger" 1999 minver: "0" 2001 maxver: "0" 2003 definition: DivX trick track extensions 2005 10.3.7. EncryptedBlock Element 2007 name: "EncryptedBlock" 2009 path: "\Segment\Cluster\EncryptedBlock" 2011 id: "0xAF" 2013 type: "binary" 2015 minver: "0" 2017 maxver: "0" 2019 definition: Similar to SimpleBlock but the data inside the Block are 2020 Transformed (encrypt and/or signed). (see EncryptedBlock Structure) 2022 10.4. Tracks Element 2024 name: "Tracks" 2026 path: "\Segment\Tracks" 2028 id: "0x1654AE6B" 2030 type: "master" 2032 recurring: "1" 2034 definition: A Top-Level Element of information with many tracks 2035 described. 2037 10.4.1. TrackEntry Element 2039 name: "TrackEntry" 2041 path: "\Segment\Tracks\TrackEntry" 2042 id: "0xAE" 2044 minOccurs: "1" 2046 type: "master" 2048 definition: Describes a track with all Elements. 2050 10.4.1.1. TrackNumber Element 2052 name: "TrackNumber" 2054 path: "\Segment\Tracks\TrackEntry\TrackNumber" 2056 id: "0xD7" 2058 minOccurs: "1" 2060 maxOccurs: "1" 2062 range: "not 0" 2064 type: "uinteger" 2066 definition: The track number as used in the Block Header (using more 2067 than 127 tracks is not encouraged, though the design allows an 2068 unlimited number). 2070 10.4.1.2. TrackUID Element 2072 name: "TrackUID" 2074 path: "\Segment\Tracks\TrackEntry\TrackUID" 2076 id: "0x73C5" 2078 minOccurs: "1" 2080 maxOccurs: "1" 2082 range: "not 0" 2084 type: "uinteger" 2086 definition: A unique ID to identify the Track. This SHOULD be kept 2087 the same when making a direct stream copy of the Track to another 2088 file. 2090 10.4.1.3. TrackType Element 2092 name: "TrackType" 2094 path: "\Segment\Tracks\TrackEntry\TrackType" 2096 id: "0x83" 2098 minOccurs: "1" 2100 maxOccurs: "1" 2102 range: "1-254" 2104 type: "uinteger" 2106 definition: A set of track types coded on 8 bits. 2108 restrictions: 2110 +-------+----------+ 2111 | value | label | 2112 +=======+==========+ 2113 | "1" | video | 2114 +-------+----------+ 2115 | "2" | audio | 2116 +-------+----------+ 2117 | "3" | complex | 2118 +-------+----------+ 2119 | "16" | logo | 2120 +-------+----------+ 2121 | "17" | subtitle | 2122 +-------+----------+ 2123 | "18" | buttons | 2124 +-------+----------+ 2125 | "32" | control | 2126 +-------+----------+ 2127 | "33" | metadata | 2128 +-------+----------+ 2130 Table 12 2132 10.4.1.4. FlagEnabled Element 2134 name: "FlagEnabled" 2136 path: "\Segment\Tracks\TrackEntry\FlagEnabled" 2137 id: "0xB9" 2139 minOccurs: "1" 2141 maxOccurs: "1" 2143 range: "0-1" 2145 default: "1" 2147 type: "uinteger" 2149 minver: "2" 2151 definition: Set if the track is usable. (1 bit) 2153 10.4.1.5. FlagDefault Element 2155 name: "FlagDefault" 2157 path: "\Segment\Tracks\TrackEntry\FlagDefault" 2159 id: "0x88" 2161 minOccurs: "1" 2163 maxOccurs: "1" 2165 range: "0-1" 2167 default: "1" 2169 type: "uinteger" 2171 definition: Set if that track (audio, video or subs) SHOULD be active 2172 if no language found matches the user preference. (1 bit) 2174 10.4.1.6. FlagForced Element 2176 name: "FlagForced" 2178 path: "\Segment\Tracks\TrackEntry\FlagForced" 2180 id: "0x55AA" 2182 minOccurs: "1" 2184 maxOccurs: "1" 2185 range: "0-1" 2187 default: "0" 2189 type: "uinteger" 2191 definition: Set if that track MUST be active during playback. There 2192 can be many forced track for a kind (audio, video or subs), the 2193 player SHOULD select the one which language matches the user 2194 preference or the default + forced track. Overlay MAY happen between 2195 a forced and non-forced track of the same kind. (1 bit) 2197 10.4.1.7. FlagLacing Element 2199 name: "FlagLacing" 2201 path: "\Segment\Tracks\TrackEntry\FlagLacing" 2203 id: "0x9C" 2205 minOccurs: "1" 2207 maxOccurs: "1" 2209 range: "0-1" 2211 default: "1" 2213 type: "uinteger" 2215 definition: Set if the track MAY contain blocks using lacing. (1 bit) 2217 10.4.1.8. MinCache Element 2219 name: "MinCache" 2221 path: "\Segment\Tracks\TrackEntry\MinCache" 2223 id: "0x6DE7" 2225 minOccurs: "1" 2227 maxOccurs: "1" 2229 default: "0" 2231 type: "uinteger" 2232 definition: The minimum number of frames a player SHOULD be able to 2233 cache during playback. If set to 0, the reference pseudo-cache 2234 system is not used. 2236 10.4.1.9. MaxCache Element 2238 name: "MaxCache" 2240 path: "\Segment\Tracks\TrackEntry\MaxCache" 2242 id: "0x6DF8" 2244 maxOccurs: "1" 2246 type: "uinteger" 2248 definition: The maximum cache size necessary to store referenced 2249 frames in and the current frame. 0 means no cache is needed. 2251 10.4.1.10. DefaultDuration Element 2253 name: "DefaultDuration" 2255 path: "\Segment\Tracks\TrackEntry\DefaultDuration" 2257 id: "0x23E383" 2259 maxOccurs: "1" 2261 range: "not 0" 2263 type: "uinteger" 2265 definition: Number of nanoseconds (not scaled via TimestampScale) per 2266 frame ('frame' in the Matroska sense -- one Element put into a 2267 (Simple)Block). 2269 10.4.1.11. DefaultDecodedFieldDuration Element 2271 name: "DefaultDecodedFieldDuration" 2273 path: "\Segment\Tracks\TrackEntry\DefaultDecodedFieldDuration" 2275 id: "0x234E7A" 2277 maxOccurs: "1" 2279 range: "not 0" 2280 type: "uinteger" 2282 minver: "4" 2284 definition: The period in nanoseconds (not scaled by TimestampScale) 2285 between two successive fields at the output of the decoding process 2286 (see the notes) 2288 10.4.1.12. TrackTimestampScale Element 2290 name: "TrackTimestampScale" 2292 path: "\Segment\Tracks\TrackEntry\TrackTimestampScale" 2294 id: "0x23314F" 2296 minOccurs: "1" 2298 maxOccurs: "1" 2300 range: "> 0x0p+0" 2302 default: "0x1p+0" 2304 type: "float" 2306 maxver: "3" 2308 definition: DEPRECATED, DO NOT USE. The scale to apply on this track 2309 to work at normal speed in relation with other tracks (mostly used to 2310 adjust video speed when the audio length differs). 2312 10.4.1.13. TrackOffset Element 2314 name: "TrackOffset" 2316 path: "\Segment\Tracks\TrackEntry\TrackOffset" 2318 id: "0x537F" 2320 maxOccurs: "1" 2322 default: "0" 2324 type: "integer" 2326 minver: "0" 2327 maxver: "0" 2329 definition: A value to add to the Block's Timestamp. This can be 2330 used to adjust the playback offset of a track. 2332 10.4.1.14. MaxBlockAdditionID Element 2334 name: "MaxBlockAdditionID" 2336 path: "\Segment\Tracks\TrackEntry\MaxBlockAdditionID" 2338 id: "0x55EE" 2340 minOccurs: "1" 2342 maxOccurs: "1" 2344 default: "0" 2346 type: "uinteger" 2348 definition: The maximum value of BlockAddID. A value 0 means there 2349 is no BlockAdditions for this track. 2351 10.4.1.15. BlockAdditionMapping Element 2353 name: "BlockAdditionMapping" 2355 path: "\Segment\Tracks\TrackEntry\BlockAdditionMapping" 2357 id: "0x41E4" 2359 type: "master" 2361 minver: "4" 2363 definition: Contains elements that describe each value of BlockAddID 2364 found in the Track. 2366 10.4.1.15.1. BlockAddIDValue Element 2368 name: "BlockAddIDValue" 2370 path: 2371 "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDValue" 2373 id: "0x41F0" 2374 minOccurs: "1" 2376 maxOccurs: "1" 2378 range: ">=2" 2380 type: "uinteger" 2382 minver: "4" 2384 definition: The BlockAddID value being described. To keep 2385 MaxBlockAdditionID as low as possible, small values SHOULD be used. 2387 10.4.1.15.2. BlockAddIDName Element 2389 name: "BlockAddIDName" 2391 path: 2392 "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDName" 2394 id: "0x41A4" 2396 maxOccurs: "1" 2398 type: "string" 2400 minver: "4" 2402 definition: A human-friendly name describing the type of 2403 BlockAdditional data as defined by the associated Block Additional 2404 Mapping. 2406 10.4.1.15.3. BlockAddIDType Element 2408 name: "BlockAddIDType" 2410 path: 2411 "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDType" 2413 id: "0x41E7" 2415 minOccurs: "1" 2417 maxOccurs: "1" 2419 default: "0" 2421 type: "uinteger" 2422 minver: "4" 2424 definition: Stores the registered identifer of the Block Additional 2425 Mapping to define how the BlockAdditional data should be handled. 2427 10.4.1.15.4. BlockAddIDExtraData Element 2429 name: "BlockAddIDExtraData" 2431 path: 2432 "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDExtraData" 2434 id: "0x41E7" 2436 maxOccurs: "1" 2438 type: "binary" 2440 minver: "4" 2442 definition: Extra binary data that the BlockAddIDType can use to 2443 interpret the BlockAdditional data. The intepretation of the binary 2444 data depends on the BlockAddIDType value and the corresponding Block 2445 Additional Mapping. 2447 10.4.1.16. Name Element 2449 name: "Name" 2451 path: "\Segment\Tracks\TrackEntry\Name" 2453 id: "0x536E" 2455 maxOccurs: "1" 2457 type: "utf-8" 2459 definition: A human-readable track name. 2461 10.4.1.17. Language Element 2463 name: "Language" 2465 path: "\Segment\Tracks\TrackEntry\Language" 2467 id: "0x22B59C" 2469 maxOccurs: "1" 2470 default: "eng" 2472 type: "string" 2474 definition: Specifies the language of the track in the Matroska 2475 languages form. This Element MUST be ignored if the LanguageIETF 2476 Element is used in the same TrackEntry. 2478 10.4.1.18. LanguageIETF Element 2480 name: "LanguageIETF" 2482 path: "\Segment\Tracks\TrackEntry\LanguageIETF" 2484 id: "0x22B59D" 2486 maxOccurs: "1" 2488 type: "string" 2490 minver: "4" 2492 definition: Specifies the language of the track according to BCP 47 2493 and using the IANA Language Subtag Registry. If this Element is 2494 used, then any Language Elements used in the same TrackEntry MUST be 2495 ignored. 2497 10.4.1.19. CodecID Element 2499 name: "CodecID" 2501 path: "\Segment\Tracks\TrackEntry\CodecID" 2503 id: "0x86" 2505 minOccurs: "1" 2507 maxOccurs: "1" 2509 type: "string" 2511 definition: An ID corresponding to the codec, see the codec page for 2512 more info. 2514 10.4.1.20. CodecPrivate Element 2516 name: "CodecPrivate" 2517 path: "\Segment\Tracks\TrackEntry\CodecPrivate" 2519 id: "0x63A2" 2521 maxOccurs: "1" 2523 type: "binary" 2525 definition: Private data only known to the codec. 2527 10.4.1.21. CodecName Element 2529 name: "CodecName" 2531 path: "\Segment\Tracks\TrackEntry\CodecName" 2533 id: "0x258688" 2535 maxOccurs: "1" 2537 type: "utf-8" 2539 definition: A human-readable string specifying the codec. 2541 10.4.1.22. AttachmentLink Element 2543 name: "AttachmentLink" 2545 path: "\Segment\Tracks\TrackEntry\AttachmentLink" 2547 id: "0x7446" 2549 maxOccurs: "1" 2551 range: "not 0" 2553 type: "uinteger" 2555 maxver: "3" 2557 definition: The UID of an attachment that is used by this codec. 2559 10.4.1.23. CodecSettings Element 2561 name: "CodecSettings" 2563 path: "\Segment\Tracks\TrackEntry\CodecSettings" 2564 id: "0x3A9697" 2566 maxOccurs: "1" 2568 type: "utf-8" 2570 minver: "0" 2572 maxver: "0" 2574 definition: A string describing the encoding setting used. 2576 10.4.1.24. CodecInfoURL Element 2578 name: "CodecInfoURL" 2580 path: "\Segment\Tracks\TrackEntry\CodecInfoURL" 2582 id: "0x3B4040" 2584 type: "string" 2586 minver: "0" 2588 maxver: "0" 2590 definition: A URL to find information about the codec used. 2592 10.4.1.25. CodecDownloadURL Element 2594 name: "CodecDownloadURL" 2596 path: "\Segment\Tracks\TrackEntry\CodecDownloadURL" 2598 id: "0x26B240" 2600 type: "string" 2602 minver: "0" 2604 maxver: "0" 2606 definition: A URL to download about the codec used. 2608 10.4.1.26. CodecDecodeAll Element 2610 name: "CodecDecodeAll" 2611 path: "\Segment\Tracks\TrackEntry\CodecDecodeAll" 2613 id: "0xAA" 2615 minOccurs: "1" 2617 maxOccurs: "1" 2619 range: "0-1" 2621 default: "1" 2623 type: "uinteger" 2625 minver: "2" 2627 definition: The codec can decode potentially damaged data (1 bit). 2629 10.4.1.27. TrackOverlay Element 2631 name: "TrackOverlay" 2633 path: "\Segment\Tracks\TrackEntry\TrackOverlay" 2635 id: "0x6FAB" 2637 type: "uinteger" 2639 definition: Specify that this track is an overlay track for the Track 2640 specified (in the u-integer). That means when this track has a gap 2641 (see SilentTracks) the overlay track SHOULD be used instead. The 2642 order of multiple TrackOverlay matters, the first one is the one that 2643 SHOULD be used. If not found it SHOULD be the second, etc. 2645 10.4.1.28. CodecDelay Element 2647 name: "CodecDelay" 2649 path: "\Segment\Tracks\TrackEntry\CodecDelay" 2651 id: "0x56AA" 2653 maxOccurs: "1" 2655 default: "0" 2657 type: "uinteger" 2658 minver: "4" 2660 definition: CodecDelay is The codec-built-in delay in nanoseconds. 2661 This value MUST be subtracted from each block timestamp in order to 2662 get the actual timestamp. The value SHOULD be small so the muxing of 2663 tracks with the same actual timestamp are in the same Cluster. 2665 10.4.1.29. SeekPreRoll Element 2667 name: "SeekPreRoll" 2669 path: "\Segment\Tracks\TrackEntry\SeekPreRoll" 2671 id: "0x56BB" 2673 minOccurs: "1" 2675 maxOccurs: "1" 2677 default: "0" 2679 type: "uinteger" 2681 minver: "4" 2683 definition: After a discontinuity, SeekPreRoll is the duration in 2684 nanoseconds of the data the decoder MUST decode before the decoded 2685 data is valid. 2687 10.4.1.30. TrackTranslate Element 2689 name: "TrackTranslate" 2691 path: "\Segment\Tracks\TrackEntry\TrackTranslate" 2693 id: "0x6624" 2695 type: "master" 2697 definition: The track identification for the given Chapter Codec. 2699 10.4.1.30.1. TrackTranslateEditionUID Element 2701 name: "TrackTranslateEditionUID" 2703 path: 2704 "\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateEditionUID" 2705 id: "0x66FC" 2707 type: "uinteger" 2709 definition: Specify an edition UID on which this translation applies. 2710 When not specified, it means for all editions found in the Segment. 2712 10.4.1.30.2. TrackTranslateCodec Element 2714 name: "TrackTranslateCodec" 2716 path: "\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateCodec" 2718 id: "0x66BF" 2720 minOccurs: "1" 2722 maxOccurs: "1" 2724 type: "uinteger" 2726 definition: The chapter codec. 2728 restrictions: 2730 +-------+-----------------+ 2731 | value | label | 2732 +=======+=================+ 2733 | "0" | Matroska Script | 2734 +-------+-----------------+ 2735 | "1" | DVD-menu | 2736 +-------+-----------------+ 2738 Table 13 2740 10.4.1.30.3. TrackTranslateTrackID Element 2742 name: "TrackTranslateTrackID" 2744 path: 2745 "\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateTrackID" 2747 id: "0x66A5" 2749 minOccurs: "1" 2751 maxOccurs: "1" 2752 type: "binary" 2754 definition: The binary value used to represent this track in the 2755 chapter codec data. The format depends on the ChapProcessCodecID 2756 used. 2758 10.4.1.31. Video Element 2760 name: "Video" 2762 path: "\Segment\Tracks\TrackEntry\Video" 2764 id: "0xE0" 2766 maxOccurs: "1" 2768 type: "master" 2770 definition: Video settings. 2772 10.4.1.31.1. FlagInterlaced Element 2774 name: "FlagInterlaced" 2776 path: "\Segment\Tracks\TrackEntry\Video\FlagInterlaced" 2778 id: "0x9A" 2780 minOccurs: "1" 2782 maxOccurs: "1" 2784 range: "0-2" 2786 default: "0" 2788 type: "uinteger" 2790 minver: "2" 2792 definition: A flag to declare if the video is known to be progressive 2793 or interlaced and if applicable to declare details about the 2794 interlacement. 2796 restrictions: 2798 +-------+--------------+ 2799 | value | label | 2800 +=======+==============+ 2801 | "0" | undetermined | 2802 +-------+--------------+ 2803 | "1" | interlaced | 2804 +-------+--------------+ 2805 | "2" | progressive | 2806 +-------+--------------+ 2808 Table 14 2810 10.4.1.31.2. FieldOrder Element 2812 name: "FieldOrder" 2814 path: "\Segment\Tracks\TrackEntry\Video\FieldOrder" 2816 id: "0x9D" 2818 minOccurs: "1" 2820 maxOccurs: "1" 2822 range: "0-14" 2824 default: "2" 2826 type: "uinteger" 2828 minver: "4" 2830 definition: Declare the field ordering of the video. If 2831 FlagInterlaced is not set to 1, this Element MUST be ignored. 2833 restrictions: 2835 +-------+--------------+-----------------------------------------+ 2836 | value | label | documentation | 2837 +=======+==============+=========================================+ 2838 | "0" | progressive | | 2839 +-------+--------------+-----------------------------------------+ 2840 | "1" | tff | Top field displayed first. Top field | 2841 | | | stored first. | 2842 +-------+--------------+-----------------------------------------+ 2843 | "2" | undetermined | | 2844 +-------+--------------+-----------------------------------------+ 2845 | "6" | bff | Bottom field displayed first. Bottom | 2846 | | | field stored first. | 2847 +-------+--------------+-----------------------------------------+ 2848 | "9" | bff(swapped) | Top field displayed first. Fields are | 2849 | | | interleaved in storage with the top | 2850 | | | line of the top field stored first. | 2851 +-------+--------------+-----------------------------------------+ 2852 | "14" | tff(swapped) | Bottom field displayed first. Fields | 2853 | | | are interleaved in storage with the top | 2854 | | | line of the top field stored first. | 2855 +-------+--------------+-----------------------------------------+ 2857 Table 15 2859 10.4.1.31.3. StereoMode Element 2861 name: "StereoMode" 2863 path: "\Segment\Tracks\TrackEntry\Video\StereoMode" 2865 id: "0x53B8" 2867 maxOccurs: "1" 2869 default: "0" 2871 type: "uinteger" 2873 minver: "3" 2875 definition: Stereo-3D video mode. There are some more details on 3D 2876 support in the Specification Notes. 2878 restrictions: 2880 +-------+---------------------------------------------------+ 2881 | value | label | 2882 +=======+===================================================+ 2883 | "0" | mono | 2884 +-------+---------------------------------------------------+ 2885 | "1" | side by side (left eye first) | 2886 +-------+---------------------------------------------------+ 2887 | "2" | top - bottom (right eye is first) | 2888 +-------+---------------------------------------------------+ 2889 | "3" | top - bottom (left eye is first) | 2890 +-------+---------------------------------------------------+ 2891 | "4" | checkboard (right eye is first) | 2892 +-------+---------------------------------------------------+ 2893 | "5" | checkboard (left eye is first) | 2894 +-------+---------------------------------------------------+ 2895 | "6" | row interleaved (right eye is first) | 2896 +-------+---------------------------------------------------+ 2897 | "7" | row interleaved (left eye is first) | 2898 +-------+---------------------------------------------------+ 2899 | "8" | column interleaved (right eye is first) | 2900 +-------+---------------------------------------------------+ 2901 | "9" | column interleaved (left eye is first) | 2902 +-------+---------------------------------------------------+ 2903 | "10" | anaglyph (cyan/red) | 2904 +-------+---------------------------------------------------+ 2905 | "11" | side by side (right eye first) | 2906 +-------+---------------------------------------------------+ 2907 | "12" | anaglyph (green/magenta) | 2908 +-------+---------------------------------------------------+ 2909 | "13" | both eyes laced in one Block (left eye is first) | 2910 +-------+---------------------------------------------------+ 2911 | "14" | both eyes laced in one Block (right eye is first) | 2912 +-------+---------------------------------------------------+ 2914 Table 16 2916 10.4.1.31.4. AlphaMode Element 2918 name: "AlphaMode" 2920 path: "\Segment\Tracks\TrackEntry\Video\AlphaMode" 2922 id: "0x53C0" 2924 maxOccurs: "1" 2926 default: "0" 2927 type: "uinteger" 2929 minver: "3" 2931 definition: Alpha Video Mode. Presence of this Element indicates 2932 that the BlockAdditional Element could contain Alpha data. 2934 10.4.1.31.5. OldStereoMode Element 2936 name: "OldStereoMode" 2938 path: "\Segment\Tracks\TrackEntry\Video\OldStereoMode" 2940 id: "0x53B9" 2942 maxOccurs: "1" 2944 type: "uinteger" 2946 maxver: "0" 2948 definition: DEPRECATED, DO NOT USE. Bogus StereoMode value used in 2949 old versions of libmatroska. 2951 restrictions: 2953 +-------+-----------+ 2954 | value | label | 2955 +=======+===========+ 2956 | "0" | mono | 2957 +-------+-----------+ 2958 | "1" | right eye | 2959 +-------+-----------+ 2960 | "2" | left eye | 2961 +-------+-----------+ 2962 | "3" | both eyes | 2963 +-------+-----------+ 2965 Table 17 2967 10.4.1.31.6. PixelWidth Element 2969 name: "PixelWidth" 2971 path: "\Segment\Tracks\TrackEntry\Video\PixelWidth" 2973 id: "0xB0" 2974 minOccurs: "1" 2976 maxOccurs: "1" 2978 range: "not 0" 2980 type: "uinteger" 2982 definition: Width of the encoded video frames in pixels. 2984 10.4.1.31.7. PixelHeight Element 2986 name: "PixelHeight" 2988 path: "\Segment\Tracks\TrackEntry\Video\PixelHeight" 2990 id: "0xBA" 2992 minOccurs: "1" 2994 maxOccurs: "1" 2996 range: "not 0" 2998 type: "uinteger" 3000 definition: Height of the encoded video frames in pixels. 3002 10.4.1.31.8. PixelCropBottom Element 3004 name: "PixelCropBottom" 3006 path: "\Segment\Tracks\TrackEntry\Video\PixelCropBottom" 3008 id: "0x54AA" 3010 maxOccurs: "1" 3012 default: "0" 3014 type: "uinteger" 3016 definition: The number of video pixels to remove at the bottom of the 3017 image. 3019 10.4.1.31.9. PixelCropTop Element 3021 name: "PixelCropTop" 3023 path: "\Segment\Tracks\TrackEntry\Video\PixelCropTop" 3025 id: "0x54BB" 3027 maxOccurs: "1" 3029 default: "0" 3031 type: "uinteger" 3033 definition: The number of video pixels to remove at the top of the 3034 image. 3036 10.4.1.31.10. PixelCropLeft Element 3038 name: "PixelCropLeft" 3040 path: "\Segment\Tracks\TrackEntry\Video\PixelCropLeft" 3042 id: "0x54CC" 3044 maxOccurs: "1" 3046 default: "0" 3048 type: "uinteger" 3050 definition: The number of video pixels to remove on the left of the 3051 image. 3053 10.4.1.31.11. PixelCropRight Element 3055 name: "PixelCropRight" 3057 path: "\Segment\Tracks\TrackEntry\Video\PixelCropRight" 3059 id: "0x54DD" 3061 maxOccurs: "1" 3063 default: "0" 3065 type: "uinteger" 3066 definition: The number of video pixels to remove on the right of the 3067 image. 3069 10.4.1.31.12. DisplayWidth Element 3071 name: "DisplayWidth" 3073 path: "\Segment\Tracks\TrackEntry\Video\DisplayWidth" 3075 id: "0x54B0" 3077 maxOccurs: "1" 3079 range: "not 0" 3081 default: see implementation notes 3083 type: "uinteger" 3085 definition: Width of the video frames to display. Applies to the 3086 video frame after cropping (PixelCrop* Elements). 3088 implementation notes: 3090 +-----------+-------------------------------------------------+ 3091 | attribute | note | 3092 +===========+=================================================+ 3093 | default | If the DisplayUnit of the same TrackEntry is 0, | 3094 | | then the default value for DisplayWidth is | 3095 | | equal to PixelWidth - PixelCropLeft - | 3096 | | PixelCropRight, else there is no default value. | 3097 +-----------+-------------------------------------------------+ 3099 Table 18 3101 10.4.1.31.13. DisplayHeight Element 3103 name: "DisplayHeight" 3105 path: "\Segment\Tracks\TrackEntry\Video\DisplayHeight" 3107 id: "0x54BA" 3109 maxOccurs: "1" 3111 range: "not 0" 3113 default: see implementation notes 3114 type: "uinteger" 3116 definition: Height of the video frames to display. Applies to the 3117 video frame after cropping (PixelCrop* Elements). 3119 implementation notes: 3121 +-----------+--------------------------------------------------+ 3122 | attribute | note | 3123 +===========+==================================================+ 3124 | default | If the DisplayUnit of the same TrackEntry is 0, | 3125 | | then the default value for DisplayHeight is | 3126 | | equal to PixelHeight - PixelCropTop - | 3127 | | PixelCropBottom, else there is no default value. | 3128 +-----------+--------------------------------------------------+ 3130 Table 19 3132 10.4.1.31.14. DisplayUnit Element 3134 name: "DisplayUnit" 3136 path: "\Segment\Tracks\TrackEntry\Video\DisplayUnit" 3138 id: "0x54B2" 3140 maxOccurs: "1" 3142 default: "0" 3144 type: "uinteger" 3146 definition: How DisplayWidth & DisplayHeight are interpreted. 3148 restrictions: 3150 +-------+----------------------+ 3151 | value | label | 3152 +=======+======================+ 3153 | "0" | pixels | 3154 +-------+----------------------+ 3155 | "1" | centimeters | 3156 +-------+----------------------+ 3157 | "2" | inches | 3158 +-------+----------------------+ 3159 | "3" | display aspect ratio | 3160 +-------+----------------------+ 3161 | "4" | unknown | 3162 +-------+----------------------+ 3164 Table 20 3166 10.4.1.31.15. AspectRatioType Element 3168 name: "AspectRatioType" 3170 path: "\Segment\Tracks\TrackEntry\Video\AspectRatioType" 3172 id: "0x54B3" 3174 maxOccurs: "1" 3176 default: "0" 3178 type: "uinteger" 3180 definition: Specify the possible modifications to the aspect ratio. 3182 restrictions: 3184 +-------+-------------------+ 3185 | value | label | 3186 +=======+===================+ 3187 | "0" | free resizing | 3188 +-------+-------------------+ 3189 | "1" | keep aspect ratio | 3190 +-------+-------------------+ 3191 | "2" | fixed | 3192 +-------+-------------------+ 3194 Table 21 3196 10.4.1.31.16. ColourSpace Element 3198 name: "ColourSpace" 3200 path: "\Segment\Tracks\TrackEntry\Video\ColourSpace" 3202 id: "0x2EB524" 3204 minOccurs: see implementation notes 3206 maxOccurs: "1" 3208 type: "binary" 3210 definition: Specify the pixel format used for the Track's data as a 3211 FourCC. This value is similar in scope to the biCompression value of 3212 AVI's BITMAPINFOHEADER. 3214 implementation notes: 3216 +-----------+--------------------------------------------+ 3217 | attribute | note | 3218 +===========+============================================+ 3219 | minOccurs | ColourSpace MUST be set (minOccurs=1) in | 3220 | | TrackEntry when the CodecID Element of the | 3221 | | TrackEntry is set to "V_UNCOMPRESSED". | 3222 +-----------+--------------------------------------------+ 3224 Table 22 3226 10.4.1.31.17. GammaValue Element 3228 name: "GammaValue" 3230 path: "\Segment\Tracks\TrackEntry\Video\GammaValue" 3232 id: "0x2FB523" 3234 maxOccurs: "1" 3236 range: "> 0x0p+0" 3238 type: "float" 3240 minver: "0" 3242 maxver: "0" 3243 definition: Gamma Value. 3245 10.4.1.31.18. FrameRate Element 3247 name: "FrameRate" 3249 path: "\Segment\Tracks\TrackEntry\Video\FrameRate" 3251 id: "0x2383E3" 3253 maxOccurs: "1" 3255 range: "> 0x0p+0" 3257 type: "float" 3259 minver: "0" 3261 maxver: "0" 3263 definition: Number of frames per second. Informational only. 3265 10.4.1.31.19. Colour Element 3267 name: "Colour" 3269 path: "\Segment\Tracks\TrackEntry\Video\Colour" 3271 id: "0x55B0" 3273 maxOccurs: "1" 3275 type: "master" 3277 minver: "4" 3279 definition: Settings describing the colour format. 3281 10.4.1.31.19.1. MatrixCoefficients Element 3283 name: "MatrixCoefficients" 3285 path: "\Segment\Tracks\TrackEntry\Video\Colour\MatrixCoefficients" 3287 id: "0x55B1" 3289 maxOccurs: "1" 3290 default: "2" 3292 type: "uinteger" 3294 minver: "4" 3296 definition: The Matrix Coefficients of the video used to derive luma 3297 and chroma values from red, green, and blue color primaries. For 3298 clarity, the value and meanings for MatrixCoefficients are adopted 3299 from Table 4 of ISO/IEC 23001-8:2016 or ITU-T H.273. 3301 restrictions: 3303 +-------+---------------------------------------+ 3304 | value | label | 3305 +=======+=======================================+ 3306 | "0" | Identity | 3307 +-------+---------------------------------------+ 3308 | "1" | ITU-R BT.709 | 3309 +-------+---------------------------------------+ 3310 | "2" | unspecified | 3311 +-------+---------------------------------------+ 3312 | "3" | reserved | 3313 +-------+---------------------------------------+ 3314 | "4" | US FCC 73.682 | 3315 +-------+---------------------------------------+ 3316 | "5" | ITU-R BT.470BG | 3317 +-------+---------------------------------------+ 3318 | "6" | SMPTE 170M | 3319 +-------+---------------------------------------+ 3320 | "7" | SMPTE 240M | 3321 +-------+---------------------------------------+ 3322 | "8" | YCoCg | 3323 +-------+---------------------------------------+ 3324 | "9" | BT2020 Non-constant Luminance | 3325 +-------+---------------------------------------+ 3326 | "10" | BT2020 Constant Luminance | 3327 +-------+---------------------------------------+ 3328 | "11" | SMPTE ST 2085 | 3329 +-------+---------------------------------------+ 3330 | "12" | Chroma-derived Non-constant Luminance | 3331 +-------+---------------------------------------+ 3332 | "13" | Chroma-derived Constant Luminance | 3333 +-------+---------------------------------------+ 3334 | "14" | ITU-R BT.2100-0 | 3335 +-------+---------------------------------------+ 3337 Table 23 3339 10.4.1.31.19.2. BitsPerChannel Element 3341 name: "BitsPerChannel" 3343 path: "\Segment\Tracks\TrackEntry\Video\Colour\BitsPerChannel" 3345 id: "0x55B2" 3347 maxOccurs: "1" 3349 default: "0" 3351 type: "uinteger" 3353 minver: "4" 3355 definition: Number of decoded bits per channel. A value of 0 3356 indicates that the BitsPerChannel is unspecified. 3358 10.4.1.31.19.3. ChromaSubsamplingHorz Element 3360 name: "ChromaSubsamplingHorz" 3362 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingHorz" 3364 id: "0x55B3" 3366 maxOccurs: "1" 3368 type: "uinteger" 3370 minver: "4" 3372 definition: The amount of pixels to remove in the Cr and Cb channels 3373 for every pixel not removed horizontally. Example: For video with 3374 4:2:0 chroma subsampling, the ChromaSubsamplingHorz SHOULD be set to 3375 1. 3377 10.4.1.31.19.4. ChromaSubsamplingVert Element 3379 name: "ChromaSubsamplingVert" 3381 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingVert" 3383 id: "0x55B4" 3385 maxOccurs: "1" 3386 type: "uinteger" 3388 minver: "4" 3390 definition: The amount of pixels to remove in the Cr and Cb channels 3391 for every pixel not removed vertically. Example: For video with 3392 4:2:0 chroma subsampling, the ChromaSubsamplingVert SHOULD be set to 3393 1. 3395 10.4.1.31.19.5. CbSubsamplingHorz Element 3397 name: "CbSubsamplingHorz" 3399 path: "\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingHorz" 3401 id: "0x55B5" 3403 maxOccurs: "1" 3405 type: "uinteger" 3407 minver: "4" 3409 definition: The amount of pixels to remove in the Cb channel for 3410 every pixel not removed horizontally. This is additive with 3411 ChromaSubsamplingHorz. Example: For video with 4:2:1 chroma 3412 subsampling, the ChromaSubsamplingHorz SHOULD be set to 1 and 3413 CbSubsamplingHorz SHOULD be set to 1. 3415 10.4.1.31.19.6. CbSubsamplingVert Element 3417 name: "CbSubsamplingVert" 3419 path: "\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingVert" 3421 id: "0x55B6" 3423 maxOccurs: "1" 3425 type: "uinteger" 3427 minver: "4" 3429 definition: The amount of pixels to remove in the Cb channel for 3430 every pixel not removed vertically. This is additive with 3431 ChromaSubsamplingVert. 3433 10.4.1.31.19.7. ChromaSitingHorz Element 3435 name: "ChromaSitingHorz" 3437 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingHorz" 3439 id: "0x55B7" 3441 maxOccurs: "1" 3443 default: "0" 3445 type: "uinteger" 3447 minver: "4" 3449 definition: How chroma is subsampled horizontally. 3451 restrictions: 3453 +-------+-----------------+ 3454 | value | label | 3455 +=======+=================+ 3456 | "0" | unspecified | 3457 +-------+-----------------+ 3458 | "1" | left collocated | 3459 +-------+-----------------+ 3460 | "2" | half | 3461 +-------+-----------------+ 3463 Table 24 3465 10.4.1.31.19.8. ChromaSitingVert Element 3467 name: "ChromaSitingVert" 3469 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingVert" 3471 id: "0x55B8" 3473 maxOccurs: "1" 3475 default: "0" 3477 type: "uinteger" 3479 minver: "4" 3480 definition: How chroma is subsampled vertically. 3482 restrictions: 3484 +-------+----------------+ 3485 | value | label | 3486 +=======+================+ 3487 | "0" | unspecified | 3488 +-------+----------------+ 3489 | "1" | top collocated | 3490 +-------+----------------+ 3491 | "2" | half | 3492 +-------+----------------+ 3494 Table 25 3496 10.4.1.31.19.9. Range Element 3498 name: "Range" 3500 path: "\Segment\Tracks\TrackEntry\Video\Colour\Range" 3502 id: "0x55B9" 3504 maxOccurs: "1" 3506 default: "0" 3508 type: "uinteger" 3510 minver: "4" 3512 definition: Clipping of the color ranges. 3514 restrictions: 3516 +-------+---------------------------------------------------------+ 3517 | value | label | 3518 +=======+=========================================================+ 3519 | "0" | unspecified | 3520 +-------+---------------------------------------------------------+ 3521 | "1" | broadcast range | 3522 +-------+---------------------------------------------------------+ 3523 | "2" | full range (no clipping) | 3524 +-------+---------------------------------------------------------+ 3525 | "3" | defined by MatrixCoefficients / TransferCharacteristics | 3526 +-------+---------------------------------------------------------+ 3528 Table 26 3530 10.4.1.31.19.10. TransferCharacteristics Element 3532 name: "TransferCharacteristics" 3534 path: 3535 "\Segment\Tracks\TrackEntry\Video\Colour\TransferCharacteristics" 3537 id: "0x55BA" 3539 maxOccurs: "1" 3541 default: "2" 3543 type: "uinteger" 3545 minver: "4" 3547 definition: The transfer characteristics of the video. For clarity, 3548 the value and meanings for TransferCharacteristics are adopted from 3549 Table 3 of ISO/IEC 23091-4 or ITU-T H.273. 3551 restrictions: 3553 +-------+---------------------------------------+ 3554 | value | label | 3555 +=======+=======================================+ 3556 | "0" | reserved | 3557 +-------+---------------------------------------+ 3558 | "1" | ITU-R BT.709 | 3559 +-------+---------------------------------------+ 3560 | "2" | unspecified | 3561 +-------+---------------------------------------+ 3562 | "3" | reserved | 3563 +-------+---------------------------------------+ 3564 | "4" | Gamma 2.2 curve - BT.470M | 3565 +-------+---------------------------------------+ 3566 | "5" | Gamma 2.8 curve - BT.470BG | 3567 +-------+---------------------------------------+ 3568 | "6" | SMPTE 170M | 3569 +-------+---------------------------------------+ 3570 | "7" | SMPTE 240M | 3571 +-------+---------------------------------------+ 3572 | "8" | Linear | 3573 +-------+---------------------------------------+ 3574 | "9" | Log | 3575 +-------+---------------------------------------+ 3576 | "10" | Log Sqrt | 3577 +-------+---------------------------------------+ 3578 | "11" | IEC 61966-2-4 | 3579 +-------+---------------------------------------+ 3580 | "12" | ITU-R BT.1361 Extended Colour Gamut | 3581 +-------+---------------------------------------+ 3582 | "13" | IEC 61966-2-1 | 3583 +-------+---------------------------------------+ 3584 | "14" | ITU-R BT.2020 10 bit | 3585 +-------+---------------------------------------+ 3586 | "15" | ITU-R BT.2020 12 bit | 3587 +-------+---------------------------------------+ 3588 | "16" | ITU-R BT.2100 Perceptual Quantization | 3589 +-------+---------------------------------------+ 3590 | "17" | SMPTE ST 428-1 | 3591 +-------+---------------------------------------+ 3592 | "18" | ARIB STD-B67 (HLG) | 3593 +-------+---------------------------------------+ 3595 Table 27 3597 10.4.1.31.19.11. Primaries Element 3599 name: "Primaries" 3600 path: "\Segment\Tracks\TrackEntry\Video\Colour\Primaries" 3602 id: "0x55BB" 3604 maxOccurs: "1" 3606 default: "2" 3608 type: "uinteger" 3610 minver: "4" 3612 definition: The colour primaries of the video. For clarity, the 3613 value and meanings for Primaries are adopted from Table 2 of ISO/IEC 3614 23091-4 or ITU-T H.273. 3616 restrictions: 3618 +-------+----------------------------------------+ 3619 | value | label | 3620 +=======+========================================+ 3621 | "0" | reserved | 3622 +-------+----------------------------------------+ 3623 | "1" | ITU-R BT.709 | 3624 +-------+----------------------------------------+ 3625 | "2" | unspecified | 3626 +-------+----------------------------------------+ 3627 | "3" | reserved | 3628 +-------+----------------------------------------+ 3629 | "4" | ITU-R BT.470M | 3630 +-------+----------------------------------------+ 3631 | "5" | ITU-R BT.470BG - BT.601 625 | 3632 +-------+----------------------------------------+ 3633 | "6" | ITU-R BT.601 525 - SMPTE 170M | 3634 +-------+----------------------------------------+ 3635 | "7" | SMPTE 240M | 3636 +-------+----------------------------------------+ 3637 | "8" | FILM | 3638 +-------+----------------------------------------+ 3639 | "9" | ITU-R BT.2020 | 3640 +-------+----------------------------------------+ 3641 | "10" | SMPTE ST 428-1 | 3642 +-------+----------------------------------------+ 3643 | "11" | SMPTE RP 432-2 | 3644 +-------+----------------------------------------+ 3645 | "12" | SMPTE EG 432-2 | 3646 +-------+----------------------------------------+ 3647 | "22" | EBU Tech. 3213-E - JEDEC P22 phosphors | 3648 +-------+----------------------------------------+ 3650 Table 28 3652 10.4.1.31.19.12. MaxCLL Element 3654 name: "MaxCLL" 3656 path: "\Segment\Tracks\TrackEntry\Video\Colour\MaxCLL" 3658 id: "0x55BC" 3660 maxOccurs: "1" 3662 type: "uinteger" 3664 minver: "4" 3665 definition: Maximum brightness of a single pixel (Maximum Content 3666 Light Level) in candelas per square meter (cd/m²). 3668 10.4.1.31.19.13. MaxFALL Element 3670 name: "MaxFALL" 3672 path: "\Segment\Tracks\TrackEntry\Video\Colour\MaxFALL" 3674 id: "0x55BD" 3676 maxOccurs: "1" 3678 type: "uinteger" 3680 minver: "4" 3682 definition: Maximum brightness of a single full frame (Maximum Frame- 3683 Average Light Level) in candelas per square meter (cd/m²). 3685 10.4.1.31.19.14. MasteringMetadata Element 3687 name: "MasteringMetadata" 3689 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata" 3691 id: "0x55D0" 3693 maxOccurs: "1" 3695 type: "master" 3697 minver: "4" 3699 definition: SMPTE 2086 mastering data. 3701 10.4.1.31.19.15. PrimaryRChromaticityX Element 3703 name: "PrimaryRChromaticityX" 3705 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim 3706 aryRChromaticityX" 3708 id: "0x55D1" 3710 maxOccurs: "1" 3712 range: "0-1" 3713 type: "float" 3715 minver: "4" 3717 definition: Red X chromaticity coordinate as defined by CIE 1931. 3719 10.4.1.31.19.16. PrimaryRChromaticityY Element 3721 name: "PrimaryRChromaticityY" 3723 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim 3724 aryRChromaticityY" 3726 id: "0x55D2" 3728 maxOccurs: "1" 3730 range: "0-1" 3732 type: "float" 3734 minver: "4" 3736 definition: Red Y chromaticity coordinate as defined by CIE 1931. 3738 10.4.1.31.19.17. PrimaryGChromaticityX Element 3740 name: "PrimaryGChromaticityX" 3742 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim 3743 aryGChromaticityX" 3745 id: "0x55D3" 3747 maxOccurs: "1" 3749 range: "0-1" 3751 type: "float" 3753 minver: "4" 3755 definition: Green X chromaticity coordinate as defined by CIE 1931. 3757 10.4.1.31.19.18. PrimaryGChromaticityY Element 3759 name: "PrimaryGChromaticityY" 3760 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim 3761 aryGChromaticityY" 3763 id: "0x55D4" 3765 maxOccurs: "1" 3767 range: "0-1" 3769 type: "float" 3771 minver: "4" 3773 definition: Green Y chromaticity coordinate as defined by CIE 1931. 3775 10.4.1.31.19.19. PrimaryBChromaticityX Element 3777 name: "PrimaryBChromaticityX" 3779 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim 3780 aryBChromaticityX" 3782 id: "0x55D5" 3784 maxOccurs: "1" 3786 range: "0-1" 3788 type: "float" 3790 minver: "4" 3792 definition: Blue X chromaticity coordinate as defined by CIE 1931. 3794 10.4.1.31.19.20. PrimaryBChromaticityY Element 3796 name: "PrimaryBChromaticityY" 3798 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Prim 3799 aryBChromaticityY" 3801 id: "0x55D6" 3803 maxOccurs: "1" 3805 range: "0-1" 3807 type: "float" 3808 minver: "4" 3810 definition: Blue Y chromaticity coordinate as defined by CIE 1931. 3812 10.4.1.31.19.21. WhitePointChromaticityX Element 3814 name: "WhitePointChromaticityX" 3816 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Whit 3817 ePointChromaticityX" 3819 id: "0x55D7" 3821 maxOccurs: "1" 3823 range: "0-1" 3825 type: "float" 3827 minver: "4" 3829 definition: White X chromaticity coordinate as defined by CIE 1931. 3831 10.4.1.31.19.22. WhitePointChromaticityY Element 3833 name: "WhitePointChromaticityY" 3835 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Whit 3836 ePointChromaticityY" 3838 id: "0x55D8" 3840 maxOccurs: "1" 3842 range: "0-1" 3844 type: "float" 3846 minver: "4" 3848 definition: White Y chromaticity coordinate as defined by CIE 1931. 3850 10.4.1.31.19.23. LuminanceMax Element 3852 name: "LuminanceMax" 3854 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Lumi 3855 nanceMax" 3856 id: "0x55D9" 3858 maxOccurs: "1" 3860 range: ">= 0x0p+0" 3862 type: "float" 3864 minver: "4" 3866 definition: Maximum luminance. Represented in candelas per square 3867 meter (cd/m²). 3869 10.4.1.31.19.24. LuminanceMin Element 3871 name: "LuminanceMin" 3873 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Lumi 3874 nanceMin" 3876 id: "0x55DA" 3878 maxOccurs: "1" 3880 range: ">= 0x0p+0" 3882 type: "float" 3884 minver: "4" 3886 definition: Minimum luminance. Represented in candelas per square 3887 meter (cd/m²). 3889 10.4.1.31.20. Projection Element 3891 name: "Projection" 3893 path: "\Segment\Tracks\TrackEntry\Video\Projection" 3895 id: "0x7670" 3897 maxOccurs: "1" 3899 type: "master" 3901 minver: "4" 3902 definition: Describes the video projection details. Used to render 3903 spherical and VR videos. 3905 10.4.1.31.20.1. ProjectionType Element 3907 name: "ProjectionType" 3909 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionType" 3911 id: "0x7671" 3913 minOccurs: "1" 3915 maxOccurs: "1" 3917 range: "0-3" 3919 default: "0" 3921 type: "uinteger" 3923 minver: "4" 3925 definition: Describes the projection used for this video track. 3927 restrictions: 3929 +-------+-----------------+ 3930 | value | label | 3931 +=======+=================+ 3932 | "0" | rectangular | 3933 +-------+-----------------+ 3934 | "1" | equirectangular | 3935 +-------+-----------------+ 3936 | "2" | cubemap | 3937 +-------+-----------------+ 3938 | "3" | mesh | 3939 +-------+-----------------+ 3941 Table 29 3943 10.4.1.31.20.2. ProjectionPrivate Element 3945 name: "ProjectionPrivate" 3947 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPrivate" 3949 id: "0x7672" 3950 maxOccurs: "1" 3952 type: "binary" 3954 minver: "4" 3956 definition: Private data that only applies to a specific 3957 projection.SemanticsIf ProjectionType equals 0 (Rectangular), then 3958 this element must not be present.If ProjectionType equals 1 3959 (Equirectangular), then this element must be present and contain the 3960 same binary data that would be stored inside an ISOBMFF 3961 Equirectangular Projection Box ('equi').If ProjectionType equals 2 3962 (Cubemap), then this element must be present and contain the same 3963 binary data that would be stored inside an ISOBMFF Cubemap Projection 3964 Box ('cbmp').If ProjectionType equals 3 (Mesh), then this element 3965 must be present and contain the same binary data that would be stored 3966 inside an ISOBMFF Mesh Projection Box ('mshp').Note: ISOBMFF box size 3967 and fourcc fields are not included in the binary data, but the 3968 FullBox version and flag fields are. This is to avoid redundant 3969 framing information while preserving versioning and semantics between 3970 the two container formats. 3972 10.4.1.31.20.3. ProjectionPoseYaw Element 3974 name: "ProjectionPoseYaw" 3976 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseYaw" 3978 id: "0x7673" 3980 minOccurs: "1" 3982 maxOccurs: "1" 3984 default: "0x0p+0" 3986 type: "float" 3988 minver: "4" 3990 definition: Specifies a yaw rotation to the projection.SemanticsValue 3991 represents a clockwise rotation, in degrees, around the up vector. 3992 This rotation must be applied before any ProjectionPosePitch or 3993 ProjectionPoseRoll rotations. The value of this field should be in 3994 the -180 to 180 degree range. 3996 10.4.1.31.20.4. ProjectionPosePitch Element 3998 name: "ProjectionPosePitch" 4000 path: 4001 "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPosePitch" 4003 id: "0x7674" 4005 minOccurs: "1" 4007 maxOccurs: "1" 4009 default: "0x0p+0" 4011 type: "float" 4013 minver: "4" 4015 definition: Specifies a pitch rotation to the 4016 projection.SemanticsValue represents a counter-clockwise rotation, in 4017 degrees, around the right vector. This rotation must be applied 4018 after the ProjectionPoseYaw rotation and before the 4019 ProjectionPoseRoll rotation. The value of this field should be in 4020 the -90 to 90 degree range. 4022 10.4.1.31.20.5. ProjectionPoseRoll Element 4024 name: "ProjectionPoseRoll" 4026 path: 4027 "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseRoll" 4029 id: "0x7675" 4031 minOccurs: "1" 4033 maxOccurs: "1" 4035 default: "0x0p+0" 4037 type: "float" 4039 minver: "4" 4040 definition: Specifies a roll rotation to the 4041 projection.SemanticsValue represents a counter-clockwise rotation, in 4042 degrees, around the forward vector. This rotation must be applied 4043 after the ProjectionPoseYaw and ProjectionPosePitch rotations. The 4044 value of this field should be in the -180 to 180 degree range. 4046 10.4.1.32. Audio Element 4048 name: "Audio" 4050 path: "\Segment\Tracks\TrackEntry\Audio" 4052 id: "0xE1" 4054 maxOccurs: "1" 4056 type: "master" 4058 definition: Audio settings. 4060 10.4.1.32.1. SamplingFrequency Element 4062 name: "SamplingFrequency" 4064 path: "\Segment\Tracks\TrackEntry\Audio\SamplingFrequency" 4066 id: "0xB5" 4068 minOccurs: "1" 4070 maxOccurs: "1" 4072 range: "> 0x0p+0" 4074 default: "0x1.f4p+12" 4076 type: "float" 4078 definition: Sampling frequency in Hz. 4080 10.4.1.32.2. OutputSamplingFrequency Element 4082 name: "OutputSamplingFrequency" 4084 path: "\Segment\Tracks\TrackEntry\Audio\OutputSamplingFrequency" 4086 id: "0x78B5" 4087 maxOccurs: "1" 4089 range: "> 0x0p+0" 4091 default: see implementation notes 4093 type: "float" 4095 definition: Real output sampling frequency in Hz (used for SBR 4096 techniques). 4098 implementation notes: 4100 +-----------+------------------------------------------------------+ 4101 | attribute | note | 4102 +===========+======================================================+ 4103 | default | The default value for OutputSamplingFrequency of the | 4104 | | same TrackEntry is equal to the SamplingFrequency. | 4105 +-----------+------------------------------------------------------+ 4107 Table 30 4109 10.4.1.32.3. Channels Element 4111 name: "Channels" 4113 path: "\Segment\Tracks\TrackEntry\Audio\Channels" 4115 id: "0x9F" 4117 minOccurs: "1" 4119 maxOccurs: "1" 4121 range: "not 0" 4123 default: "1" 4125 type: "uinteger" 4127 definition: Numbers of channels in the track. 4129 10.4.1.32.4. ChannelPositions Element 4131 name: "ChannelPositions" 4133 path: "\Segment\Tracks\TrackEntry\Audio\ChannelPositions" 4134 id: "0x7D7B" 4136 maxOccurs: "1" 4138 type: "binary" 4140 minver: "0" 4142 maxver: "0" 4144 definition: Table of horizontal angles for each successive channel, 4145 see appendix. 4147 10.4.1.32.5. BitDepth Element 4149 name: "BitDepth" 4151 path: "\Segment\Tracks\TrackEntry\Audio\BitDepth" 4153 id: "0x6264" 4155 maxOccurs: "1" 4157 range: "not 0" 4159 type: "uinteger" 4161 definition: Bits per sample, mostly used for PCM. 4163 10.4.1.33. TrackOperation Element 4165 name: "TrackOperation" 4167 path: "\Segment\Tracks\TrackEntry\TrackOperation" 4169 id: "0xE2" 4171 maxOccurs: "1" 4173 type: "master" 4175 minver: "3" 4177 definition: Operation that needs to be applied on tracks to create 4178 this virtual track. For more details look at the Specification Notes 4179 on the subject. 4181 10.4.1.33.1. TrackCombinePlanes Element 4183 name: "TrackCombinePlanes" 4185 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes" 4187 id: "0xE3" 4189 maxOccurs: "1" 4191 type: "master" 4193 minver: "3" 4195 definition: Contains the list of all video plane tracks that need to 4196 be combined to create this 3D track 4198 10.4.1.33.1.1. TrackPlane Element 4200 name: "TrackPlane" 4202 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\T 4203 rackPlane" 4205 id: "0xE4" 4207 minOccurs: "1" 4209 type: "master" 4211 minver: "3" 4213 definition: Contains a video plane track that need to be combined to 4214 create this 3D track 4216 10.4.1.33.1.2. TrackPlaneUID Element 4218 name: "TrackPlaneUID" 4220 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\T 4221 rackPlane\TrackPlaneUID" 4223 id: "0xE5" 4225 minOccurs: "1" 4227 maxOccurs: "1" 4228 range: "not 0" 4230 type: "uinteger" 4232 minver: "3" 4234 definition: The trackUID number of the track representing the plane. 4236 10.4.1.33.1.3. TrackPlaneType Element 4238 name: "TrackPlaneType" 4240 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\T 4241 rackPlane\TrackPlaneType" 4243 id: "0xE6" 4245 minOccurs: "1" 4247 maxOccurs: "1" 4249 type: "uinteger" 4251 minver: "3" 4253 definition: The kind of plane this track corresponds to. 4255 restrictions: 4257 +-------+------------+ 4258 | value | label | 4259 +=======+============+ 4260 | "0" | left eye | 4261 +-------+------------+ 4262 | "1" | right eye | 4263 +-------+------------+ 4264 | "2" | background | 4265 +-------+------------+ 4267 Table 31 4269 10.4.1.33.2. TrackJoinBlocks Element 4271 name: "TrackJoinBlocks" 4273 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks" 4275 id: "0xE9" 4276 maxOccurs: "1" 4278 type: "master" 4280 minver: "3" 4282 definition: Contains the list of all tracks whose Blocks need to be 4283 combined to create this virtual track 4285 10.4.1.33.2.1. TrackJoinUID Element 4287 name: "TrackJoinUID" 4289 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks\Trac 4290 kJoinUID" 4292 id: "0xED" 4294 minOccurs: "1" 4296 range: "not 0" 4298 type: "uinteger" 4300 minver: "3" 4302 definition: The trackUID number of a track whose blocks are used to 4303 create this virtual track. 4305 10.4.1.34. TrickTrackUID Element 4307 name: "TrickTrackUID" 4309 path: "\Segment\Tracks\TrackEntry\TrickTrackUID" 4311 id: "0xC0" 4313 maxOccurs: "1" 4315 type: "uinteger" 4317 minver: "0" 4319 maxver: "0" 4321 definition: DivX trick track extensions 4323 10.4.1.35. TrickTrackSegmentUID Element 4325 name: "TrickTrackSegmentUID" 4327 path: "\Segment\Tracks\TrackEntry\TrickTrackSegmentUID" 4329 id: "0xC1" 4331 maxOccurs: "1" 4333 type: "binary" 4335 minver: "0" 4337 maxver: "0" 4339 definition: DivX trick track extensions 4341 10.4.1.36. TrickTrackFlag Element 4343 name: "TrickTrackFlag" 4345 path: "\Segment\Tracks\TrackEntry\TrickTrackFlag" 4347 id: "0xC6" 4349 maxOccurs: "1" 4351 default: "0" 4353 type: "uinteger" 4355 minver: "0" 4357 maxver: "0" 4359 definition: DivX trick track extensions 4361 10.4.1.37. TrickMasterTrackUID Element 4363 name: "TrickMasterTrackUID" 4365 path: "\Segment\Tracks\TrackEntry\TrickMasterTrackUID" 4367 id: "0xC7" 4369 maxOccurs: "1" 4370 type: "uinteger" 4372 minver: "0" 4374 maxver: "0" 4376 definition: DivX trick track extensions 4378 10.4.1.38. TrickMasterTrackSegmentUID Element 4380 name: "TrickMasterTrackSegmentUID" 4382 path: "\Segment\Tracks\TrackEntry\TrickMasterTrackSegmentUID" 4384 id: "0xC4" 4386 maxOccurs: "1" 4388 type: "binary" 4390 minver: "0" 4392 maxver: "0" 4394 definition: DivX trick track extensions 4396 10.4.1.39. ContentEncodings Element 4398 name: "ContentEncodings" 4400 path: "\Segment\Tracks\TrackEntry\ContentEncodings" 4402 id: "0x6D80" 4404 maxOccurs: "1" 4406 type: "master" 4408 definition: Settings for several content encoding mechanisms like 4409 compression or encryption. 4411 10.4.1.39.1. ContentEncoding Element 4413 name: "ContentEncoding" 4415 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding" 4417 id: "0x6240" 4418 minOccurs: "1" 4420 type: "master" 4422 definition: Settings for one content encoding like compression or 4423 encryption. 4425 10.4.1.39.1.1. ContentEncodingOrder Element 4427 name: "ContentEncodingOrder" 4429 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4430 ntentEncodingOrder" 4432 id: "0x5031" 4434 minOccurs: "1" 4436 maxOccurs: "1" 4438 default: "0" 4440 type: "uinteger" 4442 definition: Tells when this modification was used during encoding/ 4443 muxing starting with 0 and counting upwards. The decoder/demuxer has 4444 to start with the highest order number it finds and work its way 4445 down. This value has to be unique over all ContentEncodingOrder 4446 Elements in the TrackEntry that contains this ContentEncodingOrder 4447 element. 4449 10.4.1.39.1.2. ContentEncodingScope Element 4451 name: "ContentEncodingScope" 4453 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4454 ntentEncodingScope" 4456 id: "0x5032" 4458 minOccurs: "1" 4460 maxOccurs: "1" 4462 range: "not 0" 4464 default: "1" 4465 type: "uinteger" 4467 definition: A bit field that describes which Elements have been 4468 modified in this way. Values (big endian) can be OR'ed. 4470 restrictions: 4472 +-------+--------------------------------------------------+ 4473 | value | label | 4474 +=======+==================================================+ 4475 | "1" | All frame contents, excluding lacing data | 4476 +-------+--------------------------------------------------+ 4477 | "2" | The track's private data | 4478 +-------+--------------------------------------------------+ 4479 | "4" | The next ContentEncoding (next | 4480 | | "ContentEncodingOrder". Either the data inside | 4481 | | "ContentCompression" and/or "ContentEncryption") | 4482 +-------+--------------------------------------------------+ 4484 Table 32 4486 10.4.1.39.1.3. ContentEncodingType Element 4488 name: "ContentEncodingType" 4490 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4491 ntentEncodingType" 4493 id: "0x5033" 4495 minOccurs: "1" 4497 maxOccurs: "1" 4499 default: "0" 4501 type: "uinteger" 4503 definition: A value describing what kind of transformation is 4504 applied. 4506 restrictions: 4508 +-------+-------------+ 4509 | value | label | 4510 +=======+=============+ 4511 | "0" | Compression | 4512 +-------+-------------+ 4513 | "1" | Encryption | 4514 +-------+-------------+ 4516 Table 33 4518 10.4.1.39.1.4. ContentCompression Element 4520 name: "ContentCompression" 4522 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4523 ntentCompression" 4525 id: "0x5034" 4527 maxOccurs: "1" 4529 type: "master" 4531 definition: Settings describing the compression used. This Element 4532 MUST be present if the value of ContentEncodingType is 0 and absent 4533 otherwise. Each block MUST be decompressable even if no previous 4534 block is available in order not to prevent seeking. 4536 10.4.1.39.1.5. ContentCompAlgo Element 4538 name: "ContentCompAlgo" 4540 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4541 ntentCompression\ContentCompAlgo" 4543 id: "0x4254" 4545 minOccurs: "1" 4547 maxOccurs: "1" 4549 default: "0" 4551 type: "uinteger" 4553 definition: The compression algorithm used. 4555 restrictions: 4557 +-------+------------------+ 4558 | value | label | 4559 +=======+==================+ 4560 | "0" | zlib | 4561 +-------+------------------+ 4562 | "1" | bzlib | 4563 +-------+------------------+ 4564 | "2" | lzo1x | 4565 +-------+------------------+ 4566 | "3" | Header Stripping | 4567 +-------+------------------+ 4569 Table 34 4571 10.4.1.39.1.6. ContentCompSettings Element 4573 name: "ContentCompSettings" 4575 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4576 ntentCompression\ContentCompSettings" 4578 id: "0x4255" 4580 maxOccurs: "1" 4582 type: "binary" 4584 definition: Settings that might be needed by the decompressor. For 4585 Header Stripping ("ContentCompAlgo"=3), the bytes that were removed 4586 from the beginning of each frames of the track. 4588 10.4.1.39.1.7. ContentEncryption Element 4590 name: "ContentEncryption" 4592 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4593 ntentEncryption" 4595 id: "0x5035" 4597 maxOccurs: "1" 4599 type: "master" 4601 definition: Settings describing the encryption used. This Element 4602 MUST be present if the value of "ContentEncodingType" is 1 4603 (encryption) and MUST be ignored otherwise. 4605 10.4.1.39.1.8. ContentEncAlgo Element 4607 name: "ContentEncAlgo" 4609 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4610 ntentEncryption\ContentEncAlgo" 4612 id: "0x47E1" 4614 minOccurs: "1" 4616 maxOccurs: "1" 4618 default: "0" 4620 type: "uinteger" 4622 definition: The encryption algorithm used. The value '0' means that 4623 the contents have not been encrypted but only signed. 4625 restrictions: 4627 +-------+-----------------------+ 4628 | value | label | 4629 +=======+=======================+ 4630 | "0" | Not encrypted | 4631 +-------+-----------------------+ 4632 | "1" | DES - FIPS 46-3 | 4633 +-------+-----------------------+ 4634 | "2" | Triple DES - RFC 1851 | 4635 +-------+-----------------------+ 4636 | "3" | Twofish | 4637 +-------+-----------------------+ 4638 | "4" | Blowfish | 4639 +-------+-----------------------+ 4640 | "5" | AES - FIPS 187 | 4641 +-------+-----------------------+ 4643 Table 35 4645 10.4.1.39.1.9. ContentEncKeyID Element 4647 name: "ContentEncKeyID" 4649 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4650 ntentEncryption\ContentEncKeyID" 4652 id: "0x47E2" 4653 maxOccurs: "1" 4655 type: "binary" 4657 definition: For public key algorithms this is the ID of the public 4658 key the the data was encrypted with. 4660 10.4.1.39.1.10. ContentEncAESSettings Element 4662 name: "ContentEncAESSettings" 4664 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4665 ntentEncryption\ContentEncAESSettings" 4667 id: "0x47E7" 4669 maxOccurs: "1" 4671 type: "master" 4673 minver: "4" 4675 definition: Settings describing the encryption algorithm used. If 4676 "ContentEncAlgo" != 5 this MUST be ignored. 4678 10.4.1.39.1.11. AESSettingsCipherMode Element 4680 name: "AESSettingsCipherMode" 4682 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4683 ntentEncryption\ContentEncAESSettings\AESSettingsCipherMode" 4685 id: "0x47E8" 4687 minOccurs: "1" 4689 maxOccurs: "1" 4691 type: "uinteger" 4693 minver: "4" 4695 definition: The AES cipher mode used in the encryption. 4697 restrictions: 4699 +-------+--------------------------------------------------+ 4700 | value | label | 4701 +=======+==================================================+ 4702 | "1" | AES-CTR / Counter, NIST SP 800-38A | 4703 +-------+--------------------------------------------------+ 4704 | "2" | AES-CBC / Cipher Block Chaining, NIST SP 800-38A | 4705 +-------+--------------------------------------------------+ 4707 Table 36 4709 10.4.1.39.1.12. ContentSignature Element 4711 name: "ContentSignature" 4713 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4714 ntentEncryption\ContentSignature" 4716 id: "0x47E3" 4718 maxOccurs: "1" 4720 type: "binary" 4722 definition: A cryptographic signature of the contents. 4724 10.4.1.39.1.13. ContentSigKeyID Element 4726 name: "ContentSigKeyID" 4728 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4729 ntentEncryption\ContentSigKeyID" 4731 id: "0x47E4" 4733 maxOccurs: "1" 4735 type: "binary" 4737 definition: This is the ID of the private key the data was signed 4738 with. 4740 10.4.1.39.1.14. ContentSigAlgo Element 4742 name: "ContentSigAlgo" 4744 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4745 ntentEncryption\ContentSigAlgo" 4746 id: "0x47E5" 4748 maxOccurs: "1" 4750 default: "0" 4752 type: "uinteger" 4754 definition: The algorithm used for the signature. 4756 restrictions: 4758 +-------+------------+ 4759 | value | label | 4760 +=======+============+ 4761 | "0" | Not signed | 4762 +-------+------------+ 4763 | "1" | RSA | 4764 +-------+------------+ 4766 Table 37 4768 10.4.1.39.1.15. ContentSigHashAlgo Element 4770 name: "ContentSigHashAlgo" 4772 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\Co 4773 ntentEncryption\ContentSigHashAlgo" 4775 id: "0x47E6" 4777 maxOccurs: "1" 4779 default: "0" 4781 type: "uinteger" 4783 definition: The hash algorithm used for the signature. 4785 restrictions: 4787 +-------+------------+ 4788 | value | label | 4789 +=======+============+ 4790 | "0" | Not signed | 4791 +-------+------------+ 4792 | "1" | SHA1-160 | 4793 +-------+------------+ 4794 | "2" | MD5 | 4795 +-------+------------+ 4797 Table 38 4799 10.5. Cues Element 4801 name: "Cues" 4803 path: "\Segment\Cues" 4805 id: "0x1C53BB6B" 4807 minOccurs: see implementation notes 4809 maxOccurs: "1" 4811 type: "master" 4813 definition: A Top-Level Element to speed seeking access. All entries 4814 are local to the Segment. 4816 implementation notes: 4818 +-----------+----------------------------------------------------+ 4819 | attribute | note | 4820 +===========+====================================================+ 4821 | minOccurs | This Element SHOULD be set when the Segment is not | 4822 | | transmitted as a live stream (see #livestreaming). | 4823 +-----------+----------------------------------------------------+ 4825 Table 39 4827 10.5.1. CuePoint Element 4829 name: "CuePoint" 4831 path: "\Segment\Cues\CuePoint" 4833 id: "0xBB" 4834 minOccurs: "1" 4836 type: "master" 4838 definition: Contains all information relative to a seek point in the 4839 Segment. 4841 10.5.1.1. CueTime Element 4843 name: "CueTime" 4845 path: "\Segment\Cues\CuePoint\CueTime" 4847 id: "0xB3" 4849 minOccurs: "1" 4851 maxOccurs: "1" 4853 type: "uinteger" 4855 definition: Absolute timestamp according to the Segment time base. 4857 10.5.1.2. CueTrackPositions Element 4859 name: "CueTrackPositions" 4861 path: "\Segment\Cues\CuePoint\CueTrackPositions" 4863 id: "0xB7" 4865 minOccurs: "1" 4867 type: "master" 4869 definition: Contain positions for different tracks corresponding to 4870 the timestamp. 4872 10.5.1.2.1. CueTrack Element 4874 name: "CueTrack" 4876 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueTrack" 4878 id: "0xF7" 4880 minOccurs: "1" 4881 maxOccurs: "1" 4883 range: "not 0" 4885 type: "uinteger" 4887 definition: The track for which a position is given. 4889 10.5.1.2.2. CueClusterPosition Element 4891 name: "CueClusterPosition" 4893 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueClusterPosition" 4895 id: "0xF1" 4897 minOccurs: "1" 4899 maxOccurs: "1" 4901 type: "uinteger" 4903 definition: The Segment Position of the Cluster containing the 4904 associated Block. 4906 10.5.1.2.3. CueRelativePosition Element 4908 name: "CueRelativePosition" 4910 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueRelativePosition" 4912 id: "0xF0" 4914 maxOccurs: "1" 4916 type: "uinteger" 4918 minver: "4" 4920 definition: The relative position inside the Cluster of the 4921 referenced SimpleBlock or BlockGroup with 0 being the first possible 4922 position for an Element inside that Cluster. 4924 10.5.1.2.4. CueDuration Element 4926 name: "CueDuration" 4928 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueDuration" 4929 id: "0xB2" 4931 maxOccurs: "1" 4933 type: "uinteger" 4935 minver: "4" 4937 definition: The duration of the block according to the Segment time 4938 base. If missing the track's DefaultDuration does not apply and no 4939 duration information is available in terms of the cues. 4941 10.5.1.2.5. CueBlockNumber Element 4943 name: "CueBlockNumber" 4945 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueBlockNumber" 4947 id: "0x5378" 4949 maxOccurs: "1" 4951 range: "not 0" 4953 default: "1" 4955 type: "uinteger" 4957 definition: Number of the Block in the specified Cluster. 4959 10.5.1.2.6. CueCodecState Element 4961 name: "CueCodecState" 4963 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueCodecState" 4965 id: "0xEA" 4967 maxOccurs: "1" 4969 default: "0" 4971 type: "uinteger" 4973 minver: "2" 4974 definition: The Segment Position of the Codec State corresponding to 4975 this Cue Element. 0 means that the data is taken from the initial 4976 Track Entry. 4978 10.5.1.2.7. CueReference Element 4980 name: "CueReference" 4982 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueReference" 4984 id: "0xDB" 4986 type: "master" 4988 minver: "2" 4990 definition: The Clusters containing the referenced Blocks. 4992 10.5.1.2.7.1. CueRefTime Element 4994 name: "CueRefTime" 4996 path: 4997 "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefTime" 4999 id: "0x96" 5001 minOccurs: "1" 5003 maxOccurs: "1" 5005 type: "uinteger" 5007 minver: "2" 5009 definition: Timestamp of the referenced Block. 5011 10.5.1.2.7.2. CueRefCluster Element 5013 name: "CueRefCluster" 5015 path: 5016 "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefCluster" 5018 id: "0x97" 5020 minOccurs: "1" 5021 maxOccurs: "1" 5023 type: "uinteger" 5025 minver: "0" 5027 maxver: "0" 5029 definition: The Segment Position of the Cluster containing the 5030 referenced Block. 5032 10.5.1.2.7.3. CueRefNumber Element 5034 name: "CueRefNumber" 5036 path: 5037 "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefNumber" 5039 id: "0x535F" 5041 maxOccurs: "1" 5043 range: "not 0" 5045 default: "1" 5047 type: "uinteger" 5049 minver: "0" 5051 maxver: "0" 5053 definition: Number of the referenced Block of Track X in the 5054 specified Cluster. 5056 10.5.1.2.7.4. CueRefCodecState Element 5058 name: "CueRefCodecState" 5060 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefCo 5061 decState" 5063 id: "0xEB" 5065 maxOccurs: "1" 5067 default: "0" 5068 type: "uinteger" 5070 minver: "0" 5072 maxver: "0" 5074 definition: The Segment Position of the Codec State corresponding to 5075 this referenced Element. 0 means that the data is taken from the 5076 initial Track Entry. 5078 10.6. Attachments Element 5080 name: "Attachments" 5082 path: "\Segment\Attachments" 5084 id: "0x1941A469" 5086 maxOccurs: "1" 5088 type: "master" 5090 definition: Contain attached files. 5092 10.6.1. AttachedFile Element 5094 name: "AttachedFile" 5096 path: "\Segment\Attachments\AttachedFile" 5098 id: "0x61A7" 5100 minOccurs: "1" 5102 type: "master" 5104 definition: An attached file. 5106 10.6.1.1. FileDescription Element 5108 name: "FileDescription" 5110 path: "\Segment\Attachments\AttachedFile\FileDescription" 5112 id: "0x467E" 5114 maxOccurs: "1" 5115 type: "utf-8" 5117 definition: A human-friendly name for the attached file. 5119 10.6.1.2. FileName Element 5121 name: "FileName" 5123 path: "\Segment\Attachments\AttachedFile\FileName" 5125 id: "0x466E" 5127 minOccurs: "1" 5129 maxOccurs: "1" 5131 type: "utf-8" 5133 definition: Filename of the attached file. 5135 10.6.1.3. FileMimeType Element 5137 name: "FileMimeType" 5139 path: "\Segment\Attachments\AttachedFile\FileMimeType" 5141 id: "0x4660" 5143 minOccurs: "1" 5145 maxOccurs: "1" 5147 type: "string" 5149 definition: MIME type of the file. 5151 10.6.1.4. FileData Element 5153 name: "FileData" 5155 path: "\Segment\Attachments\AttachedFile\FileData" 5157 id: "0x465C" 5159 minOccurs: "1" 5161 maxOccurs: "1" 5162 type: "binary" 5164 definition: The data of the file. 5166 10.6.1.5. FileUID Element 5168 name: "FileUID" 5170 path: "\Segment\Attachments\AttachedFile\FileUID" 5172 id: "0x46AE" 5174 minOccurs: "1" 5176 maxOccurs: "1" 5178 range: "not 0" 5180 type: "uinteger" 5182 definition: Unique ID representing the file, as random as possible. 5184 10.6.1.6. FileReferral Element 5186 name: "FileReferral" 5188 path: "\Segment\Attachments\AttachedFile\FileReferral" 5190 id: "0x4675" 5192 maxOccurs: "1" 5194 type: "binary" 5196 minver: "0" 5198 maxver: "0" 5200 definition: A binary value that a track/codec can refer to when the 5201 attachment is needed. 5203 10.6.1.7. FileUsedStartTime Element 5205 name: "FileUsedStartTime" 5207 path: "\Segment\Attachments\AttachedFile\FileUsedStartTime" 5209 id: "0x4661" 5210 maxOccurs: "1" 5212 type: "uinteger" 5214 minver: "0" 5216 maxver: "0" 5218 definition: DivX font extension 5220 10.6.1.8. FileUsedEndTime Element 5222 name: "FileUsedEndTime" 5224 path: "\Segment\Attachments\AttachedFile\FileUsedEndTime" 5226 id: "0x4662" 5228 maxOccurs: "1" 5230 type: "uinteger" 5232 minver: "0" 5234 maxver: "0" 5236 definition: DivX font extension 5238 10.7. Chapters Element 5240 name: "Chapters" 5242 path: "\Segment\Chapters" 5244 id: "0x1043A770" 5246 maxOccurs: "1" 5248 type: "master" 5250 recurring: "1" 5252 definition: A system to define basic menus and partition data. For 5253 more detailed information, look at the Chapters Explanation. 5255 10.7.1. EditionEntry Element 5257 name: "EditionEntry" 5259 path: "\Segment\Chapters\EditionEntry" 5261 id: "0x45B9" 5263 minOccurs: "1" 5265 type: "master" 5267 definition: Contains all information about a Segment edition. 5269 10.7.1.1. EditionUID Element 5271 name: "EditionUID" 5273 path: "\Segment\Chapters\EditionEntry\EditionUID" 5275 id: "0x45BC" 5277 maxOccurs: "1" 5279 range: "not 0" 5281 type: "uinteger" 5283 definition: A unique ID to identify the edition. It's useful for 5284 tagging an edition. 5286 10.7.1.2. EditionFlagHidden Element 5288 name: "EditionFlagHidden" 5290 path: "\Segment\Chapters\EditionEntry\EditionFlagHidden" 5292 id: "0x45BD" 5294 minOccurs: "1" 5296 maxOccurs: "1" 5298 range: "0-1" 5300 default: "0" 5302 type: "uinteger" 5303 definition: If an edition is hidden (1), it SHOULD NOT be available 5304 to the user interface (but still to Control Tracks; see flag notes). 5305 (1 bit) 5307 10.7.1.3. EditionFlagDefault Element 5309 name: "EditionFlagDefault" 5311 path: "\Segment\Chapters\EditionEntry\EditionFlagDefault" 5313 id: "0x45DB" 5315 minOccurs: "1" 5317 maxOccurs: "1" 5319 range: "0-1" 5321 default: "0" 5323 type: "uinteger" 5325 definition: If a flag is set (1) the edition SHOULD be used as the 5326 default one. (1 bit) 5328 10.7.1.4. EditionFlagOrdered Element 5330 name: "EditionFlagOrdered" 5332 path: "\Segment\Chapters\EditionEntry\EditionFlagOrdered" 5334 id: "0x45DD" 5336 maxOccurs: "1" 5338 range: "0-1" 5340 default: "0" 5342 type: "uinteger" 5344 definition: Specify if the chapters can be defined multiple times and 5345 the order to play them is enforced. (1 bit) 5347 10.7.1.5. ChapterAtom Element 5349 name: "ChapterAtom" 5350 path: "\Segment\Chapters\EditionEntry\+ChapterAtom" 5352 id: "0xB6" 5354 minOccurs: "1" 5356 type: "master" 5358 recursive: "1" 5360 definition: Contains the atom information to use as the chapter atom 5361 (apply to all tracks). 5363 10.7.1.5.1. ChapterUID Element 5365 name: "ChapterUID" 5367 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterUID" 5369 id: "0x73C4" 5371 minOccurs: "1" 5373 maxOccurs: "1" 5375 range: "not 0" 5377 type: "uinteger" 5379 definition: A unique ID to identify the Chapter. 5381 10.7.1.5.2. ChapterStringUID Element 5383 name: "ChapterStringUID" 5385 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterStringUID" 5387 id: "0x5654" 5389 maxOccurs: "1" 5391 type: "utf-8" 5393 minver: "3" 5395 definition: A unique string ID to identify the Chapter. Use for 5396 WebVTT cue identifier storage. 5398 10.7.1.5.3. ChapterTimeStart Element 5400 name: "ChapterTimeStart" 5402 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTimeStart" 5404 id: "0x91" 5406 minOccurs: "1" 5408 maxOccurs: "1" 5410 type: "uinteger" 5412 definition: Timestamp of the start of Chapter (not scaled). 5414 10.7.1.5.4. ChapterTimeEnd Element 5416 name: "ChapterTimeEnd" 5418 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTimeEnd" 5420 id: "0x92" 5422 maxOccurs: "1" 5424 type: "uinteger" 5426 definition: Timestamp of the end of Chapter (timestamp excluded, not 5427 scaled). 5429 10.7.1.5.5. ChapterFlagHidden Element 5431 name: "ChapterFlagHidden" 5433 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterFlagHidden" 5435 id: "0x98" 5437 minOccurs: "1" 5439 maxOccurs: "1" 5441 range: "0-1" 5443 default: "0" 5445 type: "uinteger" 5446 definition: If a chapter is hidden (1), it SHOULD NOT be available to 5447 the user interface (but still to Control Tracks; see flag notes). (1 5448 bit) 5450 10.7.1.5.6. ChapterFlagEnabled Element 5452 name: "ChapterFlagEnabled" 5454 path: 5455 "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterFlagEnabled" 5457 id: "0x4598" 5459 minOccurs: "1" 5461 maxOccurs: "1" 5463 range: "0-1" 5465 default: "1" 5467 type: "uinteger" 5469 definition: Specify whether the chapter is enabled. It can be 5470 enabled/disabled by a Control Track. When disabled, the movie SHOULD 5471 skip all the content between the TimeStart and TimeEnd of this 5472 chapter (see flag notes). (1 bit) 5474 10.7.1.5.7. ChapterSegmentUID Element 5476 name: "ChapterSegmentUID" 5478 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterSegmentUID" 5480 id: "0x6E67" 5482 minOccurs: see implementation notes 5484 maxOccurs: "1" 5486 range: ">0" 5488 type: "binary" 5490 definition: The SegmentUID of another Segment to play during this 5491 chapter. 5493 implementation notes: 5495 +-----------+---------------------------------------------+ 5496 | attribute | note | 5497 +===========+=============================================+ 5498 | minOccurs | ChapterSegmentUID MUST be set (minOccurs=1) | 5499 | | if ChapterSegmentEditionUID is used. | 5500 +-----------+---------------------------------------------+ 5502 Table 40 5504 10.7.1.5.8. ChapterSegmentEditionUID Element 5506 name: "ChapterSegmentEditionUID" 5508 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterSegmentEdit 5509 ionUID" 5511 id: "0x6EBC" 5513 maxOccurs: "1" 5515 range: "not 0" 5517 type: "uinteger" 5519 definition: The EditionUID to play from the Segment linked in 5520 ChapterSegmentUID. If ChapterSegmentEditionUID is undeclared then no 5521 Edition of the linked Segment is used. 5523 10.7.1.5.9. ChapterPhysicalEquiv Element 5525 name: "ChapterPhysicalEquiv" 5527 path: 5528 "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterPhysicalEquiv" 5530 id: "0x63C3" 5532 maxOccurs: "1" 5534 type: "uinteger" 5536 definition: Specify the physical equivalent of this ChapterAtom like 5537 "DVD" (60) or "SIDE" (50), see complete list of values. 5539 10.7.1.5.10. ChapterTrack Element 5541 name: "ChapterTrack" 5542 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTrack" 5544 id: "0x8F" 5546 maxOccurs: "1" 5548 type: "master" 5550 definition: List of tracks on which the chapter applies. If this 5551 Element is not present, all tracks apply 5553 10.7.1.5.10.1. ChapterTrackUID Element 5555 name: "ChapterTrackUID" 5557 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTrack\Chapt 5558 erTrackUID" 5560 id: "0x89" 5562 minOccurs: "1" 5564 range: "not 0" 5566 type: "uinteger" 5568 definition: UID of the Track to apply this chapter too. In the 5569 absence of a control track, choosing this chapter will select the 5570 listed Tracks and deselect unlisted tracks. Absence of this Element 5571 indicates that the Chapter SHOULD be applied to any currently used 5572 Tracks. 5574 10.7.1.5.11. ChapterDisplay Element 5576 name: "ChapterDisplay" 5578 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay" 5580 id: "0x80" 5582 type: "master" 5584 definition: Contains all possible strings to use for the chapter 5585 display. 5587 10.7.1.5.11.1. ChapString Element 5589 name: "ChapString" 5591 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Cha 5592 pString" 5594 id: "0x85" 5596 minOccurs: "1" 5598 maxOccurs: "1" 5600 type: "utf-8" 5602 definition: Contains the string to use as the chapter atom. 5604 10.7.1.5.11.2. ChapLanguage Element 5606 name: "ChapLanguage" 5608 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Cha 5609 pLanguage" 5611 id: "0x437C" 5613 minOccurs: "1" 5615 default: "eng" 5617 type: "string" 5619 definition: The languages corresponding to the string, in the 5620 bibliographic ISO-639-2 form. This Element MUST be ignored if the 5621 ChapLanguageIETF Element is used within the same ChapterDisplay 5622 Element. 5624 10.7.1.5.11.3. ChapLanguageIETF Element 5626 name: "ChapLanguageIETF" 5628 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Cha 5629 pLanguageIETF" 5631 id: "0x437D" 5633 type: "string" 5634 minver: "4" 5636 definition: Specifies the language used in the ChapString according 5637 to BCP 47 and using the IANA Language Subtag Registry. If this 5638 Element is used, then any ChapLanguage Elements used in the same 5639 ChapterDisplay MUST be ignored. 5641 10.7.1.5.11.4. ChapCountry Element 5643 name: "ChapCountry" 5645 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Cha 5646 pCountry" 5648 id: "0x437E" 5650 type: "string" 5652 definition: The countries corresponding to the string, same 2 octets 5653 as in Internet domains. This Element MUST be ignored if the 5654 ChapLanguageIETF Element is used within the same ChapterDisplay 5655 Element. 5657 10.7.1.5.12. ChapProcess Element 5659 name: "ChapProcess" 5661 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess" 5663 id: "0x6944" 5665 type: "master" 5667 definition: Contains all the commands associated to the Atom. 5669 10.7.1.5.12.1. ChapProcessCodecID Element 5671 name: "ChapProcessCodecID" 5673 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapPr 5674 ocessCodecID" 5676 id: "0x6955" 5678 minOccurs: "1" 5680 maxOccurs: "1" 5681 default: "0" 5683 type: "uinteger" 5685 definition: Contains the type of the codec used for the processing. 5686 A value of 0 means native Matroska processing (to be defined), a 5687 value of 1 means the DVD command set is used. More codec IDs can be 5688 added later. 5690 10.7.1.5.12.2. ChapProcessPrivate Element 5692 name: "ChapProcessPrivate" 5694 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapPr 5695 ocessPrivate" 5697 id: "0x450D" 5699 maxOccurs: "1" 5701 type: "binary" 5703 definition: Some optional data attached to the ChapProcessCodecID 5704 information. For ChapProcessCodecID = 1, it is the "DVD level" 5705 equivalent. 5707 10.7.1.5.12.3. ChapProcessCommand Element 5709 name: "ChapProcessCommand" 5711 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapPr 5712 ocessCommand" 5714 id: "0x6911" 5716 type: "master" 5718 definition: Contains all the commands associated to the Atom. 5720 10.7.1.5.12.4. ChapProcessTime Element 5722 name: "ChapProcessTime" 5724 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapPr 5725 ocessCommand\ChapProcessTime" 5727 id: "0x6922" 5728 minOccurs: "1" 5730 maxOccurs: "1" 5732 type: "uinteger" 5734 definition: Defines when the process command SHOULD be handled 5736 restrictions: 5738 +-------+-------------------------------+ 5739 | value | label | 5740 +=======+===============================+ 5741 | "0" | during the whole chapter | 5742 +-------+-------------------------------+ 5743 | "1" | before starting playback | 5744 +-------+-------------------------------+ 5745 | "2" | after playback of the chapter | 5746 +-------+-------------------------------+ 5748 Table 41 5750 10.7.1.5.12.5. ChapProcessData Element 5752 name: "ChapProcessData" 5754 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapPr 5755 ocessCommand\ChapProcessData" 5757 id: "0x6933" 5759 minOccurs: "1" 5761 maxOccurs: "1" 5763 type: "binary" 5765 definition: Contains the command information. The data SHOULD be 5766 interpreted depending on the ChapProcessCodecID value. For 5767 ChapProcessCodecID = 1, the data correspond to the binary DVD cell 5768 pre/post commands. 5770 10.8. Tags Element 5772 name: "Tags" 5774 path: "\Segment\Tags" 5775 id: "0x1254C367" 5777 type: "master" 5779 definition: Element containing metadata describing Tracks, Editions, 5780 Chapters, Attachments, or the Segment as a whole. A list of valid 5781 tags can be found here. 5783 10.8.1. Tag Element 5785 name: "Tag" 5787 path: "\Segment\Tags\Tag" 5789 id: "0x7373" 5791 minOccurs: "1" 5793 type: "master" 5795 definition: A single metadata descriptor. 5797 10.8.1.1. Targets Element 5799 name: "Targets" 5801 path: "\Segment\Tags\Tag\Targets" 5803 id: "0x63C0" 5805 minOccurs: "1" 5807 maxOccurs: "1" 5809 type: "master" 5811 definition: Specifies which other elements the metadata represented 5812 by the Tag applies to. If empty or not present, then the Tag 5813 describes everything in the Segment. 5815 10.8.1.1.1. TargetTypeValue Element 5817 name: "TargetTypeValue" 5819 path: "\Segment\Tags\Tag\Targets\TargetTypeValue" 5821 id: "0x68CA" 5822 maxOccurs: "1" 5824 default: "50" 5826 type: "uinteger" 5828 definition: A number to indicate the logical level of the target. 5830 restrictions: 5832 +-------+--------------------------+--------------------------------+ 5833 | value | label | documentation | 5834 +=======+==========================+================================+ 5835 | "70" | COLLECTION | The highest hierarchical level | 5836 | | | that tags can describe. | 5837 +-------+--------------------------+--------------------------------+ 5838 | "60" | EDITION / ISSUE / | A list of lower levels grouped | 5839 | | VOLUME / OPUS / | together. | 5840 | | SEASON / SEQUEL | | 5841 +-------+--------------------------+--------------------------------+ 5842 | "50" | ALBUM / OPERA / | The most common grouping level | 5843 | | CONCERT / MOVIE / | of music and video (equals to | 5844 | | EPISODE / CONCERT | an episode for TV series). | 5845 +-------+--------------------------+--------------------------------+ 5846 | "40" | PART / SESSION | When an album or episode has | 5847 | | | different logical parts. | 5848 +-------+--------------------------+--------------------------------+ 5849 | "30" | TRACK / SONG / | The common parts of an album | 5850 | | CHAPTER | or movie. | 5851 +-------+--------------------------+--------------------------------+ 5852 | "20" | SUBTRACK / PART / | Corresponds to parts of a | 5853 | | MOVEMENT / SCENE | track for audio (like a | 5854 | | | movement). | 5855 +-------+--------------------------+--------------------------------+ 5856 | "10" | SHOT | The lowest hierarchy found in | 5857 | | | music or movies. | 5858 +-------+--------------------------+--------------------------------+ 5860 Table 42 5862 10.8.1.1.2. TargetType Element 5864 name: "TargetType" 5866 path: "\Segment\Tags\Tag\Targets\TargetType" 5868 id: "0x63CA" 5869 maxOccurs: "1" 5871 type: "string" 5873 definition: An informational string that can be used to display the 5874 logical level of the target like "ALBUM", "TRACK", "MOVIE", 5875 "CHAPTER", etc (see TargetType). 5877 restrictions: 5879 +--------------+------------+ 5880 | value | label | 5881 +==============+============+ 5882 | "COLLECTION" | COLLECTION | 5883 +--------------+------------+ 5884 | "EDITION" | EDITION | 5885 +--------------+------------+ 5886 | "ISSUE" | ISSUE | 5887 +--------------+------------+ 5888 | "VOLUME" | VOLUME | 5889 +--------------+------------+ 5890 | "OPUS" | OPUS | 5891 +--------------+------------+ 5892 | "SEASON" | SEASON | 5893 +--------------+------------+ 5894 | "SEQUEL" | SEQUEL | 5895 +--------------+------------+ 5896 | "ALBUM" | ALBUM | 5897 +--------------+------------+ 5898 | "OPERA" | OPERA | 5899 +--------------+------------+ 5900 | "CONCERT" | CONCERT | 5901 +--------------+------------+ 5902 | "MOVIE" | MOVIE | 5903 +--------------+------------+ 5904 | "EPISODE" | EPISODE | 5905 +--------------+------------+ 5906 | "PART" | PART | 5907 +--------------+------------+ 5908 | "SESSION" | SESSION | 5909 +--------------+------------+ 5910 | "TRACK" | TRACK | 5911 +--------------+------------+ 5912 | "SONG" | SONG | 5913 +--------------+------------+ 5914 | "CHAPTER" | CHAPTER | 5915 +--------------+------------+ 5916 | "SUBTRACK" | SUBTRACK | 5917 +--------------+------------+ 5918 | "PART" | PART | 5919 +--------------+------------+ 5920 | "MOVEMENT" | MOVEMENT | 5921 +--------------+------------+ 5922 | "SCENE" | SCENE | 5923 +--------------+------------+ 5924 | "SHOT" | SHOT | 5925 +--------------+------------+ 5927 Table 43 5929 10.8.1.1.3. TagTrackUID Element 5931 name: "TagTrackUID" 5933 path: "\Segment\Tags\Tag\Targets\TagTrackUID" 5935 id: "0x63C5" 5937 default: "0" 5939 type: "uinteger" 5941 definition: A unique ID to identify the Track(s) the tags belong to. 5942 If the value is 0 at this level, the tags apply to all tracks in the 5943 Segment. 5945 10.8.1.1.4. TagEditionUID Element 5947 name: "TagEditionUID" 5949 path: "\Segment\Tags\Tag\Targets\TagEditionUID" 5951 id: "0x63C9" 5953 default: "0" 5955 type: "uinteger" 5957 definition: A unique ID to identify the EditionEntry(s) the tags 5958 belong to. If the value is 0 at this level, the tags apply to all 5959 editions in the Segment. 5961 10.8.1.1.5. TagChapterUID Element 5963 name: "TagChapterUID" 5964 path: "\Segment\Tags\Tag\Targets\TagChapterUID" 5966 id: "0x63C4" 5968 default: "0" 5970 type: "uinteger" 5972 definition: A unique ID to identify the Chapter(s) the tags belong 5973 to. If the value is 0 at this level, the tags apply to all chapters 5974 in the Segment. 5976 10.8.1.1.6. TagAttachmentUID Element 5978 name: "TagAttachmentUID" 5980 path: "\Segment\Tags\Tag\Targets\TagAttachmentUID" 5982 id: "0x63C6" 5984 default: "0" 5986 type: "uinteger" 5988 definition: A unique ID to identify the Attachment(s) the tags belong 5989 to. If the value is 0 at this level, the tags apply to all the 5990 attachments in the Segment. 5992 10.8.1.2. SimpleTag Element 5994 name: "SimpleTag" 5996 path: "\Segment\Tags\Tag\+SimpleTag" 5998 id: "0x67C8" 6000 minOccurs: "1" 6002 type: "master" 6004 recursive: "1" 6006 definition: Contains general information about the target. 6008 10.8.1.2.1. TagName Element 6010 name: "TagName" 6011 path: "\Segment\Tags\Tag\+SimpleTag\TagName" 6013 id: "0x45A3" 6015 minOccurs: "1" 6017 maxOccurs: "1" 6019 type: "utf-8" 6021 definition: The name of the Tag that is going to be stored. 6023 10.8.1.2.2. TagLanguage Element 6025 name: "TagLanguage" 6027 path: "\Segment\Tags\Tag\+SimpleTag\TagLanguage" 6029 id: "0x447A" 6031 minOccurs: "1" 6033 maxOccurs: "1" 6035 default: "und" 6037 type: "string" 6039 definition: Specifies the language of the tag specified, in the 6040 Matroska languages form. This Element MUST be ignored if the 6041 TagLanguageIETF Element is used within the same SimpleTag Element. 6043 10.8.1.2.3. TagLanguageIETF Element 6045 name: "TagLanguageIETF" 6047 path: "\Segment\Tags\Tag\+SimpleTag\TagLanguageIETF" 6049 id: "0x447B" 6051 maxOccurs: "1" 6053 type: "string" 6055 minver: "4" 6056 definition: Specifies the language used in the TagString according to 6057 BCP 47 and using the IANA Language Subtag Registry. If this Element 6058 is used, then any TagLanguage Elements used in the same SimpleTag 6059 MUST be ignored. 6061 10.8.1.2.4. TagDefault Element 6063 name: "TagDefault" 6065 path: "\Segment\Tags\Tag\+SimpleTag\TagDefault" 6067 id: "0x4484" 6069 minOccurs: "1" 6071 maxOccurs: "1" 6073 range: "0-1" 6075 default: "1" 6077 type: "uinteger" 6079 definition: A boolean value to indicate if this is the default/ 6080 original language to use for the given tag. 6082 10.8.1.2.5. TagString Element 6084 name: "TagString" 6086 path: "\Segment\Tags\Tag\+SimpleTag\TagString" 6088 id: "0x4487" 6090 maxOccurs: "1" 6092 type: "utf-8" 6094 definition: The value of the Tag. 6096 10.8.1.2.6. TagBinary Element 6098 name: "TagBinary" 6100 path: "\Segment\Tags\Tag\+SimpleTag\TagBinary" 6102 id: "0x4485" 6103 maxOccurs: "1" 6105 type: "binary" 6107 definition: The values of the Tag if it is binary. Note that this 6108 cannot be used in the same SimpleTag as TagString. 6110 11. Matroska Element Ordering 6112 Except for the "EBML Header" and the "CRC-32 Element", the EBML 6113 specification does not require any particular storage order for 6114 "Elements". The Matroska specification however defines mandates and 6115 recommendations for ordering certain "Elements" in order to 6116 facilitate better playback, seeking, and editing efficiency. This 6117 section describes and offers rationale for ordering requirements and 6118 recommendations for Matroska. 6120 11.1. Top-Level Elements 6122 The "Info Element" is the only REQUIRED "Top-Level Element" in a 6123 Matroska file. To be playable, Matroska MUST also contain at least 6124 one "Tracks Element" and "Cluster Element". The first "Info Element" 6125 and the first "Tracks Element" MUST either be stored before the first 6126 "Cluster Element" or both SHALL be referenced by a "SeekHead Element" 6127 occurring before the first "Cluster Element". 6129 It is possible to edit a Matroska file after it has been created. 6130 For example, chapters, tags or attachments can be added. When new 6131 "Top-Level Elements" are added to a Matroska file, the "SeekHead" 6132 Element(s) MUST be updated so that the "SeekHead" Element(s) itemize 6133 the identity and position of all "Top-Level Elements". Editing, 6134 removing, or adding "Elements" to a Matroska file often requires that 6135 some existing "Elements" be voided or extended; therefore, it is 6136 RECOMMENDED to use "Void Elements" as padding in between "Top-Level 6137 Elements". 6139 11.2. CRC-32 6141 As noted by the EBML specification, if a "CRC-32 Element" is used 6142 then the "CRC-32 Element" MUST be the first ordered "Element" within 6143 its "Parent Element". The Matroska specification recommends that 6144 "CRC-32 Elements" SHOULD NOT be used as an immediate "Child Element" 6145 of the "Segment Element"; however all "Top-Level Elements" of an 6146 "EBML Document" SHOULD include a "CRC-32 Element" as a "Child 6147 Element". 6149 11.3. SeekHead 6151 If used, the first "SeekHead Element" SHOULD be the first non-"CRC-32 6152 Child Element" of the "Segment Element". If a second "SeekHead 6153 Element" is used, then the first "SeekHead Element" MUST reference 6154 the identity and position of the second "SeekHead". Additionally, 6155 the second "SeekHead Element" MUST only reference "Cluster" Elements 6156 and not any other "Top-Level Element" already contained within the 6157 first "SeekHead Element". The second "SeekHead Element" MAY be 6158 stored in any order relative to the other "Top-Level Elements." 6159 Whether one or two "SeekHead Element(s)" are used, the "SeekHead 6160 Element(s)" MUST collectively reference the identity and position of 6161 all "Top-Level Elements" except for the first "SeekHead Element". 6163 It is RECOMMENDED that the first "SeekHead Element" be followed by a 6164 "Void Element" to allow for the "SeekHead Element" to be expanded to 6165 cover new "Top-Level Elements" that could be added to the Matroska 6166 file, such as "Tags", "Chapters" and "Attachments Elements". 6168 11.4. Cues (index) 6170 The "Cues Element" is RECOMMENDED to optimize seeking access in 6171 Matroska. It is programmatically simpler to add the "Cues Element" 6172 after all "Cluster Elements" have been written because this does not 6173 require a prediction of how much space to reserve before writing the 6174 "Cluster Elements". However, storing the "Cues Element" before the 6175 "Cluster Elements" can provide some seeking advantages. If the "Cues 6176 Element" is present, then it SHOULD either be stored before the first 6177 "Cluster Element" or be referenced by a "SeekHead Element". 6179 11.5. Info 6181 The first "Info Element" SHOULD occur before the first "Tracks 6182 Element" and first "Cluster Element" except when referenced by a 6183 "SeekHead Element". 6185 11.6. Chapters Element 6187 The "Chapters Element" SHOULD be placed before the "Cluster 6188 Element(s)". The "Chapters Element" can be used during playback even 6189 if the user does not need to seek. It immediately gives the user 6190 information about what section is being read and what other sections 6191 are available. In the case of Ordered Chapters it RECOMMENDED to 6192 evaluate the logical linking even before playing. The "Chapters 6193 Element" SHOULD be placed before the first "Tracks Element" and after 6194 the first "Info Element". 6196 11.7. Attachments 6198 The "Attachments Element" is not intended to be used by default when 6199 playing the file, but could contain information relevant to the 6200 content, such as cover art or fonts. Cover art is useful even before 6201 the file is played and fonts could be needed before playback starts 6202 for initialization of subtitles. The "Attachments Element" MAY be 6203 placed before the first "Cluster Element"; however if the 6204 "Attachments Element" is likely to be edited, then it SHOULD be 6205 placed after the last "Cluster Element". 6207 11.8. Tags 6209 The "Tags Element" is most subject to changes after the file was 6210 originally created. For easier editing, the "Tags Element" SHOULD be 6211 placed at the end of the "Segment Element", even after the 6212 "Attachments Element". On the other hand, it is inconvenient to have 6213 to seek in the "Segment" for tags, especially for network streams. 6214 So it's better if the "Tags Element" is found early in the stream. 6215 When editing the "Tags Element", the original "Tags Element" at the 6216 beginning can be overwritten with a "Void Element" and a new "Tags 6217 Element" written at the end of the "Segment Element". The file size 6218 will only marginally change. 6220 11.9. Optimum layout from a muxer 6222 * SeekHead 6224 * Info 6226 * Tracks 6228 * Chapters 6230 * Attachments 6232 * Tags 6234 * Clusters 6236 * Cues 6238 11.10. Optimum layout after editing tags 6240 * SeekHead 6242 * Info 6243 * Tracks 6245 * Chapters 6247 * Attachments 6249 * Void 6251 * Clusters 6253 * Cues 6255 * Tags 6257 11.11. Optimum layout with Cues at the front 6259 * SeekHead 6261 * Info 6263 * Tracks 6265 * Chapters 6267 * Attachments 6269 * Tags 6271 * Cues 6273 * Clusters 6275 11.12. Cluster Timestamp 6277 The "Timestamp Element" MUST occur as in storage order before any 6278 "SimpleBlock", "BlockGroup", or "EncryptedBlock" within the "Cluster 6279 Element". 6281 12. Chapters 6283 12.1. Edition and Chapter Flags 6285 12.1.1. Chapter Flags 6287 Two "Chapter Flags" are defined to describe the behavior of the 6288 "ChapterAtom Element": "ChapterFlagHidden" and "ChapterFlagEnabled". 6290 If a "ChapterAtom Element" is the "Child Element" of another 6291 "ChapterAtom Element" with a "Chapter Flag" set to "true", then the 6292 "Child ChapterAtom Element" MUST be interpreted as having its same 6293 "Chapter Flag" set to "true". If a "ChapterAtom Element" is the 6294 "Child Element" of another "ChapterAtom Element" with a "Chapter 6295 Flag" set to "false" or if the "ChapterAtom Element" does not have a 6296 "ChapterAtom Element" as its "Parent Element", then it MUST be 6297 interpreted according to its own "Chapter Flag". 6299 As an example, consider a "Parent ChapterAtom Element" that has its 6300 "ChapterFlagHidden" set to "true" and also contains two child 6301 "ChapterAtoms", the first with "ChapterFlagHidden" set to "true" and 6302 the second with "ChapterFlagHidden" either set to "false" or not 6303 present at all (in which case the default value of the Element 6304 applies, which is "false"). Since the parent "ChapterAtom" has its 6305 "ChapterFlagHidden" set to "true" then all of its children 6306 "ChapterAtoms" MUST also be interpreted as if their 6307 "ChapterFlagHidden" is also set to "true". However, if a "Control 6308 Track" toggles the parent's "ChapterFlagHidden" flag to "false", then 6309 only the parent "ChapterAtom" and its second child "ChapterAtom" MUST 6310 be interpreted as if "ChapterFlagHidden" is set to "false". The 6311 first child "ChapterAtom" which has the "ChapterFlagHidden" flag set 6312 to "true" retains its value until its value is toggled to "false" by 6313 a "Control Track". 6315 12.1.2. Edition Flags 6317 Three "Edition Flags" are defined to describe the behavior of the 6318 "EditionEntry Element": "EditionFlagHidden", "EditionFlagDefault" and 6319 "EditionFlagOrdered". 6321 12.1.2.1. EditionFlagHidden 6323 The "EditionFlagHidden Flag" behaves similarly to the 6324 "ChapterFlagHidden Flag": if "EditionFlagHidden" is set to "true", 6325 its "Child ChapterAtoms Elements" MUST also be interpreted as if 6326 their "ChapterFlagHidden" is also set to "true", regardless of their 6327 own "ChapterFlagHidden Flags". If "EditionFlagHidden" is toggled by 6328 a "Control Track" to "false", the "ChapterFlagHidden Flags" of the 6329 "Child ChapterAtoms Elements" SHALL determine whether the 6330 "ChapterAtom" is hidden or not. 6332 12.1.2.2. EditionFlagDefault 6334 It is RECOMMENDED that no more than one "Edition" have an 6335 "EditionFlagDefault Flag" set to "true". The first "Edition" with 6336 both the "EditionFlagDefault Flag" set to "true" and the 6337 "EditionFlagHidden Flag" set to "false" is the Default Edition. When 6338 all "EditionFlagDefault Flags" are set to "false", then the first 6339 "Edition" with the "EditionFlagHidden Flag" set to "false" is the 6340 Default Edition. The Default Edition is the edition that should be 6341 used for playback by default. 6343 12.1.2.3. EditionFlagOrdered 6345 The "EditionFlagOrdered Flag" is a significant feature as it enables 6346 an "Edition" of "Ordered Chapters" which defines and arranges a 6347 virtual timeline rather than simply labeling points within the 6348 timeline. For example, with "Editions" of "Ordered Chapters" a 6349 single "Matroska file" can present multiple edits of a film without 6350 duplicating content. Alternatively if a videotape is digitized in 6351 full, one "Ordered Edition" could present the full content (including 6352 colorbars, countdown, slate, a feature presentation, and black 6353 frames), while another "Edition" of "Ordered Chapters" can use 6354 "Chapters" that only mark the intended presentation with the 6355 colorbars and other ancillary visual information excluded. If an 6356 "Edition" of "Ordered Chapters" is enabled then the "Matroska Player" 6357 MUST play those Chapters in their stored order from the timestamp 6358 marked in the "ChapterTimeStart Element" to the timestamp marked in 6359 to "ChapterTimeEnd Element". 6361 If the "EditionFlagOrdered Flag" is set to "false", "Simple Chapters" 6362 are used and only the "ChapterTimeStart" of a "Chapter" is used as 6363 chapter mark to jump to the predefined point in the timeline. With 6364 "Simple Chapters", a "Matroska Player" MUST ignore certain "Chapter 6365 Elements". All these elements are now informational only. 6367 The following list shows the different usage of "Chapter Elements" 6368 between an ordered and non-ordered "Edition". 6370 +------------------------------------+-------+------+ 6371 | Chapter elements / ordered Edition | False | True | 6372 +====================================+=======+======+ 6373 | ChapterUID | X | X | 6374 +------------------------------------+-------+------+ 6375 | ChapterStringUID | X | X | 6376 +------------------------------------+-------+------+ 6377 | ChapterTimeStart | X | X | 6378 +------------------------------------+-------+------+ 6379 | ChapterTimeEnd | - | X | 6380 +------------------------------------+-------+------+ 6381 | ChapterFlagHidden | X | X | 6382 +------------------------------------+-------+------+ 6383 | ChapterFlagEnabled | X | X | 6384 +------------------------------------+-------+------+ 6385 | ChapterSegmentUID | - | X | 6386 +------------------------------------+-------+------+ 6387 | ChapterSegmentEditionUID | - | X | 6388 +------------------------------------+-------+------+ 6389 | ChapterPhysicalEquiv | X | X | 6390 +------------------------------------+-------+------+ 6391 | ChapterTrack | - | X | 6392 +------------------------------------+-------+------+ 6393 | ChapterDisplay | X | X | 6394 +------------------------------------+-------+------+ 6395 | ChapProcess | - | X | 6396 +------------------------------------+-------+------+ 6398 Table 44 6400 Furthermore there are other EBML "Elements" which could be used if 6401 the "EditionFlagOrdered Flag" is set to "true". 6403 +----------------------------------+-------+------+ 6404 | Other elements / ordered Edition | False | True | 6405 +==================================+=======+======+ 6406 | Info/SegmentFamily | - | X | 6407 +----------------------------------+-------+------+ 6408 | Info/ChapterTranslate | - | X | 6409 +----------------------------------+-------+------+ 6410 | Track/TrackTranslate | - | X | 6411 +----------------------------------+-------+------+ 6413 Table 45 6415 These other "Elements" belong to the Matroska DVD menu system and are 6416 only used when the "ChapProcessCodecID Element" is set to 1. 6418 12.1.2.3.1. Ordered-Edition and Matroska Segment-Linking 6420 * Hard Linking: "Ordered-Chapters" supersedes the "Hard Linking". 6422 * Soft Linking: In this complex system "Ordered Chapters" are 6423 REQUIRED and a "Chapter CODEC" MUST interpret the "ChapProcess" of 6424 all chapters. 6426 * Medium Linking: "Ordered Chapters" are used in a normal way and 6427 can be combined with the "ChapterSegmentUID" element which 6428 establishes a link to another Matroska file/Segment. 6430 See the section on the Linked Segments (#linked-segments)) for more 6431 information about "Hard Linking", "Soft Linking" and "Medium 6432 Linking". 6434 12.2. Menu features 6436 The menu features are handled like a _chapter codec_. That means each 6437 codec has a type, some private data and some data in the chapters. 6439 The type of the menu system is defined by the "ChapProcessCodecID" 6440 parameter. For now only 2 values are supported : 0 matroska script, 6441 1 menu borrowed from the DVD. The private data depend on the type of 6442 menu system (stored in ChapProcessPrivate), idem for the data in the 6443 chapters (stored in ChapProcessData). 6445 12.2.1. Matroska Script (0) 6447 This is the case when "ChapProcessCodecID" = 0. This is a script 6448 language build for Matroska purposes. The inspiration comes from 6449 ActionScript, javascript and other similar scripting languages. The 6450 commands are stored as text commands, in UTF-8. The syntax is C 6451 like, with commands spanned on many lines, each terminating with a 6452 ";". You can also include comments at the end of lines with "//" or 6453 comment many lines using "/* */". The scripts are stored in 6454 ChapProcessData. For the moment ChapProcessPrivate is not used. 6456 The one and only command existing for the moment is "GotoAndPlay( 6457 ChapterUID );". As the same suggests, it means that when this 6458 command is encountered, the "Matroska Player" SHOULD jump to the 6459 "Chapter" specified by the UID and play it. 6461 12.2.2. DVD menu (1) 6463 This is the case when "ChapProcessCodecID" = 1. Each level of a 6464 chapter corresponds to a logical level in the DVD system that is 6465 stored in the first octet of the ChapProcessPrivate. This DVD 6466 hierarchy is as follows: 6468 +--------------------+------+-----------+----------+-------------+ 6469 | ChapProcessPrivate | DVD | Hierarchy | Commands | Comment | 6470 | | Name | | Possible | | 6471 +====================+======+===========+==========+=============+ 6472 | 0x30 | SS | DVD | - | First Play, | 6473 | | | domain | | Video | 6474 | | | | | Manager, | 6475 | | | | | Video Title | 6476 +--------------------+------+-----------+----------+-------------+ 6477 | 0x2A | LU | Language | - | Contains | 6478 | | | Unit | | only PGCs | 6479 +--------------------+------+-----------+----------+-------------+ 6480 | 0x28 | TT | Title | - | Contains | 6481 | | | | | only PGCs | 6482 +--------------------+------+-----------+----------+-------------+ 6483 | 0x20 | PGC | Program | * | | 6484 | | | Group | | | 6485 | | | Chain | | | 6486 | | | (PGC) | | | 6487 +--------------------+------+-----------+----------+-------------+ 6488 | 0x18 | PG | Program 1 | - | | 6489 | | | / Program | | | 6490 | | | 2 / | | | 6491 | | | Program 3 | | | 6492 +--------------------+------+-----------+----------+-------------+ 6493 | 0x10 | PTT | Part Of | - | Equivalent | 6494 | | | Title 1 / | | to the | 6495 | | | Part Of | | chapters on | 6496 | | | Title 2 | | the sleeve. | 6497 +--------------------+------+-----------+----------+-------------+ 6498 | 0x08 | CN | Cell 1 / | - | | 6499 | | | Cell 2 / | | | 6500 | | | Cell 3 / | | | 6501 | | | Cell 4 / | | | 6502 | | | Cell 5 / | | | 6503 | | | Cell 6 | | | 6504 +--------------------+------+-----------+----------+-------------+ 6506 Table 46 6508 You can also recover wether a Segment is a Video Manager (VMG), Video 6509 Title Set (VTS) or Video Title Set Menu (VTSM) from the 6510 ChapterTranslateID element found in the Segment Info. This field 6511 uses 2 octets as follows: 6513 1. Domain Type: 0 for VMG, the domain number for VTS and VTSM 6515 2. Domain Value: 0 for VMG and VTSM, 1 for the VTS source. 6517 For instance, the menu part from VTS_01_0.VOB would be coded [1,0] 6518 and the content part from VTS_02_3.VOB would be [2,1]. The VMG is 6519 always [0,0] 6521 The following octets of ChapProcessPrivate are as follows: 6523 +---------+------+-------------------------------------------------+ 6524 | Octet 1 | DVD | Following Octets | 6525 | | Name | | 6526 +=========+======+=================================================+ 6527 | 0x30 | SS | Domain name code (1: 0x00= First play, 0xC0= | 6528 | | | VMG, 0x40= VTSM, 0x80= VTS) + VTS(M) number (2) | 6529 +---------+------+-------------------------------------------------+ 6530 | 0x2A | LU | Language code (2) + Language extension (1) | 6531 +---------+------+-------------------------------------------------+ 6532 | 0x28 | TT | global Title number (2) + corresponding TTN of | 6533 | | | the VTS (1) | 6534 +---------+------+-------------------------------------------------+ 6535 | 0x20 | PGC | PGC number (2) + Playback Type (1) + Disabled | 6536 | | | User Operations (4) | 6537 +---------+------+-------------------------------------------------+ 6538 | 0x18 | PG | Program number (2) | 6539 +---------+------+-------------------------------------------------+ 6540 | 0x10 | PTT | PTT-chapter number (1) | 6541 +---------+------+-------------------------------------------------+ 6542 | 0x08 | CN | Cell number [VOB ID(2)][Cell ID(1)][Angle | 6543 | | | Num(1)] | 6544 +---------+------+-------------------------------------------------+ 6546 Table 47 6548 If the level specified in ChapProcessPrivate is a PGC (0x20), there 6549 is an octet called the Playback Type, specifying the kind of PGC 6550 defined: 6552 * 0x00: entry only/basic PGC 6554 * 0x82: Title+Entry Menu (only found in the Video Manager domain) 6555 * 0x83: Root Menu (only found in the VTSM domain) 6557 * 0x84: Subpicture Menu (only found in the VTSM domain) 6559 * 0x85: Audio Menu (only found in the VTSM domain) 6561 * 0x86: Angle Menu (only found in the VTSM domain) 6563 * 0x87: Chapter Menu (only found in the VTSM domain) 6565 The next 4 following octets correspond to the User Operation flags 6566 (http://dvd.sourceforge.net/dvdinfo/uops.html) in the standard PGC. 6567 When a bit is set, the command SHOULD be disabled. 6569 ChapProcessData contains the pre/post/cell commands in binary format 6570 as there are stored on a DVD. There is just an octet preceding these 6571 data to specify the number of commands in the element. As follows: 6572 [# of commands(1)][command 1 (8)][command 2 (8)][command 3 (8)]. 6574 More information on the DVD commands and format on DVD-replica 6575 (http://www.dvd-replica.com/DVD/), where we got most of the info 6576 about it. You can also get information on DVD from the DVDinfo 6577 project (http://dvd.sourceforge.net/dvdinfo/). 6579 12.3. Example 1 : basic chaptering 6581 In this example a movie is split in different chapters. It could 6582 also just be an audio file (album) on which each track corresponds to 6583 a chapter. 6585 * 00000ms - 05000ms : Intro 6587 * 05000ms - 25000ms : Before the crime 6589 * 25000ms - 27500ms : The crime 6591 * 27500ms - 38000ms : The killer arrested 6593 * 38000ms - 43000ms : Credits 6595 This would translate in the following matroska form : 6597 6598 6599 16603393396715046047 6600 6601 1193046 6602 0 6603 5000000000 6604 6605 Intro 6606 eng 6607 6608 0 6609 1 6610 6611 6612 2311527 6613 5000000000 6614 25000000000 6615 6616 Before the crime 6617 eng 6618 6619 6620 Avant le crime 6621 fra 6622 6623 0 6624 1 6625 6626 6627 3430008 6628 25000000000 6629 27500000000 6630 6631 The crime 6632 eng 6633 6634 6635 Le crime 6636 fra 6637 6638 0 6639 1 6640 6641 6642 4548489 6643 27500000000 6644 38000000000 6645 6646 After the crime 6647 eng 6648 6649 6650 Après le crime 6651 fra 6652 6653 0 6654 1 6655 6656 6657 5666960 6658 38000000000 6659 43000000000 6660 6661 Credits 6662 eng 6663 6664 6665 Générique 6666 fra 6667 6668 0 6669 1 6670 6671 0 6672 0 6673 6674 6676 12.4. Example 2 : nested chapters 6678 In this example an (existing) album is split into different chapters, 6679 and one of them contain another splitting. 6681 12.4.1. The Micronauts "Bleep To Bleep" 6683 * 00:00 - 12:28 : Baby Wants To Bleep/Rock 6685 - 00:00 - 04:38 : Baby wants to bleep (pt.1) 6687 - 04:38 - 07:12 : Baby wants to rock 6689 - 07:12 - 10:33 : Baby wants to bleep (pt.2) 6691 - 10:33 - 12:28 : Baby wants to bleep (pt.3) 6693 * 12:30 - 19:38 : Bleeper_O+2 6695 * 19:40 - 22:20 : Baby wants to bleep (pt.4) 6697 * 22:22 - 25:18 : Bleep to bleep 6698 * 25:20 - 33:35 : Baby wants to bleep (k) 6700 * 33:37 - 44:28 : Bleeper 6702 6703 6704 1281690858003401414 6705 6706 1 6707 0 6708 748000000 6709 6710 Baby wants to Bleep/Rock 6711 eng 6712 6713 6714 2 6715 0 6716 278000000 6717 6718 Baby wants to bleep (pt.1) 6719 eng 6720 6721 0 6722 1 6723 6724 6725 3 6726 278000000 6727 432000000 6728 6729 Baby wants to rock 6730 eng 6731 6732 0 6733 1 6734 6735 6736 4 6737 432000000 6738 633000000 6739 6740 Baby wants to bleep (pt.2) 6741 eng 6742 6743 0 6744 1 6745 6746 6747 5 6748 633000000 6749 748000000 6750 6751 Baby wants to bleep (pt.3) 6752 eng 6753 6754 0 6755 1 6756 6757 0 6758 1 6759 6760 6761 6 6762 750000000 6763 1178500000 6764 6765 Bleeper_O+2 6766 eng 6767 6768 0 6769 1 6770 6771 6772 7 6773 1180500000 6774 1340000000 6775 6776 Baby wants to bleep (pt.4) 6777 eng 6778 6779 0 6780 1 6781 6782 6783 8 6784 1342000000 6785 1518000000 6786 6787 Bleep to bleep 6788 eng 6789 6790 0 6791 1 6792 6793 6794 9 6795 1520000000 6796 2015000000 6797 6798 Baby wants to bleep (k) 6799 eng 6800 6801 0 6802 1 6803 6804 6805 10 6806 2017000000 6807 2668000000 6808 6809 Bleeper 6810 eng 6811 6812 0 6813 1 6814 6815 0 6816 0 6817 6818 6820 13. Attachments 6822 Matroska supports storage of related files and data in the 6823 "Attachments Element" (a "Top-Level Element"). "Attachment Elements" 6824 can be used to store related cover art, font files, transcripts, 6825 reports, error recovery files, picture or text-based annotations, 6826 copies of specifications, or other ancillary files related to the 6827 "Segment". 6829 "Matroska Readers" MUST NOT execute files stored as "Attachment 6830 Elements". 6832 13.1. Cover Art 6834 This section defines a set of guidelines for the storage of cover art 6835 in Matroska files. A "Matroska Reader" MAY use embedded cover art to 6836 display a representational still-image depiction of the multimedia 6837 contents of the Matroska file. 6839 Only JPEG and PNG image formats SHOULD be used for cover art 6840 pictures. 6842 There can be two different covers for a movie/album: a portrait style 6843 (e.g., a DVD case) and a landscape style (e.g., a wide banner ad). 6845 There can be two versions of the same cover, the "normal cover" and 6846 the "small cover". The dimension of the "normal cover" SHOULD be 600 6847 pixels on the smallest side (for example, 960x600 for landscape, 6848 600x800 for portrait, or 600x600 for square). The dimension of the 6849 "small cover" SHOULD be 120 pixels on the smallest side (for example, 6850 192x120 or 120x160). 6852 Versions of cover art can be differentiated by the filename, which is 6853 stored in the "FileName Element". The default filename of the 6854 "normal cover" in square or portrait mode is "cover.(jpg|png)". When 6855 stored, the "normal cover" SHOULD be the first Attachment in storage 6856 order. The "small cover" SHOULD be prefixed with "small_", such as 6857 "small_cover.(jpg|png)". The landscape variant SHOULD be suffixed 6858 with "_land", such as "cover_land.(jpg|png)". The filenames are case 6859 sensitive. 6861 The following table provides examples of file names for cover art in 6862 Attachments. 6864 +----------------------+-------------------+-----------------+ 6865 | FileName | Image Orientation | Pixel Length of | 6866 | | | Smallest Side | 6867 +======================+===================+=================+ 6868 | cover.jpg | Portrait or | 600 | 6869 | | square | | 6870 +----------------------+-------------------+-----------------+ 6871 | small_cover.png | Portrait or | 120 | 6872 | | square | | 6873 +----------------------+-------------------+-----------------+ 6874 | cover_land.png | Landscape | 600 | 6875 +----------------------+-------------------+-----------------+ 6876 | small_cover_land.jpg | Landscape | 120 | 6877 +----------------------+-------------------+-----------------+ 6879 Table 48 6881 14. Cues 6883 The "Cues Element" provides an index of certain "Cluster Elements" to 6884 allow for optimized seeking to absolute timestamps within the 6885 "Segment". The "Cues Element" contains one or many "CuePoint 6886 Elements" which each MUST reference an absolute timestamp (via the 6887 "CueTime Element"), a "Track" (via the "CueTrack Element"), and a 6888 "Segment Position" (via the "CueClusterPosition Element"). 6889 Additional non-mandated Elements are part of the "CuePoint Element" 6890 such as "CueDuration", "CueRelativePosition", "CueCodecState" and 6891 others which provide any "Matroska Reader" with additional 6892 information to use in the optimization of seeking performance. 6894 14.1. Recommendations 6896 The following recommendations are provided to optimize Matroska 6897 performance. 6899 * Unless Matroska is used as a live stream, it SHOULD contain a 6900 "Cues Element". 6902 * For each video track, each keyframe SHOULD be referenced by a 6903 "CuePoint Element". 6905 * It is RECOMMENDED to not reference non-keyframes of video tracks 6906 in "Cues" unless it references a "Cluster Element" which contains 6907 a "CodecState Element" but no keyframes. 6909 * For each subtitle track present, each subtitle frame SHOULD be 6910 referenced by a "CuePoint Element" with a "CueDuration Element". 6912 * References to audio tracks MAY be skipped in "CuePoint Elements" 6913 if a video track is present. When included the "CuePoint 6914 Elements" SHOULD reference audio keyframes at most once every 500 6915 milliseconds. 6917 * If the referenced frame is not stored within the first 6918 "SimpleBlock" or first "BlockGroup" within its "Cluster Element", 6919 then the "CueRelativePosition Element" SHOULD be written to 6920 reference where in the "Cluster" the reference frame is stored. 6922 * If a "CuePoint Element" references "Cluster Element" that includes 6923 a "CodecState Element", then that "CuePoint Element" MUST use a 6924 "CueCodecState Element". 6926 * "CuePoint Elements" SHOULD be numerically sorted in storage order 6927 by the value of the "CueTime Element". 6929 15. Matroska Streaming 6931 In Matroska, there are two kinds of streaming: file access and 6932 livestreaming. 6934 15.1. File Access 6936 File access can simply be reading a file located on your computer, 6937 but also includes accessing a file from an HTTP (web) server or CIFS 6938 (Windows share) server. These protocols are usually safe from 6939 reading errors and seeking in the stream is possible. However, when 6940 a file is stored far away or on a slow server, seeking can be an 6941 expensive operation and SHOULD be avoided. The following guidelines, 6942 when followed, help reduce the number of seeking operations for 6943 regular playback and also have the playback start quickly without a 6944 lot of data needed to read first (like a "Cues Element", "Attachment 6945 Element" or "SeekHead Element"). 6947 Matroska, having a small overhead, is well suited for storing music/ 6948 videos on file servers without a big impact on the bandwidth used. 6949 Matroska does not require the index to be loaded before playing, 6950 which allows playback to start very quickly. The index can be loaded 6951 only when seeking is requested the first time. 6953 15.2. Livestreaming 6955 Livestreaming is the equivalent of television broadcasting on the 6956 internet. There are 2 families of servers for livestreaming: RTP/ 6957 RTSP and HTTP. Matroska is not meant to be used over RTP. RTP 6958 already has timing and channel mechanisms that would be wasted if 6959 doubled in Matroska. Additionally, having the same information at 6960 the RTP and Matroska level would be a source of confusion if they do 6961 not match. Livestreaming of Matroska over HTTP (or any other plain 6962 protocol based on TCP) is possible. 6964 A live Matroska stream is different from a file because it usually 6965 has no known end (only ending when the client disconnects). For 6966 this, all bits of the "size" portion of the "Segment Element" MUST be 6967 set to 1. Another option is to concatenate "Segment Elements" with 6968 known sizes, one after the other. This solution allows a change of 6969 codec/resolution between each segment. For example, this allows for 6970 a switch between 4:3 and 16:9 in a television program. 6972 When "Segment Elements" are continuous, certain "Elements", like 6973 "MetaSeek", "Cues", "Chapters", and "Attachments", MUST NOT be used. 6975 It is possible for a "Matroska Player" to detect that a stream is not 6976 seekable. If the stream has neither a "MetaSeek" list or a "Cues" 6977 list at the beginning of the stream, it SHOULD be considered non- 6978 seekable. Even though it is possible to seek blindly forward in the 6979 stream, it is NOT RECOMMENDED. 6981 In the context of live radio or web TV, it is possible to "tag" the 6982 content while it is playing. The "Tags Element" can be placed 6983 between "Clusters" each time it is necessary. In that case, the new 6984 "Tags Element" MUST reset the previously encountered "Tags Elements" 6985 and use the new values instead. 6987 16. Menu Specifications 6989 This document is a _draft of the Menu system_ that will be the 6990 default one in "Matroska". As it will just be composed of a Control 6991 Track, it will be seen as a "codec" and could be replaced later by 6992 something else if needed. 6994 A menu is like what you see on DVDs, when you have some screens to 6995 select the audio format, subtitles or scene selection. 6997 16.1. Requirements 6999 What we'll try to have is a system that can do almost everything done 7000 on a DVD, or more, or better, or drop the unused features if 7001 necessary. 7003 As the name suggests, a Control Track is a track that can control the 7004 playback of the file and/or all the playback features. To make it as 7005 simple as possible for "Matroska Players", the Control Track will 7006 just give orders to the "Matroska Player" and get the actions 7007 associated with the highlights/hotspots. 7009 16.1.1. Highlights/Hotspots 7011 A highlight is basically a rectangle/key associated with an action 7012 UID. When that rectangle/key is activated, the "Matroska Player" 7013 send the UID of the action to the Control Track handler (codec). The 7014 fact that it can also be a key means that even for audio only files, 7015 a keyboard shortcut or button panel could be used for menus. But in 7016 that case, the hotspot will have to be associated with a name to 7017 display. 7019 This highlight is sent from the Control Track to the "Matroska 7020 Player". Then the "Matroska Player" has to handle that highlight 7021 until it's deactivated (see Playback Features (#playback-features)). 7023 The highlight contains a UID of the action, a displayable name (UTF- 7024 8), an associated key (list of keys to be defined, probably 7025 up/down/left/right/select), a screen position/range and an image to 7026 display. The image will be displayed either when the user place the 7027 mouse over the rectangle (or any other shape), or when an option of 7028 the screen is selected (not activated). There could be a second 7029 image used when the option is activated. And there could be a third 7030 image that can serve as background. This way you could have a still 7031 image (like in some DVDs) for the menu and behind that image blank 7032 video (small bitrate). 7034 When a highlight is activated by the user, the "Matroska Player" has 7035 to send the UID of the action to the Control Track. Then the Control 7036 Track codec will handle the action and possibly give new orders to 7037 the "Matroska Player". 7039 The format used for storing images SHOULD be extensible. For the 7040 moment we'll use PNG and BMP, both with alpha channel. 7042 16.1.2. Playback features 7044 All the following features will be sent from the Control Track to the 7045 "Matroska Player" : 7047 * Jump to chapter (UID, prev, next, number) 7049 * Disable all tracks of a kind (audio, video, subtitle) 7051 * Enable track UID (the kind doesn't matter) 7053 * Define/Disable a highlight 7055 * Enable/Disable jumping 7057 * Enable/Disable track selection of a kind 7059 * Select Edition ID (see chapters) 7061 * Pause playback 7063 * Stop playback 7065 * Enable/Disable a Chapter UID 7067 * Hide/Unhide a Chapter UID 7069 All the actions will be written in a normal Matroska track, with a 7070 timestamp. A "Menu Frame" SHOULD be able to contain more that one 7071 action/highlight for a given timestamp. (to be determined, EBML 7072 format structure) 7074 16.1.3. Player requirements 7076 Some "Matroska Players" might not support the control track. That 7077 mean they will play the active/looped parts as part of the data. So 7078 I suggest putting the active/looped parts of a movie at the end of a 7079 movie. When a Menu-aware "Matroska Player" encounter the default 7080 Control Track of a "Matroska" file, the first order SHOULD be to jump 7081 at the start of the active/looped part of the movie. 7083 16.2. Working Graph 7085 Matroska Source file -> Control Track <-> Player. 7086 -> other tracks -> rendered 7088 17. Unknown elements 7090 Matroska is based upon the principle that a reading application does 7091 not have to support 100% of the specifications in order to be able to 7092 play the file. A Matroska file therefore contains version indicators 7093 that tell a reading application what to expect. 7095 It is possible and valid to have the version fields indicate that the 7096 file contains Matroska "Elements" from a higher specification version 7097 number while signaling that a reading application MUST only support a 7098 lower version number properly in order to play it back (possibly with 7099 a reduced feature set). For example, a reading application 7100 supporting at least Matroska version "V" reading a file whose 7101 "DocTypeReadVersion" field is equal to or lower than "V" MUST skip 7102 Matroska/EBML "Elements" it encounters but does not know about if 7103 that unknown element fits into the size constraints set by the 7104 current "Parent Element". 7106 18. Default Values 7108 The default value of an "Element" is assumed when not present in the 7109 data stream. It is assumed only in the scope of its "Parent 7110 Element". For example, the "Language Element" is in the scope of the 7111 "Track Element". If the "Parent Element" is not present or assumed, 7112 then the "Child Element" cannot be assumed. 7114 19. DefaultDecodedFieldDuration 7116 The "DefaultDecodedFieldDuration Element" can signal to the 7117 displaying application how often fields of a video sequence will be 7118 available for displaying. It can be used for both interlaced and 7119 progressive content. If the video sequence is signaled as 7120 interlaced, then the period between two successive fields at the 7121 output of the decoding process equals "DefaultDecodedFieldDuration". 7123 For video sequences signaled as progressive, it is twice the value of 7124 "DefaultDecodedFieldDuration". 7126 These values are valid at the end of the decoding process before 7127 post-processing (such as deinterlacing or inverse telecine) is 7128 applied. 7130 Examples: 7132 * Blu-ray movie: 1000000000ns/(48/1.001) = 20854167ns 7134 * PAL broadcast/DVD: 1000000000ns/(50/1.000) = 20000000ns 7136 * N/ATSC broadcast: 1000000000ns/(60/1.001) = 16683333ns 7138 * hard-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (60 7139 encoded interlaced fields per second) 7141 * soft-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (48 7142 encoded interlaced fields per second, with "repeat_first_field = 7143 1") 7145 20. Encryption 7147 Encryption in Matroska is designed in a very generic style to allow 7148 people to implement whatever form of encryption is best for them. It 7149 is possible to use the encryption framework in Matroska as a type of 7150 DRM (Digital Rights Management). 7152 Because encryption occurs within the "Block Element", it is possible 7153 to manipulate encrypted streams without decrypting them. The streams 7154 could potentially be copied, deleted, cut, appended, or any number of 7155 other possible editing techniques without decryption. The data can 7156 be used without having to expose it or go through the decrypting 7157 process. 7159 Encryption can also be layered within Matroska. This means that two 7160 completely different types of encryption can be used, requiring two 7161 separate keys to be able to decrypt a stream. 7163 Encryption information is stored in the "ContentEncodings Element" 7164 under the "ContentEncryption Element". 7166 21. Image Presentation 7167 21.1. Cropping 7169 The "PixelCrop Elements" ("PixelCropTop", "PixelCropBottom", 7170 "PixelCropRight" and "PixelCropLeft") indicate when and by how much 7171 encoded videos frames SHOULD be cropped for display. These Elements 7172 allow edges of the frame that are not intended for display, such as 7173 the sprockets of a full-frame film scan or the VANC area of a 7174 digitized analog videotape, to be stored but hidden. "PixelCropTop" 7175 and "PixelCropBottom" store an integer of how many rows of pixels 7176 SHOULD be cropped from the top and bottom of the image 7177 (respectively). "PixelCropLeft" and "PixelCropRight" store an 7178 integer of how many columns of pixels SHOULD be cropped from the left 7179 and right of the image (respectively). For example, a pillar-boxed 7180 video that stores a 1440x1080 visual image within the center of a 7181 padded 1920x1080 encoded image MAY set both "PixelCropLeft" and 7182 "PixelCropRight" to "240", so that a "Matroska Player" SHOULD crop 7183 off 240 columns of pixels from the left and right of the encoded 7184 image to present the image with the pillar-boxes hidden. 7186 21.2. Rotation 7188 The ProjectionPoseRoll Element (see Section 10.4.1.31.20.5) can be 7189 used to indicate that the image from the associated video track 7190 SHOULD be rotated for presentation. For instance, the following 7191 representation of the Projection Element Section 10.4.1.31.20) and 7192 the ProjectionPoseRoll Element represents a video track where the 7193 image SHOULD be presentation with a 90 degree counter-clockwise 7194 rotation. 7196 7197 90 7198 7200 22. Matroska versioning 7202 The "EBML Header" of each Matroska document informs the reading 7203 application on what version of Matroska to expect. The "Elements" 7204 within "EBML Header" with jurisdiction over this information are 7205 "DocTypeVersion" and "DocTypeReadVersion". 7207 "DocTypeVersion" MUST be equal to or greater than the highest 7208 Matroska version number of any "Element" present in the Matroska 7209 file. For example, a file using the "SimpleBlock Element" MUST have 7210 a "DocTypeVersion" equal to or greater than 2. A file containing 7211 "CueRelativePosition" Elements MUST have a "DocTypeVersion" equal to 7212 or greater than 4. 7214 The "DocTypeReadVersion" MUST contain the minimum version number that 7215 a reading application can minimally support in order to play the file 7216 back -- optionally with a reduced feature set. For example, if a 7217 file contains only "Elements" of version 2 or lower except for 7218 "CueRelativePosition" (which is a version 4 Matroska "Element"), then 7219 "DocTypeReadVersion" SHOULD still be set to 2 and not 4 because 7220 evaluating "CueRelativePosition" is not necessary for standard 7221 playback -- it makes seeking more precise if used. 7223 "DocTypeVersion" MUST always be equal to or greater than 7224 "DocTypeReadVersion". 7226 A reading application supporting Matroska version "V" MUST NOT refuse 7227 to read an application with "DocReadTypeVersion" equal to or lower 7228 than "V" even if "DocTypeVersion" is greater than "V". See also the 7229 note about Unknown Elements (#unknown-elements). 7231 23. MIME Types 7233 There is no IETF endorsed MIME type for Matroska files. These 7234 definitions can be used: 7236 * .mka : Matroska audio "audio/x-matroska" 7238 * .mkv : Matroska video "video/x-matroska" 7240 * .mk3d : Matroska 3D video "video/x-matroska-3d" 7242 24. Segment Position 7244 The "Segment Position" of an "Element" refers to the position of the 7245 first octet of the "Element ID" of that "Element", measured in 7246 octets, from the beginning of the "Element Data" section of the 7247 containing "Segment Element". In other words, the "Segment Position" 7248 of an "Element" is the distance in octets from the beginning of its 7249 containing "Segment Element" minus the size of the "Element ID" and 7250 "Element Data Size" of that "Segment Element". The "Segment 7251 Position" of the first "Child Element" of the "Segment Element" is 0. 7252 An "Element" which is not stored within a "Segment Element", such as 7253 the "Elements" of the "EBML Header", do not have a "Segment 7254 Position". 7256 24.1. Segment Position Exception 7258 "Elements" that are defined to store a "Segment Position" MAY define 7259 reserved values to indicate a special meaning. 7261 24.2. Example of Segment Position 7263 This table presents an example of "Segment Position" by showing a 7264 hexadecimal representation of a very small Matroska file with labels 7265 to show the offsets in octets. The file contains a "Segment Element" 7266 with an "Element ID" of "0x18538067" and a "MuxingApp Element" with 7267 an "Element ID" of "0x4D80". 7269 0 1 2 7270 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 7271 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 7272 0 |1A|45|DF|A3|8B|42|82|88|6D|61|74|72|6F|73|6B|61|18|53|80|67| 7273 20 |93|15|49|A9|66|8E|4D|80|84|69|65|74|66|57|41|84|69|65|74|66| 7275 In the above example, the "Element ID" of the "Segment Element" is 7276 stored at offset 16, the "Element Data Size" of the "Segment Element" 7277 is stored at offset 20, and the "Element Data" of the "Segment 7278 Element" is stored at offset 21. 7280 The "MuxingApp Element" is stored at offset 26. Since the "Segment 7281 Position" of an "Element" is calculated by subtracting the position 7282 of the "Element Data" of the containing "Segment Element" from the 7283 position of that "Element", the "Segment Position" of "MuxingApp 7284 Element" in the above example is "26 - 21" or "5". 7286 25. Linked Segments 7288 Matroska provides several methods to link two or many "Segment 7289 Elements" together to create a "Linked Segment". A "Linked Segment" 7290 is a set of multiple "Segments" related together into a single 7291 presentation by using Hard Linking, Medium Linking, or Soft Linking. 7292 All "Segments" within a "Linked Segment" MUST utilize the same track 7293 numbers and timescale. All "Segments" within a "Linked Segment" MUST 7294 be stored within the same directory. All "Segments" within a "Linked 7295 Segment" MUST store a "SegmentUID". 7297 25.1. Hard Linking 7299 Hard Linking (also called splitting) is the process of creating a 7300 "Linked Segment" by relating multiple "Segment Elements" using the 7301 "NextUID" and "PrevUID" Elements. Within a "Linked Segment", the 7302 timestamps of each "Segment" MUST follow consecutively in linking 7303 order. With Hard Linking, the chapters of any "Segment" within the 7304 "Linked Segment" MUST only reference the current "Segment". With 7305 Hard Linking, the "NextUID" and "PrevUID" MUST reference the 7306 respective "SegmentUID" values of the next and previous "Segments". 7307 The first "Segment" of a "Linked Segment" SHOULD have a "NextUID 7308 Element" and MUST NOT have a "PrevUID Element". The last "Segment" 7309 of a "Linked Segment" SHOULD have a "PrevUID Element" and MUST NOT 7310 have a "NextUID Element". The middle "Segments" of a "Linked 7311 Segment" SHOULD have both a "NextUID Element" and a "PrevUID 7312 Element". 7314 In a chain of "Linked Segments" the "NextUID" always takes precedence 7315 over the "PrevUID". So if SegmentA has a NextUID to SegmentB and 7316 SegmentB has a PrevUID to SegmentC, the link to use is SegmentA to 7317 SegmentB. If SegmentB has a PrevUID to SegmentA but SegmentA has no 7318 NextUID, then the Matroska Player MAY consider these two Segments 7319 linked as SegmentA followed by SegmentB. 7321 As an example, three "Segments" can be Hard Linked as a "Linked 7322 Segment" through cross-referencing each other with "SegmentUID", 7323 "PrevUID", and "NextUID", as in this table. 7325 +------------+----------------+------------------+------------------+ 7326 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7327 +============+================+==================+==================+ 7328 |"start.mkv" |71000c23cd310998| n/a | a77b3598941cb803 | 7329 | |53fbc94dd984a5dd| | eac0fcdafe44fac9 | 7330 +------------+----------------+------------------+------------------+ 7331 |"middle.mkv"|a77b3598941cb803| 71000c23cd310998 | 6c92285fa6d3e827 | 7332 | |eac0fcdafe44fac9| 53fbc94dd984a5dd | b198d120ea3ac674 | 7333 +------------+----------------+------------------+------------------+ 7334 | "end.mkv" |6c92285fa6d3e827| a77b3598941cb803 | n/a | 7335 | |b198d120ea3ac674| eac0fcdafe44fac9 | | 7336 +------------+----------------+------------------+------------------+ 7338 Table 49 7340 An other example where only the "NextUID" Element is used. 7342 +--------------+------------------+-----------+------------------+ 7343 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7344 +==============+==================+===========+==================+ 7345 | "start.mkv" | 71000c23cd310998 | n/a | a77b3598941cb803 | 7346 | | 53fbc94dd984a5dd | | eac0fcdafe44fac9 | 7347 +--------------+------------------+-----------+------------------+ 7348 | "middle.mkv" | a77b3598941cb803 | n/a | 6c92285fa6d3e827 | 7349 | | eac0fcdafe44fac9 | | b198d120ea3ac674 | 7350 +--------------+------------------+-----------+------------------+ 7351 | "end.mkv" | 6c92285fa6d3e827 | n/a | n/a | 7352 | | b198d120ea3ac674 | | | 7353 +--------------+------------------+-----------+------------------+ 7355 Table 50 7357 A next example where only the "PrevUID" Element is used. 7359 +--------------+------------------+------------------+-----------+ 7360 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7361 +==============+==================+==================+===========+ 7362 | "start.mkv" | 71000c23cd310998 | n/a | n/a | 7363 | | 53fbc94dd984a5dd | | | 7364 +--------------+------------------+------------------+-----------+ 7365 | "middle.mkv" | a77b3598941cb803 | 71000c23cd310998 | n/a | 7366 | | eac0fcdafe44fac9 | 53fbc94dd984a5dd | | 7367 +--------------+------------------+------------------+-----------+ 7368 | "end.mkv" | 6c92285fa6d3e827 | a77b3598941cb803 | n/a | 7369 | | b198d120ea3ac674 | eac0fcdafe44fac9 | | 7370 +--------------+------------------+------------------+-----------+ 7372 Table 51 7374 In this example only the "middle.mkv" is using the "PrevUID" and 7375 "NextUID" Elements. 7377 +------------+----------------+------------------+------------------+ 7378 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7379 +============+================+==================+==================+ 7380 |"start.mkv" |71000c23cd310998| n/a | n/a | 7381 | |53fbc94dd984a5dd| | | 7382 +------------+----------------+------------------+------------------+ 7383 |"middle.mkv"|a77b3598941cb803| 71000c23cd310998 | 6c92285fa6d3e827 | 7384 | |eac0fcdafe44fac9| 53fbc94dd984a5dd | b198d120ea3ac674 | 7385 +------------+----------------+------------------+------------------+ 7386 | "end.mkv" |6c92285fa6d3e827| n/a | n/a | 7387 | |b198d120ea3ac674| | | 7388 +------------+----------------+------------------+------------------+ 7390 Table 52 7392 25.2. Medium Linking 7394 Medium Linking creates relationships between "Segments" using Ordered 7395 Chapters and the "ChapterSegmentUID Element". A "Segment Edition" 7396 with Ordered Chapters MAY contain "Chapter Elements" that reference 7397 timestamp ranges from other "Segments". The "Segment" referenced by 7398 the Ordered Chapter via the "ChapterSegmentUID Element" SHOULD be 7399 played as part of a Linked Segment. The timestamps of Segment 7400 content referenced by Ordered Chapters MUST be adjusted according to 7401 the cumulative duration of the the previous Ordered Chapters. 7403 As an example a file named "intro.mkv" could have a "SegmentUID" of 7404 "0xb16a58609fc7e60653a60c984fc11ead". Another file called 7405 "program.mkv" could use a Chapter Edition that contains two Ordered 7406 Chapters. The first chapter references the "Segment" of "intro.mkv" 7407 with the use of a "ChapterSegmentUID", "ChapterSegmentEditionUID", 7408 "ChapterTimeStart" and optionally a "ChapterTimeEnd" element. The 7409 second chapter references content within the "Segment" of 7410 "program.mkv". A "Matroska Player" SHOULD recognize the "Linked 7411 Segment" created by the use of "ChapterSegmentUID" in an enabled 7412 "Edition" and present the reference content of the two "Segments" 7413 together. 7415 25.3. Soft Linking 7417 Soft Linking is used by codec chapters. They can reference another 7418 "Segment" and jump to that "Segment". The way the "Segments" are 7419 described are internal to the chapter codec and unknown to the 7420 Matroska level. But there are "Elements" within the "Info Element" 7421 (such as "ChapterTranslate") that can translate a value representing 7422 a "Segment" in the chapter codec and to the current "SegmentUID". 7423 All "Segments" that could be used in a "Linked Segment" in this way 7424 SHOULD be marked as members of the same family via the "SegmentFamily 7425 Element", so that the "Matroska Player" can quickly switch from one 7426 to the other. 7428 26. Track Flags 7430 26.1. Default flag 7432 The "default track" flag is a hint for a "Matroska Player" and SHOULD 7433 always be changeable by the user. If the user wants to see or hear a 7434 track of a certain kind (audio, video, subtitles) and hasn't chosen a 7435 specific track, the "Matroska Player" SHOULD use the first track of 7436 that kind whose "default track" flag is set to "1". If no such track 7437 is found then the first track of this kind SHOULD be chosen. 7439 Only one track of a kind MAY have its "default track" flag set in a 7440 segment. If a track entry does not contain the "default track" flag 7441 element then its default value "1" is to be used. 7443 26.2. Forced flag 7445 The "forced" flag tells the "Matroska Player" that it MUST display/ 7446 play this track or another track of the same kind that also has its 7447 "forced" flag set. When there are multiple "forced" tracks, the 7448 "Matroska Player" SHOULD determine the track based upon the language 7449 of the forced flag or use the default flag if no track matches the 7450 use languages. Another track of the same kind without the "forced" 7451 flag may be use simultaneously with the "forced" track (like DVD 7452 subtitles for example). 7454 26.3. Track Operation 7456 "TrackOperation" allows combining multiple tracks to make a virtual 7457 one. It uses two separate system to combine tracks. One to create a 7458 3D "composition" (left/right/background planes) and one to simplify 7459 join two tracks together to make a single track. 7461 A track created with "TrackOperation" is a proper track with a UID 7462 and all its flags. However the codec ID is meaningless because each 7463 "sub" track needs to be decoded by its own decoder before the 7464 "operation" is applied. The "Cues Elements" corresponding to such a 7465 virtual track SHOULD be the sum of the "Cues Elements" for each of 7466 the tracks it's composed of (when the "Cues" are defined per track). 7468 In the case of "TrackJoinBlocks", the "Block Elements" (from 7469 "BlockGroup" and "SimpleBlock") of all the tracks SHOULD be used as 7470 if they were defined for this new virtual "Track". When two "Block 7471 Elements" have overlapping start or end timestamps, it's up to the 7472 underlying system to either drop some of these frames or render them 7473 the way they overlap. This situation SHOULD be avoided when creating 7474 such tracks as you can never be sure of the end result on different 7475 platforms. 7477 26.4. Overlay Track 7479 Overlay tracks SHOULD be rendered in the same 'channel' as the track 7480 its linked to. When content is found in such a track, it SHOULD be 7481 played on the rendering channel instead of the original track. 7483 26.5. Multi-planar and 3D videos 7485 There are two different ways to compress 3D videos: have each 'eye' 7486 track in a separate track and have one track have both 'eyes' 7487 combined inside (which is more efficient, compression-wise). 7488 Matroska supports both ways. 7490 For the single track variant, there is the "StereoMode Element" which 7491 defines how planes are assembled in the track (mono or left-right 7492 combined). Odd values of StereoMode means the left plane comes first 7493 for more convenient reading. The pixel count of the track 7494 ("PixelWidth"/"PixelHeight") is the raw amount of pixels (for example 7495 3840x1080 for full HD side by side) and the 7496 "DisplayWidth"/"DisplayHeight" in pixels is the amount of pixels for 7497 one plane (1920x1080 for that full HD stream). Old stereo 3D were 7498 displayed using anaglyph (cyan and red colours separated). For 7499 compatibility with such movies, there is a value of the StereoMode 7500 that corresponds to AnaGlyph. 7502 There is also a "packed" mode (values 13 and 14) which consists of 7503 packing two frames together in a "Block" using lacing. The first 7504 frame is the left eye and the other frame is the right eye (or vice 7505 versa). The frames SHOULD be decoded in that order and are possibly 7506 dependent on each other (P and B frames). 7508 For separate tracks, Matroska needs to define exactly which track 7509 does what. "TrackOperation" with "TrackCombinePlanes" do that. For 7510 more details look at how TrackOperation works (#track-operation). 7512 The 3D support is still in infancy and may evolve to support more 7513 features. 7515 The StereoMode used to be part of Matroska v2 but it didn't meet the 7516 requirement for multiple tracks. There was also a bug in libmatroska 7517 prior to 0.9.0 that would save/read it as 0x53B9 instead of 0x53B8. 7518 "Matroska Readers" may support these legacy files by checking 7519 Matroska v2 or 0x53B9. The older values 7520 (http://www.matroska.org/node/1/revisions/74/view#StereoMode) were 0: 7521 mono, 1: right eye, 2: left eye, 3: both eyes. 7523 27. Timestamps 7525 Historically timestamps in Matroska were mistakenly called timecodes. 7526 The "Timestamp Element" was called Timecode, the "TimestampScale 7527 Element" was called TimecodeScale, the "TrackTimestampScale Element" 7528 was called TrackTimecodeScale and the "ReferenceTimestamp Element" 7529 was called ReferenceTimeCode. 7531 27.1. Timestamp Types 7533 * Absolute Timestamp = Block+Cluster 7535 * Relative Timestamp = Block 7537 * Scaled Timestamp = Block+Cluster 7538 * Raw Timestamp = (Block+Cluster)*TimestampScale*TrackTimestampScale 7540 27.2. Block Timestamps 7542 The "Block Element"'s timestamp MUST be a signed integer that 7543 represents the "Raw Timestamp" relative to the "Cluster"'s "Timestamp 7544 Element", multiplied by the "TimestampScale Element". See 7545 TimestampScale (#timestampscale) for more information. 7547 The "Block Element"'s timestamp MUST be represented by a 16bit signed 7548 integer (sint16). The "Block"'s timestamp has a range of -32768 to 7549 +32767 units. When using the default value of the "TimestampScale 7550 Element", each integer represents 1ms. The maximum time span of 7551 "Block Elements" in a "Cluster" using the default "TimestampScale 7552 Element" of 1ms is 65536ms. 7554 If a "Cluster"'s "Timestamp Element" is set to zero, it is possible 7555 to have "Block Elements" with a negative "Raw Timestamp". "Block 7556 Elements" with a negative "Raw Timestamp" are not valid. 7558 27.3. Raw Timestamp 7560 The exact time of an object SHOULD be represented in nanoseconds. To 7561 find out a "Block"'s "Raw Timestamp", you need the "Block"'s 7562 "Timestamp Element", the "Cluster"'s "Timestamp Element", and the 7563 "TimestampScale Element". 7565 27.4. TimestampScale 7567 The "TimestampScale Element" is used to calculate the "Raw Timestamp" 7568 of a "Block". The timestamp is obtained by adding the "Block"'s 7569 timestamp to the "Cluster"'s "Timestamp Element", and then 7570 multiplying that result by the "TimestampScale". The result will be 7571 the "Block"'s "Raw Timestamp" in nanoseconds. The formula for this 7572 would look like: 7574 (a + b) * c 7576 a = `Block`'s Timestamp 7577 b = `Cluster`'s Timestamp 7578 c = `TimestampScale` 7580 For example, assume a "Cluster"'s "Timestamp" has a value of 564264, 7581 the "Block" has a "Timestamp" of 1233, and the "TimestampScale 7582 Element" is the default of 1000000. 7584 (1233 + 564264) * 1000000 = 565497000000 7585 So, the "Block" in this example has a specific time of 565497000000 7586 in nanoseconds. In milliseconds this would be 565497ms. 7588 27.5. TimestampScale Rounding 7590 Because the default value of "TimestampScale" is 1000000, which makes 7591 each integer in the "Cluster" and "Block" "Timestamp Elements" equal 7592 1ms, this is the most commonly used. When dealing with audio, this 7593 causes inaccuracy when seeking. When the audio is combined with 7594 video, this is not an issue. For most cases, the the synch of audio 7595 to video does not need to be more than 1ms accurate. This becomes 7596 obvious when one considers that sound will take 2-3ms to travel a 7597 single meter, so distance from your speakers will have a greater 7598 effect on audio/visual synch than this. 7600 However, when dealing with audio-only files, seeking accuracy can 7601 become critical. For instance, when storing a whole CD in a single 7602 track, a user will want to be able to seek to the exact sample that a 7603 song begins at. If seeking a few sample ahead or behind, a 'crack' 7604 or 'pop' may result as a few odd samples are rendered. Also, when 7605 performing precise editing, it may be very useful to have the audio 7606 accuracy down to a single sample. 7608 When storing timestamps for an audio stream, the "TimestampScale 7609 Element" SHOULD have an accuracy of at least that of the audio sample 7610 rate, otherwise there are rounding errors that prevent users from 7611 knowing the precise location of a sample. Here's how a program has 7612 to round each timestamp in order to be able to recreate the sample 7613 number accurately. 7615 Let's assume that the application has an audio track with a sample 7616 rate of 44100. As written above the "TimestampScale" MUST have at 7617 least the accuracy of the sample rate itself: 1000000000 / 44100 = 7618 22675.7369614512. This value MUST always be truncated. Otherwise 7619 the accuracy will not suffice. So in this example the application 7620 will use 22675 for the "TimestampScale". The application could even 7621 use some lower value like 22674 which would allow it to be a little 7622 bit imprecise about the original timestamps. But more about that in 7623 a minute. 7625 Next the application wants to write sample number 52340 and 7626 calculates the timestamp. This is easy. In order to calculate the 7627 "Raw Timestamp" in ns all it has to do is calculate "Raw Timestamp = 7628 round(1000000000 * sample_number / sample_rate)". Rounding at this 7629 stage is very important! The application might skip it if it choses 7630 a slightly smaller value for the "TimestampScale" factor instead of 7631 the truncated one like shown above. Otherwise it has to round or the 7632 results won't be reversible. For our example we get "Raw Timestamp = 7633 round(1000000000 * 52340 / 44100) = round(1186848072.56236) = 7634 1186848073". 7636 The next step is to calculate the "Absolute Timestamp" - that is the 7637 timestamp that will be stored in the Matroska file. Here the 7638 application has to divide the "Raw Timestamp" from the previous 7639 paragraph by the "TimestampScale" factor and round the result: 7640 "Absolute Timestamp = round(Raw Timestamp / TimestampScale_factor)" 7641 which will result in the following for our example: "Absolute 7642 Timestamp = round(1186848073 / 22675) = round(52341.7011245866) = 7643 52342". This number is the one the application has to write to the 7644 file. 7646 Now our file is complete, and we want to play it back with another 7647 application. Its task is to find out which sample the first 7648 application wrote into the file. So it starts reading the Matroska 7649 file and finds the "TimestampScale" factor 22675 and the audio sample 7650 rate 44100. Later it finds a data block with the "Absolute 7651 Timestamp" of 52342. But how does it get the sample number from 7652 these numbers? 7654 First it has to calculate the "Raw Timestamp" of the block it has 7655 just read. Here's no rounding involved, just an integer 7656 multiplication: "Raw Timestamp = Absolute Timestamp * 7657 TimestampScale_factor". In our example: "Raw Timestamp = 52342 * 7658 22675 = 1186854850". 7660 The conversion from the "Raw Timestamp" to the sample number again 7661 requires rounding: "sample_number = round(Raw Timestamp * sample_rate 7662 / 1000000000)". In our example: "sample_number = round(1186854850 * 7663 44100 / 1000000000) = round(52340.298885) = 52340". This is exactly 7664 the sample number that the previous program started with. 7666 Some general notes for a program: 7668 1. Always calculate the timestamps / sample numbers with floating 7669 point numbers of at least 64bit precision (called 'double' in 7670 most modern programming languages). If you're calculating with 7671 integers then make sure they're 64bit long, too. 7673 2. Always round if you divide. Always! If you don't you'll end up 7674 with situations in which you have a timestamp in the Matroska 7675 file that does not correspond to the sample number that it 7676 started with. Using a slightly lower timestamp scale factor can 7677 help here in that it removes the need for proper rounding in the 7678 conversion from sample number to "Raw Timestamp". 7680 27.6. TrackTimestampScale 7682 The "TrackTimestampScale Element" is used align tracks that would 7683 otherwise be played at different speeds. An example of this would be 7684 if you have a film that was originally recorded at 24fps video. When 7685 playing this back through a PAL broadcasting system, it is standard 7686 to speed up the film to 25fps to match the 25fps display speed of the 7687 PAL broadcasting standard. However, when broadcasting the video 7688 through NTSC, it is typical to leave the film at its original speed. 7689 If you wanted to make a single file where there was one video stream, 7690 and an audio stream used from the PAL broadcast, as well as an audio 7691 stream used from the NTSC broadcast, you would have the problem that 7692 the PAL audio stream would be 1/24th faster than the NTSC audio 7693 stream, quickly leading to problems. It is possible to stretch out 7694 the PAL audio track and re-encode it at a slower speed, however when 7695 dealing with lossy audio codecs, this often results in a loss of 7696 audio quality and/or larger file sizes. 7698 This is the type of problem that "TrackTimestampScale" was designed 7699 to fix. Using it, the video can be played back at a speed that will 7700 synch with either the NTSC or the PAL audio stream, depending on 7701 which is being used for playback. To continue the above example: 7703 Track 1: Video 7704 Track 2: NTSC Audio 7705 Track 3: PAL Audio 7707 Because the NTSC track is at the original speed, it will used as the 7708 default value of 1.0 for its "TrackTimestampScale". The video will 7709 also be aligned to the NTSC track with the default value of 1.0. 7711 The "TrackTimestampScale" value to use for the PAL track would be 7712 calculated by determining how much faster the PAL track is than the 7713 NTSC track. In this case, because we know the video for the NTSC 7714 audio is being played back at 24fps and the video for the PAL audio 7715 is being played back at 25fps, the calculation would be: 7717 25/24 is almost 1.04166666666666666667 7718 When writing a file that uses a non-default "TrackTimestampScale", 7719 the values of the "Block"'s timestamp are whatever they would be when 7720 normally storing the track with a default value for the 7721 "TrackTimestampScale". However, the data is interleaved a little 7722 differently. Data SHOULD be interleaved by its Raw Timestamp (#raw- 7723 timestamp) in the order handed back from the encoder. The "Raw 7724 Timestamp" of a "Block" from a track using "TrackTimestampScale" is 7725 calculated using: 7727 "(Block's Timestamp + Cluster's Timestamp) * TimestampScale * 7728 TrackTimestampScale" 7730 So, a Block from the PAL track above that had a Scaled Timestamp 7731 (#timestamp-types) of 100 seconds would have a "Raw Timestamp" of 7732 104.66666667 seconds, and so would be stored in that part of the 7733 file. 7735 When playing back a track using the "TrackTimestampScale", if the 7736 track is being played by itself, there is no need to scale it. From 7737 the above example, when playing the Video with the NTSC Audio, 7738 neither are scaled. However, when playing back the Video with the 7739 PAL Audio, the timestamps from the PAL Audio track are scaled using 7740 the "TrackTimestampScale", resulting in the video playing back in 7741 synch with the audio. 7743 It would be possible for a "Matroska Player" to also adjust the 7744 audio's samplerate at the same time as adjusting the timestamps if 7745 you wanted to play the two audio streams synchronously. It would 7746 also be possible to adjust the video to match the audio's speed. 7747 However, for playback, the selected track(s) timestamps SHOULD be 7748 adjusted if they need to be scaled. 7750 While the above example deals specifically with audio tracks, this 7751 element can be used to align video, audio, subtitles, or any other 7752 type of track contained in a Matroska file. 7754 28. Normative References 7756 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 7757 Requirement Levels", BCP 14, RFC 2119, 7758 DOI 10.17487/RFC2119, March 1997, 7759 . 7761 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 7762 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 7763 May 2017, . 7765 Authors' Addresses 7767 Steve Lhomme 7769 Email: slhomme@matroska.org 7771 Moritz Bunkus 7773 Email: moritz@bunkus.org 7775 Dave Rice 7777 Email: dave@dericed.com