1<?xml version="1.0" encoding="utf-8"?> 2 3<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 4[ 5<!ENTITY product "mkvmerge"> 6<!ENTITY version "65.0.0"> 7<!ENTITY date "2022-02-06"> 8 9<!ENTITY mkvmerge "<citerefentry><refentrytitle>mkvmerge</refentrytitle><manvolnum>1</manvolnum></citerefentry>"> 10<!ENTITY mkvinfo "<citerefentry><refentrytitle>mkvinfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>"> 11<!ENTITY mkvextract "<citerefentry><refentrytitle>mkvextract</refentrytitle><manvolnum>1</manvolnum></citerefentry>"> 12<!ENTITY mkvpropedit "<citerefentry><refentrytitle>mkvpropedit</refentrytitle><manvolnum>1</manvolnum></citerefentry>"> 13<!ENTITY mtxgui "<citerefentry><refentrytitle>mkvtoolnix-gui</refentrytitle><manvolnum>1</manvolnum></citerefentry>"> 14 15<!ENTITY matroska "<productname>Matroska</productname>"> 16<!ENTITY oggvorbis "<productname>OggVorbis</productname>"> 17<!ENTITY xml "<abbrev>XML</abbrev>"> 18 19]> 20 21<refentry lang="en" id="mkvmerge"> 22 <refentryinfo> 23 <productname>&product;</productname> 24 <date>&date;</date> 25 <authorgroup> 26 <author> 27 <contrib>Developer</contrib> 28 <firstname>Moritz</firstname> 29 <surname>Bunkus</surname> 30 <email>moritz@bunkus.org</email> 31 </author> 32 </authorgroup> 33 </refentryinfo> 34 <refmeta> 35 <refentrytitle>&product;</refentrytitle> 36 <manvolnum>1</manvolnum> 37 <refmiscinfo class="version">&version;</refmiscinfo> 38 <refmiscinfo class="date">&date;</refmiscinfo> 39 <refmiscinfo class="source">MKVToolNix</refmiscinfo> 40 <refmiscinfo class="manual">User Commands</refmiscinfo> 41 </refmeta> 42 43 <refnamediv> 44 <refname>&product;</refname> 45 <refpurpose>Merge multimedia streams into a &matroska; file</refpurpose> 46 </refnamediv> 47 48 <refsynopsisdiv id="mkvmerge.synopsis"> 49 <title>Synopsis</title> 50 <cmdsynopsis> 51 <command>mkvmerge</command> 52 <arg>global options</arg> 53 <arg choice="req">-o out</arg> 54 <arg>options1</arg> 55 <arg choice="req">file1</arg> 56 <arg> 57 <arg>options2</arg> 58 <arg choice="req">file2</arg> 59 </arg> 60 <arg>@options-file.json</arg> 61 </cmdsynopsis> 62 </refsynopsisdiv> 63 64 <refsect1 id="mkvmerge.description"> 65 <title>Description</title> 66 <para> 67 This program takes the input from several media files and joins their streams (all of them or just a selection) into 68 a &matroska; file; see <ulink url="https://www.matroska.org/">the &matroska; website</ulink>. 69 </para> 70 71 <important> 72 <para> 73 The order of command line options is important. Please read the section <link linkend="mkvmerge.option_order">"Option 74 order"</link> if you're new to the program. 75 </para> 76 </important> 77 78 <refsect2> 79 <title>Global options</title> 80 81 <variablelist> 82 <varlistentry id="mkvmerge.description.verbose"> 83 <term><option>-v</option>, <option>--verbose</option></term> 84 <listitem> 85 <para>Increase verbosity.</para> 86 </listitem> 87 </varlistentry> 88 89 <varlistentry id="mkvmerge.description.quiet"> 90 <term><option>-q</option>, <option>--quiet</option></term> 91 <listitem> 92 <para>Suppress status output.</para> 93 </listitem> 94 </varlistentry> 95 96 <varlistentry id="mkvmerge.description.output"> 97 <term><option>-o</option>, <option>--output</option> <parameter>file-name</parameter></term> 98 <listitem> 99 <para>Write to the file <parameter>file-name</parameter>. If splitting is used then this parameter is treated a bit differently. See 100 the explanation for the <link linkend="mkvmerge.description.split"><option>--split</option></link> option for details.</para> 101 </listitem> 102 </varlistentry> 103 104 <varlistentry id="mkvmerge.description.webm"> 105 <term><option>-w</option>, <option>--webm</option></term> 106 <listitem> 107 <para>Create a WebM compliant file. This is also turned on if the output file name's extension is "webm". This mode enforces 108 several restrictions. The only allowed codecs are VP8, VP9 video and Opus, Vorbis audio tracks. The DocType header item is changed to 109 "webm". 110 </para> 111 112 <para> 113 For chapters and tags only a subset of elements are allowed. &mkvmerge; will automatically remove all elements not allowed by the 114 specification. 115 </para> 116 </listitem> 117 </varlistentry> 118 119 <varlistentry id="mkvmerge.description.title"> 120 <term><option>--title</option> <parameter>title</parameter></term> 121 <listitem> 122 <para>Sets the general title for the output file, e.g. the movie name.</para> 123 </listitem> 124 </varlistentry> 125 126 <varlistentry id="mkvmerge.description.default_language"> 127 <term><option>--default-language</option> <parameter>language-code</parameter></term> 128 <listitem> 129 <para>Sets the default language code that will be used for tracks for which no language is set with the <link 130 linkend="mkvmerge.description.language"><option>--language</option></link> option and for which the source container doesn't provide a 131 language.</para> 132 133 <para>The default language code is '<literal>und</literal>' for 'undefined'.</para> 134 </listitem> 135 </varlistentry> 136 </variablelist> 137 </refsect2> 138 139 <refsect2> 140 <title>Segment info handling (global options)</title> 141 142 <variablelist> 143 <varlistentry id="mkvmerge.description.segmentinfo"> 144 <term><option>--segmentinfo</option> <parameter>filename.xml</parameter></term> 145 <listitem> 146 <para> 147 Read segment information from an <abbrev>XML</abbrev> file. This file can contain the segment family <abbrev>UID</abbrev>, segment 148 <abbrev>UID</abbrev>, previous and next segment <abbrev>UID</abbrev> elements. An example file and a <abbrev>DTD</abbrev> are included 149 in the MKVToolNix distribution. 150 </para> 151 152 <para> 153 See the section about <link linkend="mkvmerge.segmentinfo">segment info XML files</link> below for details. 154 </para> 155 </listitem> 156 </varlistentry> 157 158 <varlistentry id="mkvmerge.description.segment_uid"> 159 <term><option>--segment-uid</option> <parameter>SID1,SID2,...</parameter></term> 160 <listitem> 161 <para> 162 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 163 the "0x" prefix, with or without spaces, exactly 32 digits. 164 </para> 165 166 <para> 167 If SID starts with = then its rest is interpreted as the name of a Matroska file whose segment UID is read and used. 168 </para> 169 170 <para> 171 Each file created contains one segment, and each segment has one segment UID. If more segment UIDs are specified than segments are 172 created then the surplus UIDs are ignored. If fewer UIDs are specified than segments are created then random UIDs will be created for 173 them. 174 </para> 175 </listitem> 176 </varlistentry> 177 </variablelist> 178 </refsect2> 179 180 <refsect2> 181 <title>Chapter and tag handling (global options)</title> 182 183 <variablelist> 184 <varlistentry id="mkvmerge.description.chapter_language"> 185 <term><option>--chapter-language</option> <parameter>language-code</parameter></term> 186 <listitem> 187 <para> 188 Sets the ISO 639-2 language code that is written for each chapter entry. Defaults to '<literal>eng</literal>'. See the section about 189 <link linkend="mkvmerge.chapters">chapters</link> below for details. 190 </para> 191 192 <para> 193 This option can be used both for simple chapter files and for source files that contain chapters but no information about the 194 chapters' language, e.g. MP4 and OGM files. 195 </para> 196 197 <para> 198 The language set with this option is also used when chapters are generated with the <link 199 linkend="mkvmerge.description.generate_chapters"><option>--generate-chapters</option> option</link>. 200 </para> 201 </listitem> 202 </varlistentry> 203 204 <varlistentry id="mkvmerge.description.chapter_charset"> 205 <term><option>--chapter-charset</option> <parameter>character-set</parameter></term> 206 <listitem> 207 <para> 208 Sets the character set that is used for the conversion to UTF-8 for simple chapter files. See the section about <link 209 linkend="mkvmerge.text_files_and_charsets">text files and character sets</link> for an explanation how &mkvmerge; converts between 210 character sets. 211 </para> 212 213 <para> 214 This switch does also apply to chapters that are copied from certain container types, e.g. Ogg/OGM and MP4 files. 215 See the section about chapters below for details. 216 </para> 217 </listitem> 218 </varlistentry> 219 220 <varlistentry id="mkvmerge.description.chapter_sync"> 221 <term><option>--chapter-sync</option> <parameter>d<optional>,o<optional>/p</optional></optional></parameter></term> 222 <listitem> 223 <para> 224 Adjust the timestamps of the chapters in the following source file by <parameter>d</parameter> ms. Alternatively you can use the 225 <option>--sync</option> option with the special track ID <constant>-2</constant> (see section <link 226 linkend="mkvmerge.track_ids.special_ids">special track IDs</link>). 227 </para> 228 229 <para> 230 <parameter>o</parameter>/<parameter>p</parameter>: adjust the timestamps by <parameter>o</parameter>/<parameter>p</parameter> to fix 231 linear drifts. <parameter>p</parameter> defaults to 1 if omitted. Both <parameter>o</parameter> and <parameter>p</parameter> can be 232 floating point numbers. 233 </para> 234 235 <para> 236 Defaults: no manual sync correction (which is the same as <parameter>d</parameter> = <constant>0</constant> and 237 <parameter>o</parameter>/<parameter>p</parameter> = <constant>1.0</constant>). 238 </para> 239 240 <para> 241 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 242 </para> 243 </listitem> 244 </varlistentry> 245 246 <varlistentry id="mkvmerge.description.generate_chapters"> 247 <term><option>--generate-chapters</option> <parameter>mode</parameter></term> 248 <listitem> 249 <para> 250 &mkvmerge; can create chapters automatically. The following two modes are currently supported: 251 </para> 252 253 <itemizedlist> 254 <listitem> 255 <para> 256 '<literal>when-appending</literal>' – This mode creates one chapter at the start and one chapter whenever a file is appended. 257 </para> 258 259 <para> 260 This mode also works with split modes '<literal>parts:</literal>' and '<literal>parts-frames:</literal>'. For these modes one 261 chapter will be generated for each appended timestamp range (those whose start timestamps are prefixed with 262 '<literal>+</literal>'). 263 </para> 264 265 <note> 266 <para> 267 &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 268 more video tracks are muxed the first one is used. Otherwise the first audio track is used. 269 </para> 270 </note> 271 </listitem> 272 273 <listitem> 274 <para> 275 '<literal>interval:</literal><parameter>time-spec</parameter>' – This mode creates one chapter at fixed intervals given by 276 <parameter>time-spec</parameter>. The format is either the form <parameter>HH:MM:SS.nnnnnnnnn</parameter> or a number followed by 277 one of the units '<literal>s</literal>', '<literal>ms</literal>' or '<literal>us</literal>'. 278 </para> 279 280 <para> 281 Example: <literal>--generate-chapters interval:45s</literal> 282 </para> 283 </listitem> 284 </itemizedlist> 285 286 <para> 287 The names for the new chapters are controlled by the option <link 288 linkend="mkvmerge.description.generate_chapters_name_template">--generate-chapters-name-template</link>. The language is set with 289 <link linkend="mkvmerge.description.chapter_language">--chapter-language</link> which must occur before 290 <option>--generate-chapters</option>. 291 </para> 292 </listitem> 293 </varlistentry> 294 295 <varlistentry id="mkvmerge.description.generate_chapters_name_template"> 296 <term><option>--generate-chapters-name-template</option> <parameter>template</parameter></term> 297 <listitem> 298 <para> 299 This sets the name template for chapter names generated by the option <link 300 linkend="mkvmerge.description.generate_chapters">--generate-chapters</link>. If the option is not used then default '<literal>Chapter 301 <NUM:2></literal>' will be used. 302 </para> 303 304 <para> 305 There are several variables that can be used in the template that are replaced by their actual values when a chapter is generated. 306 The string '<literal><NUM></literal>' will be replaced by the chapter number. The string '<literal><START></literal>' 307 will be replaced by the chapter's start timestamp. 308 </para> 309 310 <para> 311 The strings <literal>'<FILE_NAME>'</literal> and <literal>'<FILE_NAME_WITH_EXT>'</literal> are only filled when 312 generating chapters for appended files. They will be replaced by the appended file's name wihtout respectively with its extension. 313 Note that only the file's base name and extension are inserted, not its directory or drive components. 314 </para> 315 316 <para> 317 You can specify a minimum number of places for the chapter number with '<literal><NUM:places></literal>', e.g. '<literal><NUM:3></literal>'. 318 The resulting number will be padded with leading zeroes if the number of places is less than specified. 319 </para> 320 321 <para> 322 You can control the format used by the start timestamp with <literal><START:format></literal>. The format defaults to 323 '<literal>%H:%M:%S</literal>' if none is given. Valid format codes are: 324 </para> 325 326 <itemizedlist> 327 <listitem> 328 <para><literal>%h</literal> – hours</para> 329 </listitem> 330 <listitem> 331 <para><literal>%H</literal> – hours zero-padded to two places</para> 332 </listitem> 333 <listitem> 334 <para><literal>%m</literal> – minutes</para> 335 </listitem> 336 <listitem> 337 <para><literal>%M</literal> – minutes zero-padded to two places</para> 338 </listitem> 339 <listitem> 340 <para><literal>%s</literal> – seconds</para> 341 </listitem> 342 <listitem> 343 <para><literal>%S</literal> – seconds zero-padded to two places</para> 344 </listitem> 345 <listitem> 346 <para><literal>%n</literal> – nanoseconds with nine places</para> 347 </listitem> 348 <listitem> 349 <para><literal>%<1-9>n</literal> – nanoseconds with up to nine places (e.g. three places with <literal>%3n</literal>)</para> 350 </listitem> 351 </itemizedlist> 352 </listitem> 353 </varlistentry> 354 355 <varlistentry id="mkvmerge.description.cue_chapter_name_format"> 356 <term><option>--cue-chapter-name-format</option> <parameter>format</parameter></term> 357 <listitem> 358 <para> 359 &mkvmerge; supports reading <abbrev>CUE</abbrev> sheets for audio files as the input for chapters. <abbrev>CUE</abbrev> sheets usually 360 contain the entries <varname>PERFORMER</varname> and <varname>TITLE</varname> for each index entry. &mkvmerge; uses these two strings 361 in order to construct the chapter name. With this option the format used for this name can be set. 362 </para> 363 364 <para> 365 If this option is not given then &mkvmerge; defaults to the format '<code>%p - %t</code>' (the performer, followed by a space, a dash, 366 another space and the title). 367 </para> 368 369 <para> 370 If the format is given then everything except the following meta characters is copied as-is, and the meta 371 characters are replaced like this: 372 </para> 373 374 <itemizedlist> 375 <listitem> 376 <para><parameter>%p</parameter> is replaced by the current entry's <varname>PERFORMER</varname> string,</para> 377 </listitem> 378 <listitem> 379 <para><parameter>%t</parameter> is replaced by the current entry's <varname>TITLE</varname> string,</para> 380 </listitem> 381 <listitem> 382 <para><parameter>%n</parameter> is replaced by the current track number and</para> 383 </listitem> 384 <listitem> 385 <para><parameter>%N</parameter> is replaced by the current track number padded with a leading zero if 386 it is < 10.</para> 387 </listitem> 388 </itemizedlist> 389 </listitem> 390 </varlistentry> 391 392 <varlistentry id="mkvmerge.description.chapters"> 393 <term><option>--chapters</option> <parameter>file-name</parameter></term> 394 <listitem> 395 <para> 396 Read chapter information from the file <parameter>file-name</parameter>. See the section about <link 397 linkend="mkvmerge.chapters">chapters</link> below for details. 398 </para> 399 </listitem> 400 </varlistentry> 401 402 <varlistentry id="mkvmerge.description.global_tags"> 403 <term><option>--global-tags</option> <parameter>file-name</parameter></term> 404 <listitem> 405 <para> 406 Read global tags from the file <parameter>file-name</parameter>. See the section about <link linkend="mkvmerge.tags">tags</link> below 407 for details. 408 </para> 409 </listitem> 410 </varlistentry> 411 </variablelist> 412 </refsect2> 413 414 <refsect2> 415 <title>General output control (advanced global options)</title> 416 417 <variablelist> 418 <varlistentry id="mkvmerge.description.track_order"> 419 <term><option>--track-order</option> <parameter>FID1:TID1,FID2:TID2,...</parameter></term> 420 <listitem> 421 <para> 422 This option changes the order in which the tracks for an input file are created. The argument is a comma separated list of pairs 423 IDs. Each pair contains first the file ID (<parameter>FID1</parameter>) which is simply the number of the file on the command line 424 starting at 0. The second is a track ID (<parameter>TID1</parameter>) from that file. If some track IDs are omitted then those tracks 425 are created after the ones given with this option have been created. 426 </para> 427 </listitem> 428 </varlistentry> 429 430 <varlistentry id="mkvmerge.description.cluster_length"> 431 <term><option>--cluster-length</option> <parameter>spec</parameter></term> 432 <listitem> 433 <para> 434 Limit the number of data blocks or the duration of data in each cluster. The <parameter>spec</parameter> parameter can either be a 435 number <parameter>n</parameter> without a unit or a number <parameter>d</parameter> postfixed with '<literal>ms</literal>'. 436 </para> 437 438 <para> 439 If no unit is used then &mkvmerge; will put at most <parameter>n</parameter> data blocks into each cluster. The maximum number of 440 blocks is 65535. 441 </para> 442 443 <para> 444 If the number <parameter>d</parameter> is postfixed with '<literal>ms</literal>' then &mkvmerge; puts at most <parameter>d</parameter> 445 milliseconds of data into each cluster. The minimum for <parameter>d</parameter> is '<literal>100ms</literal>', and the maximum is 446 '<literal>32000ms</literal>'. 447 </para> 448 449 <para> 450 &mkvmerge; defaults to putting at most 65535 data blocks and 5000ms of data into a cluster. 451 </para> 452 453 <para> 454 Programs trying to find a certain frame can only seek directly to a cluster and have to read the whole cluster afterwards. Therefore 455 creating larger clusters may lead to imprecise or slow seeking. 456 </para> 457 </listitem> 458 </varlistentry> 459 460 <varlistentry id="mkvmerge.description.clusters_in_meta_seek"> 461 <term><option>--clusters-in-meta-seek</option></term> 462 <listitem> 463 <para> 464 Tells &mkvmerge; to create a meta seek element at the end of the file containing all clusters. See also the section about the 465 <link linkend="mkvmerge.file_layout">&matroska; file layout</link>. 466 </para> 467 </listitem> 468 </varlistentry> 469 470 471 <varlistentry id="mkvmerge.description.timestamp_scale"> 472 <term><option>--timestamp-scale</option> <parameter>factor</parameter></term> 473 <listitem> 474 <para> 475 Forces the timestamp scale factor to <parameter>factor</parameter>. Valid values are in the range 476 <constant>1000</constant>..<constant>10000000</constant> or the special value <constant>-1</constant>. 477 </para> 478 479 <para> 480 Normally &mkvmerge; will use a value of <constant>1000000</constant> which means that timestamps and durations will have a precision of 481 1ms. For files that will not contain a video track but at least one audio track &mkvmerge; will automatically chose a timestamp scale 482 factor so that all timestamps and durations have a precision of one audio sample. This causes bigger overhead but allows precise 483 seeking and extraction. 484 </para> 485 486 <para> 487 If the special value <constant>-1</constant> is used then &mkvmerge; will use sample precision even if a video track is present. 488 </para> 489 </listitem> 490 </varlistentry> 491 492 <varlistentry id="mkvmerge.description.enable_durations"> 493 <term><option>--enable-durations</option></term> 494 <listitem> 495 <para> 496 Write durations for all blocks. This will increase file size and does not offer any additional value for players at the moment. 497 </para> 498 </listitem> 499 </varlistentry> 500 501 <varlistentry id="mkvmerge.description.no_cues"> 502 <term><option>--no-cues</option></term> 503 <listitem> 504 <para> 505 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 506 without the cue data, but seeking will probably be imprecise and slower. Use this only if you're really desperate for space or for 507 testing purposes. See also option <link linkend="mkvmerge.description.cues"><option>--cues</option></link> which can be specified for 508 each input file. 509 </para> 510 </listitem> 511 </varlistentry> 512 513 <varlistentry id="mkvmerge.description.no_date"> 514 <term><option>--no-date</option></term> 515 <listitem> 516 <para> 517 By default &mkvmerge; sets the "date" segment information field to the time & date when multiplexing started. With this option 518 that field is not written at all. 519 </para> 520 </listitem> 521 </varlistentry> 522 523 <varlistentry id="mkvmerge.description.disable_lacing"> 524 <term><option>--disable-lacing</option></term> 525 <listitem> 526 <para> 527 Disables lacing for all tracks. This will increase the file's size, especially if there are many audio tracks. This option is not 528 intended for everyday use. 529 </para> 530 </listitem> 531 </varlistentry> 532 533 <varlistentry id="mkvmerge.description.disable_track_statistics_tags"> 534 <term><option>--disable-track-statistics-tags</option></term> 535 <listitem> 536 <para> 537 Normally &mkvmerge; will write certain tags with statistics for each track. If such tags are already present then they will be 538 overwritten. The tags are <constant>BPS</constant>, <constant>DURATION</constant>, <constant>NUMBER_OF_BYTES</constant> and 539 <constant>NUMBER_OF_FRAMES</constant>. 540 </para> 541 542 <para> 543 Enabling this option prevents &mkvmerge; from writing those tags and from touching any existing tags with same names. 544 </para> 545 </listitem> 546 </varlistentry> 547 548 <varlistentry id="mkvmerge.description.disable_language_ietf"> 549 <term><option>--disable-language-ietf</option></term> 550 <listitem> 551 <para> 552 Normally &mkvmerge; will write the new IETF BCP 47 language elements in addition to the legacy language elements in track headers, 553 chapters and tags. If this option is used, only the legacy elements are written. 554 </para> 555 </listitem> 556 </varlistentry> 557 </variablelist> 558 </refsect2> 559 560 <refsect2> 561 <title>File splitting, linking, appending and concatenation (more global options)</title> 562 563 <variablelist> 564 <varlistentry id="mkvmerge.description.split"> 565 <term><option>--split</option> <parameter>specification</parameter></term> 566 567 <listitem> 568 <para> 569 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. 570 Therefore the split point may be a bit off from what the user has specified. 571 </para> 572 573 <para> 574 At the moment &mkvmerge; supports the following modes: 575 </para> 576 577 <orderedlist> 578 <listitem> 579 <para> 580 Splitting by size. 581 </para> 582 583 <para> 584 Syntax: <option>--split</option> <optional><literal>size:</literal></optional><parameter>d</parameter><optional>k|m|g</optional> 585 </para> 586 587 <para> 588 Examples: <code>--split size:700m</code> or <code>--split 150000000</code> 589 </para> 590 591 <para> 592 The parameter <parameter>d</parameter> may end with '<literal>k</literal>', '<literal>m</literal>' or '<literal>g</literal>' to 593 indicate that the size is in KB, MB or GB respectively. Otherwise a size in bytes is assumed. After the current output file has 594 reached this size limit a new one will be started. 595 </para> 596 597 <para> 598 The '<literal>size:</literal>' prefix may be omitted for compatibility reasons. 599 </para> 600 </listitem> 601 602 <listitem> 603 <para> 604 Splitting after a duration. 605 </para> 606 607 <para> 608 Syntax: <option>--split</option> <optional><literal>duration:</literal></optional><parameter>HH:MM:SS.nnnnnnnnn</parameter>|<parameter>d</parameter>s 609 </para> 610 611 <para> 612 Examples: <code>--split duration:00:60:00.000</code> or <code>--split 3600s</code> 613 </para> 614 615 <para> 616 The parameter must either have the form <parameter>HH:MM:SS.nnnnnnnnn</parameter> for specifying the duration in up to nano-second 617 precision or be a number <parameter>d</parameter> followed by the letter '<literal>s</literal>' for the duration in 618 seconds. <parameter>HH</parameter> is the number of hours, <parameter>MM</parameter> the number of minutes, 619 <parameter>SS</parameter> the number of seconds and <parameter>nnnnnnnnn</parameter> the number of nanoseconds. Both the number of 620 hours and the number of nanoseconds can be omitted. There can be up to nine digits after the decimal point. After the duration of 621 the contents in the current output has reached this limit a new output file will be started. 622 </para> 623 624 <para> 625 The '<literal>duration:</literal>' prefix may be omitted for compatibility reasons. 626 </para> 627 </listitem> 628 629 <listitem> 630 <para> 631 Splitting after specific timestamps. 632 </para> 633 634 <para> 635 Syntax: <option>--split</option> <literal>timestamps:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional> 636 </para> 637 638 <para> 639 Example: <code>--split timestamps:00:45:00.000,01:20:00.250,6300s</code> 640 </para> 641 642 <para> 643 The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>C</parameter> etc must all have the same format as the 644 ones used for the duration (see above). The list of timestamps is separated by commas. After the input stream has reached the 645 current split point's timestamp a new file is created. Then the next split point given in this list is used. 646 </para> 647 648 <para> 649 The '<literal>timestamps:</literal>' prefix must not be omitted. 650 </para> 651 </listitem> 652 653 <listitem> 654 <para> 655 Keeping specific parts by specifying timestamp ranges while discarding others. 656 </para> 657 658 <para> 659 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> 660 </para> 661 662 <para> 663 Examples: 664 <orderedlist> 665 <listitem><para><code>--split parts:00:01:20-00:02:45,00:05:50-00:10:30</code></para></listitem> 666 <listitem><para><code>--split parts:00:01:20-00:02:45,+00:05:50-00:10:30</code></para></listitem> 667 <listitem><para><code>--split parts:-00:02:45,00:05:50-</code></para></listitem> 668 </orderedlist> 669 </para> 670 671 <para> 672 The <literal>parts</literal> mode tells &mkvmerge; to keep certain ranges of timestamps while discarding others. The ranges to keep 673 have to be listed after the <literal>parts:</literal> keyword and be separated by commas. A range itself consists of a start and an 674 end timestamp in the same format the other variations of <parameter>--split</parameter> accept (e.g. both 675 <literal>00:01:20</literal> and <literal>80s</literal> refer to the same timestamp). 676 </para> 677 678 <para> 679 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 680 defaults to the start of the file (see example 3). 681 </para> 682 683 <para> 684 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 685 example 3). 686 </para> 687 688 <para> 689 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 690 that the user has to prefix the start timestamp with a <literal>+</literal>. This tells &mkvmerge; not to create a new file and 691 instead append the range to the same file the previous range was written to. Timestamps will be adjusted so that there will be no 692 gap in the output file even if there was a gap in the two ranges in the input file. 693 </para> 694 695 <para> 696 In example 1 &mkvmerge; will create two files. The first will contain the content starting from <literal>00:01:20</literal> until 697 <literal>00:02:45</literal>. The second file will contain the content starting from <literal>00:05:50</literal> until 698 <literal>00:10:30</literal>. 699 </para> 700 701 <para> 702 In example 2 &mkvmerge; will create only one file. This file will contain both the content starting from <literal>00:01:20</literal> 703 until <literal>00:02:45</literal> and the content starting from <literal>00:05:50</literal> until <literal>00:10:30</literal>. 704 </para> 705 706 <para> 707 In example 3 &mkvmerge; will create two files. The first will contain the content from the start of the source files until 708 <literal>00:02:45</literal>. The second file will contain the content starting from <literal>00:05:50</literal> until the end of 709 the source files. 710 </para> 711 712 <note> 713 <para> 714 Note that &mkvmerge; only makes decisions about splitting at key frame positions. This applies to both the start and the end of 715 each range. So even if an end timestamp is between two key frames &mkvmerge; will continue outputting the frames up to but 716 excluding the following key frame. 717 </para> 718 </note> 719 </listitem> 720 721 <listitem> 722 <para> 723 Keeping specific parts by specifying frame/field number ranges while discarding others. 724 </para> 725 726 <para> 727 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> 728 </para> 729 730 <para> 731 Examples: 732 <orderedlist> 733 <listitem><para><code>--split parts-frames:137-258,548-1211</code></para></listitem> 734 <listitem><para><code>--split parts-frames:733-912,+1592-2730</code></para></listitem> 735 <listitem><para><code>--split parts-frames:-430,2512-</code></para></listitem> 736 </orderedlist> 737 </para> 738 739 <para> 740 The <literal>parts-frames</literal> mode tells &mkvmerge; to keep certain ranges of frame/field numbers while discarding 741 others. The ranges to keep have to be listed after the <literal>parts-frames:</literal> keyword and be separated by commas. A range 742 itself consists of a start and an end frame/field number. Numbering starts at 1. 743 </para> 744 745 <para> 746 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 747 to the start of the file (see example 3). 748 </para> 749 750 <para> 751 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 752 example 3). 753 </para> 754 755 <para> 756 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 757 that the user has to prefix the start number with a <literal>+</literal>. This tells &mkvmerge; not to create a new file and 758 instead append the range to the same file the previous range was written to. Timestamps will be adjusted so that there will be no 759 gap in the output file even if there was a gap in the two ranges in the input file. 760 </para> 761 762 <note> 763 <para> 764 Note that &mkvmerge; only makes decisions about splitting at key frame positions. This applies to both the start and the end of 765 each range. So even if an end frame/field number is between two key frames &mkvmerge; will continue outputting the frames up to 766 but excluding the following key frame. 767 </para> 768 </note> 769 770 <para> 771 In example 1 &mkvmerge; will create two files. The first will contain the content starting from the first key frame at or after 772 <literal>137</literal> up to but excluding the first key frame at or after <literal>258</literal>. The second file will contain the 773 content starting from <literal>548</literal> until <literal>1211</literal>. 774 </para> 775 776 <para> 777 In example 2 &mkvmerge; will create only one file. This file will contain both the content starting from <literal>733</literal> 778 until <literal>912</literal> and the content starting from <literal>1592</literal> until <literal>2730</literal>. 779 </para> 780 781 <para> 782 In example 3 &mkvmerge; will create two files. The first will contain the content from the start of the source files until 783 <literal>430</literal>. The second file will contain the content starting from <literal>2512</literal> until the end of the source 784 files. 785 </para> 786 787 <para> 788 This mode considers only the first video track that is output. If no video track is output no splitting will occur. 789 </para> 790 791 <note> 792 <para> 793 The numbers given with this argument are interpreted based on the number of &matroska; blocks that are output. A single &matroska; 794 block contains either a full frame (for progressive content) or a single field (for interlaced content). mkvmerge does not 795 distinguish between those two and simply counts the number of blocks. For example: If one wanted to split after the 25th full 796 frame with interlaced content one would have to use <literal>50</literal> (two fields per full frame) as the split point. 797 </para> 798 </note> 799 </listitem> 800 801 <listitem> 802 <para> 803 Splitting after specific frames/fields. 804 </para> 805 806 <para> 807 Syntax: <option>--split</option> <literal>frames:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional> 808 </para> 809 810 <para> 811 Example: <code>--split frames:120,237,891</code> 812 </para> 813 814 <para> 815 The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>C</parameter> etc must all be positive integers. 816 Numbering starts at 1. The list of frame/field numbers is separated by commas. After the input stream has reached the current 817 split point's frame/field number a new file is created. Then the next split point given in this list is used. 818 </para> 819 820 <para> 821 The '<literal>frames:</literal>' prefix must not be omitted. 822 </para> 823 824 <para> 825 This mode considers only the first video track that is output. If no video track is output no splitting will occur. 826 </para> 827 828 <note> 829 <para> 830 The numbers given with this argument are interpreted based on the number of &matroska; blocks that are output. A single &matroska; 831 block contains either a full frame (for progressive content) or a single field (for interlaced content). mkvmerge does not 832 distinguish between those two and simply counts the number of blocks. For example: If one wanted to split after the 25th full 833 frame with interlaced content one would have to use <literal>50</literal> (two fields per full frame) as the split point. 834 </para> 835 </note> 836 </listitem> 837 838 <listitem> 839 <para> 840 Splitting before specific chapters. 841 </para> 842 843 <para> 844 Syntax: <option>--split</option> <literal>chapters:all</literal> or <option>--split</option> 845 <literal>chapters:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional> 846 </para> 847 848 <para> 849 Example: <code>--split chapters:5,8</code> 850 </para> 851 852 <para> 853 The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>C</parameter> etc must all be positive integers. 854 Numbering starts at 1. The list of chapter numbers is separated by commas. Splitting will occur right before the first key frame 855 whose timestamp is equal to or bigger than the start timestamp for the chapters whose numbers are listed. A chapter starting at 0s 856 is never considered for splitting and discarded silently. 857 </para> 858 859 <para> 860 The keyword <literal>all</literal> can be used instead of listing all chapter numbers manually. 861 </para> 862 863 <para> 864 The '<literal>chapters:</literal>' prefix must not be omitted. 865 </para> 866 867 <note> 868 <para> 869 The &matroska; file format supports arbitrary deeply nested chapter structures called 'edition entries' and 'chapter atoms'. 870 However, this mode only considers the top-most level of chapters across all edition entries. 871 </para> 872 </note> 873 </listitem> 874 </orderedlist> 875 876 <para> 877 For this splitting mode the output filename is treated differently than for the normal operation. It may contain a 878 <function>printf</function> like expression '<code>%d</code>' including an optional field width, 879 e.g. '<code>%02d</code>'. If it does then the current file number will be formatted appropriately and inserted at that point 880 in the filename. If there is no such pattern then a pattern of '<code>-%03d</code>' is assumed right before the file's 881 extension: '<code>-o output.mkv</code>' would result in '<code>output-001.mkv</code>' and so on. If there's no extension 882 then '<code>-%03d</code>' will be appended to the name. 883 </para> 884 885 <para> 886 Another possible pattern is '<code>%c</code>' which will be replaced by the name of the first chapter in the file. Note that when 887 '<code>%c</code>' is present, the pattern '<code>-%03d</code>' will not be added automatically. 888 </para> 889 </listitem> 890 </varlistentry> 891 892 <varlistentry id="mkvmerge.description.link"> 893 <term><option>--link</option></term> 894 <listitem> 895 <para> 896 Link files to one another when splitting the output file. See the section on <link linkend="mkvmerge.file_linking">file linking</link> 897 below for details. 898 </para> 899 </listitem> 900 </varlistentry> 901 902 <varlistentry id="mkvmerge.description.link_to_previous"> 903 <term><option>--link-to-previous</option> <parameter>segment-UID</parameter></term> 904 <listitem> 905 <para> 906 Links the first output file to the segment with the segment UID given by the <parameter>segment-UID</parameter> parameter. See the 907 section on <link linkend="mkvmerge.file_linking">file linking</link> below for details. 908 </para> 909 910 <para> 911 If SID starts with = then its rest is interpreted as the name of a Matroska file whose segment UID is read and used. 912 </para> 913 </listitem> 914 </varlistentry> 915 916 <varlistentry id="mkvmerge.description.link_to_next"> 917 <term><option>--link-to-next</option> <parameter>segment-UID</parameter></term> 918 <listitem> 919 <para> 920 Links the last output file to the segment with the segment UID given by the <parameter>segment-UID</parameter> parameter. See the 921 section on <link linkend="mkvmerge.file_linking">file linking</link> below for details. 922 </para> 923 924 <para> 925 If SID starts with = then its rest is interpreted as the name of a Matroska file whose segment UID is read and used. 926 </para> 927 </listitem> 928 </varlistentry> 929 930 <varlistentry id="mkvmerge.description.append_mode"> 931 <term><option>--append-mode</option> <parameter>mode</parameter></term> 932 <listitem> 933 <para> 934 Determines how timestamps are calculated when appending files. The parameter <parameter>mode</parameter> can have two values: 935 '<literal>file</literal>' which is also the default and '<literal>track</literal>'. 936 </para> 937 938 <para> 939 When mkvmerge appends a track (called '<literal>track2_1</literal>' from now on) from a second file (called 940 '<literal>file2</literal>') to a track (called '<literal>track1_1</literal>') from the first file (called '<literal>file1</literal>') 941 then it has to offset all timestamps for '<literal>track2_1</literal>' by an amount. For '<literal>file</literal>' mode this amount is 942 the highest timestamp encountered in '<literal>file1</literal>' even if that timestamp was from a different track than 943 '<literal>track1_1</literal>'. In track mode the offset is the highest timestamp of '<literal>track1_1</literal>'. 944 </para> 945 946 <para> 947 Unfortunately mkvmerge cannot detect which mode to use reliably. Therefore it defaults to '<literal>file</literal>' 948 mode. '<literal>file</literal>' mode usually works better for files that have been created independently of each other; e.g. when 949 appending <abbrev>AVI</abbrev> or <abbrev>MP4</abbrev> files. '<literal>track</literal>' mode may work better for sources that are 950 essentially just parts of one big file, e.g. for <abbrev>VOB</abbrev> and <abbrev>EVO</abbrev> files. 951 </para> 952 953 <para> 954 Subtitle tracks are always treated as if '<literal>file</literal>' mode were active even if '<literal>track</literal>' mode actually 955 is. 956 </para> 957 </listitem> 958 </varlistentry> 959 960 <varlistentry id="mkvmerge.description.append_to"> 961 <term><option>--append-to</option> <parameter>SFID1:STID1:DFID1:DTID1<optional>,...</optional></parameter></term> 962 <listitem> 963 <para> 964 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 965 and a second track ID. The first pair, "source file ID" and "source track ID", identifies the track that is to be appended. The 966 second pair, "destination file ID" and "destination track ID", identifies the track the first one is appended to. 967 </para> 968 969 <para> 970 If this option has been omitted then a standard mapping is used. This standard mapping appends each track from the current file to a 971 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 972 file have the same number of tracks and track IDs with the command <command>mkvmerge -o output.mkv part1.mkv +part2.mkv</command>. 973 </para> 974 </listitem> 975 </varlistentry> 976 977 <varlistentry id="mkvmerge.description.plus_sign"> 978 <term><option>+</option></term> 979 <listitem> 980 <para> 981 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 982 the following two commands are equivalent: 983 </para> 984 985 <screen>$ mkvmerge -o full.mkv file1.mkv + file2.mkv 986$ mkvmerge -o full.mkv file1.mkv +file2.mkv</screen> 987 </listitem> 988 </varlistentry> 989 990 <varlistentry id="mkvmerge.description.square_brackets"> 991 <term><option>[</option> <parameter>file1</parameter> <parameter>file2</parameter> <option>]</option></term> 992 <listitem> 993 <para> 994 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. 995 </para> 996 997 <para> 998 This is an alternative syntax to using '+' between the file names. Therefore the following two commands are equivalent: 999 </para> 1000 1001 <screen>$ mkvmerge -o full.mkv file1.mkv + file2.mkv 1002$ mkvmerge -o full.mkv '[' file1.mkv file2.mkv ']'</screen> 1003 </listitem> 1004 </varlistentry> 1005 1006 <varlistentry id="mkvmerge.description.prevent_concatenation"> 1007 <term><option>=</option></term> 1008 <listitem> 1009 <para> 1010 For certain file types (MPEG program streams = VOBs) &mkvmerge; normally looks for files in the same directory as an input file that 1011 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 1012 all of those files as if they were concatenated into a single big file. This option, a single '=', causes mkvmerge not to look for 1013 those additional files. 1014 </para> 1015 1016 <para> 1017 The '=' can also be put in front of the next file name. Therefore the following two commands are equivalent: 1018 </para> 1019 1020 <screen>$ mkvmerge -o full.mkv = file1.vob 1021$ mkvmerge -o full.mkv =file1.vob</screen> 1022 </listitem> 1023 </varlistentry> 1024 1025 <varlistentry id="mkvmerge.description.concatenation"> 1026 <term><option>(</option> <parameter>file1</parameter> <parameter>file2</parameter> <option>)</option></term> 1027 <listitem> 1028 <para> 1029 If multiple file names are contained in a pair of parenthesis then those files will be treated as if they were concatenated into a 1030 single big file consisting of the content of each of the files one after the other. 1031 </para> 1032 1033 <para> 1034 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 1035 of headers which is usually the case with stand-alone files like AVI or MP4. 1036 </para> 1037 1038 <para> 1039 Putting a file name into parenthesis also prevents &mkvmerge; from looking for additional files with the same base name as described 1040 in <link linkend="mkvmerge.description.prevent_concatenation">option <option>=</option></link>. Therefore these two command lines are 1041 equivalent: 1042 </para> 1043 1044 <screen>$ mkvmerge -o out.mkv = file.mkv 1045$ mkvmerge -o out.mkv '(' file.mkv ')'</screen> 1046 1047 <para> 1048 Several things should be noted: 1049 </para> 1050 1051 <orderedlist> 1052 <listitem> 1053 <para> 1054 There must be spaces both after the opening and before the closing parenthesis. 1055 </para> 1056 </listitem> 1057 1058 <listitem> 1059 <para> 1060 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. 1061 </para> 1062 </listitem> 1063 1064 <listitem> 1065 <para> 1066 Some shells treat parenthesis as special characters. Hence you must escape or quote them as shown in the example above. 1067 </para> 1068 </listitem> 1069 </orderedlist> 1070 </listitem> 1071 </varlistentry> 1072 </variablelist> 1073 1074 </refsect2> 1075 1076 <refsect2> 1077 <title>Attachment support (more global options)</title> 1078 1079 <variablelist> 1080 <varlistentry id="mkvmerge.description.attachment_description"> 1081 <term><option>--attachment-description</option> <parameter>description</parameter></term> 1082 <listitem> 1083 <para> 1084 Plain text description of the following attachment. Applies to the next <link 1085 linkend="mkvmerge.description.attach_file"><option>--attach-file</option></link> or <option>--attach-file-once</option> option. 1086 1087 </para> 1088 </listitem> 1089 </varlistentry> 1090 1091 <varlistentry id="mkvmerge.description.attachment_mime_type"> 1092 <term><option>--attachment-mime-type</option> <parameter>MIME type</parameter></term> 1093 <listitem> 1094 <para> 1095 <abbrev>MIME</abbrev> type of the following attachment. Applies to the next <link 1096 linkend="mkvmerge.description.attach_file"><option>--attach-file</option></link> or <link 1097 linkend="mkvmerge.description.attach_file"><option>--attach-file-once</option></link> option. A list of officially recognized 1098 <abbrev>MIME</abbrev> types can be found e.g. at <ulink url="https://www.iana.org/assignments/media-types/">the IANA 1099 homepage</ulink>. The <abbrev>MIME</abbrev> type is mandatory for an attachment. 1100 </para> 1101 </listitem> 1102 </varlistentry> 1103 1104 <varlistentry id="mkvmerge.description.attachment_name"> 1105 <term><option>--attachment-name</option> <parameter>name</parameter></term> 1106 <listitem> 1107 <para> 1108 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 1109 from the file name of the attachment as given with the <link 1110 linkend="mkvmerge.description.attach_file"><option>--attach-file</option></link> or the <link 1111 linkend="mkvmerge.description.attach_file"><option>--attach-file-once</option></link> option. 1112 </para> 1113 </listitem> 1114 </varlistentry> 1115 1116 <varlistentry id="mkvmerge.description.attach_file"> 1117 <term> 1118 <option>--attach-file</option> <parameter>file-name</parameter>, 1119 <option>--attach-file-once</option> <parameter>file-name</parameter> 1120 </term> 1121 <listitem> 1122 <para> 1123 Creates a file attachment inside the &matroska; file. The <abbrev>MIME</abbrev> type must have been set before this option can used. The 1124 difference between the two forms is that during splitting the files attached with <option>--attach-file</option> are attached to all 1125 output files while the ones attached with <option>--attach-file-once</option> are only attached to the first file created. If 1126 splitting is not used then both do the same. 1127 </para> 1128 1129 <para> 1130 &mkvextract; can be used to extract attached files from a &matroska; file. 1131 </para> 1132 </listitem> 1133 </varlistentry> 1134 </variablelist> 1135 </refsect2> 1136 1137 <refsect2> 1138 <title>Options that can be used for each input file</title> 1139 1140 <variablelist> 1141 <varlistentry id="mkvmerge.description.audio_tracks"> 1142 <term><option>-a</option>, <option>--audio-tracks</option> <parameter><optional>!</optional>n,m,...</parameter></term> 1143 <listitem> 1144 <para> 1145 Copy the audio tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with the 1146 <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see 1147 section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all audio tracks. 1148 </para> 1149 1150 <para> 1151 Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags 1152 for their tracks. 1153 </para> 1154 1155 <para> 1156 Default: copy all tracks of this kind. 1157 </para> 1158 1159 <para> 1160 If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed 1161 after the <literal>!</literal>. 1162 </para> 1163 </listitem> 1164 </varlistentry> 1165 1166 <varlistentry id="mkvmerge.description.video_tracks"> 1167 <term><option>-d</option>, <option>--video-tracks</option> <parameter><optional>!</optional>n,m,...</parameter></term> 1168 <listitem> 1169 <para> 1170 Copy the video tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with the 1171 <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see 1172 section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all video tracks. 1173 </para> 1174 1175 <para> 1176 Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags 1177 for their tracks. 1178 </para> 1179 1180 <para> 1181 If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed 1182 after the <literal>!</literal>. 1183 </para> 1184 </listitem> 1185 </varlistentry> 1186 1187 <varlistentry id="mkvmerge.description.subtitle_tracks"> 1188 <term><option>-s</option>, <option>--subtitle-tracks</option> <parameter><optional>!</optional>n,m,...</parameter></term> 1189 <listitem> 1190 <para> 1191 Copy the subtitle tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with 1192 the <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see 1193 section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all subtitle tracks. 1194 </para> 1195 1196 <para> 1197 Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags 1198 for their tracks. 1199 </para> 1200 1201 <para> 1202 If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed 1203 after the <literal>!</literal>. 1204 </para> 1205 </listitem> 1206 </varlistentry> 1207 1208 <varlistentry id="mkvmerge.description.button_tracks"> 1209 <term><option>-b</option>, <option>--button-tracks</option> <parameter><optional>!</optional>n,m,...</parameter></term> 1210 <listitem> 1211 <para> 1212 Copy the button tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with 1213 the <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch. They're not simply the track numbers (see 1214 section <link linkend="mkvmerge.track_ids">track IDs</link>). Default: copy all button tracks. 1215 </para> 1216 1217 <para> 1218 Instead of track IDs you can also provide ISO 639-2 language codes. This will only work for source files that provide language tags 1219 for their tracks. 1220 </para> 1221 1222 <para> 1223 If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy all tracks of this kind but the ones listed 1224 after the <literal>!</literal>. 1225 </para> 1226 </listitem> 1227 </varlistentry> 1228 1229 <varlistentry id="mkvmerge.description.track_tags"> 1230 <term><option>--track-tags</option> <parameter><optional>!</optional>n,m,...</parameter></term> 1231 <listitem> 1232 <para> 1233 Copy the tags for tracks <parameter>n</parameter>, <parameter>m</parameter> etc. The numbers are track IDs which can be obtained with 1234 the <link linkend="mkvmerge.description.identify"><option>--identify</option></link> switch (see section <link 1235 linkend="mkvmerge.track_ids">track IDs</link>). They're not simply the track numbers. Default: copy tags for all tracks. 1236 </para> 1237 1238 <para> 1239 If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy everything but the IDs listed after the 1240 <literal>!</literal>. 1241 </para> 1242 </listitem> 1243 </varlistentry> 1244 1245 <varlistentry id="mkvmerge.description.attachments"> 1246 <term><option>-m</option>, <option>--attachments</option> <parameter><optional>!</optional>n<optional>:all|first</optional>,m<optional>:all|first</optional>,...</parameter></term> 1247 <listitem> 1248 <para> 1249 Copy the attachments with the IDs <parameter>n</parameter>, <parameter>m</parameter> etc to all or only the first output file. Each ID 1250 can be followed by either '<literal>:all</literal>' (which is the default if neither is entered) or '<literal>:first</literal>'. If 1251 splitting is active then those attachments whose IDs are specified with '<literal>:all</literal>' are copied to all of the resulting 1252 output files while the others are only copied into the first output file. If splitting is not active then both variants have the same 1253 effect. 1254 </para> 1255 1256 <para> 1257 The default is to copy all attachments to all output files. 1258 </para> 1259 1260 <para> 1261 If the IDs are prefixed with <literal>!</literal> then the meaning is reversed: copy everything but the IDs listed after the 1262 <literal>!</literal>. 1263 </para> 1264 </listitem> 1265 </varlistentry> 1266 1267 <varlistentry id="mkvmerge.description.no_audio"> 1268 <term><option>-A</option>, <option>--no-audio</option></term> 1269 <listitem> 1270 <para> 1271 Don't copy any audio track from this file. 1272 </para> 1273 </listitem> 1274 </varlistentry> 1275 1276 <varlistentry id="mkvmerge.description.no_video"> 1277 <term><option>-D</option>, <option>--no-video</option></term> 1278 <listitem> 1279 <para> 1280 Don't copy any video track from this file. 1281 </para> 1282 </listitem> 1283 </varlistentry> 1284 1285 <varlistentry id="mkvmerge.description.no_subtitles"> 1286 <term><option>-S</option>, <option>--no-subtitles</option></term> 1287 <listitem> 1288 <para> 1289 Don't copy any subtitle track from this file. 1290 </para> 1291 </listitem> 1292 </varlistentry> 1293 1294 <varlistentry id="mkvmerge.description.no_buttons"> 1295 <term><option>-B</option>, <option>--no-buttons</option></term> 1296 <listitem> 1297 <para> 1298 Don't copy any button track from this file. 1299 </para> 1300 </listitem> 1301 </varlistentry> 1302 1303 <varlistentry id="mkvmerge.description.no_track_tags"> 1304 <term><option>-T</option>, <option>--no-track-tags</option></term> 1305 <listitem> 1306 <para> 1307 Don't copy any track specific tags from this file. 1308 </para> 1309 </listitem> 1310 </varlistentry> 1311 1312 <varlistentry id="mkvmerge.description.no_chapters"> 1313 <term><option>--no-chapters</option></term> 1314 <listitem> 1315 <para> 1316 Don't copy chapters from this file. 1317 </para> 1318 </listitem> 1319 </varlistentry> 1320 1321 <varlistentry id="mkvmerge.description.no_attachments"> 1322 <term><option>-M</option>, <option>--no-attachments</option></term> 1323 <listitem> 1324 <para> 1325 Don't copy attachments from this file. 1326 </para> 1327 </listitem> 1328 </varlistentry> 1329 1330 <varlistentry id="mkvmerge.description.no_global_tags"> 1331 <term><option>--no-global-tags</option></term> 1332 <listitem> 1333 <para> 1334 Don't copy global tags from this file. 1335 </para> 1336 </listitem> 1337 </varlistentry> 1338 1339 <varlistentry id="mkvmerge.description.sync"> 1340 <term><option>-y</option>, <option>--sync</option> <parameter>TID:d<optional>,o<optional>/p</optional></optional></parameter></term> 1341 <listitem> 1342 <para> 1343 Adjust the timestamps of the track with the id <parameter>TID</parameter> by <parameter>d</parameter> ms. The track IDs are the same as 1344 the ones given with <link linkend="mkvmerge.description.identify"><option>--identify</option></link> (see section <link 1345 linkend="mkvmerge.track_ids">track IDs</link>). 1346 </para> 1347 1348 <para> 1349 <parameter>o</parameter>/<parameter>p</parameter>: adjust the timestamps by <parameter>o</parameter>/<parameter>p</parameter> to fix 1350 linear drifts. <parameter>p</parameter> defaults to 1 if omitted. Both <parameter>o</parameter> and <parameter>p</parameter> can be 1351 floating point numbers. 1352 </para> 1353 1354 <para> 1355 Defaults: no manual sync correction (which is the same as <parameter>d</parameter> = <constant>0</constant> and 1356 <parameter>o</parameter>/<parameter>p</parameter> = <constant>1.0</constant>). 1357 </para> 1358 1359 <para> 1360 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1361 </para> 1362 </listitem> 1363 </varlistentry> 1364 1365 <varlistentry id="mkvmerge.description.cues"> 1366 <term><option>--cues</option> <parameter>TID:none|iframes|all</parameter></term> 1367 <listitem> 1368 <para> 1369 Controls for which tracks cue (index) entries are created for the given track (see section <link linkend="mkvmerge.track_ids">track 1370 IDs</link>). '<literal>none</literal>' inhibits the creation of cue entries. For '<literal>iframes</literal>' only blocks with 1371 no backward or forward references ( = I frames in video tracks) are put into the cue sheet. '<literal>all</literal>' causes 1372 &mkvmerge; to create cue entries for all blocks which will make the file very big. 1373 </para> 1374 1375 <para> 1376 The default is '<literal>iframes</literal>' for video and subtitle tracks and '<literal>none</literal>' for audio tracks. See also 1377 option <link linkend="mkvmerge.description.no_cues"><option>--no-cues</option></link> which inhibits the creation of cue entries 1378 regardless of the <option>--cues</option> options used. 1379 </para> 1380 1381 <para> 1382 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1383 </para> 1384 </listitem> 1385 </varlistentry> 1386 1387 <varlistentry id="mkvmerge.description.default_track_flag"> 1388 <term><option>--default-track-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1389 <listitem> 1390 <para> 1391 Sets the "default track" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the 1392 optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. The flag will be set if the 1393 source container doesn't provide that information and the user doesn't specify it via this option. 1394 </para> 1395 1396 <para> 1397 If the user does not explicitly select a track during playback, the player should select one of the tracks that has its "default 1398 track" flag set, taking user preferences such as their preferred language into account. 1399 </para> 1400 1401 <para> 1402 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1403 </para> 1404 </listitem> 1405 </varlistentry> 1406 1407 <varlistentry id="mkvmerge.description.track_enabled_flag"> 1408 <term><option>--track-enabled-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1409 <listitem> 1410 <para> 1411 Sets the "track enabled" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) to the 1412 given value <parameter>bool</parameter> (0 or 1; defaults to 1 if not specified). Tracks are enabled by default if no option is 1413 specified for them and the source container doesn't provide this information either. 1414 </para> 1415 1416 <para> 1417 Only tracks whose "track enabled" flag is set should be considered for playback. 1418 </para> 1419 1420 <para> 1421 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1422 </para> 1423 </listitem> 1424 </varlistentry> 1425 1426 <varlistentry id="mkvmerge.description.forced_display_flag"> 1427 <term><option>--forced-display-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1428 <listitem> 1429 <para> 1430 Sets the "forced display" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the 1431 optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. Use this for tracks 1432 containing onscreen text or foreign-language dialogue. 1433 </para> 1434 1435 <para> 1436 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1437 </para> 1438 </listitem> 1439 </varlistentry> 1440 1441 <varlistentry id="mkvmerge.description.hearing_impaired_flag"> 1442 <term><option>--hearing-impaired-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1443 <listitem> 1444 <para> 1445 Sets the "hearing impaired" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the 1446 optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if the 1447 track is suitable for users with hearing impairments. 1448 </para> 1449 1450 <para> 1451 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1452 </para> 1453 </listitem> 1454 </varlistentry> 1455 1456 <varlistentry id="mkvmerge.description.visual_impaired_flag"> 1457 <term><option>--visual-impaired-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1458 <listitem> 1459 <para> 1460 Sets the "visual impaired" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the 1461 optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if the 1462 track is suitable for users with visual impairments. 1463 </para> 1464 1465 <para> 1466 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1467 </para> 1468 </listitem> 1469 </varlistentry> 1470 1471 <varlistentry id="mkvmerge.description.text_descriptions_flag"> 1472 <term><option>--text-descriptions-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1473 <listitem> 1474 <para> 1475 Sets the "text descriptions" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if 1476 the optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if 1477 the track contains textual descriptions of video content suitable for playback via a text-to-speech system for a visually-impaired 1478 user. 1479 </para> 1480 1481 <para> 1482 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1483 </para> 1484 </listitem> 1485 </varlistentry> 1486 1487 <varlistentry id="mkvmerge.description.original_flag"> 1488 <term><option>--original-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1489 <listitem> 1490 <para> 1491 Sets the "original language" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if 1492 the optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if 1493 the track is in the content's original language (not a translation). 1494 </para> 1495 1496 <para> 1497 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1498 </para> 1499 </listitem> 1500 </varlistentry> 1501 1502 <varlistentry id="mkvmerge.description.commentary_flag"> 1503 <term><option>--commentary-flag</option> <parameter>TID<optional>:bool</optional></parameter></term> 1504 <listitem> 1505 <para> 1506 Sets the "commentary" flag for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) if the 1507 optional argument <parameter>bool</parameter> is set to <constant>1</constant> or if it isn't present. This flag can be set if the 1508 track contains commentary. 1509 </para> 1510 1511 <para> 1512 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1513 </para> 1514 </listitem> 1515 </varlistentry> 1516 1517 <varlistentry id="mkvmerge.description.blockadd"> 1518 <term><option>--blockadd</option> <parameter>TID:level</parameter></term> 1519 <listitem> 1520 <para> 1521 Keep only the <classname>BlockAdditions</classname> up to the level <parameter>level</parameter> for the given track. The default is 1522 to keep all levels. This option only affects certain kinds of codecs like WAVPACK4. 1523 </para> 1524 </listitem> 1525 </varlistentry> 1526 1527 <varlistentry id="mkvmerge.description.track_name"> 1528 <term><option>--track-name</option> <parameter>TID:name</parameter></term> 1529 <listitem> 1530 <para> 1531 Sets the track name for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>) to 1532 <parameter>name</parameter>. 1533 </para> 1534 </listitem> 1535 </varlistentry> 1536 1537 <varlistentry id="mkvmerge.description.language"> 1538 <term><option>--language</option> <parameter>TID:language</parameter></term> 1539 <listitem> 1540 <para> 1541 Sets the language for the given track (see section <link linkend="mkvmerge.track_ids">track IDs</link>). Both ISO 639-2 language codes 1542 and ISO 639-1 country codes are allowed. The country codes will be converted to language codes automatically. All languages including 1543 their ISO 639-2 codes can be listed with the <link 1544 linkend="mkvmerge.description.list_languages"><option>--list-languages</option></link> option. 1545 </para> 1546 1547 <para> 1548 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 1549 </para> 1550 </listitem> 1551 </varlistentry> 1552 1553 <varlistentry id="mkvmerge.description.tags"> 1554 <term><option>-t</option>, <option>--tags</option> <parameter>TID:file-name</parameter></term> 1555 <listitem> 1556 <para> 1557 Read tags for the track with the number <parameter>TID</parameter> from the file <parameter>file-name</parameter>. See the section 1558 about <link linkend="mkvmerge.tags">tags</link> below for details. 1559 </para> 1560 </listitem> 1561 </varlistentry> 1562 1563 <varlistentry id="mkvmerge.description.aac_is_sbr"> 1564 <term><option>--aac-is-sbr</option> <parameter>TID<optional>:0|1</optional></parameter></term> 1565 <listitem> 1566 <para> 1567 Tells &mkvmerge; that the track with the ID <parameter>TID</parameter> is <abbrev>SBR AAC</abbrev> (also known as 1568 <abbrev>HE-AAC</abbrev> or <abbrev>AAC+</abbrev>). This options is needed if a) the source file is an <abbrev>AAC</abbrev> file 1569 (<emphasis>not</emphasis> for a &matroska; file) and b) the <abbrev>AAC</abbrev> file contains <abbrev>SBR AAC</abbrev> data. The 1570 reason for this switch is that it is technically impossible to automatically tell normal <abbrev>AAC</abbrev> data from <abbrev>SBR 1571 AAC</abbrev> data without decoding a complete <abbrev>AAC</abbrev> frame. As there are several patent issues with <abbrev>AAC</abbrev> 1572 decoders &mkvmerge; will never contain this decoding stage. So for <abbrev>SBR AAC</abbrev> files this switch is mandatory. The 1573 resulting file might not play back correctly or even not at all if the switch was omitted. 1574 </para> 1575 1576 <para> 1577 If the source file is a &matroska; file then the <classname>CodecID</classname> should be enough to detect <abbrev>SBR 1578 AAC</abbrev>. However, if the <classname>CodecID</classname> is wrong then this switch can be used to correct that. 1579 </para> 1580 1581 <para> 1582 If mkvmerge wrongfully detects that an <abbrev>AAC</abbrev> file is <abbrev>SBR</abbrev> then you can add 1583 '<literal>:0</literal>' to the track ID. 1584 </para> 1585 </listitem> 1586 </varlistentry> 1587 1588 <varlistentry id="mkvmerge.description.reduce_to_core"> 1589 <term><option>--reduce-to-core</option> <parameter>TID</parameter></term> 1590 <listitem> 1591 <para> 1592 Some audio codecs have a lossy core and optional extensions that implement lossless decoding. This option tells &mkvmerge; to only 1593 copy the core but not the extensions. By default &mkvmerge; copies both the core and the extensions. 1594 </para> 1595 1596 <para> 1597 Currently only <abbrev>DTS</abbrev> tracks are affected by this option. TrueHD tracks that contain an embedded <abbrev>AC-3</abbrev> 1598 core are instead presented as two separate tracks for which the user can select which track to copy. For <abbrev>DTS</abbrev> such a 1599 scheme would not work as the HD extensions cannot be decoded by themselves – unlike the TrueHD data. 1600 </para> 1601 </listitem> 1602 </varlistentry> 1603 1604 <varlistentry id="mkvmerge.description.remove_dialog_normalization_gain"> 1605 <term><option>--remove-dialog-normalization-gain</option> <parameter>TID</parameter></term> 1606 <listitem> 1607 <para> 1608 Some audio codecs contain header fields that tell the decoder or player to apply a (usually negative) gain for dialog 1609 normalization. This option tells &mkvmerge; to remove or minimize that gain by modifying the corresponding header fields. 1610 </para> 1611 1612 <para> 1613 Currently only <abbrev>AC-3</abbrev>, <abbrev>DTS</abbrev> and <abbrev>TrueHD</abbrev> tracks are affected by this option. 1614 </para> 1615 </listitem> 1616 </varlistentry> 1617 1618 <varlistentry id="mkvmerge.description.timestamps"> 1619 <term><option>--timestamps</option> <parameter>TID:file-name</parameter></term> 1620 <listitem> 1621 <para> 1622 Read the timestamps to be used for the specific track ID from <parameter>file-name</parameter>. These timestamps forcefully override 1623 the timestamps that &mkvmerge; normally calculates. Read the section about <link linkend="mkvmerge.external_timestamp_files">external 1624 timestamp files</link>. 1625 </para> 1626 </listitem> 1627 </varlistentry> 1628 1629 <varlistentry id="mkvmerge.description.default_duration"> 1630 <term><option>--default-duration</option> <parameter>TID:x</parameter></term> 1631 <listitem> 1632 <para> 1633 Forces the default duration of a given track to the specified value. Also modifies the track's timestamps to match the default 1634 duration. The argument <parameter>x</parameter> must be postfixed with '<literal>s</literal>', '<literal>ms</literal>', 1635 '<literal>us</literal>', '<literal>ns</literal>', '<literal>fps</literal>', '<literal>p</literal>' or '<literal>i</literal>' to 1636 specify the default duration in seconds, milliseconds, microseconds, nanoseconds, 'frames per second', 'progressive frames per 1637 second' or 'interlaced frames per second' respectively. The number <parameter>x</parameter> itself can be a floating point number or 1638 a fraction. 1639 </para> 1640 1641 <para> 1642 If the default duration is not forced then mkvmerge will try to derive the track's default duration from the container and/or the 1643 encoded bitstream for certain track types, e.g. AVC/H.264 or MPEG-2. 1644 </para> 1645 1646 <para> 1647 This option can also be used to change the <abbrev>FPS</abbrev> of video tracks without having to use an external timestamp file. 1648 </para> 1649 </listitem> 1650 </varlistentry> 1651 1652 <varlistentry id="mkvmerge.description.fix_bitstream_timing_information"> 1653 <term><option>--fix-bitstream-timing-information</option> <parameter>TID<optional>:0|1</optional></parameter></term> 1654 <listitem> 1655 <para> 1656 Normally &mkvmerge; does not change the timing information (frame/field rate) stored in the video bitstream. With this option that 1657 information is adjusted to match the container timing information. The container timing information can come from various sources: 1658 from the command line (see option <link linkend="mkvmerge.description.default_duration"><option>--default-duration</option></link>), 1659 the source container or derived from the bitstream. 1660 </para> 1661 1662 <note> 1663 <para>This has only been implemented for AVC/H.264 video tracks so far.</para> 1664 </note> 1665 </listitem> 1666 </varlistentry> 1667 1668 <varlistentry id="mkvmerge.description.compression"> 1669 <term><option>--compression</option> <parameter>TID:n</parameter></term> 1670 <listitem> 1671 <para> 1672 Selects the compression method to be used for the track. Note that the player also has to support this method. Valid values are 1673 '<literal>none</literal>', '<literal>zlib</literal>' and '<literal>mpeg4_p2</literal>'/'<literal>mpeg4p2</literal>'. 1674 </para> 1675 <para> 1676 The compression method '<literal>mpeg4_p2</literal>'/'<literal>mpeg4p2</literal>' is a special compression method called 'header 1677 removal' that is only available for <abbrev>MPEG4</abbrev> part 2 video tracks. 1678 </para> 1679 <para> 1680 The default for some subtitle types is '<literal>zlib</literal>' compression. This compression method is also the one that most if 1681 not all playback applications support. Support for other compression methods other than '<literal>none</literal>' is not assured. 1682 </para> 1683 </listitem> 1684 </varlistentry> 1685 </variablelist> 1686 </refsect2> 1687 1688 <refsect2> 1689 <title>Options that only apply to video tracks</title> 1690 1691 <variablelist> 1692 <varlistentry id="mkvmerge.description.fourcc"> 1693 <term><option>-f</option>, <option>--fourcc</option> <parameter>TID:FourCC</parameter></term> 1694 <listitem> 1695 <para> 1696 Forces the <classname>FourCC</classname> to the specified value. Works only for video tracks in the 'MS compatibility mode'. 1697 </para> 1698 </listitem> 1699 </varlistentry> 1700 1701 <varlistentry id="mkvmerge.description.display_dimensions"> 1702 <term><option>--display-dimensions</option> <parameter>TID:widthxheight</parameter></term> 1703 <listitem> 1704 <para> 1705 &matroska; files contain two values that set the display properties that a player should scale the image on playback to: display width 1706 and display height. These values can be set with this option, e.g. '<literal>1:640x480</literal>'. 1707 </para> 1708 1709 <para> 1710 Another way to specify the values is to use the <link 1711 linkend="mkvmerge.description.aspect_ratio"><option>--aspect-ratio</option></link> or the <link 1712 linkend="mkvmerge.description.aspect_ratio_factor"><option>--aspect-ratio-factor</option></link> option (see below). These options 1713 are mutually exclusive. 1714 </para> 1715 </listitem> 1716 </varlistentry> 1717 1718 <varlistentry id="mkvmerge.description.aspect_ratio"> 1719 <term><option>--aspect-ratio</option> <parameter>TID:ratio|width/height</parameter></term> 1720 <listitem> 1721 <para> 1722 &matroska; files contain two values that set the display properties that a player should scale the image on playback to: display width 1723 and display height. With this option &mkvmerge; will automatically calculate the display width and display height based on the 1724 image's original width and height and the aspect ratio given with this option. The ratio can be given either as a floating point 1725 number <parameter>ratio</parameter> or as a fraction '<parameter>width</parameter>/<parameter>height</parameter>', 1726 e.g. '<literal>16/9</literal>'. 1727 </para> 1728 1729 <para> 1730 Another way to specify the values is to use the <link 1731 linkend="mkvmerge.description.aspect_ratio_factor"><option>--aspect-ratio-factor</option></link> or <link 1732 linkend="mkvmerge.description.display_dimensions"><option>--display-dimensions</option></link> options (see above and below). These 1733 options are mutually exclusive. 1734 </para> 1735 </listitem> 1736 </varlistentry> 1737 1738 <varlistentry id="mkvmerge.description.aspect_ratio_factor"> 1739 <term><option>--aspect-ratio-factor</option> <parameter>TID:factor|n/d</parameter></term> 1740 <listitem> 1741 <para> 1742 Another way to set the aspect ratio is to specify a <parameter>factor</parameter>. The original aspect ratio is first multiplied with 1743 this <parameter>factor</parameter> and used as the target aspect ratio afterwards. 1744 </para> 1745 1746 <para> 1747 Another way to specify the values is to use the <link 1748 linkend="mkvmerge.description.aspect_ratio"><option>--aspect-ratio</option></link> or <link 1749 linkend="mkvmerge.description.display_dimensions"><option>--display-dimensions</option></link> options (see above). These options are 1750 mutually exclusive. 1751 </para> 1752 </listitem> 1753 </varlistentry> 1754 1755 <varlistentry id="mkvmerge.description.cropping"> 1756 <term><option>--cropping</option> <parameter>TID:left,top,right,bottom</parameter></term> 1757 <listitem> 1758 <para> 1759 Sets the pixel cropping parameters of a video track to the given values. 1760 </para> 1761 </listitem> 1762 </varlistentry> 1763 1764 <varlistentry id="mkvmerge.description.colour_matrix_coefficients"> 1765 <term><option>--colour-matrix-coefficients</option> <parameter>TID:n</parameter></term> 1766 <listitem> 1767 <para> 1768 Sets the matrix coefficients of the video used to derive luma and chroma values from red, green and blue color primaries. The 1769 parameter <parameter>n</parameter> is an integer rangeing from <constant>0</constant> and <constant>10</constant>. 1770 </para> 1771 1772 <para> 1773 Valid values and their meaning are: 1774 </para> 1775 1776 <para> 1777 <constant>0</constant>: GBR, <constant>1</constant>: BT709, <constant>2</constant>: unspecified, <constant>3</constant>: reserved, 1778 <constant>4</constant>: FCC, <constant>5</constant>: BT470BG, <constant>6</constant>: SMPTE 170M, <constant>7</constant>: SMPTE 240M, 1779 <constant>8</constant>: YCOCG, <constant>9</constant>: BT2020 non-constant luminance, <constant>10</constant>: BT2020 constant 1780 luminance 1781 </para> 1782 </listitem> 1783 </varlistentry> 1784 1785 <varlistentry id="mkvmerge.description.colour_bits_per_channel"> 1786 <term><option>--colour-bits-per-channel</option> <parameter>TID:n</parameter></term> 1787 <listitem> 1788 <para> 1789 Sets the number of coded bits for a colour channel. A value of <constant>0</constant> indicates that the number of bits is 1790 unspecified. 1791 </para> 1792 </listitem> 1793 </varlistentry> 1794 1795 <varlistentry id="mkvmerge.description.chroma_subsample"> 1796 <term><option>--chroma-subsample</option> <parameter>TID:hori,vert</parameter></term> 1797 <listitem> 1798 <para> 1799 The amount of pixels to remove in the Cr and Cb channels for every pixel not removed horizontally/vertically. 1800 </para> 1801 1802 <para> 1803 Example: For video with 4:2:0 chroma subsampling, the parameter should be set to 1804 <code><parameter>TID</parameter>:<constant>1</constant>,<constant>1</constant></code>. 1805 </para> 1806 </listitem> 1807 </varlistentry> 1808 1809 <varlistentry id="mkvmerge.description.cb_subsample"> 1810 <term><option>--cb-subsample</option> <parameter>TID:hori,vert</parameter></term> 1811 <listitem> 1812 <para> 1813 The amount of pixels to remove in the Cb channel for every pixel not removed horizontally/vertically. This is additive with 1814 <option>--chroma-subsample</option>. 1815 </para> 1816 1817 <para> 1818 Example: For video with 4:2:1 chroma subsampling, the parameter <option>--chroma-subsample</option> should be set to 1819 <code><parameter>TID</parameter>:<constant>1</constant>,<constant>0</constant></code> and Cb-subsample should be set to 1820 <code><parameter>TID</parameter>:<constant>1</constant>,<constant>0</constant></code>. 1821 </para> 1822 </listitem> 1823 </varlistentry> 1824 1825 <varlistentry id="mkvmerge.description.chroma_siting"> 1826 <term><option>--chroma-siting</option> <parameter>TID:hori,vert</parameter></term> 1827 <listitem> 1828 <para> 1829 Sets how chroma is sited horizontally/vertically (<constant>0</constant>: unspecified, <constant>1</constant>: top collocated, 1830 <constant>2</constant>: half). 1831 </para> 1832 </listitem> 1833 </varlistentry> 1834 1835 <varlistentry id="mkvmerge.description.colour_range"> 1836 <term><option>--colour-range</option> <parameter>TID:n</parameter></term> 1837 <listitem> 1838 <para> 1839 Sets the clipping of the color ranges (<constant>0</constant>: unspecified, <constant>1</constant>: broadcast range, 1840 <constant>2</constant>: full range (no clipping), <constant>3</constant>: defined by MatrixCoefficients/TransferCharacteristics). 1841 </para> 1842 </listitem> 1843 </varlistentry> 1844 1845 <varlistentry id="mkvmerge.description.colour_transfer_characteristics"> 1846 <term><option>--colour-transfer-characteristics</option> <parameter>TID:n</parameter></term> 1847 <listitem> 1848 <para> 1849 The transfer characteristics of the video. 1850 </para> 1851 1852 <para> 1853 Valid values and their meaning are: 1854 </para> 1855 1856 <para> 1857 <constant>0</constant>: reserved, <constant>1</constant>: ITU-R BT.709, <constant>2</constant>: unspecified, <constant>3</constant>: 1858 reserved, <constant>4</constant>: gamma 2.2 curve, <constant>5</constant>: gamma 2.8 curve, <constant>6</constant>: SMPTE 170M, 1859 <constant>7</constant>: SMPTE 240M, <constant>8</constant>: linear, <constant>9</constant>: log, <constant>10</constant>: log sqrt, 1860 <constant>11</constant>: IEC 61966-2-4, <constant>12</constant>: ITU-R BT.1361 extended colour gamut, <constant>13</constant>: IEC 1861 61966-2-1, <constant>14</constant>: ITU-R BT.2020 10 bit, <constant>15</constant>: ITU-R BT.2020 12 bit, <constant>16</constant>: 1862 SMPTE ST 2084, <constant>17</constant>: SMPTE ST 428-1; <constant>18</constant>: ARIB STD-B67 (HLG) 1863 </para> 1864 </listitem> 1865 </varlistentry> 1866 1867 <varlistentry id="mkvmerge.description.colour_primaries"> 1868 <term><option>--colour-primaries</option> <parameter>TID:n</parameter></term> 1869 <listitem> 1870 <para> 1871 Sets the colour primaries of the video. 1872 </para> 1873 1874 <para> 1875 Valid values and their meaning are: 1876 </para> 1877 1878 <para> 1879 <constant>0</constant>: reserved, <constant>1</constant>: ITU-R BT.709, <constant>2</constant>: unspecified, <constant>3</constant>: 1880 reserved, <constant>4</constant>: ITU-R BT.470M, <constant>5</constant>: ITU-R BT.470BG, <constant>6</constant>: SMPTE 170M, 1881 <constant>7</constant>: SMPTE 240M, <constant>8</constant>: FILM, <constant>9</constant>: ITU-R BT.2020, <constant>10</constant>: 1882 SMPTE ST 428-1, <constant>22</constant>: JEDEC P22 phosphors 1883 </para> 1884 </listitem> 1885 </varlistentry> 1886 1887 <varlistentry id="mkvmerge.description.max_content_light"> 1888 <term><option>--max-content-light</option> <parameter>TID:n</parameter></term> 1889 <listitem> 1890 <para> 1891 Sets the maximum brightness of a single pixel (Maximum Content Light Level) in candelas per square meter (cd/m²). The value of 1892 <parameter>n</parameter> should be a non-negtive integer. 1893 </para> 1894 </listitem> 1895 </varlistentry> 1896 1897 <varlistentry id="mkvmerge.description.max_frame_light"> 1898 <term><option>--max-frame-light</option> <parameter>TID:n</parameter></term> 1899 <listitem> 1900 <para> 1901 Sets the maximum brightness of a single full frame (Maximum Frame-Average Light Level) in candelas per square meter (cd/m²). The 1902 value of <parameter>n</parameter> should be a non-negtive 1903 integer. 1904 </para> 1905 </listitem> 1906 </varlistentry> 1907 1908 <varlistentry id="mkvmerge.description.chromaticity_coordinates"> 1909 <term><option>--chromaticity-coordinates</option> 1910 <parameter>TID:red-x,red-y,green-x,green-y,blue-x,blue-y</parameter></term> 1911 <listitem> 1912 <para> 1913 Sets the red/green/blue chromaticity coordinates as defined by CIE 1931. 1914 </para> 1915 </listitem> 1916 </varlistentry> 1917 1918 <varlistentry id="mkvmerge.description.white_colour_coordinates"> 1919 <term><option>--white-colour-coordinates</option> <parameter>TID:x,y</parameter></term> 1920 <listitem> 1921 <para> 1922 Sets the white colour chromaticity coordinates as defined by CIE 1931. 1923 </para> 1924 </listitem> 1925 </varlistentry> 1926 1927 <varlistentry id="mkvmerge.description.max_luminance"> 1928 <term><option>--max-luminance</option> <parameter>TID:float</parameter></term> 1929 <listitem> 1930 <para> 1931 Sets the maximum luminance in candelas per square meter (cd/m²). The value should be less than 9999.99. 1932 </para> 1933 </listitem> 1934 </varlistentry> 1935 1936 <varlistentry id="mkvmerge.description.min_luminance"> 1937 <term><option>--min-luminance</option> <parameter>TID:float</parameter></term> 1938 <listitem> 1939 <para> 1940 Sets the minimum luminance in candelas per square meter (cd/m²). The value should be less than 999.9999. 1941 </para> 1942 </listitem> 1943 </varlistentry> 1944 1945 <varlistentry id="mkvmerge.description.projection_type"> 1946 <term><option>--projection-type</option> <parameter>TID:method</parameter></term> 1947 <listitem> 1948 <para> 1949 Sets the video projection method used. Valid values are 0 (rectangular projection), 1 (equirectangular projection), 2 (cubemap projection) and 3 (mesh projection). 1950 </para> 1951 </listitem> 1952 </varlistentry> 1953 1954 <varlistentry id="mkvmerge.description.projection_private"> 1955 <term><option>--projection-private</option> <parameter>TID:data</parameter></term> 1956 <listitem> 1957 <para> 1958 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. 1959 </para> 1960 </listitem> 1961 </varlistentry> 1962 1963 <varlistentry id="mkvmerge.description.projection_pose_yaw"> 1964 <term><option>--projection-pose-yaw</option> <parameter>TID:float</parameter></term> 1965 <listitem> 1966 <para> 1967 Specifies a yaw rotation to the projection. 1968 </para> 1969 </listitem> 1970 </varlistentry> 1971 1972 <varlistentry id="mkvmerge.description.projection_pose_pitch"> 1973 <term><option>--projection-pose-pitch</option> <parameter>TID:float</parameter></term> 1974 <listitem> 1975 <para> 1976 Specifies a pitch rotation to the projection. 1977 </para> 1978 </listitem> 1979 </varlistentry> 1980 1981 <varlistentry id="mkvmerge.description.projection_pose_roll"> 1982 <term><option>--projection-pose-roll</option> <parameter>TID:float</parameter></term> 1983 <listitem> 1984 <para> 1985 Specifies a roll rotation to the projection. 1986 </para> 1987 </listitem> 1988 </varlistentry> 1989 1990 <varlistentry id="mkvmerge.description.field_order"> 1991 <term><option>--field-order</option> <parameter>TID:n</parameter></term> 1992 <listitem> 1993 <para> 1994 Sets the field order for the video track with the track ID <parameter>TID</parameter>. The order must be one of the following numbers: 1995 </para> 1996 1997 <para> 1998 <constant>0</constant>: progressive; <constant>1</constant>: interlaced with top field displayed first and top field stored first; 1999 <constant>2</constant>: undetermined field order; <constant>6</constant>: interlaced with bottom field displayed first and bottom 2000 field stored first; <constant>9</constant>: interlaced with bottom field displayed first and top field stored first; 2001 <constant>14</constant>: interlaced with top field displayed first and bottom field stored first 2002 </para> 2003 </listitem> 2004 </varlistentry> 2005 2006 <varlistentry id="mkvmerge.description.stereo_mode"> 2007 <term><option>--stereo-mode</option> <parameter>TID:n|keyword</parameter></term> 2008 <listitem> 2009 <para> 2010 Sets the stereo mode for the video track with the track ID <parameter>TID</parameter>. The mode can either be a number 2011 <parameter>n</parameter> between <constant>0</constant> and <constant>14</constant> or one of these keywords: 2012 </para> 2013 2014 <para> 2015 '<literal>mono</literal>', '<literal>side_by_side_left_first</literal>', '<literal>top_bottom_right_first</literal>', 2016 '<literal>top_bottom_left_first</literal>', '<literal>checkerboard_right_first</literal>', 2017 '<literal>checkerboard_left_first</literal>', '<literal>row_interleaved_right_first</literal>', 2018 '<literal>row_interleaved_left_first</literal>', '<literal>column_interleaved_right_first</literal>', 2019 '<literal>column_interleaved_left_first</literal>', '<literal>anaglyph_cyan_red</literal>', 2020 '<literal>side_by_side_right_first</literal>', '<literal>anaglyph_green_magenta</literal>', 2021 '<literal>both_eyes_laced_left_first</literal>', '<literal>both_eyes_laced_right_first</literal>'. 2022 </para> 2023 </listitem> 2024 </varlistentry> 2025 </variablelist> 2026 </refsect2> 2027 2028 <refsect2> 2029 <title>Options that only apply to text subtitle tracks</title> 2030 2031 <variablelist> 2032 <varlistentry id="mkvmerge.description.sub_charset"> 2033 <term><option>--sub-charset</option> <parameter>TID:character-set</parameter></term> 2034 <listitem> 2035 <para> 2036 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 2037 derived from the current locale settings. Note that a charset is not needed for subtitles read from &matroska; files or from Kate 2038 streams, as these are always stored in UTF-8. See the section about <link linkend="mkvmerge.text_files_and_charsets">text files and 2039 character sets</link> for an explanation how &mkvmerge; converts between character sets. 2040 </para> 2041 2042 <para> 2043 This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time. 2044 </para> 2045 </listitem> 2046 </varlistentry> 2047 </variablelist> 2048 </refsect2> 2049 2050 <refsect2> 2051 <title>Other options</title> 2052 2053 <variablelist> 2054 <varlistentry id="mkvmerge.description.identify"> 2055 <term><option>-i</option>, <option>--identify</option> <parameter>file-name</parameter></term> 2056 <listitem> 2057 <para> 2058 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 2059 used then the only other option allowed is the filename. 2060 </para> 2061 2062 <para>The output format used for the result can be changed with the option <link linkend="mkvmerge.description.identification_format">--identification-format</link>.</para> 2063 </listitem> 2064 </varlistentry> 2065 2066 <varlistentry id="mkvmerge.description.identify_json"> 2067 <term><option>-J</option> <parameter>file-name</parameter></term> 2068 <listitem> 2069 <para> 2070 This is a convenient alias for "<literal>--identification-format json --identify file-name</literal>". 2071 </para> 2072 </listitem> 2073 </varlistentry> 2074 2075 <varlistentry id="mkvmerge.description.identification_format"> 2076 <term><option>-F</option>, <option>--identification-format</option> <parameter>format</parameter></term> 2077 <listitem> 2078 <para> 2079 Determines the output format used by the <link linkend="mkvmerge.description.identify"><literal>--identify</literal> 2080 option</link>. The following formats are supported: <literal>text</literal> (the default if this option isn't used) and 2081 <literal>json</literal>. 2082 </para> 2083 2084 <orderedlist> 2085 <listitem> 2086 <para>The <literal>text</literal> format is short and human-readable. It consists of one line per item found (container, tracks, attachments etc.).</para> 2087 2088 <para>This format is not meant to be parsed. The output will be translated into the language &mkvmerge; uses (see also <link 2089 linkend="mkvmerge.description.ui_language">--ui-language</link>).</para> 2090 </listitem> 2091 2092 <listitem> 2093 <para> 2094 The <literal>json</literal> format outputs a machine-readable JSON representation. This format follows the JSON schema described in 2095 the following file: 2096 </para> 2097 2098 <para> 2099 <ulink url="https://mkvtoolnix.download/doc/mkvmerge-identification-output-schema-v14.json"><literal>mkvmerge-identification-output-schema-v14.json</literal></ulink> 2100 </para> 2101 2102 <para> 2103 All versions of the JSON schema are available both online and in the released source code archives. 2104 </para> 2105 </listitem> 2106 </orderedlist> 2107 </listitem> 2108 </varlistentry> 2109 2110 <varlistentry id="mkvmerge.description.probe_range_percentage"> 2111 <term><option>--probe-range-percentage</option> <parameter>percentage</parameter></term> 2112 <listitem> 2113 <para> 2114 File types such as MPEG program and transport streams (<literal>.vob</literal>, <literal>.m2ts</literal>) require parsing a certain 2115 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, 2116 whichever is higher. 2117 </para> 2118 2119 <para> 2120 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 2121 is built-in and cannot be changed. 2122 </para> 2123 </listitem> 2124 </varlistentry> 2125 2126 <varlistentry id="mkvmerge.description.list_types"> 2127 <term><option>-l</option>, <option>--list-types</option></term> 2128 <listitem> 2129 <para> 2130 Lists supported input file types. 2131 </para> 2132 </listitem> 2133 </varlistentry> 2134 2135 <varlistentry id="mkvmerge.description.list_languages"> 2136 <term><option>--list-languages</option></term> 2137 <listitem> 2138 <para> 2139 Lists all languages and their ISO 639-2 code which can be used with the <link 2140 linkend="mkvmerge.description.language"><option>--language</option></link> option. 2141 </para> 2142 </listitem> 2143 </varlistentry> 2144 2145 <varlistentry id="mkvmerge.description.priority"> 2146 <term><option>--priority</option> <parameter>priority</parameter></term> 2147 <listitem> 2148 <para> 2149 Sets the process priority that &mkvmerge; runs with. Valid values are '<literal>lowest</literal>', '<literal>lower</literal>', 2150 '<literal>normal</literal>', '<literal>higher</literal>' and '<literal>highest</literal>'. If nothing is given then 2151 '<literal>normal</literal>' is used. On Unix like systems &mkvmerge; will use the 2152 <citerefentry><refentrytitle>nice</refentrytitle><manvolnum>2</manvolnum></citerefentry> function. Therefore only the super user can 2153 use '<literal>higher</literal>' and '<literal>highest</literal>'. On Windows all values are useable for every user. 2154 </para> 2155 2156 <para>Selecting '<literal>lowest</literal>' also causes &mkvmerge; to select idle I/O priority in addition to the lowest possible 2157 process priority.</para> 2158 </listitem> 2159 </varlistentry> 2160 2161 <varlistentry id="mkvmerge.description.command_line_charset"> 2162 <term><option>--command-line-charset</option> <parameter>character-set</parameter></term> 2163 <listitem> 2164 <para> 2165 Sets the character set to convert strings given on the command line from. It defaults to the character set given by system's current 2166 locale. This settings applies to arguments of the following options: <link 2167 linkend="mkvmerge.description.title"><option>--title</option></link>, <link 2168 linkend="mkvmerge.description.track_name"><option>--track-name</option></link> and <link 2169 linkend="mkvmerge.description.attachment_description"><option>--attachment-description</option></link>. 2170 </para> 2171 </listitem> 2172 </varlistentry> 2173 2174 <varlistentry id="mkvmerge.description.output_charset"> 2175 <term><option>--output-charset</option> <parameter>character-set</parameter></term> 2176 <listitem> 2177 <para> 2178 Sets the character set to which strings are converted that are to be output. It defaults to the character set given by system's 2179 current locale. 2180 </para> 2181 </listitem> 2182 </varlistentry> 2183 2184 <varlistentry id="mkvmerge.description.redirect_output"> 2185 <term><option>-r</option>, <option>--redirect-output</option> <parameter>file-name</parameter></term> 2186 <listitem> 2187 <para> 2188 Writes all messages to the file <parameter>file-name</parameter> instead of to the console. While this can be done easily with output 2189 redirection there are cases in which this option is needed: when the terminal reinterprets the output before writing it to a file. 2190 The character set set with <link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link> is honored. 2191 </para> 2192 </listitem> 2193 </varlistentry> 2194 2195 <varlistentry id="mkvmerge.description.flush_on_close"> 2196 <term><option>--flush-on-close</option></term> 2197 <listitem> 2198 <para> 2199 Tells the program to flush all data cached in memory to storage when closing files opened for writing. 2200 This can be used to prevent data loss on power outages or to circumvent certain problems in the operating system or drivers. 2201 The downside is that multiplexing will take longer as mkvmerge will wait until all data has been written to the storage before exiting. 2202 See issues #2469 and #2480 on the MKVToolNix bug tracker for in-depth discussions on the pros and cons. 2203 </para> 2204 </listitem> 2205 </varlistentry> 2206 2207 <varlistentry id="mkvmerge.description.ui_language"> 2208 <term><option>--ui-language</option> <parameter>code</parameter></term> 2209 <listitem> 2210 <para> 2211 Forces the translations for the language <parameter>code</parameter> to be used (e.g. '<literal>de_DE</literal>' for the German 2212 translations). Entering '<literal>list</literal>' as the <parameter>code</parameter> will cause the program to output a list of 2213 available translations. 2214 </para> 2215 </listitem> 2216 </varlistentry> 2217 2218 <varlistentry id="mkvmerge.description.abort_on_warnings"> 2219 <term><option>--abort-on-warnings</option></term> 2220 <listitem> 2221 <para> 2222 Tells the program to abort after the first warning is emitted. The program's exit code will be 1. 2223 </para> 2224 </listitem> 2225 </varlistentry> 2226 2227 <varlistentry id="mkvmerge.description.deterministic"> 2228 <term><option>--deterministic</option> <parameter>seed</parameter></term> 2229 <listitem> 2230 <para> 2231 Enables the creation of byte-identical files if the same version of &mkvmerge; is used with the same source files, the same set of 2232 options and the same seed. Note that the "date" segment information field is not written in this mode. 2233 </para> 2234 2235 <para>The seed can be an arbitrary string and does not have to be a number.</para> 2236 2237 <para> 2238 The result of byte-identical files is only guaranteed under the following conditions: 2239 </para> 2240 2241 <orderedlist> 2242 <listitem> 2243 <para>The same version of &mkvmerge; built with the same versions of libEBML and libMatroska is used.</para> 2244 </listitem> 2245 2246 <listitem> 2247 <para>The source files used are byte-identical.</para> 2248 </listitem> 2249 2250 <listitem> 2251 <para>The same command line options are used in the same order (with the notable exception of <parameter>--output …</parameter>).</para> 2252 </listitem> 2253 </orderedlist> 2254 2255 <para> 2256 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. 2257 </para> 2258 </listitem> 2259 </varlistentry> 2260 2261 <varlistentry id="mkvmerge.description.debug"> 2262 <term><option>--debug</option> <parameter>topic</parameter></term> 2263 <listitem> 2264 <para> 2265 Turn on debugging for a specific feature. This option is only useful for developers. 2266 </para> 2267 </listitem> 2268 </varlistentry> 2269 2270 <varlistentry id="mkvmerge.description.engage"> 2271 <term><option>--engage</option> <parameter>feature</parameter></term> 2272 <listitem> 2273 <para> 2274 Turn on experimental features. A list of available features can be requested with <command>mkvmerge --engage list</command>. These 2275 features are not meant to be used in normal situations. 2276 </para> 2277 </listitem> 2278 </varlistentry> 2279 2280 <varlistentry id="mkvmerge.description.gui_mode"> 2281 <term><option>--gui-mode</option></term> 2282 <listitem> 2283 <para> 2284 Turns on GUI mode. In this mode specially-formatted lines may be output that can tell a controlling GUI what's happening. These 2285 messages follow the format '<literal>#GUI#message</literal>'. The message may be followed by key/value pairs as in 2286 '<literal>#GUI#message#key1=value1#key2=value2…</literal>'. Neither the messages nor the keys are ever translated and always output 2287 in English. 2288 </para> 2289 </listitem> 2290 </varlistentry> 2291 2292 <varlistentry id="mkvmerge.description.at_sign"> 2293 <term><option>@</option><parameter>options-file.json</parameter></term> 2294 <listitem> 2295 <para> 2296 Reads additional command line arguments from the file <parameter>options-file</parameter>. See the section about <link 2297 linkend="mkvmerge.option_files">option files</link> for further information. 2298 </para> 2299 </listitem> 2300 </varlistentry> 2301 2302 <varlistentry id="mkvmerge.description.capabilities"> 2303 <term><option>--capabilities</option></term> 2304 <listitem> 2305 <para> 2306 Lists information about optional features that have been compiled in and exit. The first line output will be the version 2307 information. All following lines contain exactly one word whose presence indicates that the feature has been compiled in. These 2308 features are: 2309 </para> 2310 2311 <itemizedlist> 2312 <listitem> 2313 <para> 2314 '<literal>FLAC</literal>' -- reading raw <abbrev>FLAC</abbrev> files and handling <abbrev>FLAC</abbrev> tracks in other containers, 2315 e.g. <productname>Ogg</productname> or &matroska;. 2316 </para> 2317 </listitem> 2318 </itemizedlist> 2319 </listitem> 2320 </varlistentry> 2321 2322 <varlistentry id="mkvmerge.description.help"> 2323 <term><option>-h</option>, <option>--help</option></term> 2324 <listitem> 2325 <para> 2326 Show usage information and exit. 2327 </para> 2328 </listitem> 2329 </varlistentry> 2330 2331 <varlistentry id="mkvmerge.description.version"> 2332 <term><option>-V</option>, <option>--version</option></term> 2333 <listitem> 2334 <para> 2335 Show version information and exit. 2336 </para> 2337 </listitem> 2338 </varlistentry> 2339 </variablelist> 2340 </refsect2> 2341 </refsect1> 2342 2343 <refsect1 id="mkvmerge.usage"> 2344 <title>Usage</title> 2345 <para> 2346 For each file the user can select which tracks &mkvmerge; should take. They are all put into the file specified with 2347 <option>-o</option>. A list of known (and supported) source formats can be obtained with the <option>-l</option> option. 2348 </para> 2349 2350 <important> 2351 <para> 2352 The order of command line options is important. Please read the section <link linkend="mkvmerge.option_order">"Option 2353 order"</link> if you're new to the program. 2354 </para> 2355 </important> 2356 </refsect1> 2357 2358 <refsect1 id="mkvmerge.option_order"> 2359 <title>Option order</title> 2360 2361 <para> 2362 The order in which options are entered is important for some options. Options fall into two categories: 2363 </para> 2364 2365 <orderedlist> 2366 <listitem> 2367 <para> 2368 Options that affect the whole program and are not tied to any input file. These include but are not limited to 2369 <option>--command-line-charset</option>, <option>--output</option> or <option>--title</option>. These can appear anywhere on the 2370 command line. 2371 </para> 2372 </listitem> 2373 2374 <listitem> 2375 <para> 2376 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 2377 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 2378 as they all appear before that input file's name. Examples for options applying to an input file are <option>--no-chapters</option> or 2379 <option>--chapter-charset</option>. Examples for options applying to a single track are <option>--default-duration</option> or 2380 <option>--language</option>. 2381 </para> 2382 </listitem> 2383 </orderedlist> 2384 2385 <para> 2386 The options are processed from left to right. If an option appears multiple times within the same scope then the last occurrence will be 2387 used. Therefore the title will be set to "Something else" in the following example: 2388 </para> 2389 2390 <screen>$ mkvmerge -o output.mkv --title 'This and that' input.avi --title 'Something else'</screen> 2391 2392 <para> 2393 The following example shows that using the <option>--language</option> option twice is OK because they're used in different scopes. Even 2394 though they apply to the same track ID they apply to different input files and therefore have different scopes: 2395 </para> 2396 2397 <screen>$ mkvmerge -o output.mkv --language 0:fre français.ogg --language 0:deu deutsch.ogg</screen> 2398 </refsect1> 2399 2400 <refsect1 id="mkvmerge.examples"> 2401 <title>Examples</title> 2402 <para> 2403 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 2404 want to encode the audio to &oggvorbis;: 2405 </para> 2406 2407 <screen>$ oggenc -q4 -oMyMovie.ogg MyMovie.wav</screen> 2408 2409 <para> 2410 After a couple of minutes you can join video and audio: 2411 </para> 2412 2413 <screen>$ mkvmerge -o MyMovie-with-sound.mkv MyMovie.avi MyMovie.ogg</screen> 2414 2415 <para> 2416 If your <abbrev>AVI</abbrev> already contains an audio track then it will be copied as well (if &mkvmerge; supports the audio format). To 2417 avoid that simply do 2418 </para> 2419 2420 <screen>$ mkvmerge -o MyMovie-with-sound.mkv -A MyMovie.avi MyMovie.ogg</screen> 2421 2422 <para> 2423 After some minutes of consideration you rip another audio track, e.g. the director's comments or another language to 2424 '<literal>MyMovie-add-audio.wav</literal>'. Encode it again and join it up with the other file: 2425 </para> 2426 2427 <screen>$ oggenc -q4 -oMyMovie-add-audio.ogg MyMovie-add-audio.wav 2428$ mkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-audio.ogg</screen> 2429 2430 <para> 2431 The same result can be achieved with 2432 </para> 2433 2434 <screen>$ mkvmerge -o MM-complete.mkv -A MyMovie.avi MyMovie.ogg MyMovie-add-audio.ogg</screen> 2435 2436 <para> 2437 Now fire up <productname>mplayer</productname> and enjoy. If you have multiple audio tracks (or even video tracks) then you can tell 2438 <productname>mplayer</productname> which track to play with the '<option>-vid</option>' and '<option>-aid</option>' options. These are 2439 0-based and do not distinguish between video and audio. 2440 </para> 2441 2442 <para> 2443 If you need an audio track synchronized you can do that easily. First find out which track ID the Vorbis track has with 2444 </para> 2445 2446 <screen>$ mkvmerge --identify outofsync.ogg</screen> 2447 2448 <para> 2449 Now you can use that ID in the following command line: 2450 </para> 2451 2452 <screen>$ mkvmerge -o goodsync.mkv -A source.avi -y 12345:200 outofsync.ogg</screen> 2453 2454 <para> 2455 This would add 200ms of silence at the beginning of the audio track with the 2456 ID <constant>12345</constant> taken from '<literal>outofsync.ogg</literal>'. 2457 </para> 2458 2459 <para> 2460 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 2461 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 2462 that an episode I transcoded was <constant>0.2</constant> seconds out of sync at the end of the movie which was 2463 <constant>77340</constant> frames long. At <constant>29.97fps</constant> <constant>0.2</constant> seconds correspond to 2464 approx. <constant>6</constant> frames. So I did 2465 </para> 2466 2467 <screen>$ mkvmerge -o goodsync.mkv -y 23456:0,77346/77340 outofsync.mkv</screen> 2468 2469 <para> 2470 The result was fine. 2471 </para> 2472 2473 <para> 2474 The sync options can also be used for subtitles in the same manner. 2475 </para> 2476 2477 <para> 2478 For text subtitles you can either use some Windows software (like <productname>SubRipper</productname>) or the 2479 <productname>subrip</productname> package found in 2480 <citerefentry><refentrytitle>transcode</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s sources in the 2481 '<literal>contrib/subrip</literal>' directory. The general process is: 2482 </para> 2483 2484 <orderedlist> 2485 <listitem> 2486 <para>extract a raw subtitle stream from the source:</para> 2487 <screen>$ tccat -i /path/to/copied/dvd/ -T 1 -L | tcextract -x ps1 -t vob -a 0x20 | subtitle2pgm -o mymovie</screen> 2488 </listitem> 2489 2490 <listitem> 2491 <para>convert the resulting PGM images to text with gocr:</para> 2492 <screen>$ pgm2txt mymovie</screen> 2493 </listitem> 2494 2495 <listitem> 2496 <para>spell-check the resulting text files:</para> 2497 <screen>$ ispell -d american *txt</screen> 2498 </listitem> 2499 2500 <listitem> 2501 <para>convert the text files to a SRT file:</para> 2502 <screen>$ srttool -s -w -i mymovie.srtx -o mymovie.srt</screen> 2503 </listitem> 2504 </orderedlist> 2505 2506 <para> 2507 The resulting file can be used as another input file for &mkvmerge;: 2508 </para> 2509 2510 <screen>$ mkvmerge -o mymovie.mkv mymovie.avi mymovie.srt</screen> 2511 2512 <para> 2513 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 2514 language. &mkvmerge; can list all of those codes for you: 2515 </para> 2516 2517 <screen>$ mkvmerge --list-languages</screen> 2518 2519 <para> 2520 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 2521 language codes and that their track IDs are 2 and 3. This can be done with 2522 </para> 2523 2524 <screen>$ mkvmerge -o with-lang-codes.mkv --language 2:ger --language 3:dut without-lang-codes.mkv</screen> 2525 2526 <para> 2527 As you can see you can use the <link linkend="mkvmerge.description.language"><option>--language</option></link> switch multiple times. 2528 </para> 2529 2530 <para> 2531 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 2532 and French, and want to have the player display the French ones by default. This can be done with 2533 </para> 2534 2535 <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> 2536 2537 <para> 2538 If you do not see the language or default track flags that you've specified in &mkvinfo;'s output then please read the 2539 section about <link linkend="mkvmerge.default_values">default values</link>. 2540 </para> 2541 2542 <para> 2543 Turn off the compression for an input file. 2544 </para> 2545 2546 <screen>$ mkvmerge -o no-compression.mkv --compression -1:none MyMovie.avi --compression -1:none mymovie.srt</screen> 2547 2548 </refsect1> 2549 2550 <refsect1 id="mkvmerge.track_ids"> 2551 <title>Track IDs</title> 2552 2553 <refsect2 id="mkvmerge.track_ids.regular_ids"> 2554 <title>Regular track IDs</title> 2555 2556 <para> 2557 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 2558 readers when demuxing the current input file, or if &mkvmerge; is called with the <link 2559 linkend="mkvmerge.description.identify"><option>--identify</option></link> option. An example for such output: 2560 </para> 2561 2562 <screen>$ mkvmerge -i v.mkv 2563File 'v.mkv': container: &matroska; 2564Track ID 0: video (V_MS/VFW/FOURCC, DIV3) 2565Track ID 1: audio (A_MPEG/L3)</screen> 2566 2567 <para> 2568 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 2569 files. Only the input file track IDs are used for options needing these values. 2570 </para> 2571 2572 <para> 2573 Also note that each input file has its own set of track IDs. Therefore the track IDs for file '<filename>file1.ext</filename>' as 2574 reported by '<literal>mkvmerge --identify</literal>' do not change no matter how many other input files are there or in which position 2575 '<filename>file1.ext</filename>' is used. 2576 </para> 2577 2578 <para> 2579 Track IDs are assigned like this: 2580 </para> 2581 2582 <itemizedlist> 2583 <listitem> 2584 <para> 2585 <abbrev>AVI</abbrev> files: The video track has the ID 0. The audio tracks get IDs in ascending order starting at 1. 2586 </para> 2587 </listitem> 2588 2589 <listitem> 2590 <para> 2591 <abbrev>AAC</abbrev>, <abbrev>AC-3</abbrev>, <abbrev>MP3</abbrev>, <abbrev>SRT</abbrev> and <abbrev>WAV</abbrev> files: The one 'track' 2592 in that file gets the ID 0. 2593 </para> 2594 </listitem> 2595 2596 <listitem> 2597 <para> 2598 Most other files: The track IDs are assigned in order the tracks are found in the file starting at 0. 2599 </para> 2600 </listitem> 2601 </itemizedlist> 2602 2603 <para> 2604 The options that use the track IDs are the ones whose description contains '<literal>TID</literal>'. The following options use track IDs 2605 as well: <option>--audio-tracks</option>, <option>--video-tracks</option>, <option>--subtitle-tracks</option>, 2606 <option>--button-tracks</option> and <option>--track-tags</option>. 2607 </para> 2608 </refsect2> 2609 2610 <refsect2 id="mkvmerge.track_ids.special_ids"> 2611 <title>Special track IDs</title> 2612 2613 <para> 2614 There are several IDs that have special meaning and do not occur in the identification output. 2615 </para> 2616 2617 <para> 2618 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 2619 file. 2620 </para> 2621 2622 <para> 2623 The special track ID '<constant>-2</constant>' refers to the chapters in a source file. Currently only the <option>--sync</option> 2624 option uses this special ID. As an alternative to <option>--sync -2:…</option> the option <option>--chapter-sync …</option> can be used. 2625 </para> 2626 </refsect2> 2627 </refsect1> 2628 2629 <refsect1 id="mkvmerge.text_files_and_charsets"> 2630 <title>Text files and character set conversions</title> 2631 <note> 2632 <para> 2633 This section applies to all programs in MKVToolNix even if it only mentions &mkvmerge;. 2634 </para> 2635 </note> 2636 2637 <refsect2 id="mkvmerge.text_files_and_charsets.introduction"> 2638 <title>Introduction</title> 2639 <para> 2640 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 2641 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 2642 back to that character set from UTF-8, e.g. if a non-English translation is used with <link 2643 linkend="mkvmerge.description.ui_language"><option>--ui-language</option></link> or for text originating from a &matroska; file. 2644 </para> 2645 2646 <para> 2647 &mkvmerge; does this conversion automatically based on the presence of a byte order marker (short: <abbrev>BOM</abbrev>) or the system's 2648 current locale. How the character set is inferred from the locale depends on the operating system that &mkvmerge; is run on. 2649 </para> 2650 </refsect2> 2651 2652 <refsect2 id="mkvmerge.text_files_and_charsets.byte_order_markers"> 2653 <title>Byte order markers (BOM)</title> 2654 2655 <para> 2656 Text files that start with a BOM are already encoded in one representation of UTF. &mkvmerge; supports the following five modes: UTF-8, 2657 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 2658 parameters that would otherwise set the character set for such a file (e.g. <link 2659 linkend="mkvmerge.description.sub_charset"><option>--sub-charset</option></link>) is silently ignored. 2660 </para> 2661 </refsect2> 2662 2663 <refsect2 id="mkvmerge.text_files_and_charsets.unix"> 2664 <title>Linux and Unix-like systems including macOS</title> 2665 2666 <para> 2667 On Unix-like systems &mkvmerge; uses the <citerefentry><refentrytitle>setlocale</refentrytitle><manvolnum>3</manvolnum></citerefentry> 2668 system call which in turn uses the environment variables <varname>LANG</varname>, <varname>LC_ALL</varname> and 2669 <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 2670 operations and for encoding strings on the command line and for output to the console. 2671 </para> 2672 </refsect2> 2673 2674 <refsect2 id="mkvmerge.text_files_and_charsets.windows"> 2675 <title>Windows</title> 2676 2677 <para> 2678 On Windows the default character set used for converting text files is determined by a call to the <function>GetACP()</function> system 2679 call. 2680 </para> 2681 2682 <para> 2683 Reading the command line is done with the <function>GetCommandLineW()</function> function which already returns a Unicode 2684 string. Therefore the option <option>--command-line-charset</option> is ignored on Windows. 2685 </para> 2686 2687 <para> 2688 Output to the console consists of three scenarios: 2689 </para> 2690 2691 <orderedlist> 2692 <listitem> 2693 <para> 2694 If the output is redirected with the option <link 2695 linkend="mkvmerge.description.redirect_output"><option>--redirect-output</option></link> then the default charset is UTF-8. This can 2696 be changed with <link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link>. 2697 </para> 2698 </listitem> 2699 2700 <listitem> 2701 <para> 2702 If the output is redirected with <command>cmd.exe</command> itself, e.g. with <literal>mkvinfo file.mkv > info.txt</literal>, then 2703 the charset is always UTF-8 and cannot be changed. 2704 </para> 2705 </listitem> 2706 2707 <listitem> 2708 <para> 2709 Otherwise (when writing directly to the console) the Windows function <function>WriteConsoleW()</function> is used and the option 2710 <link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link> is ignored. The console should be able to 2711 output all Unicode characters for which the corresponding language support is installed (e.g. Chinese characters might not be 2712 displayed on English Windows versions). 2713 </para> 2714 </listitem> 2715 </orderedlist> 2716 </refsect2> 2717 2718 <refsect2 id="mkvmerge.text_files_and_charsets.options"> 2719 <title>Command line options</title> 2720 2721 <para> 2722 The following options exist that allow specifying the character sets: 2723 </para> 2724 2725 <itemizedlist> 2726 <listitem> 2727 <para> 2728 <link linkend="mkvmerge.description.sub_charset"><option>--sub-charset</option></link> for text subtitle files and for text subtitle 2729 tracks stored in container formats for which the character set cannot be determined unambiguously (e.g. Ogg files), 2730 </para> 2731 </listitem> 2732 2733 <listitem> 2734 <para> 2735 <link linkend="mkvmerge.description.chapter_charset"><option>--chapter-charset</option></link> for chapter text files and for chapters 2736 and file titles stored in container formats for which the character set cannot be determined unambiguously (e.g. Ogg files for chapter 2737 information, track and file titles etc; MP4 files for chapter information), 2738 </para> 2739 </listitem> 2740 2741 <listitem> 2742 <para> 2743 <link linkend="mkvmerge.description.command_line_charset"><option>--command-line-charset</option></link> for all strings on the command 2744 line, 2745 </para> 2746 </listitem> 2747 2748 <listitem> 2749 <para> 2750 <link linkend="mkvmerge.description.output_charset"><option>--output-charset</option></link> for all strings written to the console or 2751 to a file if the output has been redirected with the <link 2752 linkend="mkvmerge.description.redirect_output"><option>--redirect-output</option></link> option. On non-Windows systems the default for 2753 the output charset is the system's current charset. On Windows it defaults to UTF-8 both for redirecting with <link 2754 linkend="mkvmerge.description.redirect_output"><option>--redirect-output</option></link> and with <command>cmd.exe</command> itself, 2755 e.g. <literal>mkvinfo file.mkv > info.txt</literal>. 2756 </para> 2757 </listitem> 2758 </itemizedlist> 2759 </refsect2> 2760 </refsect1> 2761 2762 <refsect1 id="mkvmerge.option_files"> 2763 <title>Option files</title> 2764 2765 <para> 2766 An option file is a file &mkvmerge; can read additional command line arguments from. This can be used in order to circumvent certain 2767 limitations of the shell or the operating system when executing external programs like a limited command line length. 2768 </para> 2769 2770 <para> 2771 An option file contains JSON-formatted data. Its content must be a valid JSON array consisting solely of JSON strings. The file's 2772 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. 2773 </para> 2774 2775 <para> 2776 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>. 2777 </para> 2778 2779 <para> 2780 The option file's name itself must be specified as a command line argument prefixed with a '<literal>@</literal>' character. 2781 </para> 2782 2783 <para> 2784 The command line '<command>mkvmerge -o "my file.mkv" -A "a movie.avi" sound.ogg</command>' could be converted into the following 2785 JSON option file called e.g. '<filename>options.json</filename>': 2786 </para> 2787 2788 <programlisting>[ 2789 "-o", 2790 "c:\\Matroska\\my file.mkv", 2791 "--title", 2792 "#65", 2793 "-A", 2794 "a movie.avi", 2795 "sound.ogg" 2796]</programlisting> 2797 2798 <para> 2799 The corresponding command would then be '<command>mkvmerge @options.json</command>'. 2800 </para> 2801 </refsect1> 2802 2803 <refsect1 id="mkvmerge.file_linking"> 2804 <title>File linking</title> 2805 <para> 2806 &matroska; supports file linking which simply says that a specific file is the predecessor or successor of the current file. To be precise, 2807 it's not really the files that are linked but the &matroska; segments. As most files will probably only contain one &matroska; segment the 2808 following explanations use the term 'file linking' although 'segment linking' would be more appropriate. 2809 </para> 2810 2811 <para> 2812 Each segment is identified by a unique 128 bit wide segment UID. This UID is automatically generated by &mkvmerge;. The linking is done 2813 primarily via putting the segment UIDs (short: <abbrev>SID</abbrev>) of the previous/next file into the segment header 2814 information. &mkvinfo; prints these <abbrev>SIDs</abbrev> if it finds them. 2815 </para> 2816 2817 <para> 2818 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 2819 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 2820 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 2821 can turn it on with the <option>--link</option> option. This option is only useful if splitting is activated as well. 2822 </para> 2823 2824 <para> 2825 Regardless of whether splitting is active or not the user can tell &mkvmerge; to link the produced files to specific 2826 <abbrev>SIDs</abbrev>. This is achieved with the options <option>--link-to-previous</option> and <option>--link-to-next</option>. These 2827 options accept a segment <abbrev>SID</abbrev> in the format that &mkvinfo; outputs: 16 hexadecimal numbers between 2828 <constant>0x00</constant> and <constant>0xff</constant> prefixed with '<literal>0x</literal>' each, e.g. '<code>0x41 0xda 0x73 0x66 2829 0xd9 0xcf 0xb2 0x1e 0xae 0x78 0xeb 0xb4 0x5e 0xca 0xb3 0x93</code>'. Alternatively a shorter form can be used: 16 hexadecimal numbers 2830 between <constant>0x00</constant> and <constant>0xff</constant> without the '<literal>0x</literal>' prefixes and without the spaces, e.g. 2831 '<code>41da7366d9cfb21eae78ebb45ecab393</code>'. 2832 </para> 2833 2834 <para> 2835 If splitting is used then the first file is linked to the <abbrev>SID</abbrev> given with <option>--link-to-previous</option> and the 2836 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 2837 file will be linked to both of the two <abbrev>SIDs</abbrev>. 2838 </para> 2839 </refsect1> 2840 2841 <refsect1 id="mkvmerge.default_values"> 2842 <title>Default values</title> 2843 <para> 2844 The &matroska; specification states that some elements have a default value. Usually an element is not written to the file if its value 2845 is equal to its default value in order to save space. The elements that the user might miss in &mkvinfo;'s output are the 2846 <parameter>language</parameter> and the <parameter>default track flag</parameter> elements. The default value for the 2847 <parameter>language</parameter> is English ('<literal>eng</literal>'), and the default value for the <parameter>default track 2848 flag</parameter> is <parameter>true</parameter>. Therefore if you used <option>--language 0:eng</option> for a track then it will not 2849 show up in &mkvinfo;'s output. 2850 </para> 2851 </refsect1> 2852 2853 <refsect1 id="mkvmerge.attachments"> 2854 <title>Attachments</title> 2855 <para> 2856 Maybe you also want to keep some photos along with your &matroska; file, or you're using <abbrev>SSA</abbrev> subtitles and need a 2857 special <productname>TrueType</productname> font that's really rare. In these cases you can attach those files to the &matroska; 2858 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 2859 to render the subtitles (the '<productname>TrueType</productname> fonts' case). 2860 </para> 2861 2862 <para> 2863 Here's an example how to attach a photo and a <productname>TrueType</productname> font to the output file: 2864 </para> 2865 2866 <screen>$ mkvmerge -o output.mkv -A video.avi sound.ogg \ 2867 --attachment-description "Me and the band behind the stage in a small get-together" \ 2868 --attachment-mime-type image/jpeg \ 2869 --attach-file me_and_the_band.jpg \ 2870 --attachment-description "The real rare and unbelievably good looking font" \ 2871 --attachment-mime-type application/octet-stream \ 2872 --attach-file really_cool_font.ttf</screen> 2873 2874 <para> 2875 If a &matroska; containing attachments file is used as an input file then &mkvmerge; will copy the attachments into the new file. The 2876 selection which attachments are copied and which are not can be changed with the options <link 2877 linkend="mkvmerge.description.attachments"><option>--attachments</option></link> and <link 2878 linkend="mkvmerge.description.no_attachments"><option>--no-attachments</option></link>. 2879 </para> 2880 </refsect1> 2881 2882 <refsect1 id="mkvmerge.chapters"> 2883 <title>Chapters</title> 2884 <para> 2885 The &matroska; chapter system is more powerful than the old known system used by <abbrev>OGM</abbrev> files. The full specifications can 2886 be found at <ulink url="https://www.matroska.org/">the &matroska; website</ulink>. 2887 </para> 2888 2889 <para> 2890 &mkvmerge; supports two kinds of chapter files as its input. The first format, called 'simple chapter format', is the same format that 2891 the <abbrev>OGM</abbrev> tools expect. The second format is a &xml; based chapter format which supports all of &matroska;'s chapter 2892 functionality. 2893 </para> 2894 2895 <para> 2896 Apart from dedicated chapter files &mkvmerge; can also read chapters from other file formats (e.g. MP4, Ogg, Blu-rays or DVDs). 2897 </para> 2898 2899 <refsect2 id="mkvmerge.chapters.simple"> 2900 <title>The simple chapter format</title> 2901 2902 <para> 2903 This format consists of pairs of lines that start with '<literal>CHAPTERxx=</literal>' and '<literal>CHAPTERxxNAME=</literal>' 2904 respectively. The first one contains the start timestamp while the second one contains the title. Here's an example: 2905 </para> 2906 2907 <screen>CHAPTER01=00:00:00.000 2908CHAPTER01NAME=Intro 2909CHAPTER02=00:02:30.000 2910CHAPTER02NAME=Baby prepares to rock 2911CHAPTER03=00:02:42.300 2912CHAPTER03NAME=Baby rocks the house</screen> 2913 2914 <para> 2915 &mkvmerge; will transform every pair or lines into one &matroska; <classname>ChapterAtom</classname>. It does not set any 2916 <classname>ChapterTrackNumber</classname> which means that the chapters all apply to all tracks in the file. 2917 </para> 2918 2919 <para> 2920 As this is a text file character set conversion may need to be done. See the section about <link 2921 linkend="mkvmerge.text_files_and_charsets">text files and character sets</link> for an explanation how &mkvmerge; converts between 2922 character sets. 2923 </para> 2924 </refsect2> 2925 2926 <refsect2 id="mkvmerge.chapters.xml"> 2927 <title>The &xml; based chapter format</title> 2928 <para> 2929 The &xml; based chapter format looks like this example: 2930 </para> 2931 2932 <screen><?xml version="1.0" encoding="ISO-8859-1"?> 2933<!DOCTYPE Chapters SYSTEM "matroskachapters.dtd"> 2934<Chapters> 2935 <EditionEntry> 2936 <ChapterAtom> 2937 <ChapterTimeStart>00:00:30.000</ChapterTimeStart> 2938 <ChapterTimeEnd>00:01:20.000</ChapterTimeEnd> 2939 <ChapterDisplay> 2940 <ChapterString>A short chapter</ChapterString> 2941 <ChapterLanguage>eng</ChapterLanguage> 2942 </ChapterDisplay> 2943 <ChapterAtom> 2944 <ChapterTimeStart>00:00:46.000</ChapterTimeStart> 2945 <ChapterTimeEnd>00:01:10.000</ChapterTimeEnd> 2946 <ChapterDisplay> 2947 <ChapterString>A part of that short chapter</ChapterString> 2948 <ChapterLanguage>eng</ChapterLanguage> 2949 </ChapterDisplay> 2950 </ChapterAtom> 2951 </ChapterAtom> 2952 </EditionEntry> 2953</Chapters></screen> 2954 2955 <para> 2956 With this format three things are possible that are not possible with the simple chapter format: 2957 </para> 2958 2959 <orderedlist> 2960 <listitem><para>The timestamp for the end of the chapter can be set,</para></listitem> 2961 <listitem><para>chapters can be nested,</para></listitem> 2962 <listitem><para>the language and country can be set.</para></listitem> 2963 </orderedlist> 2964 2965 <para> 2966 The mkvtoolnix distribution contains some sample files in the <filename>doc</filename> subdirectory which can be used as a basis. 2967 </para> 2968 2969 <para> 2970 The following lists the supported XML tags, their data types and, where appropriate, the valid range for their values: 2971 </para> 2972 2973 <screen>Chapters (master) 2974 EditionEntry (master) 2975 EditionUID (unsigned integer, valid range: 1 <= value) 2976 EditionFlagHidden (unsigned integer, valid range: 0 <= value <= 1) 2977 EditionFlagDefault (unsigned integer, valid range: 0 <= value <= 1) 2978 EditionFlagOrdered (unsigned integer, valid range: 0 <= value <= 1) 2979 ChapterAtom (master) 2980 ChapterAtom (master) 2981 ChapterUID (unsigned integer, valid range: 1 <= value) 2982 ChapterTimeStart (unsigned integer) 2983 ChapterTimeEnd (unsigned integer) 2984 ChapterFlagHidden (unsigned integer, valid range: 0 <= value <= 1) 2985 ChapterFlagEnabled (unsigned integer, valid range: 0 <= value <= 1) 2986 ChapterSegmentUID (binary, valid range: 1 <= length in bytes) 2987 ChapterSegmentEditionUID (unsigned integer, valid range: 1 <= value) 2988 ChapterPhysicalEquiv (unsigned integer) 2989 ChapterTrack (master) 2990 ChapterTrackNumber (unsigned integer, valid range: 1 <= value) 2991 ChapterDisplay (master) 2992 ChapterString (UTF-8 string) 2993 ChapterLanguage (UTF-8 string) 2994 ChapterCountry (UTF-8 string) 2995 ChapterProcess (master) 2996 ChapterProcessCodecID (unsigned integer) 2997 ChapterProcessPrivate (binary) 2998 ChapterProcessCommand (master) 2999 ChapterProcessTime (unsigned integer) 3000 ChapterProcessData (binary)</screen> 3001 </refsect2> 3002 3003 <refsect2 id="mkvmerge.chapters.blurays"> 3004 <title>Reading chapters from Blu-rays</title> 3005 3006 <para> 3007 &mkvmerge; can read chapters from unencrypted Blu-rays. For that you can use the path to one of the MPLS play lists with the 3008 <parameter>--chapters</parameter> parameter. 3009 </para> 3010 3011 <para> 3012 Example: <literal>--chapters /srv/blurays/BigBuckBunny/BDMV/PLAYLIST/00001.mpls</literal> 3013 </para> 3014 </refsect2> 3015 3016 <refsect2 id="mkvmerge.chapters.dvds"> 3017 <title>Reading chapters from DVDs</title> 3018 3019 <para> 3020 When MKVToolNix is compiled with the <productname>libdvdread</productname> library, &mkvmerge; can read chapters from DVDs. For that you 3021 can use the path to one of the folders or files on the DVD with the <parameter>--chapters</parameter> parameter. As DVDs can contain 3022 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 3023 file name argument. The title number defaults to 1. 3024 </para> 3025 3026 <para> 3027 Example: <literal>--chapters /srv/dvds/BigBuckBunny/VIDEO_TS:2</literal> 3028 </para> 3029 </refsect2> 3030 3031 <refsect2> 3032 <title>General notes</title> 3033 <para> 3034 When splitting files &mkvmerge; will correctly adjust the chapters as well. This means that each file only includes the chapter entries 3035 that apply to it, and that the timestamps will be offset to match the new timestamps of each output file. 3036 </para> 3037 3038 <para> 3039 &mkvmerge; is able to copy chapters from &matroska; source files unless this is explicitly disabled with the <link 3040 linkend="mkvmerge.description.no_chapters"><option>--no-chapters</option></link> option. The chapters from all sources (&matroska; files, 3041 Ogg files, <abbrev>MP4</abbrev> files, chapter text files) are usually not merged but end up in separate 3042 <classname>ChapterEditions</classname>. Only if chapters are read from several &matroska; or &xml; files that share the 3043 same edition UIDs will chapters be merged into a single <classname>ChapterEdition</classname>. If such a merge is desired in other 3044 situations as well then the user has to extract the chapters from all sources with &mkvextract; first, merge the &xml; 3045 files manually and mux them afterwards. 3046 </para> 3047 </refsect2> 3048 </refsect1> 3049 3050 <refsect1 id="mkvmerge.tags"> 3051 <title>Tags</title> 3052 3053 <refsect2> 3054 <title>Introduction</title> 3055 3056 <para> 3057 &matroska;'s tag system is similar to that of other containers: a set of <parameter>KEY=VALUE</parameter> pairs. However, in &matroska; 3058 these tags can also be nested, and both the <parameter>KEY</parameter> and the <parameter>VALUE</parameter> are elements of their 3059 own. The example file <filename>example-tags-2.xml</filename> shows how to use this system. 3060 </para> 3061 </refsect2> 3062 3063 <refsect2 id="mkvmerge.tags.scope"> 3064 <title>Scope of the tags</title> 3065 3066 <para> 3067 &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 3068 or more tracks, to one or more chapters, or even to a combination of both. The <ulink 3069 url="https://www.matroska.org/technical/specs/index.html">&matroska; specification</ulink> gives more details about this fact. 3070 </para> 3071 3072 <para> 3073 One important fact is that tags are linked to tracks or chapters with the <classname>Targets</classname> &matroska; tag element, and 3074 that the UIDs used for this linking are <emphasis>not</emphasis> the track IDs &mkvmerge; uses everywhere. Instead the numbers used are 3075 the UIDs which &mkvmerge; calculates automatically (if the track is taken from a file format other than &matroska;) or which are copied 3076 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 3077 file before the file is handed over to &mkvmerge;. 3078 </para> 3079 3080 <para> 3081 &mkvmerge; knows two options with which you can add tags to &matroska; files: The <link 3082 linkend="mkvmerge.description.global_tags"><option>--global-tags</option></link> and the <link 3083 linkend="mkvmerge.description.tags"><option>--tags</option></link> options. The difference is that the former option, <link 3084 linkend="mkvmerge.description.global_tags"><option>--global-tags</option></link>, will make the tags apply to the complete file by 3085 removing any of those <classname>Targets</classname> elements mentioned above. The latter option, <link 3086 linkend="mkvmerge.description.tags"><option>--tags</option></link>, automatically inserts the UID that &mkvmerge; generates for the tag 3087 specified with the <parameter>TID</parameter> part of the <link linkend="mkvmerge.description.tags"><option>--tags</option></link> 3088 option. 3089 </para> 3090 </refsect2> 3091 3092 <refsect2 id="mkvmerge.tags.example"> 3093 <title>Example</title> 3094 <para> 3095 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> 3096 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 3097 <classname>Targets</classname> elements and call &mkvmerge;: 3098 </para> 3099 3100 <screen>$ mkvmerge -o file.mkv --tags 0:tags.xml file.avi</screen> 3101 </refsect2> 3102 3103 <refsect2 id="mkvmerge.tags.file_format"> 3104 <title>Tag file format</title> 3105 <para> 3106 &mkvmerge; supports a &xml; based tag file format. The format is very closely modeled after the <ulink 3107 url="https://www.matroska.org/technical/specs/index.html">&matroska; specification</ulink>. Both the binary and the source distributions 3108 of MKVToolNix come with a sample file called <filename>example-tags-2.xml</filename> which simply lists all known tags and which can be 3109 used as a basis for real life tag files. 3110 </para> 3111 3112 <para> 3113 The basics are: 3114 </para> 3115 3116 <itemizedlist> 3117 <listitem><para>The outermost element must be <classname><Tags></classname>.</para></listitem> 3118 <listitem> 3119 <para>One logical tag is contained inside one pair of <classname><Tag></classname> &xml; tags.</para> 3120 </listitem> 3121 <listitem><para>White spaces directly before and after tag contents are ignored.</para></listitem> 3122 </itemizedlist> 3123 </refsect2> 3124 3125 <refsect2 id="mkvmerge.tags.data_types"> 3126 <title>Data types</title> 3127 <para> 3128 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 3129 the <classname><String></classname> element while the binary type is used for the <classname><Binary></classname> element. 3130 </para> 3131 3132 <para> 3133 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 3134 &xml; tag starts with '<literal>@</literal>' then the following text is treated as a file name. The corresponding file's content is 3135 copied into the &matroska; element. 3136 </para> 3137 3138 <para> 3139 Otherwise the data is expected to be Base64 encoded. This is an encoding that transforms binary data into a limited set of 3140 <abbrev>ASCII</abbrev> characters and is used e.g. in email programs. &mkvextract; will output Base64 encoded data for binary elements. 3141 </para> 3142 3143 <para> 3144 The deprecated tagging system knows some more data types which can be found in the official &matroska; tag specs. As &mkvmerge; does not 3145 support this system anymore these types aren't described here. 3146 </para> 3147 </refsect2> 3148 3149 <refsect2 id="mkvmerge.tags.xml"> 3150 <title>Known tags for the XML file format</title> 3151 3152 <para> 3153 The following lists the supported XML tags, their data types and, where appropriate, the valid range for their values: 3154 </para> 3155 3156 <screen>Tags (master) 3157 Tag (master) 3158 Targets (master) 3159 TargetTypeValue (unsigned integer) 3160 TargetType (UTF-8 string) 3161 TrackUID (unsigned integer) 3162 EditionUID (unsigned integer) 3163 ChapterUID (unsigned integer) 3164 AttachmentUID (unsigned integer) 3165 Simple (master) 3166 Simple (master) 3167 Name (UTF-8 string) 3168 TagLanguage (UTF-8 string) 3169 DefaultLanguage (unsigned integer) 3170 String (UTF-8 string) 3171 Binary (binary)</screen> 3172 </refsect2> 3173 </refsect1> 3174 3175 <refsect1 id="mkvmerge.segmentinfo"> 3176 <title>The segment info XML files</title> 3177 3178 <para> 3179 With a segment info XML file it is possible to set certain values in the "segment information" header field of a &matroska; 3180 file. All of these values cannot be set via other command line options. 3181 </para> 3182 3183 <para> 3184 Other "segment information" header fields can be set via command line options but not via the XML file. This includes e.g. the 3185 <option><link linkend="mkvmerge.description.title">--title</link></option> and the <option><link 3186 linkend="mkvmerge.description.timestamp_scale">--timestamp-scale</link></option> options. 3187 </para> 3188 3189 <para> 3190 There are other elements that can be set neither via command line options nor via the XML files. These include the following elements: 3191 <varname>DateUTC</varname> (also known as the "muxing date"), <varname>MuxingApp</varname>, <varname>WritingApp</varname> 3192 and <varname>Duration</varname>. They're always set by &mkvmerge; itself. 3193 </para> 3194 3195 <para> 3196 The following lists the supported XML tags, their data types and, where appropriate, the valid range for their values: 3197 </para> 3198 3199 <screen>Info (master) 3200 SegmentUID (binary, valid range: length in bytes == 16) 3201 SegmentFilename (UTF-8 string) 3202 PreviousSegmentUID (binary, valid range: length in bytes == 16) 3203 PreviousSegmentFilename (UTF-8 string) 3204 NextSegmentUID (binary, valid range: length in bytes == 16) 3205 NextSegmentFilename (UTF-8 string) 3206 SegmentFamily (binary, valid range: length in bytes == 16) 3207 ChapterTranslate (master) 3208 ChapterTranslateEditionUID (unsigned integer) 3209 ChapterTranslateCodec (unsigned integer) 3210 ChapterTranslateID (binary)</screen> 3211 </refsect1> 3212 3213 <refsect1 id="mkvmerge.file_layout"> 3214 <title>&matroska; file layout</title> 3215 <para> 3216 The &matroska; file layout is quite flexible. &mkvmerge; will render a file in a predefined way. The resulting file looks like this: 3217 </para> 3218 3219 <para> 3220 [EBML head] [segment {meta seek #1} [segment information] [track information] {attachments} {chapters} [cluster 1] {cluster 2} ... 3221 {cluster n} {cues} {meta seek #2} {tags}] 3222 </para> 3223 3224 <para> 3225 The elements in curly braces are optional and depend on the contents and options used. A couple of notes: 3226 </para> 3227 3228 <itemizedlist> 3229 <listitem> 3230 <para> 3231 meta seek #1 includes only a small number of level 1 elements, and only if they actually exist: attachments, chapters, cues, tags, meta 3232 seek #2. Older versions of &mkvmerge; used to put the clusters into this meta seek element as well. Therefore some imprecise guessing 3233 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 3234 the meta seek element #2. 3235 </para> 3236 </listitem> 3237 3238 <listitem> 3239 <para>Attachment, chapter and tag elements are only present if they were added.</para> 3240 </listitem> 3241 </itemizedlist> 3242 3243 <para> 3244 The shortest possible &matroska; file would look like this: 3245 </para> 3246 3247 <para> 3248 [EBML head] [segment [segment information] [track information] [cluster 1]] 3249 </para> 3250 3251 <para> 3252 This might be the case for audio-only files. 3253 </para> 3254 </refsect1> 3255 3256 <refsect1 id="mkvmerge.external_timestamp_files"> 3257 <title>External timestamp files</title> 3258 <para> 3259 &mkvmerge; allows the user to chose the timestamps for a specific track himself. This can be used in order to create files with variable 3260 frame rate video or include gaps in audio. A frame in this case is the unit that &mkvmerge; creates separately per &matroska; block. For 3261 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 3262 packet containing <constant>1536</constant> samples. 3263 </para> 3264 3265 <para> 3266 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 3267 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: 3268 </para> 3269 3270 <screen>$ mkvmerge ... --timestamps 0:my_timestamps.txt v1.avi +v2.avi</screen> 3271 3272 <para> 3273 There are four formats that are recognized by &mkvmerge;. The first line always contains the version number. Empty lines, lines 3274 containing only whitespace and lines beginning with '<literal>#</literal>' are ignored. 3275 </para> 3276 3277 <refsect2> 3278 <title>Timestamp file format v1</title> 3279 <para> 3280 This format starts with the version line. The second line declares the default number of frames per second. All following lines contain 3281 three numbers separated by commas: the start frame (<constant>0</constant> is the first frame), the end frame and the number of frames 3282 in this range. The <abbrev>FPS</abbrev> is a floating point number with the dot '<literal>.</literal>' as the decimal point. The ranges 3283 can contain gaps for which the default <abbrev>FPS</abbrev> is used. An example: 3284 </para> 3285 3286 <screen># timestamp format v1 3287assume 27.930 3288800,1000,25 32891500,1700,30</screen> 3290 </refsect2> 3291 3292 <refsect2> 3293 <title>Timestamp file format v2</title> 3294 3295 <para> 3296 In this format each line contains a timestamp for the corresponding frame. This timestamp must be given in millisecond precision. It can 3297 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 3298 are frames in the track. The timestamps in this file must be sorted. Example for 25fps: 3299 </para> 3300 3301 <screen># timestamp format v2 33020 330340 330480</screen> 3305 </refsect2> 3306 3307 <refsect2> 3308 <title>Timestamp file format v3</title> 3309 <para> 3310 In this format each line contains a duration in seconds followed by an optional number of frames per second. Both can be floating point 3311 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 3312 frame timestamps itself. For that you should be using <constant>0.0</constant> as the number of frames per second. You can also create 3313 gaps in the stream by using the '<literal>gap</literal>' keyword followed by the duration of the gap. Example for an audio file: 3314 </para> 3315 3316 <screen># timestamp format v3 3317assume 0.0 331825.325 33197.530,38.236 3320gap, 10.050 33212.000,38.236</screen> 3322 </refsect2> 3323 3324 <refsect2> 3325 <title>Timestamp file format v4</title> 3326 <para> 3327 This format is identical to the v2 format. The only difference is that the timestamps do not have to be sorted. This format should 3328 almost never be used. 3329 </para> 3330 </refsect2> 3331 </refsect1> 3332 3333 <refsect1 id="mkvmerge.exit_codes"> 3334 <title>Exit codes</title> 3335 3336 <para> 3337 &mkvmerge; exits with one of three exit codes: 3338 </para> 3339 3340 <itemizedlist> 3341 <listitem> 3342 <para> 3343 <constant>0</constant> -- This exit code means that muxing has completed successfully. 3344 </para> 3345 </listitem> 3346 3347 <listitem> 3348 <para> 3349 <constant>1</constant> -- In this case &mkvmerge; has output at least one warning, but muxing did continue. A warning is prefixed with 3350 the text '<literal>Warning:</literal>'. Depending on the issues involved the resulting file might be ok or not. The user is urged to 3351 check both the warning and the resulting file. 3352 </para> 3353 </listitem> 3354 3355 <listitem> 3356 <para> 3357 <constant>2</constant> -- This exit code is used after an error occurred. &mkvmerge; aborts right after outputting the error message. 3358 Error messages range from wrong command line arguments over read/write errors to broken files. 3359 </para> 3360 </listitem> 3361 </itemizedlist> 3362 </refsect1> 3363 3364 <refsect1 id="mkvmerge.environment_variables"> 3365 <title>Environment variables</title> 3366 3367 <para> 3368 &mkvmerge; uses the default variables that determine the system's locale (e.g. <varname>LANG</varname> and the <varname>LC_*</varname> 3369 family). Additional variables: 3370 </para> 3371 3372 <variablelist> 3373 <varlistentry id="mkvmerge.environment_variables.debug"> 3374 <term><varname>MKVMERGE_DEBUG</varname>, <varname>MKVTOOLNIX_DEBUG</varname> and its short form <varname>MTX_DEBUG</varname></term> 3375 <listitem> 3376 <para>The content is treated as if it had been passed via the <link 3377 linkend="mkvmerge.description.debug"><option>--debug</option></link> option.</para> 3378 </listitem> 3379 </varlistentry> 3380 3381 <varlistentry id="mkvmerge.environment_variables.engage"> 3382 <term><varname>MKVMERGE_ENGAGE</varname>, <varname>MKVTOOLNIX_ENGAGE</varname> and its short form <varname>MTX_ENGAGE</varname></term> 3383 <listitem> 3384 <para>The content is treated as if it had been passed via the <link 3385 linkend="mkvmerge.description.engage"><option>--engage</option></link> option.</para> 3386 </listitem> 3387 </varlistentry> 3388 </variablelist> 3389 </refsect1> 3390 3391 <refsect1 id="mkvmerge.seealso"> 3392 <title>See also</title> 3393 <para> 3394 &mkvinfo;, &mkvextract;, &mkvpropedit;, &mtxgui; 3395 </para> 3396 </refsect1> 3397 3398 <refsect1 id="mkvmerge.www"> 3399 <title>WWW</title> 3400 <para> 3401 The latest version can always be found at <ulink url="https://mkvtoolnix.download/">the MKVToolNix homepage</ulink>. 3402 </para> 3403 </refsect1> 3404 3405</refentry> 3406
