From e0d0c45f62bb58ee4567bf3deeb80e3a140430a4 Mon Sep 17 00:00:00 2001 From: Moritz Bunkus Date: Sat, 8 Aug 2009 02:01:36 +0200 Subject: [PATCH] The start of the conversion of mkvmerge's man page to DocBook XML. --- doc/docbook/mkvmerge.xml | 493 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 493 insertions(+) create mode 100644 doc/docbook/mkvmerge.xml diff --git a/doc/docbook/mkvmerge.xml b/doc/docbook/mkvmerge.xml new file mode 100644 index 000000000..955ac538f --- /dev/null +++ b/doc/docbook/mkvmerge.xml @@ -0,0 +1,493 @@ + + + + +]> + + + + &product; + + + Developer + Moritz + Bunkus + moritz@bunkus.org + + + + + &product; + 1 + &version; + http://www.bunkus.org/videotools/mkvtoolnix + http://www.bunkus.org/videotools/mkvtoolnix/doc + + + + &product; + Merge multimedia streams into a Matroska file + + + + Synopsis + + mkvmerge + global options + -o out + options1 + file1 + + options2 + file2 + + @optionsfile + + + + + Description + + This program takes the input from several media files and joins their streams (all of them or just a selection) into + a Matroska file; see the Matroska website. + + + + Global options: + + + + + , + + Increase verbosity. + + + + + , + + Suppress status output. + + + + + , out + + Write to the file out. If splitting is used then this parameter is treated a bit + differently. See the explanation for the option for details. + + + + + title + + Sets the general title for the output file, e.g. the movie name. + + + + + file + + Read global tags from the XML file file. See the section about tags + below for details. + + + + + code + + Sets the default language code that will be used for all tracks unless overwritten with the + option. The default language code is 'und' for 'undefined'. + + + + + + Chapter handling: (global options) + + + + + language + + + Sets the ISO639-2 language code that is written for each chapter entry. + Defaults to 'eng'. + See the section about chapters below for details. + + + + This option can be used both for simple chapter files and for source files + that contain chapters but no information about the chapters' language, + e.g. MP4 and OGM files. + + + + + + charset + + + Sets the charset that is used for the conversion to UTF-8 for simple chapter files. Defaults to the current system + locale. + + + + This switch does also apply to chapters that are copied from certain container types, e.g. Ogg/OGM and MP4 files. + See the section about chapters below for details. + + + + + + format + + + mkvmerge supports reading CUE sheets for audio files as the input for + chapters. CUE sheets usually contain the entries PERFORMER and + TITLE for each index entry. mkvmerge uses these two strings in order + to construct the chapter name. With this option the format used for this name can be set. + + + + If this option is not given then mkvmerge defaults to the format '%p - %t' + (the performer, followed by a space, a dash, another space and the title). + + + + If the format is given then everything except the following meta characters is copied as-is, and the meta + characters are replaced like this: + + + + + %p is replaced by the current entry's PERFORMER string, + + + %t is replaced by the current entry's TITLE string, + + + %n is replaced by the current track number and + + + %N is replaced by the current track number padded with a leading zero if + it is < 10. + + + + + + + file + + + Read chapter information from the file file. See the section about chapters below for + details. + + + + + + + General output control (advanced global options): + + + + + FID1:TID1,FID2:TID2,... + + + This option changes the order in which the tracks for an input file are created. The argument is a comma separated + list of pairs IDs. Each pair contains first the file ID which is simply the number of the file on the command line + starting at 0. The second is a track ID from that file. If some track IDs are omitted then those tracks are + created after the ones given with this option have been created. + + + + + + nms + + + Put at most n data blocks into each cluster. If the number is postfixed with 'ms' then put + at most n milliseconds of data into each cluster. The maximum length for a cluster that + mkvmerge accepts is 60000 blocks and 32000ms; the minimum length is 100ms. Programs + will only be able to seek to clusters, so creating larger clusters may lead to imprecise or slow seeking. + + + + + + + + + Tells mkvmerge not to create and write the cue data which can be compared to an index + in an AVI. Matroska files can be played back without the cue data, but seeking will probably be imprecise and + slower. Use this only if you're really desperate for space or for testing purposes. See also option + which can be specified for each input file. + + + + + + + + + Tells mkvmerge not to create a meta seek element at the end of the file containing all + clusters. See also the section about the Matroska file layout. + + + + + + + + + Disables lacing for all tracks. This will increase the file's size, especially if there are many audio + tracks. This option is not intended for everyday use. + + + + + + + + + Write durations for all blocks. This will increase file size and does not offer any additional value for players + at the moment. + + + + + + n + + + Forces the timecode scale factor to n. Valid values are in the range + 1000..10000000 or the special value -1. + + + + Normally mkvmerge will use a value of 1000000 which means that + timecodes and durations will have a precision of 1ms. For files that will not contain a video track but at least + one audio track mkvmerge will automatically chose a timecode scale factor so that all + timecodes and durations have a precision of one audio sample. This causes bigger overhead but allows precise seeking + and extraction. + + + + If the special value -1 is used then mkvmerge will use sample + precision even if a video track is present. + + + + + + + File splitting and linking (more global options): + + + + + specification + + + + Splits the output file after a given size or a given time. Please note that tracks can only be split right before a key frame. Due + to buffering mkvmerge will split right before the next key frame after the split point has been reached. + Therefore the split point may be a bit off from what the user has specified. + + + + At the moment mkvmerge supports three different modes. + + + + + + Splitting by size. + + + + Syntax: size:dk|m|g + + + + Examples: --split size:700m or --split 150000000 + + + + The parameter d may end with 'k', 'm' or 'g' to + indicate that the size is in KB, MB or GB respectively. Otherwise a size in Bytes is assumed. After the current output file has + reached this size limit a new one will be started. + + + + The 'size:' prefix may be omitted for compatibility reasons. + + + + + + Splitting after a duration. + + + + Syntax: duration:HH:MM:SS.nnnnnnnnn|ns + + + + Examples: --split duration:00:60:00.000 or --split 3600s + + + + The paramter must either have the form HH:MM:SS.nnnnnnnnn for specifying the duration in up to nano-second + precision or be a number n followed by the letter 's' for the duration in + seconds. HH is the number of hours, MM the number of minutes, + SS the number of seconds and nnnnnnnnn the number of nanoseconds. Both the number of + hours and the number of nanoseconds can be omitted. There can be up to nine digits after the decimal point. After the duration of + the contents in the current output has reached this limit a new output file will be started. + + + + The 'duration:' prefix may be omitted for compatibility reasons. + + + + + + Splitting after specific timecodes. + + + + Syntax: timecodes:A,B,C... + + + + Example: --split timecodes:00:45:00.000,01:20:00.250,6300s + + + + The parameters A, B etc must all have the same format as the ones used for the + duration (see above). The list of timecodes is separated by commas. After the input stream has reached the current split point's + timecode a new file is created. Then the next split point given in this list is used. + + + + The 'timecodes:' prefix must not be omitted. + + + + For this splitting mode the output filename is treated differently than for the normal operation. It may contain a + printf like expression '%d' including an optional field width, + e.g. '%02d'. If it does then the current file number will be formatted appropriately and inserted at that point + in the filename. If there is no such pattern then a pattern of '-%03d' is assumed right before the file's + extension: '-o output.mkv' would result in 'output-001.mkv' and so on. If there's no extension + then '-%03d' will be appended to the name. + + + + + + + + + + + Link files to one another when splitting the output file. See the section on file linking + below for details. + + + + + + SID + + + Links the first output file to the segment with the segment UID given by the SID parameter. See the section on + file linking below for details. + + + + + + SID + + + Links the last output file to the segment with the segment UID given by the SID parameter. See the section on + file linking below for details. + + + + + + + + + + + + + + + File linking + + Matroska supports file linking which simply says that a specific file is the predecessor or successor of the current file. To be precise, + it's not really the files that are linked but the Matroska segments. As most files will probably only contain one Matroska segment the + following explanations use the term 'file linking' although 'segment linking' would be more appropriate. + + + + Each segment is identified by a unique 128 bit wide segment UID. This UID is automatically generated by + mkvmerge. The linking is done primarily via putting the segment UIDs (short: SID) of the + previous/next file into the segment header information. + + mkvinfo + 1 + + prints these SIDs if it finds them. + + + + If a file is split into several smaller ones and linking is used then the timecodes will not start at 0 again but will continue where the + last file has left off. This way the absolute time is kept even if the previous files are not available (e.g. when streaming). If no + linking is used then the timecodes should start at 0 for each file. By default mkvmerge does not use file + linking. If you want that you can turn it on with the option. This option is only useful if splitting is + activated as well. + + + + Regardless of whether splitting is active or not the user can tell mkvmerge to link the produced files to + specific SIDs. This is achieved with the options and + . These options accept a segment SID in the format that + + mkvinfo + 1 + + outputs: 16 hexadecimal numbers between 0x00 and 0xff prefixed with '0x' + each, e.g. '0x41 0xda 0x73 0x66 0xd9 0xcf 0xb2 0x1e 0xae 0x78 0xeb 0xb4 0x5e 0xca 0xb3 0x93'. Alternatively a shorter + form can be used: 16 hexadecimal numbers between 0x00 and 0xff without the + '0x' prefixes and without the spaces, e.g. '41da7366d9cfb21eae78ebb45ecab393'. + + + + If splitting is used then the first file is linked to the SID given with and the + last file is linked to the SID given with . If splitting is not used then the one output + file will be linked to both of the two SIDs. + + + + + See also + + mkvinfo1, + mkvextract1, + mmg1 + + + +