MKV and WebM won't play: EBML, Clusters, and the Cues index

One format wearing two names

MKV and WebM are, underneath, the same thing. Matroska(the .mkv file) is a flexible container that can hold almost any codec, several audio tracks, subtitles, and chapters. WebMis a deliberately narrowed subset of it, restricted to a handful of web-friendly codecs — VP8, VP9, or AV1 for video, Vorbis or Opus for audio — so browsers can support it cleanly. Both are built on exactly the same byte-level system, which means when one won't play, the same anatomy explains why, and the same repair applies.

That anatomy is worth knowing because Matroska fails differently than the MP4 family. Where an MP4 leans on a single index block, Matroska leans on a chain of self-describing pieces, and that changes what survives a bad download or an interrupted record.

How EBML is built: elements all the way down

Matroska is written in EBML, the Extensible Binary Meta Language. Think of it as a binary cousin of XML: everything in the file is an element, and every element is the same three things in a row — an ID that says what it is, a length that says how many bytes it spans, and the content, which can itself be more elements nested inside. Both the ID and the length use a variable-width encoding, so small values take few bytes and large ones take more.

At the top sits a short EBML header that identifies the file as Matroska or WebM. Everything else lives inside one bigSegment element, and within it a handful of top-level children carry the whole file: Info (timescale and duration),Tracks (the codec and shape of each stream), Cues(the seek index), and a run of Cluster elements (the actual media). A small SeekHead near the front acts as a directory, recording where each of those top-level elements begins.

A Matroska file: a small header and track declarations, the long run of Clusters that holds the media, and a Cues index — often written at the end — for seeking.

The crucial detail is that the length prefix on every element is what lets a player skip from one to the next. If a length field is corrupted, a player loses its place in the file, because it no longer knows where the current element ends and the next begins.

Clusters carry the media; Cues only helps you seek

The media itself lives in Clusters. Each Cluster starts with a timestamp and then holds a short run of blocks — the encoded frames for that slice of the timeline. Clusters are written in order as recording or muxing proceeds, and each one is self-timed: it knows where it sits on the clock without consulting anything else. This is the heart of why Matroska is resilient. A player can begin at the first Cluster and walk forward, decoding each in turn, using nothing but the track declarations up front.

The Cues block is a separate convenience. It maps timestamps to the byte offsets of Clusters so a player can jump straight to a keyframe when you drag the scrubber, instead of reading from the start. Cues is frequently written last, once all the Cluster positions are known — which is precisely the block most likely to be missing when a file is cut short. Losing it costs you accurate seeking, not the video.

Compare that with an MP4, where the single moov index is needed even to begin playback, and the contrast is clear: an MP4 without its index plays nowhere, while an MKV without its Cues usually plays fine from the top and only stumbles when you try to seek. The two containers' opposite behavior under the same interruption is the practical payoff of knowing their internals, an extension of thecodec-versus-container distinction.

How MKV and WebM actually break

Most real damage falls into a few recognizable shapes, and matching yours tells you the prognosis before you spend any effort.

• Truncated tail. A download stopped early or a record cut off leaves a run of complete Clusters and then nothing — the Cues, duration, and any finalizing elements never arrived. This is the common case, and it recovers well: the media up to the cut is intact.
• Broken Cues or SeekHead. The index that supports seeking is damaged while the Clusters are fine. Playback from the start works; jumping around fails or lands wrong. Rebuilding the index fixes it completely.
• A corrupt element length. A mangled length prefix on a top-level element derails the parser, because it can no longer find the boundary between elements. A repair re-derives the boundaries by scanning for the known element IDs.
• Damage inside a Cluster. Bad sectors landing in a Cluster corrupt the frames stored there, showing as a glitch over that stretch. Clusters before and after decode normally; the damaged frames can't be regenerated.

What repair does with a Matroska file

Repairing an MKV or WebM is a structural rebuild around the media that survived, never a re-encode. A tool reads the EBML header andTracks to learn the codecs and stream shapes, then scans the body for Cluster elements by their IDs rather than trusting the possibly damaged length fields and SeekHead. Every Cluster that parses cleanly is kept in timeline order. From those surviving Clusters it recomputes the duration, rebuilds a correct Cues index andSeekHead, repairs the top-level size fields, and writes a valid file that players accept and can seek through again.

The honest ceiling is the same as for any container. Frames that were never written — the footage past a truncation — cannot be restored, and frames physically damaged inside a Cluster can't be regenerated, only skipped around. What repair reliably returns is every Cluster that decoded, wrapped in a clean structure. For the same job on the MP4 side, seefragmented MP4 andMP4 anatomy.