Creating and working with Matroska files
C++ Ruby C M4 HTML NSIS Other
Failed to load latest commit information.
.tx Transifex config: add man pages as resource Feb 3, 2016
ac configure: don't abort if moc/uic/rcc/qmake is found but too old May 9, 2017
debian-upstream Debian packaging: run test suite with LC_ALL=C Jun 16, 2017
doc identification: output stream_id & sub_stream_id as integers; drop ts… Jun 22, 2017
examples Relaxing requirements on ChapterDisplay to make it non-mandatory with… Jul 28, 2016
installer installer translations: update Polish Jun 20, 2017
lib libEBML: update to revision cd393f30cb12060f6b4e9666268122e1a346a491 Mar 10, 2017
po translations: update Turkish Jun 22, 2017
rake.d build system: run test suite with LC_ALL=C Jun 18, 2017
share GUIs: rename .desktop files to adhere to standards Apr 19, 2017
src GUI: mux: remember decision in add/append decision dialog Jun 24, 2017
tests tests: add case for c7422da Jun 24, 2017
tools version number bump script: fix updating the installer version number May 20, 2017
.gitignore hevcc_dump: new tool for dumping a HEVCC from the middle of a file (i… Mar 19, 2017
.gitmodules Source: switch libebml/libmatroska submodules to new URL step 2 Jan 10, 2013
AUTHORS MP4 reader: fixes for the COLR atom support Apr 22, 2017
COPYING Update the copy of GPLv2 to the latest version from the FSF Mar 5, 2012
ChangeLog re-add ChangeLog with a note to read instead Dec 29, 2016
INSTALL INSTALL: update name of file Sep 1, 2014 GUI: mux: remember decision in add/append decision dialog Jun 24, 2017 bump version number, set release code name May 20, 2017 bump version number, set release code name May 20, 2017
Rakefile Rakefile: fix syntax for older Ruby versions May 20, 2017 Fixed build instructions Aug 1, 2010 build system: try detecting pugixml via pkg-config with fallback Feb 13, 2017 bump version number, set release code name May 20, 2017
install-sh Add flags for setting the colour properties for a video track Jul 2, 2016
mkinstalldirs switched to auto* Feb 16, 2003
mkvtoolnix.spec bump version number, set release code name May 20, 2017

MKVToolNix 12.0.0

Table of contents

  1. Introduction
  2. Installation
  3. Requirements
  4. Optional components
  5. Building libEBML and libMatroska
  6. Building MKVToolNix
  7. Getting and building a development snapshot
  8. Configuration and compilation
  9. Notes for compilation on (Open)Solaris
  10. Unit tests
  11. Reporting bugs
  12. Test suite and continuous integration tests
  13. Included libraries and their licenses
  14. avilib
  15. Boost's utf8_codecvt_facet
  16. libEBML
  17. libMatroska
  18. librmff
  19. nlohmann's JSON
  20. pugixml
  21. utf8-cpp

1. Introduction

With these tools one can get information about (via mkvinfo) Matroska files, extract tracks/data from (via mkvextract) Matroska files and create (via mkvmerge) Matroska files from other media files. Matroska is a new multimedia file format aiming to become THE new container format for the future. You can find more information about it and its underlying technology, the Extensible Binary Meta Language (EBML), at

The full documentation for each command is now maintained in its man page only. Type mkvmerge -h to get you started.

This code comes under the GPL v2 (see or the file COPYING). Modify as needed.

The icons are based on the work of Alexandr Grigorcea and modified by Eduard Geier. They're licensed under the terms of the Creative Commons Attribution 3.0 Unported license.

The newest version can always be found at

Moritz Bunkus

2. Installation

If you want to compile the tools yourself, you must first decide if you want to use a 'proper' release version or the current development version. As both Matroska and MKVToolNix are under heavy development, there might be features available in the git repository that are not available in the releases. On the other hand the git repository version might not even compile.

2.1. Requirements

In order to compile MKVToolNix, you need a couple of libraries. Most of them should be available pre-compiled for your distribution. The programs and libraries you absolutely need are:

  • A C++ compiler that supports several features of the C++11 and C++14 standards: initializer lists, range-based for loops, right angle brackets, the auto keyword, lambda functions, the nullptr keyword, tuples, alias declarations, std::make_unique(), digit separators, binary literals and generic lambdas. Others may be needed, too. For GCC this means at least v4.9.x; for clang v3.4 or later.

  • libEBML v1.3.4 or later and libMatroska v1.4.5 or later for low-level access to Matroska files. Instructions on how to compile them are a bit further down in this file.

  • libOgg and libVorbis for access to Ogg/OGM files and Vorbis support

  • zlib — a compression library

  • Boost — Several of Boost's libraries are used: format, RegEx, filesystem, system, math, Range, rational, variant. At least v1.46.0 is required.

  • libxslt's xsltproc binary and DocBook XSL stylesheets — for creating man pages from XML documents

You also need the rake or drake build program. I suggest rake v10.0.0 or newer (this is included with Ruby 2.1) as it offers parallel builds out of the box. If you only have an earlier version of rake, you can install and use the drake gem for the same gain.

2.2. Optional components

Other libraries are optional and only limit the features that are built. These include:

  • Qt v5.3 or newer — a cross-platform GUI toolkit. You need this if you want to use the MKVToolNix GUI or mkvinfo's GUI.

  • libFLAC for FLAC support (Free Lossless Audio Codec)

  • lzo and bzip2 are compression libraries. These are the least important libraries as almost no application supports Matroska content that is compressed with either of these libs. The aforementioned zlib is what every program supports.

  • libMagic from the "file" package for automatic content type detection

  • po4a for building the translated man pages

2.3. Building libEBML and libMatroska

This is optional as MKVToolNix comes with its own set of the libraries. It will use them if no version is found on the system.

Start with the two libraries. Either download releases of libEBML 1.3.4 and libMatroska 1.4.5 or get a fresh copy from the git repository:

git clone
git clone

First change to libEBML's directory and run ./configure followed by make. Now install libEBML by running make install as root (e.g. via sudo). Change to libMatroska's directory and go through the same steps: first ./configure followed by make as a normal user and lastly make install as root.

2.4. Building MKVToolNix

Either download the current release from the MKVToolNix home page and unpack it or get a development snapshot from my Git repository.

2.4.1. Getting and building a development snapshot

You can ignore this subsection if you want to build from a release tarball.

All you need for Git repository access is to download a Git client from the Git homepage at There are clients for both Unix/Linux and Windows.

First clone my Git repository with this command:

git clone

Now change to the MKVToolNix directory with cd mkvtoolnix and run ./ which will generate the "configure" script. You need the GNU "autoconf" utility for this step.

2.4.2. Configuration and compilation

If you have run make install for both libraries, then configure should automatically find the libraries' position. Otherwise you need to tell configure where the libEBML and libMatroska include and library files are:

./configure \
  --with-extra-includes=/where/i/put/libebml\;/where/i/put/libmatroska \

Now run rake and, as "root", rake install.

2.5. Notes for compilation on (Open)Solaris

You can compile MKVToolNix with Sun's sunstudio compiler, but you need additional options for configure:

./configure --prefix=/usr \
  CXX="/opt/sunstudio12.1/bin/CC -library=stlport4" \
  --with-extra-includes=/where/i/put/libebml\;/where/i/put/libmatroska \

2.6. Unit tests

Building and running unit tests is completely optional. If you want to do this, you have to follow these steps:

  1. Download the "googletest" framework from (at the time of writing the file to download was "googletest-release-1.8.0.tar.gz")

  2. Extract the archive somewhere and create a symbolic link to its googletest-release-1.8.0/googletest/include/gtest sub-directory inside MKVToolNix' "lib" directory.

  3. Configure MKVToolNix normally.

  4. Build the unit test executable and run it with

     rake tests:unit

3. Reporting bugs

If you're sure you've found a bug — e.g. if one of my programs crashes with an obscur error message, or if the resulting file is missing part of the original data, then by all means submit a bug report.

I use GitHub's issue system as my bug database. You can submit your bug reports there. Please be as verbose as possible — e.g. include the command line, if you use Windows or Linux etc.pp.

If at all possible, please include sample files as well so that I can reproduce the issue. If they are larger than 1 MB, please upload them somewhere and post a link in the issue. You can also upload them to my FTP server. Details on how to connect can be found in the MKVToolNix FAQ.

4. Test suite and continuous integration tests

MKVToolNix contains a lot of test cases in order to detect regressions before they're released. Regressions include both compilation issues as well as changes from expected program behavior.

As mentioned in section 2.6., MKVToolNix comes with a set of unit tests based on the Google Test library in the tests/unit sub-directory that you can run yourself. These cover only a small amount of code, and any effort to extend them would be most welcome.

A second test suite exists that targets the program behavior, e.g. the output generated by mkvmerge when specific options are used with specific input files. These are the test cases in the tests directory itself. Unfortunately the files they run on often contain copyrighted material that I cannot distribute. Therefore you cannot run them yourself.

A third pillar of the testing effort is the continuous integration tests run on a Buildbot instance. These are run automatically for each commit made to the git repository. The tests include:

  • building of all the packages for Linux distributions that I normally provide for download myself in both 32-bit and 64-bit variants
  • building of the Windows installer and portable packages in both 32-bit and 64-bit variants
  • building with both g++ and clang++
  • building and running the unit tests
  • building and running the test file test suite
  • building with all optional features disabled

5. Included third-party components and their licenses

MKVToolNix includes and uses the following libraries & artwork:

5.1. avilib

Reading and writing avi files.

Copyright (C) 1999 Rainer Johanni, originally part of the transcode package.

5.2. Boost's utf8_codecvt_facet

A class, utf8_codecvt_facet, derived from std::codecvt<wchar_t, char>, which can be used to convert utf8 data in files into wchar_t strings in the application.

  • License: Boost Software License - Version 1.0 (see doc/licenses/Boost-1.0.txt)
  • URL:

5.3. libEBML

A C++ library to parse EBML files

5.4. libMatroska

A C++ library to parse Matroska files

5.5. librmff

librmff is short for 'RealMedia file format access library'. It aims at providing the programmer an easy way to read and write RealMedia files.

5.6. nlohmann's JSON

JSON for Modern C++

5.7. pugixml

An XML processing library

5.8. utf8-cpp

UTF-8 with C++ in a Portable Way

5.9. Oxygen icons and sound files

Most of the icons included in this package originate from the Oxygen Project. These include all files in the share/icons sub-directory safe for those whose name starts with mkv.

The preferred form of modification are the SVG icons. These are not part of the binary distribution of MKVToolNix, but they are contained in the source code in the icons/scalable sub-directory. You can obtain the source code from the MKVToolNix website.

All of the sound files in the share/sounds sub-directory originate from the Oxygen project.