Download-Tools/mkvtoolnix
1
0
Fork 0
mirror of https://gitlab.com/mbunkus/mkvtoolnix.git synced 2024-12-24 11:54:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Finally a full conversion including a couple of updates.

Browse Source
This commit is contained in:
Moritz Bunkus 2009-08-09 18:01:07 +02:00
parent 34faf5a63c
commit 3377dfa947
1 changed files with 634 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

651
doc/docbook/mkvmerge.xml
View File

@ -4,6 +4,7 @@
[
<!ENTITY product "mkvmerge">
<!ENTITY version "2.9.7">
<!ENTITY date "July 2009">
<!ENTITY mkvmerge "<citerefentry><refentrytitle>mkvmerge</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
<!ENTITY mkvinfo "<citerefentry><refentrytitle>mkvinfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
@ -12,12 +13,14 @@
<!ENTITY matroska "<productname>Matroska</productname>">
<!ENTITY oggvorbis "<productname>OggVorbis</productname>">
<!ENTITY xml "<abbrev>XML</abbrev>">
]>
<refentry lang="en" id="mkvmerge">
<refentryinfo>
<productname>&product;</productname>
<date>&date;</date>
<authorgroup>
<author>
<contrib>Developer</contrib>
@ -31,7 +34,8 @@
<refentrytitle>&product;</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="version">&version;</refmiscinfo>
<refmiscinfo class="source">http://www.bunkus.org/videotools/mkvtoolnix</refmiscinfo>
<refmiscinfo class="date">&date;</refmiscinfo>
<refmiscinfo class="source">www.bunkus.org</refmiscinfo>
<refmiscinfo class="manual">http://www.bunkus.org/videotools/mkvtoolnix/doc</refmiscinfo>
</refmeta>
@ -97,10 +101,10 @@
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="mkvmerge.description.tags">
<term><option>--tags</option> <parameter>file-name</parameter></term>
<listitem>
<para>Read global tags from the <abbrev>XML</abbrev> file <parameter>file-name</parameter>. See the section about tags below for
<para>Read global tags from the &xml; file <parameter>file-name</parameter>. See the section about tags below for
details.</para>
</listitem>
</varlistentry>
@ -116,7 +120,7 @@
</variablelist>
<para>
Chapter handling: (global options)
Chapter and tag handling: (global options)
</para>
<variablelist>
@ -135,7 +139,7 @@
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="mkvmerge.description.chapter_charset">
<term><option>--chapter-charset</option> <parameter>character-set</parameter></term>
<listitem>
<para>
@ -197,6 +201,16 @@
</para>
</listitem>
</varlistentry>
<varlistentry id="mkvmerge.description.global_tags">
<term><option>--global-tags</option> <parameter>file-name</parameter></term>
<listitem>
<para>
Read global tags from the file <parameter>file-name</parameter>. See the section about <link linkend="mkvmerge.tags">tags</link> below
for details.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
@ -572,7 +586,7 @@
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--video-tracks</option> <parameter>n,m,...</parameter></term>
<term><option>-d</option>, <option>--video-tracks</option> <parameter>n,m,...</parameter></term>
<listitem>
<para>
Copy the video tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with the
@ -583,7 +597,7 @@
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--subtitle-tracks</option> <parameter>n,m,...</parameter></term>
<term><option>-s</option>, <option>--subtitle-tracks</option> <parameter>n,m,...</parameter></term>
<listitem>
<para>
Copy the subtitle tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with
@ -594,7 +608,7 @@
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--button-tracks</option> <parameter>n,m,...</parameter></term>
<term><option>-b</option>, <option>--button-tracks</option> <parameter>n,m,...</parameter></term>
<listitem>
<para>
Copy the button tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with
@ -615,6 +629,23 @@
</listitem>
</varlistentry>
<varlistentry id="mkvmerge.description.attachments">
<term><option>-m</option>, <option>--attachments</option> <parameter>n<optional>:all|first</optional>,m<optional>:all|first</optional>,...</parameter></term>
<listitem>
<para>
Copy the attachments with the IDs <parameter>n</parameter>, <parameter>m</parameter> etc to all or only the first output file. Each ID
can be followed by either '<literal>:all</literal>' (which is the default if neither is entered) or '<literal>:first</literal>'. If
splitting is active then those attachments whose IDs are specified with '<literal>:all</literal>' are copied to all of the resulting
output files while the others are only copied into the first output file. If splitting is not active then both variants have the same
effect.
</para>
<para>
The default is to copy all attachments to all output files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-A</option>, <option>--no-audio</option></term>
<listitem>
@ -660,7 +691,7 @@
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="mkvmerge.description.no_chapters">
<term><option>--no-chapters</option></term>
<listitem>
<para>
@ -669,8 +700,8 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-attachments</option></term>
<varlistentry id="mkvmerge.description.no_attachments">
<term><option>-M</option>, <option>--no-attachments</option></term>
<listitem>
<para>
Don't copy attachments from this file.
@ -1014,7 +1045,7 @@
</para>
<variablelist>
<varlistentry>
<varlistentry id="mkvmerge.description.sub_charset">
<term><option>--sub-charset</option> <parameter>TID:character-set</parameter></term>
<listitem>
<para>
@ -1078,7 +1109,7 @@
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="mkvmerge.description.command_line_charset">
<term><option>--command-line-charset</option> <parameter>character-set</parameter></term>
<listitem>
<para>
@ -1101,7 +1132,7 @@
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="mkvmerge.description.redirect_output">
<term><option>-r</option>, <option>--redirect-output</option> <parameter>file-name</parameter></term>
<listitem>
<para>
@ -1112,7 +1143,7 @@
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="mkvmerge.description.ui_language">
<term><option>--ui-language</option> <parameter>code</parameter></term>
<listitem>
<para>
@ -1294,7 +1325,7 @@ $ mkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-audio.ogg
<para>
For text subtitles you can either use some Windows software (like <productname>SubRipper</productname>) or the
<productname>subrip</productname> package found in
<citerefentry><refentrytitle>transcode</refentrytitle><manvolume>1</manvolume></citerefentry>'s sources in the
<citerefentry><refentrytitle>transcode</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s sources in the
'<literal>contrib/subrip</literal>' directory. The general process is:
</para>
@ -1334,7 +1365,7 @@ $ mkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-audio.ogg
<screen>$ mkvmerge --list-languages</screen>
<para>
Search the list for the languages you need. Let's assume you have put two audio tracks into a Matroska file and want to set their
Search the list for the languages you need. Let's assume you have put two audio tracks into a &matroska; file and want to set their
language codes and that their track IDs are 2 and 3. This can be done with
</para>
@ -1357,6 +1388,185 @@ $ mkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-audio.ogg
</para>
</refsect1>
<refsect1 id="mkvmerge.track_ids">
<title>Track IDs</title>
<para>
Some of the options for &mkvmerge; need a track ID to specify which track they should be applied to. Those track IDs are printed by the
readers when demuxing the current input file, or if &mkvmerge; is called with the <link
linkend="mkvmerge.description.identify"><option>--identify</option></link> option. An example for such output:
</para>
<screen>
$ mkvmerge -i v.mkv
File 'v.mkv': container: &matroska;
Track ID 1: video (V_MS/VFW/FOURCC, DIV3)
Track ID 2: audio (A_MPEG/L3)
</screen>
<para>
Track IDs are assigned like this:
</para>
<itemizedlist>
<listitem>
<para>
<abbrev>AVI</abbrev> files: The video track has the ID 0. The audio tracks get IDs in ascending order starting at 1.
</para>
</listitem>
<listitem>
<para>
<abbrev>AAC</abbrev>, <abbrev>AC3</abbrev>, <abbrev>MP3</abbrev>, <abbrev>SRT</abbrev> and <abbrev>WAV</abbrev> files: The one 'track'
in that file gets the ID 0.
</para>
</listitem>
<listitem>
<para>
Ogg/<abbrev>OGM</abbrev> files: The track IDs are assigned in order the tracks are found in the file starting at 0.
</para>
</listitem>
<listitem>
<para>
&matroska; files: The track's ID is the track number as reported by &mkvinfo;. It is <emphasis>not</emphasis> the track UID.
</para>
</listitem>
</itemizedlist>
<para>
The special track ID '<constant>-1</constant>' is a wild card and applies the given switch to all tracks that are read from an input
file.
</para>
<para>
The options that use the track IDs are the ones whose description contains '<literal>TID</literal>'.
The following options use track IDs as well: <option>--atracks</option>,
<option>--vtracks</option>, <option>--stracks</option> and <option>--btracks</option>.
</para>
</refsect1>
<refsect1 id="mkvmerge.text_files_and_charsets">
<title>Text files and character set conversions</title>
<note>
<para>
This section applies to all programs in MkvToolNix even if it only mentions &mkvmerge;.
</para>
</note>
<para>
All text in a &matroska; file is encoded in UTF-8. This means that &mkvmerge; has to convert every text file it reads as well as every
text given on the command line from one character set into UTF-8. In return this also means that &mkvmerge;'s output has to be converted
back to that character set from UTF-8, e.g. if a non-English translation is used with <link
linkend="mkvmerge.description.ui_language"><option>--ui-language</option></link> or for text originating from a &matroska; file.
</para>
<para>
&mkvmerge; does this conversion automatically based on the presence of a <foreignphrase>byte order marker</foreignphrase> (short:
<abbrev>BOM</abbrev>) or the system's current locale. How the character set is inferred from the locale depends on the operating system
that &mkvmerge; is run on.
</para>
<para>
Text files that start with a BOM are already encoded in one representation of UTF. &mkvmerge; supports the following five modes: UTF-8,
UTF-16 Little and Big Endian, UTF-32 Little and Big Endian. Text files with a BOM are automatically converted to UTF-8. Any of the
parameters that would otherwise set the character set for such a file (e.g. <link
linkend="mkvmerge.description.sub_charset"><option>--sub-charset</option></link>) is silently ignored.
</para>
<para>
On Unix-like systems &mkvmerge; uses the <citerefentry><refentrytitle>setlocale</refentrytitle><manvolnum>3</manvolnum></citerefentry>
system call which in turn uses the environment variables <varname>LANG</varname>, <varname>LC_ALL</varname> and
<varname>LC_CYPE</varname>. The resulting character set is often one of UTF-8 or the ISO-8859-* family and is used for all text file
operations and for encoding strings on the command line and for output to the console.
</para>
<para>
On Windows there are actually two different character sets that &mkvmerge; uses due to the way the Windows shell program
<command>cmd.exe</command> is implemented. The first character set is determined by a call to the <function>GetCP()</function> system
call. This character set is used as the default for text file conversions and for all elements displayed by the <abbrev>GUI</abbrev>
programs in the MkvToolNix package. <command>cmd.exe</command> uses another character set which is determined by a call to the
<function>GetACP()</function> system call. This is the default character set for all strings read from the command line and for all
strings output to the console.
</para>
<para>
The following options exist that allow specifying the character sets:
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="mkvmerge.description.sub_charset"><option>--sub-charset</option></link> for text subtitle files and for text subtitle
tracks stored in container formats for which the character set cannot be determined unambiguously (e.g. Ogg files),
</para>
</listitem>
<listitem>
<para>
<link linkend="mkvmerge.description.chapter_charset"><option>--chapter-charset</option></link> for chapter text files and for chapters
and file titles stored in container formats for which the character set cannot be determined unambiguously (e.g. Ogg files for chapter
information, track and file titles etc; MP4 files for chapter information),
</para>
</listitem>
<listitem>
<para>
<link linkend="mkvmerge.description.command_line_charset"><option>--command-line-charset</option></link> for all strings on the command
line,
</para>
</listitem>
<listitem>
<para>
<link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link> for all strings written to the console or
to a file if the output has been redirected with the <link
linkend="mkvmerge.description.redirect_output"><option>--redirect-output</option></link> option.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="mkvmerge.subtitles">
<title>Subtitles</title>
<para>
There are several text subtitle formats that can be embedded into &matroska;. At the moment &mkvmerge; supports only text, VobSub and Kate
subtitle formats. Text subtitles must be recoded to UTF-8 so that they can be displayed correctly by a player (see the section about
<link linkend="mkvmerge.text_files_and_charsets"> text files and character sets</link> for an explanation how &mkvmerge; converts between
character sets). Kate subtitles are already encoded in UTF-8 and do not have to be re0encoded.
</para>
<para>
The following subtitle formats are supported at the moment:
</para>
<itemizedlist>
<listitem>
<para>
Subtitle Ripper (SRT) files
</para>
</listitem>
<listitem>
<para>
Substation Alpha (SSA) / Advanced Substation Alpha scripts (ASS)
</para>
</listitem>
<listitem>
<para>
OggKate streams
</para>
</listitem>
<listitem>
<para>
VobSub bitmap subtitle files
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="mkvmerge.file_linking">
<title>File linking</title>
@ -1396,6 +1606,413 @@ $ mkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-audio.ogg
</para>
</refsect1>
<refsect1 id="mkvmerge.default_values">
<title>Default values</title>
<para>
The &matroska; specification states that some elements have a default value. Usually an element is not written to the file if its value
is equal to its default value in order to save space. The elements that the user might miss in &mkvinfo;'s output are the
<parameter>language</parameter> and the <parameter>default track flag</parameter> elements. The default value for the
<parameter>language</parameter> is English ('<literal>eng</literal>'), and the default value for the <parameter>default track
flag</parameter> is <parameter>true</parameter>. Therefore if you used <option>--language 0:eng</option> for a track then it will not
show up in &mkvinfo;'s output.
</para>
</refsect1>
<refsect1 id="mkvmerge.attachments">
<title>Attachments</title>
<para>
Maybe you also want to keep some photos along with your &matroska; file, or you're using <abbrev>SSA</abbrev> subtitles and need a
special <productname>TrueType</productname> font that's really rare. In these cases you can attach those files to the &matroska;
file. They will not be just appended to the file but embedded in it. A player can then show those files (the 'photos' case) or use them
to render the subtitles (the '<productname>TrueType</productname> fonts' case).
</para>
<para>
Here's an example how to attach a photo and a <productname>TrueType</productname> font to the output file:
</para>
<screen>
$ mkvmerge -o output.mkv -A video.avi sound.ogg --attachment-description "Me and the band behind the stage in a small get-together" --attachment-mime-type image/jpeg --attach-file me_and_the_band.jpg --attachment-description "The real rare and unbelievably good looking font" --attachment-type application/octet-stream --attach-file really_cool_font.ttf
</screen>
<para>
If a &matroska; containing attachments file is used as an input file then &mkvmerge; will copy the attachments into the new file. The
selection which attachments are copied and which are not can be changed with the options <link
linkend="mkvmerge.description.attachments"><option>--attachments</option></link> and <link
linkend="mkvmerge.description.no_attachments"><option>--no-attachments</option></link>.
</para>
</refsect1>
<refsect1 id="mkvmerge.chapters">
<title>Chapters</title>
<para>
The &matroska; chapter system is more powerful than the old known system used by <abbrev>OGM</abbrev> files. The full specifications can
be found at <ulink url="http://www.matroska.org/">the &matroska; website</ulink>.
</para>
<para>
&mkvmerge; supports two kinds of chapter files as its input. The first format, called '<foreignphrase>simple chapter
format</foreignphrase>', is the same format that the <abbrev>OGM</abbrev> tools expect. The second format is a &xml; based
chapter format which supports all of &matroska;'s chapter functionality.
</para>
<refsect2>
<title>The simple chapter format</title>
<para>
This formmat consists of pairs of lines that start with '<literal>CHAPTERxx=</literal>' and '<literal>CHAPTERxxNAME=</literal>'
respectively. The first one contains the start timecode while the second one contains the title. Here's an example:
</para>
<screen>
CHAPTER01=00:00:00.000
CHAPTER01NAME=Intro
CHAPTER02=00:02:30.000
CHAPTER02NAME=Baby prepares to rock
CHAPTER03=00:02:42.300
CHAPTER03NAME=Baby rocks the house
</screen>
<para>
&mkvmerge; will transform every pair or lines into one &matroska; <classname>ChapterAtom</classname>. It does not set any
<classname>ChapterTrackNumber</classname> which means that the chapters all apply to all tracks in the file.
</para>
<para>
As this is a text file character set conversion may need to be done. See the section about <link
linkend="mkvmerge.text_files_and_charsets"> text files and character sets</link> for an explanation how &mkvmerge; converts between
character sets.
</para>
</refsect2>
<refsect2>
<title>The &xml; based chapter format</title>
<para>
The &xml; based chapter format looks like this example:
</para>
<screen>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt;
&lt;!DOCTYPE Chapters SYSTEM &quot;matroskachapters.dtd&quot;&gt;
&lt;Chapters&gt;
&lt;EditionEntry&gt;
&lt;ChapterAtom&gt;
&lt;ChapterTimeStart&gt;00:00:30.000&lt;/ChapterTimeStart&gt;
&lt;ChapterTimeEnd&gt;00:01:20.000&lt;/ChapterTimeEnd&gt;
&lt;ChapterDisplay&gt;
&lt;ChapterString&gt;A short chapter&lt;/ChapterString&gt;
&lt;ChapterLanguage&gt;eng&lt;/ChapterLanguage&gt;
&lt;/ChapterDisplay&gt;
&lt;ChapterAtom&gt;
&lt;ChapterTimeStart&gt;00:00:46.000&lt;/ChapterTimeStart&gt;
&lt;ChapterTimeEnd&gt;00:01:10.000&lt;/ChapterTimeEnd&gt;
&lt;ChapterDisplay&gt;
&lt;ChapterString&gt;A part of that short chapter&lt;/ChapterString&gt;
&lt;ChapterLanguage&gt;eng&lt;/ChapterLanguage&gt;
&lt;/ChapterDisplay&gt;
&lt;/ChapterAtom&gt;
&lt;/ChapterAtom&gt;
&lt;/EditionEntry&gt;
&lt;/Chapters&gt;
</screen>
<para>
With this format three things are possible that are not possible with the simple chapter format:
</para>
<orderedlist>
<listitem><para>The timestamp for the end of the chapter can be set,</para></listitem>
<listitem><para>chapters can be nested,</para></listitem>
<listitem><para>the language and country can be set.</para></listitem>
</orderedlist>
<para>
The mkvtoolnix distribution contains some sample files in the <filename>doc</filename> subdirectory which can be used as a basis.
</para>
</refsect2>
<refsect2>
<title>General notes</title>
<para>
When splitting files &mkvmerge; will correctly adjust the chapters as well. This means that each file only includes the chapter entries
that apply to it, and that the timecodes will be offset to match the new timecodes of each output file.
</para>
<para>
&mkvmerge; is able to copy chapters from &matroska; source files unless this is explicitly disabled with the <link
linkend="mkvmerge.description.no_chapters"><option>--no-chapters</option></link> option. The chapters from all sources (&matroska; files,
Ogg files, <abbrev>MP4</abbrev> files, chapter text files) are usually not merged but end up in separate
<classname>ChapterEditions</classname>. Only if chapters are read from several &matroska; or &xml; files that share the
same edition UIDs will chapters be merged into a single <classname>ChapterEdition</classname>. If such a merge is desired in other
situations as well then the user has to extract the chapters from all sources with &mkvextract; first, merge the &xml;
files manually and mux them afterwards.
</para>
</refsect2>
</refsect1>
<refsect1 id="mkvmerge.tags">
<title>Tags</title>
<refsect2>
<title>Introduction</title>
<para>
&matroska; supports an extensive set of tags that is deprecated and a new, simpler system like it is is used in most other containers:
<parameter>KEY=VALUE</parameter>. However, in &matroska; these tags can also be nested, and both the <parameter>KEY</parameter> and the
<parameter>VALUE</parameter> are elements of their own. The example file <filename>example-tags-2.xml</filename> shows how to use this
new system.
</para>
</refsect2>
<refsect2>
<title>Scope of the tags</title>
<para>
&matroska; tags do not automatically apply to the complete file. They can, but they also may apply to different parts of the file: to one
or more tracks, to one or more chapters, or even to a combination of both. The <ulink
url="http://matroska.org/technical/specs/index.html">the &matroska; specification</ulink> gives more details about this fact.
</para>
<para>
One important fact is that tags are linked to tracks or chapters with the <classname>Targets</classname> &matroska; tag element, and
that the UIDs used for this linking are <emphasis>not</emphasis> the track IDs &mkvmerge; uses everywhere. Instead the numbers used are
the UIDs which &mkvmerge; calculates automatically (if the track is taken from a file format other than &matroska;) or which are copied
from the source file if the track's source file is a &matroska; file. Therefore it is difficult to know which UIDs to use in the tag
file before the file is handed over to &mkvmerge;.
</para>
<para>
&mkvmerge; knows two options with which you can add tags to &matroska; files: The <link
linkend="mkvmerge.description.global_tags"><option>--global-tags</option></link> and the <link
linkend="mkvmerge.description.tags"><option>--tags</option></link> options. The difference is that the former option, <link
linkend="mkvmerge.description.global_tags"><option>--global-tags</option></link>, will make the tags apply to the complete file by
removing any of those <classname>Targets</classname> elements mentioned above. The latter option, <link
linkend="mkvmerge.description.tags"><option>--tags</option></link>, automatically inserts the UID that &mkvmerge; generates for the tag
specified with the <parameter>TID</parameter> part of the <link linkend="mkvmerge.description.tags"><option>--tags</option></link>
option.
</para>
</refsect2>
<refsect2>
<title>Example</title>
<para>
Let's say that you want to add tags to a video track read from an <abbrev>AVI</abbrev>. <command>mkvmerge --identify file.avi</command>
tells you that the video track's ID (do not mix this ID with the UID!) is 0. So you create your tag file, leave out all
<classname>Targets</classname> elements and call &mkvmerge;:
</para>
<screen>
$ mkvmerge -o file.mkv --tags 0:tags.xml file.avi
</screen>
</refsect2>
<refsect2>
<title>Tag file format</title>
<para>
&mkvmerge; supports a &xml; based tag file format. The format is very closely modeled after <ulink
url="http://matroska.org/technical/specs/index.html">the &matroska; specification</ulink>. Both the binary and the source distributions
of MkvToolNix come with a sample file called <filename>example-tags-2.xml</filename> which simply lists all known tags and which can be
used as a basis for real life tag files.
</para>
<para>
The basics are:
</para>
<itemizedlist>
<listitem><para>The outermost element must be <classname>&lt;Tags&gt;</classname>.</para></listitem>
<listitem>
<para>One logical tag is contained inside one pair of <classname>&lt;Tag&gt;</classname> &xml; tags.</para>
</listitem>
<listitem><para>White spaces directly before and after tag contents are ignored.</para></listitem>
</itemizedlist>
</refsect2>
<refsect2>
<title>Data types</title>
<para>
The new &matroska; tagging system only knows two data types, a UTF-8 string and a binary type. The first is used for the tag's name and
the <classname>&lt;String&gt;</classname> element while the binary type is used for the <classname>&lt;Binary&gt;</classname> element.
</para>
<para>
As binary data itself would not fit into a &xml; file &mkvmerge; supports two other methods of storing binary data. If the contents of a
&xml; tag starts with '<literal>@</literal>' then the following text is treated as a file name. The corresponding file's content is
copied into the &matroska; element.
</para>
<para>
Otherwise the data is expected to be <foreignphrase>Base64</foreignphrase> encoded. This is an encoding that transforms binary data into
a limited set of <abbrev>ASCII</abbrev> characters and is used e.g. in email programs. &mkvextract; will output
<foreignphrase>Base64</foreignphrase> encoded data for binary elements.
</para>
<para>
The deprecated tagging system knows some more data types which can be found in the official &matroska; tag specs. As &mkvmerge; does not
support this system anymore these types aren't described here.
</para>
</refsect2>
</refsect1>
<refsect1 id="mkvmerge.file_layout">
<title>&matroska; file layout</title>
<para>
The &matroska; file layout is quite flexible. &mkvmerge; will render a file in a predefined way. The resulting file looks like this:
</para>
<para>
[EBML head] [segment {meta seek #1} {attachments} {chapters} [segment information] [track information] [cluster 1] {cluster 2} ...
{cluster n} {cues} {meta seek #2} {tags}]
</para>
<para>
The elements in curly braces are optional and depend on the contents and options used. A couple of notes:
</para>
<itemizedlist>
<listitem>
<para>
meta seek #1 includes only a small number of level 1 elements, and only if they actually exist: attachments, chapters, cues, tags, meta
seek #2. Older versions of &mkvmerge; used to put the clusters into this meta seek element as well. Therefore some imprecise guessing
was necessary to reserve enough space. It often failed. Now only the clusters are stored in meta seek #2, and meta seek #1 refers to
the meta seek element #2.
</para>
</listitem>
<listitem>
<para>Attachment, chapter and tag elements are only present if they were added.</para>
</listitem>
</itemizedlist>
<para>
The shortest possible Matroska file would look like this:
</para>
<para>
[EBML head] [segment [segment information] [track information] [cluster 1]]
</para>
<para>
This might be the case for audio-only files.
</para>
</refsect1>
<refsect1 id="mkvmerge.external_timecode_files">
<title>External timecode files</title>
<para>
&mkvmerge; allows the user to chose the timecodes for a specific track himself. This can be used in order to create files with variable
frame rate video or include gaps in audio. A frame in this case is the unit that &mkvmerge; creates separately per &matroska; block. For
video this is exactly one frame, for audio this is one packet of the specific audio type. E.g. for <abbrev>AC3</abbrev> this would be a
packet containing <constant>1536</constant> samples.
</para>
<para>
Timecode files that are used when tracks are appended to each other must only be specified for the first part in a chain of tracks. For
example if you append two files, v1.avi and v2.avi, and want to use timecodes then your command line must look something like this:
</para>
<screen>
mkvmerge ... --timecodes 0:my_timecodes.txt v1.avi +v2.avi
</screen>
<para>
There are four formats that are recognized by &mkvmerge;. The first line always contains the version number. Empty lines, lines
containing only whitespace and lines beginning with '<literal>#</literal>' are ignored.
</para>
<refsect2>
<title>Timecode file format v1</title>
<para>
This format starts with the version line. The second line declares the default number of frames per second. All following lines contain
three numbers separated by commas: the start frame (<constant>0</constant> is the first frame), the end frame and the number of frames
in this range. The <abbrev>FPS</abbrev> is a floating point number with the dot '<literal>.</literal>' as the decimal point. The ranges
can contain gaps for which the default <abbrev>FPS</abbrev> is used. An example:
</para>
<screen>
# timecode format v1
assume 27.930
800,1000,25
1500,1700,30
</screen>
</refsect2>
<refsect2>
<title>Timecode file format v2</title>
<para>
In this format each line contains a timecode for the corresponding frame. This timecode must be given in millisecond precision. It can
be a floating point number, but it doesn't have to be. You <emphasis>have to</emphasis> give at least as many timecode lines as there
are frames in the track. The timecodes in this file must be sorted. Example for 25fps:
</para>
<screen>
# timecode format v2
0
40
80
</screen>
</refsect2>
<refsect2>
<title>Timecode file format v3</title>
<para>
In this format each line contains a duration in seconds followed by an optional number of frames per second. Both can be floating point
numbers. If the number of frames per second is not present the default one is used. For audio you should let the codec calculate the
frame timecodes itself. For that you should be using <constant>0.0</constant> as the number of frames per second. You can also create
gaps in the stream by using the '<literal>gap</literal>' keyword followed by the duration of the gap. Example for an audio file:
</para>
<screen>
# timecode format v3
assume 0.0
25.325
7.530,38.236
gap, 10.050
2.000,38.236
</screen>
</refsect2>
<refsect2>
<title>Timecode file format v4</title>
<para>
This format is identical to the v2 format. The only difference is that the timecodes do not have to be sorted. This format should
almost never be used.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Exit codes</title>
<para>
&mkvmerge; exits with one of three exit codes:
</para>
<itemizedlist>
<listitem>
<para>
<constant>0</constant> -- This exit codes means that muxing has completed successfully.
</para>
</listitem>
<listitem>
<para>
<constant>1</constant> -- In this case &mkvmerge; has output at least one warning, but muxing did continue. A warning is prefixed with
the text '<literal>Warning:</literal>'. Depending on the issues involved the resulting file might be ok or not. The user is urged to
check both the warning and the resulting file.
</para>
</listitem>
<listitem>
<para>
<constant>2</constant> -- This exit code is used after an error occured. &mkvmerge; aborts right after outputting the error message.
Error messages range from wrong command line arguments over read/write errors to broken files.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="mkvmerge.seealso">
<title>See also</title>
<para>