From 36afe85209bb2ed01a6f7ed422241e70ec9bf2e0 Mon Sep 17 00:00:00 2001 From: Franck ALBARET Date: Mon, 16 Apr 2018 08:01:21 +0000 Subject: [PATCH] Add new file --- README.md | 509 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 509 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1c4be04 --- /dev/null +++ b/README.md @@ -0,0 +1,509 @@ +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, +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} \ No newline at end of file