Completed the first edition of the mmg guide.

doc/mkvmerge-gui.html

@@ -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
+    Formats. It was derived from a project called MCF, but
-  from it significantly because it is based on EBML (Extensible Binary
+    differentiates from it significantly because it is based on EBML
-  Meta Language), a binary derivative of XML. EBML enables the Matroska
+    (Extensible Binary Meta Language), a binary derivative of XML. EBML
-  Development Team to gain significant advantages in terms of future
+    enables the Matroska Development Team to gain significant advantages
-  format extensibility, without breaking file support in old
+    in terms of future format extensibility, without breaking file
-  parsers.</p>
+    support in old parsers.</p>
 
-  <p>If you need any more info please head over to <a
+  <p>If you need any more info please head over to
-  href="http://www.matroska.org/">Matroska's homepage</a>.</p>
+    <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
+    two programs created by <a href="mailto:moritz@bunkus.org">Moritz
-  Bunkus</a>. They're part of the <i>mkvtoolnix</i>
+    Bunkus</a>. They're part of the <i>mkvtoolnix</i>
-  package. <i>mkvmerge</i> can read a lot of different multimedia files
+    package. <i>mkvmerge</i> can read a lot of different multimedia
-  and put their contents into Matroska files. Unfortunately this is a
+    files and put their contents into Matroska files. Unfortunately this
-  command line program, and not everyone is comfortable working on the
+    is a command line program, and not everyone is comfortable working
-  command line. This is where <i>mkvmerge GUI</i> comes into play. It is
+    on the command line. This is where <i>mkvmerge GUI</i> comes into
-  a GUI that provides the user with an intuitive but powerful interface
+    play. It is a GUI that provides the user with an intuitive but
-  to <i>mkvmerge</i>.</p>
+    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
+    other Unix derivatives. The program is licensed under the GPL, so
-  source code is available to anyone interested.</p>
+    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'
+    <a href="http://www.bunkus.org/videotools/mkvtoolnix/">Moritz
-  website</a>. Windows users will have to download the runtime DLLs as
+    Bunkus' website</a>. Windows users will have to download the runtime
-  well as the <i>mkvtoolnix</i> binaries. Linux/Unix users will probably
+    DLLs as well as the <i>mkvtoolnix</i> binaries. Linux/Unix users
-  download the sources and compile <i>mkvtoolnix</i> themselves.</p>
+    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
+    command line options are explained in detail in <a
-  page/HTML page.</p>
+    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
+      installation. <i>mkvmerge</i>'s own documentation and the
-  <code>README</code> files that are included in the <i>mkvtoolnix</i>
+      <code>README</code> files that are included in the
-  package.</i>)</p>
+      <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
+          <i>mkvmerge</i> binary. Under normal circumstances it will be
-        found automatically. But if not then you can select the binary
+          found automatically. But if not then you can select the binary
-        to use on the <i>Settings</i> tab.</p>
+          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>. An input <i>file</i> usually contains one or more
-  <i>tracks</i>. <i>mkvmerge</i> needs at least one input file and the
+    <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
+    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
+    work. Starting with this minimal set of options the user can add
-  input files, select advanced options for each track, apply some more
+    more input files, select advanced options for each track, apply some
-  global options etc.</p>
+    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
+          most important tab: the <i>input tab</i>. Here you see four
-        different elements. The topmost input box lists all input
+          different elements. The topmost input box lists all input
-        <i>files</i>. Directly under this box are options that apply
+          <i>files</i>. Directly under this box are options that apply
-        to the currently selected input <i>file</i>.</p>
+          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
+          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>
+          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
+          box the second list box will contains all <i>tracks</i> that
-        be read from this <i>file</i>. Each track is ENabled by default
+          can be read from this <i>file</i>. Each track is ENabled by
-        and will be muxed into the resulting file. However, you can
+          default and will be muxed into the resulting file. However,
-        change that by simply clicking on the check box right in front of
+          you can change that by simply clicking on the check box right
-        the track's name in the second list box. For each of these
+          in front of the track's name in the second list box. For each
-        tracks the user can select track specific options with the input
+          of these tracks the user can select track specific options
-        boxes and check boxes below the track listing. These options
+          with the input boxes and check boxes below the track
-        will be described in the following sections.</p>
+          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
+        <font size="-1">Three enabled tracks and one disabled track. The
-        not be copied into the output file.
+        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 that apply to this specific file. At the moment three such
-  options have been implemented: <code>No chapters</code> and <code>No
+    options have been implemented, and they all are only available for
-  attachments</code>. These options tell <i>mkvmerge</i> not to copy any
+    Matroska files: <code>No chapters</code>, <code>No
-  chapters / attachments from the current source file.</p>
+    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
+    the <a href="mkvmerge-gui.html#chaptereditor">chapter editor</a> in
-  this document and in <i>mkvmerge</i>'s own documentation.</p>
+    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
+    video, subtitles) and even depending on the contents of the track
-  a subset of all the track specific options are available. The options
+    only a subset of all the track specific options are available. The
-  are:</p>
+    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>