mirror of
https://gitlab.com/mbunkus/mkvtoolnix.git
synced 2024-10-22 07:21:21 +00:00
3535 lines
156 KiB
XML
3535 lines
156 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
|
||
[
|
||
<!ENTITY product "mkvmerge">
|
||
<!ENTITY version "88.0">
|
||
<!ENTITY date "2024-10-19">
|
||
|
||
<!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 mkvpropedit "<citerefentry><refentrytitle>mkvpropedit</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
||
<!ENTITY mtxgui "<citerefentry><refentrytitle>mkvtoolnix-gui</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">MKVToolNix</refmiscinfo>
|
||
<refmiscinfo class="manual">User Commands</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>@options-file.json</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="https://www.matroska.org/">the &matroska; website</ulink>.
|
||
</para>
|
||
|
||
<important>
|
||
<para>
|
||
The order of command line options is important. Please read the section <link linkend="mkvmerge.option_order">"Option
|
||
order"</link> if you're new to the program.
|
||
</para>
|
||
</important>
|
||
|
||
<refsect2>
|
||
<title>Global options</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="mkvmerge.description.verbose">
|
||
<term><option>-v</option>, <option>--verbose</option></term>
|
||
<listitem>
|
||
<para>Increase verbosity.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.quiet">
|
||
<term><option>-q</option>, <option>--quiet</option></term>
|
||
<listitem>
|
||
<para>Suppress status output.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.output">
|
||
<term><option>-o</option>, <option>--output</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.webm">
|
||
<term><option>-w</option>, <option>--webm</option></term>
|
||
<listitem>
|
||
<para>Create a WebM compliant file. This is also turned on if the output file name's extension is "webm". This mode enforces
|
||
several restrictions. The only allowed codecs are VP8, VP9 video and Opus, Vorbis audio tracks. The DocType header item is changed to
|
||
"webm".
|
||
</para>
|
||
|
||
<para>
|
||
For chapters and tags only a subset of elements are allowed. &mkvmerge; will automatically remove all elements not allowed by the
|
||
specification.
|
||
</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.default_language">
|
||
<term><option>--default-language</option> <parameter>language-code</parameter></term>
|
||
<listitem>
|
||
<para>Sets the default language code that will be used for tracks for which no language is set with the <link
|
||
linkend="mkvmerge.description.language"><option>--language</option></link> option and for which the source container doesn't provide a
|
||
language.</para>
|
||
|
||
<para>The default language code is '<literal>und</literal>' for 'undetermined'.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Segment info handling (global options)</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="mkvmerge.description.segmentinfo">
|
||
<term><option>--segmentinfo</option> <parameter>filename.xml</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Read segment information from an <abbrev>XML</abbrev> file. This file can contain the segment family <abbrev>UID</abbrev>, segment
|
||
<abbrev>UID</abbrev>, previous and next segment <abbrev>UID</abbrev> elements. An example file and a <abbrev>DTD</abbrev> are included
|
||
in the MKVToolNix distribution.
|
||
</para>
|
||
|
||
<para>
|
||
See the section about <link linkend="mkvmerge.segmentinfo">segment info XML files</link> below for details.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.segment_uid">
|
||
<term><option>--segment-uid</option> <parameter>SID1,SID2,...</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the segment UIDs to use. This is a comma-separated list of 128-bit segment UIDs in the usual UID form: hex numbers with or without
|
||
the "0x" prefix, with or without spaces, exactly 32 digits.
|
||
</para>
|
||
|
||
<para>
|
||
If SID starts with = then its rest is interpreted as the name of a Matroska file whose segment UID is read and used.
|
||
</para>
|
||
|
||
<para>
|
||
Each file created contains one segment, and each segment has one segment UID. If more segment UIDs are specified than segments are
|
||
created then the surplus UIDs are ignored. If fewer UIDs are specified than segments are created then random UIDs will be created for
|
||
them.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Chapter and tag handling (global options)</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="mkvmerge.description.chapter_language">
|
||
<term><option>--chapter-language</option> <parameter>language-code</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the ISO 639-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>
|
||
|
||
<para>
|
||
The language set with this option is also used when chapters are generated with the <link
|
||
linkend="mkvmerge.description.generate_chapters"><option>--generate-chapters</option> option</link>.
|
||
</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 id="mkvmerge.description.chapter_sync">
|
||
<term><option>--chapter-sync</option> <parameter>d<optional>,o<optional>/p</optional></optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Adjust the timestamps of the chapters in the following source file by <parameter>d</parameter> ms. Alternatively you can use the
|
||
<option>--sync</option> option with the special track ID <constant>-2</constant> (see section <link
|
||
linkend="mkvmerge.track_ids.special_ids">special 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.generate_chapters">
|
||
<term><option>--generate-chapters</option> <parameter>mode</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
&mkvmerge; can create chapters automatically. The following two modes are currently supported:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
'<literal>when-appending</literal>' – This mode creates one chapter at the start and one chapter whenever a file is appended.
|
||
</para>
|
||
|
||
<para>
|
||
This mode also works with split modes '<literal>parts:</literal>' and '<literal>parts-frames:</literal>'. For these modes one
|
||
chapter will be generated for each appended timestamp range (those whose start timestamps are prefixed with
|
||
'<literal>+</literal>').
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
&mkvmerge; requires a video or an audio track to be present in order to be able to determine when a new file is appended. If one or
|
||
more video tracks are muxed the first one is used. Otherwise the first audio track is used.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
'<literal>interval:</literal><parameter>time-spec</parameter>' – This mode creates one chapter at fixed intervals given by
|
||
<parameter>time-spec</parameter>. The format is either the form <parameter>HH:MM:SS.nnnnnnnnn</parameter> or a number followed by
|
||
one of the units '<literal>s</literal>', '<literal>ms</literal>' or '<literal>us</literal>'.
|
||
</para>
|
||
|
||
<para>
|
||
Example: <literal>--generate-chapters interval:45s</literal>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
The names for the new chapters are controlled by the option <link
|
||
linkend="mkvmerge.description.generate_chapters_name_template">--generate-chapters-name-template</link>. The language is set with
|
||
<link linkend="mkvmerge.description.chapter_language">--chapter-language</link> which must occur before
|
||
<option>--generate-chapters</option>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.generate_chapters_name_template">
|
||
<term><option>--generate-chapters-name-template</option> <parameter>template</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
This sets the name template for chapter names generated by the option <link
|
||
linkend="mkvmerge.description.generate_chapters">--generate-chapters</link>. If the option is not used then default '<literal>Chapter
|
||
<NUM:2></literal>' will be used.
|
||
</para>
|
||
|
||
<para>
|
||
There are several variables that can be used in the template that are replaced by their actual values when a chapter is generated.
|
||
The string '<literal><NUM></literal>' will be replaced by the chapter number. The string '<literal><START></literal>'
|
||
will be replaced by the chapter's start timestamp.
|
||
</para>
|
||
|
||
<para>
|
||
The strings <literal>'<FILE_NAME>'</literal> and <literal>'<FILE_NAME_WITH_EXT>'</literal> are only filled when
|
||
generating chapters for appended files. They will be replaced by the appended file's name without respectively with its extension.
|
||
Note that only the file's base name and extension are inserted, not its directory or drive components.
|
||
</para>
|
||
|
||
<para>
|
||
You can specify a minimum number of places for the chapter number with '<literal><NUM:places></literal>', e.g. '<literal><NUM:3></literal>'.
|
||
The resulting number will be padded with leading zeroes if the number of places is less than specified.
|
||
</para>
|
||
|
||
<para>
|
||
You can control the format used by the start timestamp with <literal><START:format></literal>. The format defaults to
|
||
'<literal>%H:%M:%S</literal>' if none is given. Valid format codes are:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>%h</literal> – hours</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>%H</literal> – hours zero-padded to two places</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>%m</literal> – minutes</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>%M</literal> – minutes zero-padded to two places</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>%s</literal> – seconds</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>%S</literal> – seconds zero-padded to two places</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>%n</literal> – nanoseconds with nine places</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>%<1-9>n</literal> – nanoseconds with up to nine places (e.g. three places with <literal>%3n</literal>)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.cue_chapter_name_format">
|
||
<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 id="mkvmerge.description.chapters">
|
||
<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>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>General output control (advanced global options)</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="mkvmerge.description.track_order">
|
||
<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>
|
||
|
||
<para>
|
||
If this option isn't given, tracks will be sorted by their type first & the order of their source file second. Video tracks come
|
||
first followed by audio & subtitle tracks. Other rarely used track types come last.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.cluster_length">
|
||
<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>d</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 5000ms 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.clusters_in_meta_seek">
|
||
<term><option>--clusters-in-meta-seek</option></term>
|
||
<listitem>
|
||
<para>
|
||
Tells &mkvmerge; 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 id="mkvmerge.description.timestamp_scale">
|
||
<term><option>--timestamp-scale</option> <parameter>factor</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Forces the timestamp 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 timestamps 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 timestamp scale
|
||
factor so that all timestamps 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>
|
||
|
||
<varlistentry id="mkvmerge.description.enable_durations">
|
||
<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 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 id="mkvmerge.description.no_date">
|
||
<term><option>--no-date</option></term>
|
||
<listitem>
|
||
<para>
|
||
By default &mkvmerge; sets the "date" segment information field to the time & date when multiplexing started. With this option
|
||
that field is not written at all.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.disable_lacing">
|
||
<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 id="mkvmerge.description.disable_track_statistics_tags">
|
||
<term><option>--disable-track-statistics-tags</option></term>
|
||
<listitem>
|
||
<para>
|
||
Normally &mkvmerge; will write certain tags with statistics for each track. If such tags are already present then they will be
|
||
overwritten. The tags are <constant>BPS</constant>, <constant>DURATION</constant>, <constant>NUMBER_OF_BYTES</constant> and
|
||
<constant>NUMBER_OF_FRAMES</constant>.
|
||
</para>
|
||
|
||
<para>
|
||
Enabling this option prevents &mkvmerge; from writing those tags and from touching any existing tags with same names.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.disable_language_ietf">
|
||
<term><option>--disable-language-ietf</option></term>
|
||
<listitem>
|
||
<para>
|
||
Normally &mkvmerge; will write the new IETF BCP 47 language elements in addition to the legacy language elements in track headers,
|
||
chapters and tags. If this option is used, only the legacy elements are written.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.normalize_language_ietf">
|
||
<term><option>--normalize-language-ietf</option> <parameter>mode</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Enables normalizing all IETF BCP 47 language tags to either their canonical form with mode '<literal>canonical</literal>', to their
|
||
extended language subtags form with mode '<literal>extlang</literal>' or turns it off with mode '<literal>off</literal>'. By default
|
||
normalization to the canonical form is applied.
|
||
</para>
|
||
|
||
<para>
|
||
In the canonical form all subtags for which preferred values exist are replaced by those preferred values. This converts
|
||
e.g. '<literal>zh-yue-jyutping</literal>' to '<literal>yue-jyutping</literal>' or '<literal>fr-FX</literal>' to '<literal>fr-FR</literal>'.
|
||
</para>
|
||
|
||
<para>
|
||
For the extended language subtags form the canonical form is built first. Afterwards all primary languages for which an extended
|
||
language subtag exists are replaced by that extended language subtag and its prefix. This converts
|
||
e.g. '<literal>yue-jyutping</literal>' back to '<literal>zh-yue-jyutping</literal>' but has no effect on '<literal>fr-FR</literal>'
|
||
as '<literal>fr</literal>' is not an extended language subtag.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.stop_after_video_ends">
|
||
<term><option>--stop-after-video-ends</option></term>
|
||
<listitem>
|
||
<para>
|
||
Stops processing after the primary video track ends, discarding any remaining packets of other tracks.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>File splitting, linking, appending and concatenation (more global options)</title>
|
||
|
||
<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.
|
||
Therefore the split point may be a bit off from what the user has specified.
|
||
</para>
|
||
|
||
<para>
|
||
At the moment &mkvmerge; supports the following modes:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
Splitting by size.
|
||
</para>
|
||
|
||
<para>
|
||
Syntax: <option>--split</option> <optional><literal>size:</literal></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><literal>duration:</literal></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 parameter 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 timestamps.
|
||
</para>
|
||
|
||
<para>
|
||
Syntax: <option>--split</option> <literal>timestamps:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional>
|
||
</para>
|
||
|
||
<para>
|
||
Example: <code>--split timestamps: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 timestamps is separated by commas. After the input stream has reached the
|
||
current split point's timestamp a new file is created. Then the next split point given in this list is used.
|
||
</para>
|
||
|
||
<para>
|
||
The '<literal>timestamps:</literal>' prefix must not be omitted.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Keeping specific parts by specifying timestamp ranges while discarding others.
|
||
</para>
|
||
|
||
<para>
|
||
Syntax: <option>--split</option> <literal>parts:</literal><parameter>start1</parameter>-<parameter>end1</parameter><optional>,<optional>+</optional><parameter>start2</parameter>-<parameter>end2</parameter><optional>,<optional>+</optional><parameter>start3</parameter>-<parameter>end3</parameter>...</optional></optional>
|
||
</para>
|
||
|
||
<para>
|
||
Examples:
|
||
<orderedlist>
|
||
<listitem><para><code>--split parts:00:01:20-00:02:45,00:05:50-00:10:30</code></para></listitem>
|
||
<listitem><para><code>--split parts:00:01:20-00:02:45,+00:05:50-00:10:30</code></para></listitem>
|
||
<listitem><para><code>--split parts:-00:02:45,00:05:50-</code></para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
|
||
<para>
|
||
The <literal>parts</literal> mode tells &mkvmerge; to keep certain ranges of timestamps while discarding others. The ranges to keep
|
||
have to be listed after the <literal>parts:</literal> keyword and be separated by commas. A range itself consists of a start and an
|
||
end timestamp in the same format the other variations of <parameter>--split</parameter> accept (e.g. both
|
||
<literal>00:01:20</literal> and <literal>80s</literal> refer to the same timestamp).
|
||
</para>
|
||
|
||
<para>
|
||
If a start timestamp is left out then it defaults to the previous range's end timestamp. If there was no previous range then it
|
||
defaults to the start of the file (see example 3).
|
||
</para>
|
||
|
||
<para>
|
||
If an end timestamp is left out then it defaults to the end of the source files which basically tells &mkvmerge; to keep the rest (see
|
||
example 3).
|
||
</para>
|
||
|
||
<para>
|
||
Normally each range will be written to a new file. This can be changed so that consecutive ranges are written to the same file. For
|
||
that the user has to prefix the start timestamp with a <literal>+</literal>. This tells &mkvmerge; not to create a new file and
|
||
instead append the range to the same file the previous range was written to. Timestamps will be adjusted so that there will be no
|
||
gap in the output file even if there was a gap in the two ranges in the input file.
|
||
</para>
|
||
|
||
<para>
|
||
In example 1 &mkvmerge; will create two files. The first will contain the content starting from <literal>00:01:20</literal> until
|
||
<literal>00:02:45</literal>. The second file will contain the content starting from <literal>00:05:50</literal> until
|
||
<literal>00:10:30</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
In example 2 &mkvmerge; will create only one file. This file will contain both the content starting from <literal>00:01:20</literal>
|
||
until <literal>00:02:45</literal> and the content starting from <literal>00:05:50</literal> until <literal>00:10:30</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
In example 3 &mkvmerge; will create two files. The first will contain the content from the start of the source files until
|
||
<literal>00:02:45</literal>. The second file will contain the content starting from <literal>00:05:50</literal> until the end of
|
||
the source files.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
Note that &mkvmerge; only makes decisions about splitting at key frame positions. This applies to both the start and the end of
|
||
each range. So even if an end timestamp is between two key frames &mkvmerge; will continue outputting the frames up to but
|
||
excluding the following key frame.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Keeping specific parts by specifying frame/field number ranges while discarding others.
|
||
</para>
|
||
|
||
<para>
|
||
Syntax: <option>--split</option> <literal>parts-frames:</literal><parameter>start1</parameter>-<parameter>end1</parameter><optional>,<optional>+</optional><parameter>start2</parameter>-<parameter>end2</parameter><optional>,<optional>+</optional><parameter>start3</parameter>-<parameter>end3</parameter>...</optional></optional>
|
||
</para>
|
||
|
||
<para>
|
||
Examples:
|
||
<orderedlist>
|
||
<listitem><para><code>--split parts-frames:137-258,548-1211</code></para></listitem>
|
||
<listitem><para><code>--split parts-frames:733-912,+1592-2730</code></para></listitem>
|
||
<listitem><para><code>--split parts-frames:-430,2512-</code></para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
|
||
<para>
|
||
The <literal>parts-frames</literal> mode tells &mkvmerge; to keep certain ranges of frame/field numbers while discarding
|
||
others. The ranges to keep have to be listed after the <literal>parts-frames:</literal> keyword and be separated by commas. A range
|
||
itself consists of a start and an end frame/field number. Numbering starts at 1.
|
||
</para>
|
||
|
||
<para>
|
||
If a start number is left out then it defaults to the previous range's end number. If there was no previous range then it defaults
|
||
to the start of the file (see example 3).
|
||
</para>
|
||
|
||
<para>
|
||
If an end number is left out then it defaults to the end of the source files which basically tells &mkvmerge; to keep the rest (see
|
||
example 3).
|
||
</para>
|
||
|
||
<para>
|
||
Normally each range will be written to a new file. This can be changed so that consecutive ranges are written to the same file. For
|
||
that the user has to prefix the start number with a <literal>+</literal>. This tells &mkvmerge; not to create a new file and
|
||
instead append the range to the same file the previous range was written to. Timestamps will be adjusted so that there will be no
|
||
gap in the output file even if there was a gap in the two ranges in the input file.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
Note that &mkvmerge; only makes decisions about splitting at key frame positions. This applies to both the start and the end of
|
||
each range. So even if an end frame/field number is between two key frames &mkvmerge; will continue outputting the frames up to
|
||
but excluding the following key frame.
|
||
</para>
|
||
</note>
|
||
|
||
<para>
|
||
In example 1 &mkvmerge; will create two files. The first will contain the content starting from the first key frame at or after
|
||
<literal>137</literal> up to but excluding the first key frame at or after <literal>258</literal>. The second file will contain the
|
||
content starting from <literal>548</literal> until <literal>1211</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
In example 2 &mkvmerge; will create only one file. This file will contain both the content starting from <literal>733</literal>
|
||
until <literal>912</literal> and the content starting from <literal>1592</literal> until <literal>2730</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
In example 3 &mkvmerge; will create two files. The first will contain the content from the start of the source files until
|
||
<literal>430</literal>. The second file will contain the content starting from <literal>2512</literal> until the end of the source
|
||
files.
|
||
</para>
|
||
|
||
<para>
|
||
This mode considers only the first video track that is output. If no video track is output no splitting will occur.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
The numbers given with this argument are interpreted based on the number of &matroska; blocks that are output. A single &matroska;
|
||
block contains either a full frame (for progressive content) or a single field (for interlaced content). mkvmerge does not
|
||
distinguish between those two and simply counts the number of blocks. For example: If one wanted to split after the 25th full
|
||
frame with interlaced content one would have to use <literal>50</literal> (two fields per full frame) as the split point.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Splitting after specific frames/fields.
|
||
</para>
|
||
|
||
<para>
|
||
Syntax: <option>--split</option> <literal>frames:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional>
|
||
</para>
|
||
|
||
<para>
|
||
Example: <code>--split frames:120,237,891</code>
|
||
</para>
|
||
|
||
<para>
|
||
The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>C</parameter> etc must all be positive integers.
|
||
Numbering starts at 1. The list of frame/field numbers is separated by commas. After the input stream has reached the current
|
||
split point's frame/field number a new file is created. Then the next split point given in this list is used.
|
||
</para>
|
||
|
||
<para>
|
||
The '<literal>frames:</literal>' prefix must not be omitted.
|
||
</para>
|
||
|
||
<para>
|
||
This mode considers only the first video track that is output. If no video track is output no splitting will occur.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
The numbers given with this argument are interpreted based on the number of &matroska; blocks that are output. A single &matroska;
|
||
block contains either a full frame (for progressive content) or a single field (for interlaced content). mkvmerge does not
|
||
distinguish between those two and simply counts the number of blocks. For example: If one wanted to split after the 25th full
|
||
frame with interlaced content one would have to use <literal>50</literal> (two fields per full frame) as the split point.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Splitting before specific chapters.
|
||
</para>
|
||
|
||
<para>
|
||
Syntax: <option>--split</option> <literal>chapters:all</literal> or <option>--split</option>
|
||
<literal>chapters:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional>
|
||
</para>
|
||
|
||
<para>
|
||
Example: <code>--split chapters:5,8</code>
|
||
</para>
|
||
|
||
<para>
|
||
The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>C</parameter> etc must all be positive integers.
|
||
Numbering starts at 1. The list of chapter numbers is separated by commas. Splitting will occur right before the first key frame
|
||
whose timestamp is equal to or bigger than the start timestamp for the chapters whose numbers are listed. A chapter starting at 0s
|
||
is never considered for splitting and discarded silently.
|
||
</para>
|
||
|
||
<para>
|
||
The keyword <literal>all</literal> can be used instead of listing all chapter numbers manually.
|
||
</para>
|
||
|
||
<para>
|
||
The '<literal>chapters:</literal>' prefix must not be omitted.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
The &matroska; file format supports arbitrary deeply nested chapter structures called 'edition entries' and 'chapter atoms'.
|
||
However, this mode only considers the top-most level of chapters across all edition entries.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<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 '<code>%d</code>' including an optional field width,
|
||
e.g. '<code>%02d</code>'. 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 '<code>-%03d</code>' is assumed right before the file's
|
||
extension: '<code>-o output.mkv</code>' would result in '<code>output-001.mkv</code>' and so on. If there's no extension
|
||
then '<code>-%03d</code>' will be appended to the name.
|
||
</para>
|
||
|
||
<para>
|
||
Another possible pattern is '<code>%c</code>' which will be replaced by the name of the first chapter in the file. Note that when
|
||
'<code>%c</code>' is present, the pattern '<code>-%03d</code>' will not be added automatically.
|
||
</para>
|
||
</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 id="mkvmerge.description.link_to_previous">
|
||
<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>
|
||
|
||
<para>
|
||
If SID starts with = then its rest is interpreted as the name of a Matroska file whose segment UID is read and used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.link_to_next">
|
||
<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>
|
||
|
||
<para>
|
||
If SID starts with = then its rest is interpreted as the name of a Matroska file whose segment UID is read and used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.append_mode">
|
||
<term><option>--append-mode</option> <parameter>mode</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Determines how timestamps 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 timestamps for '<literal>track2_1</literal>' by an amount. For '<literal>file</literal>' mode this amount is
|
||
the highest timestamp encountered in '<literal>file1</literal>' even if that timestamp was from a different track than
|
||
'<literal>track1_1</literal>'. In track mode the offset is the highest timestamp 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 id="mkvmerge.description.append_to">
|
||
<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>
|
||
|
||
<varlistentry id="mkvmerge.description.plus_sign">
|
||
<term><option>+</option></term>
|
||
<listitem>
|
||
<para>
|
||
A single '+' causes the next file to be appended instead of added. The '+' can also be put in front of the next file name. Therefore
|
||
the following two commands are equivalent:
|
||
</para>
|
||
|
||
<screen>$ mkvmerge -o full.mkv file1.mkv + file2.mkv
|
||
$ mkvmerge -o full.mkv file1.mkv +file2.mkv</screen>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.square_brackets">
|
||
<term><option>[</option> <parameter>file1</parameter> <parameter>file2</parameter> <option>]</option></term>
|
||
<listitem>
|
||
<para>
|
||
If multiple file names are contained in a pair of square brackets then the second and all following files will be appended to the first file named within the brackets.
|
||
</para>
|
||
|
||
<para>
|
||
This is an alternative syntax to using '+' between the file names. Therefore the following two commands are equivalent:
|
||
</para>
|
||
|
||
<screen>$ mkvmerge -o full.mkv file1.mkv + file2.mkv
|
||
$ mkvmerge -o full.mkv '[' file1.mkv file2.mkv ']'</screen>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.prevent_concatenation">
|
||
<term><option>=</option></term>
|
||
<listitem>
|
||
<para>
|
||
For certain file types (MPEG program streams = VOBs) &mkvmerge; normally looks for files in the same directory as an input file that
|
||
have the same base name and only differ in their running number (e.g. 'VTS_01_1.VOB', 'VTS_01_2.VOB', 'VTS_01_3.VOB' etc) and treats
|
||
all of those files as if they were concatenated into a single big file. This option, a single '=', causes mkvmerge not to look for
|
||
those additional files.
|
||
</para>
|
||
|
||
<para>
|
||
The '=' can also be put in front of the next file name. Therefore the following two commands are equivalent:
|
||
</para>
|
||
|
||
<screen>$ mkvmerge -o full.mkv = file1.vob
|
||
$ mkvmerge -o full.mkv =file1.vob</screen>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.concatenation">
|
||
<term><option>(</option> <parameter>file1</parameter> <parameter>file2</parameter> <option>)</option></term>
|
||
<listitem>
|
||
<para>
|
||
If multiple file names are contained in a pair of parenthesis then those files will be treated as if they were concatenated into a
|
||
single big file consisting of the content of each of the files one after the other.
|
||
</para>
|
||
|
||
<para>
|
||
This can be used for e.g. VOB files coming from a DVD or MPEG transport streams. It cannot be used if each file contains its own set
|
||
of headers which is usually the case with stand-alone files like AVI or MP4.
|
||
</para>
|
||
|
||
<para>
|
||
Putting a file name into parenthesis also prevents &mkvmerge; from looking for additional files with the same base name as described
|
||
in <link linkend="mkvmerge.description.prevent_concatenation">option <option>=</option></link>. Therefore these two command lines are
|
||
equivalent:
|
||
</para>
|
||
|
||
<screen>$ mkvmerge -o out.mkv = file.mkv
|
||
$ mkvmerge -o out.mkv '(' file.mkv ')'</screen>
|
||
|
||
<para>
|
||
Several things should be noted:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
There must be spaces both after the opening and before the closing parenthesis.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Every parameter between parenthesis is interpreted as a file name. Therefore all options applying to this logical file must be listed before the opening parenthesis.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Some shells treat parenthesis as special characters. Hence you must escape or quote them as shown in the example above.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Attachment support (more global options)</title>
|
||
|
||
<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 id="mkvmerge.description.attachment_mime_type">
|
||
<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="https://www.iana.org/assignments/media-types/">the IANA
|
||
homepage</ulink>. The <abbrev>MIME</abbrev> type is mandatory for an attachment.
|
||
</para>
|
||
|
||
<para>
|
||
If no <abbrev>MIME</abbrev> type is given a for an attachment, its type will be detected automatically.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.attachment_name">
|
||
<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 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>
|
||
|
||
<varlistentry id="mkvmerge.description.enable_legacy_font_mime_types">
|
||
<term><option>--enable-legacy-font-mime-types</option></term>
|
||
<listitem>
|
||
<para>
|
||
Enables the use of legacy <abbrev>MIME</abbrev> types for certain types of font attachments. For example,
|
||
'<literal>application/x-truetype-font</literal>' will be used for TrueType fonts instead of '<literal>fonts/ttf</literal>'.
|
||
</para>
|
||
|
||
<para>
|
||
This affects both new attachments if its <abbrev>MIME</abbrev> type is detected automatically and existing attachments whose stored
|
||
<abbrev>MIME</abbrev> types will be remapped to the legacy ones.
|
||
</para>
|
||
|
||
<para>
|
||
The affected <abbrev>MIME</abbrev> types are '<literal>font/sfnt</literal>', '<literal>font/ttf</literal>' and
|
||
'<literal>font/collection</literal>' which are all mapped to '<literal>application/x-truetype-fonts</literal>' and
|
||
'<literal>font/otf</literal>' which is mapped to '<literal>application/vnd.ms-opentype</literal>'.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Options that can be used for each input file</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="mkvmerge.description.audio_tracks">
|
||
<term><option>-a</option>, <option>--audio-tracks</option> <parameter><optional>!</optional>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>
|
||
|
||
<para>
|
||
Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags
|
||
for their tracks.
|
||
</para>
|
||
|
||
<para>
|
||
Default: copy all tracks of this kind.
|
||
</para>
|
||
|
||
<para>
|
||
If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed
|
||
after the <literal>!</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.video_tracks">
|
||
<term><option>-d</option>, <option>--video-tracks</option> <parameter><optional>!</optional>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>
|
||
|
||
<para>
|
||
Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags
|
||
for their tracks.
|
||
</para>
|
||
|
||
<para>
|
||
If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed
|
||
after the <literal>!</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.subtitle_tracks">
|
||
<term><option>-s</option>, <option>--subtitle-tracks</option> <parameter><optional>!</optional>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>
|
||
|
||
<para>
|
||
Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags
|
||
for their tracks.
|
||
</para>
|
||
|
||
<para>
|
||
If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed
|
||
after the <literal>!</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.button_tracks">
|
||
<term><option>-b</option>, <option>--button-tracks</option> <parameter><optional>!</optional>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>
|
||
|
||
<para>
|
||
Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags
|
||
for their tracks.
|
||
</para>
|
||
|
||
<para>
|
||
If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed
|
||
after the <literal>!</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.track_tags">
|
||
<term><option>--track-tags</option> <parameter><optional>!</optional>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>
|
||
|
||
<para>
|
||
If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy everything but the IDs listed after the
|
||
<literal>!</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.attachments">
|
||
<term><option>-m</option>, <option>--attachments</option> <parameter><optional>!</optional>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>
|
||
|
||
<para>
|
||
If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy everything but the IDs listed after the
|
||
<literal>!</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.no_audio">
|
||
<term><option>-A</option>, <option>--no-audio</option></term>
|
||
<listitem>
|
||
<para>
|
||
Don't copy any audio track from this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.no_video">
|
||
<term><option>-D</option>, <option>--no-video</option></term>
|
||
<listitem>
|
||
<para>
|
||
Don't copy any video track from this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.no_subtitles">
|
||
<term><option>-S</option>, <option>--no-subtitles</option></term>
|
||
<listitem>
|
||
<para>
|
||
Don't copy any subtitle track from this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.no_buttons">
|
||
<term><option>-B</option>, <option>--no-buttons</option></term>
|
||
<listitem>
|
||
<para>
|
||
Don't copy any button track from this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.no_track_tags">
|
||
<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 id="mkvmerge.description.no_global_tags">
|
||
<term><option>--no-global-tags</option></term>
|
||
<listitem>
|
||
<para>
|
||
Don't copy global tags from this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.regenerate_track_uids">
|
||
<term><option>--regenerate-track-uids</option></term>
|
||
<listitem>
|
||
<para>
|
||
When this option is used for a Matroska source file, &mkvmerge; will create new random unique track IDs instead of keeping the
|
||
existing ones in the file. Existing track UIDs in chapters & tags read from the same file will be remapped to the newly generated
|
||
values.
|
||
</para>
|
||
|
||
<para>
|
||
This behavior is enabled automatically for Matroska files created by the MakeMKV software. The reason is that MakeMKV uses
|
||
consecutive numbers (1, 2, 3…) as UIDs instead of generating random ones.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.sync">
|
||
<term><option>-y</option>, <option>--sync</option> <parameter>TID:d<optional>,o<optional>/p</optional></optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Adjust the timestamps 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 and subtitle tracks and '<literal>none</literal>' for audio tracks. 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 id="mkvmerge.description.default_track_flag">
|
||
<term><option>--default-track-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "default track" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the
|
||
optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. The flag will be set if the
|
||
source container doesn't provide that information and the user doesn't specify it via this option.
|
||
</para>
|
||
|
||
<para>
|
||
If the user does not explicitly select a track during playback, the player should select one of the tracks that has its "default
|
||
track" flag set, taking user preferences such as their preferred language into account.
|
||
</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.track_enabled_flag">
|
||
<term><option>--track-enabled-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "track enabled" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) to the
|
||
given value <parameter>bool</parameter> (0 or 1; defaults to 1 if not specified). Tracks are enabled by default if no option is
|
||
specified for them and the source container doesn't provide this information either.
|
||
</para>
|
||
|
||
<para>
|
||
Only tracks whose "track enabled" flag is set should be considered for playback.
|
||
</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.forced_display_flag">
|
||
<term><option>--forced-display-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "forced display" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the
|
||
optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. Use this for tracks
|
||
containing onscreen text or foreign-language dialogue.
|
||
</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.hearing_impaired_flag">
|
||
<term><option>--hearing-impaired-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "hearing impaired" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the
|
||
optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if the
|
||
track is suitable for users with hearing impairments.
|
||
</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.visual_impaired_flag">
|
||
<term><option>--visual-impaired-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "visual impaired" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the
|
||
optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if the
|
||
track is suitable for users with visual impairments.
|
||
</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.text_descriptions_flag">
|
||
<term><option>--text-descriptions-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "text descriptions" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if
|
||
the optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if
|
||
the track contains textual descriptions of video content suitable for playback via a text-to-speech system for a visually-impaired
|
||
user.
|
||
</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.original_flag">
|
||
<term><option>--original-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "original language" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if
|
||
the optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if
|
||
the track is in the content's original language (not a translation).
|
||
</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.commentary_flag">
|
||
<term><option>--commentary-flag</option> <parameter>TID<optional>:bool</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the "commentary" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the
|
||
optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if the
|
||
track contains commentary.
|
||
</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.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 ISO 639-2 language codes
|
||
and ISO 639-1 country codes are allowed. The country codes will be converted to language codes automatically. All languages including
|
||
their ISO 639-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 id="mkvmerge.description.tags">
|
||
<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 id="mkvmerge.description.aac_is_sbr">
|
||
<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 id="mkvmerge.description.audio_emphasis">
|
||
<term><option>--audio-emphasis</option> <parameter>TID:n|symbolic-name</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the emphasis for the audio track with the track ID <parameter>TID</parameter>. The mode can either be a number
|
||
<parameter>n</parameter> (certain values between <constant>0</constant> and <constant>16</constant>) or a symbolic name. All valid
|
||
numbers & symbolic names can be listed with the <link
|
||
linkend="mkvmerge.description.list_audio_emphasis"><option>--list-audio-emphasis</option> option</link>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.reduce_to_core">
|
||
<term><option>--reduce-to-core</option> <parameter>TID</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Some audio codecs have a lossy core and optional extensions that implement lossless decoding. This option tells &mkvmerge; to only
|
||
copy the core but not the extensions. By default &mkvmerge; copies both the core and the extensions.
|
||
</para>
|
||
|
||
<para>
|
||
Currently only <abbrev>DTS</abbrev> tracks are affected by this option. TrueHD tracks that contain an embedded <abbrev>AC-3</abbrev>
|
||
core are instead presented as two separate tracks for which the user can select which track to copy. For <abbrev>DTS</abbrev> such a
|
||
scheme would not work as the HD extensions cannot be decoded by themselves – unlike the TrueHD data.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.remove_dialog_normalization_gain">
|
||
<term><option>--remove-dialog-normalization-gain</option> <parameter>TID</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Some audio codecs contain header fields that tell the decoder or player to apply a (usually negative) gain for dialog
|
||
normalization. This option tells &mkvmerge; to remove or minimize that gain by modifying the corresponding header fields.
|
||
</para>
|
||
|
||
<para>
|
||
Currently only <abbrev>AC-3</abbrev>, <abbrev>DTS</abbrev> and <abbrev>TrueHD</abbrev> tracks are affected by this option.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.timestamps">
|
||
<term><option>--timestamps</option> <parameter>TID:file-name</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Read the timestamps to be used for the specific track ID from <parameter>file-name</parameter>. These timestamps forcefully override
|
||
the timestamps that &mkvmerge; normally calculates. Read the section about <link linkend="mkvmerge.external_timestamp_files">external
|
||
timestamp files</link>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.default_duration">
|
||
<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 timestamps 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>', '<literal>fps</literal>', '<literal>p</literal>' or '<literal>i</literal>' to
|
||
specify the default duration in seconds, milliseconds, microseconds, nanoseconds, 'frames per second', 'progressive frames per
|
||
second' or 'interlaced 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 the
|
||
encoded bitstream for certain track types, e.g. AVC/H.264 or MPEG-2.
|
||
</para>
|
||
|
||
<para>
|
||
This option can also be used to change the <abbrev>FPS</abbrev> of video tracks without having to use an external timestamp file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.fix_bitstream_timing_information">
|
||
<term><option>--fix-bitstream-timing-information</option> <parameter>TID<optional>:0|1</optional></parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Normally &mkvmerge; does not change the timing information (frame/field rate) stored in the video bitstream. With this option that
|
||
information is adjusted to match the container timing information. The container timing information can come from various sources:
|
||
from the command line (see option <link linkend="mkvmerge.description.default_duration"><option>--default-duration</option></link>),
|
||
the source container or derived from the bitstream.
|
||
</para>
|
||
|
||
<note>
|
||
<para>This has only been implemented for AVC/H.264 video tracks so far.</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.compression">
|
||
<term><option>--compression</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Selects the compression method to be used for the track. Note that the player also has to support this method. Valid values are
|
||
'<literal>none</literal>', '<literal>zlib</literal>' and '<literal>mpeg4_p2</literal>'/'<literal>mpeg4p2</literal>'.
|
||
</para>
|
||
<para>
|
||
The compression method '<literal>mpeg4_p2</literal>'/'<literal>mpeg4p2</literal>' is a special compression method called 'header
|
||
removal' that is only available for <abbrev>MPEG4</abbrev> part 2 video tracks.
|
||
</para>
|
||
<para>
|
||
The default for some subtitle types 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>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Options that only apply to video tracks</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="mkvmerge.description.fourcc">
|
||
<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 'MS compatibility mode'.
|
||
</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 id="mkvmerge.description.cropping">
|
||
<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 id="mkvmerge.description.color_matrix_coefficients">
|
||
<term><option>--color-matrix-coefficients</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the matrix coefficients of the video used to derive luma and chroma values from red, green and blue color primaries. The
|
||
parameter <parameter>n</parameter> is an integer rangeing from <constant>0</constant> and <constant>10</constant>.
|
||
</para>
|
||
|
||
<para>
|
||
Valid values and their meaning are:
|
||
</para>
|
||
|
||
<para>
|
||
<constant>0</constant>: GBR, <constant>1</constant>: BT709, <constant>2</constant>: unspecified, <constant>3</constant>: reserved,
|
||
<constant>4</constant>: FCC, <constant>5</constant>: BT470BG, <constant>6</constant>: SMPTE 170M, <constant>7</constant>: SMPTE 240M,
|
||
<constant>8</constant>: YCOCG, <constant>9</constant>: BT2020 non-constant luminance, <constant>10</constant>: BT2020 constant
|
||
luminance
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.color_bits_per_channel">
|
||
<term><option>--color-bits-per-channel</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the number of coded bits for a color channel. A value of <constant>0</constant> indicates that the number of bits is
|
||
unspecified.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.chroma_subsample">
|
||
<term><option>--chroma-subsample</option> <parameter>TID:hori,vert</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
The amount of pixels to remove in the Cr and Cb channels for every pixel not removed horizontally/vertically.
|
||
</para>
|
||
|
||
<para>
|
||
Example: For video with 4:2:0 chroma subsampling, the parameter should be set to
|
||
<code><parameter>TID</parameter>:<constant>1</constant>,<constant>1</constant></code>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.cb_subsample">
|
||
<term><option>--cb-subsample</option> <parameter>TID:hori,vert</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
The amount of pixels to remove in the Cb channel for every pixel not removed horizontally/vertically. This is additive with
|
||
<option>--chroma-subsample</option>.
|
||
</para>
|
||
|
||
<para>
|
||
Example: For video with 4:2:1 chroma subsampling, the parameter <option>--chroma-subsample</option> should be set to
|
||
<code><parameter>TID</parameter>:<constant>1</constant>,<constant>0</constant></code> and Cb-subsample should be set to
|
||
<code><parameter>TID</parameter>:<constant>1</constant>,<constant>0</constant></code>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.chroma_siting">
|
||
<term><option>--chroma-siting</option> <parameter>TID:hori,vert</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets how chroma is sited horizontally/vertically (<constant>0</constant>: unspecified, <constant>1</constant>: top collocated,
|
||
<constant>2</constant>: half).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.color_range">
|
||
<term><option>--color-range</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the clipping of the color ranges (<constant>0</constant>: unspecified, <constant>1</constant>: broadcast range,
|
||
<constant>2</constant>: full range (no clipping), <constant>3</constant>: defined by MatrixCoefficients/TransferCharacteristics).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.color_transfer_characteristics">
|
||
<term><option>--color-transfer-characteristics</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
The transfer characteristics of the video.
|
||
</para>
|
||
|
||
<para>
|
||
Valid values and their meaning are:
|
||
</para>
|
||
|
||
<para>
|
||
<constant>0</constant>: reserved, <constant>1</constant>: ITU-R BT.709, <constant>2</constant>: unspecified, <constant>3</constant>:
|
||
reserved, <constant>4</constant>: gamma 2.2 curve, <constant>5</constant>: gamma 2.8 curve, <constant>6</constant>: SMPTE 170M,
|
||
<constant>7</constant>: SMPTE 240M, <constant>8</constant>: linear, <constant>9</constant>: log, <constant>10</constant>: log sqrt,
|
||
<constant>11</constant>: IEC 61966-2-4, <constant>12</constant>: ITU-R BT.1361 extended color gamut, <constant>13</constant>: IEC
|
||
61966-2-1, <constant>14</constant>: ITU-R BT.2020 10 bit, <constant>15</constant>: ITU-R BT.2020 12 bit, <constant>16</constant>:
|
||
SMPTE ST 2084, <constant>17</constant>: SMPTE ST 428-1; <constant>18</constant>: ARIB STD-B67 (HLG)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.color_primaries">
|
||
<term><option>--color-primaries</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the color primaries of the video.
|
||
</para>
|
||
|
||
<para>
|
||
Valid values and their meaning are:
|
||
</para>
|
||
|
||
<para>
|
||
<constant>0</constant>: reserved, <constant>1</constant>: ITU-R BT.709, <constant>2</constant>: unspecified, <constant>3</constant>:
|
||
reserved, <constant>4</constant>: ITU-R BT.470M, <constant>5</constant>: ITU-R BT.470BG, <constant>6</constant>: SMPTE 170M,
|
||
<constant>7</constant>: SMPTE 240M, <constant>8</constant>: FILM, <constant>9</constant>: ITU-R BT.2020, <constant>10</constant>:
|
||
SMPTE ST 428-1, <constant>22</constant>: JEDEC P22 phosphors
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.max_content_light">
|
||
<term><option>--max-content-light</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum brightness of a single pixel (Maximum Content Light Level) in candelas per square meter (cd/m²). The value of
|
||
<parameter>n</parameter> should be a non-negtive integer.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.max_frame_light">
|
||
<term><option>--max-frame-light</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum brightness of a single full frame (Maximum Frame-Average Light Level) in candelas per square meter (cd/m²). The
|
||
value of <parameter>n</parameter> should be a non-negtive
|
||
integer.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.chromaticity_coordinates">
|
||
<term><option>--chromaticity-coordinates</option>
|
||
<parameter>TID:red-x,red-y,green-x,green-y,blue-x,blue-y</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the red/green/blue chromaticity coordinates as defined by CIE 1931.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.white_color_coordinates">
|
||
<term><option>--white-color-coordinates</option> <parameter>TID:x,y</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the white color chromaticity coordinates as defined by CIE 1931.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.max_luminance">
|
||
<term><option>--max-luminance</option> <parameter>TID:float</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum luminance in candelas per square meter (cd/m²). The value should be less than 9999.99.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.min_luminance">
|
||
<term><option>--min-luminance</option> <parameter>TID:float</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the minimum luminance in candelas per square meter (cd/m²). The value should be less than 999.9999.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.projection_type">
|
||
<term><option>--projection-type</option> <parameter>TID:method</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the video projection method used. Valid values are 0 (rectangular projection), 1 (equirectangular projection), 2 (cubemap projection) and 3 (mesh projection).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.projection_private">
|
||
<term><option>--projection-private</option> <parameter>TID:data</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets private data that only applies to a specific projection. Data must be given as hex numbers with or without the "0x" prefix, with or without spaces.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.projection_pose_yaw">
|
||
<term><option>--projection-pose-yaw</option> <parameter>TID:float</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a yaw rotation to the projection.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.projection_pose_pitch">
|
||
<term><option>--projection-pose-pitch</option> <parameter>TID:float</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a pitch rotation to the projection.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.projection_pose_roll">
|
||
<term><option>--projection-pose-roll</option> <parameter>TID:float</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a roll rotation to the projection.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.field_order">
|
||
<term><option>--field-order</option> <parameter>TID:n</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Sets the field order for the video track with the track ID <parameter>TID</parameter>. The order must be one of the following numbers:
|
||
</para>
|
||
|
||
<para>
|
||
<constant>0</constant>: progressive; <constant>1</constant>: interlaced with top field displayed first and top field stored first;
|
||
<constant>2</constant>: undetermined field order; <constant>6</constant>: interlaced with bottom field displayed first and bottom
|
||
field stored first; <constant>9</constant>: interlaced with bottom field displayed first and top field stored first;
|
||
<constant>14</constant>: interlaced with top field displayed first and bottom field stored first
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.stereo_mode">
|
||
<term><option>--stereo-mode</option> <parameter>TID:n|symbolic-name</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>14</constant> or a symbolic name. All valid numbers & names
|
||
can be listed with the <link linkend="mkvmerge.description.list_stereo_modes"><option>--list-stereo-modes</option> option</link>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Options that only apply to text subtitle tracks</title>
|
||
|
||
<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>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Other options</title>
|
||
|
||
<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>
|
||
|
||
<para>The output format used for the result can be changed with the option <link linkend="mkvmerge.description.identification_format">--identification-format</link>.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.identify_json">
|
||
<term><option>-J</option> <parameter>file-name</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
This is a convenient alias for "<literal>--identification-format json --identify file-name</literal>".
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.identification_format">
|
||
<term><option>-F</option>, <option>--identification-format</option> <parameter>format</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Determines the output format used by the <link linkend="mkvmerge.description.identify"><literal>--identify</literal>
|
||
option</link>. The following formats are supported: <literal>text</literal> (the default if this option isn't used) and
|
||
<literal>json</literal>.
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>The <literal>text</literal> format is short and human-readable. It consists of one line per item found (container, tracks, attachments etc.).</para>
|
||
|
||
<para>This format is not meant to be parsed. The output will be translated into the language &mkvmerge; uses (see also <link
|
||
linkend="mkvmerge.description.ui_language">--ui-language</link>).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
The <literal>json</literal> format outputs a machine-readable JSON representation. This format follows the JSON schema described in
|
||
the following file:
|
||
</para>
|
||
|
||
<para>
|
||
<ulink url="https://mkvtoolnix.download/doc/mkvmerge-identification-output-schema-v20.json"><literal>mkvmerge-identification-output-schema-v20.json</literal></ulink>
|
||
</para>
|
||
|
||
<para>
|
||
All versions of the JSON schema are available both online and in the released source code archives.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.probe_range_percentage">
|
||
<term><option>--probe-range-percentage</option> <parameter>percentage</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
File types such as MPEG program and transport streams (<literal>.vob</literal>, <literal>.m2ts</literal>) require parsing a certain
|
||
amount of data in order to detect all tracks contained in the file. This amount is 0.3% of the source file's size or 10 MB,
|
||
whichever is higher.
|
||
</para>
|
||
|
||
<para>
|
||
If tracks are known to be present but not found then the percentage to probe can be changed with this option. The minimum of 10 MB
|
||
is built-in and cannot be changed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.list_audio_emphasis">
|
||
<term><option>--list-audio-emphasis</option></term>
|
||
<listitem>
|
||
<para>
|
||
Lists all valid numbers & their corresponding symbolic names for the <link
|
||
linkend="mkvmerge.description.audio_emphasis"><option>--audio-emphasis</option></link> option.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.list_languages">
|
||
<term><option>--list-languages</option></term>
|
||
<listitem>
|
||
<para>
|
||
Lists all languages and their ISO 639-2 code which can be used with the <link
|
||
linkend="mkvmerge.description.language"><option>--language</option></link> option.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.list_stereo_modes">
|
||
<term><option>--list-stereo-modes</option></term>
|
||
<listitem>
|
||
<para>
|
||
Lists all valid numbers & their corresponding symbolic names for the <link
|
||
linkend="mkvmerge.description.stereo_mode"><option>--stereo-mode</option></link> option.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.list_types">
|
||
<term><option>-l</option>, <option>--list-types</option></term>
|
||
<listitem>
|
||
<para>
|
||
Lists supported input file types.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.priority">
|
||
<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>
|
||
|
||
<para>Selecting '<literal>lowest</literal>' also causes &mkvmerge; to select idle I/O priority in addition to the lowest possible
|
||
process priority.</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.flush_on_close">
|
||
<term><option>--flush-on-close</option></term>
|
||
<listitem>
|
||
<para>
|
||
Tells the program to flush all data cached in memory to storage when closing files opened for writing.
|
||
This can be used to prevent data loss on power outages or to circumvent certain problems in the operating system or drivers.
|
||
The downside is that multiplexing will take longer as mkvmerge will wait until all data has been written to the storage before exiting.
|
||
See issues #2469 and #2480 on the MKVToolNix bug tracker for in-depth discussions on the pros and cons.
|
||
</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). Entering '<literal>list</literal>' as the <parameter>code</parameter> will cause the program to output a list of
|
||
available translations.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.abort_on_warnings">
|
||
<term><option>--abort-on-warnings</option></term>
|
||
<listitem>
|
||
<para>
|
||
Tells the program to abort after the first warning is emitted. The program's exit code will be 1.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.deterministic">
|
||
<term><option>--deterministic</option> <parameter>seed</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Enables the creation of byte-identical files if the same version of &mkvmerge; is used with the same source files, the same set of
|
||
options and the same seed. Note that the "date" segment information field is not written in this mode.
|
||
</para>
|
||
|
||
<para>The seed can be an arbitrary string and does not have to be a number.</para>
|
||
|
||
<para>
|
||
The result of byte-identical files is only guaranteed under the following conditions:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>The same version of &mkvmerge; built with the same versions of libEBML and libMatroska is used.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The source files used are byte-identical.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The same command line options are used in the same order (with the notable exception of <parameter>--output …</parameter>).</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>
|
||
Using other versions of &mkvmerge; or other command-line options may result in the same byte-identical file but is not guaranteed to do so.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.debug">
|
||
<term><option>--debug</option> <parameter>topic</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Turn on debugging for a specific feature. This option is only useful for developers.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.engage">
|
||
<term><option>--engage</option> <parameter>feature</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Turn on experimental features. A list of available features can be requested with <command>mkvmerge --engage list</command>. These
|
||
features are not meant to be used in normal situations.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.gui_mode">
|
||
<term><option>--gui-mode</option></term>
|
||
<listitem>
|
||
<para>
|
||
Turns on GUI mode. In this mode specially-formatted lines may be output that can tell a controlling GUI what's happening. These
|
||
messages follow the format '<literal>#GUI#message</literal>'. The message may be followed by key/value pairs as in
|
||
'<literal>#GUI#message#key1=value1#key2=value2…</literal>'. Neither the messages nor the keys are ever translated and always output
|
||
in English.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.at_sign">
|
||
<term><option>@</option><parameter>options-file.json</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Reads additional command line arguments from the file <parameter>options-file</parameter>. See the section about <link
|
||
linkend="mkvmerge.option_files">option files</link> for further information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.capabilities">
|
||
<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>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 id="mkvmerge.description.help">
|
||
<term><option>-h</option>, <option>--help</option></term>
|
||
<listitem>
|
||
<para>
|
||
Show usage information and exit.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.description.version">
|
||
<term><option>-V</option>, <option>--version</option></term>
|
||
<listitem>
|
||
<para>
|
||
Show version information and exit.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
</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>
|
||
|
||
<important>
|
||
<para>
|
||
The order of command line options is important. Please read the section <link linkend="mkvmerge.option_order">"Option
|
||
order"</link> if you're new to the program.
|
||
</para>
|
||
</important>
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.option_order">
|
||
<title>Option order</title>
|
||
|
||
<para>
|
||
The order in which options are entered is important for some options. Options fall into two categories:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
Options that affect the whole program and are not tied to any input file. These include but are not limited to
|
||
<option>--command-line-charset</option>, <option>--output</option> or <option>--title</option>. These can appear anywhere on the
|
||
command line.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Options that affect a single input file or a single track in an input file. These options all apply to the following input file on the
|
||
command line. All options applying to the same input (or to tracks from the same input file) file can be written in any order as long
|
||
as they all appear before that input file's name. Examples for options applying to an input file are <option>--no-chapters</option> or
|
||
<option>--chapter-charset</option>. Examples for options applying to a single track are <option>--default-duration</option> or
|
||
<option>--language</option>.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>
|
||
The options are processed from left to right. If an option appears multiple times within the same scope then the last occurrence will be
|
||
used. Therefore the title will be set to "Something else" in the following example:
|
||
</para>
|
||
|
||
<screen>$ mkvmerge -o output.mkv --title 'This and that' input.avi --title 'Something else'</screen>
|
||
|
||
<para>
|
||
The following example shows that using the <option>--language</option> option twice is OK because they're used in different scopes. Even
|
||
though they apply to the same track ID they apply to different input files and therefore have different scopes:
|
||
</para>
|
||
|
||
<screen>$ mkvmerge -o output.mkv --language 0:fre français.ogg --language 0:deu deutsch.ogg</screen>
|
||
</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 ISO 639-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-flag 3 without-lang-codes.mkv --language 0:eng english.srt --default-track-flag 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>
|
||
|
||
<para>
|
||
Turn off the compression for an input file.
|
||
</para>
|
||
|
||
<screen>$ mkvmerge -o no-compression.mkv --compression -1:none MyMovie.avi --compression -1:none mymovie.srt</screen>
|
||
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.track_ids">
|
||
<title>Track IDs</title>
|
||
|
||
<refsect2 id="mkvmerge.track_ids.regular_ids">
|
||
<title>Regular 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 0: video (V_MS/VFW/FOURCC, DIV3)
|
||
Track ID 1: audio (A_MPEG/L3)</screen>
|
||
|
||
<para>
|
||
Do not confuse the track IDs that are assigned to the tracks that are placed in the output MKV file with the track IDs of the input
|
||
files. Only the input file track IDs are used for options needing these values.
|
||
</para>
|
||
|
||
<para>
|
||
Also note that each input file has its own set of track IDs. Therefore the track IDs for file '<filename>file1.ext</filename>' as
|
||
reported by '<literal>mkvmerge --identify</literal>' do not change no matter how many other input files are there or in which position
|
||
'<filename>file1.ext</filename>' is used.
|
||
</para>
|
||
|
||
<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>AC-3</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>
|
||
Most other files: The track IDs are assigned in order the tracks are found in the file starting at 0.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<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>--audio-tracks</option>, <option>--video-tracks</option>, <option>--subtitle-tracks</option>,
|
||
<option>--button-tracks</option> and <option>--track-tags</option>.
|
||
</para>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.track_ids.special_ids">
|
||
<title>Special track IDs</title>
|
||
|
||
<para>
|
||
There are several IDs that have special meaning and do not occur in the identification output.
|
||
</para>
|
||
|
||
<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 special track ID '<constant>-2</constant>' refers to the chapters in a source file. Currently only the <option>--sync</option>
|
||
option uses this special ID. As an alternative to <option>--sync -2:…</option> the option <option>--chapter-sync …</option> can be used.
|
||
</para>
|
||
</refsect2>
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.language_handling">
|
||
<title>Language handling</title>
|
||
|
||
<para>
|
||
&matroska; has support for two different types of language elements: the old, deprecated "Language" element containing ISO 639-2 alpha 3
|
||
codes and the new "LanguageIETF" tags containing IETF BCP 47 language tags. All of &mkvmerge;'s options that accept a language accept a
|
||
BCP 47 language tag. &mkvmerge; will derive the value for the deprecated "Language" element from the BCP 47 language tags wherever possible.
|
||
</para>
|
||
|
||
<para>
|
||
When identifying a file in JSON mode, existing "LanguageIETF" track header elements will be output as the
|
||
<literal>language_ietf</literal> track property.
|
||
</para>
|
||
|
||
<para>
|
||
When writing a file &mkvmerge; will always write the "LanguageIETF", "ChapLanguageIETF" and "TagLanguageIETF" elements (the latter two
|
||
only if chapters or tags are written respectively). In addition to those elements the corresponding old elements will be written; they'll
|
||
be set to the ISO 639-2 code portion of the BCP 47 language tag. For example, when the track language is set to
|
||
<literal>sr-Cyrl-RS</literal> "LanguageIETF" will be set to <literal>sr-Cyrl-RS</literal> and the old "Language" element will be set to
|
||
<literal>srp</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
When reading existing files (Matroska files, XML chapter or tag files etc.) that already contain "…LanguageIETF" elements the existing
|
||
elements will be kept. Otherwise "…LanguageIETF" elements will be added based on command-line options and other existing deprecated
|
||
"…Language" elements.
|
||
</para>
|
||
|
||
<para>
|
||
The creation of the new elements can be disabled completely with the command-line option <option>--disable-language-ietf</option> which
|
||
operates on all three new elements.
|
||
</para>
|
||
|
||
<para>
|
||
You can chose the normalization method applied to extended language sub-tags with the parameter <link
|
||
linkend="mkvmerge.description.normalize_language_ietf"><option>--normalize-language-ietf</option></link>.
|
||
</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>
|
||
|
||
<refsect2 id="mkvmerge.text_files_and_charsets.introduction">
|
||
<title>Introduction</title>
|
||
<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 byte order marker (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>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.text_files_and_charsets.byte_order_markers">
|
||
<title>Byte order markers (BOM)</title>
|
||
|
||
<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>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.text_files_and_charsets.unix">
|
||
<title>Linux and Unix-like systems including macOS</title>
|
||
|
||
<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>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.text_files_and_charsets.windows">
|
||
<title>Windows</title>
|
||
|
||
<para>
|
||
On Windows the default character set used for converting text files is determined by a call to the <function>GetACP()</function> system
|
||
call.
|
||
</para>
|
||
|
||
<para>
|
||
Reading the command line is done with the <function>GetCommandLineW()</function> function which already returns a Unicode
|
||
string. Therefore the option <option>--command-line-charset</option> is ignored on Windows.
|
||
</para>
|
||
|
||
<para>
|
||
Output to the console consists of three scenarios:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
If the output is redirected with the option <link
|
||
linkend="mkvmerge.description.redirect_output"><option>--redirect-output</option></link> then the default charset is UTF-8. This can
|
||
be changed with <link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link>.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
If the output is redirected with <command>cmd.exe</command> itself, e.g. with <literal>mkvinfo file.mkv > info.txt</literal>, then
|
||
the charset is always UTF-8 and cannot be changed.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Otherwise (when writing directly to the console) the Windows function <function>WriteConsoleW()</function> is used and the option
|
||
<link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link> is ignored. The console should be able to
|
||
output all Unicode characters for which the corresponding language support is installed (e.g. Chinese characters might not be
|
||
displayed on English Windows versions).
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.text_files_and_charsets.options">
|
||
<title>Command line options</title>
|
||
|
||
<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. On non-Windows systems the default for
|
||
the output charset is the system's current charset. On Windows it defaults to UTF-8 both for redirecting with <link
|
||
linkend="mkvmerge.description.redirect_output"><option>--redirect-output</option></link> and with <command>cmd.exe</command> itself,
|
||
e.g. <literal>mkvinfo file.mkv > info.txt</literal>.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</refsect2>
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.option_files">
|
||
<title>Option files</title>
|
||
|
||
<para>
|
||
An option file is a file &mkvmerge; can read additional command line arguments from. This can be used in order to circumvent certain
|
||
limitations of the shell or the operating system when executing external programs like a limited command line length.
|
||
</para>
|
||
|
||
<para>
|
||
An option file contains JSON-formatted data. Its content must be a valid JSON array consisting solely of JSON strings. The file's
|
||
encoding must be UTF-8. The file should not start with a byte order marker (<abbrev>BOM</abbrev>), but if one exists, it will be skipped.
|
||
</para>
|
||
|
||
<para>
|
||
The rules for escaping special characters inside JSON are the ones in the official JSON specification, <ulink url="https://tools.ietf.org/html/rfc7159">RFC 7159</ulink>.
|
||
</para>
|
||
|
||
<para>
|
||
The option file's name itself must be specified as a command line argument prefixed with a '<literal>@</literal>' character.
|
||
</para>
|
||
|
||
<para>
|
||
The command line '<command>mkvmerge -o "my file.mkv" -A "a movie.avi" sound.ogg</command>' could be converted into the following
|
||
JSON option file called e.g. '<filename>options.json</filename>':
|
||
</para>
|
||
|
||
<programlisting>[
|
||
"-o",
|
||
"c:\\Matroska\\my file.mkv",
|
||
"--title",
|
||
"#65",
|
||
"-A",
|
||
"a movie.avi",
|
||
"sound.ogg"
|
||
]</programlisting>
|
||
|
||
<para>
|
||
The corresponding command would then be '<command>mkvmerge @options.json</command>'.
|
||
</para>
|
||
</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 timestamps 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 timestamps 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. '<code>0x41 0xda 0x73 0x66
|
||
0xd9 0xcf 0xb2 0x1e 0xae 0x78 0xeb 0xb4 0x5e 0xca 0xb3 0x93</code>'. 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.
|
||
'<code>41da7366d9cfb21eae78ebb45ecab393</code>'.
|
||
</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-mime-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="https://www.matroska.org/">the &matroska; website</ulink>.
|
||
</para>
|
||
|
||
<para>
|
||
&mkvmerge; supports two kinds of chapter files as its input. The first format, called 'simple chapter format', 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>
|
||
|
||
<para>
|
||
Apart from dedicated chapter files &mkvmerge; can also read chapters from other file formats (e.g. MP4, Ogg, Blu-rays or DVDs).
|
||
</para>
|
||
|
||
<refsect2 id="mkvmerge.chapters.simple">
|
||
<title>The simple chapter format</title>
|
||
|
||
<para>
|
||
This format consists of pairs of lines that start with '<literal>CHAPTERxx=</literal>' and '<literal>CHAPTERxxNAME=</literal>'
|
||
respectively. The first one contains the start timestamp 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 all chapters 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 id="mkvmerge.chapters.xml">
|
||
<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>
|
||
|
||
<para>
|
||
The following lists the supported XML tags, their data types and, where appropriate, the valid range for their values:
|
||
</para>
|
||
|
||
<screen>Chapters (master)
|
||
EditionEntry (master)
|
||
EditionUID (unsigned integer, valid range: 1 <= value)
|
||
EditionFlagHidden (unsigned integer, valid range: 0 <= value <= 1)
|
||
EditionFlagDefault (unsigned integer, valid range: 0 <= value <= 1)
|
||
EditionFlagOrdered (unsigned integer, valid range: 0 <= value <= 1)
|
||
ChapterAtom (master)
|
||
ChapterAtom (master)
|
||
ChapterUID (unsigned integer, valid range: 1 <= value)
|
||
ChapterTimeStart (unsigned integer)
|
||
ChapterTimeEnd (unsigned integer)
|
||
ChapterFlagHidden (unsigned integer, valid range: 0 <= value <= 1)
|
||
ChapterFlagEnabled (unsigned integer, valid range: 0 <= value <= 1)
|
||
ChapterSegmentUID (binary, valid range: 1 <= length in bytes)
|
||
ChapterSegmentEditionUID (unsigned integer, valid range: 1 <= value)
|
||
ChapterPhysicalEquiv (unsigned integer)
|
||
ChapterTrack (master)
|
||
ChapterTrackNumber (unsigned integer, valid range: 1 <= value)
|
||
ChapterDisplay (master)
|
||
ChapterString (UTF-8 string)
|
||
ChapterLanguage (UTF-8 string)
|
||
ChapterCountry (UTF-8 string)
|
||
ChapterProcess (master)
|
||
ChapterProcessCodecID (unsigned integer)
|
||
ChapterProcessPrivate (binary)
|
||
ChapterProcessCommand (master)
|
||
ChapterProcessTime (unsigned integer)
|
||
ChapterProcessData (binary)</screen>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.chapters.blurays">
|
||
<title>Reading chapters from Blu-rays</title>
|
||
|
||
<para>
|
||
&mkvmerge; can read chapters from unencrypted Blu-rays. For that you can use the path to one of the MPLS play lists with the
|
||
<parameter>--chapters</parameter> parameter.
|
||
</para>
|
||
|
||
<para>
|
||
Example: <literal>--chapters /srv/blurays/BigBuckBunny/BDMV/PLAYLIST/00001.mpls</literal>
|
||
</para>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.chapters.dvds">
|
||
<title>Reading chapters from DVDs</title>
|
||
|
||
<para>
|
||
When MKVToolNix is compiled with the <productname>libdvdread</productname> library, &mkvmerge; can read chapters from DVDs. For that you
|
||
can use the path to one of the folders or files on the DVD with the <parameter>--chapters</parameter> parameter. As DVDs can contain
|
||
more than one title and each title has its own set of chapters, you can append a colon and the desired title number to the end of the
|
||
file name argument. The title number defaults to 1.
|
||
</para>
|
||
|
||
<para>
|
||
Example: <literal>--chapters /srv/dvds/BigBuckBunny/VIDEO_TS:2</literal>
|
||
</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 timestamps will be offset to match the new timestamps 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;'s tag system is similar to that of other containers: a set of <parameter>KEY=VALUE</parameter> pairs. 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 system.
|
||
</para>
|
||
</refsect2>
|
||
|
||
<refsect2 id="mkvmerge.tags.scope">
|
||
<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="https://www.matroska.org/technical/specs/index.html">&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 id="mkvmerge.tags.example">
|
||
<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 id="mkvmerge.tags.file_format">
|
||
<title>Tag file format</title>
|
||
<para>
|
||
&mkvmerge; supports a &xml; based tag file format. The format is very closely modeled after the <ulink
|
||
url="https://www.matroska.org/technical/specs/index.html">&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 id="mkvmerge.tags.data_types">
|
||
<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 Base64 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 Base64 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>
|
||
|
||
<refsect2 id="mkvmerge.tags.xml">
|
||
<title>Known tags for the XML file format</title>
|
||
|
||
<para>
|
||
The following lists the supported XML tags, their data types and, where appropriate, the valid range for their values:
|
||
</para>
|
||
|
||
<screen>Tags (master)
|
||
Tag (master)
|
||
Targets (master)
|
||
TargetTypeValue (unsigned integer)
|
||
TargetType (UTF-8 string)
|
||
TrackUID (unsigned integer)
|
||
EditionUID (unsigned integer)
|
||
ChapterUID (unsigned integer)
|
||
AttachmentUID (unsigned integer)
|
||
Simple (master)
|
||
Simple (master)
|
||
Name (UTF-8 string)
|
||
TagLanguage (UTF-8 string)
|
||
DefaultLanguage (unsigned integer)
|
||
String (UTF-8 string)
|
||
Binary (binary)</screen>
|
||
</refsect2>
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.segmentinfo">
|
||
<title>Segment information</title>
|
||
|
||
<para>
|
||
With a segment info XML file it is possible to set certain values in the "segment information" header field of a &matroska;
|
||
file. All of these values cannot be set via other command line options.
|
||
</para>
|
||
|
||
<para>
|
||
Other "segment information" header fields can be set via command line options but not via the XML file. This includes e.g. the
|
||
<option><link linkend="mkvmerge.description.title">--title</link></option> and the <option><link
|
||
linkend="mkvmerge.description.timestamp_scale">--timestamp-scale</link></option> options.
|
||
</para>
|
||
|
||
<para>
|
||
There are other elements that can be set neither via command line options nor via the XML files. These include the following elements:
|
||
<varname>DateUTC</varname> (also known as the "muxing date"), <varname>MuxingApp</varname>, <varname>WritingApp</varname>
|
||
and <varname>Duration</varname>. They're always set by &mkvmerge; itself.
|
||
</para>
|
||
|
||
<para>
|
||
The following lists the supported XML tags, their data types and, where appropriate, the valid range for their values:
|
||
</para>
|
||
|
||
<screen>Info (master)
|
||
SegmentUID (binary, valid range: length in bytes == 16)
|
||
SegmentFilename (UTF-8 string)
|
||
PreviousSegmentUID (binary, valid range: length in bytes == 16)
|
||
PreviousSegmentFilename (UTF-8 string)
|
||
NextSegmentUID (binary, valid range: length in bytes == 16)
|
||
NextSegmentFilename (UTF-8 string)
|
||
SegmentFamily (binary, valid range: length in bytes == 16)
|
||
ChapterTranslate (master)
|
||
ChapterTranslateEditionUID (unsigned integer)
|
||
ChapterTranslateCodec (unsigned integer)
|
||
ChapterTranslateID (binary)</screen>
|
||
</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} [segment information] [track information] {attachments} {chapters} [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_timestamp_files">
|
||
<title>External timestamp files</title>
|
||
<para>
|
||
&mkvmerge; allows the user to chose the timestamps 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>AC-3</abbrev> this would be a
|
||
packet containing <constant>1536</constant> samples.
|
||
</para>
|
||
|
||
<para>
|
||
Timestamp 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 timestamps then your command line must look something like this:
|
||
</para>
|
||
|
||
<screen>$ mkvmerge ... --timestamps 0:my_timestamps.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>Timestamp 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># timestamp format v1
|
||
assume 27.930
|
||
800,1000,25
|
||
1500,1700,30</screen>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Timestamp file format v2</title>
|
||
|
||
<para>
|
||
In this format each line contains a timestamp for the corresponding frame. This timestamp 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 timestamp lines as there
|
||
are frames in the track. The timestamps in this file must be sorted. Example for 25fps:
|
||
</para>
|
||
|
||
<screen># timestamp format v2
|
||
0
|
||
40
|
||
80</screen>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Timestamp 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 timestamps 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># timestamp format v3
|
||
assume 0.0
|
||
25.325
|
||
7.530,38.236
|
||
gap, 10.050
|
||
2.000,38.236</screen>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Timestamp file format v4</title>
|
||
<para>
|
||
This format is identical to the v2 format. The only difference is that the timestamps do not have to be sorted. This format should
|
||
almost never be used.
|
||
</para>
|
||
</refsect2>
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.exit_codes">
|
||
<title>Exit codes</title>
|
||
|
||
<para>
|
||
&mkvmerge; exits with one of three exit codes:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<constant>0</constant> -- This exit code 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 occurred. &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.environment_variables">
|
||
<title>Environment variables</title>
|
||
|
||
<para>
|
||
&mkvmerge; uses the default variables that determine the system's locale (e.g. <varname>LANG</varname> and the <varname>LC_*</varname>
|
||
family). Additional variables:
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="mkvmerge.environment_variables.debug">
|
||
<term><varname>MKVMERGE_DEBUG</varname>, <varname>MKVTOOLNIX_DEBUG</varname> and its short form <varname>MTX_DEBUG</varname></term>
|
||
<listitem>
|
||
<para>The content is treated as if it had been passed via the <link
|
||
linkend="mkvmerge.description.debug"><option>--debug</option></link> option.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="mkvmerge.environment_variables.engage">
|
||
<term><varname>MKVMERGE_ENGAGE</varname>, <varname>MKVTOOLNIX_ENGAGE</varname> and its short form <varname>MTX_ENGAGE</varname></term>
|
||
<listitem>
|
||
<para>The content is treated as if it had been passed via the <link
|
||
linkend="mkvmerge.description.engage"><option>--engage</option></link> option.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.seealso">
|
||
<title>See also</title>
|
||
<para>
|
||
&mkvinfo;, &mkvextract;, &mkvpropedit;, &mtxgui;
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 id="mkvmerge.www">
|
||
<title>WWW</title>
|
||
<para>
|
||
The latest version can always be found at <ulink url="https://mkvtoolnix.download/">the MKVToolNix homepage</ulink>.
|
||
</para>
|
||
</refsect1>
|
||
|
||
</refentry>
|