diff --git a/doc/man/mkvpropedit.xml b/doc/man/mkvpropedit.xml new file mode 100644 index 000000000..cc793fbad --- /dev/null +++ b/doc/man/mkvpropedit.xml @@ -0,0 +1,390 @@ + + + + + + +mkvmerge1"> +mkvinfo1"> +mkvextract1"> +mkvpropedit1"> +mmg1"> + +Matroska"> +OggVorbis"> +XML"> + +]> + + + + &product; + &date; + + + Developer + Moritz + Bunkus + moritz@bunkus.org + + + + + &product; + 1 + &version; + &date; + MkvToolNix + User Commands + + + + &product; + Modify properties of existing &matroska; files without a complete remux + + + + Synopsis + + mkvpropedit + options + source-filename + actions + + + + + Description + + This program analyses an existing &matroska; file and modifies some of its properties. Then it writes those modifications to the existing + file. Among the properties that can be changed are the segment information elements (e.g. the title) and the track headers (e.g. the + language code, 'default track' flag or the name). + + + + Options: + + + + + , + + + Lists all known and editable property names, their type (string, integer, boolean etc) and a short description. The program exits + afterwards. Therefore the source-filename parameter does not have to be supplied. + + + + + + , mode + + + Sets the parse mode. The parameter 'mode' can either be 'fast' (which is also the default) + or 'full'. The 'fast' mode does not parse the whole file but uses the meta seek elements for + 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 + elements or which are damaged the user might have to se the 'full' parse mode. A full scan of a file can take a + couple of minutes while a fast scan only takes seconds. + + + + + + + Actions: + + + + + , selector + + + Sets the &matroska; file section (segment information or a certain track's headers) that all following add, set and delete actions operate on. This option can be used multiple times in order to make + modifications to more than one element. + + + + See the section about edit selectors for a full description of the syntax. + + + + + + , name=value + + + Adds a property name with the value value. The property will be added even if such a + property exists already. Note that most properties are unique and cannot occur more than once. + + + + + + , name=value + + + Sets all occurences of the property name to the value value. If no such property exists + then it will be added. + + + + + + , name + + + Deletes all occurences of the property name. Note that some properties are required and cannot be deleted. + + + + + + + Other options: + + + + + character-set + + + Sets the character set to convert strings given on the command line from. It defaults to the character set given by system's current + locale. + + + + + + character-set + + + Sets the character set to which strings are converted that are to be output. It defaults to the character set given by system's + current locale. + + + + + + , file-name + + + Writes all messages to the file file-name instead of to the console. While this can be done easily with + output redirection there are cases in which this option is needed: when the terminal reinterprets the output before writing it to a + file. The character set set with is honored. + + + + + + code + + + Forces the translations for the language code to be used (e.g. 'de_DE' for the German + translations). It is preferable to use the environment variables LANG, LC_MESSAGES and + LC_ALL though. Entering 'list' as the code will cause &mkvextract; to + output a list of available translations. + + + + + + , + + + Be verbose and show all the important &matroska; elements as they're read. + + + + + + , + + + Show usage information and exit. + + + + + + , + + + Show version information and exit. + + + + + + options-file + + + Reads additional command line arguments from the file options-file. Lines whose first non-whitespace + character is a hash mark ('#') are treated as comments and ignored. White spaces at the start and end of a line + will be stripped. Each line must contain exactly one option. There is no meta character escaping. + + + + The command line 'mkvpropedit source.mkv --edit track:a2 --set title=Comments' could be converted into the + following option file: + + + +# Modify source.mkv +source.mkv +# Edit the second audio track +--edit +track:a2 +# and set the title to 'Comments' +--set +title=Comments + + + + + + + + Edit selectors + + The option sets the &matroska; file section (segment + information or a certain track's headers) that all following add, set and delete actions operate + on. This stays valid until the next option is found. The + argument to this option is called the edit selector. + + + + Segment information + + The segment information can be selected with one of these three words: 'info', 'segment_info' or + 'segmentinfo'. It contains properties like the segment title or the segment UID. + + + + + Track headers + + Track headers can be selected with a slightly more complex selector. All variations start with 'track:'. The track + header properties include elements like the language code, 'default track' flag or the track's name. + + + + + n + + + If the parameter n is a number then the nth track will be selected. The track order is + the same that &mkvmerge;'s option outputs. + + + + + + tn + + + If the parameter starts with a single character t followed by a n then the + nth track of a specific track type will be selected. The track type parameter t must be + one of these fourc characters: 'a' for an audio track, 'b' for a button track, + 's' for a subtitle track and 'v' for a video track. The track order is the same that + &mkvmerge;'s option outputs. + + + + + + =uid + + + If the parameter starts with a '=' followed by a number uid then the track whose track + UID element equals this uid. Track UIDs can be obtained with &mkvinfo;. + + + + + + @number + + + If the parameter starts with a '@' followed by a number number then the track whose track + number element equals this number. Track number can be obtained with &mkvinfo;. + + + + + + + + Notes + + Due to the nature of the track edit selectors it is possible that several selectors actually match the same track headers. In such cases + all actions for those edit selectors will be combined and executed in the order in which they're given on the command line. + + + + + + Examples + + The following example edits a file called 'movie.mkv'. It sets the segment title and modifies the language code of an + audio and a subtitle track. Note that this example can be shortened by leaving out the first option because editing the segment information element is the + default for all options found before the first option anyway. + + + +$ mkvpropedit movie.mkv --edit info --set "title=The movie" --edit track:a1 --set language=fre --edit track:a2 --set language=ita + + + + + Exit codes + + + &mkvpropedit; exits with one of three exit codes: + + + + + + 0 -- This exit codes means that the modification has completed successfully. + + + + + + 1 -- In this case &mkvpropedit; has output at least one warning, but the modification did continue. A warning is + prefixed with the text 'Warning:'. Depending on the issues involved the resulting files might be ok or not. The + user is urged to check both the warning and the resulting files. + + + + + + 2 -- This exit code is used after an error occured. &mkvpropedit; aborts right after outputting the error message. + Error messages range from wrong command line arguments over read/write errors to broken files. + + + + + + + See also + + &mkvmerge;, &mkvinfo;, &mkvextract;, &mmg; + + + + + WWW + + The latest version can always be found at the MKVToolNix homepage. + + + +