idnits 2.17.1 draft-ietf-cellar-matroska-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (19 October 2020) is 1284 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 6611 -- Looks like a reference, but probably isn't: '0' on line 6612 -- Looks like a reference, but probably isn't: '2' on line 6611 == Outdated reference: A later version (-12) exists of draft-ietf-cellar-codec-04 == Outdated reference: A later version (-12) exists of draft-ietf-cellar-tags-04 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 cellar S. Lhomme 3 Internet-Draft 4 Intended status: Informational M. Bunkus 5 Expires: 22 April 2021 6 D. Rice 7 19 October 2020 9 Matroska Media Container Format Specifications 10 draft-ietf-cellar-matroska-06 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 22 April 2021. 35 Copyright Notice 37 Copyright (c) 2020 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 42 license-info) in effect on the date of publication of this document. 43 Please review these documents carefully, as they describe your rights 44 and restrictions with respect to this document. Code Components 45 extracted from this document must include Simplified BSD License text 46 as described in Section 4.e of the Trust Legal Provisions and are 47 provided without warranty as described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 52 2. Status of this document . . . . . . . . . . . . . . . . . . . 5 53 3. Security Considerations . . . . . . . . . . . . . . . . . . . 6 54 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 55 5. Notation and Conventions . . . . . . . . . . . . . . . . . . 6 56 6. Basis in EBML . . . . . . . . . . . . . . . . . . . . . . . . 7 57 6.1. Added Constraints on EBML . . . . . . . . . . . . . . . . 7 58 6.2. Matroska Design . . . . . . . . . . . . . . . . . . . . . 7 59 6.2.1. Language Codes . . . . . . . . . . . . . . . . . . . 7 60 6.2.2. Physical Types . . . . . . . . . . . . . . . . . . . 8 61 6.2.3. Block Structure . . . . . . . . . . . . . . . . . . . 8 62 6.2.4. Lacing . . . . . . . . . . . . . . . . . . . . . . . 10 63 7. Matroska Structure . . . . . . . . . . . . . . . . . . . . . 14 64 8. Matroska Additions to Schema Element Attributes . . . . . . . 22 65 9. Matroska Schema . . . . . . . . . . . . . . . . . . . . . . . 23 66 9.1. EBMLMaxIDLength Element . . . . . . . . . . . . . . . . . 23 67 9.2. EBMLMaxSizeLength Element . . . . . . . . . . . . . . . . 23 68 10. Segment Element . . . . . . . . . . . . . . . . . . . . . . . 24 69 10.1. SeekHead Element . . . . . . . . . . . . . . . . . . . . 24 70 10.1.1. Seek Element . . . . . . . . . . . . . . . . . . . . 24 71 10.2. Info Element . . . . . . . . . . . . . . . . . . . . . . 25 72 10.2.1. SegmentUID Element . . . . . . . . . . . . . . . . . 26 73 10.2.2. SegmentFilename Element . . . . . . . . . . . . . . 26 74 10.2.3. PrevUID Element . . . . . . . . . . . . . . . . . . 26 75 10.2.4. PrevFilename Element . . . . . . . . . . . . . . . . 27 76 10.2.5. NextUID Element . . . . . . . . . . . . . . . . . . 27 77 10.2.6. NextFilename Element . . . . . . . . . . . . . . . . 28 78 10.2.7. SegmentFamily Element . . . . . . . . . . . . . . . 28 79 10.2.8. ChapterTranslate Element . . . . . . . . . . . . . . 28 80 10.2.9. TimestampScale Element . . . . . . . . . . . . . . . 30 81 10.2.10. Duration Element . . . . . . . . . . . . . . . . . . 30 82 10.2.11. DateUTC Element . . . . . . . . . . . . . . . . . . 31 83 10.2.12. Title Element . . . . . . . . . . . . . . . . . . . 31 84 10.2.13. MuxingApp Element . . . . . . . . . . . . . . . . . 31 85 10.2.14. WritingApp Element . . . . . . . . . . . . . . . . . 32 86 10.3. Cluster Element . . . . . . . . . . . . . . . . . . . . 32 87 10.3.1. Timestamp Element . . . . . . . . . . . . . . . . . 32 88 10.3.2. SilentTracks Element . . . . . . . . . . . . . . . . 33 89 10.3.3. Position Element . . . . . . . . . . . . . . . . . . 33 90 10.3.4. PrevSize Element . . . . . . . . . . . . . . . . . . 34 91 10.3.5. SimpleBlock Element . . . . . . . . . . . . . . . . 34 92 10.3.6. BlockGroup Element . . . . . . . . . . . . . . . . . 34 93 10.3.7. EncryptedBlock Element . . . . . . . . . . . . . . . 44 94 10.4. Tracks Element . . . . . . . . . . . . . . . . . . . . . 44 95 10.4.1. TrackEntry Element . . . . . . . . . . . . . . . . . 45 96 10.5. Cues Element . . . . . . . . . . . . . . . . . . . . . . 106 97 10.5.1. CuePoint Element . . . . . . . . . . . . . . . . . . 107 98 10.6. Attachments Element . . . . . . . . . . . . . . . . . . 112 99 10.6.1. AttachedFile Element . . . . . . . . . . . . . . . . 112 100 10.7. Chapters Element . . . . . . . . . . . . . . . . . . . . 116 101 10.7.1. EditionEntry Element . . . . . . . . . . . . . . . . 116 102 10.8. Tags Element . . . . . . . . . . . . . . . . . . . . . . 127 103 10.8.1. Tag Element . . . . . . . . . . . . . . . . . . . . 127 104 11. Matroska Element Ordering . . . . . . . . . . . . . . . . . . 135 105 11.1. Top-Level Elements . . . . . . . . . . . . . . . . . . . 135 106 11.2. CRC-32 . . . . . . . . . . . . . . . . . . . . . . . . . 135 107 11.3. SeekHead . . . . . . . . . . . . . . . . . . . . . . . . 135 108 11.4. Cues (index) . . . . . . . . . . . . . . . . . . . . . . 136 109 11.5. Info . . . . . . . . . . . . . . . . . . . . . . . . . . 136 110 11.6. Chapters Element . . . . . . . . . . . . . . . . . . . . 136 111 11.7. Attachments . . . . . . . . . . . . . . . . . . . . . . 136 112 11.8. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 137 113 11.9. Optimum layout from a muxer . . . . . . . . . . . . . . 137 114 11.10. Optimum layout after editing tags . . . . . . . . . . . 137 115 11.11. Optimum layout with Cues at the front . . . . . . . . . 138 116 11.12. Cluster Timestamp . . . . . . . . . . . . . . . . . . . 138 117 12. Chapters . . . . . . . . . . . . . . . . . . . . . . . . . . 138 118 12.1. Edition and Chapter Flags . . . . . . . . . . . . . . . 138 119 12.1.1. Chapter Flags . . . . . . . . . . . . . . . . . . . 138 120 12.1.2. Edition Flags . . . . . . . . . . . . . . . . . . . 139 121 12.1.3. ChapterSegmentUID . . . . . . . . . . . . . . . . . 141 122 12.2. Menu features . . . . . . . . . . . . . . . . . . . . . 142 123 12.2.1. Matroska Script (0) . . . . . . . . . . . . . . . . 142 124 12.2.2. DVD menu (1) . . . . . . . . . . . . . . . . . . . . 143 125 12.3. Example 1 : basic chaptering . . . . . . . . . . . . . . 145 126 12.4. Example 2 : nested chapters . . . . . . . . . . . . . . 147 127 12.4.1. The Micronauts "Bleep To Bleep" . . . . . . . . . . 147 128 13. Attachments . . . . . . . . . . . . . . . . . . . . . . . . . 150 129 13.1. Cover Art . . . . . . . . . . . . . . . . . . . . . . . 150 130 14. Cues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 131 14.1. Recommendations . . . . . . . . . . . . . . . . . . . . 152 132 15. Matroska Streaming . . . . . . . . . . . . . . . . . . . . . 152 133 15.1. File Access . . . . . . . . . . . . . . . . . . . . . . 153 134 15.2. Livestreaming . . . . . . . . . . . . . . . . . . . . . 153 135 16. Menu Specifications . . . . . . . . . . . . . . . . . . . . . 154 136 16.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 154 137 16.1.1. Highlights/Hotspots . . . . . . . . . . . . . . . . 154 138 16.1.2. Playback features . . . . . . . . . . . . . . . . . 155 139 16.1.3. Player requirements . . . . . . . . . . . . . . . . 156 140 16.2. Working Graph . . . . . . . . . . . . . . . . . . . . . 156 141 17. Unknown elements . . . . . . . . . . . . . . . . . . . . . . 156 142 18. Default Values . . . . . . . . . . . . . . . . . . . . . . . 156 143 19. DefaultDecodedFieldDuration . . . . . . . . . . . . . . . . . 156 144 20. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 157 145 21. Image Presentation . . . . . . . . . . . . . . . . . . . . . 157 146 21.1. Cropping . . . . . . . . . . . . . . . . . . . . . . . . 158 147 21.2. Rotation . . . . . . . . . . . . . . . . . . . . . . . . 158 148 22. Matroska versioning . . . . . . . . . . . . . . . . . . . . . 158 149 23. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . 159 150 24. Segment Position . . . . . . . . . . . . . . . . . . . . . . 159 151 24.1. Segment Position Exception . . . . . . . . . . . . . . . 159 152 24.2. Example of Segment Position . . . . . . . . . . . . . . 160 153 25. Linked Segments . . . . . . . . . . . . . . . . . . . . . . . 160 154 25.1. Hard Linking . . . . . . . . . . . . . . . . . . . . . . 160 155 25.2. Medium Linking . . . . . . . . . . . . . . . . . . . . . 162 156 25.3. Soft Linking . . . . . . . . . . . . . . . . . . . . . . 163 157 26. Track Flags . . . . . . . . . . . . . . . . . . . . . . . . . 163 158 26.1. Default flag . . . . . . . . . . . . . . . . . . . . . . 163 159 26.2. Forced flag . . . . . . . . . . . . . . . . . . . . . . 163 160 26.3. Track Operation . . . . . . . . . . . . . . . . . . . . 164 161 26.4. Overlay Track . . . . . . . . . . . . . . . . . . . . . 164 162 26.5. Multi-planar and 3D videos . . . . . . . . . . . . . . . 164 163 27. Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . 165 164 27.1. Timestamp Types . . . . . . . . . . . . . . . . . . . . 165 165 27.2. Block Timestamps . . . . . . . . . . . . . . . . . . . . 166 166 27.3. Raw Timestamp . . . . . . . . . . . . . . . . . . . . . 166 167 27.4. TimestampScale . . . . . . . . . . . . . . . . . . . . . 166 168 27.5. TimestampScale Rounding . . . . . . . . . . . . . . . . 167 169 27.6. TrackTimestampScale . . . . . . . . . . . . . . . . . . 169 170 28. Normative References . . . . . . . . . . . . . . . . . . . . 170 171 29. Informative References . . . . . . . . . . . . . . . . . . . 171 172 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 171 174 1. Introduction 176 Matroska aims to become THE standard of multimedia container formats. 177 It was derived from a project called [MCF], but differentiates from 178 it significantly because it is based on EBML (Extensible Binary Meta 179 Language) [RFC8794], a binary derivative of XML. EBML enables 180 significant advantages in terms of future format extensibility, 181 without breaking file support in old parsers. 183 First, it is essential to clarify exactly "What an Audio/Video 184 container is", to avoid any misunderstandings: 186 * It is NOT a video or audio compression format (codec) 188 * It is an envelope for which there can be many audio, video, and 189 subtitles streams, allowing the user to store a complete movie or 190 CD in a single file. 192 Matroska is designed with the future in mind. It incorporates 193 features like: 195 * Fast seeking in the file 197 * Chapter entries 199 * Full metadata (tags) support 201 * Selectable subtitle/audio/video streams 203 * Modularly expandable 205 * Error resilience (can recover playback even when the stream is 206 damaged) 208 * Streamable over the internet and local networks (HTTP, CIFS, FTP, 209 etc) 211 * Menus (like DVDs have) 213 Matroska is an open standards project. This means for personal use 214 it is absolutely free to use and that the technical specifications 215 describing the bitstream are open to everybody, even to companies 216 that would like to support it in their products. 218 2. Status of this document 220 This document is a work-in-progress specification defining the 221 Matroska file format as part of the IETF Cellar working group 222 (https://datatracker.ietf.org/wg/cellar/charter/). But since it's 223 quite complete it is used as a reference for the development of 224 libmatroska. A legacy version of the specification can be found here 225 (https://www.matroska.org/files/ 226 matroska_file_format_alexander_noe.pdf) (PDF doc by Alexander 227 Noé -- outdated). 229 For a simplified diagram of the layout of a Matroska file, see the 230 Diagram page (diagram.md). 232 The table found below is now generated from the "source" of the 233 Matroska specification. This XML file (https://github.com/Matroska- 234 Org/foundation-source/blob/master/spectool/specdata.xml) is also used 235 to generate the semantic data used in libmatroska and libmatroska2. 236 We encourage anyone to use and monitor its changes so your code is 237 spec-proof and always up to date. 239 Note that versions 1, 2, and 3 have been finalized. Version 4 is 240 currently work in progress. There MAY be further additions to v4. 242 3. Security Considerations 244 Matroska inherits security considerations from EBML. 246 Attacks on a "Matroska Reader" could include: 248 * Storage of a arbitrary and potentially executable data within an 249 "Attachment Element". "Matroska Readers" that extract or use data 250 from Matroska Attachments SHOULD check that the data adheres to 251 expectations. 253 * A "Matroska Attachment" with an inaccurate mime-type. 255 4. IANA Considerations 257 To be determined. 259 5. Notation and Conventions 261 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 262 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 263 "OPTIONAL" in this document are to be interpreted as described in BCP 264 14 [RFC2119] [RFC8174] when, and only when, they appear in all 265 capitals, as shown here. 267 This document defines specific terms in order to define the format 268 and application of "Matroska". Specific terms are defined below: 270 "Matroska": A multimedia container format based on EBML (Extensible 271 Binary Meta Language). 273 "Matroska Reader": A data parser that interprets the semantics of a 274 Matroska document and creates a way for programs to use 275 "Matroska". 277 "Matroska Player": A "Matroska Reader" with a primary purpose of 278 playing audiovisual files, including "Matroska" documents. 280 6. Basis in EBML 282 Matroska is a Document Type of EBML (Extensible Binary Meta 283 Language). This specification is dependent on the EBML Specification 284 [RFC8794]. For an understanding of Matroska's EBML Schema, see in 285 particular the sections of the EBML Specification covering EBML 286 Element Types (Section 7), EBML Schema (Section 11.1), and EBML 287 Structure (Section 3). 289 6.1. Added Constraints on EBML 291 As an EBML Document Type, Matroska adds the following constraints to 292 the EBML specification. 294 * The "docType" of the "EBML Header" MUST be "matroska". 296 * The "EBMLMaxIDLength" of the "EBML Header" MUST be "4". 298 * The "EBMLMaxSizeLength" of the "EBML Header" MUST be between "1" 299 and "8" inclusive. 301 6.2. Matroska Design 303 All top-levels elements (Segment and direct sub-elements) are coded 304 on 4 octets -- i.e. class D elements. 306 6.2.1. Language Codes 308 Matroska from version 1 through 3 uses language codes that can be 309 either the 3 letters bibliographic ISO-639-2 310 (https://www.loc.gov/standards/iso639-2/php/English_list.php) form 311 (like "fre" for french), or such a language code followed by a dash 312 and a country code for specialities in languages (like "fre-ca" for 313 Canadian French). The "ISO 639-2 Language Elements" are "Language 314 Element", "TagLanguage Element", and "ChapLanguage Element". 316 Starting in Matroska version 4, either "ISO 639-2" or BCP 47 317 (https://tools.ietf.org/html/bcp47) MAY be used, although "BCP 47" is 318 RECOMMENDED. The "BCP 47 Language Elements" are "LanguageIETF 319 Element", "TagLanguageIETF Element", and "ChapLanguageIETF Element". 320 If a "BCP 47 Language Element" and an "ISO 639-2 Language Element" 321 are used within the same "Parent Element", then the "ISO 639-2 322 Language Element" MUST be ignored and precedence given to the "BCP 47 323 Language Element". 325 Country codes are the same as used for internet domains 326 (https://www.iana.org/domains/root/db). 328 6.2.2. Physical Types 330 Each level can have different meanings for audio and video. The 331 ORIGINAL_MEDIUM tag can be used to specify a string for 332 ChapterPhysicalEquiv = 60. Here is the list of possible levels for 333 both audio and video: 335 +======================+============+===========+=================+ 336 | ChapterPhysicalEquiv | Audio | Video | Comment | 337 +======================+============+===========+=================+ 338 | 70 | SET / | SET / | the collection | 339 | | PACKAGE | PACKAGE | of different | 340 | | | | media | 341 +----------------------+------------+-----------+-----------------+ 342 | 60 | CD / 12" / | DVD / VHS | the physical | 343 | | 10" / 7" / | / | medium like a | 344 | | TAPE / | LASERDISC | CD or a DVD | 345 | | MINIDISC / | | | 346 | | DAT | | | 347 +----------------------+------------+-----------+-----------------+ 348 | 50 | SIDE | SIDE | when the | 349 | | | | original medium | 350 | | | | (LP/DVD) has | 351 | | | | different sides | 352 +----------------------+------------+-----------+-----------------+ 353 | 40 | - | LAYER | another | 354 | | | | physical level | 355 | | | | on DVDs | 356 +----------------------+------------+-----------+-----------------+ 357 | 30 | SESSION | SESSION | as found on CDs | 358 | | | | and DVDs | 359 +----------------------+------------+-----------+-----------------+ 360 | 20 | TRACK | - | as found on | 361 | | | | audio CDs | 362 +----------------------+------------+-----------+-----------------+ 363 | 10 | INDEX | - | the first | 364 | | | | logical level | 365 | | | | of the side/ | 366 | | | | medium | 367 +----------------------+------------+-----------+-----------------+ 369 Table 1 371 6.2.3. Block Structure 373 Bit 0 is the most significant bit. 375 Frames using references SHOULD be stored in "coding order". That 376 means the references first, and then the frames referencing them. A 377 consequence is that timestamps might not be consecutive. But a frame 378 with a past timestamp MUST reference a frame already known, otherwise 379 it's considered bad/void. 381 6.2.3.1. Block Header 383 +========+========+=============================================+ 384 | Offset | Player | Description | 385 +========+========+=============================================+ 386 | 0x00+ | MUST | Track Number (Track Entry). It is coded in | 387 | | | EBML like form (1 octet if the value is < | 388 | | | 0x80, 2 if < 0x4000, etc) (most significant | 389 | | | bits set to increase the range). | 390 +--------+--------+---------------------------------------------+ 391 | 0x01+ | MUST | Timestamp (relative to Cluster timestamp, | 392 | | | signed int16) | 393 +--------+--------+---------------------------------------------+ 395 Table 2 397 6.2.3.2. Block Header Flags 399 +========+=====+========+====================================+ 400 | Offset | Bit | Player | Description | 401 +========+=====+========+====================================+ 402 | 0x03+ | 0-3 | - | Reserved, set to 0 | 403 +--------+-----+--------+------------------------------------+ 404 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode | 405 | | | | this frame but not display it | 406 +--------+-----+--------+------------------------------------+ 407 | 0x03+ | 5-6 | MUST | Lacing | 408 +--------+-----+--------+------------------------------------+ 409 | | | | * 00 : no lacing | 410 +--------+-----+--------+------------------------------------+ 411 | | | | * 01 : Xiph lacing | 412 +--------+-----+--------+------------------------------------+ 413 | | | | * 11 : EBML lacing | 414 +--------+-----+--------+------------------------------------+ 415 | | | | * 10 : fixed-size lacing | 416 +--------+-----+--------+------------------------------------+ 417 | 0x03+ | 7 | - | not used | 418 +--------+-----+--------+------------------------------------+ 420 Table 3 422 6.2.4. Lacing 424 Lacing is a mechanism to save space when storing data. It is 425 typically used for small blocks of data (referred to as frames in 426 Matroska). There are 3 types of lacing: 428 1. Xiph, inspired by what is found in the Ogg container 430 2. EBML, which is the same with sizes coded differently 432 3. fixed-size, where the size is not coded 434 For example, a user wants to store 3 frames of the same track. The 435 first frame is 800 octets long, the second is 500 octets long and the 436 third is 1000 octets long. As these data are small, they can be 437 stored in a lace to save space. They will then be stored in the same 438 block as follows: 440 6.2.4.1. Xiph lacing 442 * Block head (with lacing bits set to 01) 444 * Lacing head: Number of frames in the lace -1 -- i.e. 2 (the 800 445 and 500 octets one) 447 * Lacing sizes: only the 2 first ones will be coded, 800 gives 448 255;255;255;35, 500 gives 255;245. The size of the last frame is 449 deduced from the total size of the Block. 451 * Data in frame 1 453 * Data in frame 2 455 * Data in frame 3 457 A frame with a size multiple of 255 is coded with a 0 at the end of 458 the size -- for example, 765 is coded 255;255;255;0. 460 6.2.4.2. EBML lacing 462 In this case, the size is not coded as blocks of 255 bytes, but as a 463 difference with the previous size and this size is coded as in EBML. 464 The first size in the lace is unsigned as in EBML. The others use a 465 range shifting to get a sign on each value: 467 +==========================+=============================+ 468 | Bit Representation | Value | 469 +==========================+=============================+ 470 | 1xxx xxxx | value -(2^(6)-1) to 2^(6)-1 | 471 | | (ie 0 to 2^(7)-2 minus | 472 | | 2^(6)-1, half of the range) | 473 +--------------------------+-----------------------------+ 474 | 01xx xxxx xxxx xxxx | value -(2^(13)-1) to | 475 | | 2^(13)-1 | 476 +--------------------------+-----------------------------+ 477 | 001x xxxx xxxx xxxx xxxx | value -(2^(20)-1) to | 478 | xxxx | 2^(20)-1 | 479 +--------------------------+-----------------------------+ 480 | 0001 xxxx xxxx xxxx xxxx | value -(2^(27)-1) to | 481 | xxxx xxxx xxxx | 2^(27)-1 | 482 +--------------------------+-----------------------------+ 483 | 0000 1xxx xxxx xxxx xxxx | value -(2^(34)-1) to | 484 | xxxx xxxx xxxx xxxx xxxx | 2^(34)-1 | 485 +--------------------------+-----------------------------+ 486 | 0000 01xx xxxx xxxx xxxx | value -(2^(41)-1) to | 487 | xxxx xxxx xxxx xxxx xxxx | 2^(41)-1 | 488 | xxxx xxxx | | 489 +--------------------------+-----------------------------+ 490 | 0000 001x xxxx xxxx xxxx | value -(2^(48)-1) to | 491 | xxxx xxxx xxxx xxxx xxxx | 2^(48)-1 | 492 | xxxx xxxx xxxx xxxx | | 493 +--------------------------+-----------------------------+ 495 Table 4 497 * Block head (with lacing bits set to 11) 499 * Lacing head: Number of frames in the lace -1 -- i.e. 2 (the 800 500 and 500 octets one) 502 * Lacing sizes: only the 2 first ones will be coded, 800 gives 0x320 503 0x4000 = 0x4320, 500 is coded as -300 : - 0x12C + 0x1FFF + 0x4000 504 = 0x5ED3. The size of the last frame is deduced from the total 505 size of the Block. 507 * Data in frame 1 509 * Data in frame 2 511 * Data in frame 3 513 6.2.4.3. Fixed-size lacing 515 In this case, only the number of frames in the lace is saved, the 516 size of each frame is deduced from the total size of the Block. For 517 example, for 3 frames of 800 octets each: 519 * Block head (with lacing bits set to 10) 521 * Lacing head: Number of frames in the lace -1 -- i.e. 2 523 * Data in frame 1 525 * Data in frame 2 527 * Data in frame 3 529 6.2.4.4. SimpleBlock Structure 531 The "SimpleBlock" is inspired by the Block structure; see 532 Section 6.2.3. The main differences are the added Keyframe flag and 533 Discardable flag. Otherwise everything is the same. 535 Bit 0 is the most significant bit. 537 Frames using references SHOULD be stored in "coding order". That 538 means the references first, and then the frames referencing them. A 539 consequence is that timestamps might not be consecutive. But a frame 540 with a past timestamp MUST reference a frame already known, otherwise 541 it's considered bad/void. 543 6.2.4.4.1. SimpleBlock Header 545 +========+========+=============================================+ 546 | Offset | Player | Description | 547 +========+========+=============================================+ 548 | 0x00+ | MUST | Track Number (Track Entry). It is coded in | 549 | | | EBML like form (1 octet if the value is < | 550 | | | 0x80, 2 if < 0x4000, etc) (most significant | 551 | | | bits set to increase the range). | 552 +--------+--------+---------------------------------------------+ 553 | 0x01+ | MUST | Timestamp (relative to Cluster timestamp, | 554 | | | signed int16) | 555 +--------+--------+---------------------------------------------+ 557 Table 5 559 6.2.4.4.2. SimpleBlock Header Flags 561 +========+=====+========+==========================================+ 562 | Offset | Bit | Player | Description | 563 +========+=====+========+==========================================+ 564 | 0x03+ | 0 | - | Keyframe, set when the Block contains | 565 | | | | only keyframes | 566 +--------+-----+--------+------------------------------------------+ 567 | 0x03+ | 1-3 | - | Reserved, set to 0 | 568 +--------+-----+--------+------------------------------------------+ 569 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode this | 570 | | | | frame but not display it | 571 +--------+-----+--------+------------------------------------------+ 572 | 0x03+ | 5-6 | MUST | Lacing | 573 +--------+-----+--------+------------------------------------------+ 574 | | | | * 00 : no lacing | 575 +--------+-----+--------+------------------------------------------+ 576 | | | | * 01 : Xiph lacing | 577 +--------+-----+--------+------------------------------------------+ 578 | | | | * 11 : EBML lacing | 579 +--------+-----+--------+------------------------------------------+ 580 | | | | * 10 : fixed-size lacing | 581 +--------+-----+--------+------------------------------------------+ 582 | 0x03+ | 7 | - | Discardable, the frames of the Block can | 583 | | | | be discarded during playing if needed | 584 +--------+-----+--------+------------------------------------------+ 586 Table 6 588 6.2.4.5. Laced Data 590 When lacing bit is set. 592 +========+========+=============================================+ 593 | Offset | Player | Description | 594 +========+========+=============================================+ 595 | 0x00 | MUST | Number of frames in the lace-1 (uint8) | 596 +--------+--------+---------------------------------------------+ 597 | 0x01 / | MUST* | Lace-coded size of each frame of the lace, | 598 | 0xXX | | except for the last one (multiple uint8). | 599 | | | *This is not used with Fixed-size lacing as | 600 | | | it is calculated automatically from (total | 601 | | | size of lace) / (number of frames in lace). | 602 +--------+--------+---------------------------------------------+ 604 Table 7 606 For (possibly) Laced Data 607 +========+========+==========================+ 608 | Offset | Player | Description | 609 +========+========+==========================+ 610 | 0x00 | MUST | Consecutive laced frames | 611 +--------+--------+--------------------------+ 613 Table 8 615 7. Matroska Structure 617 A Matroska file MUST be composed of at least one "EBML Document" 618 using the "Matroska Document Type". Each "EBML Document" MUST start 619 with an "EBML Header" and MUST be followed by the "EBML Root 620 Element", defined as "Segment" in Matroska. Matroska defines several 621 "Top Level Elements" which MAY occur within the "Segment". 623 As an example, a simple Matroska file consisting of a single "EBML 624 Document" could be represented like this: 626 * "EBML Header" 628 * "Segment" 630 A more complex Matroska file consisting of an "EBML Stream" 631 (consisting of two "EBML Documents") could be represented like this: 633 * "EBML Header" 635 * "Segment" 637 * "EBML Header" 639 * "Segment" 641 The following diagram represents a simple Matroska file, comprised of 642 an "EBML Document" with an "EBML Header", a "Segment Element" (the 643 "Root Element"), and all eight Matroska "Top Level Elements". In the 644 following diagrams of this section, horizontal spacing expresses a 645 parent-child relationship between Matroska Elements (e.g., the "Info 646 Element" is contained within the "Segment Element") whereas vertical 647 alignment represents the storage order within the file. 649 +-------------+ 650 | EBML Header | 651 +---------------------------+ 652 | Segment | SeekHead | 653 | |-------------| 654 | | Info | 655 | |-------------| 656 | | Tracks | 657 | |-------------| 658 | | Chapters | 659 | |-------------| 660 | | Cluster | 661 | |-------------| 662 | | Cues | 663 | |-------------| 664 | | Attachments | 665 | |-------------| 666 | | Tags | 667 +---------------------------+ 669 The Matroska "EBML Schema" defines eight "Top Level Elements": 670 "SeekHead", "Info", "Tracks", "Chapters", "Cluster", "Cues", 671 "Attachments", and "Tags". 673 The "SeekHead Element" (also known as "MetaSeek") contains an index 674 of "Top Level Elements" locations within the "Segment". Use of the 675 "SeekHead Element" is RECOMMENDED. Without a "SeekHead Element", a 676 Matroska parser would have to search the entire file to find all of 677 the other "Top Level Elements". This is due to Matroska's flexible 678 ordering requirements; for instance, it is acceptable for the 679 "Chapters Element" to be stored after the "Cluster Elements". 681 +--------------------------------+ 682 | SeekHead | Seek | SeekID | 683 | | |--------------| 684 | | | SeekPosition | 685 +--------------------------------+ 687 Figure 1: Representation of a "SeekHead Element". 689 The "Info Element" contains vital information for identifying the 690 whole "Segment". This includes the title for the "Segment", a 691 randomly generated unique identifier, and the unique identifier(s) of 692 any linked "Segment Elements". 694 +-------------------------+ 695 | Info | SegmentUID | 696 | |------------------| 697 | | SegmentFilename | 698 | |------------------| 699 | | PrevUID | 700 | |------------------| 701 | | PrevFilename | 702 | |------------------| 703 | | NextUID | 704 | |------------------| 705 | | NextFilename | 706 | |------------------| 707 | | SegmentFamily | 708 | |------------------| 709 | | ChapterTranslate | 710 | |------------------| 711 | | TimestampScale | 712 | |------------------| 713 | | Duration | 714 | |------------------| 715 | | DateUTC | 716 | |------------------| 717 | | Title | 718 | |------------------| 719 | | MuxingApp | 720 | |------------------| 721 | | WritingApp | 722 |-------------------------| 724 Figure 2: Representation of an "Info Element" and its "Child 725 Elements". 727 The "Tracks Element" defines the technical details for each track and 728 can store the name, number, unique identifier, language, and type 729 (audio, video, subtitles, etc.) of each track. For example, the 730 "Tracks Element" MAY store information about the resolution of a 731 video track or sample rate of an audio track. 733 The "Tracks Element" MUST identify all the data needed by the codec 734 to decode the data of the specified track. However, the data 735 required is contingent on the codec used for the track. For example, 736 a "Track Element" for uncompressed audio only requires the audio bit 737 rate to be present. A codec such as AC-3 would require that the 738 "CodecID Element" be present for all tracks, as it is the primary way 739 to identify which codec to use to decode the track. 741 +------------------------------------+ 742 | Tracks | TrackEntry | TrackNumber | 743 | | |--------------| 744 | | | TrackUID | 745 | | |--------------| 746 | | | TrackType | 747 | | |--------------| 748 | | | Name | 749 | | |--------------| 750 | | | Language | 751 | | |--------------| 752 | | | CodecID | 753 | | |--------------| 754 | | | CodecPrivate | 755 | | |--------------| 756 | | | CodecName | 757 | | |----------------------------------+ 758 | | | Video | FlagInterlaced | 759 | | | |-------------------| 760 | | | | FieldOrder | 761 | | | |-------------------| 762 | | | | StereoMode | 763 | | | |-------------------| 764 | | | | AlphaMode | 765 | | | |-------------------| 766 | | | | PixelWidth | 767 | | | |-------------------| 768 | | | | PixelHeight | 769 | | | |-------------------| 770 | | | | DisplayWidth | 771 | | | |-------------------| 772 | | | | DisplayHeight | 773 | | | |-------------------| 774 | | | | AspectRatioType | 775 | | | |-------------------| 776 | | | | Color | 777 | | |----------------------------------| 778 | | | Audio | SamplingFrequency | 779 | | | |-------------------| 780 | | | | Channels | 781 | | | |-------------------| 782 | | | | BitDepth | 783 |--------------------------------------------------------| 785 Figure 3: Representation of the "Tracks Element" and a selection 786 of its "Descendant Elements". 788 The "Chapters Element" lists all of the chapters. Chapters are a way 789 to set predefined points to jump to in video or audio. 791 +-----------------------------------------+ 792 | Chapters | Edition | EditionUID | 793 | | Entry |--------------------| 794 | | | EditionFlagHidden | 795 | | |--------------------| 796 | | | EditionFlagDefault | 797 | | |--------------------| 798 | | | EditionFlagOrdered | 799 | | |---------------------------------+ 800 | | | ChapterAtom | ChapterUID | 801 | | | |-------------------| 802 | | | | ChapterStringUID | 803 | | | |-------------------| 804 | | | | ChapterTimeStart | 805 | | | |-------------------| 806 | | | | ChapterTimeEnd | 807 | | | |-------------------| 808 | | | | ChapterFlagHidden | 809 | | | |-------------------------------+ 810 | | | | ChapterDisplay | ChapString | 811 | | | | |--------------| 812 | | | | | ChapLanguage | 813 +------------------------------------------------------------------+ 815 Figure 4: Representation of the "Chapters Element" and a 816 selection of its "Descendant Elements". 818 "Cluster Elements" contain the content for each track, e.g., video 819 frames. A Matroska file SHOULD contain at least one "Cluster 820 Element". The "Cluster Element" helps to break up "SimpleBlock" or 821 "BlockGroup Elements" and helps with seeking and error protection. 822 It is RECOMMENDED that the size of each individual "Cluster Element" 823 be limited to store no more than 5 seconds or 5 megabytes. Every 824 "Cluster Element" MUST contain a "Timestamp Element". This SHOULD be 825 the "Timestamp Element" used to play the first "Block" in the 826 "Cluster Element". There SHOULD be one or more "BlockGroup" or 827 "SimpleBlock Element" in each "Cluster Element". A "BlockGroup 828 Element" MAY contain a "Block" of data and any information relating 829 directly to that "Block". 831 +--------------------------+ 832 | Cluster | Timestamp | 833 | |----------------| 834 | | SilentTracks | 835 | |----------------| 836 | | Position | 837 | |----------------| 838 | | PrevSize | 839 | |----------------| 840 | | SimpleBlock | 841 | |----------------| 842 | | BlockGroup | 843 | |----------------| 844 | | EncryptedBlock | 845 +--------------------------+ 847 Figure 5: Representation of a "Cluster Element" and its immediate 848 "Child Elements". 850 +----------------------------------+ 851 | Block | Portion of | Data Type | 852 | | a Block | - Bit Flag | 853 | |--------------------------+ 854 | | Header | TrackNumber | 855 | | |-------------| 856 | | | Timestamp | 857 | | |-------------| 858 | | | Flags | 859 | | | - Gap | 860 | | | - Lacing | 861 | | | - Reserved | 862 | |--------------------------| 863 | | Optional | FrameSize | 864 | |--------------------------| 865 | | Data | Frame | 866 +----------------------------------+ 868 Figure 6: Representation of the "Block Element" structure. 870 Each "Cluster" MUST contain exactly one "Timestamp Element". The 871 "Timestamp Element" value MUST be stored once per "Cluster". The 872 "Timestamp Element" in the "Cluster" is relative to the entire 873 "Segment". The "Timestamp Element" SHOULD be the first "Element" in 874 the "Cluster". 876 Additionally, the "Block" contains an offset that, when added to the 877 "Cluster"'s "Timestamp Element" value, yields the "Block"'s effective 878 timestamp. Therefore, timestamp in the "Block" itself is relative to 879 the "Timestamp Element" in the "Cluster". For example, if the 880 "Timestamp Element" in the "Cluster" is set to 10 seconds and a 881 "Block" in that "Cluster" is supposed to be played 12 seconds into 882 the clip, the timestamp in the "Block" would be set to 2 seconds. 884 The "ReferenceBlock" in the "BlockGroup" is used instead of the basic 885 "P-frame"/"B-frame" description. Instead of simply saying that this 886 "Block" depends on the "Block" directly before, or directly 887 afterwards, the "Timestamp" of the necessary "Block" is used. 888 Because there can be as many "ReferenceBlock Elements" as necessary 889 for a "Block", it allows for some extremely complex referencing. 891 The "Cues Element" is used to seek when playing back a file by 892 providing a temporal index for some of the "Tracks". It is similar 893 to the "SeekHead Element", but used for seeking to a specific time 894 when playing back the file. It is possible to seek without this 895 element, but it is much more difficult because a "Matroska Reader" 896 would have to 'hunt and peck' through the file looking for the 897 correct timestamp. 899 The "Cues Element" SHOULD contain at least one "CuePoint Element". 900 Each "CuePoint Element" stores the position of the "Cluster" that 901 contains the "BlockGroup" or "SimpleBlock Element". The timestamp is 902 stored in the "CueTime Element" and location is stored in the 903 "CueTrackPositions Element". 905 The "Cues Element" is flexible. For instance, "Cues Element" can be 906 used to index every single timestamp of every "Block" or they can be 907 indexed selectively. For video files, it is RECOMMENDED to index at 908 least the keyframes of the video track. 910 +-------------------------------------+ 911 | Cues | CuePoint | CueTime | 912 | | |-------------------| 913 | | | CueTrackPositions | 914 | |------------------------------| 915 | | CuePoint | CueTime | 916 | | |-------------------| 917 | | | CueTrackPositions | 918 +-------------------------------------+ 920 Figure 7: Representation of a "Cues Element" and two levels of 921 its "Descendant Elements". 923 The "Attachments Element" is for attaching files to a Matroska file 924 such as pictures, webpages, programs, or even the codec needed to 925 play back the file. 927 +------------------------------------------------+ 928 | Attachments | AttachedFile | FileDescription | 929 | | |-------------------| 930 | | | FileName | 931 | | |-------------------| 932 | | | FileMimeType | 933 | | |-------------------| 934 | | | FileData | 935 | | |-------------------| 936 | | | FileUID | 937 | | |-------------------| 938 | | | FileName | 939 | | |-------------------| 940 | | | FileReferral | 941 | | |-------------------| 942 | | | FileUsedStartTime | 943 | | |-------------------| 944 | | | FileUsedEndTime | 945 +------------------------------------------------+ 947 Figure 8: Representation of a "Attachments Element". 949 The "Tags Element" contains metadata that describes the "Segment" and 950 potentially its "Tracks", "Chapters", and "Attachments". Each 951 "Track" or "Chapter" that those tags applies to has its UID listed in 952 the "Tags". The "Tags" contain all extra information about the file: 953 scriptwriter, singer, actors, directors, titles, edition, price, 954 dates, genre, comments, etc. Tags can contain their values in 955 multiple languages. For example, a movie's "title" "Tag" might 956 contain both the original English title as well as the title it was 957 released as in Germany. 959 +-------------------------------------------+ 960 | Tags | Tag | Targets | TargetTypeValue | 961 | | | |------------------| 962 | | | | TargetType | 963 | | | |------------------| 964 | | | | TagTrackUID | 965 | | | |------------------| 966 | | | | TagEditionUID | 967 | | | |------------------| 968 | | | | TagChapterUID | 969 | | | |------------------| 970 | | | | TagAttachmentUID | 971 | | |------------------------------| 972 | | | SimpleTag | TagName | 973 | | | |------------------| 974 | | | | TagLanguage | 975 | | | |------------------| 976 | | | | TagDefault | 977 | | | |------------------| 978 | | | | TagString | 979 | | | |------------------| 980 | | | | TagBinary | 981 | | | |------------------| 982 | | | | SimpleTag | 983 +-------------------------------------------+ 985 Figure 9: Representation of a "Tags Element" and three levels of 986 its "Children Elements". 988 8. Matroska Additions to Schema Element Attributes 990 In addition to the EBML Schema definition provided by the EBML 991 Specification, Matroska adds the following additional attributes: 993 +===========+==========+========================================+ 994 | attribute | required | definition | 995 | name | | | 996 +===========+==========+========================================+ 997 | webm | No | A boolean to express if the Matroska | 998 | | | Element is also supported within | 999 | | | version 2 of the "webm" specification. | 1000 | | | Please consider the webm specification | 1001 | | | (http://www.webmproject.org/docs/ | 1002 | | | container/) as the authoritative on | 1003 | | | "webm". | 1004 +-----------+----------+----------------------------------------+ 1006 Table 9 1008 9. Matroska Schema 1010 This specification includes an "EBML Schema", which defines the 1011 Elements and structure of Matroska as an EBML Document Type. The 1012 EBML Schema defines every valid Matroska element in a manner defined 1013 by the EBML specification. 1015 Here the definition of each Matroska Element is provided. 1017 9.1. EBMLMaxIDLength Element 1019 name: EBMLMaxIDLength 1021 path: "\EBML\EBMLMaxIDLength" 1023 id: 0x42F2 1025 minOccurs: 1 1027 maxOccurs: 1 1029 range: 4 1031 default: 4 1033 type: uinteger 1035 9.2. EBMLMaxSizeLength Element 1037 name: EBMLMaxSizeLength 1039 path: "\EBML\EBMLMaxSizeLength" 1041 id: 0x42F3 1043 minOccurs: 1 1045 maxOccurs: 1 1047 range: 1-8 1049 default: 8 1051 type: uinteger 1053 10. Segment Element 1055 name: Segment 1057 path: "\Segment" 1059 id: 0x18538067 1061 minOccurs: 1 1063 maxOccurs: 1 1065 type: master 1067 unknownsizeallowed: 1 1069 definition: The Root Element that contains all other Top-Level 1070 Elements (Elements defined only at Level 1). A Matroska file is 1071 composed of 1 Segment. 1073 10.1. SeekHead Element 1075 name: SeekHead 1077 path: "\Segment\SeekHead" 1079 id: 0x114D9B74 1081 maxOccurs: 2 1083 type: master 1085 definition: Contains the Segment Position of other Top-Level 1086 Elements. 1088 10.1.1. Seek Element 1090 name: Seek 1092 path: "\Segment\SeekHead\Seek" 1094 id: 0x4DBB 1096 minOccurs: 1 1098 type: master 1100 definition: Contains a single seek entry to an EBML Element. 1102 10.1.1.1. SeekID Element 1104 name: SeekID 1106 path: "\Segment\SeekHead\Seek\SeekID" 1108 id: 0x53AB 1110 minOccurs: 1 1112 maxOccurs: 1 1114 type: binary 1116 definition: The binary ID corresponding to the Element name. 1118 10.1.1.2. SeekPosition Element 1120 name: SeekPosition 1122 path: "\Segment\SeekHead\Seek\SeekPosition" 1124 id: 0x53AC 1126 minOccurs: 1 1128 maxOccurs: 1 1130 type: uinteger 1132 definition: The Segment Position of the Element. 1134 10.2. Info Element 1136 name: Info 1138 path: "\Segment\Info" 1140 id: 0x1549A966 1142 minOccurs: 1 1144 type: master 1146 recurring: 1 1148 definition: Contains general information about the Segment. 1150 10.2.1. SegmentUID Element 1152 name: SegmentUID 1154 path: "\Segment\Info\SegmentUID" 1156 id: 0x73A4 1158 maxOccurs: 1 1160 range: not 0 1162 type: binary 1164 definition: A randomly generated unique ID to identify the Segment 1165 amongst many others (128 bits). 1167 usage notes: If the Segment is a part of a Linked Segment, then this 1168 Element is REQUIRED. 1170 10.2.2. SegmentFilename Element 1172 name: SegmentFilename 1174 path: "\Segment\Info\SegmentFilename" 1176 id: 0x7384 1178 maxOccurs: 1 1180 type: utf-8 1182 definition: A filename corresponding to this Segment. 1184 10.2.3. PrevUID Element 1186 name: PrevUID 1188 path: "\Segment\Info\PrevUID" 1190 id: 0x3CB923 1192 maxOccurs: 1 1194 type: binary 1196 definition: A unique ID to identify the previous Segment of a Linked 1197 Segment (128 bits). 1199 usage notes: If the Segment is a part of a Linked Segment that uses 1200 Hard Linking, then either the PrevUID or the NextUID Element is 1201 REQUIRED. If a Segment contains a PrevUID but not a NextUID, then 1202 it MAY be considered as the last Segment of the Linked Segment. 1203 The PrevUID MUST NOT be equal to the SegmentUID. 1205 10.2.4. PrevFilename Element 1207 name: PrevFilename 1209 path: "\Segment\Info\PrevFilename" 1211 id: 0x3C83AB 1213 maxOccurs: 1 1215 type: utf-8 1217 definition: A filename corresponding to the file of the previous 1218 Linked Segment. 1220 usage notes: Provision of the previous filename is for display 1221 convenience, but PrevUID SHOULD be considered authoritative for 1222 identifying the previous Segment in a Linked Segment. 1224 10.2.5. NextUID Element 1226 name: NextUID 1228 path: "\Segment\Info\NextUID" 1230 id: 0x3EB923 1232 maxOccurs: 1 1234 type: binary 1236 definition: A unique ID to identify the next Segment of a Linked 1237 Segment (128 bits). 1239 usage notes: If the Segment is a part of a Linked Segment that uses 1240 Hard Linking, then either the PrevUID or the NextUID Element is 1241 REQUIRED. If a Segment contains a NextUID but not a PrevUID, then 1242 it MAY be considered as the first Segment of the Linked Segment. 1243 The NextUID MUST NOT be equal to the SegmentUID. 1245 10.2.6. NextFilename Element 1247 name: NextFilename 1249 path: "\Segment\Info\NextFilename" 1251 id: 0x3E83BB 1253 maxOccurs: 1 1255 type: utf-8 1257 definition: A filename corresponding to the file of the next Linked 1258 Segment. 1260 usage notes: Provision of the next filename is for display 1261 convenience, but NextUID SHOULD be considered authoritative for 1262 identifying the Next Segment. 1264 10.2.7. SegmentFamily Element 1266 name: SegmentFamily 1268 path: "\Segment\Info\SegmentFamily" 1270 id: 0x4444 1272 type: binary 1274 definition: A randomly generated unique ID that all Segments of a 1275 Linked Segment MUST share (128 bits). 1277 usage notes: If the Segment is a part of a Linked Segment that uses 1278 Soft Linking, then this Element is REQUIRED. 1280 10.2.8. ChapterTranslate Element 1282 name: ChapterTranslate 1284 path: "\Segment\Info\ChapterTranslate" 1286 id: 0x6924 1288 type: master 1290 definition: A tuple of corresponding ID used by chapter codecs to 1291 represent this Segment. 1293 10.2.8.1. ChapterTranslateEditionUID Element 1295 name: ChapterTranslateEditionUID 1297 path: "\Segment\Info\ChapterTranslate\ChapterTranslateEditionUID" 1299 id: 0x69FC 1301 type: uinteger 1303 definition: Specify an edition UID on which this correspondence 1304 applies. When not specified, it means for all editions found in 1305 the Segment. 1307 10.2.8.2. ChapterTranslateCodec Element 1309 name: ChapterTranslateCodec 1311 path: "\Segment\Info\ChapterTranslate\ChapterTranslateCodec" 1313 id: 0x69BF 1315 minOccurs: 1 1317 maxOccurs: 1 1319 type: uinteger 1321 definition: The chapter codec; see Section 10.7.1.5.12.1. 1323 restrictions: 1325 +=======+=================+ 1326 | value | label | 1327 +=======+=================+ 1328 | 0 | Matroska Script | 1329 +-------+-----------------+ 1330 | 1 | DVD-menu | 1331 +-------+-----------------+ 1333 Table 10 1335 10.2.8.3. ChapterTranslateID Element 1337 name: ChapterTranslateID 1339 path: "\Segment\Info\ChapterTranslate\ChapterTranslateID" 1340 id: 0x69A5 1342 minOccurs: 1 1344 maxOccurs: 1 1346 type: binary 1348 definition: The binary value used to represent this Segment in the 1349 chapter codec data. The format depends on the ChapProcessCodecID 1350 used; see Section 10.7.1.5.12.1. 1352 10.2.9. TimestampScale Element 1354 name: TimestampScale 1356 path: "\Segment\Info\TimestampScale" 1358 id: 0x2AD7B1 1360 minOccurs: 1 1362 maxOccurs: 1 1364 range: not 0 1366 default: 1000000 1368 type: uinteger 1370 definition: Timestamp scale in nanoseconds (1.000.000 means all 1371 timestamps in the Segment are expressed in milliseconds). 1373 10.2.10. Duration Element 1375 name: Duration 1377 path: "\Segment\Info\Duration" 1379 id: 0x4489 1381 maxOccurs: 1 1383 range: > 0x0p+0 1385 type: float 1387 definition: Duration of the Segment in nanoseconds based on 1388 TimestampScale. 1390 10.2.11. DateUTC Element 1392 name: DateUTC 1394 path: "\Segment\Info\DateUTC" 1396 id: 0x4461 1398 maxOccurs: 1 1400 type: date 1402 definition: The date and time that the Segment was created by the 1403 muxing application or library. 1405 10.2.12. Title Element 1407 name: Title 1409 path: "\Segment\Info\Title" 1411 id: 0x7BA9 1413 maxOccurs: 1 1415 type: utf-8 1417 definition: General name of the Segment. 1419 10.2.13. MuxingApp Element 1421 name: MuxingApp 1423 path: "\Segment\Info\MuxingApp" 1425 id: 0x4D80 1427 minOccurs: 1 1429 maxOccurs: 1 1431 type: utf-8 1433 definition: Muxing application or library (example: "libmatroska- 1434 0.4.3"). 1436 usage notes: Include the full name of the application or library 1437 followed by the version number. 1439 10.2.14. WritingApp Element 1441 name: WritingApp 1443 path: "\Segment\Info\WritingApp" 1445 id: 0x5741 1447 minOccurs: 1 1449 maxOccurs: 1 1451 type: utf-8 1453 definition: Writing application (example: "mkvmerge-0.3.3"). 1455 usage notes: Include the full name of the application followed by 1456 the version number. 1458 10.3. Cluster Element 1460 name: Cluster 1462 path: "\Segment\Cluster" 1464 id: 0x1F43B675 1466 type: master 1468 unknownsizeallowed: 1 1470 definition: The Top-Level Element containing the (monolithic) Block 1471 structure. 1473 10.3.1. Timestamp Element 1475 name: Timestamp 1477 path: "\Segment\Cluster\Timestamp" 1479 id: 0xE7 1481 minOccurs: 1 1483 maxOccurs: 1 1484 type: uinteger 1486 definition: Absolute timestamp of the cluster (based on 1487 TimestampScale). 1489 10.3.2. SilentTracks Element 1491 name: SilentTracks 1493 path: "\Segment\Cluster\SilentTracks" 1495 id: 0x5854 1497 maxOccurs: 1 1499 type: master 1501 definition: The list of tracks that are not used in that part of the 1502 stream. It is useful when using overlay tracks on seeking or to 1503 decide what track to use. 1505 10.3.2.1. SilentTrackNumber Element 1507 name: SilentTrackNumber 1509 path: "\Segment\Cluster\SilentTracks\SilentTrackNumber" 1511 id: 0x58D7 1513 type: uinteger 1515 definition: One of the track number that are not used from now on in 1516 the stream. It could change later if not specified as silent in a 1517 further Cluster. 1519 10.3.3. Position Element 1521 name: Position 1523 path: "\Segment\Cluster\Position" 1525 id: 0xA7 1527 maxOccurs: 1 1529 type: uinteger 1531 definition: The Segment Position of the Cluster in the Segment (0 in 1532 live streams). It might help to resynchronise offset on damaged 1533 streams. 1535 10.3.4. PrevSize Element 1537 name: PrevSize 1539 path: "\Segment\Cluster\PrevSize" 1541 id: 0xAB 1543 maxOccurs: 1 1545 type: uinteger 1547 definition: Size of the previous Cluster, in octets. Can be useful 1548 for backward playing. 1550 10.3.5. SimpleBlock Element 1552 name: SimpleBlock 1554 path: "\Segment\Cluster\SimpleBlock" 1556 id: 0xA3 1558 type: binary 1560 minver: 2 1562 definition: Similar to Block, see Section 6.2.3, but without all the 1563 extra information, mostly used to reduced overhead when no extra 1564 feature is needed; see Section 6.2.4.4 on SimpleBlock Structure. 1566 10.3.6. BlockGroup Element 1568 name: BlockGroup 1570 path: "\Segment\Cluster\BlockGroup" 1572 id: 0xA0 1574 type: master 1576 definition: Basic container of information containing a single Block 1577 and information specific to that Block. 1579 10.3.6.1. Block Element 1581 name: Block 1583 path: "\Segment\Cluster\BlockGroup\Block" 1585 id: 0xA1 1587 minOccurs: 1 1589 maxOccurs: 1 1591 type: binary 1593 definition: Block containing the actual data to be rendered and a 1594 timestamp relative to the Cluster Timestamp; see Section 6.2.3 on 1595 Block Structure. 1597 10.3.6.2. BlockVirtual Element 1599 name: BlockVirtual 1601 path: "\Segment\Cluster\BlockGroup\BlockVirtual" 1603 id: 0xA2 1605 maxOccurs: 1 1607 type: binary 1609 minver: 0 1611 maxver: 0 1613 definition: A Block with no data. It MUST be stored in the stream 1614 at the place the real Block would be in display order. 1616 10.3.6.3. BlockAdditions Element 1618 name: BlockAdditions 1620 path: "\Segment\Cluster\BlockGroup\BlockAdditions" 1622 id: 0x75A1 1624 maxOccurs: 1 1626 type: master 1627 definition: Contain additional blocks to complete the main one. An 1628 EBML parser that has no knowledge of the Block structure could 1629 still see and use/skip these data. 1631 10.3.6.3.1. BlockMore Element 1633 name: BlockMore 1635 path: "\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore" 1637 id: 0xA6 1639 minOccurs: 1 1641 type: master 1643 definition: Contain the BlockAdditional and some parameters. 1645 10.3.6.3.1.1. BlockAddID Element 1647 name: BlockAddID 1649 path: "\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAdd 1650 ID" 1652 id: 0xEE 1654 minOccurs: 1 1656 maxOccurs: 1 1658 range: not 0 1660 default: 1 1662 type: uinteger 1664 definition: An ID to identify the BlockAdditional level. If 1665 BlockAddIDType of the corresponding block is 0, this value is also 1666 the value of BlockAddIDType for the meaning of the content of 1667 BlockAdditional. 1669 10.3.6.3.1.2. BlockAdditional Element 1671 name: BlockAdditional 1673 path: "\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAdd 1674 itional" 1676 id: 0xA5 1678 minOccurs: 1 1680 maxOccurs: 1 1682 type: binary 1684 definition: Interpreted by the codec as it wishes (using the 1685 BlockAddID). 1687 10.3.6.4. BlockDuration Element 1689 name: BlockDuration 1691 path: "\Segment\Cluster\BlockGroup\BlockDuration" 1693 id: 0x9B 1695 minOccurs: see implementation notes 1697 maxOccurs: 1 1699 default: see implementation notes 1701 type: uinteger 1703 definition: The duration of the Block (based on TimestampScale). 1704 The BlockDuration Element can be useful at the end of a Track to 1705 define the duration of the last frame (as there is no subsequent 1706 Block available), or when there is a break in a track like for 1707 subtitle tracks. 1709 implementation notes: 1711 +==========================+===============================+ 1712 | attribute | note | 1713 +==========================+===============================+ 1714 | minOccurs | BlockDuration MUST be set | 1715 | | (minOccurs=1) if the | 1716 | | associated TrackEntry stores | 1717 | | a DefaultDuration value. | 1718 +--------------------------+-------------------------------+ 1719 | default | When not written and with no | 1720 | | DefaultDuration, the value is | 1721 | | assumed to be the difference | 1722 | | between the timestamp | 1723 +--------------------------+-------------------------------+ 1724 | of this Block and the | | 1725 | timestamp of the next | | 1726 | Block in "display" order | | 1727 | (not coding order). | | 1728 +--------------------------+-------------------------------+ 1730 Table 11 1732 10.3.6.5. ReferencePriority Element 1734 name: ReferencePriority 1736 path: "\Segment\Cluster\BlockGroup\ReferencePriority" 1738 id: 0xFA 1740 minOccurs: 1 1742 maxOccurs: 1 1744 default: 0 1746 type: uinteger 1748 definition: This frame is referenced and has the specified cache 1749 priority. In cache only a frame of the same or higher priority 1750 can replace this frame. A value of 0 means the frame is not 1751 referenced. 1753 10.3.6.6. ReferenceBlock Element 1755 name: ReferenceBlock 1757 path: "\Segment\Cluster\BlockGroup\ReferenceBlock" 1758 id: 0xFB 1760 type: integer 1762 definition: Timestamp of another frame used as a reference (ie: B or 1763 P frame). The timestamp is relative to the block it's attached 1764 to. 1766 10.3.6.7. ReferenceVirtual Element 1768 name: ReferenceVirtual 1770 path: "\Segment\Cluster\BlockGroup\ReferenceVirtual" 1772 id: 0xFD 1774 maxOccurs: 1 1776 type: integer 1778 minver: 0 1780 maxver: 0 1782 definition: The Segment Position of the data that would otherwise be 1783 in position of the virtual block. 1785 10.3.6.8. CodecState Element 1787 name: CodecState 1789 path: "\Segment\Cluster\BlockGroup\CodecState" 1791 id: 0xA4 1793 maxOccurs: 1 1795 type: binary 1797 minver: 2 1799 definition: The new codec state to use. Data interpretation is 1800 private to the codec. This information SHOULD always be 1801 referenced by a seek entry. 1803 10.3.6.9. DiscardPadding Element 1805 name: DiscardPadding 1807 path: "\Segment\Cluster\BlockGroup\DiscardPadding" 1809 id: 0x75A2 1811 maxOccurs: 1 1813 type: integer 1815 minver: 4 1817 definition: Duration in nanoseconds of the silent data added to the 1818 Block (padding at the end of the Block for positive value, at the 1819 beginning of the Block for negative value). The duration of 1820 DiscardPadding is not calculated in the duration of the TrackEntry 1821 and SHOULD be discarded during playback. 1823 10.3.6.10. Slices Element 1825 name: Slices 1827 path: "\Segment\Cluster\BlockGroup\Slices" 1829 id: 0x8E 1831 maxOccurs: 1 1833 type: master 1835 definition: Contains slices description. 1837 10.3.6.10.1. TimeSlice Element 1839 name: TimeSlice 1841 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice" 1843 id: 0xE8 1845 type: master 1847 maxver: 1 1849 definition: Contains extra time information about the data contained 1850 in the Block. Being able to interpret this Element is not 1851 REQUIRED for playback. 1853 10.3.6.10.1.1. LaceNumber Element 1855 name: LaceNumber 1857 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\LaceNumber" 1859 id: 0xCC 1861 maxOccurs: 1 1863 default: 0 1865 type: uinteger 1867 maxver: 1 1869 definition: The reverse number of the frame in the lace (0 is the 1870 last frame, 1 is the next to last, etc). Being able to interpret 1871 this Element is not REQUIRED for playback. 1873 10.3.6.10.1.2. FrameNumber Element 1875 name: FrameNumber 1877 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\FrameNumber" 1879 id: 0xCD 1881 maxOccurs: 1 1883 default: 0 1885 type: uinteger 1887 minver: 0 1889 maxver: 0 1891 definition: The number of the frame to generate from this lace with 1892 this delay (allow you to generate many frames from the same Block/ 1893 Frame). 1895 10.3.6.10.1.3. BlockAdditionID Element 1897 name: BlockAdditionID 1899 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\BlockAdditionID" 1901 id: 0xCB 1903 maxOccurs: 1 1905 default: 0 1907 type: uinteger 1909 minver: 0 1911 maxver: 0 1913 definition: The ID of the BlockAdditional Element (0 is the main 1914 Block). 1916 10.3.6.10.1.4. Delay Element 1918 name: Delay 1920 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\Delay" 1922 id: 0xCE 1924 maxOccurs: 1 1926 default: 0 1928 type: uinteger 1930 minver: 0 1932 maxver: 0 1934 definition: The (scaled) delay to apply to the Element. 1936 10.3.6.10.1.5. SliceDuration Element 1938 name: SliceDuration 1940 path: "\Segment\Cluster\BlockGroup\Slices\TimeSlice\SliceDuration" 1942 id: 0xCF 1943 maxOccurs: 1 1945 default: 0 1947 type: uinteger 1949 minver: 0 1951 maxver: 0 1953 definition: The (scaled) duration to apply to the Element. 1955 10.3.6.11. ReferenceFrame Element 1957 name: ReferenceFrame 1959 path: "\Segment\Cluster\BlockGroup\ReferenceFrame" 1961 id: 0xC8 1963 maxOccurs: 1 1965 type: master 1967 minver: 0 1969 maxver: 0 1971 definition: DivX trick track extensions 1973 10.3.6.11.1. ReferenceOffset Element 1975 name: ReferenceOffset 1977 path: "\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceOffset" 1979 id: 0xC9 1981 minOccurs: 1 1983 maxOccurs: 1 1985 type: uinteger 1987 minver: 0 1989 maxver: 0 1990 definition: DivX trick track extensions 1992 10.3.6.11.2. ReferenceTimestamp Element 1994 name: ReferenceTimestamp 1996 path: "\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceTimestamp 1997 " 1999 id: 0xCA 2001 minOccurs: 1 2003 maxOccurs: 1 2005 type: uinteger 2007 minver: 0 2009 maxver: 0 2011 definition: DivX trick track extensions 2013 10.3.7. EncryptedBlock Element 2015 name: EncryptedBlock 2017 path: "\Segment\Cluster\EncryptedBlock" 2019 id: 0xAF 2021 type: binary 2023 minver: 0 2025 maxver: 0 2027 definition: Similar to SimpleBlock, see Section 6.2.4.4, but the 2028 data inside the Block are Transformed (encrypt and/or signed). 2030 10.4. Tracks Element 2032 name: Tracks 2034 path: "\Segment\Tracks" 2036 id: 0x1654AE6B 2037 type: master 2039 recurring: 1 2041 definition: A Top-Level Element of information with many tracks 2042 described. 2044 10.4.1. TrackEntry Element 2046 name: TrackEntry 2048 path: "\Segment\Tracks\TrackEntry" 2050 id: 0xAE 2052 minOccurs: 1 2054 type: master 2056 definition: Describes a track with all Elements. 2058 10.4.1.1. TrackNumber Element 2060 name: TrackNumber 2062 path: "\Segment\Tracks\TrackEntry\TrackNumber" 2064 id: 0xD7 2066 minOccurs: 1 2068 maxOccurs: 1 2070 range: not 0 2072 type: uinteger 2074 definition: The track number as used in the Block Header (using more 2075 than 127 tracks is not encouraged, though the design allows an 2076 unlimited number). 2078 10.4.1.2. TrackUID Element 2080 name: TrackUID 2082 path: "\Segment\Tracks\TrackEntry\TrackUID" 2084 id: 0x73C5 2085 minOccurs: 1 2087 maxOccurs: 1 2089 range: not 0 2091 type: uinteger 2093 definition: A unique ID to identify the Track. This SHOULD be kept 2094 the same when making a direct stream copy of the Track to another 2095 file. 2097 10.4.1.3. TrackType Element 2099 name: TrackType 2101 path: "\Segment\Tracks\TrackEntry\TrackType" 2103 id: 0x83 2105 minOccurs: 1 2107 maxOccurs: 1 2109 range: 1-254 2111 type: uinteger 2113 definition: A set of track types coded on 8 bits. 2115 restrictions: 2117 +=======+==========+ 2118 | value | label | 2119 +=======+==========+ 2120 | 1 | video | 2121 +-------+----------+ 2122 | 2 | audio | 2123 +-------+----------+ 2124 | 3 | complex | 2125 +-------+----------+ 2126 | 16 | logo | 2127 +-------+----------+ 2128 | 17 | subtitle | 2129 +-------+----------+ 2130 | 18 | buttons | 2131 +-------+----------+ 2132 | 32 | control | 2133 +-------+----------+ 2134 | 33 | metadata | 2135 +-------+----------+ 2137 Table 12 2139 10.4.1.4. FlagEnabled Element 2141 name: FlagEnabled 2143 path: "\Segment\Tracks\TrackEntry\FlagEnabled" 2145 id: 0xB9 2147 minOccurs: 1 2149 maxOccurs: 1 2151 range: 0-1 2153 default: 1 2155 type: uinteger 2157 minver: 2 2159 definition: Set if the track is usable. (1 bit) 2161 10.4.1.5. FlagDefault Element 2163 name: FlagDefault 2164 path: "\Segment\Tracks\TrackEntry\FlagDefault" 2166 id: 0x88 2168 minOccurs: 1 2170 maxOccurs: 1 2172 range: 0-1 2174 default: 1 2176 type: uinteger 2178 definition: Set if that track (audio, video or subs) SHOULD be 2179 active if no language found matches the user preference. (1 bit) 2181 10.4.1.6. FlagForced Element 2183 name: FlagForced 2185 path: "\Segment\Tracks\TrackEntry\FlagForced" 2187 id: 0x55AA 2189 minOccurs: 1 2191 maxOccurs: 1 2193 range: 0-1 2195 default: 0 2197 type: uinteger 2199 definition: Set if that track MUST be active during playback. There 2200 can be many forced track for a kind (audio, video or subs), the 2201 player SHOULD select the one which language matches the user 2202 preference or the default + forced track. Overlay MAY happen 2203 between a forced and non-forced track of the same kind. (1 bit) 2205 10.4.1.7. FlagLacing Element 2207 name: FlagLacing 2209 path: "\Segment\Tracks\TrackEntry\FlagLacing" 2211 id: 0x9C 2212 minOccurs: 1 2214 maxOccurs: 1 2216 range: 0-1 2218 default: 1 2220 type: uinteger 2222 definition: Set if the track MAY contain blocks using lacing. (1 2223 bit) 2225 10.4.1.8. MinCache Element 2227 name: MinCache 2229 path: "\Segment\Tracks\TrackEntry\MinCache" 2231 id: 0x6DE7 2233 minOccurs: 1 2235 maxOccurs: 1 2237 default: 0 2239 type: uinteger 2241 definition: The minimum number of frames a player SHOULD be able to 2242 cache during playback. If set to 0, the reference pseudo-cache 2243 system is not used. 2245 10.4.1.9. MaxCache Element 2247 name: MaxCache 2249 path: "\Segment\Tracks\TrackEntry\MaxCache" 2251 id: 0x6DF8 2253 maxOccurs: 1 2255 type: uinteger 2257 definition: The maximum cache size necessary to store referenced 2258 frames in and the current frame. 0 means no cache is needed. 2260 10.4.1.10. DefaultDuration Element 2262 name: DefaultDuration 2264 path: "\Segment\Tracks\TrackEntry\DefaultDuration" 2266 id: 0x23E383 2268 maxOccurs: 1 2270 range: not 0 2272 type: uinteger 2274 definition: Number of nanoseconds (not scaled via TimestampScale) 2275 per frame (frame in the Matroska sense -- one Element put into a 2276 (Simple)Block). 2278 10.4.1.11. DefaultDecodedFieldDuration Element 2280 name: DefaultDecodedFieldDuration 2282 path: "\Segment\Tracks\TrackEntry\DefaultDecodedFieldDuration" 2284 id: 0x234E7A 2286 maxOccurs: 1 2288 range: not 0 2290 type: uinteger 2292 minver: 4 2294 definition: The period in nanoseconds (not scaled by TimestampScale) 2295 between two successive fields at the output of the decoding 2296 process, see Section 19 for more information 2298 10.4.1.12. TrackTimestampScale Element 2300 name: TrackTimestampScale 2302 path: "\Segment\Tracks\TrackEntry\TrackTimestampScale" 2304 id: 0x23314F 2306 minOccurs: 1 2307 maxOccurs: 1 2309 range: > 0x0p+0 2311 default: 0x1p+0 2313 type: float 2315 maxver: 3 2317 definition: DEPRECATED, DO NOT USE. The scale to apply on this 2318 track to work at normal speed in relation with other tracks 2319 (mostly used to adjust video speed when the audio length differs). 2321 10.4.1.13. TrackOffset Element 2323 name: TrackOffset 2325 path: "\Segment\Tracks\TrackEntry\TrackOffset" 2327 id: 0x537F 2329 maxOccurs: 1 2331 default: 0 2333 type: integer 2335 minver: 0 2337 maxver: 0 2339 definition: A value to add to the Block's Timestamp. This can be 2340 used to adjust the playback offset of a track. 2342 10.4.1.14. MaxBlockAdditionID Element 2344 name: MaxBlockAdditionID 2346 path: "\Segment\Tracks\TrackEntry\MaxBlockAdditionID" 2348 id: 0x55EE 2350 minOccurs: 1 2352 maxOccurs: 1 2354 default: 0 2355 type: uinteger 2357 definition: The maximum value of BlockAddID (Section 10.3.6.3.1.1). 2358 A value 0 means there is no BlockAdditions (Section 10.3.6.3) for 2359 this track. 2361 10.4.1.15. BlockAdditionMapping Element 2363 name: BlockAdditionMapping 2365 path: "\Segment\Tracks\TrackEntry\BlockAdditionMapping" 2367 id: 0x41E4 2369 type: master 2371 minver: 4 2373 definition: Contains elements that extend the track format, by 2374 adding content either to each frame, with BlockAddID 2375 (Section 10.3.6.3.1.1), or to the track as a whole with 2376 BlockAddIDExtraData. 2378 10.4.1.15.1. BlockAddIDValue Element 2380 name: BlockAddIDValue 2382 path: "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDVal 2383 ue" 2385 id: 0x41F0 2387 maxOccurs: 1 2389 range: >=2 2391 type: uinteger 2393 minver: 4 2395 definition: If the track format extension needs content beside 2396 frames, the value refers to the BlockAddID (Section 10.3.6.3.1.1), 2397 value being described. To keep MaxBlockAdditionID as low as 2398 possible, small values SHOULD be used. 2400 10.4.1.15.2. BlockAddIDName Element 2402 name: BlockAddIDName 2404 path: "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDNam 2405 e" 2407 id: 0x41A4 2409 maxOccurs: 1 2411 type: string 2413 minver: 4 2415 definition: A human-friendly name describing the type of 2416 BlockAdditional data, as defined by the associated Block 2417 Additional Mapping. 2419 10.4.1.15.3. BlockAddIDType Element 2421 name: BlockAddIDType 2423 path: "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDTyp 2424 e" 2426 id: 0x41E7 2428 minOccurs: 1 2430 maxOccurs: 1 2432 default: 0 2434 type: uinteger 2436 minver: 4 2438 definition: Stores the registered identifer of the Block Additional 2439 Mapping to define how the BlockAdditional data should be handled. 2441 10.4.1.15.4. BlockAddIDExtraData Element 2443 name: BlockAddIDExtraData 2445 path: "\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDExt 2446 raData" 2448 id: 0x41ED 2450 maxOccurs: 1 2452 type: binary 2454 minver: 4 2456 definition: Extra binary data that the BlockAddIDType can use to 2457 interpret the BlockAdditional data. The intepretation of the 2458 binary data depends on the BlockAddIDType value and the 2459 corresponding Block Additional Mapping. 2461 10.4.1.16. Name Element 2463 name: Name 2465 path: "\Segment\Tracks\TrackEntry\Name" 2467 id: 0x536E 2469 maxOccurs: 1 2471 type: utf-8 2473 definition: A human-readable track name. 2475 10.4.1.17. Language Element 2477 name: Language 2479 path: "\Segment\Tracks\TrackEntry\Language" 2481 id: 0x22B59C 2483 maxOccurs: 1 2485 default: eng 2487 type: string 2489 definition: Specifies the language of the track in the Matroska 2490 languages form; see Section 6.2.1 on language codes. This Element 2491 MUST be ignored if the LanguageIETF Element is used in the same 2492 TrackEntry. 2494 10.4.1.18. LanguageIETF Element 2496 name: LanguageIETF 2498 path: "\Segment\Tracks\TrackEntry\LanguageIETF" 2500 id: 0x22B59D 2502 maxOccurs: 1 2504 type: string 2506 minver: 4 2508 definition: Specifies the language of the track according to BCP 47 2509 and using the IANA Language Subtag Registry. If this Element is 2510 used, then any Language Elements used in the same TrackEntry MUST 2511 be ignored. 2513 10.4.1.19. CodecID Element 2515 name: CodecID 2517 path: "\Segment\Tracks\TrackEntry\CodecID" 2519 id: 0x86 2521 minOccurs: 1 2523 maxOccurs: 1 2525 type: string 2527 definition: An ID corresponding to the codec, see 2528 [I-D.ietf-cellar-codec] for more info. 2530 10.4.1.20. CodecPrivate Element 2532 name: CodecPrivate 2534 path: "\Segment\Tracks\TrackEntry\CodecPrivate" 2536 id: 0x63A2 2538 maxOccurs: 1 2540 type: binary 2541 definition: Private data only known to the codec. 2543 10.4.1.21. CodecName Element 2545 name: CodecName 2547 path: "\Segment\Tracks\TrackEntry\CodecName" 2549 id: 0x258688 2551 maxOccurs: 1 2553 type: utf-8 2555 definition: A human-readable string specifying the codec. 2557 10.4.1.22. AttachmentLink Element 2559 name: AttachmentLink 2561 path: "\Segment\Tracks\TrackEntry\AttachmentLink" 2563 id: 0x7446 2565 maxOccurs: 1 2567 range: not 0 2569 type: uinteger 2571 maxver: 3 2573 definition: The UID of an attachment that is used by this codec. 2575 10.4.1.23. CodecSettings Element 2577 name: CodecSettings 2579 path: "\Segment\Tracks\TrackEntry\CodecSettings" 2581 id: 0x3A9697 2583 maxOccurs: 1 2585 type: utf-8 2587 minver: 0 2588 maxver: 0 2590 definition: A string describing the encoding setting used. 2592 10.4.1.24. CodecInfoURL Element 2594 name: CodecInfoURL 2596 path: "\Segment\Tracks\TrackEntry\CodecInfoURL" 2598 id: 0x3B4040 2600 type: string 2602 minver: 0 2604 maxver: 0 2606 definition: A URL to find information about the codec used. 2608 10.4.1.25. CodecDownloadURL Element 2610 name: CodecDownloadURL 2612 path: "\Segment\Tracks\TrackEntry\CodecDownloadURL" 2614 id: 0x26B240 2616 type: string 2618 minver: 0 2620 maxver: 0 2622 definition: A URL to download about the codec used. 2624 10.4.1.26. CodecDecodeAll Element 2626 name: CodecDecodeAll 2628 path: "\Segment\Tracks\TrackEntry\CodecDecodeAll" 2630 id: 0xAA 2632 minOccurs: 1 2634 maxOccurs: 1 2635 range: 0-1 2637 default: 1 2639 type: uinteger 2641 minver: 2 2643 definition: The codec can decode potentially damaged data (1 bit). 2645 10.4.1.27. TrackOverlay Element 2647 name: TrackOverlay 2649 path: "\Segment\Tracks\TrackEntry\TrackOverlay" 2651 id: 0x6FAB 2653 type: uinteger 2655 definition: Specify that this track is an overlay track for the 2656 Track specified (in the u-integer). That means when this track 2657 has a gap, see Section 10.3.2 on SilentTracks, the overlay track 2658 SHOULD be used instead. The order of multiple TrackOverlay 2659 matters, the first one is the one that SHOULD be used. If not 2660 found it SHOULD be the second, etc. 2662 10.4.1.28. CodecDelay Element 2664 name: CodecDelay 2666 path: "\Segment\Tracks\TrackEntry\CodecDelay" 2668 id: 0x56AA 2670 maxOccurs: 1 2672 default: 0 2674 type: uinteger 2676 minver: 4 2678 definition: CodecDelay is The codec-built-in delay in nanoseconds. 2679 This value MUST be subtracted from each block timestamp in order 2680 to get the actual timestamp. The value SHOULD be small so the 2681 muxing of tracks with the same actual timestamp are in the same 2682 Cluster. 2684 10.4.1.29. SeekPreRoll Element 2686 name: SeekPreRoll 2688 path: "\Segment\Tracks\TrackEntry\SeekPreRoll" 2690 id: 0x56BB 2692 minOccurs: 1 2694 maxOccurs: 1 2696 default: 0 2698 type: uinteger 2700 minver: 4 2702 definition: After a discontinuity, SeekPreRoll is the duration in 2703 nanoseconds of the data the decoder MUST decode before the decoded 2704 data is valid. 2706 10.4.1.30. TrackTranslate Element 2708 name: TrackTranslate 2710 path: "\Segment\Tracks\TrackEntry\TrackTranslate" 2712 id: 0x6624 2714 type: master 2716 definition: The track identification for the given Chapter Codec. 2718 10.4.1.30.1. TrackTranslateEditionUID Element 2720 name: TrackTranslateEditionUID 2722 path: "\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateEditi 2723 onUID" 2725 id: 0x66FC 2727 type: uinteger 2729 definition: Specify an edition UID on which this translation 2730 applies. When not specified, it means for all editions found in 2731 the Segment. 2733 10.4.1.30.2. TrackTranslateCodec Element 2735 name: TrackTranslateCodec 2737 path: "\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateCodec 2738 " 2740 id: 0x66BF 2742 minOccurs: 1 2744 maxOccurs: 1 2746 type: uinteger 2748 definition: The chapter codec; see Section 10.7.1.5.12.1. 2750 restrictions: 2752 +=======+=================+ 2753 | value | label | 2754 +=======+=================+ 2755 | 0 | Matroska Script | 2756 +-------+-----------------+ 2757 | 1 | DVD-menu | 2758 +-------+-----------------+ 2760 Table 13 2762 10.4.1.30.3. TrackTranslateTrackID Element 2764 name: TrackTranslateTrackID 2766 path: "\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateTrack 2767 ID" 2769 id: 0x66A5 2771 minOccurs: 1 2773 maxOccurs: 1 2775 type: binary 2777 definition: The binary value used to represent this track in the 2778 chapter codec data. The format depends on the ChapProcessCodecID 2779 used; see Section 10.7.1.5.12.1. 2781 10.4.1.31. Video Element 2783 name: Video 2785 path: "\Segment\Tracks\TrackEntry\Video" 2787 id: 0xE0 2789 maxOccurs: 1 2791 type: master 2793 definition: Video settings. 2795 10.4.1.31.1. FlagInterlaced Element 2797 name: FlagInterlaced 2799 path: "\Segment\Tracks\TrackEntry\Video\FlagInterlaced" 2801 id: 0x9A 2803 minOccurs: 1 2805 maxOccurs: 1 2807 range: 0-2 2809 default: 0 2811 type: uinteger 2813 minver: 2 2815 definition: A flag to declare if the video is known to be 2816 progressive, or interlaced, and if applicable to declare details 2817 about the interlacement. 2819 restrictions: 2821 +=======+==============+ 2822 | value | label | 2823 +=======+==============+ 2824 | 0 | undetermined | 2825 +-------+--------------+ 2826 | 1 | interlaced | 2827 +-------+--------------+ 2828 | 2 | progressive | 2829 +-------+--------------+ 2831 Table 14 2833 10.4.1.31.2. FieldOrder Element 2835 name: FieldOrder 2837 path: "\Segment\Tracks\TrackEntry\Video\FieldOrder" 2839 id: 0x9D 2841 minOccurs: 1 2843 maxOccurs: 1 2845 range: 0-14 2847 default: 2 2849 type: uinteger 2851 minver: 4 2853 definition: Declare the field ordering of the video. If 2854 FlagInterlaced is not set to 1, this Element MUST be ignored. 2856 restrictions: 2858 +===================+==============+===============================+ 2859 | value | label | documentation | 2860 +===================+==============+===============================+ 2861 | 0 | progressive | | 2862 +-------------------+--------------+-------------------------------+ 2863 | 1 | tff | Top field displayed first. | 2864 | | | Top field stored first. | 2865 +-------------------+--------------+-------------------------------+ 2866 | 2 | undetermined | | 2867 +-------------------+--------------+-------------------------------+ 2868 | 6 | bff | Bottom field displayed first. | 2869 | | | Bottom field stored first. | 2870 +-------------------+--------------+-------------------------------+ 2871 | 9 | bff(swapped) | Top field displayed first. | 2872 | | | Fields are interleaved in | 2873 | | | storage | 2874 +-------------------+--------------+-------------------------------+ 2875 | with the top line | | | 2876 | of the top field | | | 2877 | stored first. | | | 2878 +-------------------+--------------+-------------------------------+ 2879 | 14 | tff(swapped) | Bottom field displayed first. | 2880 | | | Fields are interleaved in | 2881 | | | storage | 2882 +-------------------+--------------+-------------------------------+ 2883 | with the top line | | | 2884 | of the top field | | | 2885 | stored first. | | | 2886 +-------------------+--------------+-------------------------------+ 2888 Table 15 2890 10.4.1.31.3. StereoMode Element 2892 name: StereoMode 2894 path: "\Segment\Tracks\TrackEntry\Video\StereoMode" 2896 id: 0x53B8 2898 maxOccurs: 1 2900 default: 0 2902 type: uinteger 2904 minver: 3 2905 definition: Stereo-3D video mode. There are some more details in 2906 Section 26.5. 2908 restrictions: 2910 +=======+===================================================+ 2911 | value | label | 2912 +=======+===================================================+ 2913 | 0 | mono | 2914 +-------+---------------------------------------------------+ 2915 | 1 | side by side (left eye first) | 2916 +-------+---------------------------------------------------+ 2917 | 2 | top - bottom (right eye is first) | 2918 +-------+---------------------------------------------------+ 2919 | 3 | top - bottom (left eye is first) | 2920 +-------+---------------------------------------------------+ 2921 | 4 | checkboard (right eye is first) | 2922 +-------+---------------------------------------------------+ 2923 | 5 | checkboard (left eye is first) | 2924 +-------+---------------------------------------------------+ 2925 | 6 | row interleaved (right eye is first) | 2926 +-------+---------------------------------------------------+ 2927 | 7 | row interleaved (left eye is first) | 2928 +-------+---------------------------------------------------+ 2929 | 8 | column interleaved (right eye is first) | 2930 +-------+---------------------------------------------------+ 2931 | 9 | column interleaved (left eye is first) | 2932 +-------+---------------------------------------------------+ 2933 | 10 | anaglyph (cyan/red) | 2934 +-------+---------------------------------------------------+ 2935 | 11 | side by side (right eye first) | 2936 +-------+---------------------------------------------------+ 2937 | 12 | anaglyph (green/magenta) | 2938 +-------+---------------------------------------------------+ 2939 | 13 | both eyes laced in one Block (left eye is first) | 2940 +-------+---------------------------------------------------+ 2941 | 14 | both eyes laced in one Block (right eye is first) | 2942 +-------+---------------------------------------------------+ 2944 Table 16 2946 10.4.1.31.4. AlphaMode Element 2948 name: AlphaMode 2950 path: "\Segment\Tracks\TrackEntry\Video\AlphaMode" 2952 id: 0x53C0 2953 maxOccurs: 1 2955 default: 0 2957 type: uinteger 2959 minver: 3 2961 definition: Alpha Video Mode. Presence of this Element indicates 2962 that the BlockAdditional Element could contain Alpha data. 2964 10.4.1.31.5. OldStereoMode Element 2966 name: OldStereoMode 2968 path: "\Segment\Tracks\TrackEntry\Video\OldStereoMode" 2970 id: 0x53B9 2972 maxOccurs: 1 2974 type: uinteger 2976 maxver: 0 2978 definition: DEPRECATED, DO NOT USE. Bogus StereoMode value used in 2979 old versions of libmatroska. 2981 restrictions: 2983 +=======+===========+ 2984 | value | label | 2985 +=======+===========+ 2986 | 0 | mono | 2987 +-------+-----------+ 2988 | 1 | right eye | 2989 +-------+-----------+ 2990 | 2 | left eye | 2991 +-------+-----------+ 2992 | 3 | both eyes | 2993 +-------+-----------+ 2995 Table 17 2997 10.4.1.31.6. PixelWidth Element 2999 name: PixelWidth 3000 path: "\Segment\Tracks\TrackEntry\Video\PixelWidth" 3002 id: 0xB0 3004 minOccurs: 1 3006 maxOccurs: 1 3008 range: not 0 3010 type: uinteger 3012 definition: Width of the encoded video frames in pixels. 3014 10.4.1.31.7. PixelHeight Element 3016 name: PixelHeight 3018 path: "\Segment\Tracks\TrackEntry\Video\PixelHeight" 3020 id: 0xBA 3022 minOccurs: 1 3024 maxOccurs: 1 3026 range: not 0 3028 type: uinteger 3030 definition: Height of the encoded video frames in pixels. 3032 10.4.1.31.8. PixelCropBottom Element 3034 name: PixelCropBottom 3036 path: "\Segment\Tracks\TrackEntry\Video\PixelCropBottom" 3038 id: 0x54AA 3040 maxOccurs: 1 3042 default: 0 3044 type: uinteger 3046 definition: The number of video pixels to remove at the bottom of 3047 the image. 3049 10.4.1.31.9. PixelCropTop Element 3051 name: PixelCropTop 3053 path: "\Segment\Tracks\TrackEntry\Video\PixelCropTop" 3055 id: 0x54BB 3057 maxOccurs: 1 3059 default: 0 3061 type: uinteger 3063 definition: The number of video pixels to remove at the top of the 3064 image. 3066 10.4.1.31.10. PixelCropLeft Element 3068 name: PixelCropLeft 3070 path: "\Segment\Tracks\TrackEntry\Video\PixelCropLeft" 3072 id: 0x54CC 3074 maxOccurs: 1 3076 default: 0 3078 type: uinteger 3080 definition: The number of video pixels to remove on the left of the 3081 image. 3083 10.4.1.31.11. PixelCropRight Element 3085 name: PixelCropRight 3087 path: "\Segment\Tracks\TrackEntry\Video\PixelCropRight" 3089 id: 0x54DD 3091 maxOccurs: 1 3093 default: 0 3095 type: uinteger 3096 definition: The number of video pixels to remove on the right of the 3097 image. 3099 10.4.1.31.12. DisplayWidth Element 3101 name: DisplayWidth 3103 path: "\Segment\Tracks\TrackEntry\Video\DisplayWidth" 3105 id: 0x54B0 3107 maxOccurs: 1 3109 range: not 0 3111 default: see implementation notes 3113 type: uinteger 3115 definition: Width of the video frames to display. Applies to the 3116 video frame after cropping (PixelCrop* Elements). 3118 implementation notes: 3120 +============================+====================================+ 3121 | attribute | note | 3122 +============================+====================================+ 3123 | default | If the DisplayUnit of the same | 3124 | | TrackEntry is 0, then the default | 3125 | | value for DisplayWidth is equal to | 3126 +----------------------------+------------------------------------+ 3127 | PixelWidth - PixelCropLeft | | 3128 | - PixelCropRight, else | | 3129 | there is no default value. | | 3130 +----------------------------+------------------------------------+ 3132 Table 18 3134 10.4.1.31.13. DisplayHeight Element 3136 name: DisplayHeight 3138 path: "\Segment\Tracks\TrackEntry\Video\DisplayHeight" 3140 id: 0x54BA 3142 maxOccurs: 1 3143 range: not 0 3145 default: see implementation notes 3147 type: uinteger 3149 definition: Height of the video frames to display. Applies to the 3150 video frame after cropping (PixelCrop* Elements). 3152 implementation notes: 3154 +============================+=====================================+ 3155 | attribute | note | 3156 +============================+=====================================+ 3157 | default | If the DisplayUnit of the same | 3158 | | TrackEntry is 0, then the default | 3159 | | value for DisplayHeight is equal to | 3160 +----------------------------+-------------------------------------+ 3161 | PixelHeight - PixelCropTop | | 3162 | - PixelCropBottom, else | | 3163 | there is no default value. | | 3164 +----------------------------+-------------------------------------+ 3166 Table 19 3168 10.4.1.31.14. DisplayUnit Element 3170 name: DisplayUnit 3172 path: "\Segment\Tracks\TrackEntry\Video\DisplayUnit" 3174 id: 0x54B2 3176 maxOccurs: 1 3178 default: 0 3180 type: uinteger 3182 definition: How DisplayWidth & DisplayHeight are interpreted. 3184 restrictions: 3186 +=======+======================+ 3187 | value | label | 3188 +=======+======================+ 3189 | 0 | pixels | 3190 +-------+----------------------+ 3191 | 1 | centimeters | 3192 +-------+----------------------+ 3193 | 2 | inches | 3194 +-------+----------------------+ 3195 | 3 | display aspect ratio | 3196 +-------+----------------------+ 3197 | 4 | unknown | 3198 +-------+----------------------+ 3200 Table 20 3202 10.4.1.31.15. AspectRatioType Element 3204 name: AspectRatioType 3206 path: "\Segment\Tracks\TrackEntry\Video\AspectRatioType" 3208 id: 0x54B3 3210 maxOccurs: 1 3212 default: 0 3214 type: uinteger 3216 definition: Specify the possible modifications to the aspect ratio. 3218 restrictions: 3220 +=======+===================+ 3221 | value | label | 3222 +=======+===================+ 3223 | 0 | free resizing | 3224 +-------+-------------------+ 3225 | 1 | keep aspect ratio | 3226 +-------+-------------------+ 3227 | 2 | fixed | 3228 +-------+-------------------+ 3230 Table 21 3232 10.4.1.31.16. ColourSpace Element 3234 name: ColourSpace 3236 path: "\Segment\Tracks\TrackEntry\Video\ColourSpace" 3238 id: 0x2EB524 3240 minOccurs: see implementation notes 3242 maxOccurs: 1 3244 type: binary 3246 definition: Specify the pixel format used for the Track's data as a 3247 FourCC. This value is similar in scope to the biCompression value 3248 of AVI's BITMAPINFOHEADER. 3250 implementation notes: 3252 +===========+============================================+ 3253 | attribute | note | 3254 +===========+============================================+ 3255 | minOccurs | ColourSpace MUST be set (minOccurs=1) in | 3256 | | TrackEntry, when the CodecID Element of | 3257 | | the TrackEntry is set to "V_UNCOMPRESSED". | 3258 +-----------+--------------------------------------------+ 3260 Table 22 3262 10.4.1.31.17. GammaValue Element 3264 name: GammaValue 3266 path: "\Segment\Tracks\TrackEntry\Video\GammaValue" 3268 id: 0x2FB523 3270 maxOccurs: 1 3272 range: > 0x0p+0 3274 type: float 3276 minver: 0 3278 maxver: 0 3279 definition: Gamma Value. 3281 10.4.1.31.18. FrameRate Element 3283 name: FrameRate 3285 path: "\Segment\Tracks\TrackEntry\Video\FrameRate" 3287 id: 0x2383E3 3289 maxOccurs: 1 3291 range: > 0x0p+0 3293 type: float 3295 minver: 0 3297 maxver: 0 3299 definition: Number of frames per second. Informational only. 3301 10.4.1.31.19. Colour Element 3303 name: Colour 3305 path: "\Segment\Tracks\TrackEntry\Video\Colour" 3307 id: 0x55B0 3309 maxOccurs: 1 3311 type: master 3313 minver: 4 3315 definition: Settings describing the colour format. 3317 10.4.1.31.19.1. MatrixCoefficients Element 3319 name: MatrixCoefficients 3321 path: "\Segment\Tracks\TrackEntry\Video\Colour\MatrixCoefficients" 3323 id: 0x55B1 3325 maxOccurs: 1 3326 default: 2 3328 type: uinteger 3330 minver: 4 3332 definition: The Matrix Coefficients of the video used to derive luma 3333 and chroma values from red, green, and blue color primaries. For 3334 clarity, the value and meanings for MatrixCoefficients are adopted 3335 from Table 4 of ISO/IEC 23001-8:2016 or ITU-T H.273. 3337 restrictions: 3339 +=======+=======================================+ 3340 | value | label | 3341 +=======+=======================================+ 3342 | 0 | Identity | 3343 +-------+---------------------------------------+ 3344 | 1 | ITU-R BT.709 | 3345 +-------+---------------------------------------+ 3346 | 2 | unspecified | 3347 +-------+---------------------------------------+ 3348 | 3 | reserved | 3349 +-------+---------------------------------------+ 3350 | 4 | US FCC 73.682 | 3351 +-------+---------------------------------------+ 3352 | 5 | ITU-R BT.470BG | 3353 +-------+---------------------------------------+ 3354 | 6 | SMPTE 170M | 3355 +-------+---------------------------------------+ 3356 | 7 | SMPTE 240M | 3357 +-------+---------------------------------------+ 3358 | 8 | YCoCg | 3359 +-------+---------------------------------------+ 3360 | 9 | BT2020 Non-constant Luminance | 3361 +-------+---------------------------------------+ 3362 | 10 | BT2020 Constant Luminance | 3363 +-------+---------------------------------------+ 3364 | 11 | SMPTE ST 2085 | 3365 +-------+---------------------------------------+ 3366 | 12 | Chroma-derived Non-constant Luminance | 3367 +-------+---------------------------------------+ 3368 | 13 | Chroma-derived Constant Luminance | 3369 +-------+---------------------------------------+ 3370 | 14 | ITU-R BT.2100-0 | 3371 +-------+---------------------------------------+ 3373 Table 23 3375 10.4.1.31.19.2. BitsPerChannel Element 3377 name: BitsPerChannel 3379 path: "\Segment\Tracks\TrackEntry\Video\Colour\BitsPerChannel" 3381 id: 0x55B2 3383 maxOccurs: 1 3385 default: 0 3387 type: uinteger 3389 minver: 4 3391 definition: Number of decoded bits per channel. A value of 0 3392 indicates that the BitsPerChannel is unspecified. 3394 10.4.1.31.19.3. ChromaSubsamplingHorz Element 3396 name: ChromaSubsamplingHorz 3398 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingHorz 3399 " 3401 id: 0x55B3 3403 maxOccurs: 1 3405 type: uinteger 3407 minver: 4 3409 definition: The amount of pixels to remove in the Cr and Cb channels 3410 for every pixel not removed horizontally. Example: For video with 3411 4:2:0 chroma subsampling, the ChromaSubsamplingHorz SHOULD be set 3412 to 1. 3414 10.4.1.31.19.4. ChromaSubsamplingVert Element 3416 name: ChromaSubsamplingVert 3418 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingVert 3419 " 3421 id: 0x55B4 3422 maxOccurs: 1 3424 type: uinteger 3426 minver: 4 3428 definition: The amount of pixels to remove in the Cr and Cb channels 3429 for every pixel not removed vertically. Example: For video with 3430 4:2:0 chroma subsampling, the ChromaSubsamplingVert SHOULD be set 3431 to 1. 3433 10.4.1.31.19.5. CbSubsamplingHorz Element 3435 name: CbSubsamplingHorz 3437 path: "\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingHorz" 3439 id: 0x55B5 3441 maxOccurs: 1 3443 type: uinteger 3445 minver: 4 3447 definition: The amount of pixels to remove in the Cb channel for 3448 every pixel not removed horizontally. This is additive with 3449 ChromaSubsamplingHorz. Example: For video with 4:2:1 chroma 3450 subsampling, the ChromaSubsamplingHorz SHOULD be set to 1 and 3451 CbSubsamplingHorz SHOULD be set to 1. 3453 10.4.1.31.19.6. CbSubsamplingVert Element 3455 name: CbSubsamplingVert 3457 path: "\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingVert" 3459 id: 0x55B6 3461 maxOccurs: 1 3463 type: uinteger 3465 minver: 4 3467 definition: The amount of pixels to remove in the Cb channel for 3468 every pixel not removed vertically. This is additive with 3469 ChromaSubsamplingVert. 3471 10.4.1.31.19.7. ChromaSitingHorz Element 3473 name: ChromaSitingHorz 3475 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingHorz" 3477 id: 0x55B7 3479 maxOccurs: 1 3481 default: 0 3483 type: uinteger 3485 minver: 4 3487 definition: How chroma is subsampled horizontally. 3489 restrictions: 3491 +=======+=================+ 3492 | value | label | 3493 +=======+=================+ 3494 | 0 | unspecified | 3495 +-------+-----------------+ 3496 | 1 | left collocated | 3497 +-------+-----------------+ 3498 | 2 | half | 3499 +-------+-----------------+ 3501 Table 24 3503 10.4.1.31.19.8. ChromaSitingVert Element 3505 name: ChromaSitingVert 3507 path: "\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingVert" 3509 id: 0x55B8 3511 maxOccurs: 1 3513 default: 0 3515 type: uinteger 3517 minver: 4 3518 definition: How chroma is subsampled vertically. 3520 restrictions: 3522 +=======+================+ 3523 | value | label | 3524 +=======+================+ 3525 | 0 | unspecified | 3526 +-------+----------------+ 3527 | 1 | top collocated | 3528 +-------+----------------+ 3529 | 2 | half | 3530 +-------+----------------+ 3532 Table 25 3534 10.4.1.31.19.9. Range Element 3536 name: Range 3538 path: "\Segment\Tracks\TrackEntry\Video\Colour\Range" 3540 id: 0x55B9 3542 maxOccurs: 1 3544 default: 0 3546 type: uinteger 3548 minver: 4 3550 definition: Clipping of the color ranges. 3552 restrictions: 3554 +=======+=========================================================+ 3555 | value | label | 3556 +=======+=========================================================+ 3557 | 0 | unspecified | 3558 +-------+---------------------------------------------------------+ 3559 | 1 | broadcast range | 3560 +-------+---------------------------------------------------------+ 3561 | 2 | full range (no clipping) | 3562 +-------+---------------------------------------------------------+ 3563 | 3 | defined by MatrixCoefficients / TransferCharacteristics | 3564 +-------+---------------------------------------------------------+ 3566 Table 26 3568 10.4.1.31.19.10. TransferCharacteristics Element 3570 name: TransferCharacteristics 3572 path: "\Segment\Tracks\TrackEntry\Video\Colour\TransferCharacteristi 3573 cs" 3575 id: 0x55BA 3577 maxOccurs: 1 3579 default: 2 3581 type: uinteger 3583 minver: 4 3585 definition: The transfer characteristics of the video. For clarity, 3586 the value and meanings for TransferCharacteristics are adopted 3587 from Table 3 of ISO/IEC 23091-4 or ITU-T H.273. 3589 restrictions: 3591 +=======+=======================================+ 3592 | value | label | 3593 +=======+=======================================+ 3594 | 0 | reserved | 3595 +-------+---------------------------------------+ 3596 | 1 | ITU-R BT.709 | 3597 +-------+---------------------------------------+ 3598 | 2 | unspecified | 3599 +-------+---------------------------------------+ 3600 | 3 | reserved | 3601 +-------+---------------------------------------+ 3602 | 4 | Gamma 2.2 curve - BT.470M | 3603 +-------+---------------------------------------+ 3604 | 5 | Gamma 2.8 curve - BT.470BG | 3605 +-------+---------------------------------------+ 3606 | 6 | SMPTE 170M | 3607 +-------+---------------------------------------+ 3608 | 7 | SMPTE 240M | 3609 +-------+---------------------------------------+ 3610 | 8 | Linear | 3611 +-------+---------------------------------------+ 3612 | 9 | Log | 3613 +-------+---------------------------------------+ 3614 | 10 | Log Sqrt | 3615 +-------+---------------------------------------+ 3616 | 11 | IEC 61966-2-4 | 3617 +-------+---------------------------------------+ 3618 | 12 | ITU-R BT.1361 Extended Colour Gamut | 3619 +-------+---------------------------------------+ 3620 | 13 | IEC 61966-2-1 | 3621 +-------+---------------------------------------+ 3622 | 14 | ITU-R BT.2020 10 bit | 3623 +-------+---------------------------------------+ 3624 | 15 | ITU-R BT.2020 12 bit | 3625 +-------+---------------------------------------+ 3626 | 16 | ITU-R BT.2100 Perceptual Quantization | 3627 +-------+---------------------------------------+ 3628 | 17 | SMPTE ST 428-1 | 3629 +-------+---------------------------------------+ 3630 | 18 | ARIB STD-B67 (HLG) | 3631 +-------+---------------------------------------+ 3633 Table 27 3635 10.4.1.31.19.11. Primaries Element 3637 name: Primaries 3638 path: "\Segment\Tracks\TrackEntry\Video\Colour\Primaries" 3640 id: 0x55BB 3642 maxOccurs: 1 3644 default: 2 3646 type: uinteger 3648 minver: 4 3650 definition: The colour primaries of the video. For clarity, the 3651 value and meanings for Primaries are adopted from Table 2 of ISO/ 3652 IEC 23091-4 or ITU-T H.273. 3654 restrictions: 3656 +=======+========================================+ 3657 | value | label | 3658 +=======+========================================+ 3659 | 0 | reserved | 3660 +-------+----------------------------------------+ 3661 | 1 | ITU-R BT.709 | 3662 +-------+----------------------------------------+ 3663 | 2 | unspecified | 3664 +-------+----------------------------------------+ 3665 | 3 | reserved | 3666 +-------+----------------------------------------+ 3667 | 4 | ITU-R BT.470M | 3668 +-------+----------------------------------------+ 3669 | 5 | ITU-R BT.470BG - BT.601 625 | 3670 +-------+----------------------------------------+ 3671 | 6 | ITU-R BT.601 525 - SMPTE 170M | 3672 +-------+----------------------------------------+ 3673 | 7 | SMPTE 240M | 3674 +-------+----------------------------------------+ 3675 | 8 | FILM | 3676 +-------+----------------------------------------+ 3677 | 9 | ITU-R BT.2020 | 3678 +-------+----------------------------------------+ 3679 | 10 | SMPTE ST 428-1 | 3680 +-------+----------------------------------------+ 3681 | 11 | SMPTE RP 432-2 | 3682 +-------+----------------------------------------+ 3683 | 12 | SMPTE EG 432-2 | 3684 +-------+----------------------------------------+ 3685 | 22 | EBU Tech. 3213-E - JEDEC P22 phosphors | 3686 +-------+----------------------------------------+ 3688 Table 28 3690 10.4.1.31.19.12. MaxCLL Element 3692 name: MaxCLL 3694 path: "\Segment\Tracks\TrackEntry\Video\Colour\MaxCLL" 3696 id: 0x55BC 3698 maxOccurs: 1 3700 type: uinteger 3702 minver: 4 3703 definition: Maximum brightness of a single pixel (Maximum Content 3704 Light Level) in candelas per square meter (cd/m²). 3706 10.4.1.31.19.13. MaxFALL Element 3708 name: MaxFALL 3710 path: "\Segment\Tracks\TrackEntry\Video\Colour\MaxFALL" 3712 id: 0x55BD 3714 maxOccurs: 1 3716 type: uinteger 3718 minver: 4 3720 definition: Maximum brightness of a single full frame (Maximum 3721 Frame-Average Light Level) in candelas per square meter (cd/ 3722 m²). 3724 10.4.1.31.19.14. MasteringMetadata Element 3726 name: MasteringMetadata 3728 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata" 3730 id: 0x55D0 3732 maxOccurs: 1 3734 type: master 3736 minver: 4 3738 definition: SMPTE 2086 mastering data. 3740 10.4.1.31.19.15. PrimaryRChromaticityX Element 3742 name: PrimaryRChromaticityX 3744 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Pri 3745 maryRChromaticityX" 3747 id: 0x55D1 3749 maxOccurs: 1 3750 range: 0-1 3752 type: float 3754 minver: 4 3756 definition: Red X chromaticity coordinate, as defined by CIE 1931. 3758 10.4.1.31.19.16. PrimaryRChromaticityY Element 3760 name: PrimaryRChromaticityY 3762 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Pri 3763 maryRChromaticityY" 3765 id: 0x55D2 3767 maxOccurs: 1 3769 range: 0-1 3771 type: float 3773 minver: 4 3775 definition: Red Y chromaticity coordinate, as defined by CIE 1931. 3777 10.4.1.31.19.17. PrimaryGChromaticityX Element 3779 name: PrimaryGChromaticityX 3781 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Pri 3782 maryGChromaticityX" 3784 id: 0x55D3 3786 maxOccurs: 1 3788 range: 0-1 3790 type: float 3792 minver: 4 3794 definition: Green X chromaticity coordinate, as defined by CIE 1931. 3796 10.4.1.31.19.18. PrimaryGChromaticityY Element 3798 name: PrimaryGChromaticityY 3800 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Pri 3801 maryGChromaticityY" 3803 id: 0x55D4 3805 maxOccurs: 1 3807 range: 0-1 3809 type: float 3811 minver: 4 3813 definition: Green Y chromaticity coordinate, as defined by CIE 1931. 3815 10.4.1.31.19.19. PrimaryBChromaticityX Element 3817 name: PrimaryBChromaticityX 3819 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Pri 3820 maryBChromaticityX" 3822 id: 0x55D5 3824 maxOccurs: 1 3826 range: 0-1 3828 type: float 3830 minver: 4 3832 definition: Blue X chromaticity coordinate, as defined by CIE 1931. 3834 10.4.1.31.19.20. PrimaryBChromaticityY Element 3836 name: PrimaryBChromaticityY 3838 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Pri 3839 maryBChromaticityY" 3841 id: 0x55D6 3843 maxOccurs: 1 3844 range: 0-1 3846 type: float 3848 minver: 4 3850 definition: Blue Y chromaticity coordinate, as defined by CIE 1931. 3852 10.4.1.31.19.21. WhitePointChromaticityX Element 3854 name: WhitePointChromaticityX 3856 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Whi 3857 tePointChromaticityX" 3859 id: 0x55D7 3861 maxOccurs: 1 3863 range: 0-1 3865 type: float 3867 minver: 4 3869 definition: White X chromaticity coordinate, as defined by CIE 1931. 3871 10.4.1.31.19.22. WhitePointChromaticityY Element 3873 name: WhitePointChromaticityY 3875 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Whi 3876 tePointChromaticityY" 3878 id: 0x55D8 3880 maxOccurs: 1 3882 range: 0-1 3884 type: float 3886 minver: 4 3888 definition: White Y chromaticity coordinate, as defined by CIE 1931. 3890 10.4.1.31.19.23. LuminanceMax Element 3892 name: LuminanceMax 3894 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Lum 3895 inanceMax" 3897 id: 0x55D9 3899 maxOccurs: 1 3901 range: >= 0x0p+0 3903 type: float 3905 minver: 4 3907 definition: Maximum luminance. Represented in candelas per square 3908 meter (cd/m²). 3910 10.4.1.31.19.24. LuminanceMin Element 3912 name: LuminanceMin 3914 path: "\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\Lum 3915 inanceMin" 3917 id: 0x55DA 3919 maxOccurs: 1 3921 range: >= 0x0p+0 3923 type: float 3925 minver: 4 3927 definition: Minimum luminance. Represented in candelas per square 3928 meter (cd/m²). 3930 10.4.1.31.20. Projection Element 3932 name: Projection 3934 path: "\Segment\Tracks\TrackEntry\Video\Projection" 3936 id: 0x7670 3937 maxOccurs: 1 3939 type: master 3941 minver: 4 3943 definition: Describes the video projection details. Used to render 3944 spherical and VR videos. 3946 10.4.1.31.20.1. ProjectionType Element 3948 name: ProjectionType 3950 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionType" 3952 id: 0x7671 3954 minOccurs: 1 3956 maxOccurs: 1 3958 range: 0-3 3960 default: 0 3962 type: uinteger 3964 minver: 4 3966 definition: Describes the projection used for this video track. 3968 restrictions: 3970 +=======+=================+ 3971 | value | label | 3972 +=======+=================+ 3973 | 0 | rectangular | 3974 +-------+-----------------+ 3975 | 1 | equirectangular | 3976 +-------+-----------------+ 3977 | 2 | cubemap | 3978 +-------+-----------------+ 3979 | 3 | mesh | 3980 +-------+-----------------+ 3982 Table 29 3984 10.4.1.31.20.2. ProjectionPrivate Element 3986 name: ProjectionPrivate 3988 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPrivate 3989 " 3991 id: 0x7672 3993 maxOccurs: 1 3995 type: binary 3997 minver: 4 3999 definition: Private data that only applies to a specific projection. 4001 * If "ProjectionType" equals 0 (Rectangular), then this element must 4002 not be present. 4004 * If "ProjectionType" equals 1 (Equirectangular), then this element 4005 must be present and contain the same binary data that would be 4006 stored inside an ISOBMFF Equirectangular Projection Box ('equi'). 4008 * If "ProjectionType" equals 2 (Cubemap), then this element must be 4009 present and contain the same binary data that would be stored 4010 inside an ISOBMFF Cubemap Projection Box ('cbmp'). 4012 * If "ProjectionType" equals 3 (Mesh), then this element must be 4013 present and contain the same binary data that would be stored 4014 inside an ISOBMFF Mesh Projection Box ('mshp'). 4016 usage notes: ISOBMFF box size and fourcc fields are not included in 4017 the binary data, but the FullBox version and flag fields are. 4018 This is to avoid redundant framing information while preserving 4019 versioning and semantics between the two container formats. 4021 10.4.1.31.20.3. ProjectionPoseYaw Element 4023 name: ProjectionPoseYaw 4025 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseYaw 4026 " 4028 id: 0x7673 4030 minOccurs: 1 4031 maxOccurs: 1 4033 default: 0x0p+0 4035 type: float 4037 minver: 4 4039 definition: Specifies a yaw rotation to the projection. 4041 Value represents a clockwise rotation, in degrees, around the up 4042 vector. This rotation must be applied before any 4043 "ProjectionPosePitch" or "ProjectionPoseRoll" rotations. The value 4044 of this field should be in the -180 to 180 degree range. 4046 10.4.1.31.20.4. ProjectionPosePitch Element 4048 name: ProjectionPosePitch 4050 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPosePit 4051 ch" 4053 id: 0x7674 4055 minOccurs: 1 4057 maxOccurs: 1 4059 default: 0x0p+0 4061 type: float 4063 minver: 4 4065 definition: Specifies a pitch rotation to the projection. 4067 Value represents a counter-clockwise rotation, in degrees, around the 4068 right vector. This rotation must be applied after the 4069 "ProjectionPoseYaw" rotation and before the "ProjectionPoseRoll" 4070 rotation. The value of this field should be in the -90 to 90 degree 4071 range. 4073 10.4.1.31.20.5. ProjectionPoseRoll Element 4075 name: ProjectionPoseRoll 4077 path: "\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseRol 4078 l" 4080 id: 0x7675 4082 minOccurs: 1 4084 maxOccurs: 1 4086 default: 0x0p+0 4088 type: float 4090 minver: 4 4092 definition: Specifies a roll rotation to the projection. 4094 Value represents a counter-clockwise rotation, in degrees, around the 4095 forward vector. This rotation must be applied after the 4096 "ProjectionPoseYaw" and "ProjectionPosePitch" rotations. The value 4097 of this field should be in the -180 to 180 degree range. 4099 10.4.1.32. Audio Element 4101 name: Audio 4103 path: "\Segment\Tracks\TrackEntry\Audio" 4105 id: 0xE1 4107 maxOccurs: 1 4109 type: master 4111 definition: Audio settings. 4113 10.4.1.32.1. SamplingFrequency Element 4115 name: SamplingFrequency 4117 path: "\Segment\Tracks\TrackEntry\Audio\SamplingFrequency" 4119 id: 0xB5 4121 minOccurs: 1 4123 maxOccurs: 1 4125 range: > 0x0p+0 4127 default: 0x1.f4p+12 4128 type: float 4130 definition: Sampling frequency in Hz. 4132 10.4.1.32.2. OutputSamplingFrequency Element 4134 name: OutputSamplingFrequency 4136 path: "\Segment\Tracks\TrackEntry\Audio\OutputSamplingFrequency" 4138 id: 0x78B5 4140 maxOccurs: 1 4142 range: > 0x0p+0 4144 default: see implementation notes 4146 type: float 4148 definition: Real output sampling frequency in Hz (used for SBR 4149 techniques). 4151 implementation notes: 4153 +===========+======================================================+ 4154 | attribute | note | 4155 +===========+======================================================+ 4156 | default | The default value for OutputSamplingFrequency of the | 4157 | | same TrackEntry is equal to the SamplingFrequency. | 4158 +-----------+------------------------------------------------------+ 4160 Table 30 4162 10.4.1.32.3. Channels Element 4164 name: Channels 4166 path: "\Segment\Tracks\TrackEntry\Audio\Channels" 4168 id: 0x9F 4170 minOccurs: 1 4172 maxOccurs: 1 4174 range: not 0 4175 default: 1 4177 type: uinteger 4179 definition: Numbers of channels in the track. 4181 10.4.1.32.4. ChannelPositions Element 4183 name: ChannelPositions 4185 path: "\Segment\Tracks\TrackEntry\Audio\ChannelPositions" 4187 id: 0x7D7B 4189 maxOccurs: 1 4191 type: binary 4193 minver: 0 4195 maxver: 0 4197 definition: Table of horizontal angles for each successive channel. 4199 10.4.1.32.5. BitDepth Element 4201 name: BitDepth 4203 path: "\Segment\Tracks\TrackEntry\Audio\BitDepth" 4205 id: 0x6264 4207 maxOccurs: 1 4209 range: not 0 4211 type: uinteger 4213 definition: Bits per sample, mostly used for PCM. 4215 10.4.1.33. TrackOperation Element 4217 name: TrackOperation 4219 path: "\Segment\Tracks\TrackEntry\TrackOperation" 4221 id: 0xE2 4222 maxOccurs: 1 4224 type: master 4226 minver: 3 4228 definition: Operation that needs to be applied on tracks to create 4229 this virtual track. For more details look at Section 26.3. 4231 10.4.1.33.1. TrackCombinePlanes Element 4233 name: TrackCombinePlanes 4235 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes" 4237 id: 0xE3 4239 maxOccurs: 1 4241 type: master 4243 minver: 3 4245 definition: Contains the list of all video plane tracks that need to 4246 be combined to create this 3D track 4248 10.4.1.33.1.1. TrackPlane Element 4250 name: TrackPlane 4252 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\ 4253 TrackPlane" 4255 id: 0xE4 4257 minOccurs: 1 4259 type: master 4261 minver: 3 4263 definition: Contains a video plane track that need to be combined to 4264 create this 3D track 4266 10.4.1.33.1.2. TrackPlaneUID Element 4268 name: TrackPlaneUID 4269 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\ 4270 TrackPlane\TrackPlaneUID" 4272 id: 0xE5 4274 minOccurs: 1 4276 maxOccurs: 1 4278 range: not 0 4280 type: uinteger 4282 minver: 3 4284 definition: The trackUID number of the track representing the plane. 4286 10.4.1.33.1.3. TrackPlaneType Element 4288 name: TrackPlaneType 4290 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes\ 4291 TrackPlane\TrackPlaneType" 4293 id: 0xE6 4295 minOccurs: 1 4297 maxOccurs: 1 4299 type: uinteger 4301 minver: 3 4303 definition: The kind of plane this track corresponds to. 4305 restrictions: 4307 +=======+============+ 4308 | value | label | 4309 +=======+============+ 4310 | 0 | left eye | 4311 +-------+------------+ 4312 | 1 | right eye | 4313 +-------+------------+ 4314 | 2 | background | 4315 +-------+------------+ 4317 Table 31 4319 10.4.1.33.2. TrackJoinBlocks Element 4321 name: TrackJoinBlocks 4323 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks" 4325 id: 0xE9 4327 maxOccurs: 1 4329 type: master 4331 minver: 3 4333 definition: Contains the list of all tracks whose Blocks need to be 4334 combined to create this virtual track 4336 10.4.1.33.2.1. TrackJoinUID Element 4338 name: TrackJoinUID 4340 path: "\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks\Tra 4341 ckJoinUID" 4343 id: 0xED 4345 minOccurs: 1 4347 range: not 0 4349 type: uinteger 4351 minver: 3 4353 definition: The trackUID number of a track whose blocks are used to 4354 create this virtual track. 4356 10.4.1.34. TrickTrackUID Element 4358 name: TrickTrackUID 4360 path: "\Segment\Tracks\TrackEntry\TrickTrackUID" 4362 id: 0xC0 4364 maxOccurs: 1 4366 type: uinteger 4368 minver: 0 4370 maxver: 0 4372 definition: DivX trick track extensions 4374 10.4.1.35. TrickTrackSegmentUID Element 4376 name: TrickTrackSegmentUID 4378 path: "\Segment\Tracks\TrackEntry\TrickTrackSegmentUID" 4380 id: 0xC1 4382 maxOccurs: 1 4384 type: binary 4386 minver: 0 4388 maxver: 0 4390 definition: DivX trick track extensions 4392 10.4.1.36. TrickTrackFlag Element 4394 name: TrickTrackFlag 4396 path: "\Segment\Tracks\TrackEntry\TrickTrackFlag" 4398 id: 0xC6 4400 maxOccurs: 1 4402 default: 0 4403 type: uinteger 4405 minver: 0 4407 maxver: 0 4409 definition: DivX trick track extensions 4411 10.4.1.37. TrickMasterTrackUID Element 4413 name: TrickMasterTrackUID 4415 path: "\Segment\Tracks\TrackEntry\TrickMasterTrackUID" 4417 id: 0xC7 4419 maxOccurs: 1 4421 type: uinteger 4423 minver: 0 4425 maxver: 0 4427 definition: DivX trick track extensions 4429 10.4.1.38. TrickMasterTrackSegmentUID Element 4431 name: TrickMasterTrackSegmentUID 4433 path: "\Segment\Tracks\TrackEntry\TrickMasterTrackSegmentUID" 4435 id: 0xC4 4437 maxOccurs: 1 4439 type: binary 4441 minver: 0 4443 maxver: 0 4445 definition: DivX trick track extensions 4447 10.4.1.39. ContentEncodings Element 4449 name: ContentEncodings 4450 path: "\Segment\Tracks\TrackEntry\ContentEncodings" 4452 id: 0x6D80 4454 maxOccurs: 1 4456 type: master 4458 definition: Settings for several content encoding mechanisms like 4459 compression or encryption. 4461 10.4.1.39.1. ContentEncoding Element 4463 name: ContentEncoding 4465 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding" 4467 id: 0x6240 4469 minOccurs: 1 4471 type: master 4473 definition: Settings for one content encoding like compression or 4474 encryption. 4476 10.4.1.39.1.1. ContentEncodingOrder Element 4478 name: ContentEncodingOrder 4480 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4481 ontentEncodingOrder" 4483 id: 0x5031 4485 minOccurs: 1 4487 maxOccurs: 1 4489 default: 0 4491 type: uinteger 4493 definition: Tells when this modification was used during encoding/ 4494 muxing starting with 0 and counting upwards. The decoder/demuxer 4495 has to start with the highest order number it finds and work its 4496 way down. This value has to be unique over all 4497 ContentEncodingOrder Elements in the TrackEntry that contains this 4498 ContentEncodingOrder element. 4500 10.4.1.39.1.2. ContentEncodingScope Element 4502 name: ContentEncodingScope 4504 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4505 ontentEncodingScope" 4507 id: 0x5032 4509 minOccurs: 1 4511 maxOccurs: 1 4513 range: not 0 4515 default: 1 4517 type: uinteger 4519 definition: A bit field that describes which Elements have been 4520 modified in this way. Values (big-endian) can be OR'ed. 4522 restrictions: 4524 +=======+==================================================+ 4525 | value | label | 4526 +=======+==================================================+ 4527 | 1 | All frame contents, excluding lacing data | 4528 +-------+--------------------------------------------------+ 4529 | 2 | The track's private data | 4530 +-------+--------------------------------------------------+ 4531 | 4 | The next ContentEncoding (next | 4532 | | "ContentEncodingOrder". Either the data inside | 4533 | | "ContentCompression" and/or "ContentEncryption") | 4534 +-------+--------------------------------------------------+ 4536 Table 32 4538 10.4.1.39.1.3. ContentEncodingType Element 4540 name: ContentEncodingType 4541 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4542 ontentEncodingType" 4544 id: 0x5033 4546 minOccurs: 1 4548 maxOccurs: 1 4550 default: 0 4552 type: uinteger 4554 definition: A value describing what kind of transformation is 4555 applied. 4557 restrictions: 4559 +=======+=============+ 4560 | value | label | 4561 +=======+=============+ 4562 | 0 | Compression | 4563 +-------+-------------+ 4564 | 1 | Encryption | 4565 +-------+-------------+ 4567 Table 33 4569 10.4.1.39.1.4. ContentCompression Element 4571 name: ContentCompression 4573 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4574 ontentCompression" 4576 id: 0x5034 4578 maxOccurs: 1 4580 type: master 4582 definition: Settings describing the compression used. This Element 4583 MUST be present if the value of ContentEncodingType is 0 and 4584 absent otherwise. Each block MUST be decompressable even if no 4585 previous block is available in order not to prevent seeking. 4587 10.4.1.39.1.5. ContentCompAlgo Element 4589 name: ContentCompAlgo 4591 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4592 ontentCompression\ContentCompAlgo" 4594 id: 0x4254 4596 minOccurs: 1 4598 maxOccurs: 1 4600 default: 0 4602 type: uinteger 4604 definition: The compression algorithm used. 4606 restrictions: 4608 +=======+==================+ 4609 | value | label | 4610 +=======+==================+ 4611 | 0 | zlib | 4612 +-------+------------------+ 4613 | 1 | bzlib | 4614 +-------+------------------+ 4615 | 2 | lzo1x | 4616 +-------+------------------+ 4617 | 3 | Header Stripping | 4618 +-------+------------------+ 4620 Table 34 4622 10.4.1.39.1.6. ContentCompSettings Element 4624 name: ContentCompSettings 4626 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4627 ontentCompression\ContentCompSettings" 4629 id: 0x4255 4631 maxOccurs: 1 4633 type: binary 4634 definition: Settings that might be needed by the decompressor. For 4635 Header Stripping ("ContentCompAlgo"=3), the bytes that were 4636 removed from the beginning of each frames of the track. 4638 10.4.1.39.1.7. ContentEncryption Element 4640 name: ContentEncryption 4642 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4643 ontentEncryption" 4645 id: 0x5035 4647 maxOccurs: 1 4649 type: master 4651 definition: Settings describing the encryption used. This Element 4652 MUST be present if the value of "ContentEncodingType" is 1 4653 (encryption) and MUST be ignored otherwise. 4655 10.4.1.39.1.8. ContentEncAlgo Element 4657 name: ContentEncAlgo 4659 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4660 ontentEncryption\ContentEncAlgo" 4662 id: 0x47E1 4664 minOccurs: 1 4666 maxOccurs: 1 4668 default: 0 4670 type: uinteger 4672 definition: The encryption algorithm used. The value "0" means that 4673 the contents have not been encrypted but only signed. 4675 restrictions: 4677 +=======+=======================+ 4678 | value | label | 4679 +=======+=======================+ 4680 | 0 | Not encrypted | 4681 +-------+-----------------------+ 4682 | 1 | DES - FIPS 46-3 | 4683 +-------+-----------------------+ 4684 | 2 | Triple DES - RFC 1851 | 4685 +-------+-----------------------+ 4686 | 3 | Twofish | 4687 +-------+-----------------------+ 4688 | 4 | Blowfish | 4689 +-------+-----------------------+ 4690 | 5 | AES - FIPS 187 | 4691 +-------+-----------------------+ 4693 Table 35 4695 10.4.1.39.1.9. ContentEncKeyID Element 4697 name: ContentEncKeyID 4699 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4700 ontentEncryption\ContentEncKeyID" 4702 id: 0x47E2 4704 maxOccurs: 1 4706 type: binary 4708 definition: For public key algorithms this is the ID of the public 4709 key the the data was encrypted with. 4711 10.4.1.39.1.10. ContentEncAESSettings Element 4713 name: ContentEncAESSettings 4715 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4716 ontentEncryption\ContentEncAESSettings" 4718 id: 0x47E7 4720 maxOccurs: 1 4722 type: master 4724 minver: 4 4725 definition: Settings describing the encryption algorithm used. If 4726 "ContentEncAlgo" != 5 this MUST be ignored. 4728 10.4.1.39.1.11. AESSettingsCipherMode Element 4730 name: AESSettingsCipherMode 4732 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4733 ontentEncryption\ContentEncAESSettings\AESSettingsCipherMode" 4735 id: 0x47E8 4737 minOccurs: 1 4739 maxOccurs: 1 4741 type: uinteger 4743 minver: 4 4745 definition: The AES cipher mode used in the encryption. 4747 restrictions: 4749 +=======+==================================================+ 4750 | value | label | 4751 +=======+==================================================+ 4752 | 1 | AES-CTR / Counter, NIST SP 800-38A | 4753 +-------+--------------------------------------------------+ 4754 | 2 | AES-CBC / Cipher Block Chaining, NIST SP 800-38A | 4755 +-------+--------------------------------------------------+ 4757 Table 36 4759 10.4.1.39.1.12. ContentSignature Element 4761 name: ContentSignature 4763 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4764 ontentEncryption\ContentSignature" 4766 id: 0x47E3 4768 maxOccurs: 1 4770 type: binary 4772 definition: A cryptographic signature of the contents. 4774 10.4.1.39.1.13. ContentSigKeyID Element 4776 name: ContentSigKeyID 4778 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4779 ontentEncryption\ContentSigKeyID" 4781 id: 0x47E4 4783 maxOccurs: 1 4785 type: binary 4787 definition: This is the ID of the private key the data was signed 4788 with. 4790 10.4.1.39.1.14. ContentSigAlgo Element 4792 name: ContentSigAlgo 4794 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4795 ontentEncryption\ContentSigAlgo" 4797 id: 0x47E5 4799 maxOccurs: 1 4801 default: 0 4803 type: uinteger 4805 definition: The algorithm used for the signature. 4807 restrictions: 4809 +=======+============+ 4810 | value | label | 4811 +=======+============+ 4812 | 0 | Not signed | 4813 +-------+------------+ 4814 | 1 | RSA | 4815 +-------+------------+ 4817 Table 37 4819 10.4.1.39.1.15. ContentSigHashAlgo Element 4821 name: ContentSigHashAlgo 4823 path: "\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding\C 4824 ontentEncryption\ContentSigHashAlgo" 4826 id: 0x47E6 4828 maxOccurs: 1 4830 default: 0 4832 type: uinteger 4834 definition: The hash algorithm used for the signature. 4836 restrictions: 4838 +=======+============+ 4839 | value | label | 4840 +=======+============+ 4841 | 0 | Not signed | 4842 +-------+------------+ 4843 | 1 | SHA1-160 | 4844 +-------+------------+ 4845 | 2 | MD5 | 4846 +-------+------------+ 4848 Table 38 4850 10.5. Cues Element 4852 name: Cues 4854 path: "\Segment\Cues" 4856 id: 0x1C53BB6B 4858 minOccurs: see implementation notes 4860 maxOccurs: 1 4862 type: master 4864 definition: A Top-Level Element to speed seeking access. All 4865 entries are local to the Segment. 4867 implementation notes: 4869 +===========+====================================================+ 4870 | attribute | note | 4871 +===========+====================================================+ 4872 | minOccurs | This Element SHOULD be set when the Segment is not | 4873 | | transmitted as a live stream (see #livestreaming). | 4874 +-----------+----------------------------------------------------+ 4876 Table 39 4878 10.5.1. CuePoint Element 4880 name: CuePoint 4882 path: "\Segment\Cues\CuePoint" 4884 id: 0xBB 4886 minOccurs: 1 4888 type: master 4890 definition: Contains all information relative to a seek point in the 4891 Segment. 4893 10.5.1.1. CueTime Element 4895 name: CueTime 4897 path: "\Segment\Cues\CuePoint\CueTime" 4899 id: 0xB3 4901 minOccurs: 1 4903 maxOccurs: 1 4905 type: uinteger 4907 definition: Absolute timestamp according to the Segment time base. 4909 10.5.1.2. CueTrackPositions Element 4911 name: CueTrackPositions 4913 path: "\Segment\Cues\CuePoint\CueTrackPositions" 4914 id: 0xB7 4916 minOccurs: 1 4918 type: master 4920 definition: Contain positions for different tracks corresponding to 4921 the timestamp. 4923 10.5.1.2.1. CueTrack Element 4925 name: CueTrack 4927 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueTrack" 4929 id: 0xF7 4931 minOccurs: 1 4933 maxOccurs: 1 4935 range: not 0 4937 type: uinteger 4939 definition: The track for which a position is given. 4941 10.5.1.2.2. CueClusterPosition Element 4943 name: CueClusterPosition 4945 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueClusterPosition" 4947 id: 0xF1 4949 minOccurs: 1 4951 maxOccurs: 1 4953 type: uinteger 4955 definition: The Segment Position of the Cluster containing the 4956 associated Block. 4958 10.5.1.2.3. CueRelativePosition Element 4960 name: CueRelativePosition 4961 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueRelativePosition" 4963 id: 0xF0 4965 maxOccurs: 1 4967 type: uinteger 4969 minver: 4 4971 definition: The relative position inside the Cluster of the 4972 referenced SimpleBlock or BlockGroup with 0 being the first 4973 possible position for an Element inside that Cluster. 4975 10.5.1.2.4. CueDuration Element 4977 name: CueDuration 4979 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueDuration" 4981 id: 0xB2 4983 maxOccurs: 1 4985 type: uinteger 4987 minver: 4 4989 definition: The duration of the block according to the Segment time 4990 base. If missing the track's DefaultDuration does not apply and 4991 no duration information is available in terms of the cues. 4993 10.5.1.2.5. CueBlockNumber Element 4995 name: CueBlockNumber 4997 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueBlockNumber" 4999 id: 0x5378 5001 maxOccurs: 1 5003 range: not 0 5005 default: 1 5007 type: uinteger 5008 definition: Number of the Block in the specified Cluster. 5010 10.5.1.2.6. CueCodecState Element 5012 name: CueCodecState 5014 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueCodecState" 5016 id: 0xEA 5018 maxOccurs: 1 5020 default: 0 5022 type: uinteger 5024 minver: 2 5026 definition: The Segment Position of the Codec State corresponding to 5027 this Cue Element. 0 means that the data is taken from the initial 5028 Track Entry. 5030 10.5.1.2.7. CueReference Element 5032 name: CueReference 5034 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueReference" 5036 id: 0xDB 5038 type: master 5040 minver: 2 5042 definition: The Clusters containing the referenced Blocks. 5044 10.5.1.2.7.1. CueRefTime Element 5046 name: CueRefTime 5048 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefT 5049 ime" 5051 id: 0x96 5053 minOccurs: 1 5055 maxOccurs: 1 5056 type: uinteger 5058 minver: 2 5060 definition: Timestamp of the referenced Block. 5062 10.5.1.2.7.2. CueRefCluster Element 5064 name: CueRefCluster 5066 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefC 5067 luster" 5069 id: 0x97 5071 minOccurs: 1 5073 maxOccurs: 1 5075 type: uinteger 5077 minver: 0 5079 maxver: 0 5081 definition: The Segment Position of the Cluster containing the 5082 referenced Block. 5084 10.5.1.2.7.3. CueRefNumber Element 5086 name: CueRefNumber 5088 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefN 5089 umber" 5091 id: 0x535F 5093 maxOccurs: 1 5095 range: not 0 5097 default: 1 5099 type: uinteger 5101 minver: 0 5103 maxver: 0 5104 definition: Number of the referenced Block of Track X in the 5105 specified Cluster. 5107 10.5.1.2.7.4. CueRefCodecState Element 5109 name: CueRefCodecState 5111 path: "\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueRefC 5112 odecState" 5114 id: 0xEB 5116 maxOccurs: 1 5118 default: 0 5120 type: uinteger 5122 minver: 0 5124 maxver: 0 5126 definition: The Segment Position of the Codec State corresponding to 5127 this referenced Element. 0 means that the data is taken from the 5128 initial Track Entry. 5130 10.6. Attachments Element 5132 name: Attachments 5134 path: "\Segment\Attachments" 5136 id: 0x1941A469 5138 maxOccurs: 1 5140 type: master 5142 definition: Contain attached files. 5144 10.6.1. AttachedFile Element 5146 name: AttachedFile 5148 path: "\Segment\Attachments\AttachedFile" 5150 id: 0x61A7 5151 minOccurs: 1 5153 type: master 5155 definition: An attached file. 5157 10.6.1.1. FileDescription Element 5159 name: FileDescription 5161 path: "\Segment\Attachments\AttachedFile\FileDescription" 5163 id: 0x467E 5165 maxOccurs: 1 5167 type: utf-8 5169 definition: A human-friendly name for the attached file. 5171 10.6.1.2. FileName Element 5173 name: FileName 5175 path: "\Segment\Attachments\AttachedFile\FileName" 5177 id: 0x466E 5179 minOccurs: 1 5181 maxOccurs: 1 5183 type: utf-8 5185 definition: Filename of the attached file. 5187 10.6.1.3. FileMimeType Element 5189 name: FileMimeType 5191 path: "\Segment\Attachments\AttachedFile\FileMimeType" 5193 id: 0x4660 5195 minOccurs: 1 5197 maxOccurs: 1 5198 type: string 5200 definition: MIME type of the file. 5202 10.6.1.4. FileData Element 5204 name: FileData 5206 path: "\Segment\Attachments\AttachedFile\FileData" 5208 id: 0x465C 5210 minOccurs: 1 5212 maxOccurs: 1 5214 type: binary 5216 definition: The data of the file. 5218 10.6.1.5. FileUID Element 5220 name: FileUID 5222 path: "\Segment\Attachments\AttachedFile\FileUID" 5224 id: 0x46AE 5226 minOccurs: 1 5228 maxOccurs: 1 5230 range: not 0 5232 type: uinteger 5234 definition: Unique ID representing the file, as random as possible. 5236 10.6.1.6. FileReferral Element 5238 name: FileReferral 5240 path: "\Segment\Attachments\AttachedFile\FileReferral" 5242 id: 0x4675 5244 maxOccurs: 1 5245 type: binary 5247 minver: 0 5249 maxver: 0 5251 definition: A binary value that a track/codec can refer to when the 5252 attachment is needed. 5254 10.6.1.7. FileUsedStartTime Element 5256 name: FileUsedStartTime 5258 path: "\Segment\Attachments\AttachedFile\FileUsedStartTime" 5260 id: 0x4661 5262 maxOccurs: 1 5264 type: uinteger 5266 minver: 0 5268 maxver: 0 5270 definition: DivX font extension 5272 10.6.1.8. FileUsedEndTime Element 5274 name: FileUsedEndTime 5276 path: "\Segment\Attachments\AttachedFile\FileUsedEndTime" 5278 id: 0x4662 5280 maxOccurs: 1 5282 type: uinteger 5284 minver: 0 5286 maxver: 0 5288 definition: DivX font extension 5290 10.7. Chapters Element 5292 name: Chapters 5294 path: "\Segment\Chapters" 5296 id: 0x1043A770 5298 maxOccurs: 1 5300 type: master 5302 recurring: 1 5304 definition: A system to define basic menus and partition data. For 5305 more detailed information, look at the Chapters explanation in 5306 Section 12. 5308 10.7.1. EditionEntry Element 5310 name: EditionEntry 5312 path: "\Segment\Chapters\EditionEntry" 5314 id: 0x45B9 5316 minOccurs: 1 5318 type: master 5320 definition: Contains all information about a Segment edition. 5322 10.7.1.1. EditionUID Element 5324 name: EditionUID 5326 path: "\Segment\Chapters\EditionEntry\EditionUID" 5328 id: 0x45BC 5330 maxOccurs: 1 5332 range: not 0 5334 type: uinteger 5336 definition: A unique ID to identify the edition. It's useful for 5337 tagging an edition. 5339 10.7.1.2. EditionFlagHidden Element 5341 name: EditionFlagHidden 5343 path: "\Segment\Chapters\EditionEntry\EditionFlagHidden" 5345 id: 0x45BD 5347 minOccurs: 1 5349 maxOccurs: 1 5351 range: 0-1 5353 default: 0 5355 type: uinteger 5357 definition: If an edition is hidden (1), it SHOULD NOT be available 5358 to the user interface (but still to Control Tracks; see 5359 Section 12.1.1 on Chapter flags). (1 bit) 5361 10.7.1.3. EditionFlagDefault Element 5363 name: EditionFlagDefault 5365 path: "\Segment\Chapters\EditionEntry\EditionFlagDefault" 5367 id: 0x45DB 5369 minOccurs: 1 5371 maxOccurs: 1 5373 range: 0-1 5375 default: 0 5377 type: uinteger 5379 definition: If a flag is set (1) the edition SHOULD be used as the 5380 default one. (1 bit) 5382 10.7.1.4. EditionFlagOrdered Element 5384 name: EditionFlagOrdered 5386 path: "\Segment\Chapters\EditionEntry\EditionFlagOrdered" 5387 id: 0x45DD 5389 maxOccurs: 1 5391 range: 0-1 5393 default: 0 5395 type: uinteger 5397 definition: Specify if the chapters can be defined multiple times 5398 and the order to play them is enforced. (1 bit) 5400 10.7.1.5. ChapterAtom Element 5402 name: ChapterAtom 5404 path: "\Segment\Chapters\EditionEntry\+ChapterAtom" 5406 id: 0xB6 5408 minOccurs: 1 5410 type: master 5412 recursive: 1 5414 definition: Contains the atom information to use as the chapter atom 5415 (apply to all tracks). 5417 10.7.1.5.1. ChapterUID Element 5419 name: ChapterUID 5421 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterUID" 5423 id: 0x73C4 5425 minOccurs: 1 5427 maxOccurs: 1 5429 range: not 0 5431 type: uinteger 5433 definition: A unique ID to identify the Chapter. 5435 10.7.1.5.2. ChapterStringUID Element 5437 name: ChapterStringUID 5439 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterStringUID" 5441 id: 0x5654 5443 maxOccurs: 1 5445 type: utf-8 5447 minver: 3 5449 definition: A unique string ID to identify the Chapter. Use for 5450 WebVTT cue identifier storage. 5452 10.7.1.5.3. ChapterTimeStart Element 5454 name: ChapterTimeStart 5456 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTimeStart" 5458 id: 0x91 5460 minOccurs: 1 5462 maxOccurs: 1 5464 type: uinteger 5466 definition: Timestamp of the start of Chapter (not scaled). 5468 10.7.1.5.4. ChapterTimeEnd Element 5470 name: ChapterTimeEnd 5472 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTimeEnd" 5474 id: 0x92 5476 maxOccurs: 1 5478 type: uinteger 5480 definition: Timestamp of the end of Chapter (timestamp excluded, not 5481 scaled). 5483 10.7.1.5.5. ChapterFlagHidden Element 5485 name: ChapterFlagHidden 5487 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterFlagHidden 5488 " 5490 id: 0x98 5492 minOccurs: 1 5494 maxOccurs: 1 5496 range: 0-1 5498 default: 0 5500 type: uinteger 5502 definition: If a chapter is hidden (1), it SHOULD NOT be available 5503 to the user interface (but still to Control Tracks; see 5504 Section 12.1.1 on Chapter flags). (1 bit) 5506 10.7.1.5.6. ChapterFlagEnabled Element 5508 name: ChapterFlagEnabled 5510 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterFlagEnable 5511 d" 5513 id: 0x4598 5515 minOccurs: 1 5517 maxOccurs: 1 5519 range: 0-1 5521 default: 1 5523 type: uinteger 5525 definition: Specify whether the chapter is enabled. It can be 5526 enabled/disabled by a Control Track. When disabled, the movie 5527 SHOULD skip all the content between the TimeStart and TimeEnd of 5528 this chapter; see Section 12.1.1 on Chapter flags. (1 bit) 5530 10.7.1.5.7. ChapterSegmentUID Element 5532 name: ChapterSegmentUID 5534 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterSegmentUID 5535 " 5537 id: 0x6E67 5539 minOccurs: see implementation notes 5541 maxOccurs: 1 5543 range: >0 5545 type: binary 5547 definition: The SegmentUID of another Segment to play during this 5548 chapter. 5550 implementation notes: 5552 +===========+=============================================+ 5553 | attribute | note | 5554 +===========+=============================================+ 5555 | minOccurs | ChapterSegmentUID MUST be set (minOccurs=1) | 5556 | | if ChapterSegmentEditionUID is used. | 5557 +-----------+---------------------------------------------+ 5559 Table 40 5561 10.7.1.5.8. ChapterSegmentEditionUID Element 5563 name: ChapterSegmentEditionUID 5565 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterSegmentEdi 5566 tionUID" 5568 id: 0x6EBC 5570 maxOccurs: 1 5572 range: not 0 5574 type: uinteger 5576 definition: The EditionUID to play from the Segment linked in 5577 ChapterSegmentUID. If ChapterSegmentEditionUID is undeclared, 5578 then no Edition of the linked Segment is used. 5580 10.7.1.5.9. ChapterPhysicalEquiv Element 5582 name: ChapterPhysicalEquiv 5584 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterPhysicalEq 5585 uiv" 5587 id: 0x63C3 5589 maxOccurs: 1 5591 type: uinteger 5593 definition: Specify the physical equivalent of this ChapterAtom like 5594 "DVD" (60) or "SIDE" (50); see Section 6.2.2 for a complete list 5595 of values. 5597 10.7.1.5.10. ChapterTrack Element 5599 name: ChapterTrack 5601 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTrack" 5603 id: 0x8F 5605 maxOccurs: 1 5607 type: master 5609 definition: List of tracks on which the chapter applies. If this 5610 Element is not present, all tracks apply 5612 10.7.1.5.10.1. ChapterTrackUID Element 5614 name: ChapterTrackUID 5616 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterTrack\Chap 5617 terTrackUID" 5619 id: 0x89 5621 minOccurs: 1 5623 range: not 0 5624 type: uinteger 5626 definition: UID of the Track to apply this chapter to. In the 5627 absence of a control track, choosing this chapter will select the 5628 listed Tracks and deselect unlisted tracks. Absence of this 5629 Element indicates that the Chapter SHOULD be applied to any 5630 currently used Tracks. 5632 10.7.1.5.11. ChapterDisplay Element 5634 name: ChapterDisplay 5636 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay" 5638 id: 0x80 5640 type: master 5642 definition: Contains all possible strings to use for the chapter 5643 display. 5645 10.7.1.5.11.1. ChapString Element 5647 name: ChapString 5649 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Ch 5650 apString" 5652 id: 0x85 5654 minOccurs: 1 5656 maxOccurs: 1 5658 type: utf-8 5660 definition: Contains the string to use as the chapter atom. 5662 10.7.1.5.11.2. ChapLanguage Element 5664 name: ChapLanguage 5666 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Ch 5667 apLanguage" 5669 id: 0x437C 5671 minOccurs: 1 5672 default: eng 5674 type: string 5676 definition: The languages corresponding to the string, in the 5677 bibliographic ISO-639-2 form. This Element MUST be ignored if the 5678 ChapLanguageIETF Element is used within the same ChapterDisplay 5679 Element. 5681 10.7.1.5.11.3. ChapLanguageIETF Element 5683 name: ChapLanguageIETF 5685 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Ch 5686 apLanguageIETF" 5688 id: 0x437D 5690 type: string 5692 minver: 4 5694 definition: Specifies the language used in the ChapString according 5695 to BCP 47 and using the IANA Language Subtag Registry. If this 5696 Element is used, then any ChapLanguage Elements used in the same 5697 ChapterDisplay MUST be ignored. 5699 10.7.1.5.11.4. ChapCountry Element 5701 name: ChapCountry 5703 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapterDisplay\Ch 5704 apCountry" 5706 id: 0x437E 5708 type: string 5710 definition: The countries corresponding to the string, same 2 octets 5711 as in Internet domains. This Element MUST be ignored if the 5712 ChapLanguageIETF Element is used within the same ChapterDisplay 5713 Element. 5715 10.7.1.5.12. ChapProcess Element 5717 name: ChapProcess 5719 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess" 5720 id: 0x6944 5722 type: master 5724 definition: Contains all the commands associated to the Atom. 5726 10.7.1.5.12.1. ChapProcessCodecID Element 5728 name: ChapProcessCodecID 5730 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapP 5731 rocessCodecID" 5733 id: 0x6955 5735 minOccurs: 1 5737 maxOccurs: 1 5739 default: 0 5741 type: uinteger 5743 definition: Contains the type of the codec used for the processing. 5744 A value of 0 means native Matroska processing (to be defined), a 5745 value of 1 means the DVD command set is used; see Section 12.2.2 5746 on DVD menus. More codec IDs can be added later. 5748 10.7.1.5.12.2. ChapProcessPrivate Element 5750 name: ChapProcessPrivate 5752 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapP 5753 rocessPrivate" 5755 id: 0x450D 5757 maxOccurs: 1 5759 type: binary 5761 definition: Some optional data attached to the ChapProcessCodecID 5762 information. For ChapProcessCodecID = 1, it is the "DVD level" 5763 equivalent; see Section 12.2.2 on DVD menus. 5765 10.7.1.5.12.3. ChapProcessCommand Element 5767 name: ChapProcessCommand 5769 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapP 5770 rocessCommand" 5772 id: 0x6911 5774 type: master 5776 definition: Contains all the commands associated to the Atom. 5778 10.7.1.5.12.4. ChapProcessTime Element 5780 name: ChapProcessTime 5782 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapP 5783 rocessCommand\ChapProcessTime" 5785 id: 0x6922 5787 minOccurs: 1 5789 maxOccurs: 1 5791 type: uinteger 5793 definition: Defines when the process command SHOULD be handled 5795 restrictions: 5797 +=======+===============================+ 5798 | value | label | 5799 +=======+===============================+ 5800 | 0 | during the whole chapter | 5801 +-------+-------------------------------+ 5802 | 1 | before starting playback | 5803 +-------+-------------------------------+ 5804 | 2 | after playback of the chapter | 5805 +-------+-------------------------------+ 5807 Table 41 5809 10.7.1.5.12.5. ChapProcessData Element 5811 name: ChapProcessData 5812 path: "\Segment\Chapters\EditionEntry\+ChapterAtom\ChapProcess\ChapP 5813 rocessCommand\ChapProcessData" 5815 id: 0x6933 5817 minOccurs: 1 5819 maxOccurs: 1 5821 type: binary 5823 definition: Contains the command information. The data SHOULD be 5824 interpreted depending on the ChapProcessCodecID value. For 5825 ChapProcessCodecID = 1, the data correspond to the binary DVD cell 5826 pre/post commands; see Section 12.2.2 on DVD menus. 5828 10.8. Tags Element 5830 name: Tags 5832 path: "\Segment\Tags" 5834 id: 0x1254C367 5836 type: master 5838 definition: Element containing metadata describing Tracks, Editions, 5839 Chapters, Attachments, or the Segment as a whole. A list of valid 5840 tags can be found in [I-D.ietf-cellar-tags]. 5842 10.8.1. Tag Element 5844 name: Tag 5846 path: "\Segment\Tags\Tag" 5848 id: 0x7373 5850 minOccurs: 1 5852 type: master 5854 definition: A single metadata descriptor. 5856 10.8.1.1. Targets Element 5858 name: Targets 5859 path: "\Segment\Tags\Tag\Targets" 5861 id: 0x63C0 5863 minOccurs: 1 5865 maxOccurs: 1 5867 type: master 5869 definition: Specifies which other elements the metadata represented 5870 by the Tag applies to. If empty or not present, then the Tag 5871 describes everything in the Segment. 5873 10.8.1.1.1. TargetTypeValue Element 5875 name: TargetTypeValue 5877 path: "\Segment\Tags\Tag\Targets\TargetTypeValue" 5879 id: 0x68CA 5881 maxOccurs: 1 5883 default: 50 5885 type: uinteger 5887 definition: A number to indicate the logical level of the target. 5889 restrictions: 5891 +=======+==========================+================================+ 5892 | value | label | documentation | 5893 +=======+==========================+================================+ 5894 | 70 | COLLECTION | The highest hierarchical level | 5895 | | | that tags can describe. | 5896 +-------+--------------------------+--------------------------------+ 5897 | 60 | EDITION / ISSUE / | A list of lower levels grouped | 5898 | | VOLUME / OPUS / | together. | 5899 | | SEASON / SEQUEL | | 5900 +-------+--------------------------+--------------------------------+ 5901 | 50 | ALBUM / OPERA / | The most common grouping level | 5902 | | CONCERT / MOVIE / | of music and video (equals to | 5903 | | EPISODE / CONCERT | an episode for TV series). | 5904 +-------+--------------------------+--------------------------------+ 5905 | 40 | PART / SESSION | When an album or episode has | 5906 | | | different logical parts. | 5907 +-------+--------------------------+--------------------------------+ 5908 | 30 | TRACK / SONG / | The common parts of an album | 5909 | | CHAPTER | or movie. | 5910 +-------+--------------------------+--------------------------------+ 5911 | 20 | SUBTRACK / PART / | Corresponds to parts of a | 5912 | | MOVEMENT / SCENE | track for audio (like a | 5913 | | | movement). | 5914 +-------+--------------------------+--------------------------------+ 5915 | 10 | SHOT | The lowest hierarchy found in | 5916 | | | music or movies. | 5917 +-------+--------------------------+--------------------------------+ 5919 Table 42 5921 10.8.1.1.2. TargetType Element 5923 name: TargetType 5925 path: "\Segment\Tags\Tag\Targets\TargetType" 5927 id: 0x63CA 5929 maxOccurs: 1 5931 type: string 5933 definition: An informational string that can be used to display the 5934 logical level of the target like "ALBUM", "TRACK", "MOVIE", 5935 "CHAPTER", etc ; see Section 6.4 of [I-D.ietf-cellar-tags]. 5937 restrictions: 5939 +============+============+ 5940 | value | label | 5941 +============+============+ 5942 | COLLECTION | COLLECTION | 5943 +------------+------------+ 5944 | EDITION | EDITION | 5945 +------------+------------+ 5946 | ISSUE | ISSUE | 5947 +------------+------------+ 5948 | VOLUME | VOLUME | 5949 +------------+------------+ 5950 | OPUS | OPUS | 5951 +------------+------------+ 5952 | SEASON | SEASON | 5953 +------------+------------+ 5954 | SEQUEL | SEQUEL | 5955 +------------+------------+ 5956 | ALBUM | ALBUM | 5957 +------------+------------+ 5958 | OPERA | OPERA | 5959 +------------+------------+ 5960 | CONCERT | CONCERT | 5961 +------------+------------+ 5962 | MOVIE | MOVIE | 5963 +------------+------------+ 5964 | EPISODE | EPISODE | 5965 +------------+------------+ 5966 | PART | PART | 5967 +------------+------------+ 5968 | SESSION | SESSION | 5969 +------------+------------+ 5970 | TRACK | TRACK | 5971 +------------+------------+ 5972 | SONG | SONG | 5973 +------------+------------+ 5974 | CHAPTER | CHAPTER | 5975 +------------+------------+ 5976 | SUBTRACK | SUBTRACK | 5977 +------------+------------+ 5978 | PART | PART | 5979 +------------+------------+ 5980 | MOVEMENT | MOVEMENT | 5981 +------------+------------+ 5982 | SCENE | SCENE | 5983 +------------+------------+ 5984 | SHOT | SHOT | 5985 +------------+------------+ 5986 Table 43 5988 10.8.1.1.3. TagTrackUID Element 5990 name: TagTrackUID 5992 path: "\Segment\Tags\Tag\Targets\TagTrackUID" 5994 id: 0x63C5 5996 default: 0 5998 type: uinteger 6000 definition: A unique ID to identify the Track(s) the tags belong to. 6001 If the value is 0 at this level, the tags apply to all tracks in 6002 the Segment. 6004 10.8.1.1.4. TagEditionUID Element 6006 name: TagEditionUID 6008 path: "\Segment\Tags\Tag\Targets\TagEditionUID" 6010 id: 0x63C9 6012 default: 0 6014 type: uinteger 6016 definition: A unique ID to identify the EditionEntry(s) the tags 6017 belong to. If the value is 0 at this level, the tags apply to all 6018 editions in the Segment. 6020 10.8.1.1.5. TagChapterUID Element 6022 name: TagChapterUID 6024 path: "\Segment\Tags\Tag\Targets\TagChapterUID" 6026 id: 0x63C4 6028 default: 0 6030 type: uinteger 6032 definition: A unique ID to identify the Chapter(s) the tags belong 6033 to. If the value is 0 at this level, the tags apply to all 6034 chapters in the Segment. 6036 10.8.1.1.6. TagAttachmentUID Element 6038 name: TagAttachmentUID 6040 path: "\Segment\Tags\Tag\Targets\TagAttachmentUID" 6042 id: 0x63C6 6044 default: 0 6046 type: uinteger 6048 definition: A unique ID to identify the Attachment(s) the tags 6049 belong to. If the value is 0 at this level, the tags apply to all 6050 the attachments in the Segment. 6052 10.8.1.2. SimpleTag Element 6054 name: SimpleTag 6056 path: "\Segment\Tags\Tag\+SimpleTag" 6058 id: 0x67C8 6060 minOccurs: 1 6062 type: master 6064 recursive: 1 6066 definition: Contains general information about the target. 6068 10.8.1.2.1. TagName Element 6070 name: TagName 6072 path: "\Segment\Tags\Tag\+SimpleTag\TagName" 6074 id: 0x45A3 6076 minOccurs: 1 6078 maxOccurs: 1 6080 type: utf-8 6081 definition: The name of the Tag that is going to be stored. 6083 10.8.1.2.2. TagLanguage Element 6085 name: TagLanguage 6087 path: "\Segment\Tags\Tag\+SimpleTag\TagLanguage" 6089 id: 0x447A 6091 minOccurs: 1 6093 maxOccurs: 1 6095 default: und 6097 type: string 6099 definition: Specifies the language of the tag specified, in the 6100 Matroska languages form; see Section 6.2.1 on language codes. 6101 This Element MUST be ignored if the TagLanguageIETF Element is 6102 used within the same SimpleTag Element. 6104 10.8.1.2.3. TagLanguageIETF Element 6106 name: TagLanguageIETF 6108 path: "\Segment\Tags\Tag\+SimpleTag\TagLanguageIETF" 6110 id: 0x447B 6112 maxOccurs: 1 6114 type: string 6116 minver: 4 6118 definition: Specifies the language used in the TagString according 6119 to BCP 47 and using the IANA Language Subtag Registry. If this 6120 Element is used, then any TagLanguage Elements used in the same 6121 SimpleTag MUST be ignored. 6123 10.8.1.2.4. TagDefault Element 6125 name: TagDefault 6127 path: "\Segment\Tags\Tag\+SimpleTag\TagDefault" 6128 id: 0x4484 6130 minOccurs: 1 6132 maxOccurs: 1 6134 range: 0-1 6136 default: 1 6138 type: uinteger 6140 definition: A boolean value to indicate if this is the default/ 6141 original language to use for the given tag. 6143 10.8.1.2.5. TagString Element 6145 name: TagString 6147 path: "\Segment\Tags\Tag\+SimpleTag\TagString" 6149 id: 0x4487 6151 maxOccurs: 1 6153 type: utf-8 6155 definition: The value of the Tag. 6157 10.8.1.2.6. TagBinary Element 6159 name: TagBinary 6161 path: "\Segment\Tags\Tag\+SimpleTag\TagBinary" 6163 id: 0x4485 6165 maxOccurs: 1 6167 type: binary 6169 definition: The values of the Tag, if it is binary. Note that this 6170 cannot be used in the same SimpleTag as TagString. 6172 11. Matroska Element Ordering 6174 Except for the "EBML Header" and the "CRC-32 Element", the EBML 6175 specification does not require any particular storage order for 6176 "Elements". The Matroska specification however defines mandates and 6177 recommendations for ordering certain "Elements" in order to 6178 facilitate better playback, seeking, and editing efficiency. This 6179 section describes and offers rationale for ordering requirements and 6180 recommendations for Matroska. 6182 11.1. Top-Level Elements 6184 The "Info Element" is the only REQUIRED "Top-Level Element" in a 6185 Matroska file. To be playable, Matroska MUST also contain at least 6186 one "Tracks Element" and "Cluster Element". The first "Info Element" 6187 and the first "Tracks Element" MUST either be stored before the first 6188 "Cluster Element" or both SHALL be referenced by a "SeekHead Element" 6189 occurring before the first "Cluster Element". 6191 It is possible to edit a Matroska file after it has been created. 6192 For example, chapters, tags, or attachments can be added. When new 6193 "Top-Level Elements" are added to a Matroska file, the "SeekHead" 6194 Element(s) MUST be updated so that the "SeekHead" Element(s) itemize 6195 the identity and position of all "Top-Level Elements". Editing, 6196 removing, or adding "Elements" to a Matroska file often requires that 6197 some existing "Elements" be voided or extended; therefore, it is 6198 RECOMMENDED to use "Void Elements" as padding in between "Top-Level 6199 Elements". 6201 11.2. CRC-32 6203 As noted by the EBML specification, if a "CRC-32 Element" is used, 6204 then the "CRC-32 Element" MUST be the first ordered "Element" within 6205 its "Parent Element". The Matroska specification recommends that 6206 "CRC-32 Elements" SHOULD NOT be used as an immediate "Child Element" 6207 of the "Segment Element"; however all "Top-Level Elements" of an 6208 "EBML Document" SHOULD include a "CRC-32 Element" as a "Child 6209 Element". 6211 11.3. SeekHead 6213 If used, the first "SeekHead Element" SHOULD be the first non-"CRC-32 6214 Child Element" of the "Segment Element". If a second "SeekHead 6215 Element" is used, then the first "SeekHead Element" MUST reference 6216 the identity and position of the second "SeekHead". Additionally, 6217 the second "SeekHead Element" MUST only reference "Cluster" Elements 6218 and not any other "Top-Level Element" already contained within the 6219 first "SeekHead Element". The second "SeekHead Element" MAY be 6220 stored in any order relative to the other "Top-Level Elements". 6221 Whether one or two "SeekHead Element(s)" are used, the "SeekHead 6222 Element(s)" MUST collectively reference the identity and position of 6223 all "Top-Level Elements" except for the first "SeekHead Element". 6225 It is RECOMMENDED that the first "SeekHead Element" be followed by a 6226 "Void Element" to allow for the "SeekHead Element" to be expanded to 6227 cover new "Top-Level Elements" that could be added to the Matroska 6228 file, such as "Tags", "Chapters", and "Attachments Elements". 6230 11.4. Cues (index) 6232 The "Cues Element" is RECOMMENDED to optimize seeking access in 6233 Matroska. It is programmatically simpler to add the "Cues Element" 6234 after all "Cluster Elements" have been written because this does not 6235 require a prediction of how much space to reserve before writing the 6236 "Cluster Elements". However, storing the "Cues Element" before the 6237 "Cluster Elements" can provide some seeking advantages. If the "Cues 6238 Element" is present, then it SHOULD either be stored before the first 6239 "Cluster Element" or be referenced by a "SeekHead Element". 6241 11.5. Info 6243 The first "Info Element" SHOULD occur before the first "Tracks 6244 Element" and first "Cluster Element" except when referenced by a 6245 "SeekHead Element". 6247 11.6. Chapters Element 6249 The "Chapters Element" SHOULD be placed before the "Cluster 6250 Element(s)". The "Chapters Element" can be used during playback even 6251 if the user does not need to seek. It immediately gives the user 6252 information about what section is being read and what other sections 6253 are available. In the case of Ordered Chapters it is RECOMMENDED to 6254 evaluate the logical linking even before playing. The "Chapters 6255 Element" SHOULD be placed before the first "Tracks Element" and after 6256 the first "Info Element". 6258 11.7. Attachments 6260 The "Attachments Element" is not intended to be used by default when 6261 playing the file, but could contain information relevant to the 6262 content, such as cover art or fonts. Cover art is useful even before 6263 the file is played and fonts could be needed before playback starts 6264 for initialization of subtitles. The "Attachments Element" MAY be 6265 placed before the first "Cluster Element"; however if the 6266 "Attachments Element" is likely to be edited, then it SHOULD be 6267 placed after the last "Cluster Element". 6269 11.8. Tags 6271 The "Tags Element" is most subject to changes after the file was 6272 originally created. For easier editing, the "Tags Element" SHOULD be 6273 placed at the end of the "Segment Element", even after the 6274 "Attachments Element". On the other hand, it is inconvenient to have 6275 to seek in the "Segment" for tags, especially for network streams. 6276 So it's better if the "Tags Element" is found early in the stream. 6277 When editing the "Tags Element", the original "Tags Element" at the 6278 beginning can be overwritten with a "Void Element" and a new "Tags 6279 Element" written at the end of the "Segment Element". The file size 6280 will only marginally change. 6282 11.9. Optimum layout from a muxer 6284 * SeekHead 6286 * Info 6288 * Tracks 6290 * Chapters 6292 * Attachments 6294 * Tags 6296 * Clusters 6298 * Cues 6300 11.10. Optimum layout after editing tags 6302 * SeekHead 6304 * Info 6306 * Tracks 6308 * Chapters 6310 * Attachments 6312 * Void 6314 * Clusters 6316 * Cues 6317 * Tags 6319 11.11. Optimum layout with Cues at the front 6321 * SeekHead 6323 * Info 6325 * Tracks 6327 * Chapters 6329 * Attachments 6331 * Tags 6333 * Cues 6335 * Clusters 6337 11.12. Cluster Timestamp 6339 The "Timestamp Element" MUST occur as in storage order before any 6340 "SimpleBlock", "BlockGroup", or "EncryptedBlock", within the "Cluster 6341 Element". 6343 12. Chapters 6345 12.1. Edition and Chapter Flags 6347 12.1.1. Chapter Flags 6349 Two "Chapter Flags" are defined to describe the behavior of the 6350 "ChapterAtom Element": "ChapterFlagHidden" and "ChapterFlagEnabled". 6352 If a "ChapterAtom Element" is the "Child Element" of another 6353 "ChapterAtom Element" with a "Chapter Flag" set to "true", then the 6354 "Child ChapterAtom Element" MUST be interpreted as having its same 6355 "Chapter Flag" set to "true". If a "ChapterAtom Element" is the 6356 "Child Element" of another "ChapterAtom Element" with a "Chapter 6357 Flag" set to "false", or if the "ChapterAtom Element" does not have a 6358 "ChapterAtom Element" as its "Parent Element", then it MUST be 6359 interpreted according to its own "Chapter Flag". 6361 As an example, consider a "Parent ChapterAtom Element" that has its 6362 "ChapterFlagHidden" set to "true" and also contains two child 6363 "ChapterAtoms", the first with "ChapterFlagHidden" set to "true" and 6364 the second with "ChapterFlagHidden" either set to "false" or not 6365 present at all (in which case the default value of the Element 6366 applies, which is "false"). Since the parent "ChapterAtom" has its 6367 "ChapterFlagHidden" set to "true", all of its children "ChapterAtoms" 6368 MUST also be interpreted as if their "ChapterFlagHidden" is also set 6369 to "true". However, if a "Control Track" toggles the parent's 6370 "ChapterFlagHidden" flag to "false", then only the parent 6371 "ChapterAtom" and its second child "ChapterAtom" MUST be interpreted 6372 as if "ChapterFlagHidden" is set to "false". The first child 6373 "ChapterAtom", which has the "ChapterFlagHidden" flag set to "true", 6374 retains its value until its value is toggled to "false" by a "Control 6375 Track". 6377 12.1.2. Edition Flags 6379 Three "Edition Flags" are defined to describe the behavior of the 6380 "EditionEntry Element": "EditionFlagHidden", "EditionFlagDefault", 6381 and "EditionFlagOrdered". 6383 12.1.2.1. EditionFlagHidden 6385 The "EditionFlagHidden Flag" behaves similarly to the 6386 "ChapterFlagHidden Flag": if "EditionFlagHidden" is set to "true", 6387 its "Child ChapterAtoms Elements" MUST also be interpreted as if 6388 their "ChapterFlagHidden" is also set to "true", regardless of their 6389 own "ChapterFlagHidden Flags". If "EditionFlagHidden" is toggled by 6390 a "Control Track" to "false", the "ChapterFlagHidden Flags" of the 6391 "Child ChapterAtoms Elements" SHALL determine whether the 6392 "ChapterAtom" is hidden or not. 6394 12.1.2.2. EditionFlagDefault 6396 It is RECOMMENDED that no more than one "Edition" have an 6397 "EditionFlagDefault Flag" set to "true". The first "Edition" with 6398 both the "EditionFlagDefault Flag" set to "true" and the 6399 "EditionFlagHidden Flag" set to "false" is the Default Edition. When 6400 all "EditionFlagDefault Flags" are set to "false", then the first 6401 "Edition" with the "EditionFlagHidden Flag" set to "false" is the 6402 Default Edition. The Default Edition is the edition that should be 6403 used for playback by default. 6405 12.1.2.3. EditionFlagOrdered 6407 The "EditionFlagOrdered Flag" is a significant feature as it enables 6408 an "Edition" of "Ordered Chapters" which defines and arranges a 6409 virtual timeline rather than simply labeling points within the 6410 timeline. For example, with "Editions" of "Ordered Chapters" a 6411 single "Matroska file" can present multiple edits of a film without 6412 duplicating content. Alternatively, if a videotape is digitized in 6413 full, one "Ordered Edition" could present the full content (including 6414 colorbars, countdown, slate, a feature presentation, and black 6415 frames), while another "Edition" of "Ordered Chapters" can use 6416 "Chapters" that only mark the intended presentation with the 6417 colorbars and other ancillary visual information excluded. If an 6418 "Edition" of "Ordered Chapters" is enabled, then the "Matroska 6419 Player" MUST play those Chapters in their stored order from the 6420 timestamp marked in the "ChapterTimeStart Element" to the timestamp 6421 marked in to "ChapterTimeEnd Element". 6423 If the "EditionFlagOrdered Flag" is set to "false", "Simple Chapters" 6424 are used and only the "ChapterTimeStart" of a "Chapter" is used as 6425 chapter mark to jump to the predefined point in the timeline. With 6426 "Simple Chapters", a "Matroska Player" MUST ignore certain "Chapter 6427 Elements". All these elements are now informational only. 6429 The following list shows the different usage of "Chapter Elements" 6430 between an ordered and non-ordered "Edition". 6432 +====================================+=======+======+ 6433 | Chapter elements / ordered Edition | False | True | 6434 +====================================+=======+======+ 6435 | ChapterUID | X | X | 6436 +------------------------------------+-------+------+ 6437 | ChapterStringUID | X | X | 6438 +------------------------------------+-------+------+ 6439 | ChapterTimeStart | X | X | 6440 +------------------------------------+-------+------+ 6441 | ChapterTimeEnd | - | X | 6442 +------------------------------------+-------+------+ 6443 | ChapterFlagHidden | X | X | 6444 +------------------------------------+-------+------+ 6445 | ChapterFlagEnabled | X | X | 6446 +------------------------------------+-------+------+ 6447 | ChapterSegmentUID | - | X | 6448 +------------------------------------+-------+------+ 6449 | ChapterSegmentEditionUID | - | X | 6450 +------------------------------------+-------+------+ 6451 | ChapterPhysicalEquiv | X | X | 6452 +------------------------------------+-------+------+ 6453 | ChapterTrack | - | X | 6454 +------------------------------------+-------+------+ 6455 | ChapterDisplay | X | X | 6456 +------------------------------------+-------+------+ 6457 | ChapProcess | - | X | 6458 +------------------------------------+-------+------+ 6460 Table 44 6462 Furthermore there are other EBML "Elements" which could be used if 6463 the "EditionFlagOrdered Flag" is set to "true". 6465 +==================================+=======+======+ 6466 | Other elements / ordered Edition | False | True | 6467 +==================================+=======+======+ 6468 | Info/SegmentFamily | - | X | 6469 +----------------------------------+-------+------+ 6470 | Info/ChapterTranslate | - | X | 6471 +----------------------------------+-------+------+ 6472 | Track/TrackTranslate | - | X | 6473 +----------------------------------+-------+------+ 6475 Table 45 6477 These other "Elements" belong to the Matroska DVD menu system and are 6478 only used when the "ChapProcessCodecID Element" is set to 1. 6480 12.1.2.3.1. Ordered-Edition and Matroska Segment-Linking 6482 * Hard Linking: "Ordered-Chapters" supersedes the "Hard Linking". 6484 * Soft Linking: In this complex system "Ordered Chapters" are 6485 REQUIRED and a "Chapter CODEC" MUST interpret the "ChapProcess" of 6486 all chapters. 6488 * Medium Linking: "Ordered Chapters" are used in a normal way and 6489 can be combined with the "ChapterSegmentUID" element which 6490 establishes a link to another Segment. 6492 See Section 25 on the Linked Segments for more information about 6493 "Hard Linking", "Soft Linking", and "Medium Linking". 6495 12.1.3. ChapterSegmentUID 6497 The "ChapterSegmentUID" is a binary value and the base element to set 6498 up a "Linked Chapter" in 2 variations: the Linked-Duration linking 6499 and the Linked-Edition linking. For both variations, the following 3 6500 conditions MUST be met: 6502 1. The "EditionFlagOrdered Flag" MUST be true. 6504 2. The "ChapterSegmentUID" MUST NOT be the "SegmentUID" of its own 6505 "Segment". 6507 3. The linked Segments MUST BE in the same folder. 6509 12.1.3.1. Variation 1: Linked-Duration 6511 Two more conditions MUST be met: 6513 1. "ChapterTimeStart" and "ChapterTimeEnd" timestamps MUST be in the 6514 range of the linked Segment duration. 6516 2. "ChapterSegmentEditionUID" MUST be not set. 6518 A "Matroska Player" MUST play the content of the linked Segment from 6519 the "ChapterTimeStart" until "ChapterTimeEnd" timestamp. 6521 12.1.3.2. Variation 2: Linked-Edition 6523 When the "ChapterSegmentEditionUID" is set to a valid "EditionUID" 6524 from the linked Segment. A "Matroska Player" MUST play these linked 6525 "Edition". 6527 12.2. Menu features 6529 The menu features are handled like a _chapter codec_. That means each 6530 codec has a type, some private data and some data in the chapters. 6532 The type of the menu system is defined by the "ChapProcessCodecID" 6533 parameter. For now, only 2 values are supported : 0 matroska script, 6534 1 menu borrowed from the DVD. he private data depend on the type of 6535 menu system (stored in ChapProcessPrivate), idem for the data in the 6536 chapters (stored in ChapProcessData). 6538 12.2.1. Matroska Script (0) 6540 This is the case when "ChapProcessCodecID" = 0. This is a script 6541 language build for Matroska purposes. The inspiration comes from 6542 ActionScript, javascript and other similar scripting languages. The 6543 commands are stored as text commands, in UTF-8. The syntax is C 6544 like, with commands spanned on many lines, each terminating with a 6545 ";". You can also include comments at the end of lines with "//" or 6546 comment many lines using "/* */". The scripts are stored in 6547 ChapProcessData. For the moment ChapProcessPrivate is not used. 6549 The one and only command existing for the moment is "GotoAndPlay( 6550 ChapterUID );". As the same suggests, it means that, when this 6551 command is encountered, the "Matroska Player" SHOULD jump to the 6552 "Chapter" specified by the UID and play it. 6554 12.2.2. DVD menu (1) 6556 This is the case when "ChapProcessCodecID" = 1. Each level of a 6557 chapter corresponds to a logical level in the DVD system that is 6558 stored in the first octet of the ChapProcessPrivate. This DVD 6559 hierarchy is as follows: 6561 +====================+======+===========+==========+=============+ 6562 | ChapProcessPrivate | DVD | Hierarchy | Commands | Comment | 6563 | | Name | | Possible | | 6564 +====================+======+===========+==========+=============+ 6565 | 0x30 | SS | DVD | - | First Play, | 6566 | | | domain | | Video | 6567 | | | | | Manager, | 6568 | | | | | Video Title | 6569 +--------------------+------+-----------+----------+-------------+ 6570 | 0x2A | LU | Language | - | Contains | 6571 | | | Unit | | only PGCs | 6572 +--------------------+------+-----------+----------+-------------+ 6573 | 0x28 | TT | Title | - | Contains | 6574 | | | | | only PGCs | 6575 +--------------------+------+-----------+----------+-------------+ 6576 | 0x20 | PGC | Program | * | | 6577 | | | Group | | | 6578 | | | Chain | | | 6579 | | | (PGC) | | | 6580 +--------------------+------+-----------+----------+-------------+ 6581 | 0x18 | PG | Program 1 | - | | 6582 | | | / Program | | | 6583 | | | 2 / | | | 6584 | | | Program 3 | | | 6585 +--------------------+------+-----------+----------+-------------+ 6586 | 0x10 | PTT | Part Of | - | Equivalent | 6587 | | | Title 1 / | | to the | 6588 | | | Part Of | | chapters on | 6589 | | | Title 2 | | the sleeve. | 6590 +--------------------+------+-----------+----------+-------------+ 6591 | 0x08 | CN | Cell 1 / | - | | 6592 | | | Cell 2 / | | | 6593 | | | Cell 3 / | | | 6594 | | | Cell 4 / | | | 6595 | | | Cell 5 / | | | 6596 | | | Cell 6 | | | 6597 +--------------------+------+-----------+----------+-------------+ 6599 Table 46 6601 You can also recover wether a Segment is a Video Manager (VMG), Video 6602 Title Set (VTS) or Video Title Set Menu (VTSM) from the 6603 ChapterTranslateID element found in the Segment Info. This field 6604 uses 2 octets as follows: 6606 1. Domain Type: 0 for VMG, the domain number for VTS and VTSM 6608 2. Domain Value: 0 for VMG and VTSM, 1 for the VTS source. 6610 For instance, the menu part from VTS_01_0.VOB would be coded [1,0] 6611 and the content part from VTS_02_3.VOB would be [2,1]. The VMG is 6612 always [0,0] 6614 The following octets of ChapProcessPrivate are as follows: 6616 +=========+======+=================================================+ 6617 | Octet 1 | DVD | Following Octets | 6618 | | Name | | 6619 +=========+======+=================================================+ 6620 | 0x30 | SS | Domain name code (1: 0x00= First play, 0xC0= | 6621 | | | VMG, 0x40= VTSM, 0x80= VTS) + VTS(M) number (2) | 6622 +---------+------+-------------------------------------------------+ 6623 | 0x2A | LU | Language code (2) + Language extension (1) | 6624 +---------+------+-------------------------------------------------+ 6625 | 0x28 | TT | global Title number (2) + corresponding TTN of | 6626 | | | the VTS (1) | 6627 +---------+------+-------------------------------------------------+ 6628 | 0x20 | PGC | PGC number (2) + Playback Type (1) + Disabled | 6629 | | | User Operations (4) | 6630 +---------+------+-------------------------------------------------+ 6631 | 0x18 | PG | Program number (2) | 6632 +---------+------+-------------------------------------------------+ 6633 | 0x10 | PTT | PTT-chapter number (1) | 6634 +---------+------+-------------------------------------------------+ 6635 | 0x08 | CN | Cell number [VOB ID(2)][Cell ID(1)][Angle | 6636 | | | Num(1)] | 6637 +---------+------+-------------------------------------------------+ 6639 Table 47 6641 If the level specified in ChapProcessPrivate is a PGC (0x20), there 6642 is an octet called the Playback Type, specifying the kind of PGC 6643 defined: 6645 * 0x00: entry only/basic PGC 6647 * 0x82: Title+Entry Menu (only found in the Video Manager domain) 6648 * 0x83: Root Menu (only found in the VTSM domain) 6650 * 0x84: Subpicture Menu (only found in the VTSM domain) 6652 * 0x85: Audio Menu (only found in the VTSM domain) 6654 * 0x86: Angle Menu (only found in the VTSM domain) 6656 * 0x87: Chapter Menu (only found in the VTSM domain) 6658 The next 4 following octets correspond to the User Operation flags 6659 (http://dvd.sourceforge.net/dvdinfo/uops.html) in the standard PGC. 6660 When a bit is set, the command SHOULD be disabled. 6662 ChapProcessData contains the pre/post/cell commands in binary format 6663 as there are stored on a DVD. There is just an octet preceding these 6664 data to specify the number of commands in the element. As follows: 6665 [# of commands(1)][command 1 (8)][command 2 (8)][command 3 (8)]. 6667 More information on the DVD commands and format on DVD-replica 6668 (http://www.dvd-replica.com/DVD/), where we got most of the info 6669 about it. You can also get information on DVD from the DVDinfo 6670 project (http://dvd.sourceforge.net/dvdinfo/). 6672 12.3. Example 1 : basic chaptering 6674 In this example a movie is split in different chapters. It could 6675 also just be an audio file (album) on which each track corresponds to 6676 a chapter. 6678 * 00000ms - 05000ms : Intro 6680 * 05000ms - 25000ms : Before the crime 6682 * 25000ms - 27500ms : The crime 6684 * 27500ms - 38000ms : The killer arrested 6686 * 38000ms - 43000ms : Credits 6688 This would translate in the following matroska form : 6690 6691 6692 16603393396715046047 6693 6694 1193046 6695 0 6696 5000000000 6697 6698 Intro 6699 eng 6700 6701 0 6702 1 6703 6704 6705 2311527 6706 5000000000 6707 25000000000 6708 6709 Before the crime 6710 eng 6711 6712 6713 Avant le crime 6714 fra 6715 6716 0 6717 1 6718 6719 6720 3430008 6721 25000000000 6722 27500000000 6723 6724 The crime 6725 eng 6726 6727 6728 Le crime 6729 fra 6730 6731 0 6732 1 6733 6734 6735 4548489 6736 27500000000 6737 38000000000 6738 6739 After the crime 6740 eng 6741 6742 6743 Après le crime 6744 fra 6745 6746 0 6747 1 6748 6749 6750 5666960 6751 38000000000 6752 43000000000 6753 6754 Credits 6755 eng 6756 6757 6758 Générique 6759 fra 6760 6761 0 6762 1 6763 6764 0 6765 0 6766 6767 6769 12.4. Example 2 : nested chapters 6771 In this example an (existing) album is split into different chapters, 6772 and one of them contain another splitting. 6774 12.4.1. The Micronauts "Bleep To Bleep" 6776 * 00:00 - 12:28 : Baby Wants To Bleep/Rock 6778 - 00:00 - 04:38 : Baby wants to bleep (pt.1) 6780 - 04:38 - 07:12 : Baby wants to rock 6782 - 07:12 - 10:33 : Baby wants to bleep (pt.2) 6784 - 10:33 - 12:28 : Baby wants to bleep (pt.3) 6786 * 12:30 - 19:38 : Bleeper_O+2 6788 * 19:40 - 22:20 : Baby wants to bleep (pt.4) 6790 * 22:22 - 25:18 : Bleep to bleep 6791 * 25:20 - 33:35 : Baby wants to bleep (k) 6793 * 33:37 - 44:28 : Bleeper 6795 6796 6797 1281690858003401414 6798 6799 1 6800 0 6801 748000000 6802 6803 Baby wants to Bleep/Rock 6804 eng 6805 6806 6807 2 6808 0 6809 278000000 6810 6811 Baby wants to bleep (pt.1) 6812 eng 6813 6814 0 6815 1 6816 6817 6818 3 6819 278000000 6820 432000000 6821 6822 Baby wants to rock 6823 eng 6824 6825 0 6826 1 6827 6828 6829 4 6830 432000000 6831 633000000 6832 6833 Baby wants to bleep (pt.2) 6834 eng 6835 6836 0 6837 1 6838 6839 6840 5 6841 633000000 6842 748000000 6843 6844 Baby wants to bleep (pt.3) 6845 eng 6846 6847 0 6848 1 6849 6850 0 6851 1 6852 6853 6854 6 6855 750000000 6856 1178500000 6857 6858 Bleeper_O+2 6859 eng 6860 6861 0 6862 1 6863 6864 6865 7 6866 1180500000 6867 1340000000 6868 6869 Baby wants to bleep (pt.4) 6870 eng 6871 6872 0 6873 1 6874 6875 6876 8 6877 1342000000 6878 1518000000 6879 6880 Bleep to bleep 6881 eng 6882 6883 0 6884 1 6885 6886 6887 9 6888 1520000000 6889 2015000000 6890 6891 Baby wants to bleep (k) 6892 eng 6893 6894 0 6895 1 6896 6897 6898 10 6899 2017000000 6900 2668000000 6901 6902 Bleeper 6903 eng 6904 6905 0 6906 1 6907 6908 0 6909 0 6910 6911 6913 13. Attachments 6915 Matroska supports storage of related files and data in the 6916 "Attachments Element" (a "Top-Level Element"). "Attachment Elements" 6917 can be used to store related cover art, font files, transcripts, 6918 reports, error recovery files, picture, or text-based annotations, 6919 copies of specifications, or other ancillary files related to the 6920 "Segment". 6922 "Matroska Readers" MUST NOT execute files stored as "Attachment 6923 Elements". 6925 13.1. Cover Art 6927 This section defines a set of guidelines for the storage of cover art 6928 in Matroska files. A "Matroska Reader" MAY use embedded cover art to 6929 display a representational still-image depiction of the multimedia 6930 contents of the Matroska file. 6932 Only JPEG and PNG image formats SHOULD be used for cover art 6933 pictures. 6935 There can be two different covers for a movie/album: a portrait style 6936 (e.g., a DVD case) and a landscape style (e.g., a wide banner ad). 6938 There can be two versions of the same cover, the "normal cover" and 6939 the "small cover". The dimension of the "normal cover" SHOULD be 600 6940 pixels on the smallest side -- for example, 960x600 for landscape, 6941 600x800 for portrait, or 600x600 for square. The dimension of the 6942 "small cover" SHOULD be 120 pixels on the smallest side -- for 6943 example, 192x120 or 120x160. 6945 Versions of cover art can be differentiated by the filename, which is 6946 stored in the "FileName Element". The default filename of the 6947 "normal cover" in square or portrait mode is "cover.(jpg|png)". When 6948 stored, the "normal cover" SHOULD be the first Attachment in storage 6949 order. The "small cover" SHOULD be prefixed with "small_", such as 6950 "small_cover.(jpg|png)". The landscape variant SHOULD be suffixed 6951 with "_land", such as "cover_land.(jpg|png)". The filenames are case 6952 sensitive. 6954 The following table provides examples of file names for cover art in 6955 Attachments. 6957 +======================+===================+=================+ 6958 | FileName | Image Orientation | Pixel Length of | 6959 | | | Smallest Side | 6960 +======================+===================+=================+ 6961 | cover.jpg | Portrait or | 600 | 6962 | | square | | 6963 +----------------------+-------------------+-----------------+ 6964 | small_cover.png | Portrait or | 120 | 6965 | | square | | 6966 +----------------------+-------------------+-----------------+ 6967 | cover_land.png | Landscape | 600 | 6968 +----------------------+-------------------+-----------------+ 6969 | small_cover_land.jpg | Landscape | 120 | 6970 +----------------------+-------------------+-----------------+ 6972 Table 48 6974 14. Cues 6976 The "Cues Element" provides an index of certain "Cluster Elements" to 6977 allow for optimized seeking to absolute timestamps within the 6978 "Segment". The "Cues Element" contains one or many "CuePoint 6979 Elements" which each MUST reference an absolute timestamp (via the 6980 "CueTime Element"), a "Track" (via the "CueTrack Element"), and a 6981 "Segment Position" (via the "CueClusterPosition Element"). 6982 Additional non-mandated Elements are part of the "CuePoint Element" 6983 such as "CueDuration", "CueRelativePosition", "CueCodecState" and 6984 others which provide any "Matroska Reader" with additional 6985 information to use in the optimization of seeking performance. 6987 14.1. Recommendations 6989 The following recommendations are provided to optimize Matroska 6990 performance. 6992 * Unless Matroska is used as a live stream, it SHOULD contain a 6993 "Cues Element". 6995 * For each video track, each keyframe SHOULD be referenced by a 6996 "CuePoint Element". 6998 * It is RECOMMENDED to not reference non-keyframes of video tracks 6999 in "Cues" unless it references a "Cluster Element" which contains 7000 a "CodecState Element" but no keyframes. 7002 * For each subtitle track present, each subtitle frame SHOULD be 7003 referenced by a "CuePoint Element" with a "CueDuration Element". 7005 * References to audio tracks MAY be skipped in "CuePoint Elements" 7006 if a video track is present. When included the "CuePoint 7007 Elements" SHOULD reference audio keyframes at most once every 500 7008 milliseconds. 7010 * If the referenced frame is not stored within the first 7011 "SimpleBlock", or first "BlockGroup" within its "Cluster Element", 7012 then the "CueRelativePosition Element" SHOULD be written to 7013 reference where in the "Cluster" the reference frame is stored. 7015 * If a "CuePoint Element" references "Cluster Element" that includes 7016 a "CodecState Element", then that "CuePoint Element" MUST use a 7017 "CueCodecState Element". 7019 * "CuePoint Elements" SHOULD be numerically sorted in storage order 7020 by the value of the "CueTime Element". 7022 15. Matroska Streaming 7024 In Matroska, there are two kinds of streaming: file access and 7025 livestreaming. 7027 15.1. File Access 7029 File access can simply be reading a file located on your computer, 7030 but also includes accessing a file from an HTTP (web) server or CIFS 7031 (Windows share) server. These protocols are usually safe from 7032 reading errors and seeking in the stream is possible. However, when 7033 a file is stored far away or on a slow server, seeking can be an 7034 expensive operation and SHOULD be avoided. The following guidelines, 7035 when followed, help reduce the number of seeking operations for 7036 regular playback and also have the playback start quickly without a 7037 lot of data needed to read first (like a "Cues Element", "Attachment 7038 Element" or "SeekHead Element"). 7040 Matroska, having a small overhead, is well suited for storing music/ 7041 videos on file servers without a big impact on the bandwidth used. 7042 Matroska does not require the index to be loaded before playing, 7043 which allows playback to start very quickly. The index can be loaded 7044 only when seeking is requested the first time. 7046 15.2. Livestreaming 7048 Livestreaming is the equivalent of television broadcasting on the 7049 internet. There are 2 families of servers for livestreaming: RTP/ 7050 RTSP and HTTP. Matroska is not meant to be used over RTP. RTP 7051 already has timing and channel mechanisms that would be wasted if 7052 doubled in Matroska. Additionally, having the same information at 7053 the RTP and Matroska level would be a source of confusion if they do 7054 not match. Livestreaming of Matroska over HTTP (or any other plain 7055 protocol based on TCP) is possible. 7057 A live Matroska stream is different from a file because it usually 7058 has no known end (only ending when the client disconnects). For 7059 this, all bits of the "size" portion of the "Segment Element" MUST be 7060 set to 1. Another option is to concatenate "Segment Elements" with 7061 known sizes, one after the other. This solution allows a change of 7062 codec/resolution between each segment. For example, this allows for 7063 a switch between 4:3 and 16:9 in a television program. 7065 When "Segment Elements" are continuous, certain "Elements", like 7066 "MetaSeek", "Cues", "Chapters", and "Attachments", MUST NOT be used. 7068 It is possible for a "Matroska Player" to detect that a stream is not 7069 seekable. If the stream has neither a "MetaSeek" list or a "Cues" 7070 list at the beginning of the stream, it SHOULD be considered non- 7071 seekable. Even though it is possible to seek blindly forward in the 7072 stream, it is NOT RECOMMENDED. 7074 In the context of live radio or web TV, it is possible to "tag" the 7075 content while it is playing. The "Tags Element" can be placed 7076 between "Clusters" each time it is necessary. In that case, the new 7077 "Tags Element" MUST reset the previously encountered "Tags Elements" 7078 and use the new values instead. 7080 16. Menu Specifications 7082 This document is a _draft of the Menu system_ that will be the 7083 default one in "Matroska". As it will just be composed of a Control 7084 Track, it will be seen as a "codec" and could be replaced later by 7085 something else if needed. 7087 A menu is like what you see on DVDs, when you have some screens to 7088 select the audio format, subtitles or scene selection. 7090 16.1. Requirements 7092 What we'll try to have is a system that can do almost everything done 7093 on a DVD, or more, or better, or drop the unused features if 7094 necessary. 7096 As the name suggests, a Control Track is a track that can control the 7097 playback of the file and/or all the playback features. To make it as 7098 simple as possible for "Matroska Players", the Control Track will 7099 just give orders to the "Matroska Player" and get the actions 7100 associated with the highlights/hotspots. 7102 16.1.1. Highlights/Hotspots 7104 A highlight is basically a rectangle/key associated with an action 7105 UID. When that rectangle/key is activated, the "Matroska Player" 7106 send the UID of the action to the Control Track handler (codec). The 7107 fact that it can also be a key means that even for audio only files, 7108 a keyboard shortcut or button panel could be used for menus. But in 7109 that case, the hotspot will have to be associated with a name to 7110 display. 7112 This highlight is sent from the Control Track to the "Matroska 7113 Player". Then the "Matroska Player" has to handle that highlight 7114 until it's deactivated; see Section 16.1.2. 7116 The highlight contains a UID of the action, a displayable name (UTF- 7117 8), an associated key (list of keys to be defined, probably 7118 up/down/left/right/select), a screen position/range and an image to 7119 display. The image will be displayed either when the user place the 7120 mouse over the rectangle (or any other shape), or when an option of 7121 the screen is selected (not activated). There could be a second 7122 image used when the option is activated. And there could be a third 7123 image that can serve as background. This way you could have a still 7124 image (like in some DVDs) for the menu and behind that image blank 7125 video (small bitrate). 7127 When a highlight is activated by the user, the "Matroska Player" has 7128 to send the UID of the action to the Control Track. Then the Control 7129 Track codec will handle the action and possibly give new orders to 7130 the "Matroska Player". 7132 The format used for storing images SHOULD be extensible. For the 7133 moment we'll use PNG and BMP, both with alpha channel. 7135 16.1.2. Playback features 7137 All the following features will be sent from the Control Track to the 7138 "Matroska Player" : 7140 * Jump to chapter (UID, prev, next, number) 7142 * Disable all tracks of a kind (audio, video, subtitle) 7144 * Enable track UID (the kind doesn't matter) 7146 * Define/Disable a highlight 7148 * Enable/Disable jumping 7150 * Enable/Disable track selection of a kind 7152 * Select Edition ID (see chapters) 7154 * Pause playback 7156 * Stop playback 7158 * Enable/Disable a Chapter UID 7160 * Hide/Unhide a Chapter UID 7162 All the actions will be written in a normal Matroska track, with a 7163 timestamp. A "Menu Frame" SHOULD be able to contain more that one 7164 action/highlight for a given timestamp. (to be determined, EBML 7165 format structure) 7167 16.1.3. Player requirements 7169 Some "Matroska Players" might not support the control track. That 7170 mean they will play the active/looped parts as part of the data. So 7171 I suggest putting the active/looped parts of a movie at the end of a 7172 movie. When a Menu-aware "Matroska Player" encounter the default 7173 Control Track of a "Matroska" file, the first order SHOULD be to jump 7174 at the start of the active/looped part of the movie. 7176 16.2. Working Graph 7178 Matroska Source file -> Control Track <-> Player. 7179 -> other tracks -> rendered 7181 17. Unknown elements 7183 Matroska is based upon the principle that a reading application does 7184 not have to support 100% of the specifications in order to be able to 7185 play the file. A Matroska file therefore contains version indicators 7186 that tell a reading application what to expect. 7188 It is possible and valid to have the version fields indicate that the 7189 file contains Matroska "Elements" from a higher specification version 7190 number while signaling that a reading application MUST only support a 7191 lower version number properly in order to play it back (possibly with 7192 a reduced feature set). For example, a reading application 7193 supporting at least Matroska version "V" reading a file whose 7194 "DocTypeReadVersion" field is equal to or lower than "V" MUST skip 7195 Matroska/EBML "Elements" it encounters but does not know about if 7196 that unknown element fits into the size constraints set by the 7197 current "Parent Element". 7199 18. Default Values 7201 The default value of an "Element" is assumed when not present in the 7202 data stream. It is assumed only in the scope of its "Parent 7203 Element". For example, the "Language Element" is in the scope of the 7204 "Track Element". If the "Parent Element" is not present or assumed, 7205 then the "Child Element" cannot be assumed. 7207 19. DefaultDecodedFieldDuration 7209 The "DefaultDecodedFieldDuration Element" can signal to the 7210 displaying application how often fields of a video sequence will be 7211 available for displaying. It can be used for both interlaced and 7212 progressive content. If the video sequence is signaled as 7213 interlaced, then the period between two successive fields at the 7214 output of the decoding process equals "DefaultDecodedFieldDuration". 7216 For video sequences signaled as progressive, it is twice the value of 7217 "DefaultDecodedFieldDuration". 7219 These values are valid at the end of the decoding process before 7220 post-processing (such as deinterlacing or inverse telecine) is 7221 applied. 7223 Examples: 7225 * Blu-ray movie: 1000000000ns/(48/1.001) = 20854167ns 7227 * PAL broadcast/DVD: 1000000000ns/(50/1.000) = 20000000ns 7229 * N/ATSC broadcast: 1000000000ns/(60/1.001) = 16683333ns 7231 * hard-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (60 7232 encoded interlaced fields per second) 7234 * soft-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (48 7235 encoded interlaced fields per second, with "repeat_first_field = 7236 1") 7238 20. Encryption 7240 Encryption in Matroska is designed in a very generic style to allow 7241 people to implement whatever form of encryption is best for them. It 7242 is possible to use the encryption framework in Matroska as a type of 7243 DRM (Digital Rights Management). 7245 Because encryption occurs within the "Block Element", it is possible 7246 to manipulate encrypted streams without decrypting them. The streams 7247 could potentially be copied, deleted, cut, appended, or any number of 7248 other possible editing techniques without decryption. The data can 7249 be used without having to expose it or go through the decrypting 7250 process. 7252 Encryption can also be layered within Matroska. This means that two 7253 completely different types of encryption can be used, requiring two 7254 separate keys to be able to decrypt a stream. 7256 Encryption information is stored in the "ContentEncodings Element" 7257 under the "ContentEncryption Element". 7259 21. Image Presentation 7260 21.1. Cropping 7262 The "PixelCrop Elements" ("PixelCropTop", "PixelCropBottom", 7263 "PixelCropRight", and "PixelCropLeft") indicate when, and by how 7264 much, encoded videos frames SHOULD be cropped for display. These 7265 Elements allow edges of the frame that are not intended for display, 7266 such as the sprockets of a full-frame film scan or the VANC area of a 7267 digitized analog videotape, to be stored but hidden. "PixelCropTop" 7268 and "PixelCropBottom" store an integer of how many rows of pixels 7269 SHOULD be cropped from the top and bottom of the image 7270 (respectively). "PixelCropLeft" and "PixelCropRight" store an 7271 integer of how many columns of pixels SHOULD be cropped from the left 7272 and right of the image (respectively). For example, a pillar-boxed 7273 video that stores a 1440x1080 visual image within the center of a 7274 padded 1920x1080 encoded image MAY set both "PixelCropLeft" and 7275 "PixelCropRight" to "240", so that a "Matroska Player" SHOULD crop 7276 off 240 columns of pixels from the left and right of the encoded 7277 image to present the image with the pillar-boxes hidden. 7279 21.2. Rotation 7281 The ProjectionPoseRoll Element (see Section 10.4.1.31.20.5) can be 7282 used to indicate that the image from the associated video track 7283 SHOULD be rotated for presentation. For instance, the following 7284 representation of the Projection Element Section 10.4.1.31.20) and 7285 the ProjectionPoseRoll Element represents a video track where the 7286 image SHOULD be presentation with a 90 degree counter-clockwise 7287 rotation. 7289 7290 90 7291 7293 22. Matroska versioning 7295 The "EBML Header" of each Matroska document informs the reading 7296 application on what version of Matroska to expect. The "Elements" 7297 within "EBML Header" with jurisdiction over this information are 7298 "DocTypeVersion" and "DocTypeReadVersion". 7300 "DocTypeVersion" MUST be equal to or greater than the highest 7301 Matroska version number of any "Element" present in the Matroska 7302 file. For example, a file using the "SimpleBlock Element" MUST have 7303 a "DocTypeVersion" equal to or greater than 2. A file containing 7304 "CueRelativePosition" Elements MUST have a "DocTypeVersion" equal to 7305 or greater than 4. 7307 The "DocTypeReadVersion" MUST contain the minimum version number that 7308 a reading application can minimally support in order to play the file 7309 back -- optionally with a reduced feature set. For example, if a 7310 file contains only "Elements" of version 2 or lower except for 7311 "CueRelativePosition" (which is a version 4 Matroska "Element"), then 7312 "DocTypeReadVersion" SHOULD still be set to 2 and not 4 because 7313 evaluating "CueRelativePosition" is not necessary for standard 7314 playback -- it makes seeking more precise if used. 7316 "DocTypeVersion" MUST always be equal to or greater than 7317 "DocTypeReadVersion". 7319 A reading application supporting Matroska version "V" MUST NOT refuse 7320 to read an application with "DocReadTypeVersion" equal to or lower 7321 than "V" even if "DocTypeVersion" is greater than "V". See also the 7322 note about Unknown Elements in Section 17. 7324 23. MIME Types 7326 There is no IETF endorsed MIME type for Matroska files. These 7327 definitions can be used: 7329 * .mka : Matroska audio "audio/x-matroska" 7331 * .mkv : Matroska video "video/x-matroska" 7333 * .mk3d : Matroska 3D video "video/x-matroska-3d" 7335 24. Segment Position 7337 The "Segment Position" of an "Element" refers to the position of the 7338 first octet of the "Element ID" of that "Element", measured in 7339 octets, from the beginning of the "Element Data" section of the 7340 containing "Segment Element". In other words, the "Segment Position" 7341 of an "Element" is the distance in octets from the beginning of its 7342 containing "Segment Element" minus the size of the "Element ID" and 7343 "Element Data Size" of that "Segment Element". The "Segment 7344 Position" of the first "Child Element" of the "Segment Element" is 0. 7345 An "Element" which is not stored within a "Segment Element", such as 7346 the "Elements" of the "EBML Header", do not have a "Segment 7347 Position". 7349 24.1. Segment Position Exception 7351 "Elements" that are defined to store a "Segment Position" MAY define 7352 reserved values to indicate a special meaning. 7354 24.2. Example of Segment Position 7356 This table presents an example of "Segment Position" by showing a 7357 hexadecimal representation of a very small Matroska file with labels 7358 to show the offsets in octets. The file contains a "Segment Element" 7359 with an "Element ID" of "0x18538067" and a "MuxingApp Element" with 7360 an "Element ID" of "0x4D80". 7362 0 1 2 7363 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 7364 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 7365 0 |1A|45|DF|A3|8B|42|82|88|6D|61|74|72|6F|73|6B|61|18|53|80|67| 7366 20 |93|15|49|A9|66|8E|4D|80|84|69|65|74|66|57|41|84|69|65|74|66| 7368 In the above example, the "Element ID" of the "Segment Element" is 7369 stored at offset 16, the "Element Data Size" of the "Segment Element" 7370 is stored at offset 20, and the "Element Data" of the "Segment 7371 Element" is stored at offset 21. 7373 The "MuxingApp Element" is stored at offset 26. Since the "Segment 7374 Position" of an "Element" is calculated by subtracting the position 7375 of the "Element Data" of the containing "Segment Element" from the 7376 position of that "Element", the "Segment Position" of "MuxingApp 7377 Element" in the above example is '26 - 21' or '5'. 7379 25. Linked Segments 7381 Matroska provides several methods to link two or many "Segment 7382 Elements" together to create a "Linked Segment". A "Linked Segment" 7383 is a set of multiple "Segments" related together into a single 7384 presentation by using Hard Linking, Medium Linking, or Soft Linking. 7385 All "Segments" within a "Linked Segment" MUST utilize the same track 7386 numbers and timescale. All "Segments" within a "Linked Segment" MUST 7387 be stored within the same directory. All "Segments" within a "Linked 7388 Segment" MUST store a "SegmentUID". 7390 25.1. Hard Linking 7392 Hard Linking (also called splitting) is the process of creating a 7393 "Linked Segment" by relating multiple "Segment Elements" using the 7394 "NextUID" and "PrevUID" Elements. Within a "Linked Segment", the 7395 timestamps of each "Segment" MUST follow consecutively in linking 7396 order. With Hard Linking, the chapters of any "Segment" within the 7397 "Linked Segment" MUST only reference the current "Segment". With 7398 Hard Linking, the "NextUID" and "PrevUID" MUST reference the 7399 respective "SegmentUID" values of the next and previous "Segments". 7400 The first "Segment" of a "Linked Segment" SHOULD have a "NextUID 7401 Element" and MUST NOT have a "PrevUID Element". The last "Segment" 7402 of a "Linked Segment" SHOULD have a "PrevUID Element" and MUST NOT 7403 have a "NextUID Element". The middle "Segments" of a "Linked 7404 Segment" SHOULD have both a "NextUID Element" and a "PrevUID 7405 Element". 7407 In a chain of "Linked Segments" the "NextUID" always takes precedence 7408 over the "PrevUID". So if SegmentA has a NextUID to SegmentB and 7409 SegmentB has a PrevUID to SegmentC, the link to use is SegmentA to 7410 SegmentB. If SegmentB has a PrevUID to SegmentA but SegmentA has no 7411 NextUID, then the Matroska Player MAY consider these two Segments 7412 linked as SegmentA followed by SegmentB. 7414 As an example, three "Segments" can be Hard Linked as a "Linked 7415 Segment" through cross-referencing each other with "SegmentUID", 7416 "PrevUID", and "NextUID", as in this table. 7418 +==========+==================+==================+==================+ 7419 |file name | SegmentUID | PrevUID | NextUID | 7420 +==========+==================+==================+==================+ 7421 |start.mkv | 71000c23cd310998 | n/a | a77b3598941cb803 | 7422 | | 53fbc94dd984a5dd | | eac0fcdafe44fac9 | 7423 +----------+------------------+------------------+------------------+ 7424 |middle.mkv| a77b3598941cb803 | 71000c23cd310998 | 6c92285fa6d3e827 | 7425 | | eac0fcdafe44fac9 | 53fbc94dd984a5dd | b198d120ea3ac674 | 7426 +----------+------------------+------------------+------------------+ 7427 |end.mkv | 6c92285fa6d3e827 | a77b3598941cb803 | n/a | 7428 | | b198d120ea3ac674 | eac0fcdafe44fac9 | | 7429 +----------+------------------+------------------+------------------+ 7431 Table 49 7433 An other example where only the "NextUID" Element is used. 7435 +============+==================+=========+==================+ 7436 | file name | SegmentUID | PrevUID | NextUID | 7437 +============+==================+=========+==================+ 7438 | start.mkv | 71000c23cd310998 | n/a | a77b3598941cb803 | 7439 | | 53fbc94dd984a5dd | | eac0fcdafe44fac9 | 7440 +------------+------------------+---------+------------------+ 7441 | middle.mkv | a77b3598941cb803 | n/a | 6c92285fa6d3e827 | 7442 | | eac0fcdafe44fac9 | | b198d120ea3ac674 | 7443 +------------+------------------+---------+------------------+ 7444 | end.mkv | 6c92285fa6d3e827 | n/a | n/a | 7445 | | b198d120ea3ac674 | | | 7446 +------------+------------------+---------+------------------+ 7448 Table 50 7450 A next example where only the "PrevUID" Element is used. 7452 +============+==================+==================+=========+ 7453 | file name | SegmentUID | PrevUID | NextUID | 7454 +============+==================+==================+=========+ 7455 | start.mkv | 71000c23cd310998 | n/a | n/a | 7456 | | 53fbc94dd984a5dd | | | 7457 +------------+------------------+------------------+---------+ 7458 | middle.mkv | a77b3598941cb803 | 71000c23cd310998 | n/a | 7459 | | eac0fcdafe44fac9 | 53fbc94dd984a5dd | | 7460 +------------+------------------+------------------+---------+ 7461 | end.mkv | 6c92285fa6d3e827 | a77b3598941cb803 | n/a | 7462 | | b198d120ea3ac674 | eac0fcdafe44fac9 | | 7463 +------------+------------------+------------------+---------+ 7465 Table 51 7467 In this example only the "middle.mkv" is using the "PrevUID" and 7468 "NextUID" Elements. 7470 +==========+==================+==================+==================+ 7471 |file name | SegmentUID | PrevUID | NextUID | 7472 +==========+==================+==================+==================+ 7473 |start.mkv | 71000c23cd310998 | n/a | n/a | 7474 | | 53fbc94dd984a5dd | | | 7475 +----------+------------------+------------------+------------------+ 7476 |middle.mkv| a77b3598941cb803 | 71000c23cd310998 | 6c92285fa6d3e827 | 7477 | | eac0fcdafe44fac9 | 53fbc94dd984a5dd | b198d120ea3ac674 | 7478 +----------+------------------+------------------+------------------+ 7479 |end.mkv | 6c92285fa6d3e827 | n/a | n/a | 7480 | | b198d120ea3ac674 | | | 7481 +----------+------------------+------------------+------------------+ 7483 Table 52 7485 25.2. Medium Linking 7487 Medium Linking creates relationships between "Segments" using Ordered 7488 Chapters and the "ChapterSegmentUID Element". A "Segment Edition" 7489 with Ordered Chapters MAY contain "Chapter Elements" that reference 7490 timestamp ranges from other "Segments". The "Segment" referenced by 7491 the Ordered Chapter via the "ChapterSegmentUID Element" SHOULD be 7492 played as part of a Linked Segment. The timestamps of Segment 7493 content referenced by Ordered Chapters MUST be adjusted according to 7494 the cumulative duration of the the previous Ordered Chapters. 7496 As an example a file named "intro.mkv" could have a "SegmentUID" of 7497 "0xb16a58609fc7e60653a60c984fc11ead". Another file called 7498 "program.mkv" could use a Chapter Edition that contains two Ordered 7499 Chapters. The first chapter references the "Segment" of "intro.mkv" 7500 with the use of a "ChapterSegmentUID", "ChapterSegmentEditionUID", 7501 "ChapterTimeStart", and optionally a "ChapterTimeEnd" element. The 7502 second chapter references content within the "Segment" of 7503 "program.mkv". A "Matroska Player" SHOULD recognize the "Linked 7504 Segment" created by the use of "ChapterSegmentUID" in an enabled 7505 "Edition" and present the reference content of the two "Segments" 7506 together. 7508 25.3. Soft Linking 7510 Soft Linking is used by codec chapters. They can reference another 7511 "Segment" and jump to that "Segment". The way the "Segments" are 7512 described are internal to the chapter codec and unknown to the 7513 Matroska level. But there are "Elements" within the "Info Element" 7514 (such as "ChapterTranslate") that can translate a value representing 7515 a "Segment" in the chapter codec and to the current "SegmentUID". 7516 All "Segments" that could be used in a "Linked Segment" in this way 7517 SHOULD be marked as members of the same family via the "SegmentFamily 7518 Element", so that the "Matroska Player" can quickly switch from one 7519 to the other. 7521 26. Track Flags 7523 26.1. Default flag 7525 The "default track" flag is a hint for a "Matroska Player" and SHOULD 7526 always be changeable by the user. If the user wants to see or hear a 7527 track of a certain kind (audio, video, subtitles) and hasn't chosen a 7528 specific track, the "Matroska Player" SHOULD use the first track of 7529 that kind whose "default track" flag is set to "1". If no such track 7530 is found, then the first track of this kind SHOULD be chosen. 7532 Only one track of a kind MAY have its "default track" flag set in a 7533 segment. If a track entry does not contain the "default track" flag 7534 element, then its default value "1" is to be used. 7536 26.2. Forced flag 7538 The "forced" flag tells the "Matroska Player" that it MUST display/ 7539 play this track or another track of the same kind that also has its 7540 "forced" flag set. When there are multiple "forced" tracks, the 7541 "Matroska Player" SHOULD determine the track based upon the language 7542 of the forced flag or use the default flag if no track matches the 7543 use languages. Another track of the same kind without the "forced" 7544 flag may be use simultaneously with the "forced" track, like DVD 7545 subtitles. 7547 26.3. Track Operation 7549 "TrackOperation" allows combining multiple tracks to make a virtual 7550 one. It uses two separate system to combine tracks. One to create a 7551 3D "composition" (left/right/background planes) and one to simplify 7552 join two tracks together to make a single track. 7554 A track created with "TrackOperation" is a proper track with a UID 7555 and all its flags. However the codec ID is meaningless because each 7556 "sub" track needs to be decoded by its own decoder before the 7557 "operation" is applied. The "Cues Elements" corresponding to such a 7558 virtual track SHOULD be the sum of the "Cues Elements" for each of 7559 the tracks it's composed of (when the "Cues" are defined per track). 7561 In the case of "TrackJoinBlocks", the "Block Elements" (from 7562 "BlockGroup" and "SimpleBlock") of all the tracks SHOULD be used as 7563 if they were defined for this new virtual "Track". When two "Block 7564 Elements" have overlapping start or end timestamps, it's up to the 7565 underlying system to either drop some of these frames or render them 7566 the way they overlap. This situation SHOULD be avoided when creating 7567 such tracks as you can never be sure of the end result on different 7568 platforms. 7570 26.4. Overlay Track 7572 Overlay tracks SHOULD be rendered in the same channel as the track 7573 its linked to. When content is found in such a track, it SHOULD be 7574 played on the rendering channel instead of the original track. 7576 26.5. Multi-planar and 3D videos 7578 There are two different ways to compress 3D videos: have each eye 7579 track in a separate track and have one track have both eyes combined 7580 inside (which is more efficient, compression-wise). Matroska 7581 supports both ways. 7583 For the single track variant, there is the "StereoMode Element", 7584 which defines how planes are assembled in the track (mono or left- 7585 right combined). Odd values of StereoMode means the left plane comes 7586 first for more convenient reading. The pixel count of the track 7587 ("PixelWidth"/"PixelHeight") is the raw amount of pixels, for example 7588 3840x1080 for full HD side by side, and the 7589 "DisplayWidth"/"DisplayHeight" in pixels is the amount of pixels for 7590 one plane (1920x1080 for that full HD stream). Old stereo 3D were 7591 displayed using anaglyph (cyan and red colours separated). For 7592 compatibility with such movies, there is a value of the StereoMode 7593 that corresponds to AnaGlyph. 7595 There is also a "packed" mode (values 13 and 14) which consists of 7596 packing two frames together in a "Block" using lacing. The first 7597 frame is the left eye and the other frame is the right eye (or vice 7598 versa). The frames SHOULD be decoded in that order and are possibly 7599 dependent on each other (P and B frames). 7601 For separate tracks, Matroska needs to define exactly which track 7602 does what. "TrackOperation" with "TrackCombinePlanes" do that. For 7603 more details look at Section 26.3 on how TrackOperation works. 7605 The 3D support is still in infancy and may evolve to support more 7606 features. 7608 The StereoMode used to be part of Matroska v2 but it didn't meet the 7609 requirement for multiple tracks. There was also a bug in libmatroska 7610 prior to 0.9.0 that would save/read it as 0x53B9 instead of 0x53B8. 7611 "Matroska Readers" may support these legacy files by checking 7612 Matroska v2 or 0x53B9. The older values were 0: mono, 1: right eye, 7613 2: left eye, 3: both eyes. 7615 27. Timestamps 7617 Historically timestamps in Matroska were mistakenly called timecodes. 7618 The "Timestamp Element" was called Timecode, the "TimestampScale 7619 Element" was called TimecodeScale, the "TrackTimestampScale Element" 7620 was called TrackTimecodeScale and the "ReferenceTimestamp Element" 7621 was called ReferenceTimeCode. 7623 27.1. Timestamp Types 7625 * Absolute Timestamp = Block+Cluster 7627 * Relative Timestamp = Block 7629 * Scaled Timestamp = Block+Cluster 7630 * Raw Timestamp = (Block+Cluster)*TimestampScale*TrackTimestampScale 7632 27.2. Block Timestamps 7634 The "Block Element"'s timestamp MUST be a signed integer that 7635 represents the "Raw Timestamp" relative to the "Cluster"'s "Timestamp 7636 Element", multiplied by the "TimestampScale Element". See 7637 Section 27.4 for more information. 7639 The "Block Element"'s timestamp MUST be represented by a 16bit signed 7640 integer (sint16). The "Block"'s timestamp has a range of -32768 to 7641 +32767 units. When using the default value of the "TimestampScale 7642 Element", each integer represents 1ms. The maximum time span of 7643 "Block Elements" in a "Cluster" using the default "TimestampScale 7644 Element" of 1ms is 65536ms. 7646 If a "Cluster"'s "Timestamp Element" is set to zero, it is possible 7647 to have "Block Elements" with a negative "Raw Timestamp". "Block 7648 Elements" with a negative "Raw Timestamp" are not valid. 7650 27.3. Raw Timestamp 7652 The exact time of an object SHOULD be represented in nanoseconds. To 7653 find out a "Block"'s "Raw Timestamp", you need the "Block"'s 7654 "Timestamp Element", the "Cluster"'s "Timestamp Element", and the 7655 "TimestampScale Element". 7657 27.4. TimestampScale 7659 The "TimestampScale Element" is used to calculate the "Raw Timestamp" 7660 of a "Block". The timestamp is obtained by adding the "Block"'s 7661 timestamp to the "Cluster"'s "Timestamp Element", and then 7662 multiplying that result by the "TimestampScale". The result will be 7663 the "Block"'s "Raw Timestamp" in nanoseconds. The formula for this 7664 would look like: 7666 (a + b) * c 7668 a = `Block`'s Timestamp 7669 b = `Cluster`'s Timestamp 7670 c = `TimestampScale` 7672 For example, assume a "Cluster"'s "Timestamp" has a value of 564264, 7673 the "Block" has a "Timestamp" of 1233, and the "TimestampScale 7674 Element" is the default of 1000000. 7676 (1233 + 564264) * 1000000 = 565497000000 7677 So, the "Block" in this example has a specific time of 565497000000 7678 in nanoseconds. In milliseconds this would be 565497ms. 7680 27.5. TimestampScale Rounding 7682 Because the default value of "TimestampScale" is 1000000, which makes 7683 each integer in the "Cluster" and "Block" "Timestamp Elements" equal 7684 1ms, this is the most commonly used. When dealing with audio, this 7685 causes inaccuracy when seeking. When the audio is combined with 7686 video, this is not an issue. For most cases, the the synch of audio 7687 to video does not need to be more than 1ms accurate. This becomes 7688 obvious when one considers that sound will take 2-3ms to travel a 7689 single meter, so distance from your speakers will have a greater 7690 effect on audio/visual synch than this. 7692 However, when dealing with audio-only files, seeking accuracy can 7693 become critical. For instance, when storing a whole CD in a single 7694 track, a user will want to be able to seek to the exact sample that a 7695 song begins at. If seeking a few sample ahead or behind, a crack or 7696 pop may result as a few odd samples are rendered. Also, when 7697 performing precise editing, it may be very useful to have the audio 7698 accuracy down to a single sample. 7700 When storing timestamps for an audio stream, the "TimestampScale 7701 Element" SHOULD have an accuracy of at least that of the audio sample 7702 rate, otherwise there are rounding errors that prevent users from 7703 knowing the precise location of a sample. Here's how a program has 7704 to round each timestamp in order to be able to recreate the sample 7705 number accurately. 7707 Let's assume that the application has an audio track with a sample 7708 rate of 44100. As written above the "TimestampScale" MUST have at 7709 least the accuracy of the sample rate itself: 1000000000 / 44100 = 7710 22675.7369614512. This value MUST always be truncated. Otherwise 7711 the accuracy will not suffice. So in this example the application 7712 will use 22675 for the "TimestampScale". The application could even 7713 use some lower value like 22674, which would allow it to be a little 7714 bit imprecise about the original timestamps. But more about that in 7715 a minute. 7717 Next the application wants to write sample number 52340 and 7718 calculates the timestamp. This is easy. In order to calculate the 7719 "Raw Timestamp" in ns all it has to do is calculate "Raw Timestamp = 7720 round(1000000000 * sample_number / sample_rate)". Rounding at this 7721 stage is very important! The application might skip it if it choses 7722 a slightly smaller value for the "TimestampScale" factor instead of 7723 the truncated one like shown above. Otherwise it has to round or the 7724 results won't be reversible. For our example we get "Raw Timestamp = 7725 round(1000000000 * 52340 / 44100) = round(1186848072.56236) = 7726 1186848073". 7728 The next step is to calculate the "Absolute Timestamp" - that is the 7729 timestamp that will be stored in the Matroska file. Here the 7730 application has to divide the "Raw Timestamp" from the previous 7731 paragraph by the "TimestampScale" factor and round the result: 7732 "Absolute Timestamp = round(Raw Timestamp / TimestampScale_factor)", 7733 which will result in the following for our example: "Absolute 7734 Timestamp = round(1186848073 / 22675) = round(52341.7011245866) = 7735 52342". This number is the one the application has to write to the 7736 file. 7738 Now our file is complete, and we want to play it back with another 7739 application. Its task is to find out which sample the first 7740 application wrote into the file. So it starts reading the Matroska 7741 file and finds the "TimestampScale" factor 22675 and the audio sample 7742 rate 44100. Later it finds a data block with the "Absolute 7743 Timestamp" of 52342. But how does it get the sample number from 7744 these numbers? 7746 First it has to calculate the "Raw Timestamp" of the block it has 7747 just read. Here's no rounding involved, just an integer 7748 multiplication: "Raw Timestamp = Absolute Timestamp * 7749 TimestampScale_factor". In our example: "Raw Timestamp = 52342 * 7750 22675 = 1186854850". 7752 The conversion from the "Raw Timestamp" to the sample number again 7753 requires rounding: "sample_number = round(Raw Timestamp * sample_rate 7754 / 1000000000)". In our example: "sample_number = round(1186854850 * 7755 44100 / 1000000000) = round(52340.298885) = 52340". This is exactly 7756 the sample number that the previous program started with. 7758 Some general notes for a program: 7760 1. Always calculate the timestamps / sample numbers with floating 7761 point numbers of at least 64bit precision (called 'double' in 7762 most modern programming languages). If you're calculating with 7763 integers, then make sure they're 64bit long, too. 7765 2. Always round if you divide. Always! If you don't you'll end up 7766 with situations in which you have a timestamp in the Matroska 7767 file that does not correspond to the sample number that it 7768 started with. Using a slightly lower timestamp scale factor can 7769 help here in that it removes the need for proper rounding in the 7770 conversion from sample number to "Raw Timestamp". 7772 27.6. TrackTimestampScale 7774 The "TrackTimestampScale Element" is used align tracks that would 7775 otherwise be played at different speeds. An example of this would be 7776 if you have a film that was originally recorded at 24fps video. When 7777 playing this back through a PAL broadcasting system, it is standard 7778 to speed up the film to 25fps to match the 25fps display speed of the 7779 PAL broadcasting standard. However, when broadcasting the video 7780 through NTSC, it is typical to leave the film at its original speed. 7781 If you wanted to make a single file where there was one video stream, 7782 and an audio stream used from the PAL broadcast, as well as an audio 7783 stream used from the NTSC broadcast, you would have the problem that 7784 the PAL audio stream would be 1/24th faster than the NTSC audio 7785 stream, quickly leading to problems. It is possible to stretch out 7786 the PAL audio track and re-encode it at a slower speed, however when 7787 dealing with lossy audio codecs, this often results in a loss of 7788 audio quality and/or larger file sizes. 7790 This is the type of problem that "TrackTimestampScale" was designed 7791 to fix. Using it, the video can be played back at a speed that will 7792 synch with either the NTSC or the PAL audio stream, depending on 7793 which is being used for playback. To continue the above example: 7795 Track 1: Video 7796 Track 2: NTSC Audio 7797 Track 3: PAL Audio 7799 Because the NTSC track is at the original speed, it will used as the 7800 default value of 1.0 for its "TrackTimestampScale". The video will 7801 also be aligned to the NTSC track with the default value of 1.0. 7803 The "TrackTimestampScale" value to use for the PAL track would be 7804 calculated by determining how much faster the PAL track is than the 7805 NTSC track. In this case, because we know the video for the NTSC 7806 audio is being played back at 24fps and the video for the PAL audio 7807 is being played back at 25fps, the calculation would be: 7809 25/24 is almost 1.04166666666666666667 7810 When writing a file that uses a non-default "TrackTimestampScale", 7811 the values of the "Block"'s timestamp are whatever they would be when 7812 normally storing the track with a default value for the 7813 "TrackTimestampScale". However, the data is interleaved a little 7814 differently. Data SHOULD be interleaved by its Raw Timestamp, see 7815 Section 27.3, in the order handed back from the encoder. The "Raw 7816 Timestamp" of a "Block" from a track using "TrackTimestampScale" is 7817 calculated using: 7819 "(Block's Timestamp + Cluster's Timestamp) * TimestampScale * 7820 TrackTimestampScale" 7822 So, a Block from the PAL track above that had a Scaled Timestamp, see 7823 Section 27.1, of 100 seconds would have a "Raw Timestamp" of 7824 104.66666667 seconds, and so would be stored in that part of the 7825 file. 7827 When playing back a track using the "TrackTimestampScale", if the 7828 track is being played by itself, there is no need to scale it. From 7829 the above example, when playing the Video with the NTSC Audio, 7830 neither are scaled. However, when playing back the Video with the 7831 PAL Audio, the timestamps from the PAL Audio track are scaled using 7832 the "TrackTimestampScale", resulting in the video playing back in 7833 synch with the audio. 7835 It would be possible for a "Matroska Player" to also adjust the 7836 audio's samplerate at the same time as adjusting the timestamps if 7837 you wanted to play the two audio streams synchronously. It would 7838 also be possible to adjust the video to match the audio's speed. 7839 However, for playback, the selected track(s) timestamps SHOULD be 7840 adjusted if they need to be scaled. 7842 While the above example deals specifically with audio tracks, this 7843 element can be used to align video, audio, subtitles, or any other 7844 type of track contained in a Matroska file. 7846 28. Normative References 7848 [I-D.ietf-cellar-codec] 7849 Lhomme, S., Bunkus, M., and D. Rice, "Matroska Media 7850 Container Codec Specifications", Work in Progress, 7851 Internet-Draft, draft-ietf-cellar-codec-04, 17 April 2020, 7852 . 7854 [I-D.ietf-cellar-tags] 7855 Lhomme, S., Bunkus, M., and D. Rice, "Matroska Media 7856 Container Tag Specifications", Work in Progress, Internet- 7857 Draft, draft-ietf-cellar-tags-04, 17 April 2020, 7858 . 7860 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 7861 Requirement Levels", BCP 14, RFC 2119, 7862 DOI 10.17487/RFC2119, March 1997, 7863 . 7865 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 7866 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 7867 May 2017, . 7869 [RFC8794] Lhomme, S., Rice, D., and M. Bunkus, "Extensible Binary 7870 Meta Language", RFC 8794, DOI 10.17487/RFC8794, July 2020, 7871 . 7873 29. Informative References 7875 [MCF] "Media Container Format", 17 July 2002, 7876 . 7878 Authors' Addresses 7880 Steve Lhomme 7882 Email: slhomme@matroska.org 7884 Moritz Bunkus 7886 Email: moritz@bunkus.org 7888 Dave Rice 7890 Email: dave@dericed.com