idnits 2.17.1 draft-lhomme-cellar-matroska-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 4 instances of too long lines in the document, the longest one being 38 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 684 has weird spacing: '...xx xxxx xxxx ...' == Line 685 has weird spacing: '...1x xxxx xxxx ...' == Line 686 has weird spacing: '...01 xxxx xxxx ...' == Line 688 has weird spacing: '...00 1xxx xxxx ...' == Line 689 has weird spacing: '...xx xxxx xxxx ...' == (4 more instances...) == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Frames using references SHOULD be stored in "coding order". That means the references first and then the frames referencing them. A consequence is that timecodes MAY NOT be consecutive. But a frame with a past timecode MUST reference a frame already known, otherwise it's considered bad/void. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Frames using references SHOULD be stored in "coding order". That means the references first and then the frames referencing them. A consequence is that timecodes MAY NOT be consecutive. But a frame with a past timecode MUST reference a frame already known, otherwise it's considered bad/void. -- The document date (January 3, 2018) is 2305 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 7359 looks like a reference -- Missing reference section? '2' on line 7361 looks like a reference -- Missing reference section? '3' on line 7364 looks like a reference -- Missing reference section? '4' on line 7366 looks like a reference -- Missing reference section? '5' on line 7368 looks like a reference -- Missing reference section? '6' on line 7370 looks like a reference -- Missing reference section? '7' on line 7373 looks like a reference -- Missing reference section? '8' on line 7376 looks like a reference -- Missing reference section? '9' on line 7378 looks like a reference -- Missing reference section? '10' on line 7381 looks like a reference -- Missing reference section? '11' on line 7384 looks like a reference -- Missing reference section? '12' on line 7387 looks like a reference -- Missing reference section? '13' on line 7390 looks like a reference -- Missing reference section? '14' on line 7392 looks like a reference -- Missing reference section? '15' on line 7394 looks like a reference -- Missing reference section? '16' on line 7396 looks like a reference -- Missing reference section? '0' on line 6211 looks like a reference -- Missing reference section? '17' on line 7398 looks like a reference -- Missing reference section? '18' on line 7400 looks like a reference -- Missing reference section? '19' on line 7402 looks like a reference -- Missing reference section? '20' on line 7404 looks like a reference Summary: 2 errors (**), 0 flaws (~~), 10 warnings (==), 24 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: Standards Track M. Bunkus 5 Expires: July 7, 2018 6 D. Rice 7 January 3, 2018 9 Matroska Specifications 10 draft-lhomme-cellar-matroska-04 12 Abstract 14 This document defines the Matroska audiovisual container, including 15 definitions of its structural elements, as well as its terminology, 16 vocabulary, and application. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on July 7, 2018. 35 Copyright Notice 37 Copyright (c) 2018 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 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 53 2. Status of this document . . . . . . . . . . . . . . . . . . . 10 54 3. Security Considerations . . . . . . . . . . . . . . . . . . . 10 55 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 56 5. Notation and Conventions . . . . . . . . . . . . . . . . . . 10 57 6. Basis in EBML . . . . . . . . . . . . . . . . . . . . . . . . 11 58 6.1. Added Constraints on EBML . . . . . . . . . . . . . . . . 11 59 6.2. Matroska Design . . . . . . . . . . . . . . . . . . . . . 11 60 6.2.1. Language Codes . . . . . . . . . . . . . . . . . . . 11 61 6.2.2. Physical Types . . . . . . . . . . . . . . . . . . . 12 62 6.2.3. Block Structure . . . . . . . . . . . . . . . . . . . 12 63 6.2.4. Lacing . . . . . . . . . . . . . . . . . . . . . . . 14 64 7. Matroska Structure . . . . . . . . . . . . . . . . . . . . . 18 65 8. Matroska Schema . . . . . . . . . . . . . . . . . . . . . . . 26 66 8.1. Matroska Additions to Schema Element Attributes . . . . . 26 67 8.2. Matroska Schema . . . . . . . . . . . . . . . . . . . . . 27 68 8.2.1. EBMLMaxIDLength Element . . . . . . . . . . . . . . . 27 69 8.2.2. EBMLMaxSizeLength Element . . . . . . . . . . . . . . 27 70 8.2.3. Segment Element . . . . . . . . . . . . . . . . . . . 28 71 8.2.4. SeekHead Element . . . . . . . . . . . . . . . . . . 28 72 8.2.5. Seek Element . . . . . . . . . . . . . . . . . . . . 28 73 8.2.6. SeekID Element . . . . . . . . . . . . . . . . . . . 29 74 8.2.7. SeekPosition Element . . . . . . . . . . . . . . . . 29 75 8.2.8. Info Element . . . . . . . . . . . . . . . . . . . . 30 76 8.2.9. SegmentUID Element . . . . . . . . . . . . . . . . . 30 77 8.2.10. SegmentFilename Element . . . . . . . . . . . . . . . 30 78 8.2.11. PrevUID Element . . . . . . . . . . . . . . . . . . . 31 79 8.2.12. PrevFilename Element . . . . . . . . . . . . . . . . 31 80 8.2.13. NextUID Element . . . . . . . . . . . . . . . . . . . 32 81 8.2.14. NextFilename Element . . . . . . . . . . . . . . . . 32 82 8.2.15. SegmentFamily Element . . . . . . . . . . . . . . . . 33 83 8.2.16. ChapterTranslate Element . . . . . . . . . . . . . . 33 84 8.2.17. ChapterTranslateEditionUID Element . . . . . . . . . 33 85 8.2.18. ChapterTranslateCodec Element . . . . . . . . . . . . 34 86 8.2.19. ChapterTranslateID Element . . . . . . . . . . . . . 34 87 8.2.20. TimecodeScale Element . . . . . . . . . . . . . . . . 35 88 8.2.21. Duration Element . . . . . . . . . . . . . . . . . . 35 89 8.2.22. DateUTC Element . . . . . . . . . . . . . . . . . . . 35 90 8.2.23. Title Element . . . . . . . . . . . . . . . . . . . . 36 91 8.2.24. MuxingApp Element . . . . . . . . . . . . . . . . . . 36 92 8.2.25. WritingApp Element . . . . . . . . . . . . . . . . . 37 93 8.2.26. Cluster Element . . . . . . . . . . . . . . . . . . . 37 94 8.2.27. Timecode Element . . . . . . . . . . . . . . . . . . 37 95 8.2.28. SilentTracks Element . . . . . . . . . . . . . . . . 38 96 8.2.29. SilentTrackNumber Element . . . . . . . . . . . . . . 38 97 8.2.30. Position Element . . . . . . . . . . . . . . . . . . 38 98 8.2.31. PrevSize Element . . . . . . . . . . . . . . . . . . 39 99 8.2.32. SimpleBlock Element . . . . . . . . . . . . . . . . . 39 100 8.2.33. BlockGroup Element . . . . . . . . . . . . . . . . . 40 101 8.2.34. Block Element . . . . . . . . . . . . . . . . . . . . 40 102 8.2.35. BlockVirtual Element . . . . . . . . . . . . . . . . 40 103 8.2.36. BlockAdditions Element . . . . . . . . . . . . . . . 41 104 8.2.37. BlockMore Element . . . . . . . . . . . . . . . . . . 41 105 8.2.38. BlockAddID Element . . . . . . . . . . . . . . . . . 41 106 8.2.39. BlockAdditional Element . . . . . . . . . . . . . . . 42 107 8.2.40. BlockDuration Element . . . . . . . . . . . . . . . . 42 108 8.2.41. ReferencePriority Element . . . . . . . . . . . . . . 43 109 8.2.42. ReferenceBlock Element . . . . . . . . . . . . . . . 43 110 8.2.43. ReferenceVirtual Element . . . . . . . . . . . . . . 44 111 8.2.44. CodecState Element . . . . . . . . . . . . . . . . . 44 112 8.2.45. DiscardPadding Element . . . . . . . . . . . . . . . 44 113 8.2.46. Slices Element . . . . . . . . . . . . . . . . . . . 45 114 8.2.47. TimeSlice Element . . . . . . . . . . . . . . . . . . 45 115 8.2.48. LaceNumber Element . . . . . . . . . . . . . . . . . 45 116 8.2.49. FrameNumber Element . . . . . . . . . . . . . . . . . 46 117 8.2.50. BlockAdditionID Element . . . . . . . . . . . . . . . 46 118 8.2.51. Delay Element . . . . . . . . . . . . . . . . . . . . 47 119 8.2.52. SliceDuration Element . . . . . . . . . . . . . . . . 47 120 8.2.53. ReferenceFrame Element . . . . . . . . . . . . . . . 48 121 8.2.54. ReferenceOffset Element . . . . . . . . . . . . . . . 48 122 8.2.55. ReferenceTimeCode Element . . . . . . . . . . . . . . 48 123 8.2.56. EncryptedBlock Element . . . . . . . . . . . . . . . 49 124 8.2.57. Tracks Element . . . . . . . . . . . . . . . . . . . 49 125 8.2.58. TrackEntry Element . . . . . . . . . . . . . . . . . 50 126 8.2.59. TrackNumber Element . . . . . . . . . . . . . . . . . 50 127 8.2.60. TrackUID Element . . . . . . . . . . . . . . . . . . 50 128 8.2.61. TrackType Element . . . . . . . . . . . . . . . . . . 51 129 8.2.62. FlagEnabled Element . . . . . . . . . . . . . . . . . 51 130 8.2.63. FlagDefault Element . . . . . . . . . . . . . . . . . 52 131 8.2.64. FlagForced Element . . . . . . . . . . . . . . . . . 52 132 8.2.65. FlagLacing Element . . . . . . . . . . . . . . . . . 53 133 8.2.66. MinCache Element . . . . . . . . . . . . . . . . . . 53 134 8.2.67. MaxCache Element . . . . . . . . . . . . . . . . . . 54 135 8.2.68. DefaultDuration Element . . . . . . . . . . . . . . . 54 136 8.2.69. DefaultDecodedFieldDuration Element . . . . . . . . . 54 137 8.2.70. TrackTimecodeScale Element . . . . . . . . . . . . . 55 138 8.2.71. TrackOffset Element . . . . . . . . . . . . . . . . . 55 139 8.2.72. MaxBlockAdditionID Element . . . . . . . . . . . . . 56 140 8.2.73. Name Element . . . . . . . . . . . . . . . . . . . . 56 141 8.2.74. Language Element . . . . . . . . . . . . . . . . . . 57 142 8.2.75. LanguageIETF Element . . . . . . . . . . . . . . . . 57 143 8.2.76. CodecID Element . . . . . . . . . . . . . . . . . . . 57 144 8.2.77. CodecPrivate Element . . . . . . . . . . . . . . . . 58 145 8.2.78. CodecName Element . . . . . . . . . . . . . . . . . . 58 146 8.2.79. AttachmentLink Element . . . . . . . . . . . . . . . 58 147 8.2.80. CodecSettings Element . . . . . . . . . . . . . . . . 59 148 8.2.81. CodecInfoURL Element . . . . . . . . . . . . . . . . 59 149 8.2.82. CodecDownloadURL Element . . . . . . . . . . . . . . 60 150 8.2.83. CodecDecodeAll Element . . . . . . . . . . . . . . . 60 151 8.2.84. TrackOverlay Element . . . . . . . . . . . . . . . . 60 152 8.2.85. CodecDelay Element . . . . . . . . . . . . . . . . . 61 153 8.2.86. SeekPreRoll Element . . . . . . . . . . . . . . . . . 61 154 8.2.87. TrackTranslate Element . . . . . . . . . . . . . . . 62 155 8.2.88. TrackTranslateEditionUID Element . . . . . . . . . . 62 156 8.2.89. TrackTranslateCodec Element . . . . . . . . . . . . . 62 157 8.2.90. TrackTranslateTrackID Element . . . . . . . . . . . . 63 158 8.2.91. Video Element . . . . . . . . . . . . . . . . . . . . 63 159 8.2.92. FlagInterlaced Element . . . . . . . . . . . . . . . 63 160 8.2.93. FieldOrder Element . . . . . . . . . . . . . . . . . 64 161 8.2.94. StereoMode Element . . . . . . . . . . . . . . . . . 64 162 8.2.95. AlphaMode Element . . . . . . . . . . . . . . . . . . 65 163 8.2.96. OldStereoMode Element . . . . . . . . . . . . . . . . 65 164 8.2.97. PixelWidth Element . . . . . . . . . . . . . . . . . 66 165 8.2.98. PixelHeight Element . . . . . . . . . . . . . . . . . 66 166 8.2.99. PixelCropBottom Element . . . . . . . . . . . . . . . 66 167 8.2.100. PixelCropTop Element . . . . . . . . . . . . . . . . 67 168 8.2.101. PixelCropLeft Element . . . . . . . . . . . . . . . 67 169 8.2.102. PixelCropRight Element . . . . . . . . . . . . . . . 68 170 8.2.103. DisplayWidth Element . . . . . . . . . . . . . . . . 68 171 8.2.104. DisplayHeight Element . . . . . . . . . . . . . . . 68 172 8.2.105. DisplayUnit Element . . . . . . . . . . . . . . . . 69 173 8.2.106. AspectRatioType Element . . . . . . . . . . . . . . 69 174 8.2.107. ColourSpace Element . . . . . . . . . . . . . . . . 70 175 8.2.108. GammaValue Element . . . . . . . . . . . . . . . . . 70 176 8.2.109. FrameRate Element . . . . . . . . . . . . . . . . . 71 177 8.2.110. Colour Element . . . . . . . . . . . . . . . . . . . 71 178 8.2.111. MatrixCoefficients Element . . . . . . . . . . . . . 71 179 8.2.112. BitsPerChannel Element . . . . . . . . . . . . . . . 72 180 8.2.113. ChromaSubsamplingHorz Element . . . . . . . . . . . 72 181 8.2.114. ChromaSubsamplingVert Element . . . . . . . . . . . 73 182 8.2.115. CbSubsamplingHorz Element . . . . . . . . . . . . . 73 183 8.2.116. CbSubsamplingVert Element . . . . . . . . . . . . . 73 184 8.2.117. ChromaSitingHorz Element . . . . . . . . . . . . . . 74 185 8.2.118. ChromaSitingVert Element . . . . . . . . . . . . . . 74 186 8.2.119. Range Element . . . . . . . . . . . . . . . . . . . 75 187 8.2.120. TransferCharacteristics Element . . . . . . . . . . 75 188 8.2.121. Primaries Element . . . . . . . . . . . . . . . . . 75 189 8.2.122. MaxCLL Element . . . . . . . . . . . . . . . . . . . 76 190 8.2.123. MaxFALL Element . . . . . . . . . . . . . . . . . . 76 191 8.2.124. MasteringMetadata Element . . . . . . . . . . . . . 77 192 8.2.125. PrimaryRChromaticityX Element . . . . . . . . . . . 77 193 8.2.126. PrimaryRChromaticityY Element . . . . . . . . . . . 77 194 8.2.127. PrimaryGChromaticityX Element . . . . . . . . . . . 78 195 8.2.128. PrimaryGChromaticityY Element . . . . . . . . . . . 78 196 8.2.129. PrimaryBChromaticityX Element . . . . . . . . . . . 79 197 8.2.130. PrimaryBChromaticityY Element . . . . . . . . . . . 79 198 8.2.131. WhitePointChromaticityX Element . . . . . . . . . . 79 199 8.2.132. WhitePointChromaticityY Element . . . . . . . . . . 80 200 8.2.133. LuminanceMax Element . . . . . . . . . . . . . . . . 80 201 8.2.134. LuminanceMin Element . . . . . . . . . . . . . . . . 81 202 8.2.135. Projection Element . . . . . . . . . . . . . . . . . 81 203 8.2.136. ProjectionType Element . . . . . . . . . . . . . . . 81 204 8.2.137. ProjectionPrivate Element . . . . . . . . . . . . . 82 205 8.2.138. ProjectionPoseYaw Element . . . . . . . . . . . . . 82 206 8.2.139. ProjectionPosePitch Element . . . . . . . . . . . . 83 207 8.2.140. ProjectionPoseRoll Element . . . . . . . . . . . . . 84 208 8.2.141. Audio Element . . . . . . . . . . . . . . . . . . . 84 209 8.2.142. SamplingFrequency Element . . . . . . . . . . . . . 84 210 8.2.143. OutputSamplingFrequency Element . . . . . . . . . . 85 211 8.2.144. Channels Element . . . . . . . . . . . . . . . . . . 85 212 8.2.145. ChannelPositions Element . . . . . . . . . . . . . . 86 213 8.2.146. BitDepth Element . . . . . . . . . . . . . . . . . . 86 214 8.2.147. TrackOperation Element . . . . . . . . . . . . . . . 87 215 8.2.148. TrackCombinePlanes Element . . . . . . . . . . . . . 87 216 8.2.149. TrackPlane Element . . . . . . . . . . . . . . . . . 87 217 8.2.150. TrackPlaneUID Element . . . . . . . . . . . . . . . 88 218 8.2.151. TrackPlaneType Element . . . . . . . . . . . . . . . 88 219 8.2.152. TrackJoinBlocks Element . . . . . . . . . . . . . . 89 220 8.2.153. TrackJoinUID Element . . . . . . . . . . . . . . . . 89 221 8.2.154. TrickTrackUID Element . . . . . . . . . . . . . . . 89 222 8.2.155. TrickTrackSegmentUID Element . . . . . . . . . . . . 90 223 8.2.156. TrickTrackFlag Element . . . . . . . . . . . . . . . 90 224 8.2.157. TrickMasterTrackUID Element . . . . . . . . . . . . 91 225 8.2.158. TrickMasterTrackSegmentUID Element . . . . . . . . . 91 226 8.2.159. ContentEncodings Element . . . . . . . . . . . . . . 91 227 8.2.160. ContentEncoding Element . . . . . . . . . . . . . . 92 228 8.2.161. ContentEncodingOrder Element . . . . . . . . . . . . 92 229 8.2.162. ContentEncodingScope Element . . . . . . . . . . . . 93 230 8.2.163. ContentEncodingType Element . . . . . . . . . . . . 93 231 8.2.164. ContentCompression Element . . . . . . . . . . . . . 94 232 8.2.165. ContentCompAlgo Element . . . . . . . . . . . . . . 94 233 8.2.166. ContentCompSettings Element . . . . . . . . . . . . 95 234 8.2.167. ContentEncryption Element . . . . . . . . . . . . . 95 235 8.2.168. ContentEncAlgo Element . . . . . . . . . . . . . . . 95 236 8.2.169. ContentEncKeyID Element . . . . . . . . . . . . . . 96 237 8.2.170. ContentSignature Element . . . . . . . . . . . . . . 96 238 8.2.171. ContentSigKeyID Element . . . . . . . . . . . . . . 97 239 8.2.172. ContentSigAlgo Element . . . . . . . . . . . . . . . 97 240 8.2.173. ContentSigHashAlgo Element . . . . . . . . . . . . . 97 241 8.2.174. Cues Element . . . . . . . . . . . . . . . . . . . . 98 242 8.2.175. CuePoint Element . . . . . . . . . . . . . . . . . . 98 243 8.2.176. CueTime Element . . . . . . . . . . . . . . . . . . 99 244 8.2.177. CueTrackPositions Element . . . . . . . . . . . . . 99 245 8.2.178. CueTrack Element . . . . . . . . . . . . . . . . . . 99 246 8.2.179. CueClusterPosition Element . . . . . . . . . . . . . 100 247 8.2.180. CueRelativePosition Element . . . . . . . . . . . . 100 248 8.2.181. CueDuration Element . . . . . . . . . . . . . . . . 101 249 8.2.182. CueBlockNumber Element . . . . . . . . . . . . . . . 101 250 8.2.183. CueCodecState Element . . . . . . . . . . . . . . . 101 251 8.2.184. CueReference Element . . . . . . . . . . . . . . . . 102 252 8.2.185. CueRefTime Element . . . . . . . . . . . . . . . . . 102 253 8.2.186. CueRefCluster Element . . . . . . . . . . . . . . . 102 254 8.2.187. CueRefNumber Element . . . . . . . . . . . . . . . . 103 255 8.2.188. CueRefCodecState Element . . . . . . . . . . . . . . 103 256 8.2.189. Attachments Element . . . . . . . . . . . . . . . . 104 257 8.2.190. AttachedFile Element . . . . . . . . . . . . . . . . 104 258 8.2.191. FileDescription Element . . . . . . . . . . . . . . 105 259 8.2.192. FileName Element . . . . . . . . . . . . . . . . . . 105 260 8.2.193. FileMimeType Element . . . . . . . . . . . . . . . . 105 261 8.2.194. FileData Element . . . . . . . . . . . . . . . . . . 106 262 8.2.195. FileUID Element . . . . . . . . . . . . . . . . . . 106 263 8.2.196. FileReferral Element . . . . . . . . . . . . . . . . 106 264 8.2.197. FileUsedStartTime Element . . . . . . . . . . . . . 107 265 8.2.198. FileUsedEndTime Element . . . . . . . . . . . . . . 107 266 8.2.199. Chapters Element . . . . . . . . . . . . . . . . . . 108 267 8.2.200. EditionEntry Element . . . . . . . . . . . . . . . . 108 268 8.2.201. EditionUID Element . . . . . . . . . . . . . . . . . 108 269 8.2.202. EditionFlagHidden Element . . . . . . . . . . . . . 109 270 8.2.203. EditionFlagDefault Element . . . . . . . . . . . . . 109 271 8.2.204. EditionFlagOrdered Element . . . . . . . . . . . . . 110 272 8.2.205. ChapterAtom Element . . . . . . . . . . . . . . . . 110 273 8.2.206. ChapterUID Element . . . . . . . . . . . . . . . . . 110 274 8.2.207. ChapterStringUID Element . . . . . . . . . . . . . . 111 275 8.2.208. ChapterTimeStart Element . . . . . . . . . . . . . . 111 276 8.2.209. ChapterTimeEnd Element . . . . . . . . . . . . . . . 112 277 8.2.210. ChapterFlagHidden Element . . . . . . . . . . . . . 112 278 8.2.211. ChapterFlagEnabled Element . . . . . . . . . . . . . 113 279 8.2.212. ChapterSegmentUID Element . . . . . . . . . . . . . 113 280 8.2.213. ChapterSegmentEditionUID Element . . . . . . . . . . 114 281 8.2.214. ChapterPhysicalEquiv Element . . . . . . . . . . . . 114 282 8.2.215. ChapterTrack Element . . . . . . . . . . . . . . . . 114 283 8.2.216. ChapterTrackNumber Element . . . . . . . . . . . . . 115 284 8.2.217. ChapterDisplay Element . . . . . . . . . . . . . . . 115 285 8.2.218. ChapString Element . . . . . . . . . . . . . . . . . 116 286 8.2.219. ChapLanguage Element . . . . . . . . . . . . . . . . 116 287 8.2.220. ChapLanguageIETF Element . . . . . . . . . . . . . . 116 288 8.2.221. ChapCountry Element . . . . . . . . . . . . . . . . 117 289 8.2.222. ChapProcess Element . . . . . . . . . . . . . . . . 117 290 8.2.223. ChapProcessCodecID Element . . . . . . . . . . . . . 118 291 8.2.224. ChapProcessPrivate Element . . . . . . . . . . . . . 118 292 8.2.225. ChapProcessCommand Element . . . . . . . . . . . . . 118 293 8.2.226. ChapProcessTime Element . . . . . . . . . . . . . . 119 294 8.2.227. ChapProcessData Element . . . . . . . . . . . . . . 119 295 8.2.228. Tags Element . . . . . . . . . . . . . . . . . . . . 120 296 8.2.229. Tag Element . . . . . . . . . . . . . . . . . . . . 120 297 8.2.230. Targets Element . . . . . . . . . . . . . . . . . . 120 298 8.2.231. TargetTypeValue Element . . . . . . . . . . . . . . 121 299 8.2.232. TargetType Element . . . . . . . . . . . . . . . . . 121 300 8.2.233. TagTrackUID Element . . . . . . . . . . . . . . . . 122 301 8.2.234. TagEditionUID Element . . . . . . . . . . . . . . . 122 302 8.2.235. TagChapterUID Element . . . . . . . . . . . . . . . 122 303 8.2.236. TagAttachmentUID Element . . . . . . . . . . . . . . 123 304 8.2.237. SimpleTag Element . . . . . . . . . . . . . . . . . 123 305 8.2.238. TagName Element . . . . . . . . . . . . . . . . . . 123 306 8.2.239. TagLanguage Element . . . . . . . . . . . . . . . . 124 307 8.2.240. TagLanguageIETF Element . . . . . . . . . . . . . . 124 308 8.2.241. TagDefault Element . . . . . . . . . . . . . . . . . 125 309 8.2.242. TagString Element . . . . . . . . . . . . . . . . . 125 310 8.2.243. TagBinary Element . . . . . . . . . . . . . . . . . 126 311 9. Matroska Element Ordering Guidelines . . . . . . . . . . . . 126 312 9.1. Top-Level Elements . . . . . . . . . . . . . . . . . . . 126 313 9.2. CRC-32 . . . . . . . . . . . . . . . . . . . . . . . . . 127 314 9.3. SeekHead . . . . . . . . . . . . . . . . . . . . . . . . 127 315 9.4. Cues (index) . . . . . . . . . . . . . . . . . . . . . . 127 316 9.5. Info . . . . . . . . . . . . . . . . . . . . . . . . . . 127 317 9.6. Chapters . . . . . . . . . . . . . . . . . . . . . . . . 128 318 9.7. Attachments . . . . . . . . . . . . . . . . . . . . . . . 128 319 9.8. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 128 320 9.9. Optimum layout from a muxer . . . . . . . . . . . . . . . 128 321 9.10. Optimum layout after editing tags . . . . . . . . . . . . 129 322 9.11. Optimum layout with Cues at the front . . . . . . . . . . 129 323 9.12. Cluster Timecode . . . . . . . . . . . . . . . . . . . . 129 324 10. Chapters . . . . . . . . . . . . . . . . . . . . . . . . . . 130 325 10.1. Edition and Chapter Flags . . . . . . . . . . . . . . . 130 326 10.1.1. Chapter Flags . . . . . . . . . . . . . . . . . . . 130 327 10.1.2. Edition Flags . . . . . . . . . . . . . . . . . . . 130 328 10.2. Menu features . . . . . . . . . . . . . . . . . . . . . 132 329 10.2.1. Matroska Script (0) . . . . . . . . . . . . . . . . 132 330 10.2.2. DVD menu (1) . . . . . . . . . . . . . . . . . . . . 133 331 10.3. Example 1 : basic chaptering . . . . . . . . . . . . . . 134 332 10.4. Example 2 : nested chapters . . . . . . . . . . . . . . 136 333 10.4.1. The Micronauts "Bleep To Bleep" . . . . . . . . . . 136 334 11. Attachments . . . . . . . . . . . . . . . . . . . . . . . . . 139 335 11.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 139 336 11.2. Cover Art . . . . . . . . . . . . . . . . . . . . . . . 139 337 12. Cues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 338 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 140 339 12.2. Recommendations . . . . . . . . . . . . . . . . . . . . 140 340 13. Matroska Streaming . . . . . . . . . . . . . . . . . . . . . 141 341 13.1. File Access . . . . . . . . . . . . . . . . . . . . . . 141 342 13.2. Livestreaming . . . . . . . . . . . . . . . . . . . . . 142 343 14. Menu Specifications . . . . . . . . . . . . . . . . . . . . . 142 344 14.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 142 345 14.2. Requirements . . . . . . . . . . . . . . . . . . . . . . 143 346 14.2.1. Highlights/Hotspots . . . . . . . . . . . . . . . . 143 347 14.2.2. Playback features . . . . . . . . . . . . . . . . . 144 348 14.2.3. Player requirements . . . . . . . . . . . . . . . . 144 349 14.3. Working Graph . . . . . . . . . . . . . . . . . . . . . 144 350 14.4. Ideas . . . . . . . . . . . . . . . . . . . . . . . . . 145 351 14.5. Data Structure . . . . . . . . . . . . . . . . . . . . . 145 352 15. Unknown elements . . . . . . . . . . . . . . . . . . . . . . 145 353 16. Default Values . . . . . . . . . . . . . . . . . . . . . . . 145 354 17. DefaultDecodedFieldDuration . . . . . . . . . . . . . . . . . 145 355 18. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 146 356 19. Image cropping . . . . . . . . . . . . . . . . . . . . . . . 147 357 20. Matroska versioning . . . . . . . . . . . . . . . . . . . . . 147 358 21. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . 148 359 22. Segment Position . . . . . . . . . . . . . . . . . . . . . . 148 360 22.1. Segment Position Exception . . . . . . . . . . . . . . . 148 361 22.2. Example of Segment Position . . . . . . . . . . . . . . 148 362 23. Linked Segments . . . . . . . . . . . . . . . . . . . . . . . 149 363 23.1. Hard Linking . . . . . . . . . . . . . . . . . . . . . . 149 364 23.2. Medium Linking . . . . . . . . . . . . . . . . . . . . . 150 365 23.3. Soft Linking . . . . . . . . . . . . . . . . . . . . . . 150 366 24. Track Flags . . . . . . . . . . . . . . . . . . . . . . . . . 151 367 24.1. Default flag . . . . . . . . . . . . . . . . . . . . . . 151 368 24.2. Forced flag . . . . . . . . . . . . . . . . . . . . . . 151 369 24.3. Track Operation . . . . . . . . . . . . . . . . . . . . 151 370 24.4. Overlay Track . . . . . . . . . . . . . . . . . . . . . 152 371 24.5. Multi-planar and 3D videos . . . . . . . . . . . . . . . 152 372 25. Timecodes . . . . . . . . . . . . . . . . . . . . . . . . . . 153 373 25.1. Timecode Types . . . . . . . . . . . . . . . . . . . . . 153 374 25.2. Block Timecodes . . . . . . . . . . . . . . . . . . . . 153 375 25.3. Raw Timecode . . . . . . . . . . . . . . . . . . . . . . 153 376 25.4. TimecodeScale . . . . . . . . . . . . . . . . . . . . . 153 377 25.5. TimecodeScale Rounding . . . . . . . . . . . . . . . . . 154 378 25.6. TrackTimecodeScale . . . . . . . . . . . . . . . . . . . 156 379 26.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 157 380 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 158 382 1. Introduction 384 Matroska aims to become THE standard of multimedia container formats. 385 It was derived from a project called MCF [1], but differentiates from 386 it significantly because it is based on EBML [2] (Extensible Binary 387 Meta Language), a binary derivative of XML. EBML enables significant 388 advantages in terms of future format extensibility, without breaking 389 file support in old parsers. 391 First, it is essential to clarify exactly "What an Audio/Video 392 container is", to avoid any misunderstandings: 394 o It is NOT a video or audio compression format (codec) 396 o It is an envelope for which there can be many audio, video and 397 subtitles streams, allowing the user to store a complete movie or 398 CD in a single file. 400 Matroska is designed with the future in mind. It incorporates 401 features like: 403 o Fast seeking in the file 405 o Chapter entries 407 o Full metadata (tags) support 409 o Selectable subtitle/audio/video streams 411 o Modularly expandable 413 o Error resilience (can recover playback even when the stream is 414 damaged) 416 o Streamable over the internet and local networks (HTTP, CIFS, FTP, 417 etc) 419 o Menus (like DVDs have) 421 Matroska is an open standards project. This means for personal use 422 it is absolutely free to use and that the technical specifications 423 describing the bitstream are open to everybody, even to companies 424 that would like to support it in their products. 426 2. Status of this document 428 This document is a work-in-progress specification defining the 429 Matroska file format as part of the IETF Cellar working group [3]. 430 But since it's quite complete it is used as a reference for the 431 development of libmatroska. Legacy versions of the specification can 432 be found here [4] (PDF doc by Alexander Noe -- outdated). 434 For a simplified diagram of the layout of a Matroska file, see the 435 Diagram page [5]. 437 A more refined and detailed version of the EBML specifications is 438 being worked on here [6]. 440 The table found below is now generated from the "source" of the 441 Matroska specification. This XML file [7] is also used to generate 442 the semantic data used in libmatroska and libmatroska2. We encourage 443 anyone to use and monitor its changes so your code is spec-proof and 444 always up to date. 446 Note that versions 1, 2 and 3 have been finalized. Version 4 is 447 currently work in progress. There MAY be further additions to v4. 449 3. Security Considerations 451 Matroska inherits security considerations from EBML. 453 Attacks on a "Matroska Reader" could include: 455 o Storage of a arbitrary and potentially executable data within an 456 "Attachment Element". "Matroska Readers" that extract or use data 457 from Matroska Attachments SHOULD check that the data adheres to 458 expectations. 460 o A "Matroska Attachment" with an inaccurate mime-type. 462 4. IANA Considerations 464 To be determined. 466 5. Notation and Conventions 468 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 469 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 470 document are to be interpreted as described in RFC 2119 [8]. 472 This document defines specific terms in order to define the format 473 and application of "Matroska". Specific terms are defined below: 475 "Matroska": a multimedia container format based on EBML (Extensible 476 Binary Meta Language) 478 "Matroska Reader": A "Matroska Reader" is a data parser that 479 interprets the semantics of a Matroska document and creates a way for 480 programs to use "Matroska". 482 "Matroska Player": A "Matroska Player" is a "Matroska Reader" with a 483 primary purpose of playing audiovisual files, including "Matroska" 484 documents. 486 6. Basis in EBML 488 Matroska is a Document Type of EBML (Extensible Binary Meta 489 Language). This specification is dependent on the EBML Specification 490 [9]. For an understanding of Matroska's EBML Schema, see in 491 particular the sections of the EBML Specification covering EBML 492 Element Types [10], EBML Schema [11], and EBML Structure [12]. 494 6.1. Added Constraints on EBML 496 As an EBML Document Type, Matroska adds the following constraints to 497 the EBML specification. 499 o The "docType" of the "EBML Header" MUST be 'matroska'. 501 o The "EBMLMaxIDLength" of the "EBML Header" MUST be "4". 503 o The "EBMLMaxSizeLength" of the "EBML Header" MUST be between "1" 504 and "8" inclusive. 506 6.2. Matroska Design 508 All top-levels elements (Segment and direct sub-elements) are coded 509 on 4 octets, i.e. class D elements. 511 6.2.1. Language Codes 513 Matroska from version 1 through 3 uses language codes that can be 514 either the 3 letters bibliographic ISO-639-2 [13] form (like "fre" 515 for french), or such a language code followed by a dash and a country 516 code for specialities in languages (like "fre-ca" for Canadian 517 French). The "ISO 639-2 Language Elements" are "Language Element", 518 "TagLanguage Element", and "ChapLanguage Element". 520 Starting in Matroska version 4, either "ISO 639-2" or BCP 47 [14] MAY 521 be used, although "BCP 47" is RECOMMENDED. The "BCP 47 Language 522 Elements" are "LanguageIETF Element", "TagLanguageIETF Element", and 523 "ChapLanguageIETF Element". If a "BCP 47 Language Element" and an 524 "ISO 639-2 Language Element" are used within the same "Parent 525 Element", then the "ISO 639-2 Language Element" MUST be ignored and 526 precedence given to the "BCP 47 Language Element". 528 Country codes are the same as used for internet domains [15]. 530 6.2.2. Physical Types 532 Each level can have different meanings for audio and video. The 533 ORIGINAL_MEDIUM tag can be used to specify a string for 534 ChapterPhysicalEquiv = 60. Here is the list of possible levels for 535 both audio and video : 537 +----------------------+--------------+-----------+-----------------+ 538 | ChapterPhysicalEquiv | Audio | Video | Comment | 539 +----------------------+--------------+-----------+-----------------+ 540 | 70 | SET / | SET / | the collection | 541 | | PACKAGE | PACKAGE | of different | 542 | | | | media | 543 | 60 | CD / 12" / | DVD / VHS | the physical | 544 | | 10" / 7" / | / | medium like a | 545 | | TAPE / | LASERDISC | CD or a DVD | 546 | | MINIDISC / | | | 547 | | DAT | | | 548 | 50 | SIDE | SIDE | when the | 549 | | | | original medium | 550 | | | | (LP/DVD) has | 551 | | | | different sides | 552 | 40 | - | LAYER | another | 553 | | | | physical level | 554 | | | | on DVDs | 555 | 30 | SESSION | SESSION | as found on CDs | 556 | | | | and DVDs | 557 | 20 | TRACK | - | as found on | 558 | | | | audio CDs | 559 | 10 | INDEX | - | the first | 560 | | | | logical level | 561 | | | | of the | 562 | | | | side/medium | 563 +----------------------+--------------+-----------+-----------------+ 565 6.2.3. Block Structure 567 Size = 1 + (1-8) + 4 + (4 + (4)) octets. So from 6 to 21 octets. 569 Bit 0 is the most significant bit. 571 Frames using references SHOULD be stored in "coding order". That 572 means the references first and then the frames referencing them. A 573 consequence is that timecodes MAY NOT be consecutive. But a frame 574 with a past timecode MUST reference a frame already known, otherwise 575 it's considered bad/void. 577 There can be many Blocks in a BlockGroup provided they all have the 578 same timecode. It is used with different parts of a frame with 579 different priorities. 581 6.2.3.1. Block Header 583 +--------+--------+-------------------------------------------------+ 584 | Offset | Player | Description | 585 +--------+--------+-------------------------------------------------+ 586 | 0x00+ | MUST | Track Number (Track Entry). It is coded in EBML | 587 | | | like form (1 octet if the value is < 0x80, 2 if | 588 | | | < 0x4000, etc) (most significant bits set to | 589 | | | increase the range). | 590 | 0x01+ | MUST | Timecode (relative to Cluster timecode, signed | 591 | | | int16) | 592 +--------+--------+-------------------------------------------------+ 594 6.2.3.2. Block Header Flags 596 +--------+-----+--------+-------------------------------------------+ 597 | Offset | Bit | Player | Description | 598 +--------+-----+--------+-------------------------------------------+ 599 | 0x03+ | 0-3 | - | Reserved, set to 0 | 600 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode this | 601 | | | | frame but not display it | 602 | 0x03+ | 5-6 | MUST | Lacing | 603 | | | | * 00 : no lacing | 604 | | | | * 01 : Xiph lacing | 605 | | | | * 11 : EBML lacing | 606 | | | | * 10 : fixed-size lacing | 607 | 0x03+ | 7 | - | not used | 608 +--------+-----+--------+-------------------------------------------+ 610 6.2.3.3. Laced Data 612 When lacing bit is set. 614 +--------+--------+-------------------------------------------------+ 615 | Offset | Player | Description | 616 +--------+--------+-------------------------------------------------+ 617 | 0x00 | MUST | Number of frames in the lace-1 (uint8) | 618 | 0x01 / | MUST* | Lace-coded size of each frame of the lace, | 619 | 0xXX | | except for the last one (multiple uint8). *This | 620 | | | is not used with Fixed-size lacing as it is | 621 | | | calculated automatically from (total size of | 622 | | | lace) / (number of frames in lace). | 623 +--------+--------+-------------------------------------------------+ 625 For (possibly) Laced Data 627 +--------+--------+--------------------------+ 628 | Offset | Player | Description | 629 +--------+--------+--------------------------+ 630 | 0x00 | MUST | Consecutive laced frames | 631 +--------+--------+--------------------------+ 633 6.2.4. Lacing 635 Lacing is a mechanism to save space when storing data. It is 636 typically used for small blocks of data (referred to as frames in 637 Matroska). There are 3 types of lacing: 639 1. Xiph, inspired by what is found in the Ogg container 641 2. EBML, which is the same with sizes coded differently 643 3. fixed-size, where the size is not coded 645 For example, a user wants to store 3 frames of the same track. The 646 first frame is 800 octets long, the second is 500 octets long and the 647 third is 1000 octets long. As these data are small, they can be 648 stored in a lace to save space. They will then be stored in the same 649 block as follows: 651 6.2.4.1. Xiph lacing 653 o Block head (with lacing bits set to 01) 655 o Lacing head: Number of frames in the lace -1, i.e. 2 (the 800 and 656 500 octets one) 658 o Lacing sizes: only the 2 first ones will be coded, 800 gives 659 255;255;255;35, 500 gives 255;245. The size of the last frame is 660 deduced from the total size of the Block. 662 o Data in frame 1 664 o Data in frame 2 666 o Data in frame 3 668 A frame with a size multiple of 255 is coded with a 0 at the end of 669 the size, for example 765 is coded 255;255;255;0. 671 6.2.4.2. EBML lacing 673 In this case, the size is not coded as blocks of 255 bytes, but as a 674 difference with the previous size and this size is coded as in EBML. 675 The first size in the lace is unsigned as in EBML. The others use a 676 range shifting to get a sign on each value: 678 +----------------------------------+--------------------------------+ 679 | Bit Representation | Value | 680 +----------------------------------+--------------------------------+ 681 | 1xxx xxxx | value -(2^6-1) to 2^6-1 (ie 0 | 682 | | to 2^7-2 minus 2^6-1, half of | 683 | | the range) | 684 | 01xx xxxx xxxx xxxx | value -(2^13-1) to 2^13-1 | 685 | 001x xxxx xxxx xxxx xxxx xxxx | value -(2^20-1) to 2^20-1 | 686 | 0001 xxxx xxxx xxxx xxxx xxxx | value -(2^27-1) to 2^27-1 | 687 | xxxx xxxx | | 688 | 0000 1xxx xxxx xxxx xxxx xxxx | value -(2^34-1) to 2^34-1 | 689 | xxxx xxxx xxxx xxxx | | 690 | 0000 01xx xxxx xxxx xxxx xxxx | value -(2^41-1) to 2^41-1 | 691 | xxxx xxxx xxxx xxxx xxxx xxxx | | 692 | 0000 001x xxxx xxxx xxxx xxxx | value -(2^48-1) to 2^48-1 | 693 | xxxx xxxx xxxx xxxx xxxx xxxx | | 694 | xxxx xxxx | | 695 +----------------------------------+--------------------------------+ 697 o Block head (with lacing bits set to 11) 699 o Lacing head: Number of frames in the lace -1, i.e. 2 (the 800 and 700 400 octets one) 702 o Lacing sizes: only the 2 first ones will be coded, 800 gives 0x320 703 0x4000 = 0x4320, 500 is coded as -300 : - 0x12C + 0x1FFF + 0x4000 704 = 0x5ED3. The size of the last frame is deduced from the total 705 size of the Block. 707 o Data in frame 1 709 o Data in frame 2 710 o Data in frame 3 712 6.2.4.3. Fixed-size lacing 714 In this case, only the number of frames in the lace is saved, the 715 size of each frame is deduced from the total size of the Block. For 716 example, for 3 frames of 800 octets each: 718 o Block head (with lacing bits set to 10) 720 o Lacing head: Number of frames in the lace -1, i.e. 2 722 o Data in frame 1 724 o Data in frame 2 726 o Data in frame 3 728 6.2.4.4. SimpleBlock Structure 730 The "SimpleBlock" is inspired by the Section 6.2.3. The main 731 differences are the added Keyframe flag and Discardable flag. 732 Otherwise everything is the same. 734 Size = 1 + (1-8) + 4 + (4 + (4)) octets. So from 6 to 21 octets. 736 Bit 0 is the most significant bit. 738 Frames using references SHOULD be stored in "coding order". That 739 means the references first and then the frames referencing them. A 740 consequence is that timecodes MAY NOT be consecutive. But a frame 741 with a past timecode MUST reference a frame already known, otherwise 742 it's considered bad/void. 744 There can be many "Block Elements" in a "BlockGroup" provided they 745 all have the same timecode. It is used with different parts of a 746 frame with different priorities. 748 6.2.4.4.1. SimpleBlock Header 749 +--------+--------+-------------------------------------------------+ 750 | Offset | Player | Description | 751 +--------+--------+-------------------------------------------------+ 752 | 0x00+ | MUST | Track Number (Track Entry). It is coded in EBML | 753 | | | like form (1 octet if the value is < 0x80, 2 if | 754 | | | < 0x4000, etc) (most significant bits set to | 755 | | | increase the range). | 756 | 0x01+ | MUST | Timecode (relative to Cluster timecode, signed | 757 | | | int16) | 758 +--------+--------+-------------------------------------------------+ 760 6.2.4.4.2. SimpleBlock Header Flags 762 +--------+-----+--------+-------------------------------------------+ 763 | Offset | Bit | Player | Description | 764 +--------+-----+--------+-------------------------------------------+ 765 | 0x03+ | 0 | - | Keyframe, set when the Block contains | 766 | | | | only keyframes | 767 | 0x03+ | 1-3 | - | Reserved, set to 0 | 768 | 0x03+ | 4 | - | Invisible, the codec SHOULD decode this | 769 | | | | frame but not display it | 770 | 0x03+ | 5-6 | MUST | Lacing | 771 | | | | * 00 : no lacing | 772 | | | | * 01 : Xiph lacing | 773 | | | | * 11 : EBML lacing | 774 | | | | * 10 : fixed-size lacing | 775 | 0x03+ | 7 | - | Discardable, the frames of the Block can | 776 | | | | be discarded during playing if needed | 777 +--------+-----+--------+-------------------------------------------+ 779 6.2.4.5. Laced Data 781 When lacing bit is set. 783 +--------+--------+-------------------------------------------------+ 784 | Offset | Player | Description | 785 +--------+--------+-------------------------------------------------+ 786 | 0x00 | MUST | Number of frames in the lace-1 (uint8) | 787 | 0x01 / | MUST* | Lace-coded size of each frame of the lace, | 788 | 0xXX | | except for the last one (multiple uint8). *This | 789 | | | is not used with Fixed-size lacing as it is | 790 | | | calculated automatically from (total size of | 791 | | | lace) / (number of frames in lace). | 792 +--------+--------+-------------------------------------------------+ 794 For (possibly) Laced Data 795 +--------+--------+--------------------------+ 796 | Offset | Player | Description | 797 +--------+--------+--------------------------+ 798 | 0x00 | MUST | Consecutive laced frames | 799 +--------+--------+--------------------------+ 801 7. Matroska Structure 803 A Matroska file MUST be composed of at least one "EBML Document" 804 using the "Matroska Document Type". Each "EBML Document" MUST start 805 with an "EBML Header" and MUST be followed by the "EBML Root 806 Element", defined as "Segment" in Matroska. Matroska defines several 807 "Top Level Elements" which MAY occur within the "Segment". 809 As an example, a simple Matroska file consisting of a single "EBML 810 Document" could be represented like this: 812 o "EBML Header" 814 o "Segment" 816 A more complex Matroska file consisting of an "EBML Stream" 817 (consisting of two "EBML Documents") could be represented like this: 819 o "EBML Header" 821 o "Segment" 823 o "EBML Header" 825 o "Segment" 827 The following diagram represents a simple Matroska file, comprised of 828 an "EBML Document" with an "EBML Header", a "Segment Element" (the 829 "Root Element"), and all eight Matroska "Top Level Elements". In the 830 following diagrams of this section, horizontal spacing expresses a 831 parent-child relationship between Matroska Elements (e.g. the "Info 832 Element" is contained within the "Segment Element") whereas vertical 833 alignment represents the storage order within the file. 835 +-------------+ 836 | EBML Header | 837 +---------------------------+ 838 | Segment | SeekHead | 839 | |-------------| 840 | | Info | 841 | |-------------| 842 | | Tracks | 843 | |-------------| 844 | | Chapters | 845 | |-------------| 846 | | Cluster | 847 | |-------------| 848 | | Cues | 849 | |-------------| 850 | | Attachments | 851 | |-------------| 852 | | Tags | 853 +---------------------------+ 855 The Matroska "EBML Schema" defines eight "Top Level Elements": 856 "SeekHead", "Info", "Tracks", "Chapters", "Cluster", "Cues", 857 "Attachments", and "Tags". 859 The "SeekHead Element" (also known as "MetaSeek") contains an index 860 of "Top Level Elements" locations within the "Segment". Use of the 861 "SeekHead Element" is RECOMMENDED. Without a "SeekHead Element", a 862 Matroska parser would have to search the entire file to find all of 863 the other "Top Level Elements". This is due to Matroska's flexible 864 ordering requirements; for instance, it is acceptable for the 865 "Chapters Element" to be stored after the "Cluster Elements". 867 +--------------------------------+ 868 | SeekHead | Seek | SeekID | 869 | | |--------------| 870 | | | SeekPosition | 871 +--------------------------------+ 873 Representation of a SeekHead Element. 875 The "Info Element" contains vital information for identifying the 876 whole "Segment". This includes the title for the "Segment", a 877 randomly generated unique identifier, and the unique identifier(s) of 878 any linked "Segment Elements". 880 +-------------------------+ 881 | Info | SegmentUID | 882 | |------------------| 883 | | SegmentFilename | 884 | |------------------| 885 | | PrevUID | 886 | |------------------| 887 | | PrevFilename | 888 | |------------------| 889 | | NextUID | 890 | |------------------| 891 | | NextFilename | 892 | |------------------| 893 | | SegmentFamily | 894 | |------------------| 895 | | ChapterTranslate | 896 | |------------------| 897 | | TimecodeScale | 898 | |------------------| 899 | | Duration | 900 | |------------------| 901 | | DateUTC | 902 | |------------------| 903 | | Title | 904 | |------------------| 905 | | MuxingApp | 906 | |------------------| 907 | | WritingApp | 908 |-------------------------| 910 Representation of an Info Element and its Child Elements. 912 The "Tracks Element" defines the technical details for each track and 913 can store the name, number, unique identifier, language and type 914 (audio, video, subtitles, etc.) of each track. For example, the 915 "Tracks Element" MAY store information about the resolution of a 916 video track or sample rate of an audio track. 918 The "Tracks Element" MUST identify all the data needed by the codec 919 to decode the data of the specified track. However, the data 920 required is contingent on the codec used for the track. For example, 921 a "Track Element" for uncompressed audio only requires the audio bit 922 rate to be present. A codec such as AC-3 would require that the 923 "CodecID Element" be present for all tracks, as it is the primary way 924 to identify which codec to use to decode the track. 926 +------------------------------------+ 927 | Tracks | TrackEntry | TrackNumber | 928 | | |--------------| 929 | | | TrackUID | 930 | | |--------------| 931 | | | TrackType | 932 | | |--------------| 933 | | | Name | 934 | | |--------------| 935 | | | Language | 936 | | |--------------| 937 | | | CodecID | 938 | | |--------------| 939 | | | CodecPrivate | 940 | | |--------------| 941 | | | CodecName | 942 | | |----------------------------------+ 943 | | | Video | FlagInterlaced | 944 | | | |-------------------| 945 | | | | FieldOrder | 946 | | | |-------------------| 947 | | | | StereoMode | 948 | | | |-------------------| 949 | | | | AlphaMode | 950 | | | |-------------------| 951 | | | | PixelWidth | 952 | | | |-------------------| 953 | | | | PixelHeight | 954 | | | |-------------------| 955 | | | | DisplayWidth | 956 | | | |-------------------| 957 | | | | DisplayHeight | 958 | | | |-------------------| 959 | | | | AspectRatioType | 960 | | | |-------------------| 961 | | | | Color | 962 | | |----------------------------------| 963 | | | Audio | SamplingFrequency | 964 | | | |-------------------| 965 | | | | Channels | 966 | | | |-------------------| 967 | | | | BitDepth | 968 |--------------------------------------------------------| 970 Representation of the Tracks Element and a selection of its 971 Descendant Elements. 973 The "Chapters Element" lists all of the chapters. Chapters are a way 974 to set predefined points to jump to in video or audio. 976 +-----------------------------------------+ 977 | Chapters | Edition | EditionUID | 978 | | Entry |--------------------| 979 | | | EditionFlagHidden | 980 | | |--------------------| 981 | | | EditionFlagDefault | 982 | | |--------------------| 983 | | | EditionFlagOrdered | 984 | | |--------------------------------+ 985 | | | ChapterAtom | ChapterUID | 986 | | | |------------------| 987 | | | | ChapterStringUID | 988 | | | |------------------| 989 | | | | ChapterTimeStart | 990 | | | |------------------| 991 | | | | ChapterTimeEnd | 992 | | | |------------------| 993 | | | | ChapterFlagHidden | 994 | | | |---------------------------------+ 995 | | | | ChapterDisplay | ChapString | 996 | | | | |--------------| 997 | | | | | ChapLanguage | 998 +--------------------------------------------------------------------+ 1000 Representation of the Chapters Element and a selection of its 1001 Descendant Elements. 1003 "Cluster Elements" contain the content for each track, e.g. video 1004 frames. A Matroska file SHOULD contain at least one "Cluster 1005 Element". The "Cluster Element" helps to break up "SimpleBlock" or 1006 "BlockGroup Elements" and helps with seeking and error protection. 1007 It is RECOMMENDED that the size of each individual "Cluster Element" 1008 be limited to store no more than 5 seconds or 5 megabytes. Every 1009 "Cluster Element" MUST contain a "Timecode Element". This SHOULD be 1010 the "Timecode Element" used to play the first "Block" in the "Cluster 1011 Element". There SHOULD be one or more "BlockGroup" or "SimpleBlock 1012 Element" in each "Cluster Element". A "BlockGroup Element" MAY 1013 contain a "Block" of data and any information relating directly to 1014 that "Block". 1016 +--------------------------+ 1017 | Cluster | Timecode | 1018 | |----------------| 1019 | | SilentTracks | 1020 | |----------------| 1021 | | Position | 1022 | |----------------| 1023 | | PrevSize | 1024 | |----------------| 1025 | | SimpleBlock | 1026 | |----------------| 1027 | | BlockGroup | 1028 | |----------------| 1029 | | EncryptedBlock | 1030 +--------------------------+ 1032 Representation of a Cluster Element and its immediate Child Elements. 1034 +----------------------------------+ 1035 | Block | Portion of | Data Type | 1036 | | a Block | - Bit Flag | 1037 | |--------------------------+ 1038 | | Header | TrackNumber | 1039 | | |-------------| 1040 | | | Timecode | 1041 | | |-------------| 1042 | | | Flags | 1043 | | | - Gap | 1044 | | | - Lacing | 1045 | | | - Reserved | 1046 | |--------------------------| 1047 | | Optional | FrameSize | 1048 | |--------------------------| 1049 | | Data | Frame | 1050 +----------------------------------+ 1052 Representation of the Block Element structure. 1054 Each "Cluster" MUST contain exactly one "Timecode Element". The 1055 "Timecode Element" value MUST be stored once per "Cluster". The 1056 "Timecode Element" in the "Cluster" is relative to the entire 1057 "Segment". The "Timecode Element" SHOULD be the first "Element" in 1058 the "Cluster". 1060 Additionally, the "Block" contains an offset that, when added to the 1061 "Cluster"'s "Timecode Element" value, yields the "Block"'s effective 1062 timecode. Therefore, timecode in the "Block" itself is relative to 1063 the "Timecode Element" in the "Cluster". For example, if the 1064 "Timecode Element" in the "Cluster" is set to 10 seconds and a 1065 "Block" in that "Cluster" is supposed to be played 12 seconds into 1066 the clip, the timecode in the "Block" would be set to 2 seconds. 1068 The "ReferenceBlock" in the "BlockGroup" is used instead of the basic 1069 "P-frame"/"B-frame" description. Instead of simply saying that this 1070 "Block" depends on the "Block" directly before, or directly 1071 afterwards, the "Timecode" of the necessary "Block" is used. Because 1072 there can be as many "ReferenceBlock Elements" as necessary for a 1073 "Block", it allows for some extremely complex referencing. 1075 The "Cues Element" is used to seek when playing back a file by 1076 providing a temporal index for some of the "Tracks". It is similar 1077 to the "SeekHead Element", but used for seeking to a specific time 1078 when playing back the file. It is possible to seek without this 1079 element, but it is much more difficult because a "Matroska Reader" 1080 would have to 'hunt and peck' through the file looking for the 1081 correct timecode. 1083 The "Cues Element" SHOULD contain at least one "CuePoint Element". 1084 Each "CuePoint Element" stores the position of the "Cluster" that 1085 contains the "BlockGroup" or "SimpleBlock Element". The timecode is 1086 stored in the "CueTime Element" and location is stored in the 1087 "CueTrackPositions Element". 1089 The "Cues Element" is flexible. For instance, "Cues Element" can be 1090 used to index every single timecode of every "Block" or they can be 1091 indexed selectively. For video files, it is RECOMMENDED to index at 1092 least the keyframes of the video track. 1094 +-------------------------------------+ 1095 | Cues | CuePoint | CueTime | 1096 | | |-------------------| 1097 | | | CueTrackPositions | 1098 | |------------------------------| 1099 | | CuePoint | CueTime | 1100 | | |-------------------| 1101 | | | CueTrackPositions | 1102 +-------------------------------------+ 1104 Representation of a Cues Element and two levels of its Descendant 1105 Elements. 1107 The "Attachments Element" is for attaching files to a Matroska file 1108 such as pictures, webpages, programs, or even the codec needed to 1109 play back the file. 1111 +------------------------------------------------+ 1112 | Attachments | AttachedFile | FileDescription | 1113 | | |-------------------| 1114 | | | FileName | 1115 | | |-------------------| 1116 | | | FileMimeType | 1117 | | |-------------------| 1118 | | | FileData | 1119 | | |-------------------| 1120 | | | FileUID | 1121 | | |-------------------| 1122 | | | FileName | 1123 | | |-------------------| 1124 | | | FileReferral | 1125 | | |-------------------| 1126 | | | FileUsedStartTime | 1127 | | |-------------------| 1128 | | | FileUsedEndTime | 1129 +------------------------------------------------+ 1131 Representation of a Attachments Element. 1133 The "Tags Element" contains metadata that describes the "Segment" and 1134 potentially its "Tracks", "Chapters", and "Attachments". Each 1135 "Track" or "Chapter" that those tags applies to has its UID listed in 1136 the "Tags". The "Tags" contain all extra information about the file: 1137 scriptwriter, singer, actors, directors, titles, edition, price, 1138 dates, genre, comments, etc. Tags can contain their values in 1139 multiple languages. For example, a movie's "title" "Tag" might 1140 contain both the original English title as well as the title it was 1141 released as in Germany. 1143 +-------------------------------------------+ 1144 | Tags | Tag | Targets | TargetTypeValue | 1145 | | | |------------------| 1146 | | | | TargetType | 1147 | | | |------------------| 1148 | | | | TagTrackUID | 1149 | | | |------------------| 1150 | | | | TagEditionUID | 1151 | | | |------------------| 1152 | | | | TagChapterUID | 1153 | | | |------------------| 1154 | | | | TagAttachmentUID | 1155 | | |------------------------------| 1156 | | | SimpleTag | TagName | 1157 | | | |------------------| 1158 | | | | TagLanguage | 1159 | | | |------------------| 1160 | | | | TagDefault | 1161 | | | |------------------| 1162 | | | | TagString | 1163 | | | |------------------| 1164 | | | | TagBinary | 1165 | | | |------------------| 1166 | | | | SimpleTag | 1167 +-------------------------------------------+ 1169 Representation of a Tags Element and three levels of its Children 1170 Elements. 1172 8. Matroska Schema 1174 This specification includes an "EBML Schema" which defines the 1175 Elements and structure of Matroska as an EBML Document Type. The 1176 EBML Schema defines every valid Matroska element in a manner defined 1177 by the EBML specification. 1179 8.1. Matroska Additions to Schema Element Attributes 1181 In addition to the EBML Schema definition provided by the EBML 1182 Specification, Matroska adds the following additional attributes: 1184 +-----------+----------+--------------------------------------------+ 1185 | attribute | required | definition | 1186 | name | | | 1187 +-----------+----------+--------------------------------------------+ 1188 | webm | No | A boolean to express if the Matroska | 1189 | | | Element is also supported within version 2 | 1190 | | | of the "webm" specification. Please | 1191 | | | consider the webm specification [16] as | 1192 | | | the authoritative on "webm". | 1193 +-----------+----------+--------------------------------------------+ 1195 8.2. Matroska Schema 1197 Here the definition of each Matroska Element is provided. 1199 % concatenate with Matroska EBML Schema converted to markdown % 1201 8.2.1. EBMLMaxIDLength Element 1203 name: "EBMLMaxIDLength" 1205 path: "1*1(\EBML\EBMLMaxIDLength)" 1207 id: "0x42F2" 1209 minOccurs: "1" 1211 maxOccurs: "1" 1213 range: "4" 1215 default: "4" 1217 type: "uinteger" 1219 8.2.2. EBMLMaxSizeLength Element 1221 name: "EBMLMaxSizeLength" 1223 path: "1*1(\EBML\EBMLMaxSizeLength)" 1225 id: "0x42F3" 1227 minOccurs: "1" 1229 maxOccurs: "1" 1231 range: "1-8" 1232 default: "8" 1234 type: "uinteger" 1236 8.2.3. Segment Element 1238 name: "Segment" 1240 path: "1*1(\Segment)" 1242 id: "0x18538067" 1244 minOccurs: "1" 1246 maxOccurs: "1" 1248 type: "master" 1250 unknownsizeallowed: "1" 1252 minver: "1" 1254 documentation: The Root Element that contains all other Top-Level 1255 Elements (Elements defined only at Level 1). A Matroska file is 1256 composed of 1 Segment. 1258 8.2.4. SeekHead Element 1260 name: "SeekHead" 1262 path: "0*2(\Segment\SeekHead)" 1264 id: "0x114D9B74" 1266 maxOccurs: "2" 1268 type: "master" 1270 minver: "1" 1272 documentation: Contains the Segment Position of other Top-Level 1273 Elements. 1275 8.2.5. Seek Element 1277 name: "Seek" 1279 path: "1*(\Segment\SeekHead\Seek)" 1280 id: "0x4DBB" 1282 minOccurs: "1" 1284 type: "master" 1286 minver: "1" 1288 documentation: Contains a single seek entry to an EBML Element. 1290 8.2.6. SeekID Element 1292 name: "SeekID" 1294 path: "1*1(\Segment\SeekHead\Seek\SeekID)" 1296 id: "0x53AB" 1298 minOccurs: "1" 1300 maxOccurs: "1" 1302 type: "binary" 1304 minver: "1" 1306 documentation: The binary ID corresponding to the Element name. 1308 8.2.7. SeekPosition Element 1310 name: "SeekPosition" 1312 path: "1*1(\Segment\SeekHead\Seek\SeekPosition)" 1314 id: "0x53AC" 1316 minOccurs: "1" 1318 maxOccurs: "1" 1320 type: "uinteger" 1322 minver: "1" 1324 documentation: The Segment Position of the Element. 1326 8.2.8. Info Element 1328 name: "Info" 1330 path: "1*(\Segment\Info)" 1332 id: "0x1549A966" 1334 minOccurs: "1" 1336 type: "master" 1338 minver: "1" 1340 definition: Contains general information about the Segment. 1342 8.2.9. SegmentUID Element 1344 name: "SegmentUID" 1346 path: "0*1(\Segment\Info\SegmentUID)" 1348 id: "0x73A4" 1350 maxOccurs: "1" 1352 range: "not 0" 1354 size: "16" 1356 type: "binary" 1358 minver: "1" 1360 definition: A randomly generated unique ID to identify the Segment 1361 amongst many others (128 bits). 1363 usage notes: If the Segment is a part of a Linked Segment then this 1364 Element is REQUIRED. 1366 8.2.10. SegmentFilename Element 1368 name: "SegmentFilename" 1370 path: "0*1(\Segment\Info\SegmentFilename)" 1372 id: "0x7384" 1373 maxOccurs: "1" 1375 type: "utf-8" 1377 minver: "1" 1379 definition: A filename corresponding to this Segment. 1381 8.2.11. PrevUID Element 1383 name: "PrevUID" 1385 path: "0*1(\Segment\Info\PrevUID)" 1387 id: "0x3CB923" 1389 maxOccurs: "1" 1391 size: "16" 1393 type: "binary" 1395 minver: "1" 1397 definition: A unique ID to identify the previous Segment of a Linked 1398 Segment (128 bits). 1400 usage notes: If the Segment is a part of a Linked Segment that uses 1401 Hard Linking then either the PrevUID or the NextUID Element is 1402 REQUIRED. If a Segment contains a PrevUID but not a NextUID then it 1403 MAY be considered as the last Segment of the Linked Segment. The 1404 PrevUID MUST NOT be equal to the SegmentUID. 1406 8.2.12. PrevFilename Element 1408 name: "PrevFilename" 1410 path: "0*1(\Segment\Info\PrevFilename)" 1412 id: "0x3C83AB" 1414 maxOccurs: "1" 1416 type: "utf-8" 1418 minver: "1" 1419 definition: A filename corresponding to the file of the previous 1420 Linked Segment. 1422 usage notes: Provision of the previous filename is for display 1423 convenience, but PrevUID SHOULD be considered authoritative for 1424 identifying the previous Segment in a Linked Segment. 1426 8.2.13. NextUID Element 1428 name: "NextUID" 1430 path: "0*1(\Segment\Info\NextUID)" 1432 id: "0x3EB923" 1434 maxOccurs: "1" 1436 size: "16" 1438 type: "binary" 1440 minver: "1" 1442 definition: A unique ID to identify the next Segment of a Linked 1443 Segment (128 bits). 1445 usage notes: If the Segment is a part of a Linked Segment that uses 1446 Hard Linking then either the PrevUID or the NextUID Element is 1447 REQUIRED. If a Segment contains a NextUID but not a PrevUID then it 1448 MAY be considered as the first Segment of the Linked Segment. The 1449 NextUID MUST NOT be equal to the SegmentUID. 1451 8.2.14. NextFilename Element 1453 name: "NextFilename" 1455 path: "0*1(\Segment\Info\NextFilename)" 1457 id: "0x3E83BB" 1459 maxOccurs: "1" 1461 type: "utf-8" 1463 minver: "1" 1465 definition: A filename corresponding to the file of the next Linked 1466 Segment. 1468 usage notes: Provision of the next filename is for display 1469 convenience, but NextUID SHOULD be considered authoritative for 1470 identifying the Next Segment. 1472 8.2.15. SegmentFamily Element 1474 name: "SegmentFamily" 1476 path: "0*(\Segment\Info\SegmentFamily)" 1478 id: "0x4444" 1480 size: "16" 1482 type: "binary" 1484 minver: "1" 1486 definition: A randomly generated unique ID that all Segments of a 1487 Linked Segment MUST share (128 bits). 1489 usage notes: If the Segment is a part of a Linked Segment that uses 1490 Soft Linking then this Element is REQUIRED. 1492 8.2.16. ChapterTranslate Element 1494 name: "ChapterTranslate" 1496 path: "0*(\Segment\Info\ChapterTranslate)" 1498 id: "0x6924" 1500 type: "master" 1502 minver: "1" 1504 documentation: A tuple of corresponding ID used by chapter codecs to 1505 represent this Segment. 1507 8.2.17. ChapterTranslateEditionUID Element 1509 name: "ChapterTranslateEditionUID" 1511 path: "0*(\Segment\Info\ChapterTranslate\ChapterTranslateEditionUID)" 1513 id: "0x69FC" 1515 type: "uinteger" 1516 minver: "1" 1518 documentation: Specify an edition UID on which this correspondance 1519 applies. When not specified, it means for all editions found in the 1520 Segment. 1522 8.2.18. ChapterTranslateCodec Element 1524 name: "ChapterTranslateCodec" 1526 path: "1*1(\Segment\Info\ChapterTranslate\ChapterTranslateCodec)" 1528 id: "0x69BF" 1530 minOccurs: "1" 1532 maxOccurs: "1" 1534 type: "uinteger" 1536 minver: "1" 1538 documentation: The chapter codec 1540 8.2.19. ChapterTranslateID Element 1542 name: "ChapterTranslateID" 1544 path: "1*1(\Segment\Info\ChapterTranslate\ChapterTranslateID)" 1546 id: "0x69A5" 1548 minOccurs: "1" 1550 maxOccurs: "1" 1552 type: "binary" 1554 minver: "1" 1556 documentation: The binary value used to represent this Segment in the 1557 chapter codec data. The format depends on the ChapProcessCodecID 1558 used. 1560 8.2.20. TimecodeScale Element 1562 name: "TimecodeScale" 1564 path: "1*1(\Segment\Info\TimecodeScale)" 1566 id: "0x2AD7B1" 1568 minOccurs: "1" 1570 maxOccurs: "1" 1572 range: "not 0" 1574 default: "1000000" 1576 type: "uinteger" 1578 minver: "1" 1580 documentation: Timestamp scale in nanoseconds (1.000.000 means all 1581 timestamps in the Segment are expressed in milliseconds). 1583 8.2.21. Duration Element 1585 name: "Duration" 1587 path: "0*1(\Segment\Info\Duration)" 1589 id: "0x4489" 1591 maxOccurs: "1" 1593 range: "> 0x0p+0" 1595 type: "float" 1597 minver: "1" 1599 definition: Duration of the Segment in nanoseconds based on 1600 TimecodeScale. 1602 8.2.22. DateUTC Element 1604 name: "DateUTC" 1606 path: "0*1(\Segment\Info\DateUTC)" 1607 id: "0x4461" 1609 maxOccurs: "1" 1611 type: "date" 1613 minver: "1" 1615 documentation: The date and time that the Segment was created by the 1616 muxing application or library. 1618 8.2.23. Title Element 1620 name: "Title" 1622 path: "0*1(\Segment\Info\Title)" 1624 id: "0x7BA9" 1626 maxOccurs: "1" 1628 type: "utf-8" 1630 minver: "1" 1632 documentation: General name of the Segment. 1634 8.2.24. MuxingApp Element 1636 name: "MuxingApp" 1638 path: "1*1(\Segment\Info\MuxingApp)" 1640 id: "0x4D80" 1642 minOccurs: "1" 1644 maxOccurs: "1" 1646 type: "utf-8" 1648 minver: "1" 1650 definition: Muxing application or library (example: "libmatroska- 1651 0.4.3"). 1653 usage notes: Include the full name of the application or library 1654 followed by the version number. 1656 8.2.25. WritingApp Element 1658 name: "WritingApp" 1660 path: "1*1(\Segment\Info\WritingApp)" 1662 id: "0x5741" 1664 minOccurs: "1" 1666 maxOccurs: "1" 1668 type: "utf-8" 1670 minver: "1" 1672 definition: Writing application (example: "mkvmerge-0.3.3"). 1674 usage notes: Include the full name of the application followed by the 1675 version number. 1677 8.2.26. Cluster Element 1679 name: "Cluster" 1681 path: "0*(\Segment\Cluster)" 1683 id: "0x1F43B675" 1685 type: "master" 1687 unknownsizeallowed: "1" 1689 minver: "1" 1691 documentation: The Top-Level Element containing the (monolithic) 1692 Block structure. 1694 8.2.27. Timecode Element 1696 name: "Timecode" 1698 path: "1*1(\Segment\Cluster\Timecode)" 1700 id: "0xE7" 1702 minOccurs: "1" 1703 maxOccurs: "1" 1705 type: "uinteger" 1707 minver: "1" 1709 documentation: Absolute timestamp of the cluster (based on 1710 TimecodeScale). 1712 8.2.28. SilentTracks Element 1714 name: "SilentTracks" 1716 path: "0*1(\Segment\Cluster\SilentTracks)" 1718 id: "0x5854" 1720 maxOccurs: "1" 1722 type: "master" 1724 minver: "1" 1726 documentation: The list of tracks that are not used in that part of 1727 the stream. It is useful when using overlay tracks on seeking or to 1728 decide what track to use. 1730 8.2.29. SilentTrackNumber Element 1732 name: "SilentTrackNumber" 1734 path: "0*(\Segment\Cluster\SilentTracks\SilentTrackNumber)" 1736 id: "0x58D7" 1738 type: "uinteger" 1740 minver: "1" 1742 documentation: One of the track number that are not used from now on 1743 in the stream. It could change later if not specified as silent in a 1744 further Cluster. 1746 8.2.30. Position Element 1748 name: "Position" 1750 path: "0*1(\Segment\Cluster\Position)" 1751 id: "0xA7" 1753 maxOccurs: "1" 1755 type: "uinteger" 1757 minver: "1" 1759 documentation: The Segment Position of the Cluster in the Segment (0 1760 in live broadcast streams). It might help to resynchronise offset on 1761 damaged streams. 1763 8.2.31. PrevSize Element 1765 name: "PrevSize" 1767 path: "0*1(\Segment\Cluster\PrevSize)" 1769 id: "0xAB" 1771 maxOccurs: "1" 1773 type: "uinteger" 1775 minver: "1" 1777 documentation: Size of the previous Cluster, in octets. Can be 1778 useful for backward playing. 1780 8.2.32. SimpleBlock Element 1782 name: "SimpleBlock" 1784 path: "0*(\Segment\Cluster\SimpleBlock)" 1786 id: "0xA3" 1788 type: "binary" 1790 minver: "2" 1792 documentation: Similar to Block but without all the extra 1793 information, mostly used to reduced overhead when no extra feature is 1794 needed. (see SimpleBlock Structure) 1796 8.2.33. BlockGroup Element 1798 name: "BlockGroup" 1800 path: "0*(\Segment\Cluster\BlockGroup)" 1802 id: "0xA0" 1804 type: "master" 1806 minver: "1" 1808 documentation: Basic container of information containing a single 1809 Block and information specific to that Block. 1811 8.2.34. Block Element 1813 name: "Block" 1815 path: "1*1(\Segment\Cluster\BlockGroup\Block)" 1817 id: "0xA1" 1819 minOccurs: "1" 1821 maxOccurs: "1" 1823 type: "binary" 1825 minver: "1" 1827 documentation: Block containing the actual data to be rendered and a 1828 timestamp relative to the Cluster Timecode. (see Block Structure) 1830 8.2.35. BlockVirtual Element 1832 name: "BlockVirtual" 1834 path: "0*1(\Segment\Cluster\BlockGroup\BlockVirtual)" 1836 id: "0xA2" 1838 maxOccurs: "1" 1840 type: "binary" 1842 minver: "0" 1843 maxver: "0" 1845 documentation: A Block with no data. It MUST be stored in the stream 1846 at the place the real Block would be in display order. (see Block 1847 Virtual) 1849 8.2.36. BlockAdditions Element 1851 name: "BlockAdditions" 1853 path: "0*1(\Segment\Cluster\BlockGroup\BlockAdditions)" 1855 id: "0x75A1" 1857 maxOccurs: "1" 1859 type: "master" 1861 minver: "1" 1863 documentation: Contain additional blocks to complete the main one. 1864 An EBML parser that has no knowledge of the Block structure could 1865 still see and use/skip these data. 1867 8.2.37. BlockMore Element 1869 name: "BlockMore" 1871 path: "1*(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore)" 1873 id: "0xA6" 1875 minOccurs: "1" 1877 type: "master" 1879 minver: "1" 1881 documentation: Contain the BlockAdditional and some parameters. 1883 8.2.38. BlockAddID Element 1885 name: "BlockAddID" 1887 path: "1*1(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\Block 1888 AddID)" 1890 id: "0xEE" 1891 minOccurs: "1" 1893 maxOccurs: "1" 1895 range: "not 0" 1897 default: "1" 1899 type: "uinteger" 1901 minver: "1" 1903 documentation: An ID to identify the BlockAdditional level. 1905 8.2.39. BlockAdditional Element 1907 name: "BlockAdditional" 1909 path: "1*1(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\Block 1910 Additional)" 1912 id: "0xA5" 1914 minOccurs: "1" 1916 maxOccurs: "1" 1918 type: "binary" 1920 minver: "1" 1922 documentation: Interpreted by the codec as it wishes (using the 1923 BlockAddID). 1925 8.2.40. BlockDuration Element 1927 name: "BlockDuration" 1929 path: "0*1(\Segment\Cluster\BlockGroup\BlockDuration)" 1931 id: "0x9B" 1933 maxOccurs: "1" 1935 default: "DefaultDuration" 1937 type: "uinteger" 1938 minver: "1" 1940 documentation: The duration of the Block (based on TimecodeScale). 1941 This Element is mandatory when DefaultDuration is set for the track 1942 (but can be omitted as other default values). When not written and 1943 with no DefaultDuration, the value is assumed to be the difference 1944 between the timestamp of this Block and the timestamp of the next 1945 Block in "display" order (not coding order). This Element can be 1946 useful at the end of a Track (as there is not other Block available), 1947 or when there is a break in a track like for subtitle tracks. 1949 8.2.41. ReferencePriority Element 1951 name: "ReferencePriority" 1953 path: "1*1(\Segment\Cluster\BlockGroup\ReferencePriority)" 1955 id: "0xFA" 1957 minOccurs: "1" 1959 maxOccurs: "1" 1961 default: "0" 1963 type: "uinteger" 1965 minver: "1" 1967 documentation: This frame is referenced and has the specified cache 1968 priority. In cache only a frame of the same or higher priority can 1969 replace this frame. A value of 0 means the frame is not referenced. 1971 8.2.42. ReferenceBlock Element 1973 name: "ReferenceBlock" 1975 path: "0*(\Segment\Cluster\BlockGroup\ReferenceBlock)" 1977 id: "0xFB" 1979 type: "integer" 1981 minver: "1" 1983 documentation: Timestamp of another frame used as a reference (ie: B 1984 or P frame). The timestamp is relative to the block it's attached 1985 to. 1987 8.2.43. ReferenceVirtual Element 1989 name: "ReferenceVirtual" 1991 path: "0*1(\Segment\Cluster\BlockGroup\ReferenceVirtual)" 1993 id: "0xFD" 1995 maxOccurs: "1" 1997 type: "integer" 1999 minver: "0" 2001 maxver: "0" 2003 documentation: The Segment Position of the data that would otherwise 2004 be in position of the virtual block. 2006 8.2.44. CodecState Element 2008 name: "CodecState" 2010 path: "0*1(\Segment\Cluster\BlockGroup\CodecState)" 2012 id: "0xA4" 2014 maxOccurs: "1" 2016 type: "binary" 2018 minver: "2" 2020 documentation: The new codec state to use. Data interpretation is 2021 private to the codec. This information SHOULD always be referenced 2022 by a seek entry. 2024 8.2.45. DiscardPadding Element 2026 name: "DiscardPadding" 2028 path: "0*1(\Segment\Cluster\BlockGroup\DiscardPadding)" 2030 id: "0x75A2" 2032 maxOccurs: "1" 2034 type: "integer" 2035 minver: "4" 2037 documentation: Duration in nanoseconds of the silent data added to 2038 the Block (padding at the end of the Block for positive value, at the 2039 beginning of the Block for negative value). The duration of 2040 DiscardPadding is not calculated in the duration of the TrackEntry 2041 and SHOULD be discarded during playback. 2043 8.2.46. Slices Element 2045 name: "Slices" 2047 path: "0*1(\Segment\Cluster\BlockGroup\Slices)" 2049 id: "0x8E" 2051 maxOccurs: "1" 2053 type: "master" 2055 minver: "1" 2057 documentation: Contains slices description. 2059 8.2.47. TimeSlice Element 2061 name: "TimeSlice" 2063 path: "0*(\Segment\Cluster\BlockGroup\Slices\TimeSlice)" 2065 id: "0xE8" 2067 type: "master" 2069 minver: "1" 2071 maxver: "1" 2073 documentation: Contains extra time information about the data 2074 contained in the Block. Being able to interpret this Element is not 2075 REQUIRED for playback. 2077 8.2.48. LaceNumber Element 2079 name: "LaceNumber" 2081 path: "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\LaceNumber)" 2082 id: "0xCC" 2084 maxOccurs: "1" 2086 default: "0" 2088 type: "uinteger" 2090 minver: "1" 2092 maxver: "1" 2094 documentation: The reverse number of the frame in the lace (0 is the 2095 last frame, 1 is the next to last, etc). Being able to interpret 2096 this Element is not REQUIRED for playback. 2098 8.2.49. FrameNumber Element 2100 name: "FrameNumber" 2102 path: "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\FrameNumber)" 2104 id: "0xCD" 2106 maxOccurs: "1" 2108 default: "0" 2110 type: "uinteger" 2112 minver: "0" 2114 maxver: "0" 2116 documentation: The number of the frame to generate from this lace 2117 with this delay (allow you to generate many frames from the same 2118 Block/Frame). 2120 8.2.50. BlockAdditionID Element 2122 name: "BlockAdditionID" 2124 path: 2125 "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\BlockAdditionID)" 2127 id: "0xCB" 2129 maxOccurs: "1" 2130 default: "0" 2132 type: "uinteger" 2134 minver: "0" 2136 maxver: "0" 2138 documentation: The ID of the BlockAdditional Element (0 is the main 2139 Block). 2141 8.2.51. Delay Element 2143 name: "Delay" 2145 path: "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\Delay)" 2147 id: "0xCE" 2149 maxOccurs: "1" 2151 default: "0" 2153 type: "uinteger" 2155 minver: "0" 2157 maxver: "0" 2159 documentation: The (scaled) delay to apply to the Element. 2161 8.2.52. SliceDuration Element 2163 name: "SliceDuration" 2165 path: 2166 "0*1(\Segment\Cluster\BlockGroup\Slices\TimeSlice\SliceDuration)" 2168 id: "0xCF" 2170 maxOccurs: "1" 2172 default: "0" 2174 type: "uinteger" 2176 minver: "0" 2177 maxver: "0" 2179 documentation: The (scaled) duration to apply to the Element. 2181 8.2.53. ReferenceFrame Element 2183 name: "ReferenceFrame" 2185 path: "0*1(\Segment\Cluster\BlockGroup\ReferenceFrame)" 2187 id: "0xC8" 2189 maxOccurs: "1" 2191 type: "master" 2193 minver: "0" 2195 maxver: "0" 2197 documentation: DivX trick track extensions 2199 8.2.54. ReferenceOffset Element 2201 name: "ReferenceOffset" 2203 path: 2204 "1*1(\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceOffset)" 2206 id: "0xC9" 2208 minOccurs: "1" 2210 maxOccurs: "1" 2212 type: "uinteger" 2214 minver: "0" 2216 maxver: "0" 2218 documentation: DivX trick track extensions 2220 8.2.55. ReferenceTimeCode Element 2222 name: "ReferenceTimeCode" 2223 path: 2224 "1*1(\Segment\Cluster\BlockGroup\ReferenceFrame\ReferenceTimeCode)" 2226 id: "0xCA" 2228 minOccurs: "1" 2230 maxOccurs: "1" 2232 type: "uinteger" 2234 minver: "0" 2236 maxver: "0" 2238 documentation: DivX trick track extensions 2240 8.2.56. EncryptedBlock Element 2242 name: "EncryptedBlock" 2244 path: "0*(\Segment\Cluster\EncryptedBlock)" 2246 id: "0xAF" 2248 type: "binary" 2250 minver: "0" 2252 maxver: "0" 2254 documentation: Similar to SimpleBlock but the data inside the Block 2255 are Transformed (encrypt and/or signed). (see EncryptedBlock 2256 Structure) 2258 8.2.57. Tracks Element 2260 name: "Tracks" 2262 path: "0*(\Segment\Tracks)" 2264 id: "0x1654AE6B" 2266 type: "master" 2268 minver: "1" 2269 documentation: A Top-Level Element of information with many tracks 2270 described. 2272 8.2.58. TrackEntry Element 2274 name: "TrackEntry" 2276 path: "1*(\Segment\Tracks\TrackEntry)" 2278 id: "0xAE" 2280 minOccurs: "1" 2282 type: "master" 2284 minver: "1" 2286 documentation: Describes a track with all Elements. 2288 8.2.59. TrackNumber Element 2290 name: "TrackNumber" 2292 path: "1*1(\Segment\Tracks\TrackEntry\TrackNumber)" 2294 id: "0xD7" 2296 minOccurs: "1" 2298 maxOccurs: "1" 2300 range: "not 0" 2302 type: "uinteger" 2304 minver: "1" 2306 documentation: The track number as used in the Block Header (using 2307 more than 127 tracks is not encouraged, though the design allows an 2308 unlimited number). 2310 8.2.60. TrackUID Element 2312 name: "TrackUID" 2314 path: "1*1(\Segment\Tracks\TrackEntry\TrackUID)" 2316 id: "0x73C5" 2317 minOccurs: "1" 2319 maxOccurs: "1" 2321 range: "not 0" 2323 type: "uinteger" 2325 minver: "1" 2327 documentation: A unique ID to identify the Track. This SHOULD be 2328 kept the same when making a direct stream copy of the Track to 2329 another file. 2331 8.2.61. TrackType Element 2333 name: "TrackType" 2335 path: "1*1(\Segment\Tracks\TrackEntry\TrackType)" 2337 id: "0x83" 2339 minOccurs: "1" 2341 maxOccurs: "1" 2343 range: "1-254" 2345 type: "uinteger" 2347 minver: "1" 2349 documentation: A set of track types coded on 8 bits. 2351 8.2.62. FlagEnabled Element 2353 name: "FlagEnabled" 2355 path: "1*1(\Segment\Tracks\TrackEntry\FlagEnabled)" 2357 id: "0xB9" 2359 minOccurs: "1" 2361 maxOccurs: "1" 2363 range: "0-1" 2364 default: "1" 2366 type: "uinteger" 2368 minver: "2" 2370 documentation: Set if the track is usable. (1 bit) 2372 8.2.63. FlagDefault Element 2374 name: "FlagDefault" 2376 path: "1*1(\Segment\Tracks\TrackEntry\FlagDefault)" 2378 id: "0x88" 2380 minOccurs: "1" 2382 maxOccurs: "1" 2384 range: "0-1" 2386 default: "1" 2388 type: "uinteger" 2390 minver: "1" 2392 documentation: Set if that track (audio, video or subs) SHOULD be 2393 active if no language found matches the user preference. (1 bit) 2395 8.2.64. FlagForced Element 2397 name: "FlagForced" 2399 path: "1*1(\Segment\Tracks\TrackEntry\FlagForced)" 2401 id: "0x55AA" 2403 minOccurs: "1" 2405 maxOccurs: "1" 2407 range: "0-1" 2409 default: "0" 2411 type: "uinteger" 2412 minver: "1" 2414 documentation: Set if that track MUST be active during playback. 2415 There can be many forced track for a kind (audio, video or subs), the 2416 player SHOULD select the one which language matches the user 2417 preference or the default + forced track. Overlay MAY happen between 2418 a forced and non-forced track of the same kind. (1 bit) 2420 8.2.65. FlagLacing Element 2422 name: "FlagLacing" 2424 path: "1*1(\Segment\Tracks\TrackEntry\FlagLacing)" 2426 id: "0x9C" 2428 minOccurs: "1" 2430 maxOccurs: "1" 2432 range: "0-1" 2434 default: "1" 2436 type: "uinteger" 2438 minver: "1" 2440 documentation: Set if the track MAY contain blocks using lacing. (1 2441 bit) 2443 8.2.66. MinCache Element 2445 name: "MinCache" 2447 path: "1*1(\Segment\Tracks\TrackEntry\MinCache)" 2449 id: "0x6DE7" 2451 minOccurs: "1" 2453 maxOccurs: "1" 2455 default: "0" 2457 type: "uinteger" 2459 minver: "1" 2460 documentation: The minimum number of frames a player SHOULD be able 2461 to cache during playback. If set to 0, the reference pseudo-cache 2462 system is not used. 2464 8.2.67. MaxCache Element 2466 name: "MaxCache" 2468 path: "0*1(\Segment\Tracks\TrackEntry\MaxCache)" 2470 id: "0x6DF8" 2472 maxOccurs: "1" 2474 type: "uinteger" 2476 minver: "1" 2478 documentation: The maximum cache size necessary to store referenced 2479 frames in and the current frame. 0 means no cache is needed. 2481 8.2.68. DefaultDuration Element 2483 name: "DefaultDuration" 2485 path: "0*1(\Segment\Tracks\TrackEntry\DefaultDuration)" 2487 id: "0x23E383" 2489 maxOccurs: "1" 2491 range: "not 0" 2493 type: "uinteger" 2495 minver: "1" 2497 documentation: Number of nanoseconds (not scaled via TimecodeScale) 2498 per frame ('frame' in the Matroska sense -- one Element put into a 2499 (Simple)Block). 2501 8.2.69. DefaultDecodedFieldDuration Element 2503 name: "DefaultDecodedFieldDuration" 2505 path: "0*1(\Segment\Tracks\TrackEntry\DefaultDecodedFieldDuration)" 2507 id: "0x234E7A" 2508 maxOccurs: "1" 2510 range: "not 0" 2512 type: "uinteger" 2514 minver: "4" 2516 documentation: The period in nanoseconds (not scaled by 2517 TimecodeScale) between two successive fields at the output of the 2518 decoding process (see the notes) 2520 8.2.70. TrackTimecodeScale Element 2522 name: "TrackTimecodeScale" 2524 path: "1*1(\Segment\Tracks\TrackEntry\TrackTimecodeScale)" 2526 id: "0x23314F" 2528 minOccurs: "1" 2530 maxOccurs: "1" 2532 range: "> 0x0p+0" 2534 default: "0x1p+0" 2536 type: "float" 2538 minver: "1" 2540 maxver: "3" 2542 documentation: DEPRECATED, DO NOT USE. The scale to apply on this 2543 track to work at normal speed in relation with other tracks (mostly 2544 used to adjust video speed when the audio length differs). 2546 8.2.71. TrackOffset Element 2548 name: "TrackOffset" 2550 path: "0*1(\Segment\Tracks\TrackEntry\TrackOffset)" 2552 id: "0x537F" 2554 maxOccurs: "1" 2555 default: "0" 2557 type: "integer" 2559 minver: "0" 2561 maxver: "0" 2563 documentation: A value to add to the Block's Timestamp. This can be 2564 used to adjust the playback offset of a track. 2566 8.2.72. MaxBlockAdditionID Element 2568 name: "MaxBlockAdditionID" 2570 path: "1*1(\Segment\Tracks\TrackEntry\MaxBlockAdditionID)" 2572 id: "0x55EE" 2574 minOccurs: "1" 2576 maxOccurs: "1" 2578 default: "0" 2580 type: "uinteger" 2582 minver: "1" 2584 documentation: The maximum value of BlockAddID. A value 0 means 2585 there is no BlockAdditions for this track. 2587 8.2.73. Name Element 2589 name: "Name" 2591 path: "0*1(\Segment\Tracks\TrackEntry\Name)" 2593 id: "0x536E" 2595 maxOccurs: "1" 2597 type: "utf-8" 2599 minver: "1" 2601 documentation: A human-readable track name. 2603 8.2.74. Language Element 2605 name: "Language" 2607 path: "0*1(\Segment\Tracks\TrackEntry\Language)" 2609 id: "0x22B59C" 2611 maxOccurs: "1" 2613 default: "eng" 2615 type: "string" 2617 minver: "1" 2619 documentation: Specifies the language of the track in the Matroska 2620 languages form. This Element MUST be ignored if the LanguageIETF 2621 Element is used in the same TrackEntry. 2623 8.2.75. LanguageIETF Element 2625 name: "LanguageIETF" 2627 path: "0*1(\Segment\Tracks\TrackEntry\LanguageIETF)" 2629 id: "0x22B59D" 2631 maxOccurs: "1" 2633 type: "string" 2635 minver: "4" 2637 documentation: Specifies the language of the track according to BCP 2638 47 and using the IANA Language Subtag Registry. If this Element is 2639 used, then any Language Elements used in the same TrackEntry MUST be 2640 ignored. 2642 8.2.76. CodecID Element 2644 name: "CodecID" 2646 path: "1*1(\Segment\Tracks\TrackEntry\CodecID)" 2648 id: "0x86" 2650 minOccurs: "1" 2651 maxOccurs: "1" 2653 type: "string" 2655 minver: "1" 2657 documentation: An ID corresponding to the codec, see the codec page 2658 for more info. 2660 8.2.77. CodecPrivate Element 2662 name: "CodecPrivate" 2664 path: "0*1(\Segment\Tracks\TrackEntry\CodecPrivate)" 2666 id: "0x63A2" 2668 maxOccurs: "1" 2670 type: "binary" 2672 minver: "1" 2674 documentation: Private data only known to the codec. 2676 8.2.78. CodecName Element 2678 name: "CodecName" 2680 path: "0*1(\Segment\Tracks\TrackEntry\CodecName)" 2682 id: "0x258688" 2684 maxOccurs: "1" 2686 type: "utf-8" 2688 minver: "1" 2690 documentation: A human-readable string specifying the codec. 2692 8.2.79. AttachmentLink Element 2694 name: "AttachmentLink" 2696 path: "0*1(\Segment\Tracks\TrackEntry\AttachmentLink)" 2698 id: "0x7446" 2699 maxOccurs: "1" 2701 range: "not 0" 2703 type: "uinteger" 2705 minver: "1" 2707 maxver: "3" 2709 documentation: The UID of an attachment that is used by this codec. 2711 8.2.80. CodecSettings Element 2713 name: "CodecSettings" 2715 path: "0*1(\Segment\Tracks\TrackEntry\CodecSettings)" 2717 id: "0x3A9697" 2719 maxOccurs: "1" 2721 type: "utf-8" 2723 minver: "0" 2725 maxver: "0" 2727 documentation: A string describing the encoding setting used. 2729 8.2.81. CodecInfoURL Element 2731 name: "CodecInfoURL" 2733 path: "0*(\Segment\Tracks\TrackEntry\CodecInfoURL)" 2735 id: "0x3B4040" 2737 type: "string" 2739 minver: "0" 2741 maxver: "0" 2743 documentation: A URL to find information about the codec used. 2745 8.2.82. CodecDownloadURL Element 2747 name: "CodecDownloadURL" 2749 path: "0*(\Segment\Tracks\TrackEntry\CodecDownloadURL)" 2751 id: "0x26B240" 2753 type: "string" 2755 minver: "0" 2757 maxver: "0" 2759 documentation: A URL to download about the codec used. 2761 8.2.83. CodecDecodeAll Element 2763 name: "CodecDecodeAll" 2765 path: "1*1(\Segment\Tracks\TrackEntry\CodecDecodeAll)" 2767 id: "0xAA" 2769 minOccurs: "1" 2771 maxOccurs: "1" 2773 range: "0-1" 2775 default: "1" 2777 type: "uinteger" 2779 minver: "2" 2781 documentation: The codec can decode potentially damaged data (1 bit). 2783 8.2.84. TrackOverlay Element 2785 name: "TrackOverlay" 2787 path: "0*(\Segment\Tracks\TrackEntry\TrackOverlay)" 2789 id: "0x6FAB" 2791 type: "uinteger" 2792 minver: "1" 2794 documentation: Specify that this track is an overlay track for the 2795 Track specified (in the u-integer). That means when this track has a 2796 gap (see SilentTracks) the overlay track SHOULD be used instead. The 2797 order of multiple TrackOverlay matters, the first one is the one that 2798 SHOULD be used. If not found it SHOULD be the second, etc. 2800 8.2.85. CodecDelay Element 2802 name: "CodecDelay" 2804 path: "0*1(\Segment\Tracks\TrackEntry\CodecDelay)" 2806 id: "0x56AA" 2808 maxOccurs: "1" 2810 default: "0" 2812 type: "uinteger" 2814 minver: "4" 2816 documentation: CodecDelay is The codec-built-in delay in nanoseconds. 2817 This value MUST be subtracted from each block timestamp in order to 2818 get the actual timestamp. The value SHOULD be small so the muxing of 2819 tracks with the same actual timestamp are in the same Cluster. 2821 8.2.86. SeekPreRoll Element 2823 name: "SeekPreRoll" 2825 path: "1*1(\Segment\Tracks\TrackEntry\SeekPreRoll)" 2827 id: "0x56BB" 2829 minOccurs: "1" 2831 maxOccurs: "1" 2833 default: "0" 2835 type: "uinteger" 2837 minver: "4" 2838 documentation: After a discontinuity, SeekPreRoll is the duration in 2839 nanoseconds of the data the decoder MUST decode before the decoded 2840 data is valid. 2842 8.2.87. TrackTranslate Element 2844 name: "TrackTranslate" 2846 path: "0*(\Segment\Tracks\TrackEntry\TrackTranslate)" 2848 id: "0x6624" 2850 type: "master" 2852 minver: "1" 2854 documentation: The track identification for the given Chapter Codec. 2856 8.2.88. TrackTranslateEditionUID Element 2858 name: "TrackTranslateEditionUID" 2860 path: "0*(\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateEdi 2861 tionUID)" 2863 id: "0x66FC" 2865 type: "uinteger" 2867 minver: "1" 2869 documentation: Specify an edition UID on which this translation 2870 applies. When not specified, it means for all editions found in the 2871 Segment. 2873 8.2.89. TrackTranslateCodec Element 2875 name: "TrackTranslateCodec" 2877 path: 2878 "1*1(\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateCodec)" 2880 id: "0x66BF" 2882 minOccurs: "1" 2884 maxOccurs: "1" 2885 type: "uinteger" 2887 minver: "1" 2889 documentation: The chapter codec. 2891 8.2.90. TrackTranslateTrackID Element 2893 name: "TrackTranslateTrackID" 2895 path: "1*1(\Segment\Tracks\TrackEntry\TrackTranslate\TrackTranslateTr 2896 ackID)" 2898 id: "0x66A5" 2900 minOccurs: "1" 2902 maxOccurs: "1" 2904 type: "binary" 2906 minver: "1" 2908 documentation: The binary value used to represent this track in the 2909 chapter codec data. The format depends on the ChapProcessCodecID 2910 used. 2912 8.2.91. Video Element 2914 name: "Video" 2916 path: "0*1(\Segment\Tracks\TrackEntry\Video)" 2918 id: "0xE0" 2920 maxOccurs: "1" 2922 type: "master" 2924 minver: "1" 2926 documentation: Video settings. 2928 8.2.92. FlagInterlaced Element 2930 name: "FlagInterlaced" 2932 path: "1*1(\Segment\Tracks\TrackEntry\Video\FlagInterlaced)" 2933 id: "0x9A" 2935 minOccurs: "1" 2937 maxOccurs: "1" 2939 range: "0-2" 2941 default: "0" 2943 type: "uinteger" 2945 minver: "2" 2947 documentation: A flag to declare is the video is known to be 2948 progressive or interlaced and if applicable to declare details about 2949 the interlacement. 2951 8.2.93. FieldOrder Element 2953 name: "FieldOrder" 2955 path: "1*1(\Segment\Tracks\TrackEntry\Video\FieldOrder)" 2957 id: "0x9D" 2959 minOccurs: "1" 2961 maxOccurs: "1" 2963 range: "0-14" 2965 default: "2" 2967 type: "uinteger" 2969 minver: "4" 2971 documentation: Declare the field ordering of the video. If 2972 FlagInterlaced is not set to 1, this Element MUST be ignored. 2974 8.2.94. StereoMode Element 2976 name: "StereoMode" 2978 path: "0*1(\Segment\Tracks\TrackEntry\Video\StereoMode)" 2980 id: "0x53B8" 2981 maxOccurs: "1" 2983 default: "0" 2985 type: "uinteger" 2987 minver: "3" 2989 documentation: Stereo-3D video mode. There are some more details on 2990 3D support in the Specification Notes. 2992 8.2.95. AlphaMode Element 2994 name: "AlphaMode" 2996 path: "0*1(\Segment\Tracks\TrackEntry\Video\AlphaMode)" 2998 id: "0x53C0" 3000 maxOccurs: "1" 3002 default: "0" 3004 type: "uinteger" 3006 minver: "3" 3008 documentation: Alpha Video Mode. Presence of this Element indicates 3009 that the BlockAdditional Element could contain Alpha data. 3011 8.2.96. OldStereoMode Element 3013 name: "OldStereoMode" 3015 path: "0*1(\Segment\Tracks\TrackEntry\Video\OldStereoMode)" 3017 id: "0x53B9" 3019 maxOccurs: "1" 3021 type: "uinteger" 3023 maxver: "0" 3025 documentation: DEPRECATED, DO NOT USE. Bogus StereoMode value used 3026 in old versions of libmatroska. 3028 8.2.97. PixelWidth Element 3030 name: "PixelWidth" 3032 path: "1*1(\Segment\Tracks\TrackEntry\Video\PixelWidth)" 3034 id: "0xB0" 3036 minOccurs: "1" 3038 maxOccurs: "1" 3040 range: "not 0" 3042 type: "uinteger" 3044 minver: "1" 3046 documentation: Width of the encoded video frames in pixels. 3048 8.2.98. PixelHeight Element 3050 name: "PixelHeight" 3052 path: "1*1(\Segment\Tracks\TrackEntry\Video\PixelHeight)" 3054 id: "0xBA" 3056 minOccurs: "1" 3058 maxOccurs: "1" 3060 range: "not 0" 3062 type: "uinteger" 3064 minver: "1" 3066 documentation: Height of the encoded video frames in pixels. 3068 8.2.99. PixelCropBottom Element 3070 name: "PixelCropBottom" 3072 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropBottom)" 3074 id: "0x54AA" 3075 maxOccurs: "1" 3077 default: "0" 3079 type: "uinteger" 3081 minver: "1" 3083 documentation: The number of video pixels to remove at the bottom of 3084 the image (for HDTV content). 3086 8.2.100. PixelCropTop Element 3088 name: "PixelCropTop" 3090 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropTop)" 3092 id: "0x54BB" 3094 maxOccurs: "1" 3096 default: "0" 3098 type: "uinteger" 3100 minver: "1" 3102 documentation: The number of video pixels to remove at the top of the 3103 image. 3105 8.2.101. PixelCropLeft Element 3107 name: "PixelCropLeft" 3109 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropLeft)" 3111 id: "0x54CC" 3113 maxOccurs: "1" 3115 default: "0" 3117 type: "uinteger" 3119 minver: "1" 3121 documentation: The number of video pixels to remove on the left of 3122 the image. 3124 8.2.102. PixelCropRight Element 3126 name: "PixelCropRight" 3128 path: "0*1(\Segment\Tracks\TrackEntry\Video\PixelCropRight)" 3130 id: "0x54DD" 3132 maxOccurs: "1" 3134 default: "0" 3136 type: "uinteger" 3138 minver: "1" 3140 documentation: The number of video pixels to remove on the right of 3141 the image. 3143 8.2.103. DisplayWidth Element 3145 name: "DisplayWidth" 3147 path: "0*1(\Segment\Tracks\TrackEntry\Video\DisplayWidth)" 3149 id: "0x54B0" 3151 maxOccurs: "1" 3153 range: "not 0" 3155 default: "PixelWidth - PixelCropLeft - PixelCropRight" 3157 type: "uinteger" 3159 minver: "1" 3161 documentation: Width of the video frames to display. Applies to the 3162 video frame after cropping (PixelCrop* Elements). The default value 3163 is only valid when DisplayUnit is 0. 3165 8.2.104. DisplayHeight Element 3167 name: "DisplayHeight" 3169 path: "0*1(\Segment\Tracks\TrackEntry\Video\DisplayHeight)" 3171 id: "0x54BA" 3172 maxOccurs: "1" 3174 range: "not 0" 3176 default: "PixelHeight - PixelCropTop - PixelCropBottom" 3178 type: "uinteger" 3180 minver: "1" 3182 documentation: Height of the video frames to display. Applies to the 3183 video frame after cropping (PixelCrop* Elements). The default value 3184 is only valid when DisplayUnit is 0. 3186 8.2.105. DisplayUnit Element 3188 name: "DisplayUnit" 3190 path: "0*1(\Segment\Tracks\TrackEntry\Video\DisplayUnit)" 3192 id: "0x54B2" 3194 maxOccurs: "1" 3196 default: "0" 3198 type: "uinteger" 3200 minver: "1" 3202 documentation: How DisplayWidth & DisplayHeight are interpreted. 3204 8.2.106. AspectRatioType Element 3206 name: "AspectRatioType" 3208 path: "0*1(\Segment\Tracks\TrackEntry\Video\AspectRatioType)" 3210 id: "0x54B3" 3212 maxOccurs: "1" 3214 default: "0" 3216 type: "uinteger" 3218 minver: "1" 3219 documentation: Specify the possible modifications to the aspect 3220 ratio. 3222 8.2.107. ColourSpace Element 3224 name: "ColourSpace" 3226 path: "0*1(\Segment\Tracks\TrackEntry\Video\ColourSpace)" 3228 id: "0x2EB524" 3230 maxOccurs: "1" 3232 size: "4" 3234 type: "binary" 3236 minver: "1" 3238 documentation: Specify the pixel format used for the Track's data as 3239 a FourCC. This value is similar in scope to the biCompression value 3240 of AVI's BITMAPINFOHEADER. This Element is MANDATORY in TrackEntry 3241 when the CodecID Element of the TrackEntry is set to 3242 "V_UNCOMPRESSED". 3244 8.2.108. GammaValue Element 3246 name: "GammaValue" 3248 path: "0*1(\Segment\Tracks\TrackEntry\Video\GammaValue)" 3250 id: "0x2FB523" 3252 maxOccurs: "1" 3254 range: "> 0x0p+0" 3256 type: "float" 3258 minver: "0" 3260 maxver: "0" 3262 documentation: Gamma Value. 3264 8.2.109. FrameRate Element 3266 name: "FrameRate" 3268 path: "0*1(\Segment\Tracks\TrackEntry\Video\FrameRate)" 3270 id: "0x2383E3" 3272 maxOccurs: "1" 3274 range: "> 0x0p+0" 3276 type: "float" 3278 minver: "0" 3280 maxver: "0" 3282 documentation: Number of frames per second. Informational only. 3284 8.2.110. Colour Element 3286 name: "Colour" 3288 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour)" 3290 id: "0x55B0" 3292 maxOccurs: "1" 3294 type: "master" 3296 minver: "4" 3298 documentation: Settings describing the colour format. 3300 8.2.111. MatrixCoefficients Element 3302 name: "MatrixCoefficients" 3304 path: 3305 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MatrixCoefficients)" 3307 id: "0x55B1" 3309 maxOccurs: "1" 3311 default: "2" 3312 type: "uinteger" 3314 minver: "4" 3316 documentation: The Matrix Coefficients of the video used to derive 3317 luma and chroma values from red, green, and blue color primaries. 3318 For clarity, the value and meanings for MatrixCoefficients are 3319 adopted from Table 4 of ISO/IEC 23001-8:2013/DCOR1. 3321 8.2.112. BitsPerChannel Element 3323 name: "BitsPerChannel" 3325 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\BitsPerChannel)" 3327 id: "0x55B2" 3329 maxOccurs: "1" 3331 default: "0" 3333 type: "uinteger" 3335 minver: "4" 3337 documentation: Number of decoded bits per channel. A value of 0 3338 indicates that the BitsPerChannel is unspecified. 3340 8.2.113. ChromaSubsamplingHorz Element 3342 name: "ChromaSubsamplingHorz" 3344 path: 3345 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingHorz)" 3347 id: "0x55B3" 3349 maxOccurs: "1" 3351 type: "uinteger" 3353 minver: "4" 3355 documentation: The amount of pixels to remove in the Cr and Cb 3356 channels for every pixel not removed horizontally. Example: For 3357 video with 4:2:0 chroma subsampling, the ChromaSubsamplingHorz SHOULD 3358 be set to 1. 3360 8.2.114. ChromaSubsamplingVert Element 3362 name: "ChromaSubsamplingVert" 3364 path: 3365 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSubsamplingVert)" 3367 id: "0x55B4" 3369 maxOccurs: "1" 3371 type: "uinteger" 3373 minver: "4" 3375 documentation: The amount of pixels to remove in the Cr and Cb 3376 channels for every pixel not removed vertically. Example: For video 3377 with 4:2:0 chroma subsampling, the ChromaSubsamplingVert SHOULD be 3378 set to 1. 3380 8.2.115. CbSubsamplingHorz Element 3382 name: "CbSubsamplingHorz" 3384 path: 3385 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingHorz)" 3387 id: "0x55B5" 3389 maxOccurs: "1" 3391 type: "uinteger" 3393 minver: "4" 3395 documentation: The amount of pixels to remove in the Cb channel for 3396 every pixel not removed horizontally. This is additive with 3397 ChromaSubsamplingHorz. Example: For video with 4:2:1 chroma 3398 subsampling, the ChromaSubsamplingHorz SHOULD be set to 1 and 3399 CbSubsamplingHorz SHOULD be set to 1. 3401 8.2.116. CbSubsamplingVert Element 3403 name: "CbSubsamplingVert" 3405 path: 3406 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\CbSubsamplingVert)" 3407 id: "0x55B6" 3409 maxOccurs: "1" 3411 type: "uinteger" 3413 minver: "4" 3415 documentation: The amount of pixels to remove in the Cb channel for 3416 every pixel not removed vertically. This is additive with 3417 ChromaSubsamplingVert. 3419 8.2.117. ChromaSitingHorz Element 3421 name: "ChromaSitingHorz" 3423 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingHorz)" 3425 id: "0x55B7" 3427 maxOccurs: "1" 3429 default: "0" 3431 type: "uinteger" 3433 minver: "4" 3435 documentation: How chroma is subsampled horizontally. 3437 8.2.118. ChromaSitingVert Element 3439 name: "ChromaSitingVert" 3441 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\ChromaSitingVert)" 3443 id: "0x55B8" 3445 maxOccurs: "1" 3447 default: "0" 3449 type: "uinteger" 3451 minver: "4" 3453 documentation: How chroma is subsampled vertically. 3455 8.2.119. Range Element 3457 name: "Range" 3459 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\Range)" 3461 id: "0x55B9" 3463 maxOccurs: "1" 3465 default: "0" 3467 type: "uinteger" 3469 minver: "4" 3471 documentation: Clipping of the color ranges. 3473 8.2.120. TransferCharacteristics Element 3475 name: "TransferCharacteristics" 3477 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\TransferCharacteri 3478 stics)" 3480 id: "0x55BA" 3482 maxOccurs: "1" 3484 default: "2" 3486 type: "uinteger" 3488 minver: "4" 3490 documentation: The transfer characteristics of the video. For 3491 clarity, the value and meanings for TransferCharacteristics 1-15 are 3492 adopted from Table 3 of ISO/IEC 23001-8:2013/DCOR1. 3493 TransferCharacteristics 16-18 are proposed values. 3495 8.2.121. Primaries Element 3497 name: "Primaries" 3499 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\Primaries)" 3501 id: "0x55BB" 3502 maxOccurs: "1" 3504 default: "2" 3506 type: "uinteger" 3508 minver: "4" 3510 documentation: The colour primaries of the video. For clarity, the 3511 value and meanings for Primaries are adopted from Table 2 of ISO/IEC 3512 23001-8:2013/DCOR1. 3514 8.2.122. MaxCLL Element 3516 name: "MaxCLL" 3518 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MaxCLL)" 3520 id: "0x55BC" 3522 maxOccurs: "1" 3524 type: "uinteger" 3526 minver: "4" 3528 documentation: Maximum brightness of a single pixel (Maximum Content 3529 Light Level) in candelas per square meter (cd/m^2). 3531 8.2.123. MaxFALL Element 3533 name: "MaxFALL" 3535 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MaxFALL)" 3537 id: "0x55BD" 3539 maxOccurs: "1" 3541 type: "uinteger" 3543 minver: "4" 3545 documentation: Maximum brightness of a single full frame (Maximum 3546 Frame-Average Light Level) in candelas per square meter (cd/m^2). 3548 8.2.124. MasteringMetadata Element 3550 name: "MasteringMetadata" 3552 path: 3553 "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata)" 3555 id: "0x55D0" 3557 maxOccurs: "1" 3559 type: "master" 3561 minver: "4" 3563 documentation: SMPTE 2086 mastering data. 3565 8.2.125. PrimaryRChromaticityX Element 3567 name: "PrimaryRChromaticityX" 3569 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3570 PrimaryRChromaticityX)" 3572 id: "0x55D1" 3574 maxOccurs: "1" 3576 range: "0-1" 3578 type: "float" 3580 minver: "4" 3582 documentation: Red X chromaticity coordinate as defined by CIE 1931. 3584 8.2.126. PrimaryRChromaticityY Element 3586 name: "PrimaryRChromaticityY" 3588 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3589 PrimaryRChromaticityY)" 3591 id: "0x55D2" 3593 maxOccurs: "1" 3595 range: "0-1" 3596 type: "float" 3598 minver: "4" 3600 documentation: Red Y chromaticity coordinate as defined by CIE 1931. 3602 8.2.127. PrimaryGChromaticityX Element 3604 name: "PrimaryGChromaticityX" 3606 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3607 PrimaryGChromaticityX)" 3609 id: "0x55D3" 3611 maxOccurs: "1" 3613 range: "0-1" 3615 type: "float" 3617 minver: "4" 3619 documentation: Green X chromaticity coordinate as defined by CIE 3620 1931. 3622 8.2.128. PrimaryGChromaticityY Element 3624 name: "PrimaryGChromaticityY" 3626 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3627 PrimaryGChromaticityY)" 3629 id: "0x55D4" 3631 maxOccurs: "1" 3633 range: "0-1" 3635 type: "float" 3637 minver: "4" 3639 documentation: Green Y chromaticity coordinate as defined by CIE 3640 1931. 3642 8.2.129. PrimaryBChromaticityX Element 3644 name: "PrimaryBChromaticityX" 3646 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3647 PrimaryBChromaticityX)" 3649 id: "0x55D5" 3651 maxOccurs: "1" 3653 range: "0-1" 3655 type: "float" 3657 minver: "4" 3659 documentation: Blue X chromaticity coordinate as defined by CIE 1931. 3661 8.2.130. PrimaryBChromaticityY Element 3663 name: "PrimaryBChromaticityY" 3665 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3666 PrimaryBChromaticityY)" 3668 id: "0x55D6" 3670 maxOccurs: "1" 3672 range: "0-1" 3674 type: "float" 3676 minver: "4" 3678 documentation: Blue Y chromaticity coordinate as defined by CIE 1931. 3680 8.2.131. WhitePointChromaticityX Element 3682 name: "WhitePointChromaticityX" 3684 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3685 WhitePointChromaticityX)" 3687 id: "0x55D7" 3689 maxOccurs: "1" 3690 range: "0-1" 3692 type: "float" 3694 minver: "4" 3696 documentation: White X chromaticity coordinate as defined by CIE 3697 1931. 3699 8.2.132. WhitePointChromaticityY Element 3701 name: "WhitePointChromaticityY" 3703 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3704 WhitePointChromaticityY)" 3706 id: "0x55D8" 3708 maxOccurs: "1" 3710 range: "0-1" 3712 type: "float" 3714 minver: "4" 3716 documentation: White Y chromaticity coordinate as defined by CIE 3717 1931. 3719 8.2.133. LuminanceMax Element 3721 name: "LuminanceMax" 3723 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3724 LuminanceMax)" 3726 id: "0x55D9" 3728 maxOccurs: "1" 3730 range: ">= 0x0p+0" 3732 type: "float" 3734 minver: "4" 3736 documentation: Maximum luminance. Represented in candelas per square 3737 meter (cd/m^2). 3739 8.2.134. LuminanceMin Element 3741 name: "LuminanceMin" 3743 path: "0*1(\Segment\Tracks\TrackEntry\Video\Colour\MasteringMetadata\ 3744 LuminanceMin)" 3746 id: "0x55DA" 3748 maxOccurs: "1" 3750 range: ">= 0x0p+0" 3752 type: "float" 3754 minver: "4" 3756 documentation: Mininum luminance. Represented in candelas per square 3757 meter (cd/m^2). 3759 8.2.135. Projection Element 3761 name: "Projection" 3763 path: "0*1(\Segment\Tracks\TrackEntry\Video\Projection)" 3765 id: "0x7670" 3767 maxOccurs: "1" 3769 type: "master" 3771 minver: "4" 3773 documentation: Describes the video projection details. Used to 3774 render spherical and VR videos. 3776 8.2.136. ProjectionType Element 3778 name: "ProjectionType" 3780 path: 3781 "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionType)" 3783 id: "0x7671" 3785 minOccurs: "1" 3786 maxOccurs: "1" 3788 range: "0-3" 3790 default: "0" 3792 type: "uinteger" 3794 minver: "4" 3796 documentation: Describes the projection used for this video track. 3798 8.2.137. ProjectionPrivate Element 3800 name: "ProjectionPrivate" 3802 path: 3803 "0*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPrivate)" 3805 id: "0x7672" 3807 maxOccurs: "1" 3809 type: "binary" 3811 minver: "4" 3813 documentation: Private data that only applies to a specific 3814 projection.SemanticsIf ProjectionType equals 0 (Rectangular), then 3815 this element must not be present.If ProjectionType equals 1 3816 (Equirectangular), then this element must be present and contain the 3817 same binary data that would be stored inside an ISOBMFF 3818 Equirectangular Projection Box ('equi').If ProjectionType equals 2 3819 (Cubemap), then this element must be present and contain the same 3820 binary data that would be stored inside an ISOBMFF Cubemap Projection 3821 Box ('cbmp').If ProjectionType equals 3 (Mesh), then this element 3822 must be present and contain the same binary data that would be stored 3823 inside an ISOBMFF Mesh Projection Box ('mshp').Note: ISOBMFF box size 3824 and fourcc fields are not included in the binary data, but the 3825 FullBox version and flag fields are. This is to avoid redundant 3826 framing information while preserving versioning and semantics between 3827 the two container formats. 3829 8.2.138. ProjectionPoseYaw Element 3831 name: "ProjectionPoseYaw" 3832 path: 3833 "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseYaw)" 3835 id: "0x7673" 3837 minOccurs: "1" 3839 maxOccurs: "1" 3841 default: "0x0p+0" 3843 type: "float" 3845 minver: "4" 3847 documentation: Specifies a yaw rotation to the 3848 projection.SemanticsValue represents a clockwise rotation, in 3849 degrees, around the up vector. This rotation must be applied before 3850 any ProjectionPosePitch or ProjectionPoseRoll rotations. The value 3851 of this field should be in the -180 to 180 degree range. 3853 8.2.139. ProjectionPosePitch Element 3855 name: "ProjectionPosePitch" 3857 path: "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPose 3858 Pitch)" 3860 id: "0x7674" 3862 minOccurs: "1" 3864 maxOccurs: "1" 3866 default: "0x0p+0" 3868 type: "float" 3870 minver: "4" 3872 documentation: Specifies a pitch rotation to the 3873 projection.SemanticsValue represents a counter-clockwise rotation, in 3874 degrees, around the right vector. This rotation must be applied 3875 after the ProjectionPoseYaw rotation and before the 3876 ProjectionPoseRoll rotation. The value of this field should be in 3877 the -90 to 90 degree range. 3879 8.2.140. ProjectionPoseRoll Element 3881 name: "ProjectionPoseRoll" 3883 path: 3884 "1*1(\Segment\Tracks\TrackEntry\Video\Projection\ProjectionPoseRoll)" 3886 id: "0x7675" 3888 minOccurs: "1" 3890 maxOccurs: "1" 3892 default: "0x0p+0" 3894 type: "float" 3896 minver: "4" 3898 documentation: Specifies a roll rotation to the 3899 projection.SemanticsValue represents a counter-clockwise rotation, in 3900 degrees, around the forward vector. This rotation must be applied 3901 after the ProjectionPoseYaw and ProjectionPosePitch rotations. The 3902 value of this field should be in the -180 to 180 degree range. 3904 8.2.141. Audio Element 3906 name: "Audio" 3908 path: "0*1(\Segment\Tracks\TrackEntry\Audio)" 3910 id: "0xE1" 3912 maxOccurs: "1" 3914 type: "master" 3916 minver: "1" 3918 documentation: Audio settings. 3920 8.2.142. SamplingFrequency Element 3922 name: "SamplingFrequency" 3924 path: "1*1(\Segment\Tracks\TrackEntry\Audio\SamplingFrequency)" 3926 id: "0xB5" 3927 minOccurs: "1" 3929 maxOccurs: "1" 3931 range: "> 0x0p+0" 3933 default: "0x1.f4p+12" 3935 type: "float" 3937 minver: "1" 3939 documentation: Sampling frequency in Hz. 3941 8.2.143. OutputSamplingFrequency Element 3943 name: "OutputSamplingFrequency" 3945 path: "0*1(\Segment\Tracks\TrackEntry\Audio\OutputSamplingFrequency)" 3947 id: "0x78B5" 3949 maxOccurs: "1" 3951 range: "> 0x0p+0" 3953 default: "SamplingFrequency" 3955 type: "float" 3957 minver: "1" 3959 documentation: Real output sampling frequency in Hz (used for SBR 3960 techniques). 3962 8.2.144. Channels Element 3964 name: "Channels" 3966 path: "1*1(\Segment\Tracks\TrackEntry\Audio\Channels)" 3968 id: "0x9F" 3970 minOccurs: "1" 3972 maxOccurs: "1" 3974 range: "not 0" 3975 default: "1" 3977 type: "uinteger" 3979 minver: "1" 3981 documentation: Numbers of channels in the track. 3983 8.2.145. ChannelPositions Element 3985 name: "ChannelPositions" 3987 path: "0*1(\Segment\Tracks\TrackEntry\Audio\ChannelPositions)" 3989 id: "0x7D7B" 3991 maxOccurs: "1" 3993 type: "binary" 3995 minver: "0" 3997 maxver: "0" 3999 documentation: Table of horizontal angles for each successive 4000 channel, see appendix. 4002 8.2.146. BitDepth Element 4004 name: "BitDepth" 4006 path: "0*1(\Segment\Tracks\TrackEntry\Audio\BitDepth)" 4008 id: "0x6264" 4010 maxOccurs: "1" 4012 range: "not 0" 4014 type: "uinteger" 4016 minver: "1" 4018 documentation: Bits per sample, mostly used for PCM. 4020 8.2.147. TrackOperation Element 4022 name: "TrackOperation" 4024 path: "0*1(\Segment\Tracks\TrackEntry\TrackOperation)" 4026 id: "0xE2" 4028 maxOccurs: "1" 4030 type: "master" 4032 minver: "3" 4034 documentation: Operation that needs to be applied on tracks to create 4035 this virtual track. For more details look at the Specification Notes 4036 on the subject. 4038 8.2.148. TrackCombinePlanes Element 4040 name: "TrackCombinePlanes" 4042 path: 4043 "0*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlanes)" 4045 id: "0xE3" 4047 maxOccurs: "1" 4049 type: "master" 4051 minver: "3" 4053 documentation: Contains the list of all video plane tracks that need 4054 to be combined to create this 3D track 4056 8.2.149. TrackPlane Element 4058 name: "TrackPlane" 4060 path: "1*(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlane 4061 s\TrackPlane)" 4063 id: "0xE4" 4065 minOccurs: "1" 4067 type: "master" 4068 minver: "3" 4070 documentation: Contains a video plane track that need to be combined 4071 to create this 3D track 4073 8.2.150. TrackPlaneUID Element 4075 name: "TrackPlaneUID" 4077 path: "1*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlan 4078 es\TrackPlane\TrackPlaneUID)" 4080 id: "0xE5" 4082 minOccurs: "1" 4084 maxOccurs: "1" 4086 range: "not 0" 4088 type: "uinteger" 4090 minver: "3" 4092 documentation: The trackUID number of the track representing the 4093 plane. 4095 8.2.151. TrackPlaneType Element 4097 name: "TrackPlaneType" 4099 path: "1*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackCombinePlan 4100 es\TrackPlane\TrackPlaneType)" 4102 id: "0xE6" 4104 minOccurs: "1" 4106 maxOccurs: "1" 4108 type: "uinteger" 4110 minver: "3" 4112 documentation: The kind of plane this track corresponds to. 4114 8.2.152. TrackJoinBlocks Element 4116 name: "TrackJoinBlocks" 4118 path: 4119 "0*1(\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks)" 4121 id: "0xE9" 4123 maxOccurs: "1" 4125 type: "master" 4127 minver: "3" 4129 documentation: Contains the list of all tracks whose Blocks need to 4130 be combined to create this virtual track 4132 8.2.153. TrackJoinUID Element 4134 name: "TrackJoinUID" 4136 path: "1*(\Segment\Tracks\TrackEntry\TrackOperation\TrackJoinBlocks\T 4137 rackJoinUID)" 4139 id: "0xED" 4141 minOccurs: "1" 4143 range: "not 0" 4145 type: "uinteger" 4147 minver: "3" 4149 documentation: The trackUID number of a track whose blocks are used 4150 to create this virtual track. 4152 8.2.154. TrickTrackUID Element 4154 name: "TrickTrackUID" 4156 path: "0*1(\Segment\Tracks\TrackEntry\TrickTrackUID)" 4158 id: "0xC0" 4160 maxOccurs: "1" 4161 type: "uinteger" 4163 minver: "0" 4165 maxver: "0" 4167 documentation: DivX trick track extensions 4169 8.2.155. TrickTrackSegmentUID Element 4171 name: "TrickTrackSegmentUID" 4173 path: "0*1(\Segment\Tracks\TrackEntry\TrickTrackSegmentUID)" 4175 id: "0xC1" 4177 maxOccurs: "1" 4179 size: "16" 4181 type: "binary" 4183 minver: "0" 4185 maxver: "0" 4187 documentation: DivX trick track extensions 4189 8.2.156. TrickTrackFlag Element 4191 name: "TrickTrackFlag" 4193 path: "0*1(\Segment\Tracks\TrackEntry\TrickTrackFlag)" 4195 id: "0xC6" 4197 maxOccurs: "1" 4199 default: "0" 4201 type: "uinteger" 4203 minver: "0" 4205 maxver: "0" 4207 documentation: DivX trick track extensions 4209 8.2.157. TrickMasterTrackUID Element 4211 name: "TrickMasterTrackUID" 4213 path: "0*1(\Segment\Tracks\TrackEntry\TrickMasterTrackUID)" 4215 id: "0xC7" 4217 maxOccurs: "1" 4219 type: "uinteger" 4221 minver: "0" 4223 maxver: "0" 4225 documentation: DivX trick track extensions 4227 8.2.158. TrickMasterTrackSegmentUID Element 4229 name: "TrickMasterTrackSegmentUID" 4231 path: "0*1(\Segment\Tracks\TrackEntry\TrickMasterTrackSegmentUID)" 4233 id: "0xC4" 4235 maxOccurs: "1" 4237 size: "16" 4239 type: "binary" 4241 minver: "0" 4243 maxver: "0" 4245 documentation: DivX trick track extensions 4247 8.2.159. ContentEncodings Element 4249 name: "ContentEncodings" 4251 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings)" 4253 id: "0x6D80" 4255 maxOccurs: "1" 4256 type: "master" 4258 minver: "1" 4260 documentation: Settings for several content encoding mechanisms like 4261 compression or encryption. 4263 8.2.160. ContentEncoding Element 4265 name: "ContentEncoding" 4267 path: 4268 "1*(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncoding)" 4270 id: "0x6240" 4272 minOccurs: "1" 4274 type: "master" 4276 minver: "1" 4278 documentation: Settings for one content encoding like compression or 4279 encryption. 4281 8.2.161. ContentEncodingOrder Element 4283 name: "ContentEncodingOrder" 4285 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4286 g\ContentEncodingOrder)" 4288 id: "0x5031" 4290 minOccurs: "1" 4292 maxOccurs: "1" 4294 default: "0" 4296 type: "uinteger" 4298 minver: "1" 4300 documentation: Tells when this modification was used during encoding/ 4301 muxing starting with 0 and counting upwards. The decoder/demuxer has 4302 to start with the highest order number it finds and work its way 4303 down. This value has to be unique over all ContentEncodingOrder 4304 Elements in the Segment. 4306 8.2.162. ContentEncodingScope Element 4308 name: "ContentEncodingScope" 4310 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4311 g\ContentEncodingScope)" 4313 id: "0x5032" 4315 minOccurs: "1" 4317 maxOccurs: "1" 4319 range: "not 0" 4321 default: "1" 4323 type: "uinteger" 4325 minver: "1" 4327 documentation: A bit field that describes which Elements have been 4328 modified in this way. Values (big endian) can be OR'ed. Possible 4329 values: 1 - all frame contents, 2 - the track's private data, 4 - the 4330 next ContentEncoding (next ContentEncodingOrder. Either the data 4331 inside ContentCompression and/or ContentEncryption) 4333 8.2.163. ContentEncodingType Element 4335 name: "ContentEncodingType" 4337 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4338 g\ContentEncodingType)" 4340 id: "0x5033" 4342 minOccurs: "1" 4344 maxOccurs: "1" 4346 default: "0" 4348 type: "uinteger" 4350 minver: "1" 4351 documentation: A value describing what kind of transformation has 4352 been done. Possible values: 0 - compression, 1 - encryption 4354 8.2.164. ContentCompression Element 4356 name: "ContentCompression" 4358 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4359 g\ContentCompression)" 4361 id: "0x5034" 4363 maxOccurs: "1" 4365 type: "master" 4367 minver: "1" 4369 documentation: Settings describing the compression used. This 4370 Element MUST be present if the value of ContentEncodingType is 0 and 4371 absent otherwise. Each block MUST be decompressable even if no 4372 previous block is available in order not to prevent seeking. 4374 8.2.165. ContentCompAlgo Element 4376 name: "ContentCompAlgo" 4378 path: "1*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4379 g\ContentCompression\ContentCompAlgo)" 4381 id: "0x4254" 4383 minOccurs: "1" 4385 maxOccurs: "1" 4387 default: "0" 4389 type: "uinteger" 4391 minver: "1" 4393 documentation: The compression algorithm used. Algorithms that have 4394 been specified so far are: 0 - zlib, 1 - bzlib, 2 - lzo1x 3 - Header 4395 Stripping 4397 8.2.166. ContentCompSettings Element 4399 name: "ContentCompSettings" 4401 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4402 g\ContentCompression\ContentCompSettings)" 4404 id: "0x4255" 4406 maxOccurs: "1" 4408 type: "binary" 4410 minver: "1" 4412 documentation: Settings that might be needed by the decompressor. 4413 For Header Stripping (ContentCompAlgo=3), the bytes that were removed 4414 from the beggining of each frames of the track. 4416 8.2.167. ContentEncryption Element 4418 name: "ContentEncryption" 4420 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4421 g\ContentEncryption)" 4423 id: "0x5035" 4425 maxOccurs: "1" 4427 type: "master" 4429 minver: "1" 4431 documentation: Settings describing the encryption used. This Element 4432 MUST be present if the value of ContentEncodingType is 1 and absent 4433 otherwise. 4435 8.2.168. ContentEncAlgo Element 4437 name: "ContentEncAlgo" 4439 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4440 g\ContentEncryption\ContentEncAlgo)" 4442 id: "0x47E1" 4444 maxOccurs: "1" 4445 default: "0" 4447 type: "uinteger" 4449 minver: "1" 4451 documentation: The encryption algorithm used. The value '0' means 4452 that the contents have not been encrypted but only signed. 4453 Predefined values: 1 - DES, 2 - 3DES, 3 - Twofish, 4 - Blowfish, 5 - 4454 AES 4456 8.2.169. ContentEncKeyID Element 4458 name: "ContentEncKeyID" 4460 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4461 g\ContentEncryption\ContentEncKeyID)" 4463 id: "0x47E2" 4465 maxOccurs: "1" 4467 type: "binary" 4469 minver: "1" 4471 documentation: For public key algorithms this is the ID of the public 4472 key the the data was encrypted with. 4474 8.2.170. ContentSignature Element 4476 name: "ContentSignature" 4478 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4479 g\ContentEncryption\ContentSignature)" 4481 id: "0x47E3" 4483 maxOccurs: "1" 4485 type: "binary" 4487 minver: "1" 4489 documentation: A cryptographic signature of the contents. 4491 8.2.171. ContentSigKeyID Element 4493 name: "ContentSigKeyID" 4495 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4496 g\ContentEncryption\ContentSigKeyID)" 4498 id: "0x47E4" 4500 maxOccurs: "1" 4502 type: "binary" 4504 minver: "1" 4506 documentation: This is the ID of the private key the data was signed 4507 with. 4509 8.2.172. ContentSigAlgo Element 4511 name: "ContentSigAlgo" 4513 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4514 g\ContentEncryption\ContentSigAlgo)" 4516 id: "0x47E5" 4518 maxOccurs: "1" 4520 default: "0" 4522 type: "uinteger" 4524 minver: "1" 4526 documentation: The algorithm used for the signature. A value of '0' 4527 means that the contents have not been signed but only encrypted. 4528 Predefined values: 1 - RSA 4530 8.2.173. ContentSigHashAlgo Element 4532 name: "ContentSigHashAlgo" 4534 path: "0*1(\Segment\Tracks\TrackEntry\ContentEncodings\ContentEncodin 4535 g\ContentEncryption\ContentSigHashAlgo)" 4537 id: "0x47E6" 4538 maxOccurs: "1" 4540 default: "0" 4542 type: "uinteger" 4544 minver: "1" 4546 documentation: The hash algorithm used for the signature. A value of 4547 '0' means that the contents have not been signed but only encrypted. 4548 Predefined values: 1 - SHA1-160 2 - MD5 4550 8.2.174. Cues Element 4552 name: "Cues" 4554 path: "0*1(\Segment\Cues)" 4556 id: "0x1C53BB6B" 4558 maxOccurs: "1" 4560 type: "master" 4562 minver: "1" 4564 documentation: A Top-Level Element to speed seeking access. All 4565 entries are local to the Segment. This Element SHOULD be mandatory 4566 for non "live" streams. 4568 8.2.175. CuePoint Element 4570 name: "CuePoint" 4572 path: "1*(\Segment\Cues\CuePoint)" 4574 id: "0xBB" 4576 minOccurs: "1" 4578 type: "master" 4580 minver: "1" 4582 documentation: Contains all information relative to a seek point in 4583 the Segment. 4585 8.2.176. CueTime Element 4587 name: "CueTime" 4589 path: "1*1(\Segment\Cues\CuePoint\CueTime)" 4591 id: "0xB3" 4593 minOccurs: "1" 4595 maxOccurs: "1" 4597 type: "uinteger" 4599 minver: "1" 4601 documentation: Absolute timestamp according to the Segment time base. 4603 8.2.177. CueTrackPositions Element 4605 name: "CueTrackPositions" 4607 path: "1*(\Segment\Cues\CuePoint\CueTrackPositions)" 4609 id: "0xB7" 4611 minOccurs: "1" 4613 type: "master" 4615 minver: "1" 4617 documentation: Contain positions for different tracks corresponding 4618 to the timestamp. 4620 8.2.178. CueTrack Element 4622 name: "CueTrack" 4624 path: "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueTrack)" 4626 id: "0xF7" 4628 minOccurs: "1" 4630 maxOccurs: "1" 4632 range: "not 0" 4633 type: "uinteger" 4635 minver: "1" 4637 documentation: The track for which a position is given. 4639 8.2.179. CueClusterPosition Element 4641 name: "CueClusterPosition" 4643 path: 4644 "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueClusterPosition)" 4646 id: "0xF1" 4648 minOccurs: "1" 4650 maxOccurs: "1" 4652 type: "uinteger" 4654 minver: "1" 4656 documentation: The Segment Position of the Cluster containing the 4657 associated Block. 4659 8.2.180. CueRelativePosition Element 4661 name: "CueRelativePosition" 4663 path: 4664 "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueRelativePosition)" 4666 id: "0xF0" 4668 maxOccurs: "1" 4670 type: "uinteger" 4672 minver: "4" 4674 documentation: The relative position of the referenced block inside 4675 the cluster with 0 being the first possible position for an Element 4676 inside that cluster. 4678 8.2.181. CueDuration Element 4680 name: "CueDuration" 4682 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueDuration)" 4684 id: "0xB2" 4686 maxOccurs: "1" 4688 type: "uinteger" 4690 minver: "4" 4692 documentation: The duration of the block according to the Segment 4693 time base. If missing the track's DefaultDuration does not apply and 4694 no duration information is available in terms of the cues. 4696 8.2.182. CueBlockNumber Element 4698 name: "CueBlockNumber" 4700 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueBlockNumber)" 4702 id: "0x5378" 4704 maxOccurs: "1" 4706 range: "not 0" 4708 default: "1" 4710 type: "uinteger" 4712 minver: "1" 4714 documentation: Number of the Block in the specified Cluster. 4716 8.2.183. CueCodecState Element 4718 name: "CueCodecState" 4720 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueCodecState)" 4722 id: "0xEA" 4724 maxOccurs: "1" 4725 default: "0" 4727 type: "uinteger" 4729 minver: "2" 4731 documentation: The Segment Position of the Codec State corresponding 4732 to this Cue Element. 0 means that the data is taken from the initial 4733 Track Entry. 4735 8.2.184. CueReference Element 4737 name: "CueReference" 4739 path: "0*(\Segment\Cues\CuePoint\CueTrackPositions\CueReference)" 4741 id: "0xDB" 4743 type: "master" 4745 minver: "2" 4747 documentation: The Clusters containing the referenced Blocks. 4749 8.2.185. CueRefTime Element 4751 name: "CueRefTime" 4753 path: "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 4754 efTime)" 4756 id: "0x96" 4758 minOccurs: "1" 4760 maxOccurs: "1" 4762 type: "uinteger" 4764 minver: "2" 4766 documentation: Timestamp of the referenced Block. 4768 8.2.186. CueRefCluster Element 4770 name: "CueRefCluster" 4771 path: "1*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 4772 efCluster)" 4774 id: "0x97" 4776 minOccurs: "1" 4778 maxOccurs: "1" 4780 type: "uinteger" 4782 minver: "0" 4784 maxver: "0" 4786 documentation: The Segment Position of the Cluster containing the 4787 referenced Block. 4789 8.2.187. CueRefNumber Element 4791 name: "CueRefNumber" 4793 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 4794 efNumber)" 4796 id: "0x535F" 4798 maxOccurs: "1" 4800 range: "not 0" 4802 default: "1" 4804 type: "uinteger" 4806 minver: "0" 4808 maxver: "0" 4810 documentation: Number of the referenced Block of Track X in the 4811 specified Cluster. 4813 8.2.188. CueRefCodecState Element 4815 name: "CueRefCodecState" 4817 path: "0*1(\Segment\Cues\CuePoint\CueTrackPositions\CueReference\CueR 4818 efCodecState)" 4819 id: "0xEB" 4821 maxOccurs: "1" 4823 default: "0" 4825 type: "uinteger" 4827 minver: "0" 4829 maxver: "0" 4831 documentation: The Segment Position of the Codec State corresponding 4832 to this referenced Element. 0 means that the data is taken from the 4833 initial Track Entry. 4835 8.2.189. Attachments Element 4837 name: "Attachments" 4839 path: "0*1(\Segment\Attachments)" 4841 id: "0x1941A469" 4843 maxOccurs: "1" 4845 type: "master" 4847 minver: "1" 4849 documentation: Contain attached files. 4851 8.2.190. AttachedFile Element 4853 name: "AttachedFile" 4855 path: "1*(\Segment\Attachments\AttachedFile)" 4857 id: "0x61A7" 4859 minOccurs: "1" 4861 type: "master" 4863 minver: "1" 4865 documentation: An attached file. 4867 8.2.191. FileDescription Element 4869 name: "FileDescription" 4871 path: "0*1(\Segment\Attachments\AttachedFile\FileDescription)" 4873 id: "0x467E" 4875 maxOccurs: "1" 4877 type: "utf-8" 4879 minver: "1" 4881 documentation: A human-friendly name for the attached file. 4883 8.2.192. FileName Element 4885 name: "FileName" 4887 path: "1*1(\Segment\Attachments\AttachedFile\FileName)" 4889 id: "0x466E" 4891 minOccurs: "1" 4893 maxOccurs: "1" 4895 type: "utf-8" 4897 minver: "1" 4899 documentation: Filename of the attached file. 4901 8.2.193. FileMimeType Element 4903 name: "FileMimeType" 4905 path: "1*1(\Segment\Attachments\AttachedFile\FileMimeType)" 4907 id: "0x4660" 4909 minOccurs: "1" 4911 maxOccurs: "1" 4913 type: "string" 4914 minver: "1" 4916 documentation: MIME type of the file. 4918 8.2.194. FileData Element 4920 name: "FileData" 4922 path: "1*1(\Segment\Attachments\AttachedFile\FileData)" 4924 id: "0x465C" 4926 minOccurs: "1" 4928 maxOccurs: "1" 4930 type: "binary" 4932 minver: "1" 4934 documentation: The data of the file. 4936 8.2.195. FileUID Element 4938 name: "FileUID" 4940 path: "1*1(\Segment\Attachments\AttachedFile\FileUID)" 4942 id: "0x46AE" 4944 minOccurs: "1" 4946 maxOccurs: "1" 4948 range: "not 0" 4950 type: "uinteger" 4952 minver: "1" 4954 documentation: Unique ID representing the file, as random as 4955 possible. 4957 8.2.196. FileReferral Element 4959 name: "FileReferral" 4961 path: "0*1(\Segment\Attachments\AttachedFile\FileReferral)" 4962 id: "0x4675" 4964 maxOccurs: "1" 4966 type: "binary" 4968 minver: "0" 4970 maxver: "0" 4972 documentation: A binary value that a track/codec can refer to when 4973 the attachment is needed. 4975 8.2.197. FileUsedStartTime Element 4977 name: "FileUsedStartTime" 4979 path: "0*1(\Segment\Attachments\AttachedFile\FileUsedStartTime)" 4981 id: "0x4661" 4983 maxOccurs: "1" 4985 type: "uinteger" 4987 minver: "0" 4989 maxver: "0" 4991 documentation: DivX font extension 4993 8.2.198. FileUsedEndTime Element 4995 name: "FileUsedEndTime" 4997 path: "0*1(\Segment\Attachments\AttachedFile\FileUsedEndTime)" 4999 id: "0x4662" 5001 maxOccurs: "1" 5003 type: "uinteger" 5005 minver: "0" 5007 maxver: "0" 5009 documentation: DivX font extension 5011 8.2.199. Chapters Element 5013 name: "Chapters" 5015 path: "0*1(\Segment\Chapters)" 5017 id: "0x1043A770" 5019 maxOccurs: "1" 5021 type: "master" 5023 minver: "1" 5025 documentation: A system to define basic menus and partition data. 5026 For more detailed information, look at the Chapters Explanation. 5028 8.2.200. EditionEntry Element 5030 name: "EditionEntry" 5032 path: "1*(\Segment\Chapters\EditionEntry)" 5034 id: "0x45B9" 5036 minOccurs: "1" 5038 type: "master" 5040 minver: "1" 5042 documentation: Contains all information about a Segment edition. 5044 8.2.201. EditionUID Element 5046 name: "EditionUID" 5048 path: "0*1(\Segment\Chapters\EditionEntry\EditionUID)" 5050 id: "0x45BC" 5052 maxOccurs: "1" 5054 range: "not 0" 5056 type: "uinteger" 5058 minver: "1" 5059 documentation: A unique ID to identify the edition. It's useful for 5060 tagging an edition. 5062 8.2.202. EditionFlagHidden Element 5064 name: "EditionFlagHidden" 5066 path: "1*1(\Segment\Chapters\EditionEntry\EditionFlagHidden)" 5068 id: "0x45BD" 5070 minOccurs: "1" 5072 maxOccurs: "1" 5074 range: "0-1" 5076 default: "0" 5078 type: "uinteger" 5080 minver: "1" 5082 documentation: If an edition is hidden (1), it SHOULD NOT be 5083 available to the user interface (but still to Control Tracks; see 5084 flag notes). (1 bit) 5086 8.2.203. EditionFlagDefault Element 5088 name: "EditionFlagDefault" 5090 path: "1*1(\Segment\Chapters\EditionEntry\EditionFlagDefault)" 5092 id: "0x45DB" 5094 minOccurs: "1" 5096 maxOccurs: "1" 5098 range: "0-1" 5100 default: "0" 5102 type: "uinteger" 5104 minver: "1" 5105 documentation: If a flag is set (1) the edition SHOULD be used as the 5106 default one. (1 bit) 5108 8.2.204. EditionFlagOrdered Element 5110 name: "EditionFlagOrdered" 5112 path: "0*1(\Segment\Chapters\EditionEntry\EditionFlagOrdered)" 5114 id: "0x45DD" 5116 maxOccurs: "1" 5118 range: "0-1" 5120 default: "0" 5122 type: "uinteger" 5124 minver: "1" 5126 documentation: Specify if the chapters can be defined multiple times 5127 and the order to play them is enforced. (1 bit) 5129 8.2.205. ChapterAtom Element 5131 name: "ChapterAtom" 5133 path: "1*(\Segment\Chapters\EditionEntry(1*(\ChapterAtom)))" 5135 id: "0xB6" 5137 minOccurs: "1" 5139 type: "master" 5141 recursive: "1" 5143 minver: "1" 5145 documentation: Contains the atom information to use as the chapter 5146 atom (apply to all tracks). 5148 8.2.206. ChapterUID Element 5150 name: "ChapterUID" 5152 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterUID)" 5153 id: "0x73C4" 5155 minOccurs: "1" 5157 maxOccurs: "1" 5159 range: "not 0" 5161 type: "uinteger" 5163 minver: "1" 5165 documentation: A unique ID to identify the Chapter. 5167 8.2.207. ChapterStringUID Element 5169 name: "ChapterStringUID" 5171 path: 5172 "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterStringUID)" 5174 id: "0x5654" 5176 maxOccurs: "1" 5178 type: "utf-8" 5180 minver: "3" 5182 documentation: A unique string ID to identify the Chapter. Use for 5183 WebVTT cue identifier storage. 5185 8.2.208. ChapterTimeStart Element 5187 name: "ChapterTimeStart" 5189 path: 5190 "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTimeStart)" 5192 id: "0x91" 5194 minOccurs: "1" 5196 maxOccurs: "1" 5198 type: "uinteger" 5200 minver: "1" 5201 documentation: Timestamp of the start of Chapter (not scaled). 5203 8.2.209. ChapterTimeEnd Element 5205 name: "ChapterTimeEnd" 5207 path: 5208 "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTimeEnd)" 5210 id: "0x92" 5212 maxOccurs: "1" 5214 type: "uinteger" 5216 minver: "1" 5218 documentation: Timestamp of the end of Chapter (timestamp excluded, 5219 not scaled). 5221 8.2.210. ChapterFlagHidden Element 5223 name: "ChapterFlagHidden" 5225 path: 5226 "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterFlagHidden)" 5228 id: "0x98" 5230 minOccurs: "1" 5232 maxOccurs: "1" 5234 range: "0-1" 5236 default: "0" 5238 type: "uinteger" 5240 minver: "1" 5242 documentation: If a chapter is hidden (1), it SHOULD NOT be available 5243 to the user interface (but still to Control Tracks; see flag notes). 5244 (1 bit) 5246 8.2.211. ChapterFlagEnabled Element 5248 name: "ChapterFlagEnabled" 5250 path: 5251 "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterFlagEnabled)" 5253 id: "0x4598" 5255 minOccurs: "1" 5257 maxOccurs: "1" 5259 range: "0-1" 5261 default: "1" 5263 type: "uinteger" 5265 minver: "1" 5267 documentation: Specify whether the chapter is enabled. It can be 5268 enabled/disabled by a Control Track. When disabled, the movie SHOULD 5269 skip all the content between the TimeStart and TimeEnd of this 5270 chapter (see flag notes). (1 bit) 5272 8.2.212. ChapterSegmentUID Element 5274 name: "ChapterSegmentUID" 5276 path: 5277 "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterSegmentUID)" 5279 id: "0x6E67" 5281 maxOccurs: "1" 5283 range: ">0" 5285 size: "16" 5287 type: "binary" 5289 minver: "1" 5291 documentation: The SegmentUID of another Segment to play during this 5292 chapter. 5294 usage notes: ChapterSegmentUID is mandatory if 5295 ChapterSegmentEditionUID is used. 5297 8.2.213. ChapterSegmentEditionUID Element 5299 name: "ChapterSegmentEditionUID" 5301 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterSegmentE 5302 ditionUID)" 5304 id: "0x6EBC" 5306 maxOccurs: "1" 5308 range: "not 0" 5310 type: "uinteger" 5312 minver: "1" 5314 documentation: The EditionUID to play from the Segment linked in 5315 ChapterSegmentUID. If ChapterSegmentEditionUID is undeclared then no 5316 Edition of the linked Segment is used. 5318 8.2.214. ChapterPhysicalEquiv Element 5320 name: "ChapterPhysicalEquiv" 5322 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterPhysical 5323 Equiv)" 5325 id: "0x63C3" 5327 maxOccurs: "1" 5329 type: "uinteger" 5331 minver: "1" 5333 documentation: Specify the physical equivalent of this ChapterAtom 5334 like "DVD" (60) or "SIDE" (50), see complete list of values. 5336 8.2.215. ChapterTrack Element 5338 name: "ChapterTrack" 5340 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTrack)" 5341 id: "0x8F" 5343 maxOccurs: "1" 5345 type: "master" 5347 minver: "1" 5349 documentation: List of tracks on which the chapter applies. If this 5350 Element is not present, all tracks apply 5352 8.2.216. ChapterTrackNumber Element 5354 name: "ChapterTrackNumber" 5356 path: "1*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterTrack\Cha 5357 pterTrackNumber)" 5359 id: "0x89" 5361 minOccurs: "1" 5363 range: "not 0" 5365 type: "uinteger" 5367 minver: "1" 5369 documentation: UID of the Track to apply this chapter too. In the 5370 absence of a control track, choosing this chapter will select the 5371 listed Tracks and deselect unlisted tracks. Absence of this Element 5372 indicates that the Chapter SHOULD be applied to any currently used 5373 Tracks. 5375 8.2.217. ChapterDisplay Element 5377 name: "ChapterDisplay" 5379 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay)" 5381 id: "0x80" 5383 type: "master" 5385 minver: "1" 5387 documentation: Contains all possible strings to use for the chapter 5388 display. 5390 8.2.218. ChapString Element 5392 name: "ChapString" 5394 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\ 5395 ChapString)" 5397 id: "0x85" 5399 minOccurs: "1" 5401 maxOccurs: "1" 5403 type: "utf-8" 5405 minver: "1" 5407 documentation: Contains the string to use as the chapter atom. 5409 8.2.219. ChapLanguage Element 5411 name: "ChapLanguage" 5413 path: "1*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\C 5414 hapLanguage)" 5416 id: "0x437C" 5418 minOccurs: "1" 5420 default: "eng" 5422 type: "string" 5424 minver: "1" 5426 documentation: The languages corresponding to the string, in the 5427 bibliographic ISO-639-2 form. This Element MUST be ignored if the 5428 ChapLanguageIETF Element is used within the same ChapterDisplay 5429 Element. 5431 8.2.220. ChapLanguageIETF Element 5433 name: "ChapLanguageIETF" 5435 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\ 5436 ChapLanguageIETF)" 5437 id: "0x437D" 5439 maxOccurs: "1" 5441 type: "string" 5443 minver: "4" 5445 documentation: Specifies the language used in the ChapString 5446 according to BCP 47 and using the IANA Language Subtag Registry. If 5447 this Element is used, then any ChapLanguage Elements used in the same 5448 ChapterDisplay MUST be ignored. 5450 8.2.221. ChapCountry Element 5452 name: "ChapCountry" 5454 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapterDisplay\C 5455 hapCountry)" 5457 id: "0x437E" 5459 type: "string" 5461 minver: "1" 5463 documentation: The countries corresponding to the string, same 2 5464 octets as in Internet domains. This Element MUST be ignored if the 5465 ChapLanguageIETF Element is used within the same ChapterDisplay 5466 Element. 5468 8.2.222. ChapProcess Element 5470 name: "ChapProcess" 5472 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess)" 5474 id: "0x6944" 5476 type: "master" 5478 minver: "1" 5480 documentation: Contains all the commands associated to the Atom. 5482 8.2.223. ChapProcessCodecID Element 5484 name: "ChapProcessCodecID" 5486 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5487 pProcessCodecID)" 5489 id: "0x6955" 5491 minOccurs: "1" 5493 maxOccurs: "1" 5495 default: "0" 5497 type: "uinteger" 5499 minver: "1" 5501 documentation: Contains the type of the codec used for the 5502 processing. A value of 0 means native Matroska processing (to be 5503 defined), a value of 1 means the DVD command set is used. More codec 5504 IDs can be added later. 5506 8.2.224. ChapProcessPrivate Element 5508 name: "ChapProcessPrivate" 5510 path: "0*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5511 pProcessPrivate)" 5513 id: "0x450D" 5515 maxOccurs: "1" 5517 type: "binary" 5519 minver: "1" 5521 documentation: Some optional data attached to the ChapProcessCodecID 5522 information. For ChapProcessCodecID = 1, it is the "DVD level" 5523 equivalent. 5525 8.2.225. ChapProcessCommand Element 5527 name: "ChapProcessCommand" 5528 path: "0*(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Chap 5529 ProcessCommand)" 5531 id: "0x6911" 5533 type: "master" 5535 minver: "1" 5537 documentation: Contains all the commands associated to the Atom. 5539 8.2.226. ChapProcessTime Element 5541 name: "ChapProcessTime" 5543 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5544 pProcessCommand\ChapProcessTime)" 5546 id: "0x6922" 5548 minOccurs: "1" 5550 maxOccurs: "1" 5552 type: "uinteger" 5554 minver: "1" 5556 documentation: Defines when the process command SHOULD be handled 5558 8.2.227. ChapProcessData Element 5560 name: "ChapProcessData" 5562 path: "1*1(\Segment\Chapters\EditionEntry\ChapterAtom\ChapProcess\Cha 5563 pProcessCommand\ChapProcessData)" 5565 id: "0x6933" 5567 minOccurs: "1" 5569 maxOccurs: "1" 5571 type: "binary" 5573 minver: "1" 5574 documentation: Contains the command information. The data SHOULD be 5575 interpreted depending on the ChapProcessCodecID value. For 5576 ChapProcessCodecID = 1, the data correspond to the binary DVD cell 5577 pre/post commands. 5579 8.2.228. Tags Element 5581 name: "Tags" 5583 path: "0*(\Segment\Tags)" 5585 id: "0x1254C367" 5587 type: "master" 5589 minver: "1" 5591 documentation: Element containing metadata describing Tracks, 5592 Editions, Chapters, Attachments, or the Segment as a whole. A list 5593 of valid tags can be found here. 5595 8.2.229. Tag Element 5597 name: "Tag" 5599 path: "1*(\Segment\Tags\Tag)" 5601 id: "0x7373" 5603 minOccurs: "1" 5605 type: "master" 5607 minver: "1" 5609 documentation: A single metadata descriptor. 5611 8.2.230. Targets Element 5613 name: "Targets" 5615 path: "1*1(\Segment\Tags\Tag\Targets)" 5617 id: "0x63C0" 5619 minOccurs: "1" 5621 maxOccurs: "1" 5622 type: "master" 5624 minver: "1" 5626 documentation: Specifies which other elements the metadata 5627 represented by the Tag applies to. If empty or not present, then the 5628 Tag describes everything in the Segment. 5630 8.2.231. TargetTypeValue Element 5632 name: "TargetTypeValue" 5634 path: "0*1(\Segment\Tags\Tag\Targets\TargetTypeValue)" 5636 id: "0x68CA" 5638 maxOccurs: "1" 5640 default: "50" 5642 type: "uinteger" 5644 minver: "1" 5646 documentation: A number to indicate the logical level of the target. 5648 8.2.232. TargetType Element 5650 name: "TargetType" 5652 path: "0*1(\Segment\Tags\Tag\Targets\TargetType)" 5654 id: "0x63CA" 5656 maxOccurs: "1" 5658 type: "string" 5660 minver: "1" 5662 documentation: An informational string that can be used to display 5663 the logical level of the target like "ALBUM", "TRACK", "MOVIE", 5664 "CHAPTER", etc (see TargetType). 5666 8.2.233. TagTrackUID Element 5668 name: "TagTrackUID" 5670 path: "0*(\Segment\Tags\Tag\Targets\TagTrackUID)" 5672 id: "0x63C5" 5674 default: "0" 5676 type: "uinteger" 5678 minver: "1" 5680 documentation: A unique ID to identify the Track(s) the tags belong 5681 to. If the value is 0 at this level, the tags apply to all tracks in 5682 the Segment. 5684 8.2.234. TagEditionUID Element 5686 name: "TagEditionUID" 5688 path: "0*(\Segment\Tags\Tag\Targets\TagEditionUID)" 5690 id: "0x63C9" 5692 default: "0" 5694 type: "uinteger" 5696 minver: "1" 5698 documentation: A unique ID to identify the EditionEntry(s) the tags 5699 belong to. If the value is 0 at this level, the tags apply to all 5700 editions in the Segment. 5702 8.2.235. TagChapterUID Element 5704 name: "TagChapterUID" 5706 path: "0*(\Segment\Tags\Tag\Targets\TagChapterUID)" 5708 id: "0x63C4" 5710 default: "0" 5712 type: "uinteger" 5713 minver: "1" 5715 documentation: A unique ID to identify the Chapter(s) the tags belong 5716 to. If the value is 0 at this level, the tags apply to all chapters 5717 in the Segment. 5719 8.2.236. TagAttachmentUID Element 5721 name: "TagAttachmentUID" 5723 path: "0*(\Segment\Tags\Tag\Targets\TagAttachmentUID)" 5725 id: "0x63C6" 5727 default: "0" 5729 type: "uinteger" 5731 minver: "1" 5733 documentation: A unique ID to identify the Attachment(s) the tags 5734 belong to. If the value is 0 at this level, the tags apply to all 5735 the attachments in the Segment. 5737 8.2.237. SimpleTag Element 5739 name: "SimpleTag" 5741 path: "1*(\Segment\Tags\Tag(1*(\SimpleTag)))" 5743 id: "0x67C8" 5745 minOccurs: "1" 5747 type: "master" 5749 recursive: "1" 5751 minver: "1" 5753 documentation: Contains general information about the target. 5755 8.2.238. TagName Element 5757 name: "TagName" 5759 path: "1*1(\Segment\Tags\Tag\SimpleTag\TagName)" 5760 id: "0x45A3" 5762 minOccurs: "1" 5764 maxOccurs: "1" 5766 type: "utf-8" 5768 minver: "1" 5770 documentation: The name of the Tag that is going to be stored. 5772 8.2.239. TagLanguage Element 5774 name: "TagLanguage" 5776 path: "1*1(\Segment\Tags\Tag\SimpleTag\TagLanguage)" 5778 id: "0x447A" 5780 minOccurs: "1" 5782 maxOccurs: "1" 5784 default: "und" 5786 type: "string" 5788 minver: "1" 5790 documentation: Specifies the language of the tag specified, in the 5791 Matroska languages form. This Element MUST be ignored if the 5792 TagLanguageIETF Element is used within the same SimpleTag Element. 5794 8.2.240. TagLanguageIETF Element 5796 name: "TagLanguageIETF" 5798 path: "0*1(\Segment\Tags\Tag\SimpleTag\TagLanguageIETF)" 5800 id: "0x447B" 5802 maxOccurs: "1" 5804 type: "string" 5806 minver: "4" 5807 documentation: Specifies the language used in the TagString according 5808 to BCP 47 and using the IANA Language Subtag Registry. If this 5809 Element is used, then any TagLanguage Elements used in the same 5810 SimpleTag MUST be ignored. 5812 8.2.241. TagDefault Element 5814 name: "TagDefault" 5816 path: "1*1(\Segment\Tags\Tag\SimpleTag\TagDefault)" 5818 id: "0x4484" 5820 minOccurs: "1" 5822 maxOccurs: "1" 5824 range: "0-1" 5826 default: "1" 5828 type: "uinteger" 5830 minver: "1" 5832 documentation: A boolean value to indicate if this is the default/ 5833 original language to use for the given tag. 5835 8.2.242. TagString Element 5837 name: "TagString" 5839 path: "0*1(\Segment\Tags\Tag\SimpleTag\TagString)" 5841 id: "0x4487" 5843 maxOccurs: "1" 5845 type: "utf-8" 5847 minver: "1" 5849 documentation: The value of the Tag. 5851 8.2.243. TagBinary Element 5853 name: "TagBinary" 5855 path: "0*1(\Segment\Tags\Tag\SimpleTag\TagBinary)" 5857 id: "0x4485" 5859 maxOccurs: "1" 5861 type: "binary" 5863 minver: "1" 5865 documentation: The values of the Tag if it is binary. Note that this 5866 cannot be used in the same SimpleTag as TagString. 5868 9. Matroska Element Ordering Guidelines 5870 Except for the "EBML Header" and the "CRC-32 Element", the EBML 5871 specification does not require any particular storage order for 5872 "Elements". The Matroska specification however defines mandates and 5873 recommendations for ordering certain "Elements" in order to 5874 facilitate better playback, seeking, and editing efficiency. This 5875 section describes and offers rationale for ordering requirements and 5876 recommendations for Matroska. 5878 9.1. Top-Level Elements 5880 The "Info Element" is the only REQUIRED "Top-Level Element" in a 5881 Matroska file. To be playable, Matroska MUST also contain at least 5882 one "Tracks Element" and "Cluster Element". The first "Info Element" 5883 and the first "Tracks Element" MUST either be stored before the first 5884 "Cluster Element" or both SHALL be referenced by a "SeekHead Element" 5885 occurring before the first "Cluster Element". 5887 It is possible to edit a Matroska file after it has been created. 5888 For example, chapters, tags or attachments can be added. When new 5889 "Top-Level Elements" are added to a Matroska file, the "SeekHead" 5890 Element(s) MUST be updated so that the "SeekHead" Element(s) itemize 5891 the identity and position of all "Top-Level Elements". Editing, 5892 removing, or adding "Elements" to a Matroska file often requires that 5893 some existing "Elements" be voided or extended; therefore, it is 5894 RECOMMENDED to use "Void Elements" as padding in between "Top-Level 5895 Elements". 5897 9.2. CRC-32 5899 As noted by the EBML specification, if a "CRC-32 Element" is used 5900 then the "CRC-32 Element" MUST be the first ordered "Element" within 5901 its "Parent Element". The Matroska specification recommends that 5902 "CRC-32 Elements" SHOULD NOT be used as an immediate "Child Element" 5903 of the "Segment Element"; however all "Top-Level Elements" of an 5904 "EBML Document" SHOULD include a "CRC-32 Element" as a "Child 5905 Element". 5907 9.3. SeekHead 5909 If used, the first "SeekHead Element" SHOULD be the first non-"CRC-32 5910 Child Element" of the "Segment Element". If a second "SeekHead 5911 Element" is used, then the first "SeekHead Element" MUST reference 5912 the identity and position of the second "SeekHead". Additionally, 5913 the second "SeekHead Element" MUST only reference "Cluster" Elements 5914 and not any other "Top-Level Element" already contained within the 5915 first "SeekHead Element". The second "SeekHead Element" MAY be 5916 stored in any order relative to the other "Top-Level Elements." 5917 Whether one or two "SeekHead Element(s)" are used, the "SeekHead 5918 Element(s)" MUST collectively reference the identity and position of 5919 all "Top-Level Elements" except for the first "SeekHead Element". 5921 It is RECOMMENDED that the first "SeekHead Element" be followed by a 5922 "Void Element" to allow for the "SeekHead Element" to be expanded to 5923 cover new "Top-Level Elements" that could be added to the Matroska 5924 file, such as "Tags", "Chapters" and "Attachments Elements". 5926 9.4. Cues (index) 5928 The "Cues Element" is RECOMMENDED to optimize seeking access in 5929 Matroska. It is programmatically simpler to add the "Cues Element" 5930 after all "Cluster Elements" have been written because this does not 5931 require a prediction of how much space to reserve before writing the 5932 "Cluster Elements". However, storing the "Cues Element" before the 5933 "Cluster Elements" can provide some seeking advantages. If the "Cues 5934 Element" is present, then it SHOULD either be stored before the first 5935 "Cluster Element" or be referenced by a "SeekHead Element". 5937 9.5. Info 5939 The first "Info Element" SHOULD occur before the first "Tracks 5940 Element" and first "Cluster Element" except when referenced by a 5941 "SeekHead Element". 5943 9.6. Chapters 5945 The "Chapters Element" SHOULD be placed before the "Cluster 5946 Element(s)". The "Chapters Element" can be used during playback even 5947 if the user does not need to seek. It immediately gives the user 5948 information about what section is being read and what other sections 5949 are available. In the case of Ordered Chapters it RECOMMENDED to 5950 evaluate the logical linking even before playing. The "Chapters 5951 Element" SHOULD be placed before the first "Tracks Element" and after 5952 the first "Info Element". 5954 9.7. Attachments 5956 The "Attachments Element" is not intended to be used by default when 5957 playing the file, but could contain information relevant to the 5958 content, such as cover art or fonts. Cover art is useful even before 5959 the file is played and fonts could be needed before playback starts 5960 for initialization of subtitles. The "Attachments Element" MAY be 5961 placed before the first "Cluster Element"; however if the 5962 "Attachments Element" is likely to be edited, then it SHOULD be 5963 placed after the last "Cluster Element". 5965 9.8. Tags 5967 The "Tags Element" is most subject to changes after the file was 5968 originally created. For easier editing, the "Tags Element" SHOULD be 5969 placed at the end of the "Segment Element", even after the 5970 "Attachments Element". On the other hand, it is inconvenient to have 5971 to seek in the "Segment" for tags, especially for network streams. 5972 So it's better if the "Tags Element" is found early in the stream. 5973 When editing the "Tags Element", the original "Tags Element" at the 5974 beginning can be overwritten with a "Void Element" and a new "Tags 5975 Element" written at the end of the "Segment Element". The file size 5976 will only marginally change. 5978 9.9. Optimum layout from a muxer 5980 o SeekHead 5982 o Info 5984 o Tracks 5986 o Chapters 5988 o Attachments 5990 o Tags 5991 o Clusters 5993 o Cues 5995 9.10. Optimum layout after editing tags 5997 o SeekHead 5999 o Info 6001 o Tracks 6003 o Chapters 6005 o Attachments 6007 o Void 6009 o Clusters 6011 o Cues 6013 o Tags 6015 9.11. Optimum layout with Cues at the front 6017 o SeekHead 6019 o Info 6021 o Tracks 6023 o Chapters 6025 o Attachments 6027 o Tags 6029 o Cues 6031 o Clusters 6033 9.12. Cluster Timecode 6035 The "Timecode Element" MUST occur as in storage order before any 6036 "SimpleBlock", "BlockGroup", or "EncryptedBlock" within the "Cluster 6037 Element". 6039 10. Chapters 6041 10.1. Edition and Chapter Flags 6043 10.1.1. Chapter Flags 6045 Two "Chapter Flags" are defined to describe the behavior of the 6046 "ChapterAtom Element": "ChapterFlagHidden" and "ChapterFlagEnabled". 6048 If a "ChapterAtom Element" is the "Child Element" of another 6049 "ChapterAtom Element" with a "Chapter Flag" set to "true", then the 6050 "Child ChapterAtom Element" MUST be interpreted as having its same 6051 "Chapter Flag" set to "true". If a "ChapterAtom Element" is the 6052 "Child Element" of another "ChapterAtom Element" with a "Chapter 6053 Flag" set to "false" or if the "ChapterAtom Element" does not have a 6054 "ChapterAtom Element" as its "Parent Element", then it MUST be 6055 interpreted according to its own "Chapter Flag". 6057 As an example, consider a "Parent ChapterAtom Element" that has its 6058 "ChapterFlagHidden" set to "true" and also contains two child 6059 "ChapterAtoms", the first with "ChapterFlagHidden" set to "true" and 6060 the second with "ChapterFlagHidden" either set to "false" or not 6061 present at all (in which case the default value of the Element 6062 applies, which is "false"). Since the parent "ChapterAtom" has its 6063 "ChapterFlagHidden" set to "true" then all of its children 6064 "ChapterAtoms" MUST also be interpreted as if their 6065 "ChapterFlagHidden" is also set to "true". However, if a "Control 6066 Track" toggles the parent's "ChapterFlagHidden" flag to "false", then 6067 only the parent "ChapterAtom" and its second child "ChapterAtom" MUST 6068 be interpreted as if "ChapterFlagHidden" is set to "false". The 6069 first child "ChapterAtom" which has the "ChapterFlagHidden" flag set 6070 to "true" retains its value until its value is toggled to "false" by 6071 a "Control Track". 6073 10.1.2. Edition Flags 6075 Three "Edition Flags" are defined to describe the behavior of the 6076 "EditionEntry Element": "EditionFlagHidden", "EditionFlagDefault" and 6077 "EditionFlagOrdered". 6079 10.1.2.1. EditionFlagHidden 6081 The "EditionFlagHidden Flag" behaves similarly to the 6082 "ChapterFlagHidden Flag": if "EditionFlagHidden" is set to "true", 6083 its "Child ChapterAtoms Elements" MUST also be interpreted as if 6084 their "ChapterFlagHidden" is also set to "true", regardless of their 6085 own "ChapterFlagHidden Flags". If "EditionFlagHidden" is toggled by 6086 a "Control Track" to "false", the "ChapterFlagHidden Flags" of the 6087 "Child ChapterAtoms Elements" SHALL determine whether the 6088 "ChapterAtom" is hidden or not. 6090 10.1.2.2. EditionFlagDefault 6092 It is RECOMMENDED that no more than one "Edition" have an 6093 "EditionFlagDefault Flag" set to "true". The first "Edition" with 6094 both the "EditionFlagDefault Flag" set to "true" and the 6095 "EditionFlagHidden Flag" set to "false" is the "Default Edition". 6096 When all "EditionFlagDefault Flags" are set to "false", then the 6097 first "Edition" is the "Default Edition". 6099 10.1.2.3. EditionFlagOrdered 6101 The "EditionFlagOrdered Flag" is a significant feature as it enables 6102 an "Edition" of "Ordered Chapters" which defines and arranges a 6103 virtual timeline rather than simply labeling points within the 6104 timeline. For example, with "Editions" of "Ordered Chapters" a 6105 single "Matroska file" can present multiple edits of a film without 6106 duplicating content. Alternatively if a videotape is digitized in 6107 full, one "Ordered Edition" could present the full content (including 6108 colorbars, countdown, slate, a feature presentation, and black 6109 frames), while another "Edition" of "Ordered Chapters" can use 6110 "Chapters" that only mark the intended presentation with the 6111 colorbars and other ancillary visual information excluded. If an 6112 "Edition" of "Ordered Chapters" is enabled then the "Matroska Player" 6113 MUST play those Chapters in their stored order from the timecode 6114 marked in the "ChapterTimeStart Element" to the timecode marked in to 6115 "ChapterTimeEnd Element". 6117 If the "EditionFlagOrdered Flag" is set to "false", "Simple Chapters" 6118 are used and only the "ChapterTimeStart" of a "Chapter" is used as 6119 chapter mark to jump to the predefined point in the timeline. With 6120 "Simple Chapters", a "Matroska Player" MUST ignore certain "Chapter 6121 Elements". All these elements are now informational only. 6123 The following list shows the different usage of "Chapter Elements" 6124 between an ordered and non-ordered "Edition". 6126 Chapter elements / ordered Edition | False | True ChapterUID | X | X 6127 ChapterStringUID | X | X ChapterTimeStart | X | X ChapterTimeEnd | 6128 - | X ChapterFlagHidden | X | X ChapterFlagEnabled | X | X 6129 ChapterSegmentUID | - | X ChapterSegmentEditionUID | - | X 6130 ChapterPhysicalEquiv | X | X ChapterTrack | - | X ChapterDisplay | 6131 X | X ChapProcess | - | X 6133 Furthermore there are other EBML "Elements" which could be used if 6134 the "EditionFlagOrdered Flag" is set to "true". 6136 Other elements / ordered Edition | False | True Info/SegmentFamily | 6137 - | X Info/ChapterTranslate | - | X Track/TrackTranslate | - | X 6139 These other "Elements" belong to the Matroska DVD menu system and are 6140 only used when the "ChapProcessCodecID Element" is set to 1. 6142 10.1.2.3.1. Ordered-Edition and Matroska Segment-Linking 6144 o Hard Linking: "Ordered-Chapters" supersedes the "Hard Linking". 6146 o Soft Linking: In this complex system "Ordered Chapters" are 6147 REQUIRED and a "Chapter CODEC" MUST interpret the "ChapProcess" of 6148 all chapters. 6150 o Medium Linking: "Ordered Chapters" are used in a normal way and 6151 can be combined with the "ChapterSegmentUID" element which 6152 establishes a link to another Matroska file/Segment. 6154 See Section 23) for more information about "Hard Linking", "Soft 6155 Linking" and "Medium Linking". 6157 10.2. Menu features 6159 The menu features are handled like a _chapter codec_. That means each 6160 codec has a type, some private data and some data in the chapters. 6162 The type of the menu system is defined by the "ChapProcessCodecID" 6163 parameter. For now only 2 values are supported : 0 matroska script, 6164 1 menu borrowed from the DVD. The private data depend on the type of 6165 menu system (stored in ChapProcessPrivate), idem for the data in the 6166 chapters (stored in ChapProcessData). 6168 10.2.1. Matroska Script (0) 6170 This is the case when "ChapProcessCodecID" = 0. This is a script 6171 language build for Matroska purposes. The inspiration comes from 6172 ActionScript, javascript and other similar scripting languages. The 6173 commands are stored as text commands, in UTF-8. The syntax is C 6174 like, with commands spanned on many lines, each terminating with a 6175 ";". You can also include comments at the end of lines with "//" or 6176 comment many lines using "/* */". The scripts are stored in 6177 ChapProcessData. For the moment ChapProcessPrivate is not used. 6179 The one and only command existing for the moment is "GotoAndPlay( 6180 ChapterUID );". As the same suggests, it means that when this 6181 command is encountered, the "Matroska Player" SHOULD jump to the 6182 "Chapter" specified by the UID and play it. 6184 10.2.2. DVD menu (1) 6186 This is the case when "ChapProcessCodecID" = 1. Each level of a 6187 chapter corresponds to a logical level in the DVD system that is 6188 stored in the first octet of the ChapProcessPrivate. This DVD 6189 hierarchy is as follows: 6191 ChapProcessPrivate | DVD Name | Hierarchy | Commands Possible | 6192 Comment 0x30 | SS | DVD domain | - | First Play, Video Manager, Video 6193 Title 0x2A | LU | Language Unit | - | Contains only PGCs 0x28 | TT | 6194 Title | - | Contains only PGCs 0x20 | PGC | Program Group Chain 6195 (PGC) | * | 0x18 | PG | Program 1 / Program 2 / Program 3 | - | 6196 0x10 | PTT | Part Of Title 1 / Part Of Title 2 | - | Equivalent to 6197 the chapters on the sleeve. 0x08 | CN | Cell 1 / Cell 2 / Cell 3 / 6198 Cell 4 / Cell 5 / Cell 6 | - | 6200 You can also recover wether a Segment is a Video Manager (VMG), Video 6201 Title Set (VTS) or Video Title Set Menu (VTSM) from the 6202 ChapterTranslateID element found in the Segment Info. This field 6203 uses 2 octets as follows: 6205 1. Domain Type: 0 for VMG, the domain number for VTS and VTSM 6207 2. Domain Value: 0 for VMG and VTSM, 1 for the VTS source. 6209 For instance, the menu part from VTS_01_0.VOB would be coded [1,0] 6210 and the content part from VTS_02_3.VOB would be [2,1]. The VMG is 6211 always [0,0] 6213 The following octets of ChapProcessPrivate are as follows: 6215 Octet 1 | DVD Name | Following Octets 0x30 | SS | Domain name code 6216 (1: 0x00= First play, 0xC0= VMG, 0x40= VTSM, 0x80= VTS) + VTS(M) 6217 number (2) 0x2A | LU | Language code (2) + Language extension (1) 6218 0x28 | TT | global Title number (2) + corresponding TTN of the VTS 6219 (1) 0x20 | PGC | PGC number (2) + Playback Type (1) + Disabled User 6220 Operations (4) 0x18 | PG | Program number (2) 0x10 | PTT | PTT- 6221 chapter number (1) 0x08 | CN | Cell number [VOB ID(2)][Cell 6222 ID(1)][Angle Num(1)] 6224 If the level specified in ChapProcessPrivate is a PGC (0x20), there 6225 is an octet called the Playback Type, specifying the kind of PGC 6226 defined: 6228 o 0x00: entry only/basic PGC 6230 o 0x82: Title+Entry Menu (only found in the Video Manager domain) 6231 o 0x83: Root Menu (only found in the VTSM domain) 6233 o 0x84: Subpicture Menu (only found in the VTSM domain) 6235 o 0x85: Audio Menu (only found in the VTSM domain) 6237 o 0x86: Angle Menu (only found in the VTSM domain) 6239 o 0x87: Chapter Menu (only found in the VTSM domain) 6241 The next 4 following octets correspond to the User Operation flags 6242 [17] in the standard PGC. When a bit is set, the command SHOULD be 6243 disabled. 6245 ChapProcessData contains the pre/post/cell commands in binary format 6246 as there are stored on a DVD. There is just an octet preceding these 6247 data to specify the number of commands in the element. As follows: 6248 [# of commands(1)][command 1 (8)][command 2 (8)][command 3 (8)]. 6250 More information on the DVD commands and format on DVD-replica [18], 6251 where we got most of the info about it. You can also get information 6252 on DVD from the DVDinfo project [19]. 6254 10.3. Example 1 : basic chaptering 6256 In this example a movie is split in different chapters. It could 6257 also just be an audio file (album) on which each track corresponds to 6258 a chapter. 6260 o 00000ms - 05000ms : Intro 6262 o 05000ms - 25000ms : Before the crime 6264 o 25000ms - 27500ms : The crime 6266 o 27500ms - 38000ms : The killer arrested 6268 o 38000ms - 43000ms : Credits 6270 This would translate in the following matroska form : 6272 6273 6274 16603393396715046047 6275 6276 1193046 6277 0 6278 5000000000 6279 6280 Intro 6281 eng 6282 6283 0 6284 1 6285 6286 6287 2311527 6288 5000000000 6289 25000000000 6290 6291 Before the crime 6292 eng 6293 6294 6295 Avant le crime 6296 fra 6297 6298 0 6299 1 6300 6301 6302 3430008 6303 25000000000 6304 27500000000 6305 6306 The crime 6307 eng 6308 6309 6310 Le crime 6311 fra 6312 6313 0 6314 1 6315 6316 6317 4548489 6318 27500000000 6319 38000000000 6320 6321 After the crime 6322 eng 6323 6324 6325 Apres le crime 6326 fra 6328 6329 0 6330 1 6331 6332 6333 5666960 6334 38000000000 6335 43000000000 6336 6337 Credits 6338 eng 6339 6340 6341 Generique 6342 fra 6343 6344 0 6345 1 6346 6347 0 6348 0 6349 6350 6352 10.4. Example 2 : nested chapters 6354 In this example an (existing) album is split into different chapters, 6355 and one of them contain another splitting. 6357 10.4.1. The Micronauts "Bleep To Bleep" 6359 o 00:00 - 12:28 : Baby Wants To Bleep/Rock 6361 * 00:00 - 04:38 : Baby wants to bleep (pt.1) 6363 * 04:38 - 07:12 : Baby wants to rock 6365 * 07:12 - 10:33 : Baby wants to bleep (pt.2) 6367 * 10:33 - 12:28 : Baby wants to bleep (pt.3) 6369 o 12:30 - 19:38 : Bleeper_O+2 6371 o 19:40 - 22:20 : Baby wants to bleep (pt.4) 6373 o 22:22 - 25:18 : Bleep to bleep 6375 o 25:20 - 33:35 : Baby wants to bleep (k) 6376 o 33:37 - 44:28 : Bleeper 6378 6379 6380 1281690858003401414 6381 6382 1 6383 0 6384 748000000 6385 6386 Baby wants to Bleep/Rock 6387 eng 6388 6389 6390 2 6391 0 6392 278000000 6393 6394 Baby wants to bleep (pt.1) 6395 eng 6396 6397 0 6398 1 6399 6400 6401 3 6402 278000000 6403 432000000 6404 6405 Baby wants to rock 6406 eng 6407 6408 0 6409 1 6410 6411 6412 4 6413 432000000 6414 633000000 6415 6416 Baby wants to bleep (pt.2) 6417 eng 6418 6419 0 6420 1 6421 6422 6423 5 6424 633000000 6425 748000000 6426 6427 Baby wants to bleep (pt.3) 6428 eng 6429 6430 0 6431 1 6432 6433 0 6434 1 6435 6436 6437 6 6438 750000000 6439 1178500000 6440 6441 Bleeper_O+2 6442 eng 6443 6444 0 6445 1 6446 6447 6448 7 6449 1180500000 6450 1340000000 6451 6452 Baby wants to bleep (pt.4) 6453 eng 6454 6455 0 6456 1 6457 6458 6459 8 6460 1342000000 6461 1518000000 6462 6463 Bleep to bleep 6464 eng 6465 6466 0 6467 1 6468 6469 6470 9 6471 1520000000 6472 2015000000 6473 6474 Baby wants to bleep (k) 6475 eng 6476 6477 0 6478 1 6479 6480 6481 10 6482 2017000000 6483 2668000000 6484 6485 Bleeper 6486 eng 6487 6488 0 6489 1 6490 6491 0 6492 0 6493 6494 6496 11. Attachments 6498 11.1. Introduction 6500 Matroska supports storage of related files and data in the 6501 "Attachments Element" (a "Top-Level Element"). "Attachment Elements" 6502 can be used to store related cover art, font files, transcripts, 6503 reports, error recovery files, picture or text-based annotations, 6504 copies of specifications, or other ancillary files related to the 6505 "Segment". 6507 "Matroska Readers" MUST NOT execute files stored as "Attachment 6508 Elements". 6510 11.2. Cover Art 6512 This section defines a set of guidelines for the storage of cover art 6513 in Matroska files. A "Matroska Reader" MAY use embedded cover art to 6514 display a representational still-image depiction of the multimedia 6515 contents of the Matroska file. 6517 Only JPEG and PNG image formats SHOULD be used for cover art 6518 pictures. 6520 There can be two different covers for a movie/album: a portrait style 6521 (e.g., a DVD case) and a landscape style (e.g., a wide banner ad). 6523 There can be two versions of the same cover, the "normal cover" and 6524 the "small cover". The dimension of the "normal cover" SHOULD be 600 6525 pixels on the smallest side (for example, 960x600 for landscape, 6526 600x800 for portrait, or 600x600 for square). The dimension of the 6527 "small cover" SHOULD be 120 pixels on the smallest side (for example, 6528 192x120 or 120x160). 6530 Versions of cover art can be differentiated by the filename, which is 6531 stored in the "FileName Element". The default filename of the 6532 "normal cover" in square or portrait mode is "cover.(jpg|png)". When 6533 stored, the "normal cover" SHOULD be the first Attachment in storage 6534 order. The "small cover" SHOULD be prefixed with "small_", such as 6535 "small_cover.(jpg|png)". The landscape variant SHOULD be suffixed 6536 with "_land", such as "cover_land.(jpg|png)". The filenames are case 6537 sensitive. 6539 The following table provides examples of file names for cover art in 6540 Attachments. 6542 FileName | Image Orientation | Pixel Length of Smallest Side 6543 cover.jpg | Portrait or square | 600 small_cover.png | Portrait or 6544 square | 120 cover_land.png | Landscape | 600 small_cover_land.jpg | 6545 Landscape | 120 6547 12. Cues 6549 12.1. Introduction 6551 The "Cues Element" provides an index of certain "Cluster Elements" to 6552 allow for optimized seeking to absolute timestamps within the 6553 "Segment". The "Cues Element" contains one or many "CuePoint 6554 Elements" which each MUST reference an absolute timestamp (via the 6555 "CueTime Element"), a "Track" (via the "CueTrack Element"), and a 6556 "Segment Position" (via the "CueClusterPosition Element"). 6557 Additional non-mandated Elements are part of the "CuePoint Element" 6558 such as "CueDuration", "CueRelativePosition", "CueCodecState" and 6559 others which provide any "Matroska Reader" with additional 6560 information to use in the optimization of seeking performance. 6562 12.2. Recommendations 6564 The following recommendations are provided to optimize Matroska 6565 performance. 6567 o Unless Matroska is used as a live stream, it SHOULD contain a 6568 "Cues Element". 6570 o For each video track, each keyframe SHOULD be referenced by a 6571 "CuePoint Element". 6573 o It is RECOMMENDED to not reference non-keyframes of video tracks 6574 in "Cues" unless it references a "Cluster Element" which contains 6575 a "CodecState Element" but no keyframes. 6577 o For each subtitle track present, each subtitle frame SHOULD be 6578 referenced by a "CuePoint Element" with a "CueDuration Element". 6580 o References to audio tracks MAY be skipped in "CuePoint Elements" 6581 if a video track is present. When included the "CuePoint 6582 Elements" SHOULD reference audio keyframes at most once every 500 6583 milliseconds. 6585 o If the referenced frame is not stored within the first 6586 "SimpleBlock" or first "BlockGroup" within its "Cluster Element", 6587 then the "CueRelativePosition Element" SHOULD be written to 6588 reference where in the "Cluster" the reference frame is stored. 6590 o If a "CuePoint Element" references "Cluster Element" that includes 6591 a "CodecState Element", then that "CuePoint Element" MUST use a 6592 "CueCodecState Element". 6594 o "CuePoint Elements" SHOULD be numerically sorted in storage order 6595 by the value of the "CueTime Element". 6597 13. Matroska Streaming 6599 In Matroska, there are two kinds of streaming: file access and 6600 livestreaming. 6602 13.1. File Access 6604 File access can simply be reading a file located on your computer, 6605 but also includes accessing a file from an HTTP (web) server or CIFS 6606 (Windows share) server. These protocols are usually safe from 6607 reading errors and seeking in the stream is possible. However, when 6608 a file is stored far away or on a slow server, seeking can be an 6609 expensive operation and SHOULD be avoided. The following guidelines, 6610 when followed, help reduce the number of seeking operations for 6611 regular playback and also have the playback start quickly without a 6612 lot of data needed to read first (like a "Cues Element", "Attachment 6613 Element" or "SeekHead Element"). 6615 Matroska, having a small overhead, is well suited for storing music/ 6616 videos on file servers without a big impact on the bandwidth used. 6617 Matroska does not require the index to be loaded before playing, 6618 which allows playback to start very quickly. The index can be loaded 6619 only when seeking is requested the first time. 6621 13.2. Livestreaming 6623 Livestreaming is the equivalent of television broadcasting on the 6624 internet. There are 2 families of servers for livestreaming: RTP/ 6625 RTSP and HTTP. Matroska is not meant to be used over RTP. RTP 6626 already has timing and channel mechanisms that would be wasted if 6627 doubled in Matroska. Additionally, having the same information at 6628 the RTP and Matroska level would be a source of confusion if they do 6629 not match. Livestreaming of Matroska over HTTP (or any other plain 6630 protocol based on TCP) is possible. 6632 A live Matroska stream is different from a file because it usually 6633 has no known end (only ending when the client disconnects). For 6634 this, all bits of the "size" portion of the "Segment Element" MUST be 6635 set to 1. Another option is to concatenate "Segment Elements" with 6636 known sizes, one after the other. This solution allows a change of 6637 codec/resolution between each segment. For example, this allows for 6638 a switch between 4:3 and 16:9 in a television program. 6640 When "Segment Elements" are continuous, certain "Elements", like 6641 "MetaSeek", "Cues", "Chapters", and "Attachments", MUST NOT be used. 6643 It is possible for a "Matroska Player" to detect that a stream is not 6644 seekable. If the stream has neither a "MetaSeek" list or a "Cues" 6645 list at the beginning of the stream, it SHOULD be considered non- 6646 seekable. Even though it is possible to seek blindly forward in the 6647 stream, it is NOT RECOMMENDED. 6649 In the context of live radio or web TV, it is possible to "tag" the 6650 content while it is playing. The "Tags Element" can be placed 6651 between "Clusters" each time it is necessary. In that case, the new 6652 "Tags Element" MUST reset the previously encountered "Tags Elements" 6653 and use the new values instead. 6655 14. Menu Specifications 6657 14.1. Introduction 6659 This document is a _draft of the Menu system_ that will be the 6660 default one in "Matroska". As it will just be composed of a Control 6661 Track, it will be seen as a "codec" and could be replaced later by 6662 something else if needed. 6664 A menu is like what you see on DVDs, when you have some screens to 6665 select the audio format, subtitles or scene selection. 6667 14.2. Requirements 6669 What we'll try to have is a system that can do almost everything done 6670 on a DVD, or more, or better, or drop the unused features if 6671 necessary. 6673 As the name suggests, a Control Track is a track that can control the 6674 playback of the file and/or all the playback features. To make it as 6675 simple as possible for "Matroska Players", the Control Track will 6676 just give orders to the "Matroska Player" and get the actions 6677 associated with the highlights/hotspots. 6679 14.2.1. Highlights/Hotspots 6681 A highlight is basically a rectangle/key associated with an action 6682 UID. When that rectangle/key is activated, the "Matroska Player" 6683 send the UID of the action to the Control Track handler (codec). The 6684 fact that it can also be a key means that even for audio only files, 6685 a keyboard shortcut or button panel could be used for menus. But in 6686 that case, the hotspot will have to be associated with a name to 6687 display. 6689 This highlight is sent from the Control Track to the "Matroska 6690 Player". Then the "Matroska Player" has to handle that highlight 6691 until it's deactivated (see Section 14.2.2). 6693 The highlight contains a UID of the action, a displayable name (UTF- 6694 8), an associated key (list of keys to be defined, probably 6695 up/down/left/right/select), a screen position/range and an image to 6696 display. The image will be displayed either when the user place the 6697 mouse over the rectangle (or any other shape), or when an option of 6698 the screen is selected (not activated). There could be a second 6699 image used when the option is activated. And there could be a third 6700 image that can serve as background. This way you could have a still 6701 image (like in some DVDs) for the menu and behind that image blank 6702 video (small bitrate). 6704 When a highlight is activated by the user, the "Matroska Player" has 6705 to send the UID of the action to the Control Track. Then the Control 6706 Track codec will handle the action and possibly give new orders to 6707 the "Matroska Player". 6709 The format used for storing images SHOULD be extensible. For the 6710 moment we'll use PNG and BMP, both with alpha channel. 6712 14.2.2. Playback features 6714 All the following features will be sent from the Control Track to the 6715 "Matroska Player" : 6717 o Jump to chapter (UID, prev, next, number) 6719 o Disable all tracks of a kind (audio, video, subtitle) 6721 o Enable track UID (the kind doesn't matter) 6723 o Define/Disable a highlight 6725 o Enable/Disable jumping 6727 o Enable/Disable track selection of a kind 6729 o Select Edition ID (see chapters) 6731 o Pause playback 6733 o Stop playback 6735 o Enable/Disable a Chapter UID 6737 o Hide/Unhide a Chapter UID 6739 All the actions will be written in a normal Matroska track, with a 6740 timecode. A "Menu Frame" SHOULD be able to contain more that one 6741 action/highlight for a given timecode. (to be determined, EBML format 6742 structure) 6744 14.2.3. Player requirements 6746 Some "Matroska Players" might not support the control track. That 6747 mean they will play the active/looped parts as part of the data. So 6748 I suggest putting the active/looped parts of a movie at the end of a 6749 movie. When a Menu-aware "Matroska Player" encounter the default 6750 Control Track of a "Matroska" file, the first order SHOULD be to jump 6751 at the start of the active/looped part of the movie. 6753 14.3. Working Graph 6755 Matroska Source file -> Control Track <-> Player. 6756 -> other tracks -> rendered 6758 14.4. Ideas 6760 !!!! KNOW Where the main/audio/subs menu starts wherever we are (use chapters) !!!! 6762 !!!! Keep in mind the state of the selected tracks of each kind (more than 1 for each possible) !!!! 6763 !!!! Order of blending !!!! 6764 !!!! What if a command is not supported by the player ? !!!! 6765 !!!! Track selection issue, only applies when 'quitting' the menu (but still possible to change live too) !!!! 6766 !!!! Allow to hide (not render) some parts of a movie for certain editions !!!! 6767 !!!! Get the parental level of the player (can be changed live) !!!! 6769 14.5. Data Structure 6771 As a Matroska side project, the obvious choice for storing binary 6772 data is EBML. 6774 15. Unknown elements 6776 Matroska is based upon the principle that a reading application does 6777 not have to support 100% of the specifications in order to be able to 6778 play the file. A Matroska file therefore contains version indicators 6779 that tell a reading application what to expect. 6781 It is possible and valid to have the version fields indicate that the 6782 file contains Matroska "Elements" from a higher specification version 6783 number while signaling that a reading application MUST only support a 6784 lower version number properly in order to play it back (possibly with 6785 a reduced feature set). For example, a reading application 6786 supporting at least Matroska version "V" reading a file whose 6787 "DocTypeReadVersion" field is equal to or lower than "V" MUST skip 6788 Matroska/EBML "Elements" it encounters but does not know about if 6789 that unknown element fits into the size constraints set by the 6790 current "Parent Element". 6792 16. Default Values 6794 The default value of an "Element" is assumed when not present in the 6795 data stream. It is assumed only in the scope of its "Parent 6796 Element". For example, the "Language Element" is in the scope of the 6797 "Track Element". If the "Parent Element" is not present or assumed, 6798 then the "Child Element" cannot be assumed. 6800 17. DefaultDecodedFieldDuration 6802 The "DefaultDecodedFieldDuration Element" can signal to the 6803 displaying application how often fields of a video sequence will be 6804 available for displaying. It can be used for both interlaced and 6805 progressive content. If the video sequence is signaled as 6806 interlaced, then the period between two successive fields at the 6807 output of the decoding process equals "DefaultDecodedFieldDuration". 6809 For video sequences signaled as progressive, it is twice the value of 6810 "DefaultDecodedFieldDuration". 6812 These values are valid at the end of the decoding process before 6813 post-processing (such as deinterlacing or inverse telecine) is 6814 applied. 6816 Examples: 6818 o Blu-ray movie: 1000000000ns/(48/1.001) = 20854167ns 6820 o PAL broadcast/DVD: 1000000000ns/(50/1.000) = 20000000ns 6822 o N/ATSC broadcast: 1000000000ns/(60/1.001) = 16683333ns 6824 o hard-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (60 6825 encoded interlaced fields per second) 6827 o soft-telecined DVD: 1000000000ns/(60/1.001) = 16683333ns (48 6828 encoded interlaced fields per second, with "repeat_first_field = 6829 1") 6831 18. Encryption 6833 Encryption in Matroska is designed in a very generic style to allow 6834 people to implement whatever form of encryption is best for them. It 6835 is possible to use the encryption framework in Matroska as a type of 6836 DRM (Digital Rights Management). 6838 Because encryption occurs within the "Block Element", it is possible 6839 to manipulate encrypted streams without decrypting them. The streams 6840 could potentially be copied, deleted, cut, appended, or any number of 6841 other possible editing techniques without decryption. The data can 6842 be used without having to expose it or go through the decrypting 6843 process. 6845 Encryption can also be layered within Matroska. This means that two 6846 completely different types of encryption can be used, requiring two 6847 separate keys to be able to decrypt a stream. 6849 Encryption information is stored in the "ContentEncodings Element" 6850 under the "ContentEncryption Element". 6852 19. Image cropping 6854 The "PixelCrop Elements" ("PixelCropTop", "PixelCropBottom", 6855 "PixelCropRight" and "PixelCropLeft") indicate when and by how much 6856 encoded videos frames SHOULD be cropped for display. These Elements 6857 allow edges of the frame that are not intended for display, such as 6858 the sprockets of a full-frame film scan or the VANC area of a 6859 digitized analog videotape, to be stored but hidden. "PixelCropTop" 6860 and "PixelCropBottom" store an integer of how many rows of pixels 6861 SHOULD be cropped from the top and bottom of the image 6862 (respectively). "PixelCropLeft" and "PixelCropRight" store an 6863 integer of how many columns of pixels SHOULD be cropped from the left 6864 and right of the image (respectively). For example, a pillar-boxed 6865 video that stores a 1440x1080 visual image within the center of a 6866 padded 1920x1080 encoded image MAY set both "PixelCropLeft" and 6867 "PixelCropRight" to "240", so that a "Matroska Player" SHOULD crop 6868 off 240 columns of pixels from the left and right of the encoded 6869 image to present the image with the pillar-boxes hidden. 6871 20. Matroska versioning 6873 The "EBML Header" of each Matroska document informs the reading 6874 application on what version of Matroska to expect. The "Elements" 6875 within "EBML Header" with jurisdiction over this information are 6876 "DocTypeVersion" and "DocTypeReadVersion". 6878 "DocTypeVersion" MUST be equal to or greater than the highest 6879 Matroska version number of any "Element" present in the Matroska 6880 file. For example, a file using the "SimpleBlock Element" MUST have 6881 a "DocTypeVersion" equal to or greater than 2. A file containing 6882 "CueRelativePosition" Elements MUST have a "DocTypeVersion" equal to 6883 or greater than 4. 6885 The "DocTypeReadVersion" MUST contain the minimum version number that 6886 a reading application can minimally support in order to play the file 6887 back -- optionally with a reduced feature set. For example, if a 6888 file contains only "Elements" of version 2 or lower except for 6889 "CueRelativePosition" (which is a version 4 Matroska "Element"), then 6890 "DocTypeReadVersion" SHOULD still be set to 2 and not 4 because 6891 evaluating "CueRelativePosition" is not necessary for standard 6892 playback -- it makes seeking more precise if used. 6894 "DocTypeVersion" MUST always be equal to or greater than 6895 "DocTypeReadVersion". 6897 A reading application supporting Matroska version "V" MUST NOT refuse 6898 to read an application with "DocReadTypeVersion" equal to or lower 6899 than "V" even if "DocTypeVersion" is greater than "V". See also the 6900 note about Section 15. 6902 21. MIME Types 6904 There is no IETF endorsed MIME type for Matroska files. These 6905 definitions can be used: 6907 o .mka : Matroska audio "audio/x-matroska" 6909 o .mkv : Matroska video "video/x-matroska" 6911 o .mk3d : Matroska 3D video "video/x-matroska-3d" 6913 22. Segment Position 6915 The "Segment Position" of an "Element" refers to the position of the 6916 first octet of the "Element ID" of that "Element", measured in 6917 octets, from the beginning of the "Element Data" section of the 6918 containing "Segment Element". In other words, the "Segment Position" 6919 of an "Element" is the distance in octets from the beginning of its 6920 containing "Segment Element" minus the size of the "Element ID" and 6921 "Element Data Size" of that "Segment Element". The "Segment 6922 Position" of the first "Child Element" of the "Segment Element" is 0. 6923 An "Element" which is not stored within a "Segment Element", such as 6924 the "Elements" of the "EBML Header", do not have a "Segment 6925 Position". 6927 22.1. Segment Position Exception 6929 "Elements" that are defined to store a "Segment Position" MAY define 6930 reserved values to indicate a special meaning. 6932 22.2. Example of Segment Position 6934 This table presents an example of "Segment Position" by showing a 6935 hexadecimal representation of a very small Matroska file with labels 6936 to show the offsets in octets. The file contains a "Segment Element" 6937 with an "Element ID" of "0x18538067" and a "MuxingApp Element" with 6938 an "Element ID" of "0x4D80". 6940 0 1 2 6941 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 6942 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 6943 0 |1A|45|DF|A3|8B|42|82|88|6D|61|74|72|6F|73|6B|61|18|53|80|67| 6944 20 |93|15|49|A9|66|8E|4D|80|84|69|65|74|66|57|41|84|69|65|74|66| 6946 In the above example, the "Element ID" of the "Segment Element" is 6947 stored at offset 16, the "Element Data Size" of the "Segment Element" 6948 is stored at offset 20, and the "Element Data" of the "Segment 6949 Element" is stored at offset 21. 6951 The "MuxingApp Element" is stored at offset 26. Since the "Segment 6952 Position" of an "Element" is calculated by subtracting the position 6953 of the "Element Data" of the containing "Segment Element" from the 6954 position of that "Element", the "Segment Position" of "MuxingApp 6955 Element" in the above example is "26 - 21" or "5". 6957 23. Linked Segments 6959 Matroska provides several methods to link two or many "Segment 6960 Elements" together to create a "Linked Segment". A "Linked Segment" 6961 is a set of multiple "Segments" related together into a single 6962 presentation by using Hard Linking, Medium Linking, or Soft Linking. 6963 All "Segments" within a "Linked Segment" MUST utilize the same track 6964 numbers and timescale. All "Segments" within a "Linked Segment" MUST 6965 be stored within the same directory. All "Segments" within a "Linked 6966 Segment" MUST store a "SegmentUID". 6968 23.1. Hard Linking 6970 Hard Linking (also called splitting) is the process of creating a 6971 "Linked Segment" by relating multiple "Segment Elements" using the 6972 "PrevUID" and "NextUID Elements". Within a "Linked Segment", the 6973 timestamps of each "Segment" MUST follow consecutively in linking 6974 order. With Hard Linking, the chapters of any "Segment" within the 6975 "Linked Segment" MUST only reference the current "Segment". With 6976 Hard Linking, the "NextUID" and "PrevUID" MUST reference the 6977 respective "SegmentUID" values of the next and previous "Segments". 6978 The first "Segment" of a "Linked Segment" MUST have a "NextUID 6979 Element" and MUST NOT have a "PrevUID Element". The last "Segment" 6980 of a "Linked Segment" MUST have a "PrevUID Element" and MUST NOT have 6981 a "NextUID Element". The middle "Segments" of a "Linked Segment" 6982 MUST have both a "NextUID Element" and a "PrevUID Element". 6984 As an example, four "Segments" can be Hard Linked as a "Linked 6985 Segment" through cross-referencing each other with "SegmentUID", 6986 "PrevUID", and "NextUID", as in this table. 6988 +--------+------------------+-------------------+-------------------+ 6989 | file | SegmentUID | PrevUID | NextUID | 6990 | name | | | | 6991 +--------+------------------+-------------------+-------------------+ 6992 | "start | "71000c23cd31099 | n/a | "a77b3598941cb803 | 6993 | .mkv" | 853fbc94dd984a5d | | eac0fcdafe44fac9" | 6994 | | d" | | | 6995 | "middl | "a77b3598941cb80 | "71000c23cd310998 | "6c92285fa6d3e827 | 6996 | e.mkv" | 3eac0fcdafe44fac | 53fbc94dd984a5dd" | b198d120ea3ac674" | 6997 | | 9" | | | 6998 | "end.m | "6c92285fa6d3e82 | "a77b3598941cb803 | n/a | 6999 | kv" | 7b198d120ea3ac67 | eac0fcdafe44fac9" | | 7000 | | 4" | | | 7001 +--------+------------------+-------------------+-------------------+ 7003 23.2. Medium Linking 7005 Medium Linking creates relationships between "Segments" using Ordered 7006 Chapters and the "ChapterSegmentUID Element". A "Segment Edition" 7007 with Ordered Chapters MAY contain "Chapter Elements" that reference 7008 timestamp ranges from other "Segments". The "Segment" referenced by 7009 the Ordered Chapter via the "ChapterSegmentUID Element" SHOULD be 7010 played as part of a Linked Segment. The timestamps of Segment 7011 content referenced by Ordered Chapters MUST be adjusted according to 7012 the cumulative duration of the the previous Ordered Chapters. 7014 As an example a file named "intro.mkv" could have a "SegmentUID" of 7015 "0xb16a58609fc7e60653a60c984fc11ead". Another file called 7016 "program.mkv" could use a Chapter Edition that contains two Ordered 7017 Chapters. The first chapter references the "Segment" of "intro.mkv" 7018 with the use of a "ChapterSegmentUID", "ChapterSegmentEditionUID", 7019 "ChapterTimeStart" and optionally a "ChapterTimeEnd" element. The 7020 second chapter references content within the "Segment" of 7021 "program.mkv". A "Matroska Player" SHOULD recognize the "Linked 7022 Segment" created by the use of "ChapterSegmentUID" in an enabled 7023 "Edition" and present the reference content of the two "Segments" 7024 together. 7026 23.3. Soft Linking 7028 Soft Linking is used by codec chapters. They can reference another 7029 "Segment" and jump to that "Segment". The way the "Segments" are 7030 described are internal to the chapter codec and unknown to the 7031 Matroska level. But there are "Elements" within the "Info Element" 7032 (such as "ChapterTranslate") that can translate a value representing 7033 a "Segment" in the chapter codec and to the current "SegmentUID". 7034 All "Segments" that could be used in a "Linked Segment" in this way 7035 SHOULD be marked as members of the same family via the "SegmentFamily 7036 Element", so that the "Matroska Player" can quickly switch from one 7037 to the other. 7039 24. Track Flags 7041 24.1. Default flag 7043 The "default track" flag is a hint for a "Matroska Player" and SHOULD 7044 always be changeable by the user. If the user wants to see or hear a 7045 track of a certain kind (audio, video, subtitles) and hasn't chosen a 7046 specific track, the "Matroska Player" SHOULD use the first track of 7047 that kind whose "default track" flag is set to "1". If no such track 7048 is found then the first track of this kind SHOULD be chosen. 7050 Only one track of a kind MAY have its "default track" flag set in a 7051 segment. If a track entry does not contain the "default track" flag 7052 element then its default value "1" is to be used. 7054 24.2. Forced flag 7056 The "forced" flag tells the "Matroska Player" that it MUST display/ 7057 play this track or another track of the same kind that also has its 7058 "forced" flag set. When there are multiple "forced" tracks, the 7059 "Matroska Player" SHOULD determine the track based upon the language 7060 of the forced flag or use the default flag if no track matches the 7061 use languages. Another track of the same kind without the "forced" 7062 flag may be use simultaneously with the "forced" track (like DVD 7063 subtitles for example). 7065 24.3. Track Operation 7067 "TrackOperation" allows combining multiple tracks to make a virtual 7068 one. It uses two separate system to combine tracks. One to create a 7069 3D "composition" (left/right/background planes) and one to simplify 7070 join two tracks together to make a single track. 7072 A track created with "TrackOperation" is a proper track with a UID 7073 and all its flags. However the codec ID is meaningless because each 7074 "sub" track needs to be decoded by its own decoder before the 7075 "operation" is applied. The "Cues Elements" corresponding to such a 7076 virtual track SHOULD be the sum of the "Cues Elements" for each of 7077 the tracks it's composed of (when the "Cues" are defined per track). 7079 In the case of "TrackJoinBlocks", the "Block Elements" (from 7080 "BlockGroup" and "SimpleBlock") of all the tracks SHOULD be used as 7081 if they were defined for this new virtual "Track". When two "Block 7082 Elements" have overlapping start or end timecodes, it's up to the 7083 underlying system to either drop some of these frames or render them 7084 the way they overlap. This situation SHOULD be avoided when creating 7085 such tracks as you can never be sure of the end result on different 7086 platforms. 7088 24.4. Overlay Track 7090 Overlay tracks SHOULD be rendered in the same 'channel' as the track 7091 its linked to. When content is found in such a track, it SHOULD be 7092 played on the rendering channel instead of the original track. 7094 24.5. Multi-planar and 3D videos 7096 There are two different ways to compress 3D videos: have each 'eye' 7097 track in a separate track and have one track have both 'eyes' 7098 combined inside (which is more efficient, compression-wise). 7099 Matroska supports both ways. 7101 For the single track variant, there is the "StereoMode Element" which 7102 defines how planes are assembled in the track (mono or left-right 7103 combined). Odd values of StereoMode means the left plane comes first 7104 for more convenient reading. The pixel count of the track 7105 ("PixelWidth"/"PixelHeight") is the raw amount of pixels (for example 7106 3840x1080 for full HD side by side) and the 7107 "DisplayWidth"/"DisplayHeight" in pixels is the amount of pixels for 7108 one plane (1920x1080 for that full HD stream). Old stereo 3D were 7109 displayed using anaglyph (cyan and red colours separated). For 7110 compatibility with such movies, there is a value of the StereoMode 7111 that corresponds to AnaGlyph. 7113 There is also a "packed" mode (values 13 and 14) which consists of 7114 packing two frames together in a "Block" using lacing. The first 7115 frame is the left eye and the other frame is the right eye (or vice 7116 versa). The frames SHOULD be decoded in that order and are possibly 7117 dependent on each other (P and B frames). 7119 For separate tracks, Matroska needs to define exactly which track 7120 does what. "TrackOperation" with "TrackCombinePlanes" do that. For 7121 more details look at Section 24.3. 7123 The 3D support is still in infancy and may evolve to support more 7124 features. 7126 The StereoMode used to be part of Matroska v2 but it didn't meet the 7127 requirement for multiple tracks. There was also a bug in libmatroska 7128 prior to 0.9.0 that would save/read it as 0x53B9 instead of 0x53B8. 7129 "Matroska Readers" may support these legacy files by checking 7130 Matroska v2 or 0x53B9. The older values [20] were 0: mono, 1: right 7131 eye, 2: left eye, 3: both eyes. 7133 25. Timecodes 7135 25.1. Timecode Types 7137 o Absolute Timecode = Block+Cluster 7139 o Relative Timecode = Block 7141 o Scaled Timecode = Block+Cluster 7143 o Raw Timecode = (Block+Cluster)*TimecodeScale*TrackTimecodeScale 7145 25.2. Block Timecodes 7147 The "Block Element"'s timecode MUST be a signed integer that 7148 represents the "Raw Timecode" relative to the "Cluster"'s "Timecode 7149 Element", multiplied by the "TimecodeScale Element". See 7150 Section 25.4 for more information. 7152 The "Block Element"'s timecode MUST be represented by a 16bit signed 7153 integer (sint16). The "Block"'s timecode has a range of -32768 to 7154 +32767 units. When using the default value of the "TimecodeScale 7155 Element", each integer represents 1ms. The maximum time span of 7156 "Block Elements" in a "Cluster" using the default "TimecodeScale 7157 Element" of 1ms is 65536ms. 7159 If a "Cluster"'s "Timecode Element" is set to zero, it is possible to 7160 have "Block Elements" with a negative "Raw Timecode". "Block 7161 Elements" with a negative "Raw Timecode" are not valid. 7163 25.3. Raw Timecode 7165 The exact time of an object SHOULD be represented in nanoseconds. To 7166 find out a "Block"'s "Raw Timecode", you need the "Block"'s "Timecode 7167 Element", the "Cluster"'s "Timecode Element", and the "TimecodeScale 7168 Element". 7170 25.4. TimecodeScale 7172 The "TimecodeScale Element" is used to calculate the "Raw Timecode" 7173 of a "Block". The timecode is obtained by adding the "Block"'s 7174 timecode to the "Cluster"'s "Timecode Element", and then multiplying 7175 that result by the "TimecodeScale". The result will be the "Block"'s 7176 "Raw Timecode" in nanoseconds. The formula for this would look like: 7178 (a + b) * c 7180 a = `Block`'s Timecode 7181 b = `Cluster`'s Timecode 7182 c = `TimeCodeScale` 7184 For example, assume a "Cluster"'s "Timecode" has a value of 564264, 7185 the "Block" has a "Timecode" of 1233, and the "TimecodeScale Element" 7186 is the default of 1000000. 7188 (1233 + 564264) * 1000000 = 565497000000 7190 So, the "Block" in this example has a specific time of 565497000000 7191 in nanoseconds. In milliseconds this would be 565497ms. 7193 25.5. TimecodeScale Rounding 7195 Because the default value of "TimecodeScale" is 1000000, which makes 7196 each integer in the "Cluster" and "Block" "Timecode Elements" equal 7197 1ms, this is the most commonly used. When dealing with audio, this 7198 causes inaccuracy when seeking. When the audio is combined with 7199 video, this is not an issue. For most cases, the the synch of audio 7200 to video does not need to be more than 1ms accurate. This becomes 7201 obvious when one considers that sound will take 2-3ms to travel a 7202 single meter, so distance from your speakers will have a greater 7203 effect on audio/visual synch than this. 7205 However, when dealing with audio-only files, seeking accuracy can 7206 become critical. For instance, when storing a whole CD in a single 7207 track, a user will want to be able to seek to the exact sample that a 7208 song begins at. If seeking a few sample ahead or behind, a 'crack' 7209 or 'pop' may result as a few odd samples are rendered. Also, when 7210 performing precise editing, it may be very useful to have the audio 7211 accuracy down to a single sample. 7213 When storing timecodes for an audio stream, the "TimecodeScale 7214 Element" SHOULD have an accuracy of at least that of the audio sample 7215 rate, otherwise there are rounding errors that prevent users from 7216 knowing the precise location of a sample. Here's how a program has 7217 to round each timecode in order to be able to recreate the sample 7218 number accurately. 7220 Let's assume that the application has an audio track with a sample 7221 rate of 44100. As written above the "TimecodeScale" MUST have at 7222 least the accuracy of the sample rate itself: 1000000000 / 44100 = 7223 22675.7369614512. This value MUST always be truncated. Otherwise 7224 the accuracy will not suffice. So in this example the application 7225 will use 22675 for the "TimecodeScale". The application could even 7226 use some lower value like 22674 which would allow it to be a little 7227 bit imprecise about the original timecodes. But more about that in a 7228 minute. 7230 Next the application wants to write sample number 52340 and 7231 calculates the timecode. This is easy. In order to calculate the 7232 "Raw Timecode" in ns all it has to do is calculate "Raw Timecode = 7233 round(1000000000 * sample_number / sample_rate)". Rounding at this 7234 stage is very important! The application might skip it if it choses 7235 a slightly smaller value for the "TimecodeScale" factor instead of 7236 the truncated one like shown above. Otherwise it has to round or the 7237 results won't be reversible. For our example we get "Raw Timecode = 7238 round(1000000000 * 52340 / 44100) = round(1186848072.56236) = 7239 1186848073". 7241 The next step is to calculate the "Absolute Timecode" - that is the 7242 timecode that will be stored in the Matroska file. Here the 7243 application has to divide the "Raw Timecode" from the previous 7244 paragraph by the "TimecodeScale" factor and round the result: 7245 "Absolute Timecode = round(Raw Timecode / TimecodeScale_factor)" 7246 which will result in the following for our example: "Absolute 7247 Timecode = round(1186848073 / 22675) = round(52341.7011245866) = 7248 52342". This number is the one the application has to write to the 7249 file. 7251 Now our file is complete, and we want to play it back with another 7252 application. Its task is to find out which sample the first 7253 application wrote into the file. So it starts reading the Matroska 7254 file and finds the "TimecodeScale" factor 22675 and the audio sample 7255 rate 44100. Later it finds a data block with the "Absolute Timecode" 7256 of 52342. But how does it get the sample number from these numbers? 7258 First it has to calculate the "Raw Timecode" of the block it has just 7259 read. Here's no rounding involved, just an integer multiplication: 7260 "Raw Timecode = Absolute Timecode * TimecodeScale_factor". In our 7261 example: "Raw Timecode = 52342 * 22675 = 1186854850". 7263 The conversion from the "Raw Timecode" to the sample number again 7264 requires rounding: "sample_number = round(Raw Timecode * sample_rate 7265 / 1000000000)". In our example: "sample_number = round(1186854850 * 7266 44100 / 1000000000) = round(52340.298885) = 52340". This is exactly 7267 the sample number that the previous program started with. 7269 Some general notes for a program: 7271 1. Always calculate the timestamps / sample numbers with floating 7272 point numbers of at least 64bit precision (called 'double' in 7273 most modern programming languages). If you're calculating with 7274 integers then make sure they're 64bit long, too. 7276 2. Always round if you divide. Always! If you don't you'll end up 7277 with situations in which you have a timecode in the Matroska file 7278 that does not correspond to the sample number that it started 7279 with. Using a slightly lower timecode scale factor can help here 7280 in that it removes the need for proper rounding in the conversion 7281 from sample number to "Raw Timecode". 7283 25.6. TrackTimecodeScale 7285 The "TrackTimecodeScale Element" is used align tracks that would 7286 otherwise be played at different speeds. An example of this would be 7287 if you have a film that was originally recorded at 24fps video. When 7288 playing this back through a PAL broadcasting system, it is standard 7289 to speed up the film to 25fps to match the 25fps display speed of the 7290 PAL broadcasting standard. However, when broadcasting the video 7291 through NTSC, it is typical to leave the film at its original speed. 7292 If you wanted to make a single file where there was one video stream, 7293 and an audio stream used from the PAL broadcast, as well as an audio 7294 stream used from the NTSC broadcast, you would have the problem that 7295 the PAL audio stream would be 1/24th faster than the NTSC audio 7296 stream, quickly leading to problems. It is possible to stretch out 7297 the PAL audio track and re-encode it at a slower speed, however when 7298 dealing with lossy audio codecs, this often results in a loss of 7299 audio quality and/or larger file sizes. 7301 This is the type of problem that "TrackTimecodeScale" was designed to 7302 fix. Using it, the video can be played back at a speed that will 7303 synch with either the NTSC or the PAL audio stream, depending on 7304 which is being used for playback. To continue the above example: 7306 Track 1: Video 7307 Track 2: NTSC Audio 7308 Track 3: PAL Audio 7310 Because the NTSC track is at the original speed, it will used as the 7311 default value of 1.0 for its "TrackTimecodeScale". The video will 7312 also be aligned to the NTSC track with the default value of 1.0. 7314 The "TrackTimecodeScale" value to use for the PAL track would be 7315 calculated by determining how much faster the PAL track is than the 7316 NTSC track. In this case, because we know the video for the NTSC 7317 audio is being played back at 24fps and the video for the PAL audio 7318 is being played back at 25fps, the calculation would be: 7320 25/24 ≈ 1.04166666666666666667 7321 When writing a file that uses a non-default "TrackTimecodeScale", the 7322 values of the "Block"'s timecode are whatever they would be when 7323 normally storing the track with a default value for the 7324 "TrackTimecodeScale". However, the data is interleaved a little 7325 differently. Data SHOULD be interleaved by its Section 25.3 in the 7326 order handed back from the encoder. The "Raw Timecode" of a "Block" 7327 from a track using "TrackTimecodeScale" is calculated using: 7329 "(Block's Timecode + Cluster's Timecode) * TimecodeScale * 7330 TrackTimecodeScale" 7332 So, a Block from the PAL track above that had a Section 25.1 of 100 7333 seconds would have a "Raw Timecode" of 104.66666667 seconds, and so 7334 would be stored in that part of the file. 7336 When playing back a track using the "TrackTimecodeScale", if the 7337 track is being played by itself, there is no need to scale it. From 7338 the above example, when playing the Video with the NTSC Audio, 7339 neither are scaled. However, when playing back the Video with the 7340 PAL Audio, the timecodes from the PAL Audio track are scaled using 7341 the "TrackTimecodeScale", resulting in the video playing back in 7342 synch with the audio. 7344 It would be possible for a "Matroska Player" to also adjust the 7345 audio's samplerate at the same time as adjusting the timecodes if you 7346 wanted to play the two audio streams synchronously. It would also be 7347 possible to adjust the video to match the audio's speed. However, 7348 for playback, the selected track(s) timecodes SHOULD be adjusted if 7349 they need to be scaled. 7351 While the above example deals specifically with audio tracks, this 7352 element can be used to align video, audio, subtitles, or any other 7353 type of track contained in a Matroska file. 7355 26. References 7357 26.1. URIs 7359 [1] http://mukoli.free.fr/mcf/mcf.html 7361 [2] https://github.com/Matroska-Org/ebml-specification/blob/master/ 7362 specification.markdown 7364 [3] https://datatracker.ietf.org/wg/cellar/charter/ 7366 [4] https://matroska.org/files/matroska.pdf 7368 [5] diagram.md 7370 [6] https://github.com/Matroska-Org/ebml-specification/blob/master/ 7371 specification.markdown 7373 [7] https://github.com/Matroska-Org/foundation- 7374 source/blob/master/spectool/specdata.xml 7376 [8] https://tools.ietf.org/html/rfc2119 7378 [9] https://github.com/Matroska-Org/ebml-specification/blob/master/ 7379 specification.markdown 7381 [10] https://github.com/Matroska-Org/ebml-specification/blob/master/ 7382 specification.markdown#ebml-element-types 7384 [11] https://github.com/Matroska-Org/ebml-specification/blob/master/ 7385 specification.markdown#ebml-schema 7387 [12] https://github.com/Matroska-Org/ebml-specification/blob/master/ 7388 specification.markdown#structure 7390 [13] https://www.loc.gov/standards/iso639-2/php/English_list.php 7392 [14] https://tools.ietf.org/html/bcp47 7394 [15] https://www.iana.org/domains/root/db 7396 [16] http://www.webmproject.org/docs/container/ 7398 [17] http://dvd.sourceforge.net/dvdinfo/uops.html 7400 [18] http://www.dvd-replica.com/DVD/ 7402 [19] http://dvd.sourceforge.net/dvdinfo/ 7404 [20] http://www.matroska.org/node/1/revisions/74/view#StereoMode 7406 Authors' Addresses 7408 Steve Lhomme 7410 Email: slhomme@matroska.org 7412 Moritz Bunkus 7414 Email: moritz@bunkus.org 7415 Dave Rice 7417 Email: dave@dericed.com