mirror of
https://gitlab.com/mbunkus/mkvtoolnix.git
synced 2024-12-25 04:11:44 +00:00
2031 lines
86 KiB
XML
2031 lines
86 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd"
|
|
[
|
|
<!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>">
|
|
<!ENTITY mkvextract "<citerefentry><refentrytitle>mkvextract</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
|
<!ENTITY mmg "<citerefentry><refentrytitle>mmg</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
|
|
|
<!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>
|
|
<firstname>Moritz</firstname>
|
|
<surname>Bunkus</surname>
|
|
<email>moritz@bunkus.org</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
<refmeta>
|
|
<refentrytitle>&product;</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="version">&version;</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>
|
|
|
|
<refnamediv>
|
|
<refname>&product;</refname>
|
|
<refpurpose>Merge multimedia streams into a &matroska; file</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv id="mkvmerge.synopsis">
|
|
<title>Synopsis</title>
|
|
<cmdsynopsis>
|
|
<command>mkvmerge</command>
|
|
<arg>global options</arg>
|
|
<arg choice="req">-o out</arg>
|
|
<arg>options1</arg>
|
|
<arg choice="req">file1</arg>
|
|
<arg>
|
|
<arg>options2</arg>
|
|
<arg choice="req">file2</arg>
|
|
</arg>
|
|
<arg>@optionsfile</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="mkvmerge.description">
|
|
<title>Description</title>
|
|
<para>
|
|
This program takes the input from several media files and joins their streams (all of them or just a selection) into
|
|
a &matroska; file; see <ulink url="http://www.matroska.org/">the &matroska; website</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
Global options:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-v</option>, <option>--verbose</option></term>
|
|
<listitem>
|
|
<para>Increase verbosity.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-q</option>, <option>--quiet</option></term>
|
|
<listitem>
|
|
<para>Suppress status output.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o</option>, <option>--out</option> <parameter>file-name</parameter></term>
|
|
<listitem>
|
|
<para>Write to the file <parameter>file-name</parameter>. If splitting is used then this parameter is treated a bit differently. See
|
|
the explanation for the <link linkend="mkvmerge.description.split"><option>--split</option></link> option for details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.title">
|
|
<term><option>--title</option> <parameter>title</parameter></term>
|
|
<listitem>
|
|
<para>Sets the general title for the output file, e.g. the movie name.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.tags">
|
|
<term><option>--tags</option> <parameter>file-name</parameter></term>
|
|
<listitem>
|
|
<para>Read global tags from the &xml; file <parameter>file-name</parameter>. See the section about tags below for
|
|
details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--default-language</option> <parameter>language-code</parameter></term>
|
|
<listitem>
|
|
<para>Sets the default language code that will be used for all tracks unless overwritten with the <link
|
|
linkend="mkvmerge.description.language"><option>--language</option></link> option. The default language code is
|
|
'<literal>und</literal>' for 'undefined'.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Chapter and tag handling: (global options)
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--chapter-language</option> <parameter>language-code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the ISO639-2 language code that is written for each chapter entry. Defaults to '<literal>eng</literal>'. See the section about
|
|
<link linkend="mkvmerge.chapters">chapters</link> below for details.
|
|
</para>
|
|
|
|
<para>
|
|
This option can be used both for simple chapter files and for source files that contain chapters but no information about the
|
|
chapters' language, e.g. MP4 and OGM files.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.chapter_charset">
|
|
<term><option>--chapter-charset</option> <parameter>character-set</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the character set that is used for the conversion to UTF-8 for simple chapter files. 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>
|
|
|
|
<para>
|
|
This switch does also apply to chapters that are copied from certain container types, e.g. Ogg/OGM and MP4 files.
|
|
See the section about chapters below for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--cue-chapter-name-format</option> <parameter>format</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
&mkvmerge; supports reading <abbrev>CUE</abbrev> sheets for audio files as the input for chapters. <abbrev>CUE</abbrev> sheets usually
|
|
contain the entries <varname>PERFORMER</varname> and <varname>TITLE</varname> for each index entry. &mkvmerge; uses these two strings
|
|
in order to construct the chapter name. With this option the format used for this name can be set.
|
|
</para>
|
|
|
|
<para>
|
|
If this option is not given then &mkvmerge; defaults to the format '<code>%p - %t</code>' (the performer, followed by a space, a dash,
|
|
another space and the title).
|
|
</para>
|
|
|
|
<para>
|
|
If the format is given then everything except the following meta characters is copied as-is, and the meta
|
|
characters are replaced like this:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><parameter>%p</parameter> is replaced by the current entry's <varname>PERFORMER</varname> string,</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><parameter>%t</parameter> is replaced by the current entry's <varname>TITLE</varname> string,</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><parameter>%n</parameter> is replaced by the current track number and</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><parameter>%N</parameter> is replaced by the current track number padded with a leading zero if
|
|
it is < 10.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--chapters</option> <parameter>file-name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Read chapter information from the file <parameter>file-name</parameter>. See the section about <link
|
|
linkend="mkvmerge.chapters">chapters</link> below for details.
|
|
</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>
|
|
General output control (advanced global options):
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--track-order</option> <parameter>FID1:TID1,FID2:TID2,...</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
This option changes the order in which the tracks for an input file are created. The argument is a comma separated list of pairs
|
|
IDs. Each pair contains first the file ID (<parameter>FID1</parameter>) which is simply the number of the file on the command line
|
|
starting at 0. The second is a track ID (<parameter>TID1</parameter>) from that file. If some track IDs are omitted then those tracks
|
|
are created after the ones given with this option have been created.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--cluster-length</option> <parameter>spec</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Limit the number of data blocks or the duration of data in each cluster. The <parameter>spec</parameter> parameter can either be a
|
|
number <parameter>n</parameter> without a unit or a number <parameter>d</parameter> postfixed with '<literal>ms</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
If no unit is used then &mkvmerge; will put at most <parameter>n</parameter> data blocks into each cluster. The maximum number of
|
|
blocks is 65535.
|
|
</para>
|
|
|
|
<para>
|
|
If the number <parameter>n</parameter> is postfixed with '<literal>ms</literal>' then &mkvmerge; puts at most <parameter>d</parameter>
|
|
milliseconds of data into each cluster. The minimum for <parameter>d</parameter> is '<literal>100ms</literal>', and the maximum is
|
|
'<literal>32000ms</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
&mkvmerge; defaults to putting at most 65535 data blocks and 2000ms of data into a cluster.
|
|
</para>
|
|
|
|
<para>
|
|
Programs trying to find a certain frame can only seek directly to a cluster and have to read the whole cluster afterwards. Therefore
|
|
creating larger clusters may lead to imprecise or slow seeking.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.no_cues">
|
|
<term><option>--no-cues</option></term>
|
|
<listitem>
|
|
<para>
|
|
Tells &mkvmerge; not to create and write the cue data which can be compared to an index in an AVI. &matroska; files can be played back
|
|
without the cue data, but seeking will probably be imprecise and slower. Use this only if you're really desperate for space or for
|
|
testing purposes. See also option <link linkend="mkvmerge.description.cues"><option>--cues</option></link> which can be specified for
|
|
each input file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--no-clusters-in-meta-seek</option></term>
|
|
<listitem>
|
|
<para>
|
|
Tells &mkvmerge; not to create a meta seek element at the end of the file containing all clusters. See also the section about the
|
|
<link linkend="mkvmerge.file_layout">&matroska; file layout</link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--disable-lacing</option></term>
|
|
<listitem>
|
|
<para>
|
|
Disables lacing for all tracks. This will increase the file's size, especially if there are many audio tracks. This option is not
|
|
intended for everyday use.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--enable-durations</option></term>
|
|
<listitem>
|
|
<para>
|
|
Write durations for all blocks. This will increase file size and does not offer any additional value for players at the moment.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--timecode-scale</option> <parameter>factor</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Forces the timecode scale factor to <parameter>factor</parameter>. Valid values are in the range
|
|
<constant>1000</constant>..<constant>10000000</constant> or the special value <constant>-1</constant>.
|
|
</para>
|
|
|
|
<para>
|
|
Normally &mkvmerge; will use a value of <constant>1000000</constant> which means that timecodes and durations will have a precision of
|
|
1ms. For files that will not contain a video track but at least one audio track &mkvmerge; will automatically chose a timecode scale
|
|
factor so that all timecodes and durations have a precision of one audio sample. This causes bigger overhead but allows precise
|
|
seeking and extraction.
|
|
</para>
|
|
|
|
<para>
|
|
If the special value <constant>-1</constant> is used then &mkvmerge; will use sample precision even if a video track is present.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
File splitting, linking and appending (more global options):
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvmerge.description.split">
|
|
<term><option>--split</option> <parameter>specification</parameter></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Splits the output file after a given size or a given time. Please note that tracks can only be split right before a key frame. Due
|
|
to buffering &mkvmerge; will split right before the next key frame after the split point has been reached. Therefore the split point
|
|
may be a bit off from what the user has specified.
|
|
</para>
|
|
|
|
<para>
|
|
At the moment &mkvmerge; supports three different modes.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Splitting by size.
|
|
</para>
|
|
|
|
<para>
|
|
Syntax: <option>--split</option> <optional>size:</optional><parameter>d</parameter><optional>k|m|g</optional>
|
|
</para>
|
|
|
|
<para>
|
|
Examples: <code>--split size:700m</code> or <code>--split 150000000</code>
|
|
</para>
|
|
|
|
<para>
|
|
The parameter <parameter>d</parameter> may end with '<literal>k</literal>', '<literal>m</literal>' or '<literal>g</literal>' to
|
|
indicate that the size is in KB, MB or GB respectively. Otherwise a size in Bytes is assumed. After the current output file has
|
|
reached this size limit a new one will be started.
|
|
</para>
|
|
|
|
<para>
|
|
The '<literal>size:</literal>' prefix may be omitted for compatibility reasons.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Splitting after a duration.
|
|
</para>
|
|
|
|
<para>
|
|
Syntax: <option>--split</option> <optional>duration:</optional><parameter>HH:MM:SS.nnnnnnnnn</parameter>|<parameter>d</parameter>s
|
|
</para>
|
|
|
|
<para>
|
|
Examples: <code>--split duration:00:60:00.000</code> or <code>--split 3600s</code>
|
|
</para>
|
|
|
|
<para>
|
|
The paramter must either have the form <parameter>HH:MM:SS.nnnnnnnnn</parameter> for specifying the duration in up to nano-second
|
|
precision or be a number <parameter>d</parameter> followed by the letter '<literal>s</literal>' for the duration in
|
|
seconds. <parameter>HH</parameter> is the number of hours, <parameter>MM</parameter> the number of minutes,
|
|
<parameter>SS</parameter> the number of seconds and <parameter>nnnnnnnnn</parameter> the number of nanoseconds. Both the number of
|
|
hours and the number of nanoseconds can be omitted. There can be up to nine digits after the decimal point. After the duration of
|
|
the contents in the current output has reached this limit a new output file will be started.
|
|
</para>
|
|
|
|
<para>
|
|
The '<literal>duration:</literal>' prefix may be omitted for compatibility reasons.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Splitting after specific timecodes.
|
|
</para>
|
|
|
|
<para>
|
|
Syntax: <option>--split</option> timecodes:<parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional>
|
|
</para>
|
|
|
|
<para>
|
|
Example: <code>--split timecodes:00:45:00.000,01:20:00.250,6300s</code>
|
|
</para>
|
|
|
|
<para>
|
|
The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>c</parameter> etc must all have the same format as the
|
|
ones used for the duration (see above). The list of timecodes is separated by commas. After the input stream has reached the
|
|
current split point's timecode a new file is created. Then the next split point given in this list is used.
|
|
</para>
|
|
|
|
<para>
|
|
The '<literal>timecodes:</literal>' prefix must not be omitted.
|
|
</para>
|
|
|
|
<para>
|
|
For this splitting mode the output filename is treated differently than for the normal operation. It may contain a
|
|
<function>printf</function> like expression '<literal>%d</literal>' including an optional field width,
|
|
e.g. '<literal>%02d</literal>'. If it does then the current file number will be formatted appropriately and inserted at that point
|
|
in the filename. If there is no such pattern then a pattern of '<literal>-%03d</literal>' is assumed right before the file's
|
|
extension: '<literal>-o output.mkv</literal>' would result in '<literal>output-001.mkv</literal>' and so on. If there's no extension
|
|
then '<literal>-%03d</literal>' will be appended to the name.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.link">
|
|
<term><option>--link</option></term>
|
|
<listitem>
|
|
<para>
|
|
Link files to one another when splitting the output file. See the section on <link linkend="mkvmerge.file_linking">file linking</link>
|
|
below for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--link-to-previous</option> <parameter>segment-UID</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Links the first output file to the segment with the segment UID given by the <parameter>segment-UID</parameter> parameter. See the
|
|
section on <link linkend="mkvmerge.file_linking">file linking</link> below for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--link-to-next</option> <parameter>segment-UID</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Links the last output file to the segment with the segment UID given by the <parameter>segment-UID</parameter> parameter. See the
|
|
section on <link linkend="mkvmerge.file_linking">file linking</link> below for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--append-mode</option> <parameter>mode</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Determines how timecodes are calculated when appending files. The parameter <parameter>mode</parameter> can have two values:
|
|
'<literal>file</literal>' which is also the default and '<literal>track</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
When mkvmerge appends a track (called '<literal>track2_1</literal>' from now on) from a second file (called
|
|
'<literal>file2</literal>') to a track (called '<literal>track1_1</literal>') from the first file (called '<literal>file1</literal>')
|
|
then it has to offset all timecodes for '<literal>track2_1</literal>' by an amount. For '<literal>file</literal>' mode this amount is
|
|
the highest timecode encountered in '<literal>file1</literal>' even if that timecode was from a different track than
|
|
'<literal>track1_1</literal>'. In track mode the offset is the highest timecode of '<literal>track1_1</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
Unfortunately mkvmerge cannot detect which mode to use reliably. Therefore it defaults to '<literal>file</literal>'
|
|
mode. '<literal>file</literal>' mode usually works better for files that have been created independently of each other; e.g. when
|
|
appending <abbrev>AVI</abbrev> or <abbrev>MP4</abbrev> files. '<literal>track</literal>' mode may work better for sources that are
|
|
essentially just parts of one big file, e.g. for <abbrev>VOB</abbrev> and <abbrev>EVO</abbrev> files.
|
|
</para>
|
|
|
|
<para>
|
|
Subtitle tracks are always treated as if '<literal>file</literal>' mode were active even if '<literal>track</literal>' mode actually
|
|
is.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--append-to</option> <parameter>SFID1:STID1:DFID1:DTID1<optional>,...</optional></parameter></term>
|
|
<listitem>
|
|
<para>
|
|
This option controls to which track another track is appended. Each spec contains four IDs: a file ID, a track ID, a second file ID
|
|
and a second track ID. The first pair, "source file ID" and "source track ID", identifies the track that is to be appended. The
|
|
second pair, "destination file ID" and "destination track ID", identifies the track the first one is appended to.
|
|
</para>
|
|
|
|
<para>
|
|
If this option has been omitted then a standard mapping is used. This standard mapping appends each track from the current file to a
|
|
track from the previous file with the same track ID. This allows for easy appending if a movie has been split into two parts and both
|
|
file have the same number of tracks and track IDs with the command <command>mkvmerge -o output.mkv part1.mkv +part2.mkv</command>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Attachment support (more global options):
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvmerge.description.attachment_description">
|
|
<term><option>--attachment-description</option> <parameter>description</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Plain text description of the following attachment. Applies to the next <link
|
|
linkend="mkvmerge.description.attach_file"><option>--attach-file</option></link> or <option>--attach-file-once</option> option.
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--attachment-mime-type</option> <parameter>MIME type</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
<abbrev >MIME</abbrev> type of the following attachment. Applies to the next <link
|
|
linkend="mkvmerge.description.attach_file"><option>--attach-file</option></link> or <link
|
|
linkend="mkvmerge.description.attach_file"><option>--attach-file-once</option></link> option. A list of officially recognized
|
|
<abbrev>MIME</abbrev> types can be found e.g. at <ulink url="http://www.iana.org/assignments/media-types/">the IANA
|
|
homepage</ulink>. The <abbrev>MIME</abbrev> type is mandatory for an attachment.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--attachment-name</option> <parameter>name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the name that will be stored in the output file for this attachment. If this option is not given then the name will be derived
|
|
from the file name of the attachment as given with the <link
|
|
linkend="mkvmerge.description.attach_file"><option>--attach-file</option></link> or the <link
|
|
linkend="mkvmerge.description.attach_file"><option>--attach-file-once</option></link> option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.attach_file">
|
|
<term>
|
|
<option>--attach-file</option> <parameter>file-name</parameter>,
|
|
<option>--attach-file-once</option> <parameter>file-name</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Creates a file attachment inside the &matroska; file. The <abbrev>MIME</abbrev> type must have been set before this option can used. The
|
|
difference between the two forms is that during splitting the files attached with <option>--attach-file</option> are attached to all
|
|
output files while the ones attached with <option>--attach-file-once</option> are only attached to the first file created. If
|
|
splitting is not used then both do the same.
|
|
</para>
|
|
|
|
<para>
|
|
&mkvextract; can be used to extract attached files from a &matroska; file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Options that can be used for each input file:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-a</option>, <option>--audio-tracks</option> <parameter>n,m,...</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Copy the audio tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with the
|
|
<link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see
|
|
section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all audio tracks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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
|
|
<link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see
|
|
section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all video tracks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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
|
|
the <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see
|
|
section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all subtitle tracks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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
|
|
the <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see
|
|
section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all button tracks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--track-tags</option> <parameter>n,m,...</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Copy the tags for tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with
|
|
the <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch (see section <link
|
|
linkend="mkvmerge.track_ids">track IDs</link>). They're not simply the track numbers. Default: copy tags for all tracks.
|
|
</para>
|
|
</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>
|
|
<para>
|
|
Don't copy any audio track from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-D</option>, <option>--no-video</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't copy any video track from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-S</option>, <option>--no-subtitles</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't copy any subtitle track from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-B</option>, <option>--no-buttons</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't copy any button track from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-T</option>, <option>--no-track-tags</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't copy any track specific tags from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.no_chapters">
|
|
<term><option>--no-chapters</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't copy chapters from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.no_attachments">
|
|
<term><option>-M</option>, <option>--no-attachments</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't copy attachments from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--no-global-tags</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't copy global tags from this file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--chapter-charset</option> <parameter>character-set</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the charset that is used for the conversion to UTF-8 for chapter information contained in the source file. 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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--chapter-language</option> <parameter>language-code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the ISO639-2 language code that is written for each chapter entry. This option can be used for source files that contain
|
|
chapters but no information about the chapters' languages, e.g. for MP4 and OGM files.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-y</option>, <option>--sync</option> <parameter>TID:d<optional>,o<optional>/p</optional></optional></parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Adjust the timecodes of the track with the id <parameter>TID</parameter> by <parameter>d</parameter> ms. The track IDs are the same as
|
|
the ones given with <link linkend="mkvmerge.description.identify"><option>--identify</option></link> (see section <link
|
|
linkend="mkvmerge.track_ids">track IDs</link>).
|
|
</para>
|
|
|
|
<para>
|
|
<parameter>o</parameter>/<parameter>p</parameter>: adjust the timestamps by <parameter>o</parameter>/<parameter>p</parameter> to fix
|
|
linear drifts. <parameter>p</parameter> defaults to 1 if omitted. Both <parameter>o</parameter> and <parameter>p</parameter> can be
|
|
floating point numbers.
|
|
</para>
|
|
|
|
<para>
|
|
Defaults: no manual sync correction (which is the same as <parameter>d</parameter> = <constant>0</constant> and
|
|
<parameter>o</parameter>/<parameter>p</parameter> = <constant>1.0</constant>).
|
|
</para>
|
|
|
|
<para>
|
|
This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.cues">
|
|
<term><option>--cues</option> <parameter>TID:none|iframes|all</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Controls for which tracks cue (index) entries are created for the given track (see section <link linkend="mkvmerge.track_ids">track
|
|
IDs</link>). '<literal>none</literal>' inhibits the creation of cue entries. For '<literal>iframes</literal>' only blocks with
|
|
no backward or forward references ( = I frames in video tracks) are put into the cue sheet. '<literal>all</literal>' causes
|
|
&mkvmerge; to create cue entries for all blocks which will make the file very big.
|
|
</para>
|
|
|
|
<para>
|
|
The default is '<literal>iframes</literal>' for video tracks and '<literal>none</literal>' for all others. See also option <link
|
|
linkend="mkvmerge.description.no_cues"><option>--no-cues</option></link> which inhibits the creation of cue entries regardless of the
|
|
<option>--cues</option> options used.
|
|
</para>
|
|
|
|
<para>
|
|
This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--default-track</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the 'default' flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the optional argument
|
|
<parameter>bool</parameter> is not present. If the user does not explicitly select a track himself then the player should prefer the
|
|
track that has his 'default' flag set. Only one track of each kind (audio, video, subtitles, buttons) can have his 'default' flag set.
|
|
If the user wants no track to have the default track flag set then he has to set <parameter>bool</parameter> to <constant>0</constant>
|
|
for all tracks.
|
|
</para>
|
|
|
|
<para>
|
|
This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--blockadd</option> <parameter>TID:level</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Keep only the <classname>BlockAdditions</classname> up to the level <parameter>level</parameter> for the given track. The default is
|
|
to keep all levels. This option only affects certain kinds of codecs like WAVPACK4.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.track_name">
|
|
<term><option>--track-name</option> <parameter>TID:name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the track name for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) to
|
|
<parameter>name</parameter>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.language">
|
|
<term><option>--language</option> <parameter>TID:language</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the language for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>). Both ISO639-2 language codes
|
|
and ISO639-1 country codes are allowed. The country codes will be converted to language codes automatically. All languages including
|
|
their ISO639-2 codes can be listed with the <link
|
|
linkend="mkvmerge.description.list_languages"><option>--list-languages</option></link> option.
|
|
</para>
|
|
|
|
<para>
|
|
This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-t</option>, <option>--tags</option> <parameter>TID:file-name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Read tags for the track with the number <parameter>TID</parameter> from the file <parameter>file-name</parameter>. See the section
|
|
about <link linkend="mkvmerge.tags">tags</link> below for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--aac-is-sbr</option> <parameter>TID<optional>:0|1</optional></parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Tells &mkvmerge; that the track with the ID <parameter>TID</parameter> is <abbrev>SBR AAC</abbrev> (also known as
|
|
<abbrev>HE-AAC</abbrev> or <abbrev>AAC+</abbrev>). This options is needed if a) the source file is an <abbrev>AAC</abbrev> file
|
|
(<emphasis>not</emphasis> for a &matroska; file) and b) the <abbrev>AAC</abbrev> file contains <abbrev>SBR AAC</abbrev> data. The
|
|
reason for this switch is that it is technically impossible to automatically tell normal <abbrev>AAC</abbrev> data from <abbrev>SBR
|
|
AAC</abbrev> data without decoding a complete <abbrev>AAC</abbrev> frame. As there are several patent issues with <abbrev>AAC</abbrev>
|
|
decoders &mkvmerge; will never contain this decoding stage. So for <abbrev>SBR AAC</abbrev> files this switch is mandatory. The
|
|
resulting file might not play back correctly or even not at all if the switch was omitted.
|
|
</para>
|
|
|
|
<para>
|
|
If the source file is a &matroska; file then the <classname>CodecID</classname> should be enough to detect <abbrev>SBR
|
|
AAC</abbrev>. However, if the <classname>CodecID</classname> is wrong then this switch can be used to correct that.
|
|
</para>
|
|
|
|
<para>
|
|
If mkvmerge wrongfully detects that an <abbrev>AAC</abbrev> file is <abbrev>SBR</abbrev> then you can add
|
|
'<literal>:0</literal>' to the track ID.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--timecodes</option> <parameter>TID:file-name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Read the timecodes to be used for the specific track ID from <parameter>file-name</parameter>. These timecodes forcefully override
|
|
the timecodes that &mkvmerge; normally calculates. Read the section about <link linkend="mkvmerge.external_timecode_files">external
|
|
timecode files</link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--default-duration</option> <parameter>TID:x</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Forces the default duration of a given track to the specified value. Also modifies the track's timecodes to match the default
|
|
duration. The argument <parameter>x</parameter> must be postfixed with '<literal>s</literal>', '<literal>ms</literal>',
|
|
'<literal>us</literal>', '<literal>ns</literal>' or '<literal>fps</literal>' to specify the default duration in seconds, milliseconds,
|
|
microseconds, nanoseconds or 'frames per second' respectively. The number <parameter>x</parameter> itself can be a floating point
|
|
number or a fraction.
|
|
</para>
|
|
|
|
<para>
|
|
If the default duration is not forced then mkvmerge will try to derive the track's default duration from the container and/or codec
|
|
used. One case in which this option is of use is when adding <foreignphrase>AVC/h.264</foreignphrase> elementary streams because
|
|
these do not contain information about their number of frames or a default duration for each frame. For such files &mkvmerge; will
|
|
assume a default duration of '<literal>25fps</literal>' unless overridden.
|
|
</para>
|
|
|
|
<para>
|
|
This option can also be used to change the <abbrev>FPS</abbrev> of video tracks without having to use an external timecode file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--nalu-size-length</option> <parameter>TID:n</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Forces the <abbrev>NALU</abbrev> size length to <parameter>n</parameter> bytes. This parameter is only used if the
|
|
<foreignphrase>AVC/h.264</foreignphrase> elementary stream packetizer is used. If left out it defaults to 4 bytes, but there are
|
|
files that contain frames or slices that are a4ll smaller than 65536 bytes. For such files you can use this parameter and decrease
|
|
the size to 2.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Options that only apply to video tracks:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-f</option>, <option>--fourcc</option> <parameter>TID:FourCC</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Forces the <classname>FourCC</classname> to the specified value. Works only for video tracks in the '<foreignphrase>MS compatibility
|
|
mode</foreignphrase>'.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.display_dimensions">
|
|
<term><option>--display-dimensions</option> <parameter>TID:widthxheight</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
&matroska; files contain two values that set the display properties that a player should scale the image on playback to: display width
|
|
and display height. These values can be set with this option, e.g. '<literal>1:640x480</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
Another way to specify the values is to use the <link
|
|
linkend="mkvmerge.description.aspect_ratio"><option>--aspect-ratio</option></link> or the <link
|
|
linkend="mkvmerge.description.aspect_ratio_factor"><option>--aspect-ratio-factor</option></link> option (see below). These options
|
|
are mutually exclusive.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.aspect_ratio">
|
|
<term><option>--aspect-ratio</option> <parameter>TID:ratio|width/height</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
&matroska; files contain two values that set the display properties that a player should scale the image on playback to: display width
|
|
and display height. With this option &mkvmerge; will automatically calculate the display width and display height based on the
|
|
image's original width and height and the aspect ratio given with this option. The ratio can be given either as a floating point
|
|
number <parameter>ratio</parameter> or as a fraction '<parameter>width</parameter>/<parameter>height</parameter>',
|
|
e.g. '<literal>16/9</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
Another way to specify the values is to use the <link
|
|
linkend="mkvmerge.description.aspect_ratio_factor"><option>--aspect-ratio-factor</option></link> or <link
|
|
linkend="mkvmerge.description.display_dimensions"><option>--display-dimensions</option></link> options (see above and below). These
|
|
options are mutually exclusive.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.aspect_ratio_factor">
|
|
<term><option>--aspect-ratio-factor</option> <parameter>TID:factor|n/d</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Another way to set the aspect ratio is to specify a <parameter>factor</parameter>. The original aspect ratio is first multiplied with
|
|
this <parameter>factor</parameter> and used as the target aspect ratio afterwards.
|
|
</para>
|
|
|
|
<para>
|
|
Another way to specify the values is to use the <link
|
|
linkend="mkvmerge.description.aspect_ratio"><option>--aspect-ratio</option></link> or <link
|
|
linkend="mkvmerge.description.display_dimensions"><option>--display-dimensions</option></link> options (see above). These options are
|
|
mutually exclusive.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--cropping</option> <parameter>TID:left,top,right,bottom</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the pixel cropping parameters of a video track to the given values.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--stereo-mode</option> <parameter>TID:n|keyword</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the stereo mode for the video track with the track ID <parameter>TID</parameter>. The mode can either be a number
|
|
<parameter>n</parameter> between <constant>0</constant> and <constant>3</constant> or one of the keywords '<literal>none</literal>'
|
|
(same as <parameter>n</parameter>=<constant>0</constant>), '<literal>right</literal>' (same as
|
|
<parameter>n</parameter>=<constant>1</constant>), '<literal>left</literal>' (same as <parameter>n</parameter>=<constant>2</constant>)
|
|
or '<literal>both</literal>' (same as <parameter>n</parameter>=<constant>3</constant>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.compression">
|
|
<term><option>--compression</option> <parameter>TID:method</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Selects the compression method to be used for the VobSub track. Note that the player also has to support this method. Valid values are
|
|
'<literal>none</literal>', '<literal>zlib</literal>', '<literal>lzo</literal>'/'<literal>lxo1x</literal>',
|
|
'<literal>bz2</literal>'/'<literal>bzlib</literal>' and '<literal>mpeg4_p2</literal>'/'<literal>mpeg4p2</literal>'. The values
|
|
'<literal>lzo</literal>'/'<literal>lxo1x</literal>' and '<literal>bz2</literal>'/'<literal>bzlib</literal>' are only available if
|
|
&mkvmerge; has been compiled with support for the <productname>liblzo</productname> respectively <productname>bzlib</productname>
|
|
compression libraries.
|
|
</para>
|
|
|
|
<para>
|
|
The compression method '<literal>mpeg4_p2</literal>'/'<literal>mpeg4p2</literal>' is a special compression method called
|
|
'<foreignphrase>header removal</foreignphrase>' that is only available for MPEG4 part 2 video tracks. The other methods are general
|
|
compression methods that can be used with any type of track.
|
|
</para>
|
|
|
|
<para>
|
|
The default is '<literal>zlib</literal>' compression. This compression method is also the one that most if not all playback
|
|
applications support. Support for other compression methods other than '<literal>none</literal>' is not assured.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Options that only apply to text subtitle tracks:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvmerge.description.sub_charset">
|
|
<term><option>--sub-charset</option> <parameter>TID:character-set</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the character set for the conversion to UTF-8 for UTF-8 subtitles for the given track ID. If not specified the charset will be
|
|
derived from the current locale settings. Note that a charset is not needed for subtitles read from &matroska; files or from Kate
|
|
streams, as these are always stored in UTF-8. 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>
|
|
|
|
<para>
|
|
This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Other options:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvmerge.description.identify">
|
|
<term><option>-i</option>, <option>--identify</option> <parameter>file-name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Will let &mkvmerge; probe the single file and report its type, the tracks contained in the file and their track IDs. If this option is
|
|
used then the only other option allowed is the filename.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-l</option>, <option>--list-types</option></term>
|
|
<listitem>
|
|
<para>
|
|
Lists supported input file types.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.list_languages">
|
|
<term><option>--list-languages</option></term>
|
|
<listitem>
|
|
<para>
|
|
Lists all languages and their ISO639-2 code which can be used with the <link
|
|
linkend="mkvmerge.description.language"><option>--language</option></link> option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--priority</option> <parameter>priority</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the process priority that &mkvmerge; runs with. Valid values are '<literal>lowest</literal>', '<literal>lower</literal>',
|
|
'<literal>normal</literal>', '<literal>higher</literal>' and '<literal>highest</literal>'. If nothing is given then
|
|
'<literal>normal</literal>' is used. On Unix like systems &mkvmerge; will use the
|
|
<citerefentry><refentrytitle>nice</refentrytitle><manvolnum>2</manvolnum></citerefentry> function. Therefore only the super user can
|
|
use '<literal>higher</literal>' and '<literal>highest</literal>'. On Windows all values are useable for every user.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.command_line_charset">
|
|
<term><option>--command-line-charset</option> <parameter>character-set</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the character set to convert strings given on the command line from. It defaults to the character set given by system's current
|
|
locale. This settings applies to arguments of the following options: <link
|
|
linkend="mkvmerge.description.title"><option>--title</option></link>, <link
|
|
linkend="mkvmerge.description.track_name"><option>--track-name</option></link> and <link
|
|
linkend="mkvmerge.description.attachment_description"><option>--attachment-description</option></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.output_charset">
|
|
<term><option>--output-charset</option> <parameter>character-set</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the character set to which strings are converted that are to be output. It defaults to the character set given by system's
|
|
current locale.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.redirect_output">
|
|
<term><option>-r</option>, <option>--redirect-output</option> <parameter>file-name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Writes all messages to the file <parameter>file-name</parameter> instead of to the console. While this can be done easily with output
|
|
redirection there are cases in which this option is needed: when the terminal reinterprets the output before writing it to a file.
|
|
The character set set with <link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link> is honored.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvmerge.description.ui_language">
|
|
<term><option>--ui-language</option> <parameter>code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Forces the translations for the language <parameter>code</parameter> to be used (e.g. '<literal>de_DE</literal>' for the German
|
|
translations). It is preferable to use the environment variables <varname>LANG</varname>, <varname>LC_MESSAGES</varname> and
|
|
<varname>LC_ALL</varname> though. Entering '<literal>list</literal>' as the <parameter>code</parameter> will cause &mkvmerge; to
|
|
output a list of available translations.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>@</option>options-file</term>
|
|
<listitem>
|
|
<para>
|
|
Reads additional command line arguments from the file <parameter>options-file</parameter>. Lines whose first non-whitespace character
|
|
is a hash mark ('<literal>#</literal>') are treated as comments and ignored. White spaces at the start and end of a line will be
|
|
stripped. Each line must contain exactly one option. There is no meta character escaping.
|
|
</para>
|
|
|
|
<para>
|
|
The command line '<command>mkvmerge -o "my file.mkv" -A "a movie.avi" sound.ogg</command>' could be converted into the following
|
|
option file:
|
|
</para>
|
|
|
|
<programlisting>
|
|
# Write to the file "my file.mkv".
|
|
-o
|
|
my file.mkv
|
|
# Only take the video from "a movie.avi".
|
|
-A
|
|
a movie.avi
|
|
sound.ogg
|
|
</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--capabilities</option></term>
|
|
<listitem>
|
|
<para>
|
|
Lists information about optional features that have been compiled in and exit. The first line output will be the version
|
|
information. All following lines contain exactly one word whose presence indicates that the feature has been compiled in. These
|
|
features are:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
'<literal>BZ2</literal>' -- the <productname>bzlib</productname> compression library. Affects the available compression methods for
|
|
the <link linkend="mkvmerge.description.compression"><option>--compression</option></link> option.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
'<literal>LZO</literal>' -- the <productname>lzo</productname> compression library. Affects the available compression methods for
|
|
the <link linkend="mkvmerge.description.compression"><option>--compression</option></link> option.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
'<literal>FLAC</literal>' -- reading raw <abbrev>FLAC</abbrev> files and handling <abbrev>FLAC</abbrev> tracks in other containers,
|
|
e.g. <productname>Ogg</productname> or &matroska;.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-h</option>, <option>--help</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show usage information and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-V</option>, <option>--version</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show version information and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvmerge.usage">
|
|
<title>Usage</title>
|
|
<para>
|
|
For each file the user can select which tracks &mkvmerge; should take. They are all put into the file specified with
|
|
<option>-o</option>. A list of known (and supported) source formats can be obtained with the <option>-l</option> option.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvmerge.examples">
|
|
<title>Examples</title>
|
|
<para>
|
|
Let's assume you have a file called MyMovie.avi and the audio track in a separate file, e.g. '<literal>MyMovie.wav</literal>'. First you
|
|
want to encode the audio to &oggvorbis;:
|
|
</para>
|
|
|
|
<screen>$ oggenc -q4 -oMyMovie.ogg MyMovie.wav</screen>
|
|
|
|
<para>
|
|
After a couple of minutes you can join video and audio:
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o MyMovie-with-sound.mkv MyMovie.avi MyMovie.ogg</screen>
|
|
|
|
<para>
|
|
If your <abbrev>AVI</abbrev> already contains an audio track then it will be copied as well (if &mkvmerge; supports the audio format). To
|
|
avoid that simply do
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o MyMovie-with-sound.mkv -A MyMovie.avi MyMovie.ogg</screen>
|
|
|
|
<para>
|
|
After some minutes of consideration you rip another audio track, e.g. the director's comments or another language to
|
|
'<literal>MyMovie-add-audio.wav</literal>'. Encode it again and join it up with the other file:
|
|
</para>
|
|
|
|
<screen>
|
|
$ oggenc -q4 -oMyMovie-add-audio.ogg MyMovie-add-audio.wav
|
|
$ mkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-audio.ogg
|
|
</screen>
|
|
|
|
<para>
|
|
The same result can be achieved with
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o MM-complete.mkv -A MyMovie.avi MyMovie.ogg MyMovie-add-audio.ogg</screen>
|
|
|
|
<para>
|
|
Now fire up <productname>mplayer</productname> and enjoy. If you have multiple audio tracks (or even video tracks) then you can tell
|
|
<productname>mplayer</productname> which track to play with the '<option>-vid</option>' and '<option>-aid</option>' options. These are
|
|
0-based and do not distinguish between video and audio.
|
|
</para>
|
|
|
|
<para>
|
|
If you need an audio track synchronized you can do that easily. First find out which track ID the Vorbis track has with
|
|
</para>
|
|
|
|
<screen>$ mkvmerge --identify outofsync.ogg</screen>
|
|
|
|
<para>
|
|
Now you can use that ID in the following command line:
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o goodsync.mkv -A source.avi -y 12345:200 outofsync.ogg</screen>
|
|
|
|
<para>
|
|
This would add 200ms of silence at the beginning of the audio track with the
|
|
ID <constant>12345</constant> taken from '<literal>outofsync.ogg</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
Some movies start synced correctly but slowly drift out of sync. For these kind of movies you can specify a delay factor that is applied
|
|
to all timestamps -- no data is added or removed. So if you make that factor too big or too small you'll get bad results. An example is
|
|
that an episode I transcoded was <constant>0.2</constant> seconds out of sync at the end of the movie which was
|
|
<constant>77340</constant> frames long. At <constant>29.97fps</constant> <constant>0.2</constant> seconds correspond to
|
|
approx. <constant>6</constant> frames. So I did
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o goodsync.mkv -y 23456:0,77346/77340 outofsync.mkv</screen>
|
|
|
|
<para>
|
|
The result was fine.
|
|
</para>
|
|
|
|
<para>
|
|
The sync options can also be used for subtitles in the same manner.
|
|
</para>
|
|
|
|
<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><manvolnum>1</manvolnum></citerefentry>'s sources in the
|
|
'<literal>contrib/subrip</literal>' directory. The general process is:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>extract a raw subtitle stream from the source:</para>
|
|
<screen>$ tccat -i /path/to/copied/dvd/ -T 1 -L | tcextract -x ps1 -t vob -a 0x20 | subtitle2pgm -o mymovie</screen>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>convert the resulting PGM images to text with gocr:</para>
|
|
<screen>$ pgm2txt mymovie</screen>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>spell-check the resulting text files:</para>
|
|
<screen>$ ispell -d american *txt</screen>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>convert the text files to a SRT file:</para>
|
|
<screen>$ srttool -s -w -i mymovie.srtx -o mymovie.srt</screen>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
The resulting file can be used as another input file for &mkvmerge;:
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o mymovie.mkv mymovie.avi mymovie.srt</screen>
|
|
|
|
<para>
|
|
If you want to specify the language for a given track then this is easily done. First find out the ISO639-2 code for your
|
|
language. &mkvmerge; can list all of those codes for you:
|
|
</para>
|
|
|
|
<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
|
|
language codes and that their track IDs are 2 and 3. This can be done with
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o with-lang-codes.mkv --language 2:ger --language 3:dut without-lang-codes.mkv</screen>
|
|
|
|
<para>
|
|
As you can see you can use the <link linkend="mkvmerge.description.language"><option>--language</option></link> switch multiple times.
|
|
</para>
|
|
|
|
<para>
|
|
Maybe you'd also like to have the player use the Dutch language as the default language. You also have extra subtitles, e.g. in English
|
|
and French, and want to have the player display the French ones by default. This can be done with
|
|
</para>
|
|
|
|
<screen>$ mkvmerge -o with-lang-codes.mkv --language 2:ger --language 3:dut --default-track 3 without-lang-codes.mkv --language 0:eng english.srt --default-track 0 --language 0:fre french.srt</screen>
|
|
|
|
<para>
|
|
If you do not see the language or default track flags that you've specified in &mkvinfo;'s output then please read the
|
|
section about <link linkend="mkvmerge.default_values">default values</link>.
|
|
</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>
|
|
<para>
|
|
&matroska; supports file linking which simply says that a specific file is the predecessor or successor of the current file. To be precise,
|
|
it's not really the files that are linked but the &matroska; segments. As most files will probably only contain one &matroska; segment the
|
|
following explanations use the term 'file linking' although 'segment linking' would be more appropriate.
|
|
</para>
|
|
|
|
<para>
|
|
Each segment is identified by a unique 128 bit wide segment UID. This UID is automatically generated by &mkvmerge;. The linking is done
|
|
primarily via putting the segment UIDs (short: <abbrev>SID</abbrev>) of the previous/next file into the segment header
|
|
information. &mkvinfo; prints these <abbrev>SIDs</abbrev> if it finds them.
|
|
</para>
|
|
|
|
<para>
|
|
If a file is split into several smaller ones and linking is used then the timecodes will not start at 0 again but will continue where the
|
|
last file has left off. This way the absolute time is kept even if the previous files are not available (e.g. when streaming). If no
|
|
linking is used then the timecodes should start at 0 for each file. By default &mkvmerge; does not use file linking. If you want that you
|
|
can turn it on with the <option>--link</option> option. This option is only useful if splitting is activated as well.
|
|
</para>
|
|
|
|
<para>
|
|
Regardless of whether splitting is active or not the user can tell &mkvmerge; to link the produced files to specific
|
|
<abbrev>SIDs</abbrev>. This is achieved with the options <option>--link-to-previous</option> and <option>--link-to-next</option>. These
|
|
options accept a segment <abbrev>SID</abbrev> in the format that &mkvinfo; outputs: 16 hexadecimal numbers between
|
|
<constant>0x00</constant> and <constant>0xff</constant> prefixed with '<literal>0x</literal>' each, e.g. '<literal>0x41 0xda 0x73 0x66
|
|
0xd9 0xcf 0xb2 0x1e 0xae 0x78 0xeb 0xb4 0x5e 0xca 0xb3 0x93</literal>'. Alternatively a shorter form can be used: 16 hexadecimal numbers
|
|
between <constant>0x00</constant> and <constant>0xff</constant> without the '<literal>0x</literal>' prefixes and without the spaces, e.g.
|
|
'<literal>41da7366d9cfb21eae78ebb45ecab393</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
If splitting is used then the first file is linked to the <abbrev>SID</abbrev> given with <option>--link-to-previous</option> and the
|
|
last file is linked to the <abbrev>SID</abbrev> given with <option>--link-to-next</option>. If splitting is not used then the one output
|
|
file will be linked to both of the two <abbrev>SIDs</abbrev>.
|
|
</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>
|
|
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<!DOCTYPE Chapters SYSTEM "matroskachapters.dtd">
|
|
<Chapters>
|
|
<EditionEntry>
|
|
<ChapterAtom>
|
|
<ChapterTimeStart>00:00:30.000</ChapterTimeStart>
|
|
<ChapterTimeEnd>00:01:20.000</ChapterTimeEnd>
|
|
<ChapterDisplay>
|
|
<ChapterString>A short chapter</ChapterString>
|
|
<ChapterLanguage>eng</ChapterLanguage>
|
|
</ChapterDisplay>
|
|
<ChapterAtom>
|
|
<ChapterTimeStart>00:00:46.000</ChapterTimeStart>
|
|
<ChapterTimeEnd>00:01:10.000</ChapterTimeEnd>
|
|
<ChapterDisplay>
|
|
<ChapterString>A part of that short chapter</ChapterString>
|
|
<ChapterLanguage>eng</ChapterLanguage>
|
|
</ChapterDisplay>
|
|
</ChapterAtom>
|
|
</ChapterAtom>
|
|
</EditionEntry>
|
|
</Chapters>
|
|
</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><Tags></classname>.</para></listitem>
|
|
<listitem>
|
|
<para>One logical tag is contained inside one pair of <classname><Tag></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><String></classname> element while the binary type is used for the <classname><Binary></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>
|
|
&mkvinfo;, &mkvextract;, &mmg;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvmerge.www">
|
|
<title>WWW</title>
|
|
<para>
|
|
The latest version can always be found at <ulink url="http://www.bunkus.org/videotools/mkvtoolnix/">the MKVToolNix homepage</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|