Creating and working with Matroska files
Go to file
2015-01-01 11:36:39 +01:00
ac build system: check for checked-out copies of libEBML/libMatroska 2014-12-21 11:19:06 +01:00
debian-upstream deactivate verbose mode by default 2014-12-12 21:02:10 +01:00
doc man page translations: re-build Ukrainian 2014-12-28 17:04:10 +01:00
examples Update DTD files and ChangeLog 2012-03-29 12:58:18 +02:00
installer Bump version number, set release code name, add release message 2014-12-12 10:55:25 +01:00
lib update libebml/libmatroska to the latest official commits 2014-12-21 11:42:51 +01:00
po Translations: update Polish 2014-12-30 12:19:28 +01:00
rake.d build system: use libEBML/libMatroska via pkg-config 2014-12-21 10:50:26 +01:00
share GUI: add several icons to resources 2014-08-31 15:37:40 +02:00
src MP4 reader: implement support for DASH 2015-01-01 11:36:39 +01:00
tests MP4 reader: implement support for DASH 2015-01-01 11:36:39 +01:00
winbuild All: remove support for BZ2 and LZO compression 2013-03-03 21:04:19 +01:00
.gitignore gitignore: add .doconf* files 2014-09-13 11:28:29 +02:00
.gitmodules Source: switch libebml/libmatroska submodules to new URL step 2 2013-01-10 22:39:23 +01:00
AUTHORS AUTHORS, ChangeLog: use real name instead of alias 2014-11-23 19:07:19 +01:00
autogen.sh Fixed build instructions 2010-08-01 11:12:45 +02:00
build-config.in build system: use libEBML/libMatroska via pkg-config 2014-12-21 10:50:26 +01:00
ChangeLog MP4 reader: implement support for DASH 2015-01-01 11:36:39 +01:00
configure.in build system: use libEBML/libMatroska via pkg-config 2014-12-21 10:50:26 +01:00
COPYING Update the copy of GPLv2 to the latest version from the FSF 2012-03-05 16:28:56 +01:00
drake Upgrade included drake to 0.9.2.0.3.1 2012-04-16 22:13:03 +02:00
INSTALL INSTALL: update name of README.md file 2014-09-01 14:58:12 +02:00
install-sh Removed whitespaces at the end of the line. 2003-05-20 06:30:25 +00:00
mkinstalldirs switched to auto* 2003-02-16 12:09:37 +00:00
mkvtoolnix.spec Bump version number, set release code name, add release message 2014-12-12 10:55:25 +01:00
NEWS Directory reorganization 2003-07-09 18:53:25 +00:00
Rakefile build system: use libEBML/libMatroska via pkg-config 2014-12-21 10:50:26 +01:00
README.md build system: require libMatroska v1.4.2 2014-12-19 14:03:11 +01:00
README.Windows.txt Bump version number, set release code name, add release message 2014-12-12 10:55:25 +01:00
TODO Change Bugzilla links to Trac links 2012-03-09 18:07:49 +01:00

MKVToolNix 7.4.0

Table of contents

  1. Introduction

  2. Installation

  3. Requirements

  4. Optional components

  5. Building libmatroska and libebml

  6. Building MKVtoolNix

  7. Notes for compilation on (Open)Solaris

  8. Unit tests

  9. Examples

  10. Reporting bugs

  11. Introduction


With these tools one can get information about (mkvinfo) Matroska files, extract tracks/data from (mkvextract) Matroska files and create (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

http://www.matroska.org/

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 www.gnu.org 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 (see http://creativecommons.org/licenses/by/3.0/).

The newest version can always be found at http://www.bunkus.org/videotools/mkvtoolnix/

Moritz Bunkus moritz@bunkus.org

  1. Installation

If you want to compile the tools yourself then 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 standard: initializer lists, range-based 'for' loops, right angle brackets, the 'auto' keyword and lambda functions. For GCC this means at least v4.6.0.

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

  • libOgg ( http://downloads.xiph.org/releases/ogg/ ) and libVorbis ( http://downloads.xiph.org/releases/vorbis/ ) for access to Ogg/OGM files and Vorbis support

  • zlib ( http://www.zlib.net/ ) -- a compression library

  • Boost ( http://www.boost.org/ ) -- Several of Boost's libraries are used: "format", "RegEx", "filesystem", "system", "foreach", "Range", "rational", "variant". At least v1.46.0 is required.

You also need the rake or drake build program or at least the programming language Ruby and the "rubygems" package. MKVToolNix comes bundled with its own copy of "drake" in case you cannot install it yourself. If you want to install it yourself I suggest you use the "drake" version because it will be able to use all available CPU cores for parallel builds.

Installing "drake" is simple. As root run the following command:

gem install drake

2.2. Optional components

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

2.3. Building libmatroska and libebml

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 get libebml 1.3.1 from http://dl.matroska.org/downloads/libebml/ and libmatroska 1.4.2 from http://dl.matroska.org/downloads/libmatroska/ or a fresh copy from the git repository:

git clone https://github.com/Matroska-Org/libebml.git
git clone https://github.com/Matroska-Org/libmatroska.git

Change to "libebml/make/linux" and run make staticlib. If you have root-access then run make install_headers install_staticlib as "root" in order to install the files. Change to "libmatroska/make/linux". Once more run make staticlib. If you have root-access then run make install_headers install_staticlib as "root" in order to install the files.

Note that if you don't want the libraries to be installed in /usr/local/lib and the headers in /usr/local/include then you can alter the prefix (which defaults to /usr/local) by adding an argument prefix=/usr to the install make command. Example:

make prefix=/usr install_headers install_staticlib

2.4. Building MKVtoolNix

Either download the current release from http://www.bunkus.org/videotools/mkvtoolnix/ and unpack it or get a development snapshot from my Git repository.

  • Getting and building a development snapshot (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 http://git-scm.com/ . There are clients for both Unix/Linux and Windows.

    First clone my Git repository with this command:

    git clone https://github.com/mbunkus/mkvtoolnix.git
    

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

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 \
  --with-extra-libs=/where/i/put/libebml/make/linux\;/where/i/put/libmatroska/make/linux

Now run rake and, as "root", rake install. If you don't have "rake" installed yourself then use the version bundled with MKVToolNix: ./rake.d/bin/drake and ./rake.d/bin/drake install.

If you want to use all available CPU cores for building then you have to use drake instead of rake. drake knows the parameter -j much like make does. You can also set the environment variable DRAKETHREADS to a number and the build process will automatically use that number of threads for a parallel build:

./drake -j4

or

export DRAKETHREADS=4
./drake

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" \
  CXXFLAGS="-D_POSIX_PTHREAD_SEMANTICS" \
  --with-extra-includes=/where/i/put/libebml\;/where/i/put/libmatroska \
  --with-extra-libs=/where/i/put/libebml/make/linux\;/where/i/put/libmatroska/make/linux

2.6. Unit tests

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

  1. Download the "googletest" framework from http://code.google.com/p/googletest/ (at the time of writing the file to download was "gtest-1.6.0.zip")

  2. Make gtest usable:

  3. Either extract the framework inside the "lib" sub-folder and rename the resulting folder "gtest-1.6.0" to "gtest"

    OR...

  4. Extract the archive somewhere and create a symbolic link to it inside the "lib" folder called or create a symbolic link called "gtest".

  5. Configure MKVToolNix normally.

  6. Build the unit test executable and run it with

     ./drake tests:unit
    
  7. Examples


Here's a very brief example of how you could use mkvmerge with mencoder in order to rip a DVD:

  1. Extract the audio to PCM audio:

     mplayer -ao pcm:file=audio.wav -vo null -vc dummy dvd://1
    
  2. Normalize the sound (optional)

     normalize audio.wav
    
  3. Encode the audio to Vorbis:

     oggenc -q3 -oaudio-q3.ogg audio.wav
    
  4. Somehow calculate the bitrate for your video. Use something like:

video_size = (target_size - audio-size) / 1.005
video_bitrate = video_size / length / 1024 * 8
  • target_size, audio_size in bytes
  • length in seconds
  • 1.005 is the overhead caused by putting the streams into an Matroska file (about 0.5%, that's correct ;)).
  • video_bitrate will be in kbit/s
  1. Use the two-pass encoding for the video:

     mencoder -oac copy -ovc lavc \
       -lavcopts vcodec=mpeg4:vbitrate=1000:vhq:vqmin=2:vpass=1 \
       -vf scale=....,crop=..... \
       -o /dev/null dvd://1
    
     mencoder -oac copy -ovc lavc \
       -lavcopts vcodec=mpeg4:vbitrate=1000:vhq:vqmin=2:vpass=2 \
       -vf scale=....,crop=..... \
       -o movie.avi dvd://1
    
  2. Merge:

     mkvmerge -o movie.mkv -A movie.avi audio-q3.ogg
    

-A is necessary in order to avoid copying the raw PCM (or MP3) audio as well.

  1. 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 Trac (https://trac.bunkus.org/) 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 1M then please upload them somewhere (e.g. to my FTP server: host name ftp.bunkus.org, user name upload, password only) and post a link or note in the bug report.