18 KiB
MKVToolNix 53.0.0
Table of contents
- Introduction
- Installation
- Reporting bugs
- Test suite and continuous integration tests
- Code of Conduct
- Included third-party components and their licenses
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 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.
The newest version can always be found at https://mkvtoolnix.download/
Moritz Bunkus moritz@bunkus.org
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
2.1.1. Hard 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, C++14 and C++17 standards: initializer lists, range-based
for
loops, right angle brackets, theauto
keyword, lambda functions, thenullptr
keyword, tuples, alias declarations,std::make_unique()
, digit separators, binary literals, generic lambdas, user-defined literals forstd::string
,[[maybe_unused]]
attribute, nested namespace definition, structured bindings,std::optional
,std::regex
. Others may be needed, too. For GCC this means at least v7; for clang v4 or later. -
libOgg and libVorbis for access to Ogg/OGM files and Vorbis support
-
zlib — a compression library
-
Boost — Several of Boost's libraries are used:
filesystem
,system
,math
,operators
,rational
. At least v1.60.0 is required. -
libxslt's xsltproc binary and DocBook XSL stylesheets — for creating man pages from XML documents
-
PCRE2 — the Perl-compatible regular expression library
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.1.2. Requirements with bundled fallbacks
Several required libraries might not be available for your
distribution. Therefore they're bundled with the MKVToolNix source
code. The configure
script will look for those libraries and use
existing versions if present. If not, the bundled versions are used
instead.
It is highly recommended to install the versions provided by your distribution instead of relying on the bundled versions.
These libraries are:
-
fmt — a small, safe and fast formatting library. Version 3 or later is required.
-
JPCRE2 — C++ wrapper for the PCRE2 library. Version 10.32.1 or newer is required.
-
libEBML v1.4.1 or later and libMatroska v1.6.1 or later for low-level access to Matroska files. Instructions on how to compile them are a bit further down in this file.
-
librmff — a library for accessing RealMedia files
-
nlohmann's JSON — JSON for Modern C++
-
pugixml — light-weight, simple and fast XML parser for C++ with XPath support
-
utf8-cpp — UTF-8 with C++ in a Portable Way
2.2. Optional components
Other libraries are optional and only limit the features that are built. These include:
-
Qt v5.9.0 or newer — a cross-platform GUI toolkit. You need this if you want to use the MKVToolNix GUI.
-
cmark — the CommonMark parsing and rendering library in C is required when building the Qt GUIs.
-
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 by either downloading releases of libEBML v1.4.1 and libMatroska v1.6.1 or by getting fresh copies from their git repositories:
git clone https://github.com/Matroska-Org/libebml.git
git clone https://github.com/Matroska-Org/libmatroska.git
First build and install libEBML according to the included instructions. Afterwards do the same for libMatroska.
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 http://git-scm.com/. There are clients for both Unix/Linux and Windows.
First clone my Git repository with this command:
git clone https://gitlab.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.
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 \
--with-extra-libs=/where/i/put/libebml/make/linux\;/where/i/put/libmatroska/make/linux
Now run rake
and, as "root", rake install
.
2.4.3. If things go wrong
By default the commands executed by the build system aren't
output. You can change that by adding V=1
as an argument to the
rake
command.
If rake
executes too many processes at once, then you've stumbled
across a known bug in rake
. In that case you should install the
drake
Ruby gem and use the command drake
instead of
rake
. drake
supports parallelism properly and doesn't try to
execute all jobs at once.
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, you have to follow these steps:
-
Download the "googletest" framework from https://github.com/google/googletest/ (at the time of writing the file to download was "googletest-release-1.8.0.tar.gz")
-
Extract the archive somewhere and create a symbolic link to its
googletest-release-1.8.0/googletest
sub-directory inside MKVToolNix'lib
directory and call itgtest
, e.g. like this:ln -s /path/to/googletest-release-1.8.0/googletest lib/gtest
-
Configure MKVToolNix normally.
-
Build the unit test executable and run it with
rake tests:run_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 GitLab'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. Code of Conduct
Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.
6. Included third-party components and their licenses
MKVToolNix includes and uses the following libraries & artwork:
6.1. avilib
Reading and writing AVI files. Originally part of the transcode
package.
- Copyright: 1999 Rainer Johanni Rainer@Johanni.de
- License: GNU General Public License v2 or later
- URL: the
transcode
project doesn't seem to have a home page anymore - Corresponding files:
lib/avilib-0.6.10/*
6.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.
- Copyright:
- 2001 Ronald Garcia, Indiana University (garcia@osl.iu.edu)
- Andrew Lumsdaine, Indiana University (lums@osl.iu.edu)
- License: Boost Software License - Version 1.0 (see
doc/licenses/Boost-1.0.txt
) - URL: http://www.boost.org
- Corresponding files:
lib/boost/*
6.3. libEBML
A C++ library to parse EBML files
- Copyright: 2002-2021 Steve Lhomme et. al.
- License: GNU Lesser General Public License v2.1 or later (see
doc/licenses/LGPL-2.1.txt
) - URL: http://www.matroska.org/
- Corresponding files:
lib/libebml/*
6.4. libMatroska
A C++ library to parse Matroska files
- Copyright: 2002-2020 Steve Lhomme et. al.
- License: GNU Lesser General Public License v2.1 or later (see
doc/licenses/LGPL-2.1.txt
) - URL: http://www.matroska.org/
- Corresponding files:
lib/libmatroska/*
6.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.
- Copyright: Moritz Bunkus
- License: GNU Lesser General Public License v2.1 or later (see
doc/licenses/LGPL-2.1.txt
) - URL: https://www.bunkus.org/videotools/librmff/index.html
- Corresponding files:
lib/librmff/*
6.6. nlohmann's JSON
JSON for Modern C++
- Copyright: 2013-2019 Niels Lohmann
- License: MIT (see
doc/licenses/nlohmann-json-MIT.txt
) - URL: https://github.com/nlohmann/json
- Corresponding files:
lib/nlohmann-json/*
6.7. pugixml
An XML processing library
- Copyright: 2006–2019 by Arseny Kapoulkine arseny.kapoulkine@gmail.com
- License: MIT (see
doc/licenses/pugixml-MIT.txt
) - URL: http://pugixml.org/
- Corresponding files:
lib/pugixml/*
6.8. utf8-cpp
UTF-8 with C++ in a Portable Way
- Copyright: 2006 Nemanja Trifunovic
- License: custom (see
doc/licenses/utf8-cpp-custom.txt
) - URL: http://utfcpp.sourceforge.net/
- Corresponding files:
lib/utf8-cpp/*
6.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.
- License: GNU Lesser General Public License v3 (see
doc/licenses/LGPL-3.0.txt
) - URL: https://techbase.kde.org/Projects/Oxygen
- Corresponding files:
share/icons/*
(except forshare/icons/*/mkv*
)share/sounds/*
6.10. MKVToolNix icons
- Copyright:
- 2011 Alexandr Grigorcea cahr.gr@gmail.com
- 2012 Eduard Geier edu.g@online.de
- 2012 Ben Humpert ben@an3k.de
- License: Creative Commons Attribution 3.0 Unported (CC BY 3.0) (see
doc/licenses/CC-BY-3.0.txt
) - Corresponding files:
share/icons/*/mkv*
6.11. QtWaitingSpinner
A highly configurable, custom Qt widget for showing "waiting" or "loading" spinner icons in Qt applications
- Copyright:
- 2012–2014 by Alexander Turkin
- 2014 by William Hallatt
- 2015 by Jacob Dawid
- License: MIT (see
doc/licenses/QtWaitingSpinner-MIT.txt
) - URL: https://github.com/snowwlex/QtWaitingSpinner
- Corresponding files:
src/mkvtoolnix-gui/util/waiting_spinning_widget.{h,cpp}
6.12. Fancy tab widget
A beefed-up tab widget class for Qt extracted from the Qt Creator project
- Copyright: 2011 Nokia Corporation and/or its subsidiary(-ies).
- License: GNU General Public License v2 (see
COPYING
) - Corresponding files:
src/mkvtoolnix-gui/util/fancy_tab_widget.{h,cpp}
6.13. fmt
Small, safe and fast formatting library
- Copyright: 2012–2019 by Victor Zverovich
- License: BSD (see
doc/licenses/fmt-BSD.txt
) - URL: http://fmtlib.net/latest/
- Corresponding files:
lib/fmt/*
6.14. jpcre2
C++ wrapper for PCRE2 Library
- Copyright: 2015–2017 Md Jahidul Hamid
- License: BSD (see
doc/licenses/jpcre2-BSD.txt
) - URL: https://github.com/jpcre2/jpcre2/
- Corresponding files:
lib/jpcre2/*