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 "mkvpropedit"> 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="mkvextract"> 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>Modify properties of existing &matroska; files without a complete remux</refpurpose> 46 </refnamediv> 47 48 <refsynopsisdiv id="mkvpropedit.synopsis"> 49 <title>Synopsis</title> 50 <cmdsynopsis> 51 <command>mkvpropedit</command> 52 <arg>options</arg> 53 <arg choice="req">source-filename</arg> 54 <arg choice="req">actions</arg> 55 </cmdsynopsis> 56 </refsynopsisdiv> 57 58 <refsect1 id="mkvpropedit.description"> 59 <title>Description</title> 60 <para> 61 This program analyses an existing &matroska; file and modifies some of its properties. Then it writes those modifications to the existing 62 file. Among the properties that can be changed are the segment information elements (e.g. the title) and the track headers (e.g. the 63 language code, 'default track' flag or the name). 64 </para> 65 66 <para> 67 Options: 68 </para> 69 70 <variablelist> 71 <varlistentry id="mkvpropedit.description.list_property_names"> 72 <term><option>-l</option>, <option>--list-property-names</option></term> 73 <listitem> 74 <para> 75 Lists all known and editable property names, their type (string, integer, boolean etc) and a short description. The program exits 76 afterwards. Therefore the <parameter>source-filename</parameter> parameter does not have to be supplied. 77 </para> 78 </listitem> 79 </varlistentry> 80 81 <varlistentry id="mkvpropedit.description.parse_mode"> 82 <term><option>-p</option>, <option>--parse-mode</option> <parameter>mode</parameter></term> 83 <listitem> 84 <para> 85 Sets the parse mode. The parameter '<parameter>mode</parameter>' can either be '<literal>fast</literal>' (which is also the default) 86 or '<literal>full</literal>'. The '<literal>fast</literal>' mode does not parse the whole file but uses the meta seek elements for 87 locating the required elements of a source file. In 99% of all cases this is enough. But for files that do not contain meta seek 88 elements or which are damaged the user might have to set the '<literal>full</literal>' parse mode. A full scan of a file can take a 89 couple of minutes while a fast scan only takes seconds. 90 </para> 91 </listitem> 92 </varlistentry> 93 </variablelist> 94 95 <para> 96 Actions that deal with track and segment info properties: 97 </para> 98 99 <variablelist> 100 <varlistentry id="mkvpropedit.description.edit"> 101 <term><option>-e</option>, <option>--edit</option> <parameter>selector</parameter></term> 102 <listitem> 103 <para> 104 Sets the &matroska; file section (segment information or a certain track's headers) that all following <link 105 linkend="mkvpropedit.description.add">add</link>, <link linkend="mkvpropedit.description.set">set</link> and <link 106 linkend="mkvpropedit.description.delete">delete</link> actions operate on. This option can be used multiple times in order to make 107 modifications to more than one element. 108 </para> 109 110 <para> 111 By default &mkvpropedit; will edit the segment information section. 112 </para> 113 114 <para> 115 See the section about <link linkend="mkvpropedit.edit_selectors">edit selectors</link> for a full description of the syntax. 116 </para> 117 </listitem> 118 </varlistentry> 119 120 <varlistentry id="mkvpropedit.description.add"> 121 <term><option>-a</option>, <option>--add</option> <parameter>name</parameter>=<parameter>value</parameter></term> 122 <listitem> 123 <para> 124 Adds a property <parameter>name</parameter> with the value <parameter>value</parameter>. The property will be added even if such a 125 property exists already. Note that most properties are unique and cannot occur more than once. 126 </para> 127 </listitem> 128 </varlistentry> 129 130 <varlistentry id="mkvpropedit.description.set"> 131 <term><option>-s</option>, <option>--set</option> <parameter>name</parameter>=<parameter>value</parameter></term> 132 <listitem> 133 <para> 134 Sets all occurrences of the property <parameter>name</parameter> to the value <parameter>value</parameter>. If no such property exists 135 then it will be added. 136 </para> 137 </listitem> 138 </varlistentry> 139 140 <varlistentry id="mkvpropedit.description.delete"> 141 <term><option>-d</option>, <option>--delete</option> <parameter>name</parameter></term> 142 <listitem> 143 <para> 144 Deletes all occurrences of the property <parameter>name</parameter>. Note that some properties are required and cannot be deleted. 145 </para> 146 </listitem> 147 </varlistentry> 148 </variablelist> 149 150 <para> 151 Actions that deal with tags and chapters: 152 </para> 153 154 <variablelist> 155 <varlistentry id="mkvpropedit.description.tags"> 156 <term><option>-t</option>, <option>--tags</option> <parameter>selector</parameter>:<parameter>filename</parameter></term> 157 <listitem> 158 <para> 159 Add or replace tags in the file with the ones from <filename>filename</filename> or remove them if <filename>filename</filename> is 160 empty. &mkvpropedit; reads the same XML tag format that &mkvmerge; reads as well. 161 </para> 162 163 <para> 164 The <parameter>selector</parameter> must be one of the words <constant>all</constant>, <constant>global</constant> or 165 <constant>track</constant>. For <constant>all</constant> &mkvpropedit; will replace or remove all tags in a file. With 166 <constant>global</constant> only global tags will be replaced or removed. 167 </para> 168 169 <para> 170 With <constant>track</constant> &mkvpropedit; will replace tags for a specific track. Additionally the tags read from 171 <filename>filename</filename> will be assigned to the same track. The track is specified in the same way <link 172 linkend="mkvpropedit.edit_selectors">edit selectors</link> are specified (see below), e.g. <code>--tags 173 track:a1:new-audio-tags.xml</code>. 174 </para> 175 </listitem> 176 </varlistentry> 177 178 <varlistentry id="mkvpropedit.description.add_track_statistics_tags"> 179 <term><option>--add-track-statistics-tags</option></term> 180 <listitem> 181 <para> 182 Calculates statistics for all tracks in a file and adds new statistics tags for them. If the file already contains such tags then they'll be updated. 183 </para> 184 </listitem> 185 </varlistentry> 186 187 <varlistentry id="mkvpropedit.description.delete_track_statistics_tags"> 188 <term><option>--delete-track-statistics-tags</option></term> 189 <listitem> 190 <para> 191 Deletes all existing track statistics tags from a file. If the file doesn't contain track statistics tags then it won't be modified. 192 </para> 193 </listitem> 194 </varlistentry> 195 196 <varlistentry id="mkvpropedit.description.chapters"> 197 <term><option>-c</option>, <option>--chapters</option> <parameter>filename</parameter></term> 198 <listitem> 199 <para> 200 Add or replace chapters in the file with the ones from <filename>filename</filename> or remove them if <filename>filename</filename> is 201 empty. &mkvpropedit; reads the same XML and simple chapter formats that &mkvmerge; reads as well. 202 </para> 203 </listitem> 204 </varlistentry> 205 </variablelist> 206 207 <para> 208 Actions for handling attachments: 209 </para> 210 211 <variablelist> 212 <varlistentry id="mkvpropedit.description.add_attachment"> 213 <term><option>--add-attachment</option> <parameter>filename</parameter></term> 214 <listitem> 215 <para> 216 Adds a new attachment from <parameter>filename</parameter>. 217 </para> 218 219 <para> 220 If the option <option>--attachment-name</option> has been used prior to this option then its value is used as the new attachment's 221 name. Otherwise it is derived from <parameter>filename</parameter>. 222 </para> 223 224 <para> 225 If the option <option>--attachment-mime-type</option> has been used prior to this option then its value is used as the new 226 attachment's MIME type. Otherwise it is auto-detected from the content of <parameter>filename</parameter>. 227 </para> 228 229 <para> 230 If the option <option>--attachment-description</option> has been used prior to this option then its value is used as the new 231 attachment's description. Otherwise no description will be set. 232 </para> 233 234 <para> 235 If the option <option>--attachment-uid</option> has been used prior to this option then its value is used as the new attachment's 236 UID. Otherwise a random UID will be generated automatically. 237 </para> 238 </listitem> 239 </varlistentry> 240 241 <varlistentry id="mkvpropedit.description.replace_attachment"> 242 <term><option>--replace-attachment</option> <parameter>selector</parameter><literal>:</literal><parameter>filename</parameter></term> 243 <listitem> 244 <para> 245 Replaces one or more attachments that match <parameter>selector</parameter> with the file <parameter>filename</parameter>. If more 246 than one existing attachment matches <parameter>selector</parameter> then all of their contents will be replaced by the content of 247 <parameter>filename</parameter>. 248 </para> 249 250 <para> 251 The <parameter>selector</parameter> can have one of four forms. They're explained below in the section <link 252 linkend="mkvpropedit.attachment_selectors">attachment selectors</link>. 253 </para> 254 255 <para> 256 If the option <option>--attachment-name</option> has been used prior to this option then its value is set as the new name for each 257 modified attachment. Otherwise the names aren't changed. 258 </para> 259 260 <para> 261 If the option <option>--attachment-mime-type</option> has been used prior to this option then its value is set as the new MIME type 262 for each modified attachment. Otherwise the MIME types aren't changed. 263 </para> 264 265 <para> 266 If the option <option>--attachment-description</option> has been used prior to this option then its value is set as the new 267 description for each modified attachment. Otherwise the descriptions aren't changed. 268 </para> 269 270 <para> 271 If the option <option>--attachment-uid</option> has been used prior to this option then its value is set as the new UID for each 272 modified attachment. Otherwise the UIDs aren't changed. 273 </para> 274 </listitem> 275 </varlistentry> 276 277 <varlistentry id="mkvpropedit.description.update_attachment"> 278 <term><option>--update-attachment</option> <parameter>selector</parameter></term> 279 <listitem> 280 <para> 281 Sets the properties of one or more attachments that match <parameter>selector</parameter>. If more than one existing attachment 282 matches <parameter>selector</parameter> then all of their properties will be updated. 283 </para> 284 285 <para> 286 The <parameter>selector</parameter> can have one of four forms. They're explained below in the section <link 287 linkend="mkvpropedit.attachment_selectors">attachment selectors</link>. 288 </para> 289 290 <para> 291 If the option <option>--attachment-name</option> has been used prior to this option then its value is set as the new name for each 292 modified attachment. Otherwise the names aren't changed. 293 </para> 294 295 <para> 296 If the option <option>--attachment-mime-type</option> has been used prior to this option then its value is set as the new MIME type 297 for each modified attachment. Otherwise the MIME types aren't changed. 298 </para> 299 300 <para> 301 If the option <option>--attachment-description</option> has been used prior to this option then its value is set as the new 302 description for each modified attachment. Otherwise the descriptions aren't changed. 303 </para> 304 305 <para> 306 If the option <option>--attachment-uid</option> has been used prior to this option then its value is set as the new UID for each 307 modified attachment. Otherwise the UIDs aren't changed. 308 </para> 309 </listitem> 310 </varlistentry> 311 312 <varlistentry id="mkvpropedit.description.delete_attachment"> 313 <term><option>--delete-attachment</option> <parameter>selector</parameter></term> 314 <listitem> 315 <para> 316 Deletes one or more attachments that match <parameter>selector</parameter>. 317 </para> 318 319 <para> 320 The <parameter>selector</parameter> can have one of four forms. They're explained below in the section <link 321 linkend="mkvpropedit.attachment_selectors">attachment selectors</link>. 322 </para> 323 </listitem> 324 </varlistentry> 325 </variablelist> 326 327 <para> 328 Options for attachment actions: 329 </para> 330 331 <variablelist> 332 <varlistentry id="mkvpropedit.description.attachment_name"> 333 <term><option>--attachment-name</option> <parameter>name</parameter></term> 334 <listitem> 335 <para> 336 Sets the name to use for the following <option>--add-attachment</option> or <option>--replace-attachment</option> operation. 337 </para> 338 </listitem> 339 </varlistentry> 340 341 <varlistentry id="mkvpropedit.description.attachment_mime_type"> 342 <term><option>--attachment-mime-type</option> <parameter>mime-type</parameter></term> 343 <listitem> 344 <para> 345 Sets the MIME type to use for the following <option>--add-attachment</option> or <option>--replace-attachment</option> operation. 346 </para> 347 </listitem> 348 </varlistentry> 349 350 <varlistentry id="mkvpropedit.description.attachment_description"> 351 <term><option>--attachment-description</option> <parameter>description</parameter></term> 352 <listitem> 353 <para> 354 Sets the description to use for the following <option>--add-attachment</option> or <option>--replace-attachment</option> operation. 355 </para> 356 </listitem> 357 </varlistentry> 358 </variablelist> 359 360 <para> 361 Other options: 362 </para> 363 364 <variablelist> 365 <varlistentry id="mkvpropedit.description.disable_language_ietf"> 366 <term><option>--disable-language-ietf</option></term> 367 <listitem> 368 <para> 369 Normally when the user requests changes to the '<literal>language</literal>' track header property, &mkvpropedit; will apply the same 370 change to the new <classname>LanguageIETF</classname> track header element in addition to the legacy <classname>Language</classname> 371 element. If this option is used, the change is only applied to the legacy <classname>Language</classname> element. 372 </para> 373 374 <para> 375 This option does not affect changes requested via the '<literal>language-ietf</literal>' track header property. 376 </para> 377 </listitem> 378 </varlistentry> 379 380 <varlistentry id="mkvpropedit.description.command_line_charset"> 381 <term><option>--command-line-charset</option> <parameter>character-set</parameter></term> 382 <listitem> 383 <para> 384 Sets the character set to convert strings given on the command line from. It defaults to the character set given by system's current 385 locale. 386 </para> 387 </listitem> 388 </varlistentry> 389 390 <varlistentry id="mkvpropedit.description.output_charset"> 391 <term><option>--output-charset</option> <parameter>character-set</parameter></term> 392 <listitem> 393 <para> 394 Sets the character set to which strings are converted that are to be output. It defaults to the character set given by system's 395 current locale. 396 </para> 397 </listitem> 398 </varlistentry> 399 400 <varlistentry id="mkvpropedit.description.redirect_output"> 401 <term><option>-r</option>, <option>--redirect-output</option> <parameter>file-name</parameter></term> 402 <listitem> 403 <para> 404 Writes all messages to the file <parameter>file-name</parameter> instead of to the console. While this can be done easily with 405 output redirection there are cases in which this option is needed: when the terminal reinterprets the output before writing it to a 406 file. The character set set with <link 407 linkend="mkvpropedit.description.output_charset"><option>--output-charset</option></link> is honored. 408 </para> 409 </listitem> 410 </varlistentry> 411 412 <varlistentry id="mkvpropedit.description.ui_language"> 413 <term><option>--ui-language</option> <parameter>code</parameter></term> 414 <listitem> 415 <para> 416 Forces the translations for the language <parameter>code</parameter> to be used (e.g. '<literal>de_DE</literal>' for the German 417 translations). Entering '<literal>list</literal>' as the <parameter>code</parameter> will cause the program to output a list of 418 available translations. 419 </para> 420 </listitem> 421 </varlistentry> 422 423 <varlistentry id="mkvpropedit.description.abort_on_warnings"> 424 <term><option>--abort-on-warnings</option></term> 425 <listitem> 426 <para> 427 Tells the program to abort after the first warning is emitted. The program's exit code will be 1. 428 </para> 429 </listitem> 430 </varlistentry> 431 432 <varlistentry id="mkvpropedit.description.debug"> 433 <term><option>--debug</option> <parameter>topic</parameter></term> 434 <listitem> 435 <para> 436 Turn on debugging for a specific feature. This option is only useful for developers. 437 </para> 438 </listitem> 439 </varlistentry> 440 441 <varlistentry id="mkvpropedit.description.engage"> 442 <term><option>--engage</option> <parameter>feature</parameter></term> 443 <listitem> 444 <para> 445 Turn on experimental features. A list of available features can be requested with <command>mkvpropedit --engage list</command>. These 446 features are not meant to be used in normal situations. 447 </para> 448 </listitem> 449 </varlistentry> 450 451 <varlistentry id="mkvpropedit.description.gui_mode"> 452 <term><option>--gui-mode</option></term> 453 <listitem> 454 <para> 455 Turns on GUI mode. In this mode specially-formatted lines may be output that can tell a controlling GUI what's happening. These 456 messages follow the format '<literal>#GUI#message</literal>'. The message may be followed by key/value pairs as in 457 '<literal>#GUI#message#key1=value1#key2=value2…</literal>'. Neither the messages nor the keys are ever translated and always output 458 in English. 459 </para> 460 </listitem> 461 </varlistentry> 462 463 <varlistentry id="mkvpropedit.description.verbose"> 464 <term><option>-v</option>, <option>--verbose</option></term> 465 <listitem> 466 <para> 467 Be verbose and show all the important &matroska; elements as they're read. 468 </para> 469 </listitem> 470 </varlistentry> 471 472 <varlistentry id="mkvpropedit.description.help"> 473 <term><option>-h</option>, <option>--help</option></term> 474 <listitem> 475 <para> 476 Show usage information and exit. 477 </para> 478 </listitem> 479 </varlistentry> 480 481 <varlistentry id="mkvpropedit.description.version"> 482 <term><option>-V</option>, <option>--version</option></term> 483 <listitem> 484 <para> 485 Show version information and exit. 486 </para> 487 </listitem> 488 </varlistentry> 489 490 <varlistentry id="mkvpropedit.description.at_sign"> 491 <term><option>@</option><parameter>options-file.json</parameter></term> 492 <listitem> 493 <para> 494 Reads additional command line arguments from the file <parameter>options-file</parameter>. For a full explanation on the supported 495 formats for such files see the section called "Option files" in the &mkvmerge; man page. 496 </para> 497 </listitem> 498 </varlistentry> 499 </variablelist> 500 </refsect1> 501 502 <refsect1 id="mkvpropedit.edit_selectors"> 503 <title>Edit selectors</title> 504 <para> 505 The <link linkend="mkvpropedit.description.edit"><option>--edit</option></link> option sets the &matroska; file section (segment 506 information or a certain track's headers) that all following <link linkend="mkvpropedit.description.add">add</link>, <link 507 linkend="mkvpropedit.description.set">set</link> and <link linkend="mkvpropedit.description.delete">delete</link> actions operate 508 on. This stays valid until the next <link linkend="mkvpropedit.description.edit"><option>--edit</option></link> option is found. The 509 argument to this option is called the edit selector. 510 </para> 511 512 <para> 513 By default &mkvpropedit; will edit the segment information section. 514 </para> 515 516 <refsect2 id="mkvpropedit.edit_selectors.segment_info"> 517 <title>Segment information</title> 518 <para> 519 The segment information can be selected with one of these three words: '<literal>info</literal>', '<literal>segment_info</literal>' or 520 '<literal>segmentinfo</literal>'. It contains properties like the segment title or the segment <abbrev>UID</abbrev>. 521 </para> 522 </refsect2> 523 524 <refsect2 id="mkvpropedit.edit_selectors.track_headers"> 525 <title>Track headers</title> 526 <para> 527 Track headers can be selected with a slightly more complex selector. All variations start with '<literal>track:</literal>'. The track 528 header properties include elements like the language code, 'default track' flag or the track's name. 529 </para> 530 531 <variablelist> 532 <varlistentry id="mkvpropedit.description.track_nth"> 533 <term><option>track:</option><parameter>n</parameter></term> 534 <listitem> 535 <para> 536 If the parameter <parameter>n</parameter> is a number then the <parameter>n</parameter>th track will be selected. The track order is 537 the same that &mkvmerge;'s <option>--identify</option> option outputs. 538 </para> 539 540 <para> 541 Numbering starts at 1. 542 </para> 543 </listitem> 544 </varlistentry> 545 546 <varlistentry id="mkvpropedit.description.track_type_nth"> 547 <term><option>track:</option><parameter>t</parameter><parameter>n</parameter></term> 548 <listitem> 549 <para> 550 If the parameter starts with a single character <parameter>t</parameter> followed by a <parameter>n</parameter> then the 551 <parameter>n</parameter>th track of a specific track type will be selected. The track type parameter <parameter>t</parameter> must be 552 one of these four characters: '<literal>a</literal>' for an audio track, '<literal>b</literal>' for a button track, 553 '<literal>s</literal>' for a subtitle track and '<literal>v</literal>' for a video track. The track order is the same that 554 &mkvmerge;'s <option>--identify</option> option outputs. 555 </para> 556 557 <para> 558 Numbering starts at 1. 559 </para> 560 </listitem> 561 </varlistentry> 562 563 <varlistentry id="mkvpropedit.description.track_uid"> 564 <term><option>track:</option>=<parameter>uid</parameter></term> 565 <listitem> 566 <para> 567 If the parameter starts with a '<literal>=</literal>' followed by a number <parameter>uid</parameter>, the track whose track 568 <abbrev>UID</abbrev> element equals the given <parameter>uid</parameter> will be selected. Track <abbrev>UIDs</abbrev> can be 569 obtained with &mkvinfo;. 570 </para> 571 </listitem> 572 </varlistentry> 573 574 <varlistentry id="mkvpropedit.description.track_number"> 575 <term><option>track:</option>@<parameter>number</parameter></term> 576 <listitem> 577 <para> 578 If the parameter starts with a '<literal>@</literal>' followed by a number <parameter>number</parameter>, the track whose track 579 number element equals this <parameter>number</parameter> will be selected. Track numbers can be obtained with &mkvinfo;. 580 </para> 581 </listitem> 582 </varlistentry> 583 </variablelist> 584 </refsect2> 585 586 <refsect2 id="mkvpropedit.edit_selectors.notes"> 587 <title>Notes</title> 588 <para> 589 Due to the nature of the track edit selectors it is possible that several selectors actually match the same track headers. In such cases 590 all actions for those edit selectors will be combined and executed in the order in which they're given on the command line. 591 </para> 592 </refsect2> 593 </refsect1> 594 595 <refsect1 id="mkvpropedit.attachment_selectors"> 596 <title>Attachment selectors</title> 597 598 <para> 599 An attachment selector is used with the two actions <link 600 linkend="mkvpropedit.description.replace_attachment"><option>--replace-attachment</option></link> and <link 601 linkend="mkvpropedit.description.delete_attachment"><option>--delete-attachment</option></link>. It can have one of the following four 602 forms: 603 </para> 604 605 <orderedlist> 606 <listitem> 607 <para> 608 Selection by attachment ID. In this form the selector is simply a number, the attachment's ID as output by &mkvmerge;'s 609 identification command. 610 </para> 611 </listitem> 612 613 <listitem> 614 <para> 615 Selection by attachment UID (unique ID). In this form the selector is the equal sign <literal>=</literal> followed by a number, the 616 attachment's unique ID as output by &mkvmerge;'s verbose identification command. 617 </para> 618 </listitem> 619 620 <listitem> 621 <para> 622 Selection by attachment name. In this form the selector is the literal word <literal>name:</literal> followed by the existing 623 attachment's name. If this selector is used with <option>--replace-attachment</option> then colons within the name to match must be 624 escaped as <literal>\c</literal>. 625 </para> 626 </listitem> 627 628 <listitem> 629 <para> 630 Selection by MIME type. In this form the selector is the literal word <literal>mime-type:</literal> followed by the existing 631 attachment's MIME type. If this selector is used with <option>--replace-attachment</option> then colons within the MIME type to match 632 must be escaped as <literal>\c</literal>. 633 </para> 634 </listitem> 635 </orderedlist> 636 </refsect1> 637 638 <refsect1 id="mkvpropedit.examples"> 639 <title>Examples</title> 640 <para> 641 The following example edits a file called '<literal>movie.mkv</literal>'. It sets the segment title and modifies the language code of an 642 audio and a subtitle track. Note that this example can be shortened by leaving out the first <link 643 linkend="mkvpropedit.description.edit"><option>--edit</option></link> option because editing the segment information element is the 644 default for all options found before the first <link linkend="mkvpropedit.description.edit"><option>--edit</option></link> option anyway. 645 </para> 646 647 <screen>$ mkvpropedit movie.mkv --edit info --set "title=The movie" --edit track:a1 --set language=fre --edit track:a2 --set language=ita</screen> 648 649 <para> 650 The second example removes the 'default track flag' from the first subtitle track and sets it for the second one. Note that 651 &mkvpropedit;, unlike &mkvmerge;, does not set the 'default track flag' of other tracks to '0' if it is set to '1' for a different track 652 automatically. 653 </para> 654 655 <screen>$ mkvpropedit movie.mkv --edit track:s1 --set flag-default=0 --edit track:s2 --set flag-default=1</screen> 656 657 <para> 658 Replacing the tags for the second subtitle track in a file looks like this: 659 </para> 660 661 <screen>$ mkvpropedit movie.mkv --tags track:s2:new-subtitle-tags.xml</screen> 662 663 <para> 664 Removing all tags requires leaving out the file name: 665 </para> 666 667 <screen>$ mkvpropedit movie.mkv --tags all:</screen> 668 669 <para> 670 Replacing the chapters in a file looks like this: 671 </para> 672 673 <screen>$ mkvpropedit movie.mkv --chapters new-chapters.xml</screen> 674 675 <para> 676 Removing all chapters requires leaving out the file name: 677 </para> 678 679 <screen>$ mkvpropedit movie.mkv --chapters ''</screen> 680 681 <para> 682 Adding a font file (<literal>Arial.ttf</literal>) as an attachment: 683 </para> 684 685 <screen>$ mkvpropedit movie.mkv --add-attachment Arial.ttf</screen> 686 687 <para> 688 Adding a font file (<literal>89719823.ttf</literal>) as an attachment and providing some information as it really is just Arial: 689 </para> 690 691 <screen>$ mkvpropedit movie.mkv --attachment-name Arial.ttf --attachment-description 'The Arial font as a TrueType font' --attachment-mime-type application/x-truetype-font --add-attachment 89719823.ttf</screen> 692 693 <para> 694 Replacing one attached font (<literal>Comic.ttf</literal>) file with another one (<literal>Arial.ttf</literal>): 695 </para> 696 697 <screen>$ mkvpropedit movie.mkv --attachment-name Arial.ttf --attachment-description 'The Arial font as a TrueType font' --replace-attachment name:Comic.ttf:Arial.ttf</screen> 698 699 <para> 700 Deleting the second attached file, whatever it may be: 701 </para> 702 703 <screen>$ mkvpropedit movie.mkv --delete-attachment 2</screen> 704 705 <para> 706 Deleting all attached fonts by MIME type: 707 </para> 708 709 <screen>$ mkvpropedit movie.mkv --delete-attachment mime-type:application/x-truetype-font</screen> 710 </refsect1> 711 712 <refsect1> 713 <title>Exit codes</title> 714 715 <para> 716 &mkvpropedit; exits with one of three exit codes: 717 </para> 718 719 <itemizedlist> 720 <listitem> 721 <para> 722 <constant>0</constant> -- This exit code means that the modification has completed successfully. 723 </para> 724 </listitem> 725 726 <listitem> 727 <para> 728 <constant>1</constant> -- In this case &mkvpropedit; has output at least one warning, but the modification did continue. A warning is 729 prefixed with the text '<literal>Warning:</literal>'. Depending on the issues involved the resulting files might be ok or not. The 730 user is urged to check both the warning and the resulting files. 731 </para> 732 </listitem> 733 734 <listitem> 735 <para> 736 <constant>2</constant> -- This exit code is used after an error occurred. &mkvpropedit; aborts right after outputting the error message. 737 Error messages range from wrong command line arguments over read/write errors to broken files. 738 </para> 739 </listitem> 740 </itemizedlist> 741 </refsect1> 742 743 <refsect1 id="mkvinfo.text_files_and_charsets"> 744 <title>Text files and character set conversions</title> 745 746 <para> 747 For an in-depth discussion about how all tools in the MKVToolNix suite handle character set conversions, input/output encoding, command 748 line encoding and console encoding please see the identically-named section in the &mkvmerge; man page. 749 </para> 750 </refsect1> 751 752 <refsect1 id="mkvpropedit.environment_variables"> 753 <title>Environment variables</title> 754 755 <para> 756 &mkvpropedit; uses the default variables that determine the system's locale (e.g. <varname>LANG</varname> and the <varname>LC_*</varname> 757 family). Additional variables: 758 </para> 759 760 <variablelist> 761 <varlistentry id="mkvpropedit.environment_variables.debug"> 762 <term><varname>MKVPROPEDIT_DEBUG</varname>, <varname>MKVTOOLNIX_DEBUG</varname> and its short form <varname>MTX_DEBUG</varname></term> 763 <listitem> 764 <para>The content is treated as if it had been passed via the <link 765 linkend="mkvpropedit.description.debug"><option>--debug</option></link> option.</para> 766 </listitem> 767 </varlistentry> 768 769 <varlistentry id="mkvpropedit.environment_variables.engage"> 770 <term><varname>MKVPROPEDIT_ENGAGE</varname>, <varname>MKVTOOLNIX_ENGAGE</varname> and its short form <varname>MTX_ENGAGE</varname></term> 771 <listitem> 772 <para>The content is treated as if it had been passed via the <link 773 linkend="mkvpropedit.description.engage"><option>--engage</option></link> option.</para> 774 </listitem> 775 </varlistentry> 776 </variablelist> 777 </refsect1> 778 779 <refsect1 id="mkvpropedit.seealso"> 780 <title>See also</title> 781 <para> 782 &mkvmerge;, &mkvinfo;, &mkvextract;, &mtxgui; 783 </para> 784 </refsect1> 785 786 <refsect1 id="mkvpropedit.www"> 787 <title>WWW</title> 788 <para> 789 The latest version can always be found at <ulink url="https://mkvtoolnix.download/">the MKVToolNix homepage</ulink>. 790 </para> 791 </refsect1> 792 793</refentry> 794