idnits 2.17.1 draft-ietf-cellar-matroska-04.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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 3548 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (27 October 2019) is 1644 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 6460 -- Looks like a reference, but probably isn't: '0' on line 6461 -- Looks like a reference, but probably isn't: '2' on line 6460 Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 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: 29 April 2020 6 D. Rice 7 27 October 2019 9 Matroska Specifications 10 draft-ietf-cellar-matroska-04 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 29 April 2020. 35 Copyright Notice 37 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . . . 5 54 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 55 5. Notation and Conventions . . . . . . . . . . . . . . . . . . 6 56 6. Basis in EBML . . . . . . . . . . . . . . . . . . . . . . . . 6 57 6.1. Added Constraints on EBML . . . . . . . . . . . . . . . . 6 58 6.2. Matroska Design . . . . . . . . . . . . . . . . . . . . . 7 59 6.2.1. Language Codes . . . . . . . . . . . . . . . . . . . 7 60 6.2.2. Physical Types . . . . . . . . . . . . . . . . . . . 7 61 6.2.3. Block Structure . . . . . . . . . . . . . . . . . . . 8 62 6.2.4. Lacing . . . . . . . . . . . . . . . . . . . . . . . 10 63 7. Matroska Structure . . . . . . . . . . . . . . . . . . . . . 14 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 9.3. Segment Element . . . . . . . . . . . . . . . . . . . . . 25 69 9.3.1. SeekHead Element . . . . . . . . . . . . . . . . . . 25 70 9.3.2. Info Element . . . . . . . . . . . . . . . . . . . . 26 71 9.3.3. Cluster Element . . . . . . . . . . . . . . . . . . . 33 72 9.3.4. Tracks Element . . . . . . . . . . . . . . . . . . . 45 73 9.3.5. Cues Element . . . . . . . . . . . . . . . . . . . . 106 74 9.3.6. Attachments Element . . . . . . . . . . . . . . . . . 112 75 9.3.7. Chapters Element . . . . . . . . . . . . . . . . . . 115 76 9.3.8. Tags Element . . . . . . . . . . . . . . . . . . . . 127 77 10. Matroska Element Ordering . . . . . . . . . . . . . . . . . . 134 78 10.1. Top-Level Elements . . . . . . . . . . . . . . . . . . . 134 79 10.2. CRC-32 . . . . . . . . . . . . . . . . . . . . . . . . . 135 80 10.3. SeekHead . . . . . . . . . . . . . . . . . . . . . . . . 135 81 10.4. Cues (index) . . . . . . . . . . . . . . . . . . . . . . 135 82 10.5. Info . . . . . . . . . . . . . . . . . . . . . . . . . . 135 83 10.6. Chapters Element . . . . . . . . . . . . . . . . . . . . 136 84 10.7. Attachments . . . . . . . . . . . . . . . . . . . . . . 136 85 10.8. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 136 86 10.9. Optimum layout from a muxer . . . . . . . . . . . . . . 136 87 10.10. Optimum layout after editing tags . . . . . . . . . . . 137 88 10.11. Optimum layout with Cues at the front . . . . . . . . . 137 89 10.12. Cluster Timestamp . . . . . . . . . . . . . . . . . . . 137 90 11. Chapters . . . . . . . . . . . . . . . . . . . . . . . . . . 138 91 11.1. Edition and Chapter Flags . . . . . . . . . . . . . . . 138 92 11.1.1. Chapter Flags . . . . . . . . . . . . . . . . . . . 138 93 11.1.2. Edition Flags . . . . . . . . . . . . . . . . . . . 138 94 11.2. Menu features . . . . . . . . . . . . . . . . . . . . . 140 95 11.2.1. Matroska Script (0) . . . . . . . . . . . . . . . . 140 96 11.2.2. DVD menu (1) . . . . . . . . . . . . . . . . . . . . 141 98 11.3. Example 1 : basic chaptering . . . . . . . . . . . . . . 142 99 11.4. Example 2 : nested chapters . . . . . . . . . . . . . . 142 100 11.4.1. The Micronauts "Bleep To Bleep" . . . . . . . . . . 143 101 12. Attachments . . . . . . . . . . . . . . . . . . . . . . . . . 143 102 12.1. Cover Art . . . . . . . . . . . . . . . . . . . . . . . 143 103 13. Cues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 104 13.1. Recommendations . . . . . . . . . . . . . . . . . . . . 144 105 14. Matroska Streaming . . . . . . . . . . . . . . . . . . . . . 145 106 14.1. File Access . . . . . . . . . . . . . . . . . . . . . . 145 107 14.2. Livestreaming . . . . . . . . . . . . . . . . . . . . . 146 108 15. Menu Specifications . . . . . . . . . . . . . . . . . . . . . 146 109 15.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 147 110 15.1.1. Highlights/Hotspots . . . . . . . . . . . . . . . . 147 111 15.1.2. Playback features . . . . . . . . . . . . . . . . . 148 112 15.1.3. Player requirements . . . . . . . . . . . . . . . . 148 113 15.2. Working Graph . . . . . . . . . . . . . . . . . . . . . 148 114 16. Unknown elements . . . . . . . . . . . . . . . . . . . . . . 149 115 17. Default Values . . . . . . . . . . . . . . . . . . . . . . . 149 116 18. DefaultDecodedFieldDuration . . . . . . . . . . . . . . . . . 149 117 19. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 150 118 20. Image Presentation . . . . . . . . . . . . . . . . . . . . . 150 119 20.1. Cropping . . . . . . . . . . . . . . . . . . . . . . . . 150 120 20.2. Rotation . . . . . . . . . . . . . . . . . . . . . . . . 151 121 21. Matroska versioning . . . . . . . . . . . . . . . . . . . . . 151 122 22. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . 152 123 23. Segment Position . . . . . . . . . . . . . . . . . . . . . . 152 124 23.1. Segment Position Exception . . . . . . . . . . . . . . . 152 125 23.2. Example of Segment Position . . . . . . . . . . . . . . 152 126 24. Linked Segments . . . . . . . . . . . . . . . . . . . . . . . 153 127 24.1. Hard Linking . . . . . . . . . . . . . . . . . . . . . . 153 128 24.2. Medium Linking . . . . . . . . . . . . . . . . . . . . . 155 129 24.3. Soft Linking . . . . . . . . . . . . . . . . . . . . . . 155 130 25. Track Flags . . . . . . . . . . . . . . . . . . . . . . . . . 156 131 25.1. Default flag . . . . . . . . . . . . . . . . . . . . . . 156 132 25.2. Forced flag . . . . . . . . . . . . . . . . . . . . . . 156 133 25.3. Track Operation . . . . . . . . . . . . . . . . . . . . 156 134 25.4. Overlay Track . . . . . . . . . . . . . . . . . . . . . 157 135 25.5. Multi-planar and 3D videos . . . . . . . . . . . . . . . 157 136 26. Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . 158 137 26.1. Timestamp Types . . . . . . . . . . . . . . . . . . . . 158 138 26.2. Block Timestamps . . . . . . . . . . . . . . . . . . . . 158 139 26.3. Raw Timestamp . . . . . . . . . . . . . . . . . . . . . 158 140 26.4. TimestampScale . . . . . . . . . . . . . . . . . . . . . 159 141 26.5. TimestampScale Rounding . . . . . . . . . . . . . . . . 159 142 26.6. TrackTimestampScale . . . . . . . . . . . . . . . . . . 161 143 27. Normative References . . . . . . . . . . . . . . . . . . . . 163 144 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 163 146 1. Introduction 148 Matroska aims to become THE standard of multimedia container formats. 149 It was derived from a project called MCF (http://mukoli.free.fr/mcf/ 150 mcf.html), but differentiates from it significantly because it is 151 based on EBML (https://github.com/Matroska-Org/ebml- 152 specification/blob/master/specification.markdown) (Extensible Binary 153 Meta Language), a binary derivative of XML. EBML enables significant 154 advantages in terms of future format extensibility, without breaking 155 file support in old parsers. 157 First, it is essential to clarify exactly "What an Audio/Video 158 container is", to avoid any misunderstandings: 160 * It is NOT a video or audio compression format (codec) 162 * It is an envelope for which there can be many audio, video and 163 subtitles streams, allowing the user to store a complete movie or 164 CD in a single file. 166 Matroska is designed with the future in mind. It incorporates 167 features like: 169 * Fast seeking in the file 171 * Chapter entries 173 * Full metadata (tags) support 175 * Selectable subtitle/audio/video streams 177 * Modularly expandable 179 * Error resilience (can recover playback even when the stream is 180 damaged) 182 * Streamable over the internet and local networks (HTTP, CIFS, FTP, 183 etc) 185 * Menus (like DVDs have) 187 Matroska is an open standards project. This means for personal use 188 it is absolutely free to use and that the technical specifications 189 describing the bitstream are open to everybody, even to companies 190 that would like to support it in their products. 192 2. Status of this document 194 This document is a work-in-progress specification defining the 195 Matroska file format as part of the IETF Cellar working group 196 (https://datatracker.ietf.org/wg/cellar/charter/). But since it's 197 quite complete it is used as a reference for the development of 198 libmatroska. Legacy versions of the specification can be found here 199 (https://matroska.org/files/matroska.pdf) (PDF doc by Alexander Noe 200 -- outdated). 202 For a simplified diagram of the layout of a Matroska file, see the 203 Diagram page (diagram.md). 205 A more refined and detailed version of the EBML specifications is 206 being worked on here (https://github.com/Matroska-Org/ebml- 207 specification/blob/master/specification.markdown). 209 The table found below is now generated from the "source" of the 210 Matroska specification. This XML file (https://github.com/Matroska- 211 Org/foundation-source/blob/master/spectool/specdata.xml) is also used 212 to generate the semantic data used in libmatroska and libmatroska2. 213 We encourage anyone to use and monitor its changes so your code is 214 spec-proof and always up to date. 216 Note that versions 1, 2 and 3 have been finalized. Version 4 is 217 currently work in progress. There MAY be further additions to v4. 219 3. Security Considerations 221 Matroska inherits security considerations from EBML. 223 Attacks on a "Matroska Reader" could include: 225 * Storage of a arbitrary and potentially executable data within an 226 "Attachment Element". "Matroska Readers" that extract or use data 227 from Matroska Attachments SHOULD check that the data adheres to 228 expectations. 230 * A "Matroska Attachment" with an inaccurate mime-type. 232 4. IANA Considerations 234 To be determined. 236 5. Notation and Conventions 238 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 239 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 240 "OPTIONAL" in this document are to be interpreted as described in BCP 241 14 [RFC2119] [RFC8174] when, and only when, they appear in all 242 capitals, as shown here. 244 This document defines specific terms in order to define the format 245 and application of "Matroska". Specific terms are defined below: 247 "Matroska": a multimedia container format based on EBML (Extensible 248 Binary Meta Language) 250 "Matroska Reader": A "Matroska Reader" is a data parser that 251 interprets the semantics of a Matroska document and creates a way for 252 programs to use "Matroska". 254 "Matroska Player": A "Matroska Player" is a "Matroska Reader" with a 255 primary purpose of playing audiovisual files, including "Matroska" 256 documents. 258 6. Basis in EBML 260 Matroska is a Document Type of EBML (Extensible Binary Meta 261 Language). This specification is dependent on the EBML Specification 262 (https://github.com/Matroska-Org/ebml-specification/blob/master/ 263 specification.markdown). For an understanding of Matroska's EBML 264 Schema, see in particular the sections of the EBML Specification 265 covering EBML Element Types (https://github.com/Matroska-Org/ebml- 266 specification/blob/master/specification.markdown#ebml-element-types), 267 EBML Schema (https://github.com/Matroska-Org/ebml- 268 specification/blob/master/specification.markdown#ebml-schema), and 269 EBML Structure (https://github.com/Matroska-Org/ebml- 270 specification/blob/master/specification.markdown#structure). 272 6.1. Added Constraints on EBML 274 As an EBML Document Type, Matroska adds the following constraints to 275 the EBML specification. 277 * The "docType" of the "EBML Header" MUST be 'matroska'. 279 * The "EBMLMaxIDLength" of the "EBML Header" MUST be "4". 281 * The "EBMLMaxSizeLength" of the "EBML Header" MUST be between "1" 282 and "8" inclusive. 284 6.2. Matroska Design 286 All top-levels elements (Segment and direct sub-elements) are coded 287 on 4 octets, i.e. class D elements. 289 6.2.1. Language Codes 291 Matroska from version 1 through 3 uses language codes that can be 292 either the 3 letters bibliographic ISO-639-2 293 (https://www.loc.gov/standards/iso639-2/php/English_list.php) form 294 (like "fre" for french), or such a language code followed by a dash 295 and a country code for specialities in languages (like "fre-ca" for 296 Canadian French). The "ISO 639-2 Language Elements" are "Language 297 Element", "TagLanguage Element", and "ChapLanguage Element". 299 Starting in Matroska version 4, either "ISO 639-2" or BCP 47 300 (https://tools.ietf.org/html/bcp47) MAY be used, although "BCP 47" is 301 RECOMMENDED. The "BCP 47 Language Elements" are "LanguageIETF 302 Element", "TagLanguageIETF Element", and "ChapLanguageIETF Element". 303 If a "BCP 47 Language Element" and an "ISO 639-2 Language Element" 304 are used within the same "Parent Element", then the "ISO 639-2 305 Language Element" MUST be ignored and precedence given to the "BCP 47 306 Language Element". 308 Country codes are the same as used for internet domains 309 (https://www.iana.org/domains/root/db). 311 6.2.2. Physical Types 313 Each level can have different meanings for audio and video. The 314 ORIGINAL_MEDIUM tag can be used to specify a string for 315 ChapterPhysicalEquiv = 60. Here is the list of possible levels for 316 both audio and video : 318 +----------------------+------------+-----------+-----------------+ 319 | ChapterPhysicalEquiv | Audio | Video | Comment | 320 +======================+============+===========+=================+ 321 | 70 | SET / | SET / | the collection | 322 | | PACKAGE | PACKAGE | of different | 323 | | | | media | 324 +----------------------+------------+-----------+-----------------+ 325 | 60 | CD / 12" / | DVD / VHS | the physical | 326 | | 10" / 7" / | / | medium like a | 327 | | TAPE / | LASERDISC | CD or a DVD | 328 | | MINIDISC / | | | 329 | | DAT | | | 330 +----------------------+------------+-----------+-----------------+ 331 | 50 | SIDE | SIDE | when the | 332 | | | | original medium | 333 | | | | (LP/DVD) has | 334 | | | | different sides | 335 +----------------------+------------+-----------+-----------------+ 336 | 40 | - | LAYER | another | 337 | | | | physical level | 338 | | | | on DVDs | 339 +----------------------+------------+-----------+-----------------+ 340 | 30 | SESSION | SESSION | as found on CDs | 341 | | | | and DVDs | 342 +----------------------+------------+-----------+-----------------+ 343 | 20 | TRACK | - | as found on | 344 | | | | audio CDs | 345 +----------------------+------------+-----------+-----------------+ 346 | 10 | INDEX | - | the first | 347 | | | | logical level | 348 | | | | of the side/ | 349 | | | | medium | 350 +----------------------+------------+-----------+-----------------+ 352 Table 1 354 6.2.3. Block Structure 356 Bit 0 is the most significant bit. 358 Frames using references SHOULD be stored in "coding order". That 359 means the references first and then the frames referencing them. A 360 consequence is that timestamps might not be consecutive. But a frame 361 with a past timestamp MUST reference a frame already known, otherwise 362 it's considered bad/void. 364 There can be many Blocks in a BlockGroup provided they all have the 365 same timestamp. It is used with different parts of a frame with 366 different priorities. 368 6.2.3.1. Block Header 370 +--------+--------+---------------------------------------------+ 371 | Offset | Player | Description | 372 +========+========+=============================================+ 373 | 0x00+ | MUST | Track Number (Track Entry). It is coded in | 374 | | | EBML like form (1 octet if the value is < | 375 | | | 0x80, 2 if < 0x4000, etc) (most significant | 376 | | | bits set to increase the range). | 377 +--------+--------+---------------------------------------------+ 378 | 0x01+ | MUST | Timestamp (relative to Cluster timestamp, | 379 | | | signed int16) | 380 +--------+--------+---------------------------------------------+ 382 Table 2 384 6.2.3.2. Block Header Flags 386 +--------+-----+--------+------------------------------------+ 387 | Offset | Bit | Player | Description | 388 +========+=====+========+====================================+ 389 | 0x03+ | 0-3 | - | Reserved, set to 0 | 390 +--------+-----+--------+------------------------------------+ 391 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode | 392 | | | | this frame but not display it | 393 +--------+-----+--------+------------------------------------+ 394 | 0x03+ | 5-6 | MUST | Lacing | 395 +--------+-----+--------+------------------------------------+ 396 | | | | * 00 : no lacing | 397 +--------+-----+--------+------------------------------------+ 398 | | | | * 01 : Xiph lacing | 399 +--------+-----+--------+------------------------------------+ 400 | | | | * 11 : EBML lacing | 401 +--------+-----+--------+------------------------------------+ 402 | | | | * 10 : fixed-size lacing | 403 +--------+-----+--------+------------------------------------+ 404 | 0x03+ | 7 | - | not used | 405 +--------+-----+--------+------------------------------------+ 407 Table 3 409 6.2.4. Lacing 411 Lacing is a mechanism to save space when storing data. It is 412 typically used for small blocks of data (referred to as frames in 413 Matroska). There are 3 types of lacing: 415 1. Xiph, inspired by what is found in the Ogg container 417 2. EBML, which is the same with sizes coded differently 419 3. fixed-size, where the size is not coded 421 For example, a user wants to store 3 frames of the same track. The 422 first frame is 800 octets long, the second is 500 octets long and the 423 third is 1000 octets long. As these data are small, they can be 424 stored in a lace to save space. They will then be stored in the same 425 block as follows: 427 6.2.4.1. Xiph lacing 429 * Block head (with lacing bits set to 01) 431 * Lacing head: Number of frames in the lace -1, i.e. 2 (the 800 and 432 500 octets one) 434 * Lacing sizes: only the 2 first ones will be coded, 800 gives 435 255;255;255;35, 500 gives 255;245. The size of the last frame is 436 deduced from the total size of the Block. 438 * Data in frame 1 440 * Data in frame 2 442 * Data in frame 3 444 A frame with a size multiple of 255 is coded with a 0 at the end of 445 the size, for example 765 is coded 255;255;255;0. 447 6.2.4.2. EBML lacing 449 In this case, the size is not coded as blocks of 255 bytes, but as a 450 difference with the previous size and this size is coded as in EBML. 451 The first size in the lace is unsigned as in EBML. The others use a 452 range shifting to get a sign on each value: 454 +--------------------------+---------------------------------------+ 455 | Bit Representation | Value | 456 +==========================+=======================================+ 457 | 1xxx xxxx | value -(2^6-1) to 2^6-1 (ie 0 to | 458 | | 2^7-2 minus 2^6-1, half of the range) | 459 +--------------------------+---------------------------------------+ 460 | 01xx xxxx xxxx xxxx | value -(2^13-1) to 2^(13-1) | 461 +--------------------------+---------------------------------------+ 462 | 001x xxxx xxxx xxxx xxxx | value -(2^20-1) to 2^(20-1) | 463 | xxxx | | 464 +--------------------------+---------------------------------------+ 465 | 0001 xxxx xxxx xxxx xxxx | value -(2^27-1) to 2^(27-1) | 466 | xxxx xxxx xxxx | | 467 +--------------------------+---------------------------------------+ 468 | 0000 1xxx xxxx xxxx xxxx | value -(2^34-1) to 2^(34-1) | 469 | xxxx xxxx xxxx xxxx xxxx | | 470 +--------------------------+---------------------------------------+ 471 | 0000 01xx xxxx xxxx xxxx | value -(2^41-1) to 2^(41-1) | 472 | xxxx xxxx xxxx xxxx xxxx | | 473 | xxxx xxxx | | 474 +--------------------------+---------------------------------------+ 475 | 0000 001x xxxx xxxx xxxx | value -(2^48-1) to 2^(48-1) | 476 | xxxx xxxx xxxx xxxx xxxx | | 477 | xxxx xxxx xxxx xxxx | | 478 +--------------------------+---------------------------------------+ 480 Table 4 482 * Block head (with lacing bits set to 11) 484 * Lacing head: Number of frames in the lace -1, i.e. 2 (the 800 and 485 500 octets one) 487 * Lacing sizes: only the 2 first ones will be coded, 800 gives 0x320 488 0x4000 = 0x4320, 500 is coded as -300 : - 0x12C + 0x1FFF + 0x4000 489 = 0x5ED3. The size of the last frame is deduced from the total 490 size of the Block. 492 * Data in frame 1 494 * Data in frame 2 496 * Data in frame 3 498 6.2.4.3. Fixed-size lacing 500 In this case, only the number of frames in the lace is saved, the 501 size of each frame is deduced from the total size of the Block. For 502 example, for 3 frames of 800 octets each: 504 * Block head (with lacing bits set to 10) 506 * Lacing head: Number of frames in the lace -1, i.e. 2 508 * Data in frame 1 510 * Data in frame 2 512 * Data in frame 3 514 6.2.4.4. SimpleBlock Structure 516 The "SimpleBlock" is inspired by the Block structure (#block- 517 structure). The main differences are the added Keyframe flag and 518 Discardable flag. Otherwise everything is the same. 520 Bit 0 is the most significant bit. 522 Frames using references SHOULD be stored in "coding order". That 523 means the references first and then the frames referencing them. A 524 consequence is that timestamps might not be consecutive. But a frame 525 with a past timestamp MUST reference a frame already known, otherwise 526 it's considered bad/void. 528 There can be many "Block Elements" in a "BlockGroup" provided they 529 all have the same timestamp. It is used with different parts of a 530 frame with different priorities. 532 6.2.4.4.1. SimpleBlock Header 534 +--------+--------+---------------------------------------------+ 535 | Offset | Player | Description | 536 +========+========+=============================================+ 537 | 0x00+ | MUST | Track Number (Track Entry). It is coded in | 538 | | | EBML like form (1 octet if the value is < | 539 | | | 0x80, 2 if < 0x4000, etc) (most significant | 540 | | | bits set to increase the range). | 541 +--------+--------+---------------------------------------------+ 542 | 0x01+ | MUST | Timestamp (relative to Cluster timestamp, | 543 | | | signed int16) | 544 +--------+--------+---------------------------------------------+ 546 Table 5 548 6.2.4.4.2. SimpleBlock Header Flags 550 +--------+-----+--------+------------------------------------------+ 551 | Offset | Bit | Player | Description | 552 +========+=====+========+==========================================+ 553 | 0x03+ | 0 | - | Keyframe, set when the Block contains | 554 | | | | only keyframes | 555 +--------+-----+--------+------------------------------------------+ 556 | 0x03+ | 1-3 | - | Reserved, set to 0 | 557 +--------+-----+--------+------------------------------------------+ 558 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode this | 559 | | | | frame but not display it | 560 +--------+-----+--------+------------------------------------------+ 561 | 0x03+ | 5-6 | MUST | Lacing | 562 +--------+-----+--------+------------------------------------------+ 563 | | | | * 00 : no lacing | 564 +--------+-----+--------+------------------------------------------+ 565 | | | | * 01 : Xiph lacing | 566 +--------+-----+--------+------------------------------------------+ 567 | | | | * 11 : EBML lacing | 568 +--------+-----+--------+------------------------------------------+ 569 | | | | * 10 : fixed-size lacing | 570 +--------+-----+--------+------------------------------------------+ 571 | 0x03+ | 7 | - | Discardable, the frames of the Block can | 572 | | | | be discarded during playing if needed | 573 +--------+-----+--------+------------------------------------------+ 575 Table 6 577 6.2.4.5. Laced Data 579 When lacing bit is set. 581 +--------+--------+---------------------------------------------+ 582 | Offset | Player | Description | 583 +========+========+=============================================+ 584 | 0x00 | MUST | Number of frames in the lace-1 (uint8) | 585 +--------+--------+---------------------------------------------+ 586 | 0x01 / | MUST* | Lace-coded size of each frame of the lace, | 587 | 0xXX | | except for the last one (multiple uint8). | 588 | | | *This is not used with Fixed-size lacing as | 589 | | | it is calculated automatically from (total | 590 | | | size of lace) / (number of frames in lace). | 591 +--------+--------+---------------------------------------------+ 593 Table 7 595 For (possibly) Laced Data 597 +--------+--------+--------------------------+ 598 | Offset | Player | Description | 599 +========+========+==========================+ 600 | 0x00 | MUST | Consecutive laced frames | 601 +--------+--------+--------------------------+ 603 Table 8 605 7. Matroska Structure 607 A Matroska file MUST be composed of at least one "EBML Document" 608 using the "Matroska Document Type". Each "EBML Document" MUST start 609 with an "EBML Header" and MUST be followed by the "EBML Root 610 Element", defined as "Segment" in Matroska. Matroska defines several 611 "Top Level Elements" which MAY occur within the "Segment". 613 As an example, a simple Matroska file consisting of a single "EBML 614 Document" could be represented like this: 616 * "EBML Header" 618 * "Segment" 620 A more complex Matroska file consisting of an "EBML Stream" 621 (consisting of two "EBML Documents") could be represented like this: 623 * "EBML Header" 624 * "Segment" 626 * "EBML Header" 628 * "Segment" 630 The following diagram represents a simple Matroska file, comprised of 631 an "EBML Document" with an "EBML Header", a "Segment Element" (the 632 "Root Element"), and all eight Matroska "Top Level Elements". In the 633 following diagrams of this section, horizontal spacing expresses a 634 parent-child relationship between Matroska Elements (e.g. the "Info 635 Element" is contained within the "Segment Element") whereas vertical 636 alignment represents the storage order within the file. 638 +-------------+ 639 | EBML Header | 640 +---------------------------+ 641 | Segment | SeekHead | 642 | |-------------| 643 | | Info | 644 | |-------------| 645 | | Tracks | 646 | |-------------| 647 | | Chapters | 648 | |-------------| 649 | | Cluster | 650 | |-------------| 651 | | Cues | 652 | |-------------| 653 | | Attachments | 654 | |-------------| 655 | | Tags | 656 +---------------------------+ 658 The Matroska "EBML Schema" defines eight "Top Level Elements": 659 "SeekHead", "Info", "Tracks", "Chapters", "Cluster", "Cues", 660 "Attachments", and "Tags". 662 The "SeekHead Element" (also known as "MetaSeek") contains an index 663 of "Top Level Elements" locations within the "Segment". Use of the 664 "SeekHead Element" is RECOMMENDED. Without a "SeekHead Element", a 665 Matroska parser would have to search the entire file to find all of 666 the other "Top Level Elements". This is due to Matroska's flexible 667 ordering requirements; for instance, it is acceptable for the 668 "Chapters Element" to be stored after the "Cluster Elements". 670 +--------------------------------+ 671 | SeekHead | Seek | SeekID | 672 | | |--------------| 673 | | | SeekPosition | 674 +--------------------------------+ 676 Figure 1: Representation of a "SeekHead Element". 678 The "Info Element" contains vital information for identifying the 679 whole "Segment". This includes the title for the "Segment", a 680 randomly generated unique identifier, and the unique identifier(s) of 681 any linked "Segment Elements". 683 +-------------------------+ 684 | Info | SegmentUID | 685 | |------------------| 686 | | SegmentFilename | 687 | |------------------| 688 | | PrevUID | 689 | |------------------| 690 | | PrevFilename | 691 | |------------------| 692 | | NextUID | 693 | |------------------| 694 | | NextFilename | 695 | |------------------| 696 | | SegmentFamily | 697 | |------------------| 698 | | ChapterTranslate | 699 | |------------------| 700 | | TimestampScale | 701 | |------------------| 702 | | Duration | 703 | |------------------| 704 | | DateUTC | 705 | |------------------| 706 | | Title | 707 | |------------------| 708 | | MuxingApp | 709 | |------------------| 710 | | WritingApp | 711 |-------------------------| 713 Figure 2: Representation of an "Info Element" and its "Child 714 Elements". 716 The "Tracks Element" defines the technical details for each track and 717 can store the name, number, unique identifier, language and type 718 (audio, video, subtitles, etc.) of each track. For example, the 719 "Tracks Element" MAY store information about the resolution of a 720 video track or sample rate of an audio track. 722 The "Tracks Element" MUST identify all the data needed by the codec 723 to decode the data of the specified track. However, the data 724 required is contingent on the codec used for the track. For example, 725 a "Track Element" for uncompressed audio only requires the audio bit 726 rate to be present. A codec such as AC-3 would require that the 727 "CodecID Element" be present for all tracks, as it is the primary way 728 to identify which codec to use to decode the track. 730 +------------------------------------+ 731 | Tracks | TrackEntry | TrackNumber | 732 | | |--------------| 733 | | | TrackUID | 734 | | |--------------| 735 | | | TrackType | 736 | | |--------------| 737 | | | Name | 738 | | |--------------| 739 | | | Language | 740 | | |--------------| 741 | | | CodecID | 742 | | |--------------| 743 | | | CodecPrivate | 744 | | |--------------| 745 | | | CodecName | 746 | | |----------------------------------+ 747 | | | Video | FlagInterlaced | 748 | | | |-------------------| 749 | | | | FieldOrder | 750 | | | |-------------------| 751 | | | | StereoMode | 752 | | | |-------------------| 753 | | | | AlphaMode | 754 | | | |-------------------| 755 | | | | PixelWidth | 756 | | | |-------------------| 757 | | | | PixelHeight | 758 | | | |-------------------| 759 | | | | DisplayWidth | 760 | | | |-------------------| 761 | | | | DisplayHeight | 762 | | | |-------------------| 763 | | | | AspectRatioType | 764 | | | |-------------------| 765 | | | | Color | 766 | | |----------------------------------| 767 | | | Audio | SamplingFrequency | 768 | | | |-------------------| 769 | | | | Channels | 770 | | | |-------------------| 771 | | | | BitDepth | 772 |--------------------------------------------------------| 774 Figure 3: Representation of the "Tracks Element" and a selection 775 of its "Descendant Elements". 777 The "Chapters Element" lists all of the chapters. Chapters are a way 778 to set predefined points to jump to in video or audio. 780 +-----------------------------------------+ 781 | Chapters | Edition | EditionUID | 782 | | Entry |--------------------| 783 | | | EditionFlagHidden | 784 | | |--------------------| 785 | | | EditionFlagDefault | 786 | | |--------------------| 787 | | | EditionFlagOrdered | 788 | | |---------------------------------+ 789 | | | ChapterAtom | ChapterUID | 790 | | | |-------------------| 791 | | | | ChapterStringUID | 792 | | | |-------------------| 793 | | | | ChapterTimeStart | 794 | | | |-------------------| 795 | | | | ChapterTimeEnd | 796 | | | |-------------------| 797 | | | | ChapterFlagHidden | 798 | | | |-------------------------------+ 799 | | | | ChapterDisplay | ChapString | 800 | | | | |--------------| 801 | | | | | ChapLanguage | 802 +------------------------------------------------------------------+ 804 Figure 4: Representation of the "Chapters Element" and a 805 selection of its "Descendant Elements". 807 "Cluster Elements" contain the content for each track, e.g. video 808 frames. A Matroska file SHOULD contain at least one "Cluster 809 Element". The "Cluster Element" helps to break up "SimpleBlock" or 810 "BlockGroup Elements" and helps with seeking and error protection. 811 It is RECOMMENDED that the size of each individual "Cluster Element" 812 be limited to store no more than 5 seconds or 5 megabytes. Every 813 "Cluster Element" MUST contain a "Timestamp Element". This SHOULD be 814 the "Timestamp Element" used to play the first "Block" in the 815 "Cluster Element". There SHOULD be one or more "BlockGroup" or 816 "SimpleBlock Element" in each "Cluster Element". A "BlockGroup 817 Element" MAY contain a "Block" of data and any information relating 818 directly to that "Block". 820 +--------------------------+ 821 | Cluster | Timestamp | 822 | |----------------| 823 | | SilentTracks | 824 | |----------------| 825 | | Position | 826 | |----------------| 827 | | PrevSize | 828 | |----------------| 829 | | SimpleBlock | 830 | |----------------| 831 | | BlockGroup | 832 | |----------------| 833 | | EncryptedBlock | 834 +--------------------------+ 836 Figure 5: Representation of a "Cluster Element" and its immediate 837 "Child Elements". 839 +----------------------------------+ 840 | Block | Portion of | Data Type | 841 | | a Block | - Bit Flag | 842 | |--------------------------+ 843 | | Header | TrackNumber | 844 | | |-------------| 845 | | | Timestamp | 846 | | |-------------| 847 | | | Flags | 848 | | | - Gap | 849 | | | - Lacing | 850 | | | - Reserved | 851 | |--------------------------| 852 | | Optional | FrameSize | 853 | |--------------------------| 854 | | Data | Frame | 855 +----------------------------------+ 857 Figure 6: Representation of the "Block Element" structure. 859 Each "Cluster" MUST contain exactly one "Timestamp Element". The 860 "Timestamp Element" value MUST be stored once per "Cluster". The 861 "Timestamp Element" in the "Cluster" is relative to the entire 862 "Segment". The "Timestamp Element" SHOULD be the first "Element" in 863 the "Cluster". 865 Additionally, the "Block" contains an offset that, when added to the 866 "Cluster"'s "Timestamp Element" value, yields the "Block"'s effective 867 timestamp. Therefore, timestamp in the "Block" itself is relative to 868 the "Timestamp Element" in the "Cluster". For example, if the 869 "Timestamp Element" in the "Cluster" is set to 10 seconds and a 870 "Block" in that "Cluster" is supposed to be played 12 seconds into 871 the clip, the timestamp in the "Block" would be set to 2 seconds. 873 The "ReferenceBlock" in the "BlockGroup" is used instead of the basic 874 "P-frame"/"B-frame" description. Instead of simply saying that this 875 "Block" depends on the "Block" directly before, or directly 876 afterwards, the "Timestamp" of the necessary "Block" is used. 877 Because there can be as many "ReferenceBlock Elements" as necessary 878 for a "Block", it allows for some extremely complex referencing. 880 The "Cues Element" is used to seek when playing back a file by 881 providing a temporal index for some of the "Tracks". It is similar 882 to the "SeekHead Element", but used for seeking to a specific time 883 when playing back the file. It is possible to seek without this 884 element, but it is much more difficult because a "Matroska Reader" 885 would have to 'hunt and peck' through the file looking for the 886 correct timestamp. 888 The "Cues Element" SHOULD contain at least one "CuePoint Element". 889 Each "CuePoint Element" stores the position of the "Cluster" that 890 contains the "BlockGroup" or "SimpleBlock Element". The timestamp is 891 stored in the "CueTime Element" and location is stored in the 892 "CueTrackPositions Element". 894 The "Cues Element" is flexible. For instance, "Cues Element" can be 895 used to index every single timestamp of every "Block" or they can be 896 indexed selectively. For video files, it is RECOMMENDED to index at 897 least the keyframes of the video track. 899 +-------------------------------------+ 900 | Cues | CuePoint | CueTime | 901 | | |-------------------| 902 | | | CueTrackPositions | 903 | |------------------------------| 904 | | CuePoint | CueTime | 905 | | |-------------------| 906 | | | CueTrackPositions | 907 +-------------------------------------+ 909 Figure 7: Representation of a "Cues Element" and two levels of 910 its "Descendant Elements". 912 The "Attachments Element" is for attaching files to a Matroska file 913 such as pictures, webpages, programs, or even the codec needed to 914 play back the file. 916 +------------------------------------------------+ 917 | Attachments | AttachedFile | FileDescription | 918 | | |-------------------| 919 | | | FileName | 920 | | |-------------------| 921 | | | FileMimeType | 922 | | |-------------------| 923 | | | FileData | 924 | | |-------------------| 925 | | | FileUID | 926 | | |-------------------| 927 | | | FileName | 928 | | |-------------------| 929 | | | FileReferral | 930 | | |-------------------| 931 | | | FileUsedStartTime | 932 | | |-------------------| 933 | | | FileUsedEndTime | 934 +------------------------------------------------+ 936 Figure 8: Representation of a "Attachments Element". 938 The "Tags Element" contains metadata that describes the "Segment" and 939 potentially its "Tracks", "Chapters", and "Attachments". Each 940 "Track" or "Chapter" that those tags applies to has its UID listed in 941 the "Tags". The "Tags" contain all extra information about the file: 942 scriptwriter, singer, actors, directors, titles, edition, price, 943 dates, genre, comments, etc. Tags can contain their values in 944 multiple languages. For example, a movie's "title" "Tag" might 945 contain both the original English title as well as the title it was 946 released as in Germany. 948 +-------------------------------------------+ 949 | Tags | Tag | Targets | TargetTypeValue | 950 | | | |------------------| 951 | | | | TargetType | 952 | | | |------------------| 953 | | | | TagTrackUID | 954 | | | |------------------| 955 | | | | TagEditionUID | 956 | | | |------------------| 957 | | | | TagChapterUID | 958 | | | |------------------| 959 | | | | TagAttachmentUID | 960 | | |------------------------------| 961 | | | SimpleTag | TagName | 962 | | | |------------------| 963 | | | | TagLanguage | 964 | | | |------------------| 965 | | | | TagDefault | 966 | | | |------------------| 967 | | | | TagString | 968 | | | |------------------| 969 | | | | TagBinary | 970 | | | |------------------| 971 | | | | SimpleTag | 972 +-------------------------------------------+ 974 Figure 9: Representation of a "Tags Element" and three levels of 975 its "Children Elements". 977 8. Matroska Additions to Schema Element Attributes 979 In addition to the EBML Schema definition provided by the EBML 980 Specification, Matroska adds the following additional attributes: 982 +-----------+----------+----------------------------------------+ 983 | attribute | required | definition | 984 | name | | | 985 +===========+==========+========================================+ 986 | webm | No | A boolean to express if the Matroska | 987 | | | Element is also supported within | 988 | | | version 2 of the "webm" specification. | 989 | | | Please consider the webm specification | 990 | | | (http://www.webmproject.org/docs/ | 991 | | | container/) as the authoritative on | 992 | | | "webm". | 993 +-----------+----------+----------------------------------------+ 995 Table 9 997 9. Matroska Schema 999 This specification includes an "EBML Schema" which defines the 1000 Elements and structure of Matroska as an EBML Document Type. The 1001 EBML Schema defines every valid Matroska element in a manner defined 1002 by the EBML specification. 1004 Here the definition of each Matroska Element is provided. 1006 9.1. EBMLMaxIDLength Element 1008 name: "EBMLMaxIDLength" 1010 path: "1*1(\EBML\EBMLMaxIDLength)" 1012 id: "0x42F2" 1014 minOccurs: "1" 1016 maxOccurs: "1" 1018 range: "4" 1020 default: "4" 1022 type: "uinteger" 1024 9.2. EBMLMaxSizeLength Element 1026 name: "EBMLMaxSizeLength" 1028 path: "1*1(\EBML\EBMLMaxSizeLength)" 1030 id: "0x42F3" 1032 minOccurs: "1" 1034 maxOccurs: "1" 1036 range: "1-8" 1038 default: "8" 1040 type: "uinteger" 1042 9.3. Segment Element 1044 name: "Segment" 1046 path: "1*1(\Segment)" 1048 id: "0x18538067" 1050 minOccurs: "1" 1052 maxOccurs: "1" 1054 type: "master" 1056 unknownsizeallowed: "1" 1058 definition: The Root Element that contains all other Top-Level 1059 Elements (Elements defined only at Level 1). A Matroska file is 1060 composed of 1 Segment. 1062 9.3.1. SeekHead Element 1064 name: "SeekHead" 1066 path: "0*2(\Segment\SeekHead)" 1068 id: "0x114D9B74" 1070 maxOccurs: "2" 1072 type: "master" 1074 definition: Contains the Segment Position of other Top-Level 1075 Elements. 1077 9.3.1.1. Seek Element 1079 name: "Seek" 1081 path: "1*(\Segment\SeekHead\Seek)" 1083 id: "0x4DBB" 1085 minOccurs: "1" 1087 type: "master" 1089 definition: Contains a single seek entry to an EBML Element. 1091 9.3.1.1.1. SeekID Element 1093 name: "SeekID" 1095 path: "1*1(\Segment\SeekHead\Seek\SeekID)" 1097 id: "0x53AB" 1099 minOccurs: "1" 1101 maxOccurs: "1" 1103 type: "binary" 1105 definition: The binary ID corresponding to the Element name. 1107 9.3.1.1.2. SeekPosition Element 1109 name: "SeekPosition" 1111 path: "1*1(\Segment\SeekHead\Seek\SeekPosition)" 1113 id: "0x53AC" 1115 minOccurs: "1" 1117 maxOccurs: "1" 1119 type: "uinteger" 1121 definition: The Segment Position of the Element. 1123 9.3.2. Info Element 1125 name: "Info" 1127 path: "1*(\Segment\Info)" 1129 id: "0x1549A966" 1131 minOccurs: "1" 1133 type: "master" 1135 recurring: "1" 1137 definition: Contains general information about the Segment. 1139 9.3.2.1. SegmentUID Element 1141 name: "SegmentUID" 1143 path: "0*1(\Segment\Info\SegmentUID)" 1145 id: "0x73A4" 1147 maxOccurs: "1" 1149 range: "not 0" 1151 type: "binary" 1153 definition: A randomly generated unique ID to identify the Segment 1154 amongst many others (128 bits). 1156 usage notes: If the Segment is a part of a Linked Segment then this 1157 Element is REQUIRED. 1159 9.3.2.2. SegmentFilename Element 1161 name: "SegmentFilename" 1163 path: "0*1(\Segment\Info\SegmentFilename)" 1165 id: "0x7384" 1167 maxOccurs: "1" 1169 type: "utf-8" 1171 definition: A filename corresponding to this Segment. 1173 9.3.2.3. PrevUID Element 1175 name: "PrevUID" 1177 path: "0*1(\Segment\Info\PrevUID)" 1179 id: "0x3CB923" 1181 maxOccurs: "1" 1183 type: "binary" 1185 definition: A unique ID to identify the previous Segment of a Linked 1186 Segment (128 bits). 1188 usage notes: If the Segment is a part of a Linked Segment that uses 1189 Hard Linking then either the PrevUID or the NextUID Element is 1190 REQUIRED. If a Segment contains a PrevUID but not a NextUID then it 1191 MAY be considered as the last Segment of the Linked Segment. The 1192 PrevUID MUST NOT be equal to the SegmentUID. 1194 9.3.2.4. PrevFilename Element 1196 name: "PrevFilename" 1198 path: "0*1(\Segment\Info\PrevFilename)" 1200 id: "0x3C83AB" 1202 maxOccurs: "1" 1204 type: "utf-8" 1206 definition: A filename corresponding to the file of the previous 1207 Linked Segment. 1209 usage notes: Provision of the previous filename is for display 1210 convenience, but PrevUID SHOULD be considered authoritative for 1211 identifying the previous Segment in a Linked Segment. 1213 9.3.2.5. NextUID Element 1215 name: "NextUID" 1217 path: "0*1(\Segment\Info\NextUID)" 1219 id: "0x3EB923" 1221 maxOccurs: "1" 1223 type: "binary" 1225 definition: A unique ID to identify the next Segment of a Linked 1226 Segment (128 bits). 1228 usage notes: If the Segment is a part of a Linked Segment that uses 1229 Hard Linking then either the PrevUID or the NextUID Element is 1230 REQUIRED. If a Segment contains a NextUID but not a PrevUID then it 1231 MAY be considered as the first Segment of the Linked Segment. The 1232 NextUID MUST NOT be equal to the SegmentUID. 1234 9.3.2.6. NextFilename Element 1236 name: "NextFilename" 1238 path: "0*1(\Segment\Info\NextFilename)" 1240 id: "0x3E83BB" 1242 maxOccurs: "1" 1244 type: "utf-8" 1246 definition: A filename corresponding to the file of the next Linked 1247 Segment. 1249 usage notes: Provision of the next filename is for display 1250 convenience, but NextUID SHOULD be considered authoritative for 1251 identifying the Next Segment. 1253 9.3.2.7. SegmentFamily Element 1255 name: "SegmentFamily" 1257 path: "0*(\Segment\Info\SegmentFamily)" 1259 id: "0x4444" 1261 type: "binary" 1263 definition: A randomly generated unique ID that all Segments of a 1264 Linked Segment MUST share (128 bits). 1266 usage notes: If the Segment is a part of a Linked Segment that uses 1267 Soft Linking then this Element is REQUIRED. 1269 9.3.2.8. ChapterTranslate Element 1271 name: "ChapterTranslate" 1273 path: "0*(\Segment\Info\ChapterTranslate)" 1275 id: "0x6924" 1277 type: "master" 1279 definition: A tuple of corresponding ID used by chapter codecs to 1280 represent this Segment. 1282 9.3.2.8.1. ChapterTranslateEditionUID Element 1284 name: "ChapterTranslateEditionUID" 1286 path: "0*(\Segment\Info\ChapterTranslate\ChapterTranslateEditionUID)" 1288 id: "0x69FC" 1290 type: "uinteger" 1292 definition: Specify an edition UID on which this correspondence 1293 applies. When not specified, it means for all editions found in the 1294 Segment. 1296 9.3.2.8.2. ChapterTranslateCodec Element 1298 name: "ChapterTranslateCodec" 1300 path: "1*1(\Segment\Info\ChapterTranslate\ChapterTranslateCodec)" 1302 id: "0x69BF" 1304 minOccurs: "1" 1306 maxOccurs: "1" 1308 type: "uinteger" 1310 definition: The chapter codec 1312 restrictions: 1314 +-------+-----------------+ 1315 | value | label | 1316 +=======+=================+ 1317 | "0" | Matroska Script | 1318 +-------+-----------------+ 1319 | "1" | DVD-menu | 1320 +-------+-----------------+ 1322 Table 10 1324 9.3.2.8.3. ChapterTranslateID Element 1326 name: "ChapterTranslateID" 1328 path: "1*1(\Segment\Info\ChapterTranslate\ChapterTranslateID)" 1329 id: "0x69A5" 1331 minOccurs: "1" 1333 maxOccurs: "1" 1335 type: "binary" 1337 definition: The binary value used to represent this Segment in the 1338 chapter codec data. The format depends on the ChapProcessCodecID 1339 used. 1341 9.3.2.9. TimestampScale Element 1343 name: "TimestampScale" 1345 path: "1*1(\Segment\Info\TimestampScale)" 1347 id: "0x2AD7B1" 1349 minOccurs: "1" 1351 maxOccurs: "1" 1353 range: "not 0" 1355 default: "1000000" 1357 type: "uinteger" 1359 definition: Timestamp scale in nanoseconds (1.000.000 means all 1360 timestamps in the Segment are expressed in milliseconds). 1362 9.3.2.10. Duration Element 1364 name: "Duration" 1366 path: "0*1(\Segment\Info\Duration)" 1368 id: "0x4489" 1370 maxOccurs: "1" 1372 range: "> 0x0p+0" 1374 type: "float" 1375 definition: Duration of the Segment in nanoseconds based on 1376 TimestampScale. 1378 9.3.2.11. DateUTC Element 1380 name: "DateUTC" 1382 path: "0*1(\Segment\Info\DateUTC)" 1384 id: "0x4461" 1386 maxOccurs: "1" 1388 type: "date" 1390 definition: The date and time that the Segment was created by the 1391 muxing application or library. 1393 9.3.2.12. Title Element 1395 name: "Title" 1397 path: "0*1(\Segment\Info\Title)" 1399 id: "0x7BA9" 1401 maxOccurs: "1" 1403 type: "utf-8" 1405 definition: General name of the Segment. 1407 9.3.2.13. MuxingApp Element 1409 name: "MuxingApp" 1411 path: "1*1(\Segment\Info\MuxingApp)" 1413 id: "0x4D80" 1415 minOccurs: "1" 1417 maxOccurs: "1" 1419 type: "utf-8" 1421 definition: Muxing application or library (example: "libmatroska- 1422 0.4.3"). 1424 usage notes: Include the full name of the application or library 1425 followed by the version number. 1427 9.3.2.14. WritingApp Element 1429 name: "WritingApp" 1431 path: "1*1(\Segment\Info\WritingApp)" 1433 id: "0x5741" 1435 minOccurs: "1" 1437 maxOccurs: "1" 1439 type: "utf-8" 1441 definition: Writing application (example: "mkvmerge-0.3.3"). 1443 usage notes: Include the full name of the application followed by the 1444 version number. 1446 9.3.3. Cluster Element 1448 name: "Cluster" 1450 path: "0*(\Segment\Cluster)" 1452 id: "0x1F43B675" 1454 type: "master" 1456 unknownsizeallowed: "1" 1458 definition: The Top-Level Element containing the (monolithic) Block 1459 structure. 1461 9.3.3.1. Timestamp Element 1463 name: "Timestamp" 1465 path: "1*1(\Segment\Cluster\Timestamp)" 1467 id: "0xE7" 1469 minOccurs: "1" 1471 maxOccurs: "1" 1472 type: "uinteger" 1474 definition: Absolute timestamp of the cluster (based on 1475 TimestampScale). 1477 9.3.3.2. SilentTracks Element 1479 name: "SilentTracks" 1481 path: "0*1(\Segment\Cluster\SilentTracks)" 1483 id: "0x5854" 1485 maxOccurs: "1" 1487 type: "master" 1489 definition: The list of tracks that are not used in that part of the 1490 stream. It is useful when using overlay tracks on seeking or to 1491 decide what track to use. 1493 9.3.3.2.1. SilentTrackNumber Element 1495 name: "SilentTrackNumber" 1497 path: "0*(\Segment\Cluster\SilentTracks\SilentTrackNumber)" 1499 id: "0x58D7" 1501 type: "uinteger" 1503 definition: One of the track number that are not used from now on in 1504 the stream. It could change later if not specified as silent in a 1505 further Cluster. 1507 9.3.3.3. Position Element 1509 name: "Position" 1511 path: "0*1(\Segment\Cluster\Position)" 1513 id: "0xA7" 1515 maxOccurs: "1" 1517 type: "uinteger" 1518 definition: The Segment Position of the Cluster in the Segment (0 in 1519 live streams). It might help to resynchronise offset on damaged 1520 streams. 1522 9.3.3.4. PrevSize Element 1524 name: "PrevSize" 1526 path: "0*1(\Segment\Cluster\PrevSize)" 1528 id: "0xAB" 1530 maxOccurs: "1" 1532 type: "uinteger" 1534 definition: Size of the previous Cluster, in octets. Can be useful 1535 for backward playing. 1537 9.3.3.5. SimpleBlock Element 1539 name: "SimpleBlock" 1541 path: "0*(\Segment\Cluster\SimpleBlock)" 1543 id: "0xA3" 1545 type: "binary" 1547 minver: "2" 1549 definition: Similar to Block but without all the extra information, 1550 mostly used to reduced overhead when no extra feature is needed. (see 1551 SimpleBlock Structure) 1553 9.3.3.6. BlockGroup Element 1555 name: "BlockGroup" 1557 path: "0*(\Segment\Cluster\BlockGroup)" 1559 id: "0xA0" 1561 type: "master" 1563 definition: Basic container of information containing a single Block 1564 and information specific to that Block. 1566 9.3.3.6.1. Block Element 1568 name: "Block" 1570 path: "1*1(\Segment\Cluster\BlockGroup\Block)" 1572 id: "0xA1" 1574 minOccurs: "1" 1576 maxOccurs: "1" 1578 type: "binary" 1580 definition: Block containing the actual data to be rendered and a 1581 timestamp relative to the Cluster Timestamp. (see Block Structure) 1583 9.3.3.6.2. BlockVirtual Element 1585 name: "BlockVirtual" 1587 path: "0*1(\Segment\Cluster\BlockGroup\BlockVirtual)" 1589 id: "0xA2" 1591 maxOccurs: "1" 1593 type: "binary" 1595 minver: "0" 1597 maxver: "0" 1599 definition: A Block with no data. It MUST be stored in the stream at 1600 the place the real Block would be in display order. (see Block 1601 Virtual) 1603 9.3.3.6.3. BlockAdditions Element 1605 name: "BlockAdditions" 1607 path: "0*1(\Segment\Cluster\BlockGroup\BlockAdditions)" 1609 id: "0x75A1" 1611 maxOccurs: "1" 1613 type: "master" 1614 definition: Contain additional blocks to complete the main one. An 1615 EBML parser that has no knowledge of the Block structure could still 1616 see and use/skip these data. 1618 9.3.3.6.3.1. BlockMore Element 1620 name: "BlockMore" 1622 path: "1*(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore)" 1624 id: "0xA6" 1626 minOccurs: "1" 1628 type: "master" 1630 definition: Contain the BlockAdditional and some parameters. 1632 9.3.3.6.3.2. BlockAddID Element 1634 name: "BlockAddID" 1636 path: "1*1(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\Block 1637 AddID)" 1639 id: "0xEE" 1641 minOccurs: "1" 1643 maxOccurs: "1" 1645 range: "not 0" 1647 default: "1" 1649 type: "uinteger" 1651 definition: An ID to identify the BlockAdditional level. A value of 1652 1 means the BlockAdditional data is interpreted as additional data 1653 passed to the codec with the Block data. 1655 9.3.3.6.3.3. BlockAdditional Element 1657 name: "BlockAdditional" 1659 path: "1*1(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\Block 1660 Additional)" 1661 id: "0xA5" 1663 minOccurs: "1" 1665 maxOccurs: "1" 1667 type: "binary" 1669 definition: Interpreted by the codec as it wishes (using the 1670 BlockAddID). 1672 9.3.3.6.4. BlockDuration Element 1674 name: "BlockDuration" 1676 path: "0*1(\Segment\Cluster\BlockGroup\BlockDuration)" 1678 id: "0x9B" 1680 minOccurs: see implementation notes 1682 maxOccurs: "1" 1684 default: see implementation notes 1686 type: "uinteger" 1688 definition: The duration of the Block (based on TimestampScale). The 1689 BlockDuration Element can be useful at the end of a Track to define 1690 the duration of the last frame (as there is no subsequent Block 1691 available), or when there is a break in a track like for subtitle 1692 tracks. 1694 implementation notes: 1696 +-----------+---------------------------------------------------+ 1697 | attribute | note | 1698 +===========+===================================================+ 1699 | minOccurs | BlockDuration MUST be set (minOccurs=1) if the | 1700 | | associated TrackEntry stores a DefaultDuration | 1701 | | value. | 1702 +-----------+---------------------------------------------------+ 1703 | default | When not written and with no DefaultDuration, the | 1704 | | value is assumed to be the difference between the | 1705 | | timestamp of this Block and the timestamp of the | 1706 | | next Block in "display" order (not coding order). | 1707 +-----------+---------------------------------------------------+ 1709 Table 11 1711 9.3.3.6.5. ReferencePriority Element 1713 name: "ReferencePriority" 1715 path: "1*1(\Segment\Cluster\BlockGroup\ReferencePriority)" 1717 id: "0xFA" 1719 minOccurs: "1" 1721 maxOccurs: "1" 1723 default: "0" 1725 type: "uinteger" 1727 definition: This frame is referenced and has the specified cache 1728 priority. In cache only a frame of the same or higher priority can 1729 replace this frame. A value of 0 means the frame is not referenced. 1731 9.3.3.6.6. ReferenceBlock Element 1733 name: "ReferenceBlock" 1735 path: "0*(\Segment\Cluster\BlockGroup\ReferenceBlock)" 1737 id: "0xFB" 1739 type: "integer" 1741 definition: Timestamp of another frame used as a reference (ie: B or 1742 P frame). The timestamp is relative to the block it's attached to. 1744 9.3.3.6.7. ReferenceVirtual Element 1746 name: "ReferenceVirtual" 1748 path: "0*1(\Segment\Cluster\BlockGroup\ReferenceVirtual)" 1750 id: "0xFD" 1752 maxOccurs: "1" 1754 type: "integer" 1756 minver: "0" 1758 maxver: "0" 1760 definition: The Segment Position of the data that would otherwise be 1761 in position of the virtual block. 1763 9.3.3.6.8. CodecState Element 1765 name: "CodecState" 1767 path: "0*1(\Segment\Cluster\BlockGroup\CodecState)" 1769 id: "0xA4" 1771 maxOccurs: "1" 1773 type: "binary" 1775 minver: "2" 1777 definition: The new codec state to use. Data interpretation is 1778 private to the codec. This information SHOULD always be referenced 1779 by a seek entry. 1781 9.3.3.6.9. DiscardPadding Element 1783 name: "DiscardPadding" 1785 path: "0*1(\Segment\Cluster\BlockGroup\DiscardPadding)" 1787 id: "0x75A2" 1789 maxOccurs: "1" 1791 type: "integer" 1792 minver: "4" 1794 definition: Duration in nanoseconds of the silent data added to the 1795 Block (padding at the end of the Block for positive value, at the 1796 beginning of the Block for negative value). The duration of 1797 DiscardPadding is not calculated in the duration of the TrackEntry 1798 and SHOULD be discarded during playback. 1800 9.3.3.6.10. Slices Element 1802 name: "Slices" 1804 path: "0*1(\Segment\Cluster\BlockGroup\Slices)" 1806 id: "0x8E" 1808 maxOccurs: "1" 1810 type: "master" 1812 definition: Contains slices description. 1814 9.3.3.6.10.1. TimeSlice Element 1816 name: "TimeSlice" 1818 path: "0*(\Segment\Cluster\BlockGroup\Slices\TimeSlice)" 1820 id: "0xE8" 1822 type: "master" 1824 maxver: "1" 1826 definition: Contains extra time information about the data contained 1827 in the Block. Being able to interpret this Element is not REQUIRED 1828 for playback. 1830 9.3.3.6.10.2. LaceNumber Element 1832 name: "LaceNumber" 1834 path: "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\LaceNumber)" 1836 id: "0xCC" 1838 maxOccurs: "1" 1839 default: "0" 1841 type: "uinteger" 1843 maxver: "1" 1845 definition: The reverse number of the frame in the lace (0 is the 1846 last frame, 1 is the next to last, etc). Being able to interpret 1847 this Element is not REQUIRED for playback. 1849 9.3.3.6.10.3. FrameNumber Element 1851 name: "FrameNumber" 1853 path: "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\FrameNumber)" 1855 id: "0xCD" 1857 maxOccurs: "1" 1859 default: "0" 1861 type: "uinteger" 1863 minver: "0" 1865 maxver: "0" 1867 definition: The number of the frame to generate from this lace with 1868 this delay (allow you to generate many frames from the same Block/ 1869 Frame). 1871 9.3.3.6.10.4. BlockAdditionID Element 1873 name: "BlockAdditionID" 1875 path: 1876 "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\BlockAdditionID)" 1878 id: "0xCB" 1880 maxOccurs: "1" 1882 default: "0" 1884 type: "uinteger" 1886 minver: "0" 1887 maxver: "0" 1889 definition: The ID of the BlockAdditional Element (0 is the main 1890 Block). 1892 9.3.3.6.10.5. Delay Element 1894 name: "Delay" 1896 path: "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\Delay)" 1898 id: "0xCE" 1900 maxOccurs: "1" 1902 default: "0" 1904 type: "uinteger" 1906 minver: "0" 1908 maxver: "0" 1910 definition: The (scaled) delay to apply to the Element. 1912 9.3.3.6.10.6. SliceDuration Element 1914 name: "SliceDuration" 1916 path: 1917 "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\SliceDuration)" 1919 id: "0xCF" 1921 maxOccurs: "1" 1923 default: "0" 1925 type: "uinteger" 1927 minver: "0" 1929 maxver: "0" 1931 definition: The (scaled) duration to apply to the Element. 1933 9.3.3.6.11. ReferenceFrame Element 1935 name: "ReferenceFrame" 1937 path: "0*1(\Segment\Cluster\BlockGroup\ReferenceFrame)" 1939 id: "0xC8" 1941 maxOccurs: "1" 1943 type: "master" 1945 minver: "0" 1947 maxver: "0" 1949 definition: DivX trick track extensions 1951 9.3.3.6.11.1. ReferenceOffset Element 1953 name: "ReferenceOffset" 1955 path: 1956 "1*1(\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceOffset)" 1958 id: "0xC9" 1960 minOccurs: "1" 1962 maxOccurs: "1" 1964 type: "uinteger" 1966 minver: "0" 1968 maxver: "0" 1970 definition: DivX trick track extensions 1972 9.3.3.6.11.2. ReferenceTimestamp Element 1974 name: "ReferenceTimestamp" 1976 path: 1977 "1*1(\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceTimestamp)" 1979 id: "0xCA" 1980 minOccurs: "1" 1982 maxOccurs: "1" 1984 type: "uinteger" 1986 minver: "0" 1988 maxver: "0" 1990 definition: DivX trick track extensions 1992 9.3.3.7. EncryptedBlock Element 1994 name: "EncryptedBlock" 1996 path: "0*(\Segment\Cluster\EncryptedBlock)" 1998 id: "0xAF" 2000 type: "binary" 2002 minver: "0" 2004 maxver: "0" 2006 definition: Similar to SimpleBlock but the data inside the Block are 2007 Transformed (encrypt and/or signed). (see EncryptedBlock Structure) 2009 9.3.4. Tracks Element 2011 name: "Tracks" 2013 path: "0*(\Segment\Tracks)" 2015 id: "0x1654AE6B" 2017 type: "master" 2019 recurring: "1" 2021 definition: A Top-Level Element of information with many tracks 2022 described. 2024 9.3.4.1. TrackEntry Element 2026 name: "TrackEntry" 2027 path: "1*(\Segment\Tracks\TrackEntry)" 2029 id: "0xAE" 2031 minOccurs: "1" 2033 type: "master" 2035 definition: Describes a track with all Elements. 2037 9.3.4.1.1. TrackNumber Element 2039 name: "TrackNumber" 2041 path: "1*1(\Segment\Tracks\TrackEntry\TrackNumber)" 2043 id: "0xD7" 2045 minOccurs: "1" 2047 maxOccurs: "1" 2049 range: "not 0" 2051 type: "uinteger" 2053 definition: The track number as used in the Block Header (using more 2054 than 127 tracks is not encouraged, though the design allows an 2055 unlimited number). 2057 9.3.4.1.2. TrackUID Element 2059 name: "TrackUID" 2061 path: "1*1(\Segment\Tracks\TrackEntry\TrackUID)" 2063 id: "0x73C5" 2065 minOccurs: "1" 2067 maxOccurs: "1" 2069 range: "not 0" 2071 type: "uinteger" 2073 definition: A unique ID to identify the Track. This SHOULD be kept 2074 the same when making a direct stream copy of the Track to another 2075 file. 2077 9.3.4.1.3. TrackType Element 2079 name: "TrackType" 2081 path: "1*1(\Segment\Tracks\TrackEntry\TrackType)" 2083 id: "0x83" 2085 minOccurs: "1" 2087 maxOccurs: "1" 2089 range: "1-254" 2091 type: "uinteger" 2093 definition: A set of track types coded on 8 bits. 2095 restrictions: 2097 +-------+----------+ 2098 | value | label | 2099 +=======+==========+ 2100 | "1" | video | 2101 +-------+----------+ 2102 | "2" | audio | 2103 +-------+----------+ 2104 | "3" | complex | 2105 +-------+----------+ 2106 | "16" | logo | 2107 +-------+----------+ 2108 | "17" | subtitle | 2109 +-------+----------+ 2110 | "18" | buttons | 2111 +-------+----------+ 2112 | "32" | control | 2113 +-------+----------+ 2114 | "33" | metadata | 2115 +-------+----------+ 2117 Table 12 2119 9.3.4.1.4. FlagEnabled Element 2121 name: "FlagEnabled" 2123 path: "1*1(\Segment\Tracks\TrackEntry\FlagEnabled)" 2125 id: "0xB9" 2127 minOccurs: "1" 2129 maxOccurs: "1" 2131 range: "0-1" 2133 default: "1" 2135 type: "uinteger" 2137 minver: "2" 2139 definition: Set if the track is usable. (1 bit) 2141 9.3.4.1.5. FlagDefault Element 2143 name: "FlagDefault" 2145 path: "1*1(\Segment\Tracks\TrackEntry\FlagDefault)" 2147 id: "0x88" 2149 minOccurs: "1" 2151 maxOccurs: "1" 2153 range: "0-1" 2155 default: "1" 2157 type: "uinteger" 2159 definition: Set if that track (audio, video or subs) SHOULD be active 2160 if no language found matches the user preference. (1 bit) 2162 9.3.4.1.6. FlagForced Element 2164 name: "FlagForced" 2166 path: "1*1(\Segment\Tracks\TrackEntry\FlagForced)" 2167 id: "0x55AA" 2169 minOccurs: "1" 2171 maxOccurs: "1" 2173 range: "0-1" 2175 default: "0" 2177 type: "uinteger" 2179 definition: Set if that track MUST be active during playback. There 2180 can be many forced track for a kind (audio, video or subs), the 2181 player SHOULD select the one which language matches the user 2182 preference or the default + forced track. Overlay MAY happen between 2183 a forced and non-forced track of the same kind. (1 bit) 2185 9.3.4.1.7. FlagLacing Element 2187 name: "FlagLacing" 2189 path: "1*1(\Segment\Tracks\TrackEntry\FlagLacing)" 2191 id: "0x9C" 2193 minOccurs: "1" 2195 maxOccurs: "1" 2197 range: "0-1" 2199 default: "1" 2201 type: "uinteger" 2203 definition: Set if the track MAY contain blocks using lacing. (1 bit) 2205 9.3.4.1.8. MinCache Element 2207 name: "MinCache" 2209 path: "1*1(\Segment\Tracks\TrackEntry\MinCache)" 2211 id: "0x6DE7" 2213 minOccurs: "1" 2214 maxOccurs: "1" 2216 default: "0" 2218 type: "uinteger" 2220 definition: The minimum number of frames a player SHOULD be able to 2221 cache during playback. If set to 0, the reference pseudo-cache 2222 system is not used. 2224 9.3.4.1.9. MaxCache Element 2226 name: "MaxCache" 2228 path: "0*1(\Segment\Tracks\TrackEntry\MaxCache)" 2230 id: "0x6DF8" 2232 maxOccurs: "1" 2234 type: "uinteger" 2236 definition: The maximum cache size necessary to store referenced 2237 frames in and the current frame. 0 means no cache is needed. 2239 9.3.4.1.10. DefaultDuration Element 2241 name: "DefaultDuration" 2243 path: "0*1(\Segment\Tracks\TrackEntry\DefaultDuration)" 2245 id: "0x23E383" 2247 maxOccurs: "1" 2249 range: "not 0" 2251 type: "uinteger" 2253 definition: Number of nanoseconds (not scaled via TimestampScale) per 2254 frame ('frame' in the Matroska sense -- one Element put into a 2255 (Simple)Block). 2257 9.3.4.1.11. DefaultDecodedFieldDuration Element 2259 name: "DefaultDecodedFieldDuration" 2261 path: "0*1(\Segment\Tracks\TrackEntry\DefaultDecodedFieldDuration)" 2262 id: "0x234E7A" 2264 maxOccurs: "1" 2266 range: "not 0" 2268 type: "uinteger" 2270 minver: "4" 2272 definition: The period in nanoseconds (not scaled by TimestampScale) 2273 between two successive fields at the output of the decoding process 2274 (see the notes) 2276 9.3.4.1.12. TrackTimestampScale Element 2278 name: "TrackTimestampScale" 2280 path: "1*1(\Segment\Tracks\TrackEntry\TrackTimestampScale)" 2282 id: "0x23314F" 2284 minOccurs: "1" 2286 maxOccurs: "1" 2288 range: "> 0x0p+0" 2290 default: "0x1p+0" 2292 type: "float" 2294 maxver: "3" 2296 definition: DEPRECATED, DO NOT USE. The scale to apply on this track 2297 to work at normal speed in relation with other tracks (mostly used to 2298 adjust video speed when the audio length differs). 2300 9.3.4.1.13. TrackOffset Element 2302 name: "TrackOffset" 2304 path: "0*1(\Segment\Tracks\TrackEntry\TrackOffset)" 2306 id: "0x537F" 2308 maxOccurs: "1" 2309 default: "0" 2311 type: "integer" 2313 minver: "0" 2315 maxver: "0" 2317 definition: A value to add to the Block's Timestamp. This can be 2318 used to adjust the playback offset of a track. 2320 9.3.4.1.14. MaxBlockAdditionID Element 2322 name: "MaxBlockAdditionID" 2324 path: "1*1(\Segment\Tracks\TrackEntry\MaxBlockAdditionID)" 2326 id: "0x55EE" 2328 minOccurs: "1" 2330 maxOccurs: "1" 2332 default: "0" 2334 type: "uinteger" 2336 definition: The maximum value of BlockAddID. A value 0 means there 2337 is no BlockAdditions for this track. 2339 9.3.4.1.15. BlockAdditionMapping Element 2341 name: "BlockAdditionMapping" 2343 path: "0*(\Segment\Tracks\TrackEntry\BlockAdditionMapping)" 2345 id: "0x41E4" 2347 type: "master" 2349 minver: "4" 2351 definition: Contains elements that describe each value of BlockAddID 2352 found in the Track. 2354 9.3.4.1.15.1. BlockAddIDValue Element 2356 name: "BlockAddIDValue" 2358 path: "1*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddID 2359 Value)" 2361 id: "0x41F0" 2363 minOccurs: "1" 2365 maxOccurs: "1" 2367 range: ">=2" 2369 type: "uinteger" 2371 minver: "4" 2373 definition: The BlockAddID value being described. To keep 2374 MaxBlockAdditionID as low as possible, small values SHOULD be used. 2376 9.3.4.1.15.2. BlockAddIDName Element 2378 name: "BlockAddIDName" 2380 path: 2381 "0*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDName)" 2383 id: "0x41A4" 2385 maxOccurs: "1" 2387 type: "string" 2389 minver: "4" 2391 definition: A human-friendly name describing the type of 2392 BlockAdditional data as defined by the associated Block Additional 2393 Mapping. 2395 9.3.4.1.15.3. BlockAddIDType Element 2397 name: "BlockAddIDType" 2399 path: 2400 "1*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDType)" 2401 id: "0x41E7" 2403 minOccurs: "1" 2405 maxOccurs: "1" 2407 default: "0" 2409 type: "uinteger" 2411 minver: "4" 2413 definition: Stores the registered identifer of the Block Additional 2414 Mapping to define how the BlockAdditional data should be handled. 2416 9.3.4.1.15.4. BlockAddIDExtraData Element 2418 name: "BlockAddIDExtraData" 2420 path: "0*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddID 2421 ExtraData)" 2423 id: "0x41E7" 2425 maxOccurs: "1" 2427 type: "binary" 2429 minver: "4" 2431 definition: Extra binary data that the BlockAddIDType can use to 2432 interpret the BlockAdditional data. The intepretation of the binary 2433 data depends on the BlockAddIDType value and the corresponding Block 2434 Additional Mapping. 2436 9.3.4.1.16. Name Element 2438 name: "Name" 2440 path: "0*1(\Segment\Tracks\TrackEntry\Name)" 2442 id: "0x536E" 2444 maxOccurs: "1" 2446 type: "utf-8" 2448 definition: A human-readable track name. 2450 9.3.4.1.17. Language Element 2452 name: "Language" 2454 path: "0*1(\Segment\Tracks\TrackEntry\Language)" 2456 id: "0x22B59C" 2458 maxOccurs: "1" 2460 default: "eng" 2462 type: "string" 2464 definition: Specifies the language of the track in the Matroska 2465 languages form. This Element MUST be ignored if the LanguageIETF 2466 Element is used in the same TrackEntry. 2468 9.3.4.1.18. LanguageIETF Element 2470 name: "LanguageIETF" 2472 path: "0*1(\Segment\Tracks\TrackEntry\LanguageIETF)" 2474 id: "0x22B59D" 2476 maxOccurs: "1" 2478 type: "string" 2480 minver: "4" 2482 definition: Specifies the language of the track according to BCP 47 2483 and using the IANA Language Subtag Registry. If this Element is 2484 used, then any Language Elements used in the same TrackEntry MUST be 2485 ignored. 2487 9.3.4.1.19. CodecID Element 2489 name: "CodecID" 2491 path: "1*1(\Segment\Tracks\TrackEntry\CodecID)" 2493 id: "0x86" 2495 minOccurs: "1" 2497 maxOccurs: "1" 2498 type: "string" 2500 definition: An ID corresponding to the codec, see the codec page for 2501 more info. 2503 9.3.4.1.20. CodecPrivate Element 2505 name: "CodecPrivate" 2507 path: "0*1(\Segment\Tracks\TrackEntry\CodecPrivate)" 2509 id: "0x63A2" 2511 maxOccurs: "1" 2513 type: "binary" 2515 definition: Private data only known to the codec. 2517 9.3.4.1.21. CodecName Element 2519 name: "CodecName" 2521 path: "0*1(\Segment\Tracks\TrackEntry\CodecName)" 2523 id: "0x258688" 2525 maxOccurs: "1" 2527 type: "utf-8" 2529 definition: A human-readable string specifying the codec. 2531 9.3.4.1.22. AttachmentLink Element 2533 name: "AttachmentLink" 2535 path: "0*1(\Segment\Tracks\TrackEntry\AttachmentLink)" 2537 id: "0x7446" 2539 maxOccurs: "1" 2541 range: "not 0" 2543 type: "uinteger" 2545 maxver: "3" 2546 definition: The UID of an attachment that is used by this codec. 2548 9.3.4.1.23. CodecSettings Element 2550 name: "CodecSettings" 2552 path: "0*1(\Segment\Tracks\TrackEntry\CodecSettings)" 2554 id: "0x3A9697" 2556 maxOccurs: "1" 2558 type: "utf-8" 2560 minver: "0" 2562 maxver: "0" 2564 definition: A string describing the encoding setting used. 2566 9.3.4.1.24. CodecInfoURL Element 2568 name: "CodecInfoURL" 2570 path: "0*(\Segment\Tracks\TrackEntry\CodecInfoURL)" 2572 id: "0x3B4040" 2574 type: "string" 2576 minver: "0" 2578 maxver: "0" 2580 definition: A URL to find information about the codec used. 2582 9.3.4.1.25. CodecDownloadURL Element 2584 name: "CodecDownloadURL" 2586 path: "0*(\Segment\Tracks\TrackEntry\CodecDownloadURL)" 2588 id: "0x26B240" 2590 type: "string" 2592 minver: "0" 2593 maxver: "0" 2595 definition: A URL to download about the codec used. 2597 9.3.4.1.26. CodecDecodeAll Element 2599 name: "CodecDecodeAll" 2601 path: "1*1(\Segment\Tracks\TrackEntry\CodecDecodeAll)" 2603 id: "0xAA" 2605 minOccurs: "1" 2607 maxOccurs: "1" 2609 range: "0-1" 2611 default: "1" 2613 type: "uinteger" 2615 minver: "2" 2617 definition: The codec can decode potentially damaged data (1 bit). 2619 9.3.4.1.27. TrackOverlay Element 2621 name: "TrackOverlay" 2623 path: "0*(\Segment\Tracks\TrackEntry\TrackOverlay)" 2625 id: "0x6FAB" 2627 type: "uinteger" 2629 definition: Specify that this track is an overlay track for the Track 2630 specified (in the u-integer). That means when this track has a gap 2631 (see SilentTracks) the overlay track SHOULD be used instead. The 2632 order of multiple TrackOverlay matters, the first one is the one that 2633 SHOULD be used. If not found it SHOULD be the second, etc. 2635 9.3.4.1.28. CodecDelay Element 2637 name: "CodecDelay" 2639 path: "0*1(\Segment\Tracks\TrackEntry\CodecDelay)" 2640 id: "0x56AA" 2642 maxOccurs: "1" 2644 default: "0" 2646 type: "uinteger" 2648 minver: "4" 2650 definition: CodecDelay is The codec-built-in delay in nanoseconds. 2651 This value MUST be subtracted from each block timestamp in order to 2652 get the actual timestamp. The value SHOULD be small so the muxing of 2653 tracks with the same actual timestamp are in the same Cluster. 2655 9.3.4.1.29. SeekPreRoll Element 2657 name: "SeekPreRoll" 2659 path: "1*1(\Segment\Tracks\TrackEntry\SeekPreRoll)" 2661 id: "0x56BB" 2663 minOccurs: "1" 2665 maxOccurs: "1" 2667 default: "0" 2669 type: "uinteger" 2671 minver: "4" 2673 definition: After a discontinuity, SeekPreRoll is the duration in 2674 nanoseconds of the data the decoder MUST decode before the decoded 2675 data is valid. 2677 9.3.4.1.30. TrackTranslate Element 2679 name: "TrackTranslate" 2681 path: "0*(\Segment\Tracks\TrackEntry\TrackTranslate)" 2683 id: "0x6624" 2685 type: "master" 2687 definition: The track identification for the given Chapter Codec. 2689 9.3.4.1.30.1. TrackTranslateEditionUID Element 2691 name: "TrackTranslateEditionUID" 2693 path: "0*(\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateEdi 2694 tionUID)" 2696 id: "0x66FC" 2698 type: "uinteger" 2700 definition: Specify an edition UID on which this translation applies. 2701 When not specified, it means for all editions found in the Segment. 2703 9.3.4.1.30.2. TrackTranslateCodec Element 2705 name: "TrackTranslateCodec" 2707 path: 2708 "1*1(\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateCodec)" 2710 id: "0x66BF" 2712 minOccurs: "1" 2714 maxOccurs: "1" 2716 type: "uinteger" 2718 definition: The chapter codec. 2720 restrictions: 2722 +-------+-----------------+ 2723 | value | label | 2724 +=======+=================+ 2725 | "0" | Matroska Script | 2726 +-------+-----------------+ 2727 | "1" | DVD-menu | 2728 +-------+-----------------+ 2730 Table 13 2732 9.3.4.1.30.3. TrackTranslateTrackID Element 2734 name: "TrackTranslateTrackID" 2735 path: "1*1(\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateTr 2736 ackID)" 2738 id: "0x66A5" 2740 minOccurs: "1" 2742 maxOccurs: "1" 2744 type: "binary" 2746 definition: The binary value used to represent this track in the 2747 chapter codec data. The format depends on the ChapProcessCodecID 2748 used. 2750 9.3.4.1.31. Video Element 2752 name: "Video" 2754 path: "0*1(\Segment\Tracks\TrackEntry\Video)" 2756 id: "0xE0" 2758 maxOccurs: "1" 2760 type: "master" 2762 definition: Video settings. 2764 9.3.4.1.31.1. FlagInterlaced Element 2766 name: "FlagInterlaced" 2768 path: "1*1(\Segment\Tracks\TrackEntry\Video\FlagInterlaced)" 2770 id: "0x9A" 2772 minOccurs: "1" 2774 maxOccurs: "1" 2776 range: "0-2" 2778 default: "0" 2780 type: "uinteger" 2782 minver: "2" 2783 definition: A flag to declare if the video is known to be progressive 2784 or interlaced and if applicable to declare details about the 2785 interlacement. 2787 restrictions: 2789 +-------+--------------+ 2790 | value | label | 2791 +=======+==============+ 2792 | "0" | undetermined | 2793 +-------+--------------+ 2794 | "1" | interlaced | 2795 +-------+--------------+ 2796 | "2" | progressive | 2797 +-------+--------------+ 2799 Table 14 2801 9.3.4.1.31.2. FieldOrder Element 2803 name: "FieldOrder" 2805 path: "1*1(\Segment\Tracks\TrackEntry\Video\FieldOrder)" 2807 id: "0x9D" 2809 minOccurs: "1" 2811 maxOccurs: "1" 2813 range: "0-14" 2815 default: "2" 2817 type: "uinteger" 2819 minver: "4" 2821 definition: Declare the field ordering of the video. If 2822 FlagInterlaced is not set to 1, this Element MUST be ignored. 2824 restrictions: 2826 +-------+--------------+-----------------------------------------+ 2827 | value | label | documentation | 2828 +=======+==============+=========================================+ 2829 | "0" | progressive | | 2830 +-------+--------------+-----------------------------------------+ 2831 | "1" | tff | Top field displayed first. Top field | 2832 | | | stored first. | 2833 +-------+--------------+-----------------------------------------+ 2834 | "2" | undetermined | | 2835 +-------+--------------+-----------------------------------------+ 2836 | "6" | bff | Bottom field displayed first. Bottom | 2837 | | | field stored first. | 2838 +-------+--------------+-----------------------------------------+ 2839 | "9" | bff(swapped) | Top field displayed first. Fields are | 2840 | | | interleaved in storage with the top | 2841 | | | line of the top field stored first. | 2842 +-------+--------------+-----------------------------------------+ 2843 | "14" | tff(swapped) | Bottom field displayed first. Fields | 2844 | | | are interleaved in storage with the top | 2845 | | | line of the top field stored first. | 2846 +-------+--------------+-----------------------------------------+ 2848 Table 15 2850 9.3.4.1.31.3. StereoMode Element 2852 name: "StereoMode" 2854 path: "0*1(\Segment\Tracks\TrackEntry\Video\StereoMode)" 2856 id: "0x53B8" 2858 maxOccurs: "1" 2860 default: "0" 2862 type: "uinteger" 2864 minver: "3" 2866 definition: Stereo-3D video mode. There are some more details on 3D 2867 support in the Specification Notes. 2869 restrictions: 2871 +-------+---------------------------------------------------+ 2872 | value | label | 2873 +=======+===================================================+ 2874 | "0" | mono | 2875 +-------+---------------------------------------------------+ 2876 | "1" | side by side (left eye first) | 2877 +-------+---------------------------------------------------+ 2878 | "2" | top - bottom (right eye is first) | 2879 +-------+---------------------------------------------------+ 2880 | "3" | top - bottom (left eye is first) | 2881 +-------+---------------------------------------------------+ 2882 | "4" | checkboard (right eye is first) | 2883 +-------+---------------------------------------------------+ 2884 | "5" | checkboard (left eye is first) | 2885 +-------+---------------------------------------------------+ 2886 | "6" | row interleaved (right eye is first) | 2887 +-------+---------------------------------------------------+ 2888 | "7" | row interleaved (left eye is first) | 2889 +-------+---------------------------------------------------+ 2890 | "8" | column interleaved (right eye is first) | 2891 +-------+---------------------------------------------------+ 2892 | "9" | column interleaved (left eye is first) | 2893 +-------+---------------------------------------------------+ 2894 | "10" | anaglyph (cyan/red) | 2895 +-------+---------------------------------------------------+ 2896 | "11" | side by side (right eye first) | 2897 +-------+---------------------------------------------------+ 2898 | "12" | anaglyph (green/magenta) | 2899 +-------+---------------------------------------------------+ 2900 | "13" | both eyes laced in one Block (left eye is first) | 2901 +-------+---------------------------------------------------+ 2902 | "14" | both eyes laced in one Block (right eye is first) | 2903 +-------+---------------------------------------------------+ 2905 Table 16 2907 9.3.4.1.31.4. AlphaMode Element 2909 name: "AlphaMode" 2911 path: "0*1(\Segment\Tracks\TrackEntry\Video\AlphaMode)" 2913 id: "0x53C0" 2915 maxOccurs: "1" 2917 default: "0" 2918 type: "uinteger" 2920 minver: "3" 2922 definition: Alpha Video Mode. Presence of this Element indicates 2923 that the BlockAdditional Element could contain Alpha data. 2925 9.3.4.1.31.5. OldStereoMode Element 2927 name: "OldStereoMode" 2929 path: "0*1(\Segment\Tracks\TrackEntry\Video\OldStereoMode)" 2931 id: "0x53B9" 2933 maxOccurs: "1" 2935 type: "uinteger" 2937 maxver: "0" 2939 definition: DEPRECATED, DO NOT USE. Bogus StereoMode value used in 2940 old versions of libmatroska. 2942 restrictions: 2944 +-------+-----------+ 2945 | value | label | 2946 +=======+===========+ 2947 | "0" | mono | 2948 +-------+-----------+ 2949 | "1" | right eye | 2950 +-------+-----------+ 2951 | "2" | left eye | 2952 +-------+-----------+ 2953 | "3" | both eyes | 2954 +-------+-----------+ 2956 Table 17 2958 9.3.4.1.31.6. PixelWidth Element 2960 name: "PixelWidth" 2962 path: "1*1(\Segment\Tracks\TrackEntry\Video\PixelWidth)" 2964 id: "0xB0" 2965 minOccurs: "1" 2967 maxOccurs: "1" 2969 range: "not 0" 2971 type: "uinteger" 2973 definition: Width of the encoded video frames in pixels. 2975 9.3.4.1.31.7. PixelHeight Element 2977 name: "PixelHeight" 2979 path: "1*1(\Segment\Tracks\TrackEntry\Video\PixelHeight)" 2981 id: "0xBA" 2983 minOccurs: "1" 2985 maxOccurs: "1" 2987 range: "not 0" 2989 type: "uinteger" 2991 definition: Height of the encoded video frames in pixels. 2993 9.3.4.1.31.8. PixelCropBottom Element 2995 name: "PixelCropBottom" 2997 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropBottom)" 2999 id: "0x54AA" 3001 maxOccurs: "1" 3003 default: "0" 3005 type: "uinteger" 3007 definition: The number of video pixels to remove at the bottom of the 3008 image. 3010 9.3.4.1.31.9. PixelCropTop Element 3012 name: "PixelCropTop" 3014 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropTop)" 3016 id: "0x54BB" 3018 maxOccurs: "1" 3020 default: "0" 3022 type: "uinteger" 3024 definition: The number of video pixels to remove at the top of the 3025 image. 3027 9.3.4.1.31.10. PixelCropLeft Element 3029 name: "PixelCropLeft" 3031 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropLeft)" 3033 id: "0x54CC" 3035 maxOccurs: "1" 3037 default: "0" 3039 type: "uinteger" 3041 definition: The number of video pixels to remove on the left of the 3042 image. 3044 9.3.4.1.31.11. PixelCropRight Element 3046 name: "PixelCropRight" 3048 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropRight)" 3050 id: "0x54DD" 3052 maxOccurs: "1" 3054 default: "0" 3056 type: "uinteger" 3057 definition: The number of video pixels to remove on the right of the 3058 image. 3060 9.3.4.1.31.12. DisplayWidth Element 3062 name: "DisplayWidth" 3064 path: "0*1(\Segment\Tracks\TrackEntry\Video\DisplayWidth)" 3066 id: "0x54B0" 3068 maxOccurs: "1" 3070 range: "not 0" 3072 default: see implementation notes 3074 type: "uinteger" 3076 definition: Width of the video frames to display. Applies to the 3077 video frame after cropping (PixelCrop* Elements). 3079 implementation notes: 3081 +-----------+-------------------------------------------------+ 3082 | attribute | note | 3083 +===========+=================================================+ 3084 | default | If the DisplayUnit of the same TrackEntry is 0, | 3085 | | then the default value for DisplayWidth is | 3086 | | equal to PixelWidth - PixelCropLeft - | 3087 | | PixelCropRight, else there is no default value. | 3088 +-----------+-------------------------------------------------+ 3090 Table 18 3092 9.3.4.1.31.13. DisplayHeight Element 3094 name: "DisplayHeight" 3096 path: "0*1(\Segment\Tracks\TrackEntry\Video\DisplayHeight)" 3098 id: "0x54BA" 3100 maxOccurs: "1" 3102 range: "not 0" 3104 default: see implementation notes 3105 type: "uinteger" 3107 definition: Height of the video frames to display. Applies to the 3108 video frame after cropping (PixelCrop* Elements). 3110 implementation notes: 3112 +-----------+--------------------------------------------------+ 3113 | attribute | note | 3114 +===========+==================================================+ 3115 | default | If the DisplayUnit of the same TrackEntry is 0, | 3116 | | then the default value for DisplayHeight is | 3117 | | equal to PixelHeight - PixelCropTop - | 3118 | | PixelCropBottom, else there is no default value. | 3119 +-----------+--------------------------------------------------+ 3121 Table 19 3123 9.3.4.1.31.14. DisplayUnit Element 3125 name: "DisplayUnit" 3127 path: "0*1(\Segment\Tracks\TrackEntry\Video\DisplayUnit)" 3129 id: "0x54B2" 3131 maxOccurs: "1" 3133 default: "0" 3135 type: "uinteger" 3137 definition: How DisplayWidth & DisplayHeight are interpreted. 3139 restrictions: 3141 +-------+----------------------+ 3142 | value | label | 3143 +=======+======================+ 3144 | "0" | pixels | 3145 +-------+----------------------+ 3146 | "1" | centimeters | 3147 +-------+----------------------+ 3148 | "2" | inches | 3149 +-------+----------------------+ 3150 | "3" | display aspect ratio | 3151 +-------+----------------------+ 3152 | "4" | unknown | 3153 +-------+----------------------+ 3155 Table 20 3157 9.3.4.1.31.15. AspectRatioType Element 3159 name: "AspectRatioType" 3161 path: "0*1(\Segment\Tracks\TrackEntry\Video\AspectRatioType)" 3163 id: "0x54B3" 3165 maxOccurs: "1" 3167 default: "0" 3169 type: "uinteger" 3171 definition: Specify the possible modifications to the aspect ratio. 3173 restrictions: 3175 +-------+-------------------+ 3176 | value | label | 3177 +=======+===================+ 3178 | "0" | free resizing | 3179 +-------+-------------------+ 3180 | "1" | keep aspect ratio | 3181 +-------+-------------------+ 3182 | "2" | fixed | 3183 +-------+-------------------+ 3185 Table 21 3187 9.3.4.1.31.16. ColourSpace Element 3189 name: "ColourSpace" 3191 path: "0*1(\Segment\Tracks\TrackEntry\Video\ColourSpace)" 3193 id: "0x2EB524" 3195 minOccurs: see implementation notes 3197 maxOccurs: "1" 3199 type: "binary" 3201 definition: Specify the pixel format used for the Track's data as a 3202 FourCC. This value is similar in scope to the biCompression value of 3203 AVI's BITMAPINFOHEADER. 3205 implementation notes: 3207 +-----------+--------------------------------------------+ 3208 | attribute | note | 3209 +===========+============================================+ 3210 | minOccurs | ColourSpace MUST be set (minOccurs=1) in | 3211 | | TrackEntry when the CodecID Element of the | 3212 | | TrackEntry is set to "V_UNCOMPRESSED". | 3213 +-----------+--------------------------------------------+ 3215 Table 22 3217 9.3.4.1.31.17. GammaValue Element 3219 name: "GammaValue" 3221 path: "0*1(\Segment\Tracks\TrackEntry\Video\GammaValue)" 3223 id: "0x2FB523" 3225 maxOccurs: "1" 3227 range: "> 0x0p+0" 3229 type: "float" 3231 minver: "0" 3233 maxver: "0" 3234 definition: Gamma Value. 3236 9.3.4.1.31.18. FrameRate Element 3238 name: "FrameRate" 3240 path: "0*1(\Segment\Tracks\TrackEntry\Video\FrameRate)" 3242 id: "0x2383E3" 3244 maxOccurs: "1" 3246 range: "> 0x0p+0" 3248 type: "float" 3250 minver: "0" 3252 maxver: "0" 3254 definition: Number of frames per second. Informational only. 3256 9.3.4.1.31.19. Colour Element 3258 name: "Colour" 3260 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour)" 3262 id: "0x55B0" 3264 maxOccurs: "1" 3266 type: "master" 3268 minver: "4" 3270 definition: Settings describing the colour format. 3272 9.3.4.1.31.20. MatrixCoefficients Element 3274 name: "MatrixCoefficients" 3276 path: 3277 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MatrixCoefficients)" 3279 id: "0x55B1" 3281 maxOccurs: "1" 3282 default: "2" 3284 type: "uinteger" 3286 minver: "4" 3288 definition: The Matrix Coefficients of the video used to derive luma 3289 and chroma values from red, green, and blue color primaries. For 3290 clarity, the value and meanings for MatrixCoefficients are adopted 3291 from Table 4 of ISO/IEC 23001-8:2016 or ITU-T H.273. 3293 restrictions: 3295 +-------+---------------------------------------+ 3296 | value | label | 3297 +=======+=======================================+ 3298 | "0" | Identity | 3299 +-------+---------------------------------------+ 3300 | "1" | ITU-R BT.709 | 3301 +-------+---------------------------------------+ 3302 | "2" | unspecified | 3303 +-------+---------------------------------------+ 3304 | "3" | reserved | 3305 +-------+---------------------------------------+ 3306 | "4" | US FCC 73.682 | 3307 +-------+---------------------------------------+ 3308 | "5" | ITU-R BT.470BG | 3309 +-------+---------------------------------------+ 3310 | "6" | SMPTE 170M | 3311 +-------+---------------------------------------+ 3312 | "7" | SMPTE 240M | 3313 +-------+---------------------------------------+ 3314 | "8" | YCoCg | 3315 +-------+---------------------------------------+ 3316 | "9" | BT2020 Non-constant Luminance | 3317 +-------+---------------------------------------+ 3318 | "10" | BT2020 Constant Luminance | 3319 +-------+---------------------------------------+ 3320 | "11" | SMPTE ST 2085 | 3321 +-------+---------------------------------------+ 3322 | "12" | Chroma-derived Non-constant Luminance | 3323 +-------+---------------------------------------+ 3324 | "13" | Chroma-derived Constant Luminance | 3325 +-------+---------------------------------------+ 3326 | "14" | ITU-R BT.2100-0 | 3327 +-------+---------------------------------------+ 3329 Table 23 3331 9.3.4.1.31.21. BitsPerChannel Element 3333 name: "BitsPerChannel" 3335 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\BitsPerChannel)" 3337 id: "0x55B2" 3339 maxOccurs: "1" 3341 default: "0" 3343 type: "uinteger" 3345 minver: "4" 3347 definition: Number of decoded bits per channel. A value of 0 3348 indicates that the BitsPerChannel is unspecified. 3350 9.3.4.1.31.22. ChromaSubsamplingHorz Element 3352 name: "ChromaSubsamplingHorz" 3354 path: 3355 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingHorz)" 3357 id: "0x55B3" 3359 maxOccurs: "1" 3361 type: "uinteger" 3363 minver: "4" 3365 definition: The amount of pixels to remove in the Cr and Cb channels 3366 for every pixel not removed horizontally. Example: For video with 3367 4:2:0 chroma subsampling, the ChromaSubsamplingHorz SHOULD be set to 3368 1. 3370 9.3.4.1.31.23. ChromaSubsamplingVert Element 3372 name: "ChromaSubsamplingVert" 3374 path: 3375 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingVert)" 3377 id: "0x55B4" 3378 maxOccurs: "1" 3380 type: "uinteger" 3382 minver: "4" 3384 definition: The amount of pixels to remove in the Cr and Cb channels 3385 for every pixel not removed vertically. Example: For video with 3386 4:2:0 chroma subsampling, the ChromaSubsamplingVert SHOULD be set to 3387 1. 3389 9.3.4.1.31.24. CbSubsamplingHorz Element 3391 name: "CbSubsamplingHorz" 3393 path: 3394 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingHorz)" 3396 id: "0x55B5" 3398 maxOccurs: "1" 3400 type: "uinteger" 3402 minver: "4" 3404 definition: The amount of pixels to remove in the Cb channel for 3405 every pixel not removed horizontally. This is additive with 3406 ChromaSubsamplingHorz. Example: For video with 4:2:1 chroma 3407 subsampling, the ChromaSubsamplingHorz SHOULD be set to 1 and 3408 CbSubsamplingHorz SHOULD be set to 1. 3410 9.3.4.1.31.25. CbSubsamplingVert Element 3412 name: "CbSubsamplingVert" 3414 path: 3415 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingVert)" 3417 id: "0x55B6" 3419 maxOccurs: "1" 3421 type: "uinteger" 3423 minver: "4" 3424 definition: The amount of pixels to remove in the Cb channel for 3425 every pixel not removed vertically. This is additive with 3426 ChromaSubsamplingVert. 3428 9.3.4.1.31.26. ChromaSitingHorz Element 3430 name: "ChromaSitingHorz" 3432 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingHorz)" 3434 id: "0x55B7" 3436 maxOccurs: "1" 3438 default: "0" 3440 type: "uinteger" 3442 minver: "4" 3444 definition: How chroma is subsampled horizontally. 3446 restrictions: 3448 +-------+-----------------+ 3449 | value | label | 3450 +=======+=================+ 3451 | "0" | unspecified | 3452 +-------+-----------------+ 3453 | "1" | left collocated | 3454 +-------+-----------------+ 3455 | "2" | half | 3456 +-------+-----------------+ 3458 Table 24 3460 9.3.4.1.31.27. ChromaSitingVert Element 3462 name: "ChromaSitingVert" 3464 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingVert)" 3466 id: "0x55B8" 3468 maxOccurs: "1" 3470 default: "0" 3471 type: "uinteger" 3473 minver: "4" 3475 definition: How chroma is subsampled vertically. 3477 restrictions: 3479 +-------+----------------+ 3480 | value | label | 3481 +=======+================+ 3482 | "0" | unspecified | 3483 +-------+----------------+ 3484 | "1" | top collocated | 3485 +-------+----------------+ 3486 | "2" | half | 3487 +-------+----------------+ 3489 Table 25 3491 9.3.4.1.31.28. Range Element 3493 name: "Range" 3495 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\Range)" 3497 id: "0x55B9" 3499 maxOccurs: "1" 3501 default: "0" 3503 type: "uinteger" 3505 minver: "4" 3507 definition: Clipping of the color ranges. 3509 restrictions: 3511 +-------+-------------------------------------------------------+ 3512 | value | label | 3513 +=======+=======================================================+ 3514 | "0" | unspecified | 3515 +-------+-------------------------------------------------------+ 3516 | "1" | broadcast range | 3517 +-------+-------------------------------------------------------+ 3518 | "2" | full range (no clipping) | 3519 +-------+-------------------------------------------------------+ 3520 | "3" | defined by MatrixCoefficients/TransferCharacteristics | 3521 +-------+-------------------------------------------------------+ 3523 Table 26 3525 9.3.4.1.31.29. TransferCharacteristics Element 3527 name: "TransferCharacteristics" 3529 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\TransferCharacteri 3530 stics)" 3532 id: "0x55BA" 3534 maxOccurs: "1" 3536 default: "2" 3538 type: "uinteger" 3540 minver: "4" 3542 definition: The transfer characteristics of the video. For clarity, 3543 the value and meanings for TransferCharacteristics are adopted from 3544 Table 3 of ISO/IEC 23091-4 or ITU-T H.273. 3546 restrictions: 3548 +-------+---------------------------------------+ 3549 | value | label | 3550 +=======+=======================================+ 3551 | "0" | reserved | 3552 +-------+---------------------------------------+ 3553 | "1" | ITU-R BT.709 | 3554 +-------+---------------------------------------+ 3555 | "2" | unspecified | 3556 +-------+---------------------------------------+ 3557 | "3" | reserved | 3558 +-------+---------------------------------------+ 3559 | "4" | Gamma 2.2 curve - BT.470M | 3560 +-------+---------------------------------------+ 3561 | "5" | Gamma 2.8 curve - BT.470BG | 3562 +-------+---------------------------------------+ 3563 | "6" | SMPTE 170M | 3564 +-------+---------------------------------------+ 3565 | "7" | SMPTE 240M | 3566 +-------+---------------------------------------+ 3567 | "8" | Linear | 3568 +-------+---------------------------------------+ 3569 | "9" | Log | 3570 +-------+---------------------------------------+ 3571 | "10" | Log Sqrt | 3572 +-------+---------------------------------------+ 3573 | "11" | IEC 61966-2-4 | 3574 +-------+---------------------------------------+ 3575 | "12" | ITU-R BT.1361 Extended Colour Gamut | 3576 +-------+---------------------------------------+ 3577 | "13" | IEC 61966-2-1 | 3578 +-------+---------------------------------------+ 3579 | "14" | ITU-R BT.2020 10 bit | 3580 +-------+---------------------------------------+ 3581 | "15" | ITU-R BT.2020 12 bit | 3582 +-------+---------------------------------------+ 3583 | "16" | ITU-R BT.2100 Perceptual Quantization | 3584 +-------+---------------------------------------+ 3585 | "17" | SMPTE ST 428-1 | 3586 +-------+---------------------------------------+ 3587 | "18" | ARIB STD-B67 (HLG) | 3588 +-------+---------------------------------------+ 3590 Table 27 3592 9.3.4.1.31.30. Primaries Element 3594 name: "Primaries" 3595 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\Primaries)" 3597 id: "0x55BB" 3599 maxOccurs: "1" 3601 default: "2" 3603 type: "uinteger" 3605 minver: "4" 3607 definition: The colour primaries of the video. For clarity, the 3608 value and meanings for Primaries are adopted from Table 2 of ISO/IEC 3609 23091-4 or ITU-T H.273. 3611 restrictions: 3613 +-------+----------------------------------------+ 3614 | value | label | 3615 +=======+========================================+ 3616 | "0" | reserved | 3617 +-------+----------------------------------------+ 3618 | "1" | ITU-R BT.709 | 3619 +-------+----------------------------------------+ 3620 | "2" | unspecified | 3621 +-------+----------------------------------------+ 3622 | "3" | reserved | 3623 +-------+----------------------------------------+ 3624 | "4" | ITU-R BT.470M | 3625 +-------+----------------------------------------+ 3626 | "5" | ITU-R BT.470BG - BT.601 625 | 3627 +-------+----------------------------------------+ 3628 | "6" | ITU-R BT.601 525 - SMPTE 170M | 3629 +-------+----------------------------------------+ 3630 | "7" | SMPTE 240M | 3631 +-------+----------------------------------------+ 3632 | "8" | FILM | 3633 +-------+----------------------------------------+ 3634 | "9" | ITU-R BT.2020 | 3635 +-------+----------------------------------------+ 3636 | "10" | SMPTE ST 428-1 | 3637 +-------+----------------------------------------+ 3638 | "11" | SMPTE RP 432-2 | 3639 +-------+----------------------------------------+ 3640 | "12" | SMPTE EG 432-2 | 3641 +-------+----------------------------------------+ 3642 | "22" | EBU Tech. 3213-E - JEDEC P22 phosphors | 3643 +-------+----------------------------------------+ 3645 Table 28 3647 9.3.4.1.31.31. MaxCLL Element 3649 name: "MaxCLL" 3651 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MaxCLL)" 3653 id: "0x55BC" 3655 maxOccurs: "1" 3657 type: "uinteger" 3659 minver: "4" 3660 definition: Maximum brightness of a single pixel (Maximum Content 3661 Light Level) in candelas per square meter (cd/m^2). 3663 9.3.4.1.31.32. MaxFALL Element 3665 name: "MaxFALL" 3667 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MaxFALL)" 3669 id: "0x55BD" 3671 maxOccurs: "1" 3673 type: "uinteger" 3675 minver: "4" 3677 definition: Maximum brightness of a single full frame (Maximum Frame- 3678 Average Light Level) in candelas per square meter (cd/m^2). 3680 9.3.4.1.31.33. MasteringMetadata Element 3682 name: "MasteringMetadata" 3684 path: 3685 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata)" 3687 id: "0x55D0" 3689 maxOccurs: "1" 3691 type: "master" 3693 minver: "4" 3695 definition: SMPTE 2086 mastering data. 3697 9.3.4.1.31.34. PrimaryRChromaticityX Element 3699 name: "PrimaryRChromaticityX" 3701 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3702 PrimaryRChromaticityX)" 3704 id: "0x55D1" 3706 maxOccurs: "1" 3707 range: "0-1" 3709 type: "float" 3711 minver: "4" 3713 definition: Red X chromaticity coordinate as defined by CIE 1931. 3715 9.3.4.1.31.35. PrimaryRChromaticityY Element 3717 name: "PrimaryRChromaticityY" 3719 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3720 PrimaryRChromaticityY)" 3722 id: "0x55D2" 3724 maxOccurs: "1" 3726 range: "0-1" 3728 type: "float" 3730 minver: "4" 3732 definition: Red Y chromaticity coordinate as defined by CIE 1931. 3734 9.3.4.1.31.36. PrimaryGChromaticityX Element 3736 name: "PrimaryGChromaticityX" 3738 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3739 PrimaryGChromaticityX)" 3741 id: "0x55D3" 3743 maxOccurs: "1" 3745 range: "0-1" 3747 type: "float" 3749 minver: "4" 3751 definition: Green X chromaticity coordinate as defined by CIE 1931. 3753 9.3.4.1.31.37. PrimaryGChromaticityY Element 3755 name: "PrimaryGChromaticityY" 3757 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3758 PrimaryGChromaticityY)" 3760 id: "0x55D4" 3762 maxOccurs: "1" 3764 range: "0-1" 3766 type: "float" 3768 minver: "4" 3770 definition: Green Y chromaticity coordinate as defined by CIE 1931. 3772 9.3.4.1.31.38. PrimaryBChromaticityX Element 3774 name: "PrimaryBChromaticityX" 3776 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3777 PrimaryBChromaticityX)" 3779 id: "0x55D5" 3781 maxOccurs: "1" 3783 range: "0-1" 3785 type: "float" 3787 minver: "4" 3789 definition: Blue X chromaticity coordinate as defined by CIE 1931. 3791 9.3.4.1.31.39. PrimaryBChromaticityY Element 3793 name: "PrimaryBChromaticityY" 3795 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3796 PrimaryBChromaticityY)" 3798 id: "0x55D6" 3800 maxOccurs: "1" 3801 range: "0-1" 3803 type: "float" 3805 minver: "4" 3807 definition: Blue Y chromaticity coordinate as defined by CIE 1931. 3809 9.3.4.1.31.40. WhitePointChromaticityX Element 3811 name: "WhitePointChromaticityX" 3813 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3814 WhitePointChromaticityX)" 3816 id: "0x55D7" 3818 maxOccurs: "1" 3820 range: "0-1" 3822 type: "float" 3824 minver: "4" 3826 definition: White X chromaticity coordinate as defined by CIE 1931. 3828 9.3.4.1.31.41. WhitePointChromaticityY Element 3830 name: "WhitePointChromaticityY" 3832 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3833 WhitePointChromaticityY)" 3835 id: "0x55D8" 3837 maxOccurs: "1" 3839 range: "0-1" 3841 type: "float" 3843 minver: "4" 3845 definition: White Y chromaticity coordinate as defined by CIE 1931. 3847 9.3.4.1.31.42. LuminanceMax Element 3849 name: "LuminanceMax" 3851 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3852 LuminanceMax)" 3854 id: "0x55D9" 3856 maxOccurs: "1" 3858 range: ">= 0x0p+0" 3860 type: "float" 3862 minver: "4" 3864 definition: Maximum luminance. Represented in candelas per square 3865 meter (cd/m^2). 3867 9.3.4.1.31.43. LuminanceMin Element 3869 name: "LuminanceMin" 3871 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3872 LuminanceMin)" 3874 id: "0x55DA" 3876 maxOccurs: "1" 3878 range: ">= 0x0p+0" 3880 type: "float" 3882 minver: "4" 3884 definition: Minimum luminance. Represented in candelas per square 3885 meter (cd/m^2). 3887 9.3.4.1.31.44. Projection Element 3889 name: "Projection" 3891 path: "0*1(\Segment\Tracks\TrackEntry\Video\Projection)" 3893 id: "0x7670" 3894 maxOccurs: "1" 3896 type: "master" 3898 minver: "4" 3900 definition: Describes the video projection details. Used to render 3901 spherical and VR videos. 3903 9.3.4.1.31.45. ProjectionType Element 3905 name: "ProjectionType" 3907 path: 3908 "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionType)" 3910 id: "0x7671" 3912 minOccurs: "1" 3914 maxOccurs: "1" 3916 range: "0-3" 3918 default: "0" 3920 type: "uinteger" 3922 minver: "4" 3924 definition: Describes the projection used for this video track. 3926 restrictions: 3928 +-------+-----------------+ 3929 | value | label | 3930 +=======+=================+ 3931 | "0" | rectangular | 3932 +-------+-----------------+ 3933 | "1" | equirectangular | 3934 +-------+-----------------+ 3935 | "2" | cubemap | 3936 +-------+-----------------+ 3937 | "3" | mesh | 3938 +-------+-----------------+ 3940 Table 29 3942 9.3.4.1.31.46. ProjectionPrivate Element 3944 name: "ProjectionPrivate" 3946 path: 3947 "0*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPrivate)" 3949 id: "0x7672" 3951 maxOccurs: "1" 3953 type: "binary" 3955 minver: "4" 3957 definition: Private data that only applies to a specific 3958 projection.SemanticsIf ProjectionType equals 0 (Rectangular), then 3959 this element must not be present.If ProjectionType equals 1 3960 (Equirectangular), then this element must be present and contain the 3961 same binary data that would be stored inside an ISOBMFF 3962 Equirectangular Projection Box ('equi').If ProjectionType equals 2 3963 (Cubemap), then this element must be present and contain the same 3964 binary data that would be stored inside an ISOBMFF Cubemap Projection 3965 Box ('cbmp').If ProjectionType equals 3 (Mesh), then this element 3966 must be present and contain the same binary data that would be stored 3967 inside an ISOBMFF Mesh Projection Box ('mshp').Note: ISOBMFF box size 3968 and fourcc fields are not included in the binary data, but the 3969 FullBox version and flag fields are. This is to avoid redundant 3970 framing information while preserving versioning and semantics between 3971 the two container formats. 3973 9.3.4.1.31.47. ProjectionPoseYaw Element 3975 name: "ProjectionPoseYaw" 3977 path: 3978 "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseYaw)" 3980 id: "0x7673" 3982 minOccurs: "1" 3984 maxOccurs: "1" 3986 default: "0x0p+0" 3988 type: "float" 3989 minver: "4" 3991 definition: Specifies a yaw rotation to the projection.SemanticsValue 3992 represents a clockwise rotation, in degrees, around the up vector. 3993 This rotation must be applied before any ProjectionPosePitch or 3994 ProjectionPoseRoll rotations. The value of this field should be in 3995 the -180 to 180 degree range. 3997 9.3.4.1.31.48. ProjectionPosePitch Element 3999 name: "ProjectionPosePitch" 4001 path: "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPose 4002 Pitch)" 4004 id: "0x7674" 4006 minOccurs: "1" 4008 maxOccurs: "1" 4010 default: "0x0p+0" 4012 type: "float" 4014 minver: "4" 4016 definition: Specifies a pitch rotation to the 4017 projection.SemanticsValue represents a counter-clockwise rotation, in 4018 degrees, around the right vector. This rotation must be applied 4019 after the ProjectionPoseYaw rotation and before the 4020 ProjectionPoseRoll rotation. The value of this field should be in 4021 the -90 to 90 degree range. 4023 9.3.4.1.31.49. ProjectionPoseRoll Element 4025 name: "ProjectionPoseRoll" 4027 path: 4028 "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseRoll)" 4030 id: "0x7675" 4032 minOccurs: "1" 4034 maxOccurs: "1" 4036 default: "0x0p+0" 4037 type: "float" 4039 minver: "4" 4041 definition: Specifies a roll rotation to the 4042 projection.SemanticsValue represents a counter-clockwise rotation, in 4043 degrees, around the forward vector. This rotation must be applied 4044 after the ProjectionPoseYaw and ProjectionPosePitch rotations. The 4045 value of this field should be in the -180 to 180 degree range. 4047 9.3.4.1.32. Audio Element 4049 name: "Audio" 4051 path: "0*1(\Segment\Tracks\TrackEntry\Audio)" 4053 id: "0xE1" 4055 maxOccurs: "1" 4057 type: "master" 4059 definition: Audio settings. 4061 9.3.4.1.32.1. SamplingFrequency Element 4063 name: "SamplingFrequency" 4065 path: "1*1(\Segment\Tracks\TrackEntry\Audio\SamplingFrequency)" 4067 id: "0xB5" 4069 minOccurs: "1" 4071 maxOccurs: "1" 4073 range: "> 0x0p+0" 4075 default: "0x1.f4p+12" 4077 type: "float" 4079 definition: Sampling frequency in Hz. 4081 9.3.4.1.32.2. OutputSamplingFrequency Element 4083 name: "OutputSamplingFrequency" 4084 path: "0*1(\Segment\Tracks\TrackEntry\Audio\OutputSamplingFrequency)" 4086 id: "0x78B5" 4088 maxOccurs: "1" 4090 range: "> 0x0p+0" 4092 default: see implementation notes 4094 type: "float" 4096 definition: Real output sampling frequency in Hz (used for SBR 4097 techniques). 4099 implementation notes: 4101 +-----------+------------------------------------------------------+ 4102 | attribute | note | 4103 +===========+======================================================+ 4104 | default | The default value for OutputSamplingFrequency of the | 4105 | | same TrackEntry is equal to the SamplingFrequency. | 4106 +-----------+------------------------------------------------------+ 4108 Table 30 4110 9.3.4.1.32.3. Channels Element 4112 name: "Channels" 4114 path: "1*1(\Segment\Tracks\TrackEntry\Audio\Channels)" 4116 id: "0x9F" 4118 minOccurs: "1" 4120 maxOccurs: "1" 4122 range: "not 0" 4124 default: "1" 4126 type: "uinteger" 4128 definition: Numbers of channels in the track. 4130 9.3.4.1.32.4. ChannelPositions Element 4132 name: "ChannelPositions" 4134 path: "0*1(\Segment\Tracks\TrackEntry\Audio\ChannelPositions)" 4136 id: "0x7D7B" 4138 maxOccurs: "1" 4140 type: "binary" 4142 minver: "0" 4144 maxver: "0" 4146 definition: Table of horizontal angles for each successive channel, 4147 see appendix. 4149 9.3.4.1.32.5. BitDepth Element 4151 name: "BitDepth" 4153 path: "0*1(\Segment\Tracks\TrackEntry\Audio\BitDepth)" 4155 id: "0x6264" 4157 maxOccurs: "1" 4159 range: "not 0" 4161 type: "uinteger" 4163 definition: Bits per sample, mostly used for PCM. 4165 9.3.4.1.33. TrackOperation Element 4167 name: "TrackOperation" 4169 path: "0*1(\Segment\Tracks\TrackEntry\TrackOperation)" 4171 id: "0xE2" 4173 maxOccurs: "1" 4175 type: "master" 4177 minver: "3" 4178 definition: Operation that needs to be applied on tracks to create 4179 this virtual track. For more details look at the Specification Notes 4180 on the subject. 4182 9.3.4.1.33.1. TrackCombinePlanes Element 4184 name: "TrackCombinePlanes" 4186 path: 4187 "0*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes)" 4189 id: "0xE3" 4191 maxOccurs: "1" 4193 type: "master" 4195 minver: "3" 4197 definition: Contains the list of all video plane tracks that need to 4198 be combined to create this 3D track 4200 9.3.4.1.33.2. TrackPlane Element 4202 name: "TrackPlane" 4204 path: "1*(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlane 4205 s\TrackPlane)" 4207 id: "0xE4" 4209 minOccurs: "1" 4211 type: "master" 4213 minver: "3" 4215 definition: Contains a video plane track that need to be combined to 4216 create this 3D track 4218 9.3.4.1.33.3. TrackPlaneUID Element 4220 name: "TrackPlaneUID" 4222 path: "1*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlan 4223 es\TrackPlane\TrackPlaneUID)" 4225 id: "0xE5" 4226 minOccurs: "1" 4228 maxOccurs: "1" 4230 range: "not 0" 4232 type: "uinteger" 4234 minver: "3" 4236 definition: The trackUID number of the track representing the plane. 4238 9.3.4.1.33.4. TrackPlaneType Element 4240 name: "TrackPlaneType" 4242 path: "1*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlan 4243 es\TrackPlane\TrackPlaneType)" 4245 id: "0xE6" 4247 minOccurs: "1" 4249 maxOccurs: "1" 4251 type: "uinteger" 4253 minver: "3" 4255 definition: The kind of plane this track corresponds to. 4257 restrictions: 4259 +-------+------------+ 4260 | value | label | 4261 +=======+============+ 4262 | "0" | left eye | 4263 +-------+------------+ 4264 | "1" | right eye | 4265 +-------+------------+ 4266 | "2" | background | 4267 +-------+------------+ 4269 Table 31 4271 9.3.4.1.33.5. TrackJoinBlocks Element 4273 name: "TrackJoinBlocks" 4275 path: 4276 "0*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks)" 4278 id: "0xE9" 4280 maxOccurs: "1" 4282 type: "master" 4284 minver: "3" 4286 definition: Contains the list of all tracks whose Blocks need to be 4287 combined to create this virtual track 4289 9.3.4.1.33.6. TrackJoinUID Element 4291 name: "TrackJoinUID" 4293 path: "1*(\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks\T 4294 rackJoinUID)" 4296 id: "0xED" 4298 minOccurs: "1" 4300 range: "not 0" 4302 type: "uinteger" 4304 minver: "3" 4306 definition: The trackUID number of a track whose blocks are used to 4307 create this virtual track. 4309 9.3.4.1.34. TrickTrackUID Element 4311 name: "TrickTrackUID" 4313 path: "0*1(\Segment\Tracks\TrackEntry\TrickTrackUID)" 4315 id: "0xC0" 4317 maxOccurs: "1" 4318 type: "uinteger" 4320 minver: "0" 4322 maxver: "0" 4324 definition: DivX trick track extensions 4326 9.3.4.1.35. TrickTrackSegmentUID Element 4328 name: "TrickTrackSegmentUID" 4330 path: "0*1(\Segment\Tracks\TrackEntry\TrickTrackSegmentUID)" 4332 id: "0xC1" 4334 maxOccurs: "1" 4336 type: "binary" 4338 minver: "0" 4340 maxver: "0" 4342 definition: DivX trick track extensions 4344 9.3.4.1.36. TrickTrackFlag Element 4346 name: "TrickTrackFlag" 4348 path: "0*1(\Segment\Tracks\TrackEntry\TrickTrackFlag)" 4350 id: "0xC6" 4352 maxOccurs: "1" 4354 default: "0" 4356 type: "uinteger" 4358 minver: "0" 4360 maxver: "0" 4362 definition: DivX trick track extensions 4364 9.3.4.1.37. TrickMasterTrackUID Element 4366 name: "TrickMasterTrackUID" 4368 path: "0*1(\Segment\Tracks\TrackEntry\TrickMasterTrackUID)" 4370 id: "0xC7" 4372 maxOccurs: "1" 4374 type: "uinteger" 4376 minver: "0" 4378 maxver: "0" 4380 definition: DivX trick track extensions 4382 9.3.4.1.38. TrickMasterTrackSegmentUID Element 4384 name: "TrickMasterTrackSegmentUID" 4386 path: "0*1(\Segment\Tracks\TrackEntry\TrickMasterTrackSegmentUID)" 4388 id: "0xC4" 4390 maxOccurs: "1" 4392 type: "binary" 4394 minver: "0" 4396 maxver: "0" 4398 definition: DivX trick track extensions 4400 9.3.4.1.39. ContentEncodings Element 4402 name: "ContentEncodings" 4404 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings)" 4406 id: "0x6D80" 4408 maxOccurs: "1" 4410 type: "master" 4411 definition: Settings for several content encoding mechanisms like 4412 compression or encryption. 4414 9.3.4.1.39.1. ContentEncoding Element 4416 name: "ContentEncoding" 4418 path: 4419 "1*(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding)" 4421 id: "0x6240" 4423 minOccurs: "1" 4425 type: "master" 4427 definition: Settings for one content encoding like compression or 4428 encryption. 4430 9.3.4.1.39.2. ContentEncodingOrder Element 4432 name: "ContentEncodingOrder" 4434 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4435 g\ContentEncodingOrder)" 4437 id: "0x5031" 4439 minOccurs: "1" 4441 maxOccurs: "1" 4443 default: "0" 4445 type: "uinteger" 4447 definition: Tells when this modification was used during encoding/ 4448 muxing starting with 0 and counting upwards. The decoder/demuxer has 4449 to start with the highest order number it finds and work its way 4450 down. This value has to be unique over all ContentEncodingOrder 4451 Elements in the TrackEntry that contains this ContentEncodingOrder 4452 element. 4454 9.3.4.1.39.3. ContentEncodingScope Element 4456 name: "ContentEncodingScope" 4457 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4458 g\ContentEncodingScope)" 4460 id: "0x5032" 4462 minOccurs: "1" 4464 maxOccurs: "1" 4466 range: "not 0" 4468 default: "1" 4470 type: "uinteger" 4472 definition: A bit field that describes which Elements have been 4473 modified in this way. Values (big endian) can be OR'ed. 4475 restrictions: 4477 +-------+--------------------------------------------------+ 4478 | value | label | 4479 +=======+==================================================+ 4480 | "1" | All frame contents, excluding lacing data | 4481 +-------+--------------------------------------------------+ 4482 | "2" | The track's private data | 4483 +-------+--------------------------------------------------+ 4484 | "4" | The next ContentEncoding (next | 4485 | | "ContentEncodingOrder". Either the data inside | 4486 | | "ContentCompression" and/or "ContentEncryption") | 4487 +-------+--------------------------------------------------+ 4489 Table 32 4491 9.3.4.1.39.4. ContentEncodingType Element 4493 name: "ContentEncodingType" 4495 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4496 g\ContentEncodingType)" 4498 id: "0x5033" 4500 minOccurs: "1" 4502 maxOccurs: "1" 4504 default: "0" 4505 type: "uinteger" 4507 definition: A value describing what kind of transformation is 4508 applied. 4510 restrictions: 4512 +-------+-------------+ 4513 | value | label | 4514 +=======+=============+ 4515 | "0" | Compression | 4516 +-------+-------------+ 4517 | "1" | Encryption | 4518 +-------+-------------+ 4520 Table 33 4522 9.3.4.1.39.5. ContentCompression Element 4524 name: "ContentCompression" 4526 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4527 g\ContentCompression)" 4529 id: "0x5034" 4531 maxOccurs: "1" 4533 type: "master" 4535 definition: Settings describing the compression used. This Element 4536 MUST be present if the value of ContentEncodingType is 0 and absent 4537 otherwise. Each block MUST be decompressable even if no previous 4538 block is available in order not to prevent seeking. 4540 9.3.4.1.39.6. ContentCompAlgo Element 4542 name: "ContentCompAlgo" 4544 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4545 g\ContentCompression\ContentCompAlgo)" 4547 id: "0x4254" 4549 minOccurs: "1" 4551 maxOccurs: "1" 4552 default: "0" 4554 type: "uinteger" 4556 definition: The compression algorithm used. 4558 restrictions: 4560 +-------+------------------+ 4561 | value | label | 4562 +=======+==================+ 4563 | "0" | zlib | 4564 +-------+------------------+ 4565 | "1" | bzlib | 4566 +-------+------------------+ 4567 | "2" | lzo1x | 4568 +-------+------------------+ 4569 | "3" | Header Stripping | 4570 +-------+------------------+ 4572 Table 34 4574 9.3.4.1.39.7. ContentCompSettings Element 4576 name: "ContentCompSettings" 4578 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4579 g\ContentCompression\ContentCompSettings)" 4581 id: "0x4255" 4583 maxOccurs: "1" 4585 type: "binary" 4587 definition: Settings that might be needed by the decompressor. For 4588 Header Stripping ("ContentCompAlgo"=3), the bytes that were removed 4589 from the beginning of each frames of the track. 4591 9.3.4.1.39.8. ContentEncryption Element 4593 name: "ContentEncryption" 4595 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4596 g\ContentEncryption)" 4598 id: "0x5035" 4599 maxOccurs: "1" 4601 type: "master" 4603 definition: Settings describing the encryption used. This Element 4604 MUST be present if the value of "ContentEncodingType" is 1 4605 (encryption) and MUST be ignored otherwise. 4607 9.3.4.1.39.9. ContentEncAlgo Element 4609 name: "ContentEncAlgo" 4611 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4612 g\ContentEncryption\ContentEncAlgo)" 4614 id: "0x47E1" 4616 minOccurs: "1" 4618 maxOccurs: "1" 4620 default: "0" 4622 type: "uinteger" 4624 definition: The encryption algorithm used. The value '0' means that 4625 the contents have not been encrypted but only signed. 4627 restrictions: 4629 +-------+-----------------------+ 4630 | value | label | 4631 +=======+=======================+ 4632 | "0" | Not encrypted | 4633 +-------+-----------------------+ 4634 | "1" | DES - FIPS 46-3 | 4635 +-------+-----------------------+ 4636 | "2" | Triple DES - RFC 1851 | 4637 +-------+-----------------------+ 4638 | "3" | Twofish | 4639 +-------+-----------------------+ 4640 | "4" | Blowfish | 4641 +-------+-----------------------+ 4642 | "5" | AES - FIPS 187 | 4643 +-------+-----------------------+ 4645 Table 35 4647 9.3.4.1.39.10. ContentEncKeyID Element 4649 name: "ContentEncKeyID" 4651 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4652 g\ContentEncryption\ContentEncKeyID)" 4654 id: "0x47E2" 4656 maxOccurs: "1" 4658 type: "binary" 4660 definition: For public key algorithms this is the ID of the public 4661 key the the data was encrypted with. 4663 9.3.4.1.39.11. ContentEncAESSettings Element 4665 name: "ContentEncAESSettings" 4667 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4668 g\ContentEncryption\ContentEncAESSettings)" 4670 id: "0x47E7" 4672 maxOccurs: "1" 4674 type: "master" 4676 minver: "4" 4678 definition: Settings describing the encryption algorithm used. If 4679 "ContentEncAlgo" != 5 this MUST be ignored. 4681 9.3.4.1.39.12. AESSettingsCipherMode Element 4683 name: "AESSettingsCipherMode" 4685 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4686 g\ContentEncryption\ContentEncAESSettings\AESSettingsCipherMode)" 4688 id: "0x47E8" 4690 minOccurs: "1" 4692 maxOccurs: "1" 4694 type: "uinteger" 4695 minver: "4" 4697 definition: The AES cipher mode used in the encryption. 4699 restrictions: 4701 +-------+--------------------------------------------------+ 4702 | value | label | 4703 +=======+==================================================+ 4704 | "1" | AES-CTR / Counter, NIST SP 800-38A | 4705 +-------+--------------------------------------------------+ 4706 | "2" | AES-CBC / Cipher Block Chaining, NIST SP 800-38A | 4707 +-------+--------------------------------------------------+ 4709 Table 36 4711 9.3.4.1.39.13. ContentSignature Element 4713 name: "ContentSignature" 4715 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4716 g\ContentEncryption\ContentSignature)" 4718 id: "0x47E3" 4720 maxOccurs: "1" 4722 type: "binary" 4724 definition: A cryptographic signature of the contents. 4726 9.3.4.1.39.14. ContentSigKeyID Element 4728 name: "ContentSigKeyID" 4730 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4731 g\ContentEncryption\ContentSigKeyID)" 4733 id: "0x47E4" 4735 maxOccurs: "1" 4737 type: "binary" 4739 definition: This is the ID of the private key the data was signed 4740 with. 4742 9.3.4.1.39.15. ContentSigAlgo Element 4744 name: "ContentSigAlgo" 4746 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4747 g\ContentEncryption\ContentSigAlgo)" 4749 id: "0x47E5" 4751 maxOccurs: "1" 4753 default: "0" 4755 type: "uinteger" 4757 definition: The algorithm used for the signature. 4759 restrictions: 4761 +-------+------------+ 4762 | value | label | 4763 +=======+============+ 4764 | "0" | Not signed | 4765 +-------+------------+ 4766 | "1" | RSA | 4767 +-------+------------+ 4769 Table 37 4771 9.3.4.1.39.16. ContentSigHashAlgo Element 4773 name: "ContentSigHashAlgo" 4775 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4776 g\ContentEncryption\ContentSigHashAlgo)" 4778 id: "0x47E6" 4780 maxOccurs: "1" 4782 default: "0" 4784 type: "uinteger" 4786 definition: The hash algorithm used for the signature. 4788 restrictions: 4790 +-------+------------+ 4791 | value | label | 4792 +=======+============+ 4793 | "0" | Not signed | 4794 +-------+------------+ 4795 | "1" | SHA1-160 | 4796 +-------+------------+ 4797 | "2" | MD5 | 4798 +-------+------------+ 4800 Table 38 4802 9.3.5. Cues Element 4804 name: "Cues" 4806 path: "0*1(\Segment\Cues)" 4808 id: "0x1C53BB6B" 4810 minOccurs: see implementation notes 4812 maxOccurs: "1" 4814 type: "master" 4816 definition: A Top-Level Element to speed seeking access. All entries 4817 are local to the Segment. 4819 implementation notes: 4821 +-----------+----------------------------------------------------+ 4822 | attribute | note | 4823 +===========+====================================================+ 4824 | minOccurs | This Element SHOULD be set when the Segment is not | 4825 | | transmitted as a live stream (see #livestreaming). | 4826 +-----------+----------------------------------------------------+ 4828 Table 39 4830 9.3.5.1. CuePoint Element 4832 name: "CuePoint" 4834 path: "1*(\Segment\Cues\CuePoint)" 4836 id: "0xBB" 4837 minOccurs: "1" 4839 type: "master" 4841 definition: Contains all information relative to a seek point in the 4842 Segment. 4844 9.3.5.1.1. CueTime Element 4846 name: "CueTime" 4848 path: "1*1(\Segment\Cues\CuePoint\CueTime)" 4850 id: "0xB3" 4852 minOccurs: "1" 4854 maxOccurs: "1" 4856 type: "uinteger" 4858 definition: Absolute timestamp according to the Segment time base. 4860 9.3.5.1.2. CueTrackPositions Element 4862 name: "CueTrackPositions" 4864 path: "1*(\Segment\Cues\CuePoint\CueTrackPositions)" 4866 id: "0xB7" 4868 minOccurs: "1" 4870 type: "master" 4872 definition: Contain positions for different tracks corresponding to 4873 the timestamp. 4875 9.3.5.1.2.1. CueTrack Element 4877 name: "CueTrack" 4879 path: "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueTrack)" 4881 id: "0xF7" 4883 minOccurs: "1" 4884 maxOccurs: "1" 4886 range: "not 0" 4888 type: "uinteger" 4890 definition: The track for which a position is given. 4892 9.3.5.1.2.2. CueClusterPosition Element 4894 name: "CueClusterPosition" 4896 path: 4897 "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueClusterPosition)" 4899 id: "0xF1" 4901 minOccurs: "1" 4903 maxOccurs: "1" 4905 type: "uinteger" 4907 definition: The Segment Position of the Cluster containing the 4908 associated Block. 4910 9.3.5.1.2.3. CueRelativePosition Element 4912 name: "CueRelativePosition" 4914 path: 4915 "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueRelativePosition)" 4917 id: "0xF0" 4919 maxOccurs: "1" 4921 type: "uinteger" 4923 minver: "4" 4925 definition: The relative position inside the Cluster of the 4926 referenced SimpleBlock or BlockGroup with 0 being the first possible 4927 position for an Element inside that Cluster. 4929 9.3.5.1.2.4. CueDuration Element 4931 name: "CueDuration" 4933 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueDuration)" 4935 id: "0xB2" 4937 maxOccurs: "1" 4939 type: "uinteger" 4941 minver: "4" 4943 definition: The duration of the block according to the Segment time 4944 base. If missing the track's DefaultDuration does not apply and no 4945 duration information is available in terms of the cues. 4947 9.3.5.1.2.5. CueBlockNumber Element 4949 name: "CueBlockNumber" 4951 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueBlockNumber)" 4953 id: "0x5378" 4955 maxOccurs: "1" 4957 range: "not 0" 4959 default: "1" 4961 type: "uinteger" 4963 definition: Number of the Block in the specified Cluster. 4965 9.3.5.1.2.6. CueCodecState Element 4967 name: "CueCodecState" 4969 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueCodecState)" 4971 id: "0xEA" 4973 maxOccurs: "1" 4975 default: "0" 4976 type: "uinteger" 4978 minver: "2" 4980 definition: The Segment Position of the Codec State corresponding to 4981 this Cue Element. 0 means that the data is taken from the initial 4982 Track Entry. 4984 9.3.5.1.2.7. CueReference Element 4986 name: "CueReference" 4988 path: "0*(\Segment\Cues\CuePoint\CueTrackPositions\CueReference)" 4990 id: "0xDB" 4992 type: "master" 4994 minver: "2" 4996 definition: The Clusters containing the referenced Blocks. 4998 9.3.5.1.2.8. CueRefTime Element 5000 name: "CueRefTime" 5002 path: "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 5003 efTime)" 5005 id: "0x96" 5007 minOccurs: "1" 5009 maxOccurs: "1" 5011 type: "uinteger" 5013 minver: "2" 5015 definition: Timestamp of the referenced Block. 5017 9.3.5.1.2.9. CueRefCluster Element 5019 name: "CueRefCluster" 5021 path: "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 5022 efCluster)" 5023 id: "0x97" 5025 minOccurs: "1" 5027 maxOccurs: "1" 5029 type: "uinteger" 5031 minver: "0" 5033 maxver: "0" 5035 definition: The Segment Position of the Cluster containing the 5036 referenced Block. 5038 9.3.5.1.2.10. CueRefNumber Element 5040 name: "CueRefNumber" 5042 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 5043 efNumber)" 5045 id: "0x535F" 5047 maxOccurs: "1" 5049 range: "not 0" 5051 default: "1" 5053 type: "uinteger" 5055 minver: "0" 5057 maxver: "0" 5059 definition: Number of the referenced Block of Track X in the 5060 specified Cluster. 5062 9.3.5.1.2.11. CueRefCodecState Element 5064 name: "CueRefCodecState" 5066 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 5067 efCodecState)" 5069 id: "0xEB" 5070 maxOccurs: "1" 5072 default: "0" 5074 type: "uinteger" 5076 minver: "0" 5078 maxver: "0" 5080 definition: The Segment Position of the Codec State corresponding to 5081 this referenced Element. 0 means that the data is taken from the 5082 initial Track Entry. 5084 9.3.6. Attachments Element 5086 name: "Attachments" 5088 path: "0*1(\Segment\Attachments)" 5090 id: "0x1941A469" 5092 maxOccurs: "1" 5094 type: "master" 5096 definition: Contain attached files. 5098 9.3.6.1. AttachedFile Element 5100 name: "AttachedFile" 5102 path: "1*(\Segment\Attachments\AttachedFile)" 5104 id: "0x61A7" 5106 minOccurs: "1" 5108 type: "master" 5110 definition: An attached file. 5112 9.3.6.1.1. FileDescription Element 5114 name: "FileDescription" 5116 path: "0*1(\Segment\Attachments\AttachedFile\FileDescription)" 5117 id: "0x467E" 5119 maxOccurs: "1" 5121 type: "utf-8" 5123 definition: A human-friendly name for the attached file. 5125 9.3.6.1.2. FileName Element 5127 name: "FileName" 5129 path: "1*1(\Segment\Attachments\AttachedFile\FileName)" 5131 id: "0x466E" 5133 minOccurs: "1" 5135 maxOccurs: "1" 5137 type: "utf-8" 5139 definition: Filename of the attached file. 5141 9.3.6.1.3. FileMimeType Element 5143 name: "FileMimeType" 5145 path: "1*1(\Segment\Attachments\AttachedFile\FileMimeType)" 5147 id: "0x4660" 5149 minOccurs: "1" 5151 maxOccurs: "1" 5153 type: "string" 5155 definition: MIME type of the file. 5157 9.3.6.1.4. FileData Element 5159 name: "FileData" 5161 path: "1*1(\Segment\Attachments\AttachedFile\FileData)" 5163 id: "0x465C" 5164 minOccurs: "1" 5166 maxOccurs: "1" 5168 type: "binary" 5170 definition: The data of the file. 5172 9.3.6.1.5. FileUID Element 5174 name: "FileUID" 5176 path: "1*1(\Segment\Attachments\AttachedFile\FileUID)" 5178 id: "0x46AE" 5180 minOccurs: "1" 5182 maxOccurs: "1" 5184 range: "not 0" 5186 type: "uinteger" 5188 definition: Unique ID representing the file, as random as possible. 5190 9.3.6.1.6. FileReferral Element 5192 name: "FileReferral" 5194 path: "0*1(\Segment\Attachments\AttachedFile\FileReferral)" 5196 id: "0x4675" 5198 maxOccurs: "1" 5200 type: "binary" 5202 minver: "0" 5204 maxver: "0" 5206 definition: A binary value that a track/codec can refer to when the 5207 attachment is needed. 5209 9.3.6.1.7. FileUsedStartTime Element 5211 name: "FileUsedStartTime" 5213 path: "0*1(\Segment\Attachments\AttachedFile\FileUsedStartTime)" 5215 id: "0x4661" 5217 maxOccurs: "1" 5219 type: "uinteger" 5221 minver: "0" 5223 maxver: "0" 5225 definition: DivX font extension 5227 9.3.6.1.8. FileUsedEndTime Element 5229 name: "FileUsedEndTime" 5231 path: "0*1(\Segment\Attachments\AttachedFile\FileUsedEndTime)" 5233 id: "0x4662" 5235 maxOccurs: "1" 5237 type: "uinteger" 5239 minver: "0" 5241 maxver: "0" 5243 definition: DivX font extension 5245 9.3.7. Chapters Element 5247 name: "Chapters" 5249 path: "0*1(\Segment\Chapters)" 5251 id: "0x1043A770" 5253 maxOccurs: "1" 5255 type: "master" 5256 recurring: "1" 5258 definition: A system to define basic menus and partition data. For 5259 more detailed information, look at the Chapters Explanation. 5261 9.3.7.1. EditionEntry Element 5263 name: "EditionEntry" 5265 path: "1*(\Segment\Chapters\EditionEntry)" 5267 id: "0x45B9" 5269 minOccurs: "1" 5271 type: "master" 5273 definition: Contains all information about a Segment edition. 5275 9.3.7.1.1. EditionUID Element 5277 name: "EditionUID" 5279 path: "0*1(\Segment\Chapters\EditionEntry\EditionUID)" 5281 id: "0x45BC" 5283 maxOccurs: "1" 5285 range: "not 0" 5287 type: "uinteger" 5289 definition: A unique ID to identify the edition. It's useful for 5290 tagging an edition. 5292 9.3.7.1.2. EditionFlagHidden Element 5294 name: "EditionFlagHidden" 5296 path: "1*1(\Segment\Chapters\EditionEntry\EditionFlagHidden)" 5298 id: "0x45BD" 5300 minOccurs: "1" 5302 maxOccurs: "1" 5303 range: "0-1" 5305 default: "0" 5307 type: "uinteger" 5309 definition: If an edition is hidden (1), it SHOULD NOT be available 5310 to the user interface (but still to Control Tracks; see flag notes). 5311 (1 bit) 5313 9.3.7.1.3. EditionFlagDefault Element 5315 name: "EditionFlagDefault" 5317 path: "1*1(\Segment\Chapters\EditionEntry\EditionFlagDefault)" 5319 id: "0x45DB" 5321 minOccurs: "1" 5323 maxOccurs: "1" 5325 range: "0-1" 5327 default: "0" 5329 type: "uinteger" 5331 definition: If a flag is set (1) the edition SHOULD be used as the 5332 default one. (1 bit) 5334 9.3.7.1.4. EditionFlagOrdered Element 5336 name: "EditionFlagOrdered" 5338 path: "0*1(\Segment\Chapters\EditionEntry\EditionFlagOrdered)" 5340 id: "0x45DD" 5342 maxOccurs: "1" 5344 range: "0-1" 5346 default: "0" 5348 type: "uinteger" 5349 definition: Specify if the chapters can be defined multiple times and 5350 the order to play them is enforced. (1 bit) 5352 9.3.7.1.5. ChapterAtom Element 5354 name: "ChapterAtom" 5356 path: "1*(\Segment\Chapters\EditionEntry(1*(\ChapterAtom)))" 5358 id: "0xB6" 5360 minOccurs: "1" 5362 type: "master" 5364 definition: Contains the atom information to use as the chapter atom 5365 (apply to all tracks). 5367 9.3.7.1.5.1. ChapterUID Element 5369 name: "ChapterUID" 5371 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterUID)" 5373 id: "0x73C4" 5375 minOccurs: "1" 5377 maxOccurs: "1" 5379 range: "not 0" 5381 type: "uinteger" 5383 definition: A unique ID to identify the Chapter. 5385 9.3.7.1.5.2. ChapterStringUID Element 5387 name: "ChapterStringUID" 5389 path: 5390 "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterStringUID)" 5392 id: "0x5654" 5394 maxOccurs: "1" 5396 type: "utf-8" 5397 minver: "3" 5399 definition: A unique string ID to identify the Chapter. Use for 5400 WebVTT cue identifier storage. 5402 9.3.7.1.5.3. ChapterTimeStart Element 5404 name: "ChapterTimeStart" 5406 path: 5407 "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTimeStart)" 5409 id: "0x91" 5411 minOccurs: "1" 5413 maxOccurs: "1" 5415 type: "uinteger" 5417 definition: Timestamp of the start of Chapter (not scaled). 5419 9.3.7.1.5.4. ChapterTimeEnd Element 5421 name: "ChapterTimeEnd" 5423 path: 5424 "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTimeEnd)" 5426 id: "0x92" 5428 maxOccurs: "1" 5430 type: "uinteger" 5432 definition: Timestamp of the end of Chapter (timestamp excluded, not 5433 scaled). 5435 9.3.7.1.5.5. ChapterFlagHidden Element 5437 name: "ChapterFlagHidden" 5439 path: 5440 "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterFlagHidden)" 5442 id: "0x98" 5444 minOccurs: "1" 5445 maxOccurs: "1" 5447 range: "0-1" 5449 default: "0" 5451 type: "uinteger" 5453 definition: If a chapter is hidden (1), it SHOULD NOT be available to 5454 the user interface (but still to Control Tracks; see flag notes). (1 5455 bit) 5457 9.3.7.1.5.6. ChapterFlagEnabled Element 5459 name: "ChapterFlagEnabled" 5461 path: 5462 "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterFlagEnabled)" 5464 id: "0x4598" 5466 minOccurs: "1" 5468 maxOccurs: "1" 5470 range: "0-1" 5472 default: "1" 5474 type: "uinteger" 5476 definition: Specify whether the chapter is enabled. It can be 5477 enabled/disabled by a Control Track. When disabled, the movie SHOULD 5478 skip all the content between the TimeStart and TimeEnd of this 5479 chapter (see flag notes). (1 bit) 5481 9.3.7.1.5.7. ChapterSegmentUID Element 5483 name: "ChapterSegmentUID" 5485 path: 5486 "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterSegmentUID)" 5488 id: "0x6E67" 5490 minOccurs: see implementation notes 5492 maxOccurs: "1" 5493 range: ">0" 5495 type: "binary" 5497 definition: The SegmentUID of another Segment to play during this 5498 chapter. 5500 implementation notes: 5502 +-----------+---------------------------------------------+ 5503 | attribute | note | 5504 +===========+=============================================+ 5505 | minOccurs | ChapterSegmentUID MUST be set (minOccurs=1) | 5506 | | if ChapterSegmentEditionUID is used. | 5507 +-----------+---------------------------------------------+ 5509 Table 40 5511 9.3.7.1.5.8. ChapterSegmentEditionUID Element 5513 name: "ChapterSegmentEditionUID" 5515 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterSegmentE 5516 ditionUID)" 5518 id: "0x6EBC" 5520 maxOccurs: "1" 5522 range: "not 0" 5524 type: "uinteger" 5526 definition: The EditionUID to play from the Segment linked in 5527 ChapterSegmentUID. If ChapterSegmentEditionUID is undeclared then no 5528 Edition of the linked Segment is used. 5530 9.3.7.1.5.9. ChapterPhysicalEquiv Element 5532 name: "ChapterPhysicalEquiv" 5534 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterPhysical 5535 Equiv)" 5537 id: "0x63C3" 5539 maxOccurs: "1" 5540 type: "uinteger" 5542 definition: Specify the physical equivalent of this ChapterAtom like 5543 "DVD" (60) or "SIDE" (50), see complete list of values. 5545 9.3.7.1.5.10. ChapterTrack Element 5547 name: "ChapterTrack" 5549 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTrack)" 5551 id: "0x8F" 5553 maxOccurs: "1" 5555 type: "master" 5557 definition: List of tracks on which the chapter applies. If this 5558 Element is not present, all tracks apply 5560 9.3.7.1.5.11. ChapterTrackUID Element 5562 name: "ChapterTrackUID" 5564 path: "1*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTrack\Cha 5565 pterTrackUID)" 5567 id: "0x89" 5569 minOccurs: "1" 5571 range: "not 0" 5573 type: "uinteger" 5575 definition: UID of the Track to apply this chapter too. In the 5576 absence of a control track, choosing this chapter will select the 5577 listed Tracks and deselect unlisted tracks. Absence of this Element 5578 indicates that the Chapter SHOULD be applied to any currently used 5579 Tracks. 5581 9.3.7.1.5.12. ChapterDisplay Element 5583 name: "ChapterDisplay" 5585 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay)" 5587 id: "0x80" 5588 type: "master" 5590 definition: Contains all possible strings to use for the chapter 5591 display. 5593 9.3.7.1.5.13. ChapString Element 5595 name: "ChapString" 5597 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\ 5598 ChapString)" 5600 id: "0x85" 5602 minOccurs: "1" 5604 maxOccurs: "1" 5606 type: "utf-8" 5608 definition: Contains the string to use as the chapter atom. 5610 9.3.7.1.5.14. ChapLanguage Element 5612 name: "ChapLanguage" 5614 path: "1*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\C 5615 hapLanguage)" 5617 id: "0x437C" 5619 minOccurs: "1" 5621 default: "eng" 5623 type: "string" 5625 definition: The languages corresponding to the string, in the 5626 bibliographic ISO-639-2 form. This Element MUST be ignored if the 5627 ChapLanguageIETF Element is used within the same ChapterDisplay 5628 Element. 5630 9.3.7.1.5.15. ChapLanguageIETF Element 5632 name: "ChapLanguageIETF" 5634 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\C 5635 hapLanguageIETF)" 5636 id: "0x437D" 5638 type: "string" 5640 minver: "4" 5642 definition: Specifies the language used in the ChapString according 5643 to BCP 47 and using the IANA Language Subtag Registry. If this 5644 Element is used, then any ChapLanguage Elements used in the same 5645 ChapterDisplay MUST be ignored. 5647 9.3.7.1.5.16. ChapCountry Element 5649 name: "ChapCountry" 5651 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\C 5652 hapCountry)" 5654 id: "0x437E" 5656 type: "string" 5658 definition: The countries corresponding to the string, same 2 octets 5659 as in Internet domains. This Element MUST be ignored if the 5660 ChapLanguageIETF Element is used within the same ChapterDisplay 5661 Element. 5663 9.3.7.1.5.17. ChapProcess Element 5665 name: "ChapProcess" 5667 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess)" 5669 id: "0x6944" 5671 type: "master" 5673 definition: Contains all the commands associated to the Atom. 5675 9.3.7.1.5.18. ChapProcessCodecID Element 5677 name: "ChapProcessCodecID" 5679 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5680 pProcessCodecID)" 5682 id: "0x6955" 5683 minOccurs: "1" 5685 maxOccurs: "1" 5687 default: "0" 5689 type: "uinteger" 5691 definition: Contains the type of the codec used for the processing. 5692 A value of 0 means native Matroska processing (to be defined), a 5693 value of 1 means the DVD command set is used. More codec IDs can be 5694 added later. 5696 9.3.7.1.5.19. ChapProcessPrivate Element 5698 name: "ChapProcessPrivate" 5700 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5701 pProcessPrivate)" 5703 id: "0x450D" 5705 maxOccurs: "1" 5707 type: "binary" 5709 definition: Some optional data attached to the ChapProcessCodecID 5710 information. For ChapProcessCodecID = 1, it is the "DVD level" 5711 equivalent. 5713 9.3.7.1.5.20. ChapProcessCommand Element 5715 name: "ChapProcessCommand" 5717 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Chap 5718 ProcessCommand)" 5720 id: "0x6911" 5722 type: "master" 5724 definition: Contains all the commands associated to the Atom. 5726 9.3.7.1.5.21. ChapProcessTime Element 5728 name: "ChapProcessTime" 5729 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5730 pProcessCommand\ChapProcessTime)" 5732 id: "0x6922" 5734 minOccurs: "1" 5736 maxOccurs: "1" 5738 type: "uinteger" 5740 definition: Defines when the process command SHOULD be handled 5742 restrictions: 5744 +-------+-------------------------------+ 5745 | value | label | 5746 +=======+===============================+ 5747 | "0" | during the whole chapter | 5748 +-------+-------------------------------+ 5749 | "1" | before starting playback | 5750 +-------+-------------------------------+ 5751 | "2" | after playback of the chapter | 5752 +-------+-------------------------------+ 5754 Table 41 5756 9.3.7.1.5.22. ChapProcessData Element 5758 name: "ChapProcessData" 5760 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5761 pProcessCommand\ChapProcessData)" 5763 id: "0x6933" 5765 minOccurs: "1" 5767 maxOccurs: "1" 5769 type: "binary" 5771 definition: Contains the command information. The data SHOULD be 5772 interpreted depending on the ChapProcessCodecID value. For 5773 ChapProcessCodecID = 1, the data correspond to the binary DVD cell 5774 pre/post commands. 5776 9.3.8. Tags Element 5778 name: "Tags" 5780 path: "0*(\Segment\Tags)" 5782 id: "0x1254C367" 5784 type: "master" 5786 definition: Element containing metadata describing Tracks, Editions, 5787 Chapters, Attachments, or the Segment as a whole. A list of valid 5788 tags can be found here. 5790 9.3.8.1. Tag Element 5792 name: "Tag" 5794 path: "1*(\Segment\Tags\Tag)" 5796 id: "0x7373" 5798 minOccurs: "1" 5800 type: "master" 5802 definition: A single metadata descriptor. 5804 9.3.8.1.1. Targets Element 5806 name: "Targets" 5808 path: "1*1(\Segment\Tags\Tag\Targets)" 5810 id: "0x63C0" 5812 minOccurs: "1" 5814 maxOccurs: "1" 5816 type: "master" 5818 definition: Specifies which other elements the metadata represented 5819 by the Tag applies to. If empty or not present, then the Tag 5820 describes everything in the Segment. 5822 9.3.8.1.1.1. TargetTypeValue Element 5824 name: "TargetTypeValue" 5826 path: "0*1(\Segment\Tags\Tag\Targets\TargetTypeValue)" 5828 id: "0x68CA" 5830 maxOccurs: "1" 5832 default: "50" 5834 type: "uinteger" 5836 definition: A number to indicate the logical level of the target. 5838 restrictions: 5840 +-------+--------------------------+--------------------------------+ 5841 | value | label | documentation | 5842 +=======+==========================+================================+ 5843 | "70" | COLLECTION | The highest hierarchical level | 5844 | | | that tags can describe. | 5845 +-------+--------------------------+--------------------------------+ 5846 | "60" | EDITION / ISSUE / | A list of lower levels grouped | 5847 | | VOLUME / OPUS / | together. | 5848 | | SEASON / SEQUEL | | 5849 +-------+--------------------------+--------------------------------+ 5850 | "50" | ALBUM / OPERA / | The most common grouping level | 5851 | | CONCERT / MOVIE / | of music and video (equals to | 5852 | | EPISODE / CONCERT | an episode for TV series). | 5853 +-------+--------------------------+--------------------------------+ 5854 | "40" | PART / SESSION | When an album or episode has | 5855 | | | different logical parts. | 5856 +-------+--------------------------+--------------------------------+ 5857 | "30" | TRACK / SONG / | The common parts of an album | 5858 | | CHAPTER | or movie. | 5859 +-------+--------------------------+--------------------------------+ 5860 | "20" | SUBTRACK / PART / | Corresponds to parts of a | 5861 | | MOVEMENT / SCENE | track for audio (like a | 5862 | | | movement). | 5863 +-------+--------------------------+--------------------------------+ 5864 | "10" | SHOT | The lowest hierarchy found in | 5865 | | | music or movies. | 5866 +-------+--------------------------+--------------------------------+ 5868 Table 42 5870 9.3.8.1.1.2. TargetType Element 5872 name: "TargetType" 5874 path: "0*1(\Segment\Tags\Tag\Targets\TargetType)" 5876 id: "0x63CA" 5878 maxOccurs: "1" 5880 type: "string" 5882 definition: An informational string that can be used to display the 5883 logical level of the target like "ALBUM", "TRACK", "MOVIE", 5884 "CHAPTER", etc (see TargetType). 5886 restrictions: 5888 +--------------+------------+ 5889 | value | label | 5890 +==============+============+ 5891 | "COLLECTION" | COLLECTION | 5892 +--------------+------------+ 5893 | "EDITION" | EDITION | 5894 +--------------+------------+ 5895 | "ISSUE" | ISSUE | 5896 +--------------+------------+ 5897 | "VOLUME" | VOLUME | 5898 +--------------+------------+ 5899 | "OPUS" | OPUS | 5900 +--------------+------------+ 5901 | "SEASON" | SEASON | 5902 +--------------+------------+ 5903 | "SEQUEL" | SEQUEL | 5904 +--------------+------------+ 5905 | "ALBUM" | ALBUM | 5906 +--------------+------------+ 5907 | "OPERA" | OPERA | 5908 +--------------+------------+ 5909 | "CONCERT" | CONCERT | 5910 +--------------+------------+ 5911 | "MOVIE" | MOVIE | 5912 +--------------+------------+ 5913 | "EPISODE" | EPISODE | 5914 +--------------+------------+ 5915 | "PART" | PART | 5916 +--------------+------------+ 5917 | "SESSION" | SESSION | 5918 +--------------+------------+ 5919 | "TRACK" | TRACK | 5920 +--------------+------------+ 5921 | "SONG" | SONG | 5922 +--------------+------------+ 5923 | "CHAPTER" | CHAPTER | 5924 +--------------+------------+ 5925 | "SUBTRACK" | SUBTRACK | 5926 +--------------+------------+ 5927 | "PART" | PART | 5928 +--------------+------------+ 5929 | "MOVEMENT" | MOVEMENT | 5930 +--------------+------------+ 5931 | "SCENE" | SCENE | 5932 +--------------+------------+ 5933 | "SHOT" | SHOT | 5934 +--------------+------------+ 5936 Table 43 5938 9.3.8.1.1.3. TagTrackUID Element 5940 name: "TagTrackUID" 5942 path: "0*(\Segment\Tags\Tag\Targets\TagTrackUID)" 5944 id: "0x63C5" 5946 default: "0" 5948 type: "uinteger" 5950 definition: A unique ID to identify the Track(s) the tags belong to. 5951 If the value is 0 at this level, the tags apply to all tracks in the 5952 Segment. 5954 9.3.8.1.1.4. TagEditionUID Element 5956 name: "TagEditionUID" 5958 path: "0*(\Segment\Tags\Tag\Targets\TagEditionUID)" 5960 id: "0x63C9" 5962 default: "0" 5964 type: "uinteger" 5965 definition: A unique ID to identify the EditionEntry(s) the tags 5966 belong to. If the value is 0 at this level, the tags apply to all 5967 editions in the Segment. 5969 9.3.8.1.1.5. TagChapterUID Element 5971 name: "TagChapterUID" 5973 path: "0*(\Segment\Tags\Tag\Targets\TagChapterUID)" 5975 id: "0x63C4" 5977 default: "0" 5979 type: "uinteger" 5981 definition: A unique ID to identify the Chapter(s) the tags belong 5982 to. If the value is 0 at this level, the tags apply to all chapters 5983 in the Segment. 5985 9.3.8.1.1.6. TagAttachmentUID Element 5987 name: "TagAttachmentUID" 5989 path: "0*(\Segment\Tags\Tag\Targets\TagAttachmentUID)" 5991 id: "0x63C6" 5993 default: "0" 5995 type: "uinteger" 5997 definition: A unique ID to identify the Attachment(s) the tags belong 5998 to. If the value is 0 at this level, the tags apply to all the 5999 attachments in the Segment. 6001 9.3.8.1.2. SimpleTag Element 6003 name: "SimpleTag" 6005 path: "1*(\Segment\Tags\Tag(1*(\SimpleTag)))" 6007 id: "0x67C8" 6009 minOccurs: "1" 6011 type: "master" 6012 definition: Contains general information about the target. 6014 9.3.8.1.2.1. TagName Element 6016 name: "TagName" 6018 path: "1*1(\Segment\Tags\Tag\SimpleTag\TagName)" 6020 id: "0x45A3" 6022 minOccurs: "1" 6024 maxOccurs: "1" 6026 type: "utf-8" 6028 definition: The name of the Tag that is going to be stored. 6030 9.3.8.1.2.2. TagLanguage Element 6032 name: "TagLanguage" 6034 path: "1*1(\Segment\Tags\Tag\SimpleTag\TagLanguage)" 6036 id: "0x447A" 6038 minOccurs: "1" 6040 maxOccurs: "1" 6042 default: "und" 6044 type: "string" 6046 definition: Specifies the language of the tag specified, in the 6047 Matroska languages form. This Element MUST be ignored if the 6048 TagLanguageIETF Element is used within the same SimpleTag Element. 6050 9.3.8.1.2.3. TagLanguageIETF Element 6052 name: "TagLanguageIETF" 6054 path: "0*1(\Segment\Tags\Tag\SimpleTag\TagLanguageIETF)" 6056 id: "0x447B" 6058 maxOccurs: "1" 6059 type: "string" 6061 minver: "4" 6063 definition: Specifies the language used in the TagString according to 6064 BCP 47 and using the IANA Language Subtag Registry. If this Element 6065 is used, then any TagLanguage Elements used in the same SimpleTag 6066 MUST be ignored. 6068 9.3.8.1.2.4. TagDefault Element 6070 name: "TagDefault" 6072 path: "1*1(\Segment\Tags\Tag\SimpleTag\TagDefault)" 6074 id: "0x4484" 6076 minOccurs: "1" 6078 maxOccurs: "1" 6080 range: "0-1" 6082 default: "1" 6084 type: "uinteger" 6086 definition: A boolean value to indicate if this is the default/ 6087 original language to use for the given tag. 6089 9.3.8.1.2.5. TagString Element 6091 name: "TagString" 6093 path: "0*1(\Segment\Tags\Tag\SimpleTag\TagString)" 6095 id: "0x4487" 6097 maxOccurs: "1" 6099 type: "utf-8" 6101 definition: The value of the Tag. 6103 9.3.8.1.2.6. TagBinary Element 6105 name: "TagBinary" 6106 path: "0*1(\Segment\Tags\Tag\SimpleTag\TagBinary)" 6108 id: "0x4485" 6110 maxOccurs: "1" 6112 type: "binary" 6114 definition: The values of the Tag if it is binary. Note that this 6115 cannot be used in the same SimpleTag as TagString. 6117 10. Matroska Element Ordering 6119 Except for the "EBML Header" and the "CRC-32 Element", the EBML 6120 specification does not require any particular storage order for 6121 "Elements". The Matroska specification however defines mandates and 6122 recommendations for ordering certain "Elements" in order to 6123 facilitate better playback, seeking, and editing efficiency. This 6124 section describes and offers rationale for ordering requirements and 6125 recommendations for Matroska. 6127 10.1. Top-Level Elements 6129 The "Info Element" is the only REQUIRED "Top-Level Element" in a 6130 Matroska file. To be playable, Matroska MUST also contain at least 6131 one "Tracks Element" and "Cluster Element". The first "Info Element" 6132 and the first "Tracks Element" MUST either be stored before the first 6133 "Cluster Element" or both SHALL be referenced by a "SeekHead Element" 6134 occurring before the first "Cluster Element". 6136 It is possible to edit a Matroska file after it has been created. 6137 For example, chapters, tags or attachments can be added. When new 6138 "Top-Level Elements" are added to a Matroska file, the "SeekHead" 6139 Element(s) MUST be updated so that the "SeekHead" Element(s) itemize 6140 the identity and position of all "Top-Level Elements". Editing, 6141 removing, or adding "Elements" to a Matroska file often requires that 6142 some existing "Elements" be voided or extended; therefore, it is 6143 RECOMMENDED to use "Void Elements" as padding in between "Top-Level 6144 Elements". 6146 10.2. CRC-32 6148 As noted by the EBML specification, if a "CRC-32 Element" is used 6149 then the "CRC-32 Element" MUST be the first ordered "Element" within 6150 its "Parent Element". The Matroska specification recommends that 6151 "CRC-32 Elements" SHOULD NOT be used as an immediate "Child Element" 6152 of the "Segment Element"; however all "Top-Level Elements" of an 6153 "EBML Document" SHOULD include a "CRC-32 Element" as a "Child 6154 Element". 6156 10.3. SeekHead 6158 If used, the first "SeekHead Element" SHOULD be the first non-"CRC-32 6159 Child Element" of the "Segment Element". If a second "SeekHead 6160 Element" is used, then the first "SeekHead Element" MUST reference 6161 the identity and position of the second "SeekHead". Additionally, 6162 the second "SeekHead Element" MUST only reference "Cluster" Elements 6163 and not any other "Top-Level Element" already contained within the 6164 first "SeekHead Element". The second "SeekHead Element" MAY be 6165 stored in any order relative to the other "Top-Level Elements." 6166 Whether one or two "SeekHead Element(s)" are used, the "SeekHead 6167 Element(s)" MUST collectively reference the identity and position of 6168 all "Top-Level Elements" except for the first "SeekHead Element". 6170 It is RECOMMENDED that the first "SeekHead Element" be followed by a 6171 "Void Element" to allow for the "SeekHead Element" to be expanded to 6172 cover new "Top-Level Elements" that could be added to the Matroska 6173 file, such as "Tags", "Chapters" and "Attachments Elements". 6175 10.4. Cues (index) 6177 The "Cues Element" is RECOMMENDED to optimize seeking access in 6178 Matroska. It is programmatically simpler to add the "Cues Element" 6179 after all "Cluster Elements" have been written because this does not 6180 require a prediction of how much space to reserve before writing the 6181 "Cluster Elements". However, storing the "Cues Element" before the 6182 "Cluster Elements" can provide some seeking advantages. If the "Cues 6183 Element" is present, then it SHOULD either be stored before the first 6184 "Cluster Element" or be referenced by a "SeekHead Element". 6186 10.5. Info 6188 The first "Info Element" SHOULD occur before the first "Tracks 6189 Element" and first "Cluster Element" except when referenced by a 6190 "SeekHead Element". 6192 10.6. Chapters Element 6194 The "Chapters Element" SHOULD be placed before the "Cluster 6195 Element(s)". The "Chapters Element" can be used during playback even 6196 if the user does not need to seek. It immediately gives the user 6197 information about what section is being read and what other sections 6198 are available. In the case of Ordered Chapters it RECOMMENDED to 6199 evaluate the logical linking even before playing. The "Chapters 6200 Element" SHOULD be placed before the first "Tracks Element" and after 6201 the first "Info Element". 6203 10.7. Attachments 6205 The "Attachments Element" is not intended to be used by default when 6206 playing the file, but could contain information relevant to the 6207 content, such as cover art or fonts. Cover art is useful even before 6208 the file is played and fonts could be needed before playback starts 6209 for initialization of subtitles. The "Attachments Element" MAY be 6210 placed before the first "Cluster Element"; however if the 6211 "Attachments Element" is likely to be edited, then it SHOULD be 6212 placed after the last "Cluster Element". 6214 10.8. Tags 6216 The "Tags Element" is most subject to changes after the file was 6217 originally created. For easier editing, the "Tags Element" SHOULD be 6218 placed at the end of the "Segment Element", even after the 6219 "Attachments Element". On the other hand, it is inconvenient to have 6220 to seek in the "Segment" for tags, especially for network streams. 6221 So it's better if the "Tags Element" is found early in the stream. 6222 When editing the "Tags Element", the original "Tags Element" at the 6223 beginning can be overwritten with a "Void Element" and a new "Tags 6224 Element" written at the end of the "Segment Element". The file size 6225 will only marginally change. 6227 10.9. Optimum layout from a muxer 6229 * SeekHead 6231 * Info 6233 * Tracks 6235 * Chapters 6237 * Attachments 6239 * Tags 6240 * Clusters 6242 * Cues 6244 10.10. Optimum layout after editing tags 6246 * SeekHead 6248 * Info 6250 * Tracks 6252 * Chapters 6254 * Attachments 6256 * Void 6258 * Clusters 6260 * Cues 6262 * Tags 6264 10.11. Optimum layout with Cues at the front 6266 * SeekHead 6268 * Info 6270 * Tracks 6272 * Chapters 6274 * Attachments 6276 * Tags 6278 * Cues 6280 * Clusters 6282 10.12. Cluster Timestamp 6284 The "Timestamp Element" MUST occur as in storage order before any 6285 "SimpleBlock", "BlockGroup", or "EncryptedBlock" within the "Cluster 6286 Element". 6288 11. Chapters 6290 11.1. Edition and Chapter Flags 6292 11.1.1. Chapter Flags 6294 Two "Chapter Flags" are defined to describe the behavior of the 6295 "ChapterAtom Element": "ChapterFlagHidden" and "ChapterFlagEnabled". 6297 If a "ChapterAtom Element" is the "Child Element" of another 6298 "ChapterAtom Element" with a "Chapter Flag" set to "true", then the 6299 "Child ChapterAtom Element" MUST be interpreted as having its same 6300 "Chapter Flag" set to "true". If a "ChapterAtom Element" is the 6301 "Child Element" of another "ChapterAtom Element" with a "Chapter 6302 Flag" set to "false" or if the "ChapterAtom Element" does not have a 6303 "ChapterAtom Element" as its "Parent Element", then it MUST be 6304 interpreted according to its own "Chapter Flag". 6306 As an example, consider a "Parent ChapterAtom Element" that has its 6307 "ChapterFlagHidden" set to "true" and also contains two child 6308 "ChapterAtoms", the first with "ChapterFlagHidden" set to "true" and 6309 the second with "ChapterFlagHidden" either set to "false" or not 6310 present at all (in which case the default value of the Element 6311 applies, which is "false"). Since the parent "ChapterAtom" has its 6312 "ChapterFlagHidden" set to "true" then all of its children 6313 "ChapterAtoms" MUST also be interpreted as if their 6314 "ChapterFlagHidden" is also set to "true". However, if a "Control 6315 Track" toggles the parent's "ChapterFlagHidden" flag to "false", then 6316 only the parent "ChapterAtom" and its second child "ChapterAtom" MUST 6317 be interpreted as if "ChapterFlagHidden" is set to "false". The 6318 first child "ChapterAtom" which has the "ChapterFlagHidden" flag set 6319 to "true" retains its value until its value is toggled to "false" by 6320 a "Control Track". 6322 11.1.2. Edition Flags 6324 Three "Edition Flags" are defined to describe the behavior of the 6325 "EditionEntry Element": "EditionFlagHidden", "EditionFlagDefault" and 6326 "EditionFlagOrdered". 6328 11.1.2.1. EditionFlagHidden 6330 The "EditionFlagHidden Flag" behaves similarly to the 6331 "ChapterFlagHidden Flag": if "EditionFlagHidden" is set to "true", 6332 its "Child ChapterAtoms Elements" MUST also be interpreted as if 6333 their "ChapterFlagHidden" is also set to "true", regardless of their 6334 own "ChapterFlagHidden Flags". If "EditionFlagHidden" is toggled by 6335 a "Control Track" to "false", the "ChapterFlagHidden Flags" of the 6336 "Child ChapterAtoms Elements" SHALL determine whether the 6337 "ChapterAtom" is hidden or not. 6339 11.1.2.2. EditionFlagDefault 6341 It is RECOMMENDED that no more than one "Edition" have an 6342 "EditionFlagDefault Flag" set to "true". The first "Edition" with 6343 both the "EditionFlagDefault Flag" set to "true" and the 6344 "EditionFlagHidden Flag" set to "false" is the "Default Edition". 6345 When all "EditionFlagDefault Flags" are set to "false", then the 6346 first "Edition" is the "Default Edition". 6348 11.1.2.3. EditionFlagOrdered 6350 The "EditionFlagOrdered Flag" is a significant feature as it enables 6351 an "Edition" of "Ordered Chapters" which defines and arranges a 6352 virtual timeline rather than simply labeling points within the 6353 timeline. For example, with "Editions" of "Ordered Chapters" a 6354 single "Matroska file" can present multiple edits of a film without 6355 duplicating content. Alternatively if a videotape is digitized in 6356 full, one "Ordered Edition" could present the full content (including 6357 colorbars, countdown, slate, a feature presentation, and black 6358 frames), while another "Edition" of "Ordered Chapters" can use 6359 "Chapters" that only mark the intended presentation with the 6360 colorbars and other ancillary visual information excluded. If an 6361 "Edition" of "Ordered Chapters" is enabled then the "Matroska Player" 6362 MUST play those Chapters in their stored order from the timestamp 6363 marked in the "ChapterTimeStart Element" to the timestamp marked in 6364 to "ChapterTimeEnd Element". 6366 If the "EditionFlagOrdered Flag" is set to "false", "Simple Chapters" 6367 are used and only the "ChapterTimeStart" of a "Chapter" is used as 6368 chapter mark to jump to the predefined point in the timeline. With 6369 "Simple Chapters", a "Matroska Player" MUST ignore certain "Chapter 6370 Elements". All these elements are now informational only. 6372 The following list shows the different usage of "Chapter Elements" 6373 between an ordered and non-ordered "Edition". 6375 Chapter elements / ordered Edition | False | True ChapterUID | X | X 6376 ChapterStringUID | X | X ChapterTimeStart | X | X ChapterTimeEnd | 6377 - | X ChapterFlagHidden | X | X ChapterFlagEnabled | X | X 6378 ChapterSegmentUID | - | X ChapterSegmentEditionUID | - | X 6379 ChapterPhysicalEquiv | X | X ChapterTrack | - | X ChapterDisplay | 6380 X | X ChapProcess | - | X 6382 Furthermore there are other EBML "Elements" which could be used if 6383 the "EditionFlagOrdered Flag" is set to "true". 6385 Other elements / ordered Edition | False | True Info/SegmentFamily | 6386 - | X Info/ChapterTranslate | - | X Track/TrackTranslate | - | X 6388 These other "Elements" belong to the Matroska DVD menu system and are 6389 only used when the "ChapProcessCodecID Element" is set to 1. 6391 11.1.2.3.1. Ordered-Edition and Matroska Segment-Linking 6393 * Hard Linking: "Ordered-Chapters" supersedes the "Hard Linking". 6395 * Soft Linking: In this complex system "Ordered Chapters" are 6396 REQUIRED and a "Chapter CODEC" MUST interpret the "ChapProcess" of 6397 all chapters. 6399 * Medium Linking: "Ordered Chapters" are used in a normal way and 6400 can be combined with the "ChapterSegmentUID" element which 6401 establishes a link to another Matroska file/Segment. 6403 See the section on the Linked Segments (#linked-segments)) for more 6404 information about "Hard Linking", "Soft Linking" and "Medium 6405 Linking". 6407 11.2. Menu features 6409 The menu features are handled like a _chapter codec_. That means each 6410 codec has a type, some private data and some data in the chapters. 6412 The type of the menu system is defined by the "ChapProcessCodecID" 6413 parameter. For now only 2 values are supported : 0 matroska script, 6414 1 menu borrowed from the DVD. The private data depend on the type of 6415 menu system (stored in ChapProcessPrivate), idem for the data in the 6416 chapters (stored in ChapProcessData). 6418 11.2.1. Matroska Script (0) 6420 This is the case when "ChapProcessCodecID" = 0. This is a script 6421 language build for Matroska purposes. The inspiration comes from 6422 ActionScript, javascript and other similar scripting languages. The 6423 commands are stored as text commands, in UTF-8. The syntax is C 6424 like, with commands spanned on many lines, each terminating with a 6425 ";". You can also include comments at the end of lines with "//" or 6426 comment many lines using "/* */". The scripts are stored in 6427 ChapProcessData. For the moment ChapProcessPrivate is not used. 6429 The one and only command existing for the moment is "GotoAndPlay( 6430 ChapterUID );". As the same suggests, it means that when this 6431 command is encountered, the "Matroska Player" SHOULD jump to the 6432 "Chapter" specified by the UID and play it. 6434 11.2.2. DVD menu (1) 6436 This is the case when "ChapProcessCodecID" = 1. Each level of a 6437 chapter corresponds to a logical level in the DVD system that is 6438 stored in the first octet of the ChapProcessPrivate. This DVD 6439 hierarchy is as follows: 6441 ChapProcessPrivate | DVD Name | Hierarchy | Commands Possible | 6442 Comment 0x30 | SS | DVD domain | - | First Play, Video Manager, Video 6443 Title 0x2A | LU | Language Unit | - | Contains only PGCs 0x28 | TT | 6444 Title | - | Contains only PGCs 0x20 | PGC | Program Group Chain 6445 (PGC) | * | 0x18 | PG | Program 1 / Program 2 / Program 3 | - | 6446 0x10 | PTT | Part Of Title 1 / Part Of Title 2 | - | Equivalent to 6447 the chapters on the sleeve. 0x08 | CN | Cell 1 / Cell 2 / Cell 3 / 6448 Cell 4 / Cell 5 / Cell 6 | - | 6450 You can also recover wether a Segment is a Video Manager (VMG), Video 6451 Title Set (VTS) or Video Title Set Menu (VTSM) from the 6452 ChapterTranslateID element found in the Segment Info. This field 6453 uses 2 octets as follows: 6455 1. Domain Type: 0 for VMG, the domain number for VTS and VTSM 6457 2. Domain Value: 0 for VMG and VTSM, 1 for the VTS source. 6459 For instance, the menu part from VTS_01_0.VOB would be coded [1,0] 6460 and the content part from VTS_02_3.VOB would be [2,1]. The VMG is 6461 always [0,0] 6463 The following octets of ChapProcessPrivate are as follows: 6465 Octet 1 | DVD Name | Following Octets 0x30 | SS | Domain name code 6466 (1: 0x00= First play, 0xC0= VMG, 0x40= VTSM, 0x80= VTS) + VTS(M) 6467 number (2) 0x2A | LU | Language code (2) + Language extension (1) 6468 0x28 | TT | global Title number (2) + corresponding TTN of the VTS 6469 (1) 0x20 | PGC | PGC number (2) + Playback Type (1) + Disabled User 6470 Operations (4) 0x18 | PG | Program number (2) 0x10 | PTT | PTT- 6471 chapter number (1) 0x08 | CN | Cell number [VOB ID(2)][Cell 6472 ID(1)][Angle Num(1)] 6474 If the level specified in ChapProcessPrivate is a PGC (0x20), there 6475 is an octet called the Playback Type, specifying the kind of PGC 6476 defined: 6478 * 0x00: entry only/basic PGC 6480 * 0x82: Title+Entry Menu (only found in the Video Manager domain) 6481 * 0x83: Root Menu (only found in the VTSM domain) 6483 * 0x84: Subpicture Menu (only found in the VTSM domain) 6485 * 0x85: Audio Menu (only found in the VTSM domain) 6487 * 0x86: Angle Menu (only found in the VTSM domain) 6489 * 0x87: Chapter Menu (only found in the VTSM domain) 6491 The next 4 following octets correspond to the User Operation flags 6492 (http://dvd.sourceforge.net/dvdinfo/uops.html) in the standard PGC. 6493 When a bit is set, the command SHOULD be disabled. 6495 ChapProcessData contains the pre/post/cell commands in binary format 6496 as there are stored on a DVD. There is just an octet preceding these 6497 data to specify the number of commands in the element. As follows: 6498 [# of commands(1)][command 1 (8)][command 2 (8)][command 3 (8)]. 6500 More information on the DVD commands and format on DVD-replica 6501 (http://www.dvd-replica.com/DVD/), where we got most of the info 6502 about it. You can also get information on DVD from the DVDinfo 6503 project (http://dvd.sourceforge.net/dvdinfo/). 6505 11.3. Example 1 : basic chaptering 6507 In this example a movie is split in different chapters. It could 6508 also just be an audio file (album) on which each track corresponds to 6509 a chapter. 6511 * 00000ms - 05000ms : Intro 6513 * 05000ms - 25000ms : Before the crime 6515 * 25000ms - 27500ms : The crime 6517 * 27500ms - 38000ms : The killer arrested 6519 * 38000ms - 43000ms : Credits 6521 This would translate in the following matroska form : 6523 16603393396715046047 1193046 0 5000000000 Intro eng 0 1 2311527 5000000000 25000000000 Before the crime eng Avant le crime fra 0 1 3430008 25000000000 27500000000 The crime eng Le crime fra 0 1 4548489 27500000000 38000000000 After the crime eng Apres le crime fra 0 1 5666960 38000000000 43000000000 Credits eng Generique fra 0 1 0 0 6525 11.4. Example 2 : nested chapters 6527 In this example an (existing) album is split into different chapters, 6528 and one of them contain another splitting. 6530 11.4.1. The Micronauts "Bleep To Bleep" 6532 * 00:00 - 12:28 : Baby Wants To Bleep/Rock 6534 - 00:00 - 04:38 : Baby wants to bleep (pt.1) 6536 - 04:38 - 07:12 : Baby wants to rock 6538 - 07:12 - 10:33 : Baby wants to bleep (pt.2) 6540 - 10:33 - 12:28 : Baby wants to bleep (pt.3) 6542 * 12:30 - 19:38 : Bleeper_O+2 6544 * 19:40 - 22:20 : Baby wants to bleep (pt.4) 6546 * 22:22 - 25:18 : Bleep to bleep 6548 * 25:20 - 33:35 : Baby wants to bleep (k) 6550 * 33:37 - 44:28 : Bleeper 6552 1281690858003401414 1 0 748000000 Baby wants to Bleep/Rock eng 2 0 278000000 Baby wants to bleep (pt.1) eng 0 1 3 278000000 432000000 Baby wants to rock eng 0 1 4 432000000 633000000 Baby wants to bleep (pt.2) eng 0 1 5 633000000 748000000 Baby wants to bleep (pt.3) eng 0 1 0 1 6 750000000 1178500000 Bleeper_O+2 eng 0 1 7 1180500000 1340000000 Baby wants to bleep (pt.4) eng 0 1 8 1342000000 1518000000 Bleep to bleep eng 0 1 9 1520000000 2015000000 Baby wants to bleep (k) eng 0 1 10 2017000000 2668000000 Bleeper eng 0 1 0 0 6554 12. Attachments 6556 Matroska supports storage of related files and data in the 6557 "Attachments Element" (a "Top-Level Element"). "Attachment Elements" 6558 can be used to store related cover art, font files, transcripts, 6559 reports, error recovery files, picture or text-based annotations, 6560 copies of specifications, or other ancillary files related to the 6561 "Segment". 6563 "Matroska Readers" MUST NOT execute files stored as "Attachment 6564 Elements". 6566 12.1. Cover Art 6568 This section defines a set of guidelines for the storage of cover art 6569 in Matroska files. A "Matroska Reader" MAY use embedded cover art to 6570 display a representational still-image depiction of the multimedia 6571 contents of the Matroska file. 6573 Only JPEG and PNG image formats SHOULD be used for cover art 6574 pictures. 6576 There can be two different covers for a movie/album: a portrait style 6577 (e.g., a DVD case) and a landscape style (e.g., a wide banner ad). 6579 There can be two versions of the same cover, the "normal cover" and 6580 the "small cover". The dimension of the "normal cover" SHOULD be 600 6581 pixels on the smallest side (for example, 960x600 for landscape, 6582 600x800 for portrait, or 600x600 for square). The dimension of the 6583 "small cover" SHOULD be 120 pixels on the smallest side (for example, 6584 192x120 or 120x160). 6586 Versions of cover art can be differentiated by the filename, which is 6587 stored in the "FileName Element". The default filename of the 6588 "normal cover" in square or portrait mode is "cover.(jpg|png)". When 6589 stored, the "normal cover" SHOULD be the first Attachment in storage 6590 order. The "small cover" SHOULD be prefixed with "small_", such as 6591 "small_cover.(jpg|png)". The landscape variant SHOULD be suffixed 6592 with "_land", such as "cover_land.(jpg|png)". The filenames are case 6593 sensitive. 6595 The following table provides examples of file names for cover art in 6596 Attachments. 6598 FileName | Image Orientation | Pixel Length of Smallest Side 6599 cover.jpg | Portrait or square | 600 small_cover.png | Portrait or 6600 square | 120 cover_land.png | Landscape | 600 small_cover_land.jpg | 6601 Landscape | 120 6603 13. Cues 6605 The "Cues Element" provides an index of certain "Cluster Elements" to 6606 allow for optimized seeking to absolute timestamps within the 6607 "Segment". The "Cues Element" contains one or many "CuePoint 6608 Elements" which each MUST reference an absolute timestamp (via the 6609 "CueTime Element"), a "Track" (via the "CueTrack Element"), and a 6610 "Segment Position" (via the "CueClusterPosition Element"). 6611 Additional non-mandated Elements are part of the "CuePoint Element" 6612 such as "CueDuration", "CueRelativePosition", "CueCodecState" and 6613 others which provide any "Matroska Reader" with additional 6614 information to use in the optimization of seeking performance. 6616 13.1. Recommendations 6618 The following recommendations are provided to optimize Matroska 6619 performance. 6621 * Unless Matroska is used as a live stream, it SHOULD contain a 6622 "Cues Element". 6624 * For each video track, each keyframe SHOULD be referenced by a 6625 "CuePoint Element". 6627 * It is RECOMMENDED to not reference non-keyframes of video tracks 6628 in "Cues" unless it references a "Cluster Element" which contains 6629 a "CodecState Element" but no keyframes. 6631 * For each subtitle track present, each subtitle frame SHOULD be 6632 referenced by a "CuePoint Element" with a "CueDuration Element". 6634 * References to audio tracks MAY be skipped in "CuePoint Elements" 6635 if a video track is present. When included the "CuePoint 6636 Elements" SHOULD reference audio keyframes at most once every 500 6637 milliseconds. 6639 * If the referenced frame is not stored within the first 6640 "SimpleBlock" or first "BlockGroup" within its "Cluster Element", 6641 then the "CueRelativePosition Element" SHOULD be written to 6642 reference where in the "Cluster" the reference frame is stored. 6644 * If a "CuePoint Element" references "Cluster Element" that includes 6645 a "CodecState Element", then that "CuePoint Element" MUST use a 6646 "CueCodecState Element". 6648 * "CuePoint Elements" SHOULD be numerically sorted in storage order 6649 by the value of the "CueTime Element". 6651 14. Matroska Streaming 6653 In Matroska, there are two kinds of streaming: file access and 6654 livestreaming. 6656 14.1. File Access 6658 File access can simply be reading a file located on your computer, 6659 but also includes accessing a file from an HTTP (web) server or CIFS 6660 (Windows share) server. These protocols are usually safe from 6661 reading errors and seeking in the stream is possible. However, when 6662 a file is stored far away or on a slow server, seeking can be an 6663 expensive operation and SHOULD be avoided. The following guidelines, 6664 when followed, help reduce the number of seeking operations for 6665 regular playback and also have the playback start quickly without a 6666 lot of data needed to read first (like a "Cues Element", "Attachment 6667 Element" or "SeekHead Element"). 6669 Matroska, having a small overhead, is well suited for storing music/ 6670 videos on file servers without a big impact on the bandwidth used. 6671 Matroska does not require the index to be loaded before playing, 6672 which allows playback to start very quickly. The index can be loaded 6673 only when seeking is requested the first time. 6675 14.2. Livestreaming 6677 Livestreaming is the equivalent of television broadcasting on the 6678 internet. There are 2 families of servers for livestreaming: RTP/ 6679 RTSP and HTTP. Matroska is not meant to be used over RTP. RTP 6680 already has timing and channel mechanisms that would be wasted if 6681 doubled in Matroska. Additionally, having the same information at 6682 the RTP and Matroska level would be a source of confusion if they do 6683 not match. Livestreaming of Matroska over HTTP (or any other plain 6684 protocol based on TCP) is possible. 6686 A live Matroska stream is different from a file because it usually 6687 has no known end (only ending when the client disconnects). For 6688 this, all bits of the "size" portion of the "Segment Element" MUST be 6689 set to 1. Another option is to concatenate "Segment Elements" with 6690 known sizes, one after the other. This solution allows a change of 6691 codec/resolution between each segment. For example, this allows for 6692 a switch between 4:3 and 16:9 in a television program. 6694 When "Segment Elements" are continuous, certain "Elements", like 6695 "MetaSeek", "Cues", "Chapters", and "Attachments", MUST NOT be used. 6697 It is possible for a "Matroska Player" to detect that a stream is not 6698 seekable. If the stream has neither a "MetaSeek" list or a "Cues" 6699 list at the beginning of the stream, it SHOULD be considered non- 6700 seekable. Even though it is possible to seek blindly forward in the 6701 stream, it is NOT RECOMMENDED. 6703 In the context of live radio or web TV, it is possible to "tag" the 6704 content while it is playing. The "Tags Element" can be placed 6705 between "Clusters" each time it is necessary. In that case, the new 6706 "Tags Element" MUST reset the previously encountered "Tags Elements" 6707 and use the new values instead. 6709 15. Menu Specifications 6711 This document is a _draft of the Menu system_ that will be the 6712 default one in "Matroska". As it will just be composed of a Control 6713 Track, it will be seen as a "codec" and could be replaced later by 6714 something else if needed. 6716 A menu is like what you see on DVDs, when you have some screens to 6717 select the audio format, subtitles or scene selection. 6719 15.1. Requirements 6721 What we'll try to have is a system that can do almost everything done 6722 on a DVD, or more, or better, or drop the unused features if 6723 necessary. 6725 As the name suggests, a Control Track is a track that can control the 6726 playback of the file and/or all the playback features. To make it as 6727 simple as possible for "Matroska Players", the Control Track will 6728 just give orders to the "Matroska Player" and get the actions 6729 associated with the highlights/hotspots. 6731 15.1.1. Highlights/Hotspots 6733 A highlight is basically a rectangle/key associated with an action 6734 UID. When that rectangle/key is activated, the "Matroska Player" 6735 send the UID of the action to the Control Track handler (codec). The 6736 fact that it can also be a key means that even for audio only files, 6737 a keyboard shortcut or button panel could be used for menus. But in 6738 that case, the hotspot will have to be associated with a name to 6739 display. 6741 This highlight is sent from the Control Track to the "Matroska 6742 Player". Then the "Matroska Player" has to handle that highlight 6743 until it's deactivated (see Playback Features (#playback-features)). 6745 The highlight contains a UID of the action, a displayable name (UTF- 6746 8), an associated key (list of keys to be defined, probably 6747 up/down/left/right/select), a screen position/range and an image to 6748 display. The image will be displayed either when the user place the 6749 mouse over the rectangle (or any other shape), or when an option of 6750 the screen is selected (not activated). There could be a second 6751 image used when the option is activated. And there could be a third 6752 image that can serve as background. This way you could have a still 6753 image (like in some DVDs) for the menu and behind that image blank 6754 video (small bitrate). 6756 When a highlight is activated by the user, the "Matroska Player" has 6757 to send the UID of the action to the Control Track. Then the Control 6758 Track codec will handle the action and possibly give new orders to 6759 the "Matroska Player". 6761 The format used for storing images SHOULD be extensible. For the 6762 moment we'll use PNG and BMP, both with alpha channel. 6764 15.1.2. Playback features 6766 All the following features will be sent from the Control Track to the 6767 "Matroska Player" : 6769 * Jump to chapter (UID, prev, next, number) 6771 * Disable all tracks of a kind (audio, video, subtitle) 6773 * Enable track UID (the kind doesn't matter) 6775 * Define/Disable a highlight 6777 * Enable/Disable jumping 6779 * Enable/Disable track selection of a kind 6781 * Select Edition ID (see chapters) 6783 * Pause playback 6785 * Stop playback 6787 * Enable/Disable a Chapter UID 6789 * Hide/Unhide a Chapter UID 6791 All the actions will be written in a normal Matroska track, with a 6792 timestamp. A "Menu Frame" SHOULD be able to contain more that one 6793 action/highlight for a given timestamp. (to be determined, EBML 6794 format structure) 6796 15.1.3. Player requirements 6798 Some "Matroska Players" might not support the control track. That 6799 mean they will play the active/looped parts as part of the data. So 6800 I suggest putting the active/looped parts of a movie at the end of a 6801 movie. When a Menu-aware "Matroska Player" encounter the default 6802 Control Track of a "Matroska" file, the first order SHOULD be to jump 6803 at the start of the active/looped part of the movie. 6805 15.2. Working Graph 6807 Matroska Source file -> Control Track <-> Player. 6808 -> other tracks -> rendered 6810 16. Unknown elements 6812 Matroska is based upon the principle that a reading application does 6813 not have to support 100% of the specifications in order to be able to 6814 play the file. A Matroska file therefore contains version indicators 6815 that tell a reading application what to expect. 6817 It is possible and valid to have the version fields indicate that the 6818 file contains Matroska "Elements" from a higher specification version 6819 number while signaling that a reading application MUST only support a 6820 lower version number properly in order to play it back (possibly with 6821 a reduced feature set). For example, a reading application 6822 supporting at least Matroska version "V" reading a file whose 6823 "DocTypeReadVersion" field is equal to or lower than "V" MUST skip 6824 Matroska/EBML "Elements" it encounters but does not know about if 6825 that unknown element fits into the size constraints set by the 6826 current "Parent Element". 6828 17. Default Values 6830 The default value of an "Element" is assumed when not present in the 6831 data stream. It is assumed only in the scope of its "Parent 6832 Element". For example, the "Language Element" is in the scope of the 6833 "Track Element". If the "Parent Element" is not present or assumed, 6834 then the "Child Element" cannot be assumed. 6836 18. DefaultDecodedFieldDuration 6838 The "DefaultDecodedFieldDuration Element" can signal to the 6839 displaying application how often fields of a video sequence will be 6840 available for displaying. It can be used for both interlaced and 6841 progressive content. If the video sequence is signaled as 6842 interlaced, then the period between two successive fields at the 6843 output of the decoding process equals "DefaultDecodedFieldDuration". 6845 For video sequences signaled as progressive, it is twice the value of 6846 "DefaultDecodedFieldDuration". 6848 These values are valid at the end of the decoding process before 6849 post-processing (such as deinterlacing or inverse telecine) is 6850 applied. 6852 Examples: 6854 * Blu-ray movie: 1000000000ns/(48/1.001) = 20854167ns 6856 * PAL broadcast/DVD: 1000000000ns/(50/1.000) = 20000000ns 6857 * N/ATSC broadcast: 1000000000ns/(60/1.001) = 16683333ns 6859 * hard-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (60 6860 encoded interlaced fields per second) 6862 * soft-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (48 6863 encoded interlaced fields per second, with "repeat_first_field = 6864 1") 6866 19. Encryption 6868 Encryption in Matroska is designed in a very generic style to allow 6869 people to implement whatever form of encryption is best for them. It 6870 is possible to use the encryption framework in Matroska as a type of 6871 DRM (Digital Rights Management). 6873 Because encryption occurs within the "Block Element", it is possible 6874 to manipulate encrypted streams without decrypting them. The streams 6875 could potentially be copied, deleted, cut, appended, or any number of 6876 other possible editing techniques without decryption. The data can 6877 be used without having to expose it or go through the decrypting 6878 process. 6880 Encryption can also be layered within Matroska. This means that two 6881 completely different types of encryption can be used, requiring two 6882 separate keys to be able to decrypt a stream. 6884 Encryption information is stored in the "ContentEncodings Element" 6885 under the "ContentEncryption Element". 6887 20. Image Presentation 6889 20.1. Cropping 6891 The "PixelCrop Elements" ("PixelCropTop", "PixelCropBottom", 6892 "PixelCropRight" and "PixelCropLeft") indicate when and by how much 6893 encoded videos frames SHOULD be cropped for display. These Elements 6894 allow edges of the frame that are not intended for display, such as 6895 the sprockets of a full-frame film scan or the VANC area of a 6896 digitized analog videotape, to be stored but hidden. "PixelCropTop" 6897 and "PixelCropBottom" store an integer of how many rows of pixels 6898 SHOULD be cropped from the top and bottom of the image 6899 (respectively). "PixelCropLeft" and "PixelCropRight" store an 6900 integer of how many columns of pixels SHOULD be cropped from the left 6901 and right of the image (respectively). For example, a pillar-boxed 6902 video that stores a 1440x1080 visual image within the center of a 6903 padded 1920x1080 encoded image MAY set both "PixelCropLeft" and 6904 "PixelCropRight" to "240", so that a "Matroska Player" SHOULD crop 6905 off 240 columns of pixels from the left and right of the encoded 6906 image to present the image with the pillar-boxes hidden. 6908 20.2. Rotation 6910 The ProjectionPoseRoll Element (see Section 9.3.4.1.31.49) can be 6911 used to indicate that the image from the associated video track 6912 SHOULD be rotated for presentation. For instance, the following 6913 representation of the Projection Element Section 9.3.4.1.31.44) and 6914 the ProjectionPoseRoll Element represents a video track where the 6915 image SHOULD be presentation with a 90 degree counter-clockwise 6916 rotation. 6918 90 6920 21. Matroska versioning 6922 The "EBML Header" of each Matroska document informs the reading 6923 application on what version of Matroska to expect. The "Elements" 6924 within "EBML Header" with jurisdiction over this information are 6925 "DocTypeVersion" and "DocTypeReadVersion". 6927 "DocTypeVersion" MUST be equal to or greater than the highest 6928 Matroska version number of any "Element" present in the Matroska 6929 file. For example, a file using the "SimpleBlock Element" MUST have 6930 a "DocTypeVersion" equal to or greater than 2. A file containing 6931 "CueRelativePosition" Elements MUST have a "DocTypeVersion" equal to 6932 or greater than 4. 6934 The "DocTypeReadVersion" MUST contain the minimum version number that 6935 a reading application can minimally support in order to play the file 6936 back -- optionally with a reduced feature set. For example, if a 6937 file contains only "Elements" of version 2 or lower except for 6938 "CueRelativePosition" (which is a version 4 Matroska "Element"), then 6939 "DocTypeReadVersion" SHOULD still be set to 2 and not 4 because 6940 evaluating "CueRelativePosition" is not necessary for standard 6941 playback -- it makes seeking more precise if used. 6943 "DocTypeVersion" MUST always be equal to or greater than 6944 "DocTypeReadVersion". 6946 A reading application supporting Matroska version "V" MUST NOT refuse 6947 to read an application with "DocReadTypeVersion" equal to or lower 6948 than "V" even if "DocTypeVersion" is greater than "V". See also the 6949 note about Unknown Elements (#unknown-elements). 6951 22. MIME Types 6953 There is no IETF endorsed MIME type for Matroska files. These 6954 definitions can be used: 6956 * .mka : Matroska audio "audio/x-matroska" 6958 * .mkv : Matroska video "video/x-matroska" 6960 * .mk3d : Matroska 3D video "video/x-matroska-3d" 6962 23. Segment Position 6964 The "Segment Position" of an "Element" refers to the position of the 6965 first octet of the "Element ID" of that "Element", measured in 6966 octets, from the beginning of the "Element Data" section of the 6967 containing "Segment Element". In other words, the "Segment Position" 6968 of an "Element" is the distance in octets from the beginning of its 6969 containing "Segment Element" minus the size of the "Element ID" and 6970 "Element Data Size" of that "Segment Element". The "Segment 6971 Position" of the first "Child Element" of the "Segment Element" is 0. 6972 An "Element" which is not stored within a "Segment Element", such as 6973 the "Elements" of the "EBML Header", do not have a "Segment 6974 Position". 6976 23.1. Segment Position Exception 6978 "Elements" that are defined to store a "Segment Position" MAY define 6979 reserved values to indicate a special meaning. 6981 23.2. Example of Segment Position 6983 This table presents an example of "Segment Position" by showing a 6984 hexadecimal representation of a very small Matroska file with labels 6985 to show the offsets in octets. The file contains a "Segment Element" 6986 with an "Element ID" of "0x18538067" and a "MuxingApp Element" with 6987 an "Element ID" of "0x4D80". 6989 0 1 2 6990 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 6991 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 6992 0 |1A|45|DF|A3|8B|42|82|88|6D|61|74|72|6F|73|6B|61|18|53|80|67| 6993 20 |93|15|49|A9|66|8E|4D|80|84|69|65|74|66|57|41|84|69|65|74|66| 6995 In the above example, the "Element ID" of the "Segment Element" is 6996 stored at offset 16, the "Element Data Size" of the "Segment Element" 6997 is stored at offset 20, and the "Element Data" of the "Segment 6998 Element" is stored at offset 21. 7000 The "MuxingApp Element" is stored at offset 26. Since the "Segment 7001 Position" of an "Element" is calculated by subtracting the position 7002 of the "Element Data" of the containing "Segment Element" from the 7003 position of that "Element", the "Segment Position" of "MuxingApp 7004 Element" in the above example is "26 - 21" or "5". 7006 24. Linked Segments 7008 Matroska provides several methods to link two or many "Segment 7009 Elements" together to create a "Linked Segment". A "Linked Segment" 7010 is a set of multiple "Segments" related together into a single 7011 presentation by using Hard Linking, Medium Linking, or Soft Linking. 7012 All "Segments" within a "Linked Segment" MUST utilize the same track 7013 numbers and timescale. All "Segments" within a "Linked Segment" MUST 7014 be stored within the same directory. All "Segments" within a "Linked 7015 Segment" MUST store a "SegmentUID". 7017 24.1. Hard Linking 7019 Hard Linking (also called splitting) is the process of creating a 7020 "Linked Segment" by relating multiple "Segment Elements" using the 7021 "NextUID" and "PrevUID" Elements. Within a "Linked Segment", the 7022 timestamps of each "Segment" MUST follow consecutively in linking 7023 order. With Hard Linking, the chapters of any "Segment" within the 7024 "Linked Segment" MUST only reference the current "Segment". With 7025 Hard Linking, the "NextUID" and "PrevUID" MUST reference the 7026 respective "SegmentUID" values of the next and previous "Segments". 7027 The first "Segment" of a "Linked Segment" SHOULD have a "NextUID 7028 Element" and MUST NOT have a "PrevUID Element". The last "Segment" 7029 of a "Linked Segment" SHOULD have a "PrevUID Element" and MUST NOT 7030 have a "NextUID Element". The middle "Segments" of a "Linked 7031 Segment" SHOULD have both a "NextUID Element" and a "PrevUID 7032 Element". 7034 In a chain of "Linked Segments" the "NextUID" always takes precedence 7035 over the "PrevUID". So if SegmentA has a NextUID to SegmentB and 7036 SegmentB has a PrevUID to SegmentC, the link to use is SegmentA to 7037 SegmentB. If SegmentB has a PrevUID to SegmentA but SegmentA has no 7038 NextUID, then the Matroska Player MAY consider these two Segments 7039 linked as SegmentA followed by SegmentB. 7041 As an example, three "Segments" can be Hard Linked as a "Linked 7042 Segment" through cross-referencing each other with "SegmentUID", 7043 "PrevUID", and "NextUID", as in this table. 7045 +------------+----------------+------------------+------------------+ 7046 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7047 +============+================+==================+==================+ 7048 |"start.mkv" |71000c23cd310998| n/a | a77b3598941cb803 | 7049 | |53fbc94dd984a5dd| | eac0fcdafe44fac9 | 7050 +------------+----------------+------------------+------------------+ 7051 |"middle.mkv"|a77b3598941cb803| 71000c23cd310998 | 6c92285fa6d3e827 | 7052 | |eac0fcdafe44fac9| 53fbc94dd984a5dd | b198d120ea3ac674 | 7053 +------------+----------------+------------------+------------------+ 7054 | "end.mkv" |6c92285fa6d3e827| a77b3598941cb803 | n/a | 7055 | |b198d120ea3ac674| eac0fcdafe44fac9 | | 7056 +------------+----------------+------------------+------------------+ 7058 Table 44 7060 An other example where only the "NextUID" Element is used. 7062 +--------------+------------------+-----------+------------------+ 7063 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7064 +==============+==================+===========+==================+ 7065 | "start.mkv" | 71000c23cd310998 | n/a | a77b3598941cb803 | 7066 | | 53fbc94dd984a5dd | | eac0fcdafe44fac9 | 7067 +--------------+------------------+-----------+------------------+ 7068 | "middle.mkv" | a77b3598941cb803 | n/a | 6c92285fa6d3e827 | 7069 | | eac0fcdafe44fac9 | | b198d120ea3ac674 | 7070 +--------------+------------------+-----------+------------------+ 7071 | "end.mkv" | 6c92285fa6d3e827 | n/a | n/a | 7072 | | b198d120ea3ac674 | | | 7073 +--------------+------------------+-----------+------------------+ 7075 Table 45 7077 A next example where only the "PrevUID" Element is used. 7079 +--------------+------------------+------------------+-----------+ 7080 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7081 +==============+==================+==================+===========+ 7082 | "start.mkv" | 71000c23cd310998 | n/a | n/a | 7083 | | 53fbc94dd984a5dd | | | 7084 +--------------+------------------+------------------+-----------+ 7085 | "middle.mkv" | a77b3598941cb803 | 71000c23cd310998 | n/a | 7086 | | eac0fcdafe44fac9 | 53fbc94dd984a5dd | | 7087 +--------------+------------------+------------------+-----------+ 7088 | "end.mkv" | 6c92285fa6d3e827 | a77b3598941cb803 | n/a | 7089 | | b198d120ea3ac674 | eac0fcdafe44fac9 | | 7090 +--------------+------------------+------------------+-----------+ 7092 Table 46 7094 In this example only the "middle.mkv" is using the "PrevUID" and 7095 "NextUID" Elements. 7097 +------------+----------------+------------------+------------------+ 7098 | file name | "SegmentUID" | "PrevUID" | "NextUID" | 7099 +============+================+==================+==================+ 7100 |"start.mkv" |71000c23cd310998| n/a | n/a | 7101 | |53fbc94dd984a5dd| | | 7102 +------------+----------------+------------------+------------------+ 7103 |"middle.mkv"|a77b3598941cb803| 71000c23cd310998 | 6c92285fa6d3e827 | 7104 | |eac0fcdafe44fac9| 53fbc94dd984a5dd | b198d120ea3ac674 | 7105 +------------+----------------+------------------+------------------+ 7106 | "end.mkv" |6c92285fa6d3e827| n/a | n/a | 7107 | |b198d120ea3ac674| | | 7108 +------------+----------------+------------------+------------------+ 7110 Table 47 7112 24.2. Medium Linking 7114 Medium Linking creates relationships between "Segments" using Ordered 7115 Chapters and the "ChapterSegmentUID Element". A "Segment Edition" 7116 with Ordered Chapters MAY contain "Chapter Elements" that reference 7117 timestamp ranges from other "Segments". The "Segment" referenced by 7118 the Ordered Chapter via the "ChapterSegmentUID Element" SHOULD be 7119 played as part of a Linked Segment. The timestamps of Segment 7120 content referenced by Ordered Chapters MUST be adjusted according to 7121 the cumulative duration of the the previous Ordered Chapters. 7123 As an example a file named "intro.mkv" could have a "SegmentUID" of 7124 "0xb16a58609fc7e60653a60c984fc11ead". Another file called 7125 "program.mkv" could use a Chapter Edition that contains two Ordered 7126 Chapters. The first chapter references the "Segment" of "intro.mkv" 7127 with the use of a "ChapterSegmentUID", "ChapterSegmentEditionUID", 7128 "ChapterTimeStart" and optionally a "ChapterTimeEnd" element. The 7129 second chapter references content within the "Segment" of 7130 "program.mkv". A "Matroska Player" SHOULD recognize the "Linked 7131 Segment" created by the use of "ChapterSegmentUID" in an enabled 7132 "Edition" and present the reference content of the two "Segments" 7133 together. 7135 24.3. Soft Linking 7137 Soft Linking is used by codec chapters. They can reference another 7138 "Segment" and jump to that "Segment". The way the "Segments" are 7139 described are internal to the chapter codec and unknown to the 7140 Matroska level. But there are "Elements" within the "Info Element" 7141 (such as "ChapterTranslate") that can translate a value representing 7142 a "Segment" in the chapter codec and to the current "SegmentUID". 7143 All "Segments" that could be used in a "Linked Segment" in this way 7144 SHOULD be marked as members of the same family via the "SegmentFamily 7145 Element", so that the "Matroska Player" can quickly switch from one 7146 to the other. 7148 25. Track Flags 7150 25.1. Default flag 7152 The "default track" flag is a hint for a "Matroska Player" and SHOULD 7153 always be changeable by the user. If the user wants to see or hear a 7154 track of a certain kind (audio, video, subtitles) and hasn't chosen a 7155 specific track, the "Matroska Player" SHOULD use the first track of 7156 that kind whose "default track" flag is set to "1". If no such track 7157 is found then the first track of this kind SHOULD be chosen. 7159 Only one track of a kind MAY have its "default track" flag set in a 7160 segment. If a track entry does not contain the "default track" flag 7161 element then its default value "1" is to be used. 7163 25.2. Forced flag 7165 The "forced" flag tells the "Matroska Player" that it MUST display/ 7166 play this track or another track of the same kind that also has its 7167 "forced" flag set. When there are multiple "forced" tracks, the 7168 "Matroska Player" SHOULD determine the track based upon the language 7169 of the forced flag or use the default flag if no track matches the 7170 use languages. Another track of the same kind without the "forced" 7171 flag may be use simultaneously with the "forced" track (like DVD 7172 subtitles for example). 7174 25.3. Track Operation 7176 "TrackOperation" allows combining multiple tracks to make a virtual 7177 one. It uses two separate system to combine tracks. One to create a 7178 3D "composition" (left/right/background planes) and one to simplify 7179 join two tracks together to make a single track. 7181 A track created with "TrackOperation" is a proper track with a UID 7182 and all its flags. However the codec ID is meaningless because each 7183 "sub" track needs to be decoded by its own decoder before the 7184 "operation" is applied. The "Cues Elements" corresponding to such a 7185 virtual track SHOULD be the sum of the "Cues Elements" for each of 7186 the tracks it's composed of (when the "Cues" are defined per track). 7188 In the case of "TrackJoinBlocks", the "Block Elements" (from 7189 "BlockGroup" and "SimpleBlock") of all the tracks SHOULD be used as 7190 if they were defined for this new virtual "Track". When two "Block 7191 Elements" have overlapping start or end timestamps, it's up to the 7192 underlying system to either drop some of these frames or render them 7193 the way they overlap. This situation SHOULD be avoided when creating 7194 such tracks as you can never be sure of the end result on different 7195 platforms. 7197 25.4. Overlay Track 7199 Overlay tracks SHOULD be rendered in the same 'channel' as the track 7200 its linked to. When content is found in such a track, it SHOULD be 7201 played on the rendering channel instead of the original track. 7203 25.5. Multi-planar and 3D videos 7205 There are two different ways to compress 3D videos: have each 'eye' 7206 track in a separate track and have one track have both 'eyes' 7207 combined inside (which is more efficient, compression-wise). 7208 Matroska supports both ways. 7210 For the single track variant, there is the "StereoMode Element" which 7211 defines how planes are assembled in the track (mono or left-right 7212 combined). Odd values of StereoMode means the left plane comes first 7213 for more convenient reading. The pixel count of the track 7214 ("PixelWidth"/"PixelHeight") is the raw amount of pixels (for example 7215 3840x1080 for full HD side by side) and the 7216 "DisplayWidth"/"DisplayHeight" in pixels is the amount of pixels for 7217 one plane (1920x1080 for that full HD stream). Old stereo 3D were 7218 displayed using anaglyph (cyan and red colours separated). For 7219 compatibility with such movies, there is a value of the StereoMode 7220 that corresponds to AnaGlyph. 7222 There is also a "packed" mode (values 13 and 14) which consists of 7223 packing two frames together in a "Block" using lacing. The first 7224 frame is the left eye and the other frame is the right eye (or vice 7225 versa). The frames SHOULD be decoded in that order and are possibly 7226 dependent on each other (P and B frames). 7228 For separate tracks, Matroska needs to define exactly which track 7229 does what. "TrackOperation" with "TrackCombinePlanes" do that. For 7230 more details look at how TrackOperation works (#track-operation). 7232 The 3D support is still in infancy and may evolve to support more 7233 features. 7235 The StereoMode used to be part of Matroska v2 but it didn't meet the 7236 requirement for multiple tracks. There was also a bug in libmatroska 7237 prior to 0.9.0 that would save/read it as 0x53B9 instead of 0x53B8. 7239 "Matroska Readers" may support these legacy files by checking 7240 Matroska v2 or 0x53B9. The older values 7241 (http://www.matroska.org/node/1/revisions/74/view#StereoMode) were 0: 7242 mono, 1: right eye, 2: left eye, 3: both eyes. 7244 26. Timestamps 7246 Historically timestamps in Matroska were mistakenly called timecodes. 7247 The "Timestamp Element" was called Timecode, the "TimestampScale 7248 Element" was called TimecodeScale, the "TrackTimestampScale Element" 7249 was called TrackTimecodeScale and the "ReferenceTimestamp Element" 7250 was called ReferenceTimeCode. 7252 26.1. Timestamp Types 7254 * Absolute Timestamp = Block+Cluster 7256 * Relative Timestamp = Block 7258 * Scaled Timestamp = Block+Cluster 7260 * Raw Timestamp = (Block+Cluster)*TimestampScale*TrackTimestampScale 7262 26.2. Block Timestamps 7264 The "Block Element"'s timestamp MUST be a signed integer that 7265 represents the "Raw Timestamp" relative to the "Cluster"'s "Timestamp 7266 Element", multiplied by the "TimestampScale Element". See 7267 TimestampScale (#timestampscale) for more information. 7269 The "Block Element"'s timestamp MUST be represented by a 16bit signed 7270 integer (sint16). The "Block"'s timestamp has a range of -32768 to 7271 +32767 units. When using the default value of the "TimestampScale 7272 Element", each integer represents 1ms. The maximum time span of 7273 "Block Elements" in a "Cluster" using the default "TimestampScale 7274 Element" of 1ms is 65536ms. 7276 If a "Cluster"'s "Timestamp Element" is set to zero, it is possible 7277 to have "Block Elements" with a negative "Raw Timestamp". "Block 7278 Elements" with a negative "Raw Timestamp" are not valid. 7280 26.3. Raw Timestamp 7282 The exact time of an object SHOULD be represented in nanoseconds. To 7283 find out a "Block"'s "Raw Timestamp", you need the "Block"'s 7284 "Timestamp Element", the "Cluster"'s "Timestamp Element", and the 7285 "TimestampScale Element". 7287 26.4. TimestampScale 7289 The "TimestampScale Element" is used to calculate the "Raw Timestamp" 7290 of a "Block". The timestamp is obtained by adding the "Block"'s 7291 timestamp to the "Cluster"'s "Timestamp Element", and then 7292 multiplying that result by the "TimestampScale". The result will be 7293 the "Block"'s "Raw Timestamp" in nanoseconds. The formula for this 7294 would look like: 7296 (a + b) * c 7298 a = `Block`'s Timestamp 7299 b = `Cluster`'s Timestamp 7300 c = `TimestampScale` 7302 For example, assume a "Cluster"'s "Timestamp" has a value of 564264, 7303 the "Block" has a "Timestamp" of 1233, and the "TimestampScale 7304 Element" is the default of 1000000. 7306 (1233 + 564264) * 1000000 = 565497000000 7308 So, the "Block" in this example has a specific time of 565497000000 7309 in nanoseconds. In milliseconds this would be 565497ms. 7311 26.5. TimestampScale Rounding 7313 Because the default value of "TimestampScale" is 1000000, which makes 7314 each integer in the "Cluster" and "Block" "Timestamp Elements" equal 7315 1ms, this is the most commonly used. When dealing with audio, this 7316 causes inaccuracy when seeking. When the audio is combined with 7317 video, this is not an issue. For most cases, the the synch of audio 7318 to video does not need to be more than 1ms accurate. This becomes 7319 obvious when one considers that sound will take 2-3ms to travel a 7320 single meter, so distance from your speakers will have a greater 7321 effect on audio/visual synch than this. 7323 However, when dealing with audio-only files, seeking accuracy can 7324 become critical. For instance, when storing a whole CD in a single 7325 track, a user will want to be able to seek to the exact sample that a 7326 song begins at. If seeking a few sample ahead or behind, a 'crack' 7327 or 'pop' may result as a few odd samples are rendered. Also, when 7328 performing precise editing, it may be very useful to have the audio 7329 accuracy down to a single sample. 7331 When storing timestamps for an audio stream, the "TimestampScale 7332 Element" SHOULD have an accuracy of at least that of the audio sample 7333 rate, otherwise there are rounding errors that prevent users from 7334 knowing the precise location of a sample. Here's how a program has 7335 to round each timestamp in order to be able to recreate the sample 7336 number accurately. 7338 Let's assume that the application has an audio track with a sample 7339 rate of 44100. As written above the "TimestampScale" MUST have at 7340 least the accuracy of the sample rate itself: 1000000000 / 44100 = 7341 22675.7369614512. This value MUST always be truncated. Otherwise 7342 the accuracy will not suffice. So in this example the application 7343 will use 22675 for the "TimestampScale". The application could even 7344 use some lower value like 22674 which would allow it to be a little 7345 bit imprecise about the original timestamps. But more about that in 7346 a minute. 7348 Next the application wants to write sample number 52340 and 7349 calculates the timestamp. This is easy. In order to calculate the 7350 "Raw Timestamp" in ns all it has to do is calculate "Raw Timestamp = 7351 round(1000000000 * sample_number / sample_rate)". Rounding at this 7352 stage is very important! The application might skip it if it choses 7353 a slightly smaller value for the "TimestampScale" factor instead of 7354 the truncated one like shown above. Otherwise it has to round or the 7355 results won't be reversible. For our example we get "Raw Timestamp = 7356 round(1000000000 * 52340 / 44100) = round(1186848072.56236) = 7357 1186848073". 7359 The next step is to calculate the "Absolute Timestamp" - that is the 7360 timestamp that will be stored in the Matroska file. Here the 7361 application has to divide the "Raw Timestamp" from the previous 7362 paragraph by the "TimestampScale" factor and round the result: 7363 "Absolute Timestamp = round(Raw Timestamp / TimestampScale_factor)" 7364 which will result in the following for our example: "Absolute 7365 Timestamp = round(1186848073 / 22675) = round(52341.7011245866) = 7366 52342". This number is the one the application has to write to the 7367 file. 7369 Now our file is complete, and we want to play it back with another 7370 application. Its task is to find out which sample the first 7371 application wrote into the file. So it starts reading the Matroska 7372 file and finds the "TimestampScale" factor 22675 and the audio sample 7373 rate 44100. Later it finds a data block with the "Absolute 7374 Timestamp" of 52342. But how does it get the sample number from 7375 these numbers? 7377 First it has to calculate the "Raw Timestamp" of the block it has 7378 just read. Here's no rounding involved, just an integer 7379 multiplication: "Raw Timestamp = Absolute Timestamp * 7380 TimestampScale_factor". In our example: "Raw Timestamp = 52342 * 7381 22675 = 1186854850". 7383 The conversion from the "Raw Timestamp" to the sample number again 7384 requires rounding: "sample_number = round(Raw Timestamp * sample_rate 7385 / 1000000000)". In our example: "sample_number = round(1186854850 * 7386 44100 / 1000000000) = round(52340.298885) = 52340". This is exactly 7387 the sample number that the previous program started with. 7389 Some general notes for a program: 7391 1. Always calculate the timestamps / sample numbers with floating 7392 point numbers of at least 64bit precision (called 'double' in 7393 most modern programming languages). If you're calculating with 7394 integers then make sure they're 64bit long, too. 7396 2. Always round if you divide. Always! If you don't you'll end up 7397 with situations in which you have a timestamp in the Matroska 7398 file that does not correspond to the sample number that it 7399 started with. Using a slightly lower timestamp scale factor can 7400 help here in that it removes the need for proper rounding in the 7401 conversion from sample number to "Raw Timestamp". 7403 26.6. TrackTimestampScale 7405 The "TrackTimestampScale Element" is used align tracks that would 7406 otherwise be played at different speeds. An example of this would be 7407 if you have a film that was originally recorded at 24fps video. When 7408 playing this back through a PAL broadcasting system, it is standard 7409 to speed up the film to 25fps to match the 25fps display speed of the 7410 PAL broadcasting standard. However, when broadcasting the video 7411 through NTSC, it is typical to leave the film at its original speed. 7412 If you wanted to make a single file where there was one video stream, 7413 and an audio stream used from the PAL broadcast, as well as an audio 7414 stream used from the NTSC broadcast, you would have the problem that 7415 the PAL audio stream would be 1/24th faster than the NTSC audio 7416 stream, quickly leading to problems. It is possible to stretch out 7417 the PAL audio track and re-encode it at a slower speed, however when 7418 dealing with lossy audio codecs, this often results in a loss of 7419 audio quality and/or larger file sizes. 7421 This is the type of problem that "TrackTimestampScale" was designed 7422 to fix. Using it, the video can be played back at a speed that will 7423 synch with either the NTSC or the PAL audio stream, depending on 7424 which is being used for playback. To continue the above example: 7426 Track 1: Video 7427 Track 2: NTSC Audio 7428 Track 3: PAL Audio 7429 Because the NTSC track is at the original speed, it will used as the 7430 default value of 1.0 for its "TrackTimestampScale". The video will 7431 also be aligned to the NTSC track with the default value of 1.0. 7433 The "TrackTimestampScale" value to use for the PAL track would be 7434 calculated by determining how much faster the PAL track is than the 7435 NTSC track. In this case, because we know the video for the NTSC 7436 audio is being played back at 24fps and the video for the PAL audio 7437 is being played back at 25fps, the calculation would be: 7439 25/24 is almost 1.04166666666666666667 7441 When writing a file that uses a non-default "TrackTimestampScale", 7442 the values of the "Block"'s timestamp are whatever they would be when 7443 normally storing the track with a default value for the 7444 "TrackTimestampScale". However, the data is interleaved a little 7445 differently. Data SHOULD be interleaved by its Raw Timestamp (#raw- 7446 timestamp) in the order handed back from the encoder. The "Raw 7447 Timestamp" of a "Block" from a track using "TrackTimestampScale" is 7448 calculated using: 7450 "(Block's Timestamp + Cluster's Timestamp) * TimestampScale * 7451 TrackTimestampScale" 7453 So, a Block from the PAL track above that had a Scaled Timestamp 7454 (#timestamp-types) of 100 seconds would have a "Raw Timestamp" of 7455 104.66666667 seconds, and so would be stored in that part of the 7456 file. 7458 When playing back a track using the "TrackTimestampScale", if the 7459 track is being played by itself, there is no need to scale it. From 7460 the above example, when playing the Video with the NTSC Audio, 7461 neither are scaled. However, when playing back the Video with the 7462 PAL Audio, the timestamps from the PAL Audio track are scaled using 7463 the "TrackTimestampScale", resulting in the video playing back in 7464 synch with the audio. 7466 It would be possible for a "Matroska Player" to also adjust the 7467 audio's samplerate at the same time as adjusting the timestamps if 7468 you wanted to play the two audio streams synchronously. It would 7469 also be possible to adjust the video to match the audio's speed. 7470 However, for playback, the selected track(s) timestamps SHOULD be 7471 adjusted if they need to be scaled. 7473 While the above example deals specifically with audio tracks, this 7474 element can be used to align video, audio, subtitles, or any other 7475 type of track contained in a Matroska file. 7477 27. Normative References 7479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 7480 Requirement Levels", BCP 14, RFC 2119, 7481 DOI 10.17487/RFC2119, March 1997, 7482 . 7484 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 7485 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 7486 May 2017, . 7488 Authors' Addresses 7490 Steve Lhomme 7492 Email: slhomme@matroska.org 7494 Moritz Bunkus 7496 Email: moritz@bunkus.org 7498 Dave Rice 7500 Email: dave@dericed.com