ubuntu-touch-icons/README.md

MKVToolNix 22.0.0


Table of contents


Introduction

Installation


Requirements
Optional components
Building libEBML and libMatroska
Building MKVToolNix
Getting and building a development snapshot
Configuration and compilation
Notes for compilation on (Open)Solaris
Unit tests


Reporting bugs
Test suite and continuous integration tests
Code of Conduct

Included libraries and their licenses


avilib
Boost's utf8_codecvt_facet
libEBML
libMatroska
librmff
nlohmann's JSON
pugixml
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

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.

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

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.5 or later
and libMatroska v1.4.8
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.49.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.
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 with the two libraries. Either download releases of
libEBML v1.3.5 and
libMatroska v1.4.8 or
get 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
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 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/include/gtest sub-directory
inside MKVToolNix' "lib" directory.
Configure MKVToolNix normally.

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 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-2010 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-2010 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-2016 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–2017 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 for share/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}