A Cluster holds a timestamp and the encoded frames. Elements marked deprecated are listed as such in RFC 9559 Appendix A.
Cluster elements
| ID | Element | Type | Meaning |
|---|---|---|---|
1F43B675 | Cluster | Master | Holds Block structures. |
E7 | Timestamp | Unsigned | Absolute Cluster time in Segment ticks. |
5854 | SilentTracks | Master | Tracks not used in this part of the stream. Deprecated. |
58D7 | SilentTrackNumber | Unsigned | A track number unused from this point. Deprecated. |
A7 | Position | Unsigned | Segment position of the Cluster; 0 for live. |
AB | PrevSize | Unsigned | Size of the previous Cluster. |
A3 | SimpleBlock | Binary | A Block with minimal overhead. |
AF | EncryptedBlock | Binary | Encrypted or signed block data. Deprecated. |
A0 | BlockGroup | Master | A Block and its extra information. |
A1 | Block | Binary | Frame data with a time relative to the Cluster. |
A2 | BlockVirtual | Binary | A Block with no data, in display order. Deprecated. |
75A1 | BlockAdditions | Master | Additional binary data for the Block. |
A6 | BlockMore | Master | Additional data and its parameters. |
A5 | BlockAdditional | Binary | Interpreted according to BlockAddID. |
EE | BlockAddID | Unsigned | How to interpret BlockAdditional; 1 is codec-defined. |
9B | BlockDuration | Unsigned | Duration of the Block in track ticks. |
FA | ReferencePriority | Unsigned | Cache priority; 0 means not referenced. |
FB | ReferenceBlock | Signed | Relative time of a Block this one depends on. |
FD | ReferenceVirtual | Signed | Segment position of data for a virtual Block. Deprecated. |
A4 | CodecState | Binary | A new codec state, private to the codec. |
75A2 | DiscardPadding | Signed | Silent padding in nanoseconds; positive at the end, negative at the start. |
8E | Slices | Master | Slice timing. Deprecated. |
E8 | TimeSlice | Master | Extra timing for the Block’s data. Deprecated. |
CC | LaceNumber | Unsigned | Reverse frame number within the lace. Deprecated. |
CD | FrameNumber | Unsigned | Frame to generate from the lace. Deprecated. |
CB | BlockAdditionID | Unsigned | BlockAdditional ID; 0 is the main Block. Deprecated. |
CE | Delay | Unsigned | Delay in track ticks. Deprecated. |
CF | SliceDuration | Unsigned | Duration in track ticks. Deprecated. |
C8 | ReferenceFrame | Master | Last reference frame, for a DivX trick track. Deprecated. |
C9 | ReferenceOffset | Unsigned | Byte offset from the previous BlockGroup. Deprecated. |
CA | ReferenceTimestamp | Unsigned | Time of the referenced BlockGroup. Deprecated. |
Block and SimpleBlock header
| Offset | Size | Type | Name | Meaning |
|---|---|---|---|---|
| 0 | 1 or more | VINT | Track number | The track’s number, as a VINT. |
| +0 | 2 | int16 | Timestamp | In track ticks, relative to the Cluster’s timestamp, big-endian: −32768 to 32767. |
| +2 | 1 | bits | Flags | See below. |
| +3 | Lace data or frame | The frame, or the lace. |
| Bit (mask) | In SimpleBlock | In Block |
|---|---|---|
0 (80) | Key frame | Reserved |
1 to 3 (70) | Reserved | Reserved |
4 (08) | Invisible in the older Matroska notes; the bit RFC 9559’s Block figure labels Gap. | |
5, 6 (06) | Lacing: 00 none, 01 Xiph, 10 fixed-size, 11 EBML. | |
7 (01) | Discardable | Reserved |
Unconfirmed: bits other than lacing and the key frame bit come from memory of the Matroska notes, because the RFC’s Block figure was not fully readable.
Lacing
Lacing packs several small frames into one Block. After the header comes one byte holding
the number of frames minus 1, then the sizes of all frames but the last, then the frames.
The last frame’s size is what remains of the Block. Tracks with
FlagLacing 0 must use no lacing, and a single frame must not be laced.
| Lacing | Sizes |
|---|---|
| Xiph | Each size as bytes of 255 ended by a byte under 255, as in Ogg. A size that is a multiple of 255 ends with a 0 byte. 500 is FF F5; 765 is FF FF FF 00. |
| EBML | The first size is a VINT. Each later size is a signed difference from the previous size, stored as a VINT from which 27n−1 − 1 is subtracted, n being its length in bytes. |
| Fixed-size | No sizes are stored; every frame has the same size, the data divided by the frame count. |
The example from RFC 9559, frames of 800, 500 and 1000 bytes. Xiph lacing stores
02, FF FF FF 23 (800), FF F5 (500), then the data.
EBML lacing stores 02, 43 20 (800), 5E D3 (−300,
because 1ED3 is 7891 and 213 − 1 is 8191).
Timestamps
A frame’s time in nanoseconds is:
(Cluster Timestamp + Block timestamp × TrackTimestampScale) × TimestampScale
If the track has a CodecDelay, subtract it. Frames that end up with negative
times are decoded but not played. In a lace, the Block’s timestamp is that of the first
frame, and the other frames follow with no gaps.