Creating and working with Matroska files
Go to file
Moritz Bunkus a65edec28f ...
2008-09-28 17:10:58 +00:00
ac I will use features introduced in Boost 1.29 soon. 2008-09-25 13:21:31 +00:00
avilib-0.6.10 Enabled warnings about shadowed variables and solved all of the resulting warnings. 2008-02-25 17:13:13 +00:00
contrib Moved the base64tool into the src/tools directory so that it will not be built by default anymore. 2008-09-20 14:21:05 +00:00
debian Moved the base64tool into the src/tools directory so that it will not be built by default anymore. 2008-09-20 14:21:05 +00:00
doc Better wording ;) 2008-09-22 17:27:47 +00:00
examples Added an example for the "--segmentinfo" command line parameter. 2007-08-19 09:12:15 +00:00
librmff Updated a link. 2007-01-11 11:01:16 +00:00
po Makefile/configure: cached the libebml and libmatroska checks; added checks for gettext. Rest: Added some support for translations (way incomplete, but it's a start). 2004-07-18 15:06:33 +00:00
src Scan the other directories, too. 2008-09-28 16:59:50 +00:00
tests Intentional change due to the fix in revision 3917. 2008-09-20 18:03:11 +00:00
AUTHORS Added support for PCM tracks with floating point numbers (CodecID A_PCM/FLOAT/IEEE). Patch by Aurelien Jacobs (see AUTHORS). 2008-08-23 12:02:10 +00:00
autogen.sh Removal of the old mingw build system. 2004-11-14 12:47:07 +00:00
ChangeLog Use the timecodes provided by the MPEG PS stream for the VC1 video packets. 2008-09-25 09:54:29 +00:00
common.vcproj Added support for the new SimpleBlock instead of BlockGroups. Patch by Steve Lhomme (steve ! lhomme () free ! fr) with fixes by myself. 2005-10-21 11:11:57 +00:00
config.msvc.h Fixes for compilation with MSVC. Added vsscanf because MSVC doesn't provide one. Patch by Steve Lhomee <steve.lhomme@free.fr>, modifications by Moritz Bunkus <moritz@bunkus.org>. 2004-10-11 20:16:16 +00:00
configure.in Bumped the version number to 2.3.0, set the release name and added the release message. 2008-09-07 12:49:59 +00:00
COPYING
INSTALL
install-sh
libmtxcommon.vcproj Merged 2100:2102 2004-08-29 11:55:57 +00:00
Makefile.in *** empty log message *** 2008-09-25 14:42:04 +00:00
mkinstalldirs
mkvextract.vcproj Updated the MSVC project files. Patch by Steve Lhomee (see AUTHORS). 2005-05-26 17:48:13 +00:00
mkvinfo.vcproj Support for "silent tracks" elements. Added project file for mkvinfo for MSVC. Patch by Steve Lhomme <steve ! lhomme () free ! fr> 2004-12-28 18:50:54 +00:00
mkvmerge.vcproj Added support for the new SimpleBlock instead of BlockGroups. Patch by Steve Lhomme (steve ! lhomme () free ! fr) with fixes by myself. 2005-10-21 11:11:57 +00:00
mkvtoolnix-unicode.nsi Bumped the version number to 2.3.0, set the release name and added the release message. 2008-09-07 12:49:59 +00:00
mkvtoolnix.nsi Bumped the version number to 2.3.0, set the release name and added the release message. 2008-09-07 12:49:59 +00:00
mkvtoolnix.sln Support for "silent tracks" elements. Added project file for mkvinfo for MSVC. Patch by Steve Lhomme <steve ! lhomme () free ! fr> 2004-12-28 18:50:54 +00:00
NEWS
README ... 2008-09-28 17:10:58 +00:00
README.Windows.txt Bumped the version number to 2.3.0, set the release name and added the release message. 2008-09-07 12:49:59 +00:00
TODO I don't use Anthill anymore. 2008-02-29 11:15:28 +00:00

MKVToolNix 2.3.0
================

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 (see www.gnu.org or the file COPYING).
Modify as needed.

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

Moritz Bunkus <moritz@bunkus.org>

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 Subversion
repository that are not available in the releases. On the other hand
the Subversion repository version might not even compile.

* Requirements

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

- libebml and libmatroska for low-level access to Matroska files.
  Instructions on how to compile them are a bit further down in this
  file.
- expat ( http://expat.sourceforge.net/ ) -- a light-weight XML
  parser library
- 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

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

- wxWidgets ( http://www.wxwidgets.org/ ) -- a cross-platform GUI
  toolkit. You need this if you want to use mmg (the mkvmerge GUI) or
  mkvinfo's GUI.
- libFLAC ( http://downloads.xiph.org/releases/flac/ ) for FLAC
  support (Free Lossless Audio Codec)
- lzo ( http://www.oberhumer.com/opensource/lzo/ ) and bzip2 (
  http://www.bzip.org/ ) 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.

* Building libmatroska and libebml

Start with the two libraries. Either get libebml 0.7.7 from
http://dl.matroska.org/downloads/libebml/ and libmatroska 0.8.0 from
http://dl.matroska.org/downloads/libmatroska/ or a fresh copy from the
Subversion repository:

svn co https://svn.matroska.org/svn/matroska/trunk/libebml
svn co https://svn.matroska.org/svn/matroska/trunk/libmatroska

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

* Building MKVtoolNix

Either download the current release from
http://www.bunkus.org/videotools/mkvtoolnix/ and unpack it or get a
fresh copy from my Subversion repository.  All you need for Subversion
repository access is to download a Subversion client from the
Subversion homepage at http://subversion.tigris.org/ . There are
clients for both Unix/Linux and Windows. It basically works like
CVS. So the typical way to check out a fresh copy looks like this:

svn co https://svn.bunkus.org/mosu/trunk/prog/video/mkvtoolnix

    Additional step if you're using the development version from the
    Subversion respository:

    Change to the MKVtoolNix directory and run "./autogen.sh" which
    will generate the "configure" script.

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/linue

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

Example
-------

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

a) Extract the audio to PCM audio:

mplayer -ao pcm:file=audio.wav -vo null -vc dummy dvd://1

b) Normalize the sound (optional)

normalize audio.wav

c) Encode the audio to Vorbis:

oggenc -q3 -oaudio-q3.ogg audio.wav

d) 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

e) 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

f) 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.

Bug reports
-----------

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 Bugzilla (https://www.bunkus.org/bugzilla/) 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 and post a link in the Anthill bug
report.