Download-Tools/mkvtoolnix
1
0
Fork 0
mirror of https://gitlab.com/mbunkus/mkvtoolnix.git synced 2024-12-23 19:31:44 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Completed the first edition of the mmg guide.

Browse Source
This commit is contained in:
Moritz Bunkus 2003-10-02 23:48:14 +00:00
parent e90d00a810
commit 440bdee3e1
3 changed files with 340 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/images/chaptereditor.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
doc/images/muxingwindow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

404
doc/mkvmerge-gui.html
View File

@ -129,18 +129,18 @@
<h3><a name="whatismatroska">What is Matroska?</a></h3>
<p>(<i>Note: simply copied from <a href="http://www.matroska.org/">
www.matroska.org</a>.</i>)</p>
www.matroska.org</a>.</i>)</p>
<p><b>Matroska</b> aims to become THE Standard of Multimedia Container
Formats. It was derived from a project called MCF, but differentiates
from it significantly because it is based on EBML (Extensible Binary
Meta Language), a binary derivative of XML. EBML enables the Matroska
Development Team to gain significant advantages in terms of future
format extensibility, without breaking file support in old
parsers.</p>
Formats. It was derived from a project called MCF, but
differentiates from it significantly because it is based on EBML
(Extensible Binary Meta Language), a binary derivative of XML. EBML
enables the Matroska Development Team to gain significant advantages
in terms of future format extensibility, without breaking file
support in old parsers.</p>
<p>If you need any more info please head over to <a
href="http://www.matroska.org/">Matroska's homepage</a>.</p>
<p>If you need any more info please head over to
<a href="http://www.matroska.org/">Matroska's homepage</a>.</p>
<h3>
<a name="whatismkvmerge">What is mkvmerge? What is mkvmerge
@ -149,49 +149,50 @@
</h3>
<p><i>mkvmerge</i> and <i>mkvmerge GUI</i> (or just <i>mmg</i>) are
two programs created by <a href="mailto:moritz@bunkus.org">Moritz
Bunkus</a>. They're part of the <i>mkvtoolnix</i>
package. <i>mkvmerge</i> can read a lot of different multimedia files
and put their contents into Matroska files. Unfortunately this is a
command line program, and not everyone is comfortable working on the
command line. This is where <i>mkvmerge GUI</i> comes into play. It is
a GUI that provides the user with an intuitive but powerful interface
to <i>mkvmerge</i>.</p>
two programs created by <a href="mailto:moritz@bunkus.org">Moritz
Bunkus</a>. They're part of the <i>mkvtoolnix</i>
package. <i>mkvmerge</i> can read a lot of different multimedia
files and put their contents into Matroska files. Unfortunately this
is a command line program, and not everyone is comfortable working
on the command line. This is where <i>mkvmerge GUI</i> comes into
play. It is a GUI that provides the user with an intuitive but
powerful interface to <i>mkvmerge</i>.</p>
<p>Both programs are available for both Windows and GNU/Linux and
other Unix derivatives. The program is licensed under the GPL, so the
source code is available to anyone interested.</p>
other Unix derivatives. The program is licensed under the GPL, so
the source code is available to anyone interested.</p>
<h3><a name="latestversion">Obtaining the latest version</a></h3>
<p>You can always find the latest version of <i>mkvtoolnix</i> on
<a href="http://www.bunkus.org/videotools/mkvtoolnix/">Moritz Bunkus'
website</a>. Windows users will have to download the runtime DLLs as
well as the <i>mkvtoolnix</i> binaries. Linux/Unix users will probably
download the sources and compile <i>mkvtoolnix</i> themselves.</p>
<a href="http://www.bunkus.org/videotools/mkvtoolnix/">Moritz
Bunkus' website</a>. Windows users will have to download the runtime
DLLs as well as the <i>mkvtoolnix</i> binaries. Linux/Unix users
will probably download the sources and compile
<i>mkvtoolnix</i> themselves.</p>
<h3><a name="scope">Scope of this guide</a></h3>
<p>This guide only focusses on the GUI part of these tools. All
command line options are explained in detail in <i>mkvmerge</i>'s man
page/HTML page.</p>
command line options are explained in detail in <a
href="mkvmerge.html"><i>mkvmerge</i>'s man page/HTML page</a>.</p>
<hr>
<h2><a name="setup">Setting up mkvmerge GUI</a></h2>
<p>(<i>Note: This section does not cover compilation and
installation. mkvmerge's own documentation and the
<code>README</code> files that are included in the <i>mkvtoolnix</i>
package.</i>)</p>
installation. <i>mkvmerge</i>'s own documentation and the
<code>README</code> files that are included in the
<i>mkvtoolnix</i> package.</i>)</p>
<table width="100%" border="0">
<tr>
<td>
<p>The only thing that <i>mmg</i> needs to know is the location of the
<i>mkvmerge</i> binary. Under normal circumstances it will be
found automatically. But if not then you can select the binary
to use on the <i>Settings</i> tab.</p>
<i>mkvmerge</i> binary. Under normal circumstances it will be
found automatically. But if not then you can select the binary
to use on the <i>Settings</i> tab.</p>
</td>
<td>&nbsp;</td>
<td>
@ -211,12 +212,12 @@
<h3><a name="basics">Basics</a></h3>
<p><i>mkvmerge</i> strictly differentiates between <i>files</i> and
<i>tracks</i>. An input <i>file</i> usually contains one or more
<i>tracks</i>. <i>mkvmerge</i> needs at least one input file and the
file name of the Matroska file it should create before it can do any
work. Starting with this minimal set of options the user can add more
input files, select advanced options for each track, apply some more
global options etc.</p>
<i>tracks</i>. An input <i>file</i> usually contains one or more
<i>tracks</i>. <i>mkvmerge</i> needs at least one input file and the
file name of the Matroska file it should create before it can do any
work. Starting with this minimal set of options the user can add
more input files, select advanced options for each track, apply some
more global options etc.</p>
<p>The typical basic steps are:<br>
<ol>
@ -233,14 +234,14 @@
<td valign="top">
<p>When <i>mmg</i> starts up it shows the first and probably
most important tab: the <i>input tab</i>. Here you see four
different elements. The topmost input box lists all input
<i>files</i>. Directly under this box are options that apply
to the currently selected input <i>file</i>.</p>
most important tab: the <i>input tab</i>. Here you see four
different elements. The topmost input box lists all input
<i>files</i>. Directly under this box are options that apply
to the currently selected input <i>file</i>.</p>
<p>The two buttons to the right of the upper list box can be
used to add files to the list box with the <i>+</i> button and
to remove the selected entry with the <i>-</i> button.</p>
used to add files to the list box with the <i>+</i> button and
to remove the selected entry with the <i>-</i> button.</p>
</td>
<td>&nbsp;</td>
@ -255,22 +256,23 @@
<tr>
<td valign="top">
<p>Once the user selects an input <i>file</i> in the upper list
box the second list box will contains all <i>tracks</i> that can
be read from this <i>file</i>. Each track is ENabled by default
and will be muxed into the resulting file. However, you can
change that by simply clicking on the check box right in front of
the track's name in the second list box. For each of these
tracks the user can select track specific options with the input
boxes and check boxes below the track listing. These options
will be described in the following sections.</p>
box the second list box will contains all <i>tracks</i> that
can be read from this <i>file</i>. Each track is ENabled by
default and will be muxed into the resulting file. However,
you can change that by simply clicking on the check box right
in front of the track's name in the second list box. For each
of these tracks the user can select track specific options
with the input boxes and check boxes below the track
listing. These options will be described in the following
sections.</p>
</td>
<td>&nbsp;</td>
<td>
<img src="images/trackselection.png"
alt="selecting specific tracks">
<br>
Three enabled tracks and one disabled track. The fourth track will
not be copied into the output file.
<font size="-1">Three enabled tracks and one disabled track. The
fourth track will not be copied into the output file.</font>
</td>
</tr>
@ -280,21 +282,27 @@
<h3><a name="fileoptions">Options for input file</a></h3>
<p>Once the user has added and selected an input file he can set
options that apply to this specific file. At the moment only two such
options have been implemented: <code>No chapters</code> and <code>No
attachments</code>. These options tell <i>mkvmerge</i> not to copy any
chapters / attachments from the current source file.</p>
options that apply to this specific file. At the moment three such
options have been implemented, and they all are only available for
Matroska files: <code>No chapters</code>, <code>No
attachments</code> and <code>No tags</code>. These options tell
<i>mkvmerge</i> not to copy any chapters / attachments / tags from
the current source file.
<br>
<b>Note:</b> At the time of writing <i>mkvmerge</i> cannot copy tags
from a source Matroska file. You have to extract them with
mkvextract first.</p>
<p>More information about chapters can be found in the section about
the <a href="mkvmerge-gui.html#chaptereditor">chapter editor</a> in
this document and in <i>mkvmerge</i>'s own documentation.</p>
the <a href="mkvmerge-gui.html#chaptereditor">chapter editor</a> in
this document and in <i>mkvmerge</i>'s own documentation.</p>
<h3><a name="trackoptions">Options for each track</a></h3>
<p>Depending on the type of the currently selected track (audio,
video, subtitles) and even depending on the contents of the track only
a subset of all the track specific options are available. The options
are:</p>
video, subtitles) and even depending on the contents of the track
only a subset of all the track specific options are available. The
options are:</p>
<table width="100%" border="0">
<tr>
@ -318,7 +326,9 @@
frames. Usually this option should be left on the value
'default'. <i>mkvmerge</i> will automatically chose the best
method for any given track type. A full explanation of
tracks can be found in <i>mkvmerge</i>'s documentation.</li>
tracks can be found in <a
href="mkvmerge.html"><i>mkvmerge</i>'s
documentation</a>.</li>
<li><code>Aspect ratio:</code> With this option the user can
set the aspect ratio that should be used upon playback. It
@ -388,6 +398,16 @@
user has to check this option manually if it applies. Please
note that this problem does not exist for HE-AAC stored in
<code>.MP4</code> files.</li>
<li><code>Tags:</code> For each track you can create a XML
tags file. For a full explanation of all tags please refer
to the example file and <a
href="mkvmerge.html"><i>mkvmerge</i>'s own
documentation</a>. In probably 99% of all cases you want to
use THIS option and associate tags with a specific
track. The tags option on the global tab is probably not
what you need.</li>
</ul>
</td>
<td>&nbsp;</td>
@ -509,7 +529,6 @@
accumulated. The formats accepted are:
<br>
<ul>
<li>For the size: A number optionally followed by the letter
'K', 'M' or 'G' indicating kilobytes (1024 bytes),
megabytes (1024 * 1024 bytes) or gigabytes (1024 * 1024 *
@ -574,6 +593,25 @@
the one output file will be linked to both of the two
UIDs.</p>
<h4><a name="global_chapters">Chapters</a></h4>
<p>With the browse button you can select the chapters to add to
the output file. A full explanation of all aspects around
chapters can be found in the <a
href="mkvmerge-gui.html#chaptereditor"> Chapter editor
section</a>.</p>
<h4><a name="global_tags">Global tags</a></h4>
<p>Unlike the tags you can select for each track on the input
tab the tags selected here have to contain the track
UIDs. These tags are not assigned to any track
automatically. In 99% of all cases this is NOT the option you
want to use!</p>
<p>The full explanation can be found in
<a href="mkvmerge.html">mkvmerge's documentation</a>.</p>
</td>
<td>&nbsp;</td>
<td valign="top">
@ -590,31 +628,269 @@
<h3><a name="doit">Starting the merge process</a></h3>
<table width="100%" border="0">
<tr>
<td valign="top">
<p>Once everything has been set up the muxing process can be
started. The last thing to do is to chose where to mux
to. With the <code>browse</code> button you can select the
output file. After this has been done hit the <code>Start
muxing</code> button or select the same entry from the
<code>Muxing</code> menu.</p>
<p>If everything has been set up correctly <i>mmg</i> will show
the muxing dialog. The progress is shown at the top, as is a
general description of what <i>mkvmerge</i> is doing at the
moment (muxing, 1st pass of splitting files or 2nd pass of
splitting files).</p>
<p><i>mkvmerge</i> knows three different 'severity levels' for
its messages: status reports, warnings and errors. All status
report messages are shown in the upper window. These include
the track types encountered and other interesting things.</p>
<p>Warnings are shown in the middle window. <i>mkvmerge</i> will
not abort when it issues a warning, but it might stop muxing
the track for which the warning was printed. You should pay
close attention to all warning messages.</p>
<p>Errors are show in the lower window. Errors are always fatal,
and <i>mkvmerge</i> will stop muxing right after it has printed
the error message. Such a message might be that the hard disc
is full or that the source file is damaged and cannot be
processed any further.</p>
<p>The button <code>Abort</code> sends <i>mkvmerge</i> the
signal to stop muxing. Unless <i>mkvmerge</i> is stuck in some
endless loop it will stop soon after you've pressed the
button. With <code>Save log</code> you can save the complete
output from <i>mkvmerge</i> into a text file for further study
or in case you've encountered a bug and want to send me some
additional information.</p>
</td>
<td>&nbsp;</td>
<td valign="top">
<p>
<img src="images/muxingwindow.png"
alt="the muxing window">
<br>
<font size="-1">The muxing window</font>
</p>
</td>
</tr>
</table>
<h3><a name="saveload">Saving and loading muxing settings</a></h3>
<p>All your hard work of setting options does not have to be lost when
you exit the program. You can save all your muxing settings into
text based configuration files with the <code>Save settings</code>
option in the <code>File</code> menu and restore them later with the
<code>Load settings</code> option. The default extension is
<code>.mmg</code> and is usually not used by other programs. You can
also associate this extension with <i>mmg</i> so that it
automatically loads the settings if it is called with the name of
such a settings file.</p>
<hr>
<h2><a name="chaptereditor">The chapter editor</a></h2>
<p>One of the new features of <i>mmg</i> is a full-featured chapter
editor. It can read text based chapter files, import chapters from
existing Matroska files, write text based chapter files that can be
selected on the global tab and write chapters directly to existing
Matroska files.</p>
<h3><a name="chapterconcept">Matroska's chapter concept</a></h3>
<p>Unlike a lot of other systems Matroska supports <i>nested</i>
chapters. This basically means that you can define sub chapters for
chapters.</p>
<p>A chapter entity in Matroska consists of at least four items: The
UID of the track(s) it applies to, the chapter title/name, it's
start time and the language code associated with it. Additional
elements are optional and include the end time, more language codes
and country codes. Usually the user will only need the mandatory
elements. Of these he can only specify the name, the start time and
the language code. <i>mkvmerge</i> will then automatically assign
all chapters to the complete file.</p>
<h3><a name="chapterexamples">Examples</a></h3>
<p>The first example is a simple one. The movie in question contains
four parts: The intro starting at the beginning, the first act, the
second act, and the credits. Note that the end timestamps are
optional.</p>
<p><code>Intro (from 00:00:00, language English)<br>
Act 1 (from 00:01:00, language English)<br>
Act 2 (from 00:05:30, language English)<br>
Credits (from 00:12:20 until 00;12:55, language
English)</code></p>
<p>A more complex example including sub chapters. Let's take Ludwig
van Beethoven's opera Fidelio. For the sake of brevity I'm only
including the first three pieces of the two acts.</p>
<p>The first act contains:
<ol>
<li>Overt&uuml;re (6:24 long),</li>
<li>Arie: 'Jetzt, Sch&auml;tzchen, jetzt sind wir allein' (4:46
long) and</li>
<li>Dialog: 'Armer Jaquino' (0:10 long).</li>
</ol>
The second act contains:
<ol>
<li>Ouvert&uuml;re und Arie: 'Gott! welch Dunkel hier!' (10:46
long),</li>
<li>Melodrama und Duett: 'Wie kalt ist es' (5:21 long) and</li>
<li>Dialog: 'Er erwacht!' (0:59 long).</li>
</ol>
</p>
<p>The first act, which will be our first chapter, has a combined
length of 11:20. Our second act has a length of 17:06. These
chapters would look like this:</p>
<p><code>Erster Akt (from 00:00:00 until 00:11:20, language German,
country Germany)<br>
&nbsp;&nbsp;&nbsp;
Ouvert&uuml;re (from 00:00:00 until 00:06:24, language German,
country Germany)<br>
&nbsp;&nbsp;&nbsp;
Arie: 'Jetzt, Sch&auml;tzchen, jetzt sind wir allein' (from
00:06:24 until 00:11:10, language German, country Germany)<br>
&nbsp;&nbsp;&nbsp;
Dialog: 'Armer Jaquino' (from 00:11:10 until 00:11:20, language
German, country Germany)<br>
Zweiter Akt (from 00:11:20 until 00:28:26, language German,
country Germany)<br>
&nbsp;&nbsp;&nbsp;
Ouvert&uuml;re und Arie: 'Gott! welch Dunkel hier!' (from 00:11:20
until 00:22:06, language German, country Germany)<br>
&nbsp;&nbsp;&nbsp;
Melodrama und Duett: 'Wie kalt ist es' (from 00:22:06 until
00:27:27, language German, country Germany)<br>
&nbsp;&nbsp;&nbsp;
Dialog: 'Er erwacht!' (from 00:27:27 until 00:28:26, language
German, country Germany)
</code>
</p>
<h3>
<a name="chapterformats">Chapter formats supported by
mkvmerge
</a>
</h3>
<p><i>mkvmerge</i> and <i>mmg</i>'s chapter editor both support
different formats for chapter files.</p>
<h4><a name="cfsimple">Simple/OGM style chapter files</a></h4>
<p>One of the most basic formats is the format used in OGM files. It
is a text based format. Each chapter entry contains of two lines,
the first containing the start time, the second the chapter's
title/name. All lines are numbered.</p>
<p>The first example from above can be expressed in this format:<br>
<code>CHAPTER01=00:00:00.000<br>
CHAPTER01NAME=Intro<br>
CHAPTER02=00:01:00.000<br>
CHAPTER02NAME=Act 1<br>
CHAPTER03=00:05:30.000<br>
CHAPTER03NAME=Act 2<br>
CHAPTER04=00:12:20.000<br>
CHAPTER04NAME=Credits
</code>
</p>
<p>The second example cannot be expressed in this format because it
supports neither language specifications nor end times or nested
chapters. The advantage is that such files are very easy to create,
and there are several tools available for both Windows and
Unix/Linux that create such files directly from DVDs.</p>
<p>Due to its limitations <i>mmg</i> cannot output chapters in this
format.</p>
<h4><a name="cfxml">Full-featured XML style chapter files</a></h4>
<p>I've created a XML based chapter format that closely matches the
system Matroska uses. With this format you have the full control
over all features. I won't describe this format here in
detail. Please have a look at the example XML chapter files that
came with <i>mkvtoolnix</i>.</p>
<h4><a name="cfkax">Chapters found in Matroska files</a></h4>
<p>The chapter editor can read chapters directly from Matroska
files. These can be written to XML chapter files or back to the same
Matroska file or another Matroska file. All features are
supported.</p>
<h3><a name="creatingchapters">Creating chapter files</a></h3>
<table width="100%" border="0">
<tr>
<td valign="top">
<p>The chapter editor consists of three parts: the tree view of
all chapters, the three buttons used for adding and removing
chapter entries, and the input boxes which are used for
setting the chapter entry's data.</p>
<p>A new chapter file is started with the <code>New</code>
option from the <code>Chapter editor</code> menu. You can add
a new chapter with the <code>Add chapter</code> or <code>Add
subchapter</code> buttons. The difference between these two
buttons is that when a chapter has been selected <code>Add
chapter</code> will append a new chapter directly after the
selected chapter on the same level, and <code>Add
subchapter</code> will add a new chapter as the last child of
the currently selected chapter.</p>
<p>The <code>Remove chapter</code> has to be used with care. It
removes the complete subtree without asking for confirmation,
and there is no undo option available at the moment.</p>
<p>After selecting a chapter entry you can change its data. The
format for the start and end time are either
<code>HH:MM:SS.mmm</code> or simply <code>HH:MM:SS</code>. The
language codes are the same ISO639-2 language codes used
everywhere else. Please note that you can use more than one
language codes by separating them with spaces. You can add a
language code to the already entered codes by selecting it
from the drop down box. The same is true for the country codes
which are ISO639-1 codes. You can have more than country code
by separating them with spaces.</p>
<p>Saving chapters to XML files can be done with <code>Save</code> or
<code>Save as</code>. <code>Save as</code> cannot be used to
write chapters to an existing Matroska file - you'll have to
use <code>Save to Matroska file</code> for that.</p>
</td>
<td>&nbsp;</td>
<td>
<p>
<img src="images/chaptereditor.png"
alt="the chapter editor">
<br>
<font size="-1">The chapter editor showing the example from
above</font>
</p>
</td>
</tr>
</table>
<h3><a name="editingchapters">Editing existing chapters</a></h3>
<p>You can load existing chapter files or chapters from Matroska files
by selecting the <code>Load</code> option from the <code>Chapter
editor</code> menu. <i>mmg</i> will automatically detect the file
type used and read the chapters.</p>
</body>
</html>