# Matroska (MKV/MKA)

Canonical URL: https://encode.wiki/containers/matroska/
Content version: ca42e61ede0a24f789d7287a0001244ad22f4abf
Status: current
License: CC BY-SA 4.0
Checksum (SHA-256): d1042443d1f64f0f9f0fa5a9723c6f1e3a354248700bc2550ffbb75d9d4465e9

Matroska is an open, EBML-based container (standardised as [RFC 9559](https://datatracker.ietf.org/doc/rfc9559/)) that can hold nearly any codec. `.mkv` is video with audio, `.mka` is audio only, `.mks` is subtitles only. [WebM](/containers/webm/) is a restricted Matroska profile.

It is the default choice for archives, releases and anything you are still going to edit, because it can carry what other containers cannot:

- any video and audio codec, including ones MP4 does not define (TrueHD, DTS-HD, PCM variants, FFV1, VP8/VP9/AV1 side by side with H.264)
- any number of video, audio and subtitle tracks, each with language, name, and default/forced flags
- ASS/SSA, SRT and WebVTT text subtitles, and PGS and VobSub image subtitles, unmodified
- **attachments**, mainly the fonts an ASS subtitle needs, plus cover art
- chapters (including named editions and ordered chapters) and tags
- HDR signalling: colour primaries, transfer, matrix, range, mastering display metadata, MaxCLL/MaxFALL
- recovery from truncation: a partly written file stays playable up to where it stopped

The cost is compatibility. Apple software does not play MKV, browser support is partial, and phones and TVs vary, so make an [MP4](/containers/mp4/) for sharing.

**Codecs documented for Matroska on this wiki**

| Relationship | Project or format | Evidence and scope | Status |
| --- | --- | --- | --- |
| Carried By by | [AV1](/codecs/video/av1/) | Uses the V_AV1 Codec ID and an AV1CodecConfigurationRecord in CodecPrivate. Scope: Container Mapping. Sources: [Matroska codec mappings](https://www.matroska.org/technical/codec_specs.html). | Normative |
| Carried By by | [Opus](/codecs/audio/opus/) | Uses the A_OPUS Codec ID and stores the Opus identification header in CodecPrivate. Scope: Container Mapping. Sources: [Matroska codec mappings](https://www.matroska.org/technical/codec_specs.html). | Normative |
| Carried By by | [AVC / H.264](/codecs/video/avc/) | The Matroska mapping uses V_MPEG4/ISO/AVC and an AVCDecoderConfigurationRecord. Scope: Container Mapping. Sources: [Matroska codec mappings](https://www.matroska.org/technical/codec_specs.html). | Documented |
| Carried By by | [HEVC / H.265](/codecs/video/hevc/) | The Matroska mapping uses V_MPEGH/ISO/HEVC and an HEVCDecoderConfigurationRecord. Scope: Container Mapping. Sources: [Matroska codec mappings](https://www.matroska.org/technical/codec_specs.html). | Documented |
| Carried By by | [VP9](/codecs/video/vp9/) | The Matroska mapping uses the V_VP9 Codec ID. Scope: Container Mapping. Sources: [Matroska codec mappings](https://www.matroska.org/technical/codec_specs.html). | Documented |
| Carried By by | [VVC / H.266](/codecs/video/vvc/) | The Matroska mapping uses V_MPEGI/ISO/VVC and a VVC decoder configuration record. Scope: Container Mapping. Sources: [Matroska codec mappings](https://www.matroska.org/technical/codec_specs.html). | Documented |
| Operates On by | [MKVToolNix](/tools/utilities/mkvtoolnix/) | MKVToolNix creates, inspects, extracts, and edits Matroska and WebM files. Scope: Muxing Inspection Metadata. Sources: [MKVToolNix command manuals (locally exercised with102.0)](https://mkvtoolnix.download/doc/mkvmerge.html), [RFC 9559: Matroska Media Container Format Specification](https://datatracker.ietf.org/doc/rfc9559/). | Documented |

[Open the complete typed relationship catalog](/api/v1/catalog.json).

## Remux with FFmpeg

```sh
ffmpeg -i input.mp4 -map 0 -c copy output.mkv
```

`-map 0` keeps every stream; without it FFmpeg takes one video, one audio and one subtitle. Matroska accepts nearly everything, so remuxing into it rarely fails. To add an SRT or ASS subtitle as a new track:

```sh
ffmpeg -i video.mkv -i subs.srt -map 0 -map 1 -c copy output.mkv
```

To attach a font for ASS subtitles, give it a MIME type; FFmpeg refuses to write an attachment without one:

```sh
ffmpeg -i input.mkv -map 0 -c copy -attach font.ttf -metadata:s:t mimetype=font/ttf output.mkv
```

## Mux and edit with MKVToolNix

[MKVToolNix](/tools/utilities/mkvtoolnix/) (`mkvmerge`, `mkvpropedit`, `mkvextract`, and the `mkvtoolnix-gui` front end) understands Matroska natively and is the tool to use when track flags, languages, chapters, or timestamps matter.

```sh
mkvmerge -o output.mkv input.mp4 subs.srt
mkvmerge -o output.mkv --language 1:jpn --track-name 1:"Commentary" --default-track-flag 1:0 input.mp4
mkvmerge -o output.mkv --attach-file font.ttf --chapters chapters.txt input.mkv
mkvmerge -o part%02d.mkv --split duration:00:20:00 input.mkv
```

`--language`, `--track-name` and other per-track options take `TID:value`, where `TID` is the track ID within the **next input file** as listed by `mkvmerge --identify file`. Use `-A`, `-S`, `-d 0 -a 1` and similar to leave tracks out. `mkvmerge -J file.mkv` prints the same information as JSON.

For changes that do not need re-muxing, `mkvpropedit` edits the file in place in seconds:

```sh
mkvpropedit input.mkv --edit track:a1 --set language=jpn --set flag-default=1
mkvpropedit input.mkv --chapters chapters.txt
mkvpropedit input.mkv --add-attachment font.ttf
```

Extract with `mkvextract input.mkv tracks 2:subs.srt`, `mkvextract input.mkv attachments 1`, or `mkvextract input.mkv chapters chapters.xml`. Track IDs here are the ones `mkvmerge --identify` prints.

## Pitfalls

- **ASS subtitles need their fonts.** If the fonts are not attached, players fall back to whatever is installed and typesetting breaks. See [SubStation Alpha](/codecs/subtitles/ssa/).
- **Track order and default flags decide what plays.** A player picks the track flagged default, or the first one, so set flags with `mkvpropedit` instead of reordering streams.
- **MKV → MP4 loses things.** Fonts, ASS/PGS subtitles and chapter detail do not survive; see [MP4](/containers/mp4/) for what MP4 can hold.