From 964216ccb12f5bac294089f5f2c1a8b1752594cd Mon Sep 17 00:00:00 2001 From: Moritz Bunkus Date: Mon, 10 Aug 2009 21:22:09 +0200 Subject: [PATCH] Removed the hand-written man pages from 'doc'. Added the converted man pages from 'doc/man'. --- .gitignore | 3 - doc/base64tool.1 | 33 - doc/man/mkvextract.1 | 514 ++++++++++++ doc/man/mkvinfo.1 | 198 +++++ doc/man/mkvmerge.1 | 1882 ++++++++++++++++++++++++++++++++++++++++++ doc/man/mmg.1 | 76 ++ doc/mkvextract.1 | 299 ------- doc/mkvinfo.1 | 91 -- doc/mkvmerge.1 | 1343 ------------------------------ doc/mmg.1 | 50 -- 10 files changed, 2670 insertions(+), 1819 deletions(-) delete mode 100644 doc/base64tool.1 create mode 100644 doc/man/mkvextract.1 create mode 100644 doc/man/mkvinfo.1 create mode 100644 doc/man/mkvmerge.1 create mode 100644 doc/man/mmg.1 delete mode 100644 doc/mkvextract.1 delete mode 100644 doc/mkvinfo.1 delete mode 100644 doc/mkvmerge.1 delete mode 100644 doc/mmg.1 diff --git a/.gitignore b/.gitignore index 9c24f53d9..453a541b3 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,3 @@ config.status config.sub configure data -/doc/man/mkvmerge.1 -/doc/man/mkvextract.1 -/doc/man/mkvinfo.1 diff --git a/doc/base64tool.1 b/doc/base64tool.1 deleted file mode 100644 index b3c23d1b0..000000000 --- a/doc/base64tool.1 +++ /dev/null @@ -1,33 +0,0 @@ -.TH BASE64TOOL "1" "July 2009" "base64tool v2.9.7" "User Commands" - - -.SH NAME -base64tool \- encode files into Base64 encoding and decode Base64 encoded files - - -.SH SYNOPSIS -.B base64tool -<\fIencode\fR|\fIdecode\fR> <\fIinput\fR> <\fIoutput\fR> [\fImaxlen\fR] - - -.SH DESCRIPTION -.LP -This program can either encode a file with Base64 encoding suited for -inclusion of binary data into text files such as XML files and decode -Base64 encoded data back into its original form. The first argument -controls whether \fBbase64tool\fR will encode or decode. The second -argument is name of the file that data is read from. The third -argument is the name of the file that output is written to. The file -will be overwritten if it exists. -.LP -When encoding an optional fourth parameter, \fImaxlen\fR, specifies -the maximum line length to output. It defaults to 72 if left out. - - -.SH AUTHOR -.I base64tool -was written by Moritz Bunkus . -.SH WWW -The newest version can always be found at -.UR http://www.bunkus.org/\:videotools/\:mkvtoolnix/ -.UE diff --git a/doc/man/mkvextract.1 b/doc/man/mkvextract.1 new file mode 100644 index 000000000..2981dadaa --- /dev/null +++ b/doc/man/mkvextract.1 @@ -0,0 +1,514 @@ +.\" Title: mkvextract +.\" Author: Moritz Bunkus +.\" Generator: DocBook XSL Stylesheets v1.73.2 +.\" Date: July 2009 +.\" Manual: User Commands +.\" Source: MkvToolNix 2.9.7 +.\" +.TH "MKVEXTRACT" "1" "July 2009" "MkvToolNix 2\&.9\&.7" "User Commands" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +mkvextract \- extract tracks from Matroska files into other files +.SH "SYNOPSIS" +.HP 11 +\fBmkvextract\fR {mode} {source\-filename} [options] [extraction\-spec] +.SH "DESCRIPTION" +.PP +This program extracts specific parts from a Matroska file to other useful formats\&. The first argument, +\fBmode\fR, tells +\fBmkvextract\fR(1) +what to extract\&. Currently supported is the extraction of +tracks, +tags, +attachments, +chapters, +CUE sheets +and +timecodes\&. The second argument is the name of the source file\&. It must be a +Matroska(TM) +file\&. All following arguments are options and extraction specifications; both of which depend on the selected mode\&. +.SS "Common options" +.PP +The following options are available in all modes and only described once in this section\&. +.PP +\fB\-\-command\-line\-charset\fR \fIcharacter\-set\fR +.RS 4 +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\&. +.RE +.PP +\fB\-\-output\-charset\fR \fIcharacter\-set\fR +.RS 4 +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\&. +.RE +.PP +\fB\-r\fR, \fB\-\-redirect\-output\fR \fIfile\-name\fR +.RS 4 +Writes all messages to the file +\fIfile\-name\fR +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 +\fB\-\-output\-charset\fR +is honored\&. +.RE +.PP +\fB\-\-ui\-language\fR \fIcode\fR +.RS 4 +Forces the translations for the language +\fIcode\fR +to be used (e\&.g\&. \'de_DE\' for the German translations)\&. It is preferable to use the environment variables +\fILANG\fR, +\fILC_MESSAGES\fR +and +\fILC_ALL\fR +though\&. Entering \'list\' as the +\fIcode\fR +will cause +\fBmkvextract\fR(1) +to output a list of available translations\&. +.RE +.PP +\fB\-v\fR, \fB\-\-verbose\fR +.RS 4 +Be verbose and show all the important +Matroska(TM) +elements as they\'re read\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show usage information and exit\&. +.RE +.PP +\fB\-V\fR, \fB\-\-version\fR +.RS 4 +Show version information and exit\&. +.RE +.PP +\fB@\fRoptions\-file +.RS 4 +Reads additional command line arguments from the file +\fIoptions\-file\fR\&. 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\&. +.sp +The command line \'\fBmkvextract tracks source\&.mkv \-\-raw 1:destination\&.raw\fR\' could be converted into the following option file: +.sp +.RS 4 +.nf +# Extract a track from source\&.mkv +tracks +source\&.mkv +# Output the track as raw data\&. +\-\-raw +1;destination\&.raw + +.fi +.RE +.RE +.SS "Track extraction mode" +.PP +Syntax: +\fBmkvextract\fR +\fBtracks\fR +\fIsource\-filename\fR +[\fIoptions\fR] +\fITID1:dest\-filename1\fR +[\fITID2:dest\-filename2\fR \&.\&.\&.] +.PP +The following command line options are available for each track in the \'tracks\' extraction mode\&. They have to appear in front of the track specification (see below) they should be applied to\&. +.PP +\fB\-c\fR \fIcharacter\-set\fR +.RS 4 +Sets the character set to convert the next text subtitle track to\&. Only valid if the next track ID targets a text subtitle track\&. It defaults to UTF\-8\&. +.RE +.PP +\fB\-\-blockadd\fR \fIlevel\fR +.RS 4 +Keep only the BlockAdditions up to this level\&. The default is to keep all levels\&. This option only affects certain kinds of codecs like WAVPACK4\&. +.RE +.PP +\fB\-\-cuesheet\fR +.RS 4 +Causes +\fBmkvextract\fR(1) +to extract a +CUE +sheet from the chapter information and tag data for the following track into a file whose name is the track\'s output name with \'\&.cue\' appended to it\&. +.RE +.PP +\fB\-\-raw\fR +.RS 4 +Extracts the raw data into a file without any container data around it\&. Unlike the +\fB\-\-fullraw\fR +flag this flag does not cause the contents of the +CodecPrivate +element to be written to the file\&. This mode works with all +CodecIDs, even the ones that +\fBmkvextract\fR(1) +doesn\'t support otherwise, but the resulting files might not be usable\&. +.RE +.PP +\fB\-\-fullraw\fR +.RS 4 +Extracts the raw data into a file without any container data around it\&. The contents of the +CodecPrivate +element will be written to the file first if the track contains such a header element\&. This mode works with all +CodecIDs, even the ones that +\fBmkvextract\fR(1) +doesn\'t support otherwise, but the resulting files might not be usable\&. +.RE +.PP +\fB\-\-no\-ogg\fR +.RS 4 +Only valid for +FLAC +tracks\&. Normally +FLAC +tracks are embedded in an Ogg transport stream\&. With this switch they are extracted to raw +FLAC +files instead\&. +.RE +.PP +\fITID:outname\fR +.RS 4 +Causes extraction of the track with the ID +\fITID\fR +into the file +\fIoutname\fR +if such a track exists in the source file\&. This option can be given multiple times\&. The track IDs are the same as the ones output by +\fBmkvmerge\fR(1)\'s +\fB\-\-identify\fR +option\&. +.sp +Each output name should be used only once\&. The exception are RealAudio and RealVideo tracks\&. If you use the same name for different tracks then those tracks will be saved in the same file\&. Example: +.sp +.RS 4 +.nf +$ mkvextract tracks input\&.mkv 1:output\-two\-tracks\&.rm 2:output\-two\-tracks\&.rm + +.fi +.RE +.RE +.SS "Tags extraction mode" +.PP +Syntax: +\fBmkvextract\fR +\fBtags\fR +\fIsource\-filename\fR +[\fIoptions\fR] +.PP +The extracted tags are written to the console unless the output is redirected (see the section about +output redirection +for details)\&. +.SS "Attachments extraction mode" +.PP +Syntax: +\fBmkvextract\fR +\fBattachments\fR +\fIsource\-filename\fR +[\fIoptions\fR] +\fIAID1:outname1\fR +[\fIAID2:outname2\fR \&.\&.\&.] +.PP +AID:outname +.RS 4 +Causes extraction of the attachment with the ID +\fIAID\fR +into the file +\fIoutname\fR +if such an attachment exists in the source file\&. If the +\fIoutname\fR +is left empty then the name of the attachment inside the source +Matroska(TM) +file is used instead\&. This option can be given multiple times\&. The attachment IDs are the same as the ones output by +\fBmkvmerge\fR(1)\'s +\fB\-\-identify\fR +option\&. +.RE +.SS "Chapters extraction mode" +.PP +Syntax: +\fBmkvextract\fR +\fBchapters\fR +\fIsource\-filename\fR +[\fIoptions\fR] +.PP +\fB\-s\fR, \fB\-\-simple\fR +.RS 4 +Exports the chapter information in the simple format used in the +OGM +tools (CHAPTER01=\&.\&.\&., CHAPTER01NAME=\&.\&.\&.)\&. In this mode some information has to be discarded\&. Default is to output the chapters in +XML +format\&. +.RE +.PP +The extracted chapters are written to the console unless the output is redirected (see the section about +output redirection +for details)\&. +.SS "Cue sheet extraction mode" +.PP +Syntax: +\fBmkvextract\fR +\fBcuesheet\fR +\fIsource\-filename\fR +[\fIoptions\fR] +.PP +The extracted cue sheet is written to the console unless the output is redirected (see the section about +output redirection +for details)\&. +.SS "Timecode extraction mode" +.PP +Syntax: +\fBmkvextract\fR +\fBtimecodes_v2\fR +\fIsource\-filename\fR +[\fIoptions\fR] +.PP +The extracted timecodes are written to the console unless the output is redirected (see the section about +output redirection +for details)\&. +.SH "OUTPUT REDIRECTION" +.PP +Several extraction modes cause +\fBmkvextract\fR(1) +to write the extracted data to the console\&. There are generally two ways of writing this data into a file: one provided by the shell and one provided by +\fBmkvextract\fR(1) +itself\&. +.PP +The shell\'s builtin redirection mechanism is used by appending \'> output\-filename\&.ext\' to the command line\&. Example: +.sp +.RS 4 +.nf +$ mkvextract tags source\&.mkv > tags\&.xml + +.fi +.RE +.PP + +\fBmkvextract\fR(1)\'s own redirection is invoked with the +\fB\-\-redirect\-output\fR +option\&. Example: +.sp +.RS 4 +.nf +$ mkvextract tags source\&.mkv \-\-redirect\-output tags\&.xml + +.fi +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +Note +.PP +On Windows you should probably use the +\fB\-\-redirect\-output\fR +option because +\fBcmd\&.exe\fR +sometimes interpretes special characters before they\'re written into the output file resulting in broken output\&. +.SH "OUTPUT FILE FORMATS" +.PP +The decision about the output format is based on the track type, not on the extension used for the output file name\&. The following track types are supported at the moment: +.PP +V_MPEG4/ISO/AVC +.RS 4 + +H\&.264 +/ +AVC +video tracks are written to +H\&.264 +elementary streams which can be processed further with e\&.g\&. +MP4Box(TM) +from the +GPAC(TM) +package\&. +.RE +.PP +V_MS/VFW/FOURCC +.RS 4 +Fixed +FPS +video tracks with this +CodecID +are written to +AVI +files\&. +.RE +.PP +V_REAL/* +.RS 4 + +RealVideo(TM) +tracks are written to +RealMedia(TM) +files\&. +.RE +.PP +A_MPEG/L3, A_AC3 +.RS 4 +These will be extracted to raw +MP3 +and +AC3 +files\&. +.RE +.PP +A_PCM/INT/LIT +.RS 4 +Raw +PCM +data will be written to a +WAV +file\&. +.RE +.PP +A_AAC/MPEG2/*, A_AAC/MPEG4/*, A_AAC +.RS 4 +All +AAC +files will be written into an +AAC +file with +ADTS +headers before each packet\&. The +ADTS +headers will not contain the deprecated emphasis field\&. +.RE +.PP +A_VORBIS +.RS 4 +Vorbis audio will be written into an +OggVorbis(TM) +file\&. +.RE +.PP +A_REAL/* +.RS 4 + +RealAudio(TM) +tracks are written to +RealMedia(TM) +files\&. +.RE +.PP +A_TTA1 +.RS 4 + +TrueAudio(TM) +tracks are written to +TTA +files\&. Please note that due to +Matroska(TM)\'s limited timecode precision the extracted file\'s header will be different regarding two fields: +\fIdata_length\fR +(the total number of samples in the file) and the +CRC\&. +.RE +.PP +S_TEXT/UTF8 +.RS 4 +Simple text subtitles will be written as +SRT +files\&. +.RE +.PP +S_TEXT/SSA, S_TEXT/ASS +.RS 4 + +SSA +and +ASS +text subtitles will be written as +SSA/ASS +files respectively\&. +.RE +.PP +S_KATE +.RS 4 + +Kate(TM) +streams will be written within an +Ogg(TM) +container\&. +.RE +.PP +Tags +.RS 4 +Tags are converted to a +XML +format\&. This format is the same that +\fBmkvmerge\fR(1) +supports for reading tags\&. +.RE +.PP +Attachments +.RS 4 +Attachments are written to they output file as they are\&. No conversion whatsoever is done\&. +.RE +.PP +Chapters +.RS 4 +Chapters are converted to a +XML +format\&. This format is the same that +\fBmkvmerge\fR(1) +supports for reading chapters\&. Alternatively a stripped\-down version can be output in the simple +OGM +style format\&. +.RE +.PP +Timecodes +.RS 4 +Timecodes are first sorted and then output as a timecode v2 format compliant file ready to be fed to +\fBmkvmerge\fR(1)\&. The extraction to other formats (v1, v3 and v4) is not supported\&. +.RE +.SH "EXIT CODES" +.PP + +\fBmkvextract\fR(1) +exits with one of three exit codes: +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB0\fR +\-\- This exit codes means that extraction has completed successfully\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB1\fR +\-\- In this case +\fBmkvextract\fR(1) +has output at least one warning, but extraction 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\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB2\fR +\-\- This exit code is used after an error occured\&. +\fBmkvextract\fR(1) +aborts right after outputting the error message\&. Error messages range from wrong command line arguments over read/write errors to broken files\&. +.RE +.SH "SEE ALSO" +.PP + +\fBmkvmerge\fR(1), +\fBmkvinfo\fR(1), +\fBmmg\fR(1) +.SH "WWW" +.PP +The latest version can always be found at +\fIthe MKVToolNix homepage\fR\&[1]\&. +.SH "AUTHOR" +.PP +\fBMoritz Bunkus\fR <\&moritz@bunkus\&.org\&> +.sp -1n +.IP "" 4 +Developer +.SH "NOTES" +.IP " 1." 4 +the MKVToolNix homepage +.RS 4 +\%http://www.bunkus.org/videotools/mkvtoolnix/ +.RE diff --git a/doc/man/mkvinfo.1 b/doc/man/mkvinfo.1 new file mode 100644 index 000000000..5755811cb --- /dev/null +++ b/doc/man/mkvinfo.1 @@ -0,0 +1,198 @@ +.\" Title: mkvinfo +.\" Author: Moritz Bunkus +.\" Generator: DocBook XSL Stylesheets v1.73.2 +.\" Date: July 2009 +.\" Manual: User Commands +.\" Source: MkvToolNix 2.9.7 +.\" +.TH "MKVINFO" "1" "July 2009" "MkvToolNix 2\&.9\&.7" "User Commands" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +mkvinfo \- Print information about elements in Matroska files +.SH "SYNOPSIS" +.HP 8 +\fBmkvinfo\fR [options] {source\-filename} +.SH "DESCRIPTION" +.PP +This program lists all elements contained in a +Matroska(TM)\&. The output can be limited to a list of tracks in the file including information about the codecs used\&. +.PP +\fB\-g\fR, \fB\-\-gui\fR +.RS 4 +Start the +GUI\&. This option is only available if mkvinfo was compiled with +GUI +support\&. +.RE +.PP +\fB\-c\fR, \fB\-\-checksums\fR +.RS 4 +Calculates and display the +\fBAdler32\fR +checksum for each frame\&. Useful for debugging only\&. +.RE +.PP +\fB\-s\fR, \fB\-\-summary\fR +.RS 4 +Only show a terse summary of what +\fBmkvinfo\fR(1) +finds and not each element\&. +.RE +.PP +\fB\-\-command\-line\-charset\fR \fIcharacter\-set\fR +.RS 4 +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\&. +.RE +.PP +\fB\-\-output\-charset\fR \fIcharacter\-set\fR +.RS 4 +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\&. +.RE +.PP +\fB\-r\fR, \fB\-\-redirect\-output\fR \fIfile\-name\fR +.RS 4 +Writes all messages to the file +\fIfile\-name\fR +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 +\fB\-\-output\-charset\fR +is honored\&. +.RE +.PP +\fB\-\-ui\-language\fR \fIcode\fR +.RS 4 +Forces the translations for the language +\fIcode\fR +to be used (e\&.g\&. \'de_DE\' for the German translations)\&. It is preferable to use the environment variables +\fILANG\fR, +\fILC_MESSAGES\fR +and +\fILC_ALL\fR +though\&. Entering \'list\' as the +\fIcode\fR +will cause +\fBmkvinfo\fR(1) +to output a list of available translations\&. +.RE +.PP +\fB\-v\fR, \fB\-\-verbose\fR +.RS 4 +Be more verbose\&. See the section about +verbosity levels +for a description which information will be output at which level\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show usage information and exit\&. +.RE +.PP +\fB\-V\fR, \fB\-\-version\fR +.RS 4 +Show version information and exit\&. +.RE +.PP +\fB@\fRoptions\-file +.RS 4 +Reads additional command line arguments from the file +\fIoptions\-file\fR\&. 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\&. +.sp +The command line \'\fBmkvinfo \-v \-v input\&.mkv \-\-redirect\-output info\&.txt\fR\' could be converted into the following option file: +.sp +.RS 4 +.nf +# Be more verbose +\-v +\-v +# Parse input\&.mkv +input\&.mkv +# and write the output to info\&.txt +\-\-redirect\-output +info\&.txt + +.fi +.RE +.RE +.SH "VERBOSITY LEVELS" +.PP +The +\fB\-v\fR +option can be used to increase +\fBmkvinfo\fR(1)\'s verbosity level and print more information about the current file\&. +.PP +At level 0 +\fBmkvinfo\fR(1) +will print only the track headers it finds and their types\&. +\fBmkvinfo\fR(1) +will exit as soon as the headers are parsed completely (more technical: as soon as the first cluster is encountered)\&. In this level the seek head entries and the cues will not be displayed \-\- even if they\'re located in front of the track information\&. +.PP +At level 1 +\fBmkvinfo\fR(1) +will also print all +Matroska(TM) +elements encountered for the complete file but the seek head entries and the cue entries\&. If the summary mode is enabled then +\fBmkvinfo\fR(1) +will output the frame position as well\&. +.PP +At level 2 +\fBmkvinfo\fR(1) +will also print the seek head entries, the cue entries and the file position at which each +Matroska(TM) +element can be found at\&. +.PP +At level 3 and above +\fBmkvinfo\fR(1) +will print some information that is not directly connected to a +Matroska(TM) +element\&. All other elements only print stuff about the elements that were just found\&. Level 3 adds meta information to ease debugging (read: it\'s intended for developers only)\&. All lines written by level 3 are enclosed in square brackets to make filtering them out easy\&. +.SH "EXIT CODES" +.PP + +\fBmkvinfo\fR(1) +exits with one of three exit codes: +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB0\fR +\-\- This exit codes means that the run has completed successfully\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB1\fR +\-\- In this case +\fBmkvinfo\fR(1) +has output at least one warning, but the run did continue\&. A warning is prefixed with the text \'Warning:\'\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB2\fR +\-\- This exit code is used after an error occured\&. +\fBmkvinfo\fR(1) +aborts right after outputting the error message\&. Error messages range from wrong command line arguments over read/write errors to broken files\&. +.RE +.SH "SEE ALSO" +.PP + +\fBmkvmerge\fR(1), +\fBmkvextract\fR(1), +\fBmmg\fR(1) +.SH "WWW" +.PP +The latest version can always be found at +\fIthe MKVToolNix homepage\fR\&[1]\&. +.SH "AUTHOR" +.PP +\fBMoritz Bunkus\fR <\&moritz@bunkus\&.org\&> +.sp -1n +.IP "" 4 +Developer +.SH "NOTES" +.IP " 1." 4 +the MKVToolNix homepage +.RS 4 +\%http://www.bunkus.org/videotools/mkvtoolnix/ +.RE diff --git a/doc/man/mkvmerge.1 b/doc/man/mkvmerge.1 new file mode 100644 index 000000000..60148cb90 --- /dev/null +++ b/doc/man/mkvmerge.1 @@ -0,0 +1,1882 @@ +.\" Title: mkvmerge +.\" Author: Moritz Bunkus +.\" Generator: DocBook XSL Stylesheets v1.73.2 +.\" Date: July 2009 +.\" Manual: User Commands +.\" Source: MkvToolNix 2.9.7 +.\" +.TH "MKVMERGE" "1" "July 2009" "MkvToolNix 2\&.9\&.7" "User Commands" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +mkvmerge \- Merge multimedia streams into a Matroska file +.SH "SYNOPSIS" +.HP 9 +\fBmkvmerge\fR [global\ options] {\-o\ out} [options1] {file1} [[options2]\ {file2}] [@optionsfile] +.SH "DESCRIPTION" +.PP +This program takes the input from several media files and joins their streams (all of them or just a selection) into a +Matroska(TM) +file; see +\fIthe Matroska(TM) website\fR\&[1]\&. +.PP +Global options: +.PP +\fB\-v\fR, \fB\-\-verbose\fR +.RS 4 +Increase verbosity\&. +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +Suppress status output\&. +.RE +.PP +\fB\-o\fR, \fB\-\-out\fR \fIfile\-name\fR +.RS 4 +Write to the file +\fIfile\-name\fR\&. If splitting is used then this parameter is treated a bit differently\&. See the explanation for the +\fB\-\-split\fR +option for details\&. +.RE +.PP +\fB\-\-title\fR \fItitle\fR +.RS 4 +Sets the general title for the output file, e\&.g\&. the movie name\&. +.RE +.PP +\fB\-\-tags\fR \fIfile\-name\fR +.RS 4 +Read global tags from the +XML +file +\fIfile\-name\fR\&. See the section about tags below for details\&. +.RE +.PP +\fB\-\-default\-language\fR \fIlanguage\-code\fR +.RS 4 +Sets the default language code that will be used for all tracks unless overwritten with the +\fB\-\-language\fR +option\&. The default language code is \'und\' for \'undefined\'\&. +.RE +.PP +Chapter and tag handling: (global options) +.PP +\fB\-\-chapter\-language\fR \fIlanguage\-code\fR +.RS 4 +Sets the ISO639\-2 language code that is written for each chapter entry\&. Defaults to \'eng\'\&. See the section about +chapters +below for details\&. +.sp +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\&. +.RE +.PP +\fB\-\-chapter\-charset\fR \fIcharacter\-set\fR +.RS 4 +Sets the character set that is used for the conversion to UTF\-8 for simple chapter files\&. See the section about +text files and character sets +for an explanation how +\fBmkvmerge\fR(1) +converts between character sets\&. +.sp +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\&. +.RE +.PP +\fB\-\-cue\-chapter\-name\-format\fR \fIformat\fR +.RS 4 + +\fBmkvmerge\fR(1) +supports reading +CUE +sheets for audio files as the input for chapters\&. +CUE +sheets usually contain the entries +\fIPERFORMER\fR +and +\fITITLE\fR +for each index entry\&. +\fBmkvmerge\fR(1) +uses these two strings in order to construct the chapter name\&. With this option the format used for this name can be set\&. +.sp +If this option is not given then +\fBmkvmerge\fR(1) +defaults to the format \'%p \- %t\' (the performer, followed by a space, a dash, another space and the title)\&. +.sp +If the format is given then everything except the following meta characters is copied as\-is, and the meta characters are replaced like this: +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fI%p\fR +is replaced by the current entry\'s +\fIPERFORMER\fR +string, +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fI%t\fR +is replaced by the current entry\'s +\fITITLE\fR +string, +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fI%n\fR +is replaced by the current track number and +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fI%N\fR +is replaced by the current track number padded with a leading zero if it is < 10\&. +.RE +.RE +.PP +\fB\-\-chapters\fR \fIfile\-name\fR +.RS 4 +Read chapter information from the file +\fIfile\-name\fR\&. See the section about +chapters +below for details\&. +.RE +.PP +\fB\-\-global\-tags\fR \fIfile\-name\fR +.RS 4 +Read global tags from the file +\fIfile\-name\fR\&. See the section about +tags +below for details\&. +.RE +.PP +General output control (advanced global options): +.PP +\fB\-\-track\-order\fR \fIFID1:TID1,FID2:TID2,\&.\&.\&.\fR +.RS 4 +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 (\fIFID1\fR) which is simply the number of the file on the command line starting at 0\&. The second is a track ID (\fITID1\fR) from that file\&. If some track IDs are omitted then those tracks are created after the ones given with this option have been created\&. +.RE +.PP +\fB\-\-cluster\-length\fR \fIspec\fR +.RS 4 +Limit the number of data blocks or the duration of data in each cluster\&. The +\fIspec\fR +parameter can either be a number +\fIn\fR +without a unit or a number +\fId\fR +postfixed with \'ms\'\&. +.sp +If no unit is used then +\fBmkvmerge\fR(1) +will put at most +\fIn\fR +data blocks into each cluster\&. The maximum number of blocks is 65535\&. +.sp +If the number +\fIn\fR +is postfixed with \'ms\' then +\fBmkvmerge\fR(1) +puts at most +\fId\fR +milliseconds of data into each cluster\&. The minimum for +\fId\fR +is \'100ms\', and the maximum is \'32000ms\'\&. +.sp + +\fBmkvmerge\fR(1) +defaults to putting at most 65535 data blocks and 2000ms of data into a cluster\&. +.sp +Programs trying to find a certain frame can only seek directly to a cluster and have to read the whole cluster afterwards\&. Therefore creating larger clusters may lead to imprecise or slow seeking\&. +.RE +.PP +\fB\-\-no\-cues\fR +.RS 4 +Tells +\fBmkvmerge\fR(1) +not to create and write the cue data which can be compared to an index in an AVI\&. +Matroska(TM) +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 +\fB\-\-cues\fR +which can be specified for each input file\&. +.RE +.PP +\fB\-\-no\-clusters\-in\-meta\-seek\fR +.RS 4 +Tells +\fBmkvmerge\fR(1) +not to create a meta seek element at the end of the file containing all clusters\&. See also the section about the +Matroska(TM) file layout\&. +.RE +.PP +\fB\-\-disable\-lacing\fR +.RS 4 +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\&. +.RE +.PP +\fB\-\-enable\-durations\fR +.RS 4 +Write durations for all blocks\&. This will increase file size and does not offer any additional value for players at the moment\&. +.RE +.PP +\fB\-\-timecode\-scale\fR \fIfactor\fR +.RS 4 +Forces the timecode scale factor to +\fIfactor\fR\&. Valid values are in the range +\fB1000\fR\&.\&.\fB10000000\fR +or the special value +\fB\-1\fR\&. +.sp +Normally +\fBmkvmerge\fR(1) +will use a value of +\fB1000000\fR +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 +\fBmkvmerge\fR(1) +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\&. +.sp +If the special value +\fB\-1\fR +is used then +\fBmkvmerge\fR(1) +will use sample precision even if a video track is present\&. +.RE +.PP +File splitting, linking and appending (more global options): +.PP +\fB\-\-split\fR \fIspecification\fR +.RS 4 +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 +\fBmkvmerge\fR(1) +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\&. +.sp +At the moment +\fBmkvmerge\fR(1) +supports three different modes\&. +.sp +.RS 4 +\h'-04' 1.\h'+02'Splitting by size\&. +.sp +Syntax: +\fB\-\-split\fR +[size:]\fId\fR[k|m|g] +.sp +Examples: +\-\-split size:700m +or +\-\-split 150000000 +.sp +The parameter +\fId\fR +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\&. +.sp +The \'size:\' prefix may be omitted for compatibility reasons\&. +.RE +.sp +.RS 4 +\h'-04' 2.\h'+02'Splitting after a duration\&. +.sp +Syntax: +\fB\-\-split\fR +[duration:]\fIHH:MM:SS\&.nnnnnnnnn\fR|\fId\fRs +.sp +Examples: +\-\-split duration:00:60:00\&.000 +or +\-\-split 3600s +.sp +The paramter must either have the form +\fIHH:MM:SS\&.nnnnnnnnn\fR +for specifying the duration in up to nano\-second precision or be a number +\fId\fR +followed by the letter \'s\' for the duration in seconds\&. +\fIHH\fR +is the number of hours, +\fIMM\fR +the number of minutes, +\fISS\fR +the number of seconds and +\fInnnnnnnnn\fR +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\&. +.sp +The \'duration:\' prefix may be omitted for compatibility reasons\&. +.RE +.sp +.RS 4 +\h'-04' 3.\h'+02'Splitting after specific timecodes\&. +.sp +Syntax: +\fB\-\-split\fR +timecodes:\fIA\fR[,\fIB\fR[,\fIC\fR\&.\&.\&.]] +.sp +Example: +\-\-split timecodes:00:45:00\&.000,01:20:00\&.250,6300s +.sp +The parameters +\fIA\fR, +\fIB\fR, +\fIc\fR +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\&. +.sp +The \'timecodes:\' prefix must not be omitted\&. +.sp +For this splitting mode the output filename is treated differently than for the normal operation\&. It may contain a +\fBprintf\fR +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\&. +.RE +.RE +.PP +\fB\-\-link\fR +.RS 4 +Link files to one another when splitting the output file\&. See the section on +file linking +below for details\&. +.RE +.PP +\fB\-\-link\-to\-previous\fR \fIsegment\-UID\fR +.RS 4 +Links the first output file to the segment with the segment UID given by the +\fIsegment\-UID\fR +parameter\&. See the section on +file linking +below for details\&. +.RE +.PP +\fB\-\-link\-to\-next\fR \fIsegment\-UID\fR +.RS 4 +Links the last output file to the segment with the segment UID given by the +\fIsegment\-UID\fR +parameter\&. See the section on +file linking +below for details\&. +.RE +.PP +\fB\-\-append\-mode\fR \fImode\fR +.RS 4 +Determines how timecodes are calculated when appending files\&. The parameter +\fImode\fR +can have two values: \'file\' which is also the default and \'track\'\&. +.sp +When mkvmerge appends a track (called \'track2_1\' from now on) from a second file (called \'file2\') to a track (called \'track1_1\') from the first file (called \'file1\') then it has to offset all timecodes for \'track2_1\' by an amount\&. For \'file\' mode this amount is the highest timecode encountered in \'file1\' even if that timecode was from a different track than \'track1_1\'\&. In track mode the offset is the highest timecode of \'track1_1\'\&. +.sp +Unfortunately mkvmerge cannot detect which mode to use reliably\&. Therefore it defaults to \'file\' mode\&. \'file\' mode usually works better for files that have been created independently of each other; e\&.g\&. when appending +AVI +or +MP4 +files\&. \'track\' mode may work better for sources that are essentially just parts of one big file, e\&.g\&. for +VOB +and +EVO +files\&. +.sp +Subtitle tracks are always treated as if \'file\' mode were active even if \'track\' mode actually is\&. +.RE +.PP +\fB\-\-append\-to\fR \fISFID1:STID1:DFID1:DTID1\fR\fI[,\&.\&.\&.]\fR +.RS 4 +This option controls to which track another track is appended\&. Each spec contains four IDs: a file ID, a track ID, a second file ID and a second track ID\&. The first pair, "source file ID" and "source track ID", identifies the track that is to be appended\&. The second pair, "destination file ID" and "destination track ID", identifies the track the first one is appended to\&. +.sp +If this option has been omitted then a standard mapping is used\&. This standard mapping appends each track from the current file to a track from the previous file with the same track ID\&. This allows for easy appending if a movie has been split into two parts and both file have the same number of tracks and track IDs with the command +\fBmkvmerge \-o output\&.mkv part1\&.mkv +part2\&.mkv\fR\&. +.RE +.PP +Attachment support (more global options): +.PP +\fB\-\-attachment\-description\fR \fIdescription\fR +.RS 4 +Plain text description of the following attachment\&. Applies to the next +\fB\-\-attach\-file\fR +or +\fB\-\-attach\-file\-once\fR +option\&. +.RE +.PP +\fB\-\-attachment\-mime\-type\fR \fIMIME type\fR +.RS 4 + +MIME +type of the following attachment\&. Applies to the next +\fB\-\-attach\-file\fR +or +\fB\-\-attach\-file\-once\fR +option\&. A list of officially recognized +MIME +types can be found e\&.g\&. at +\fIthe IANA homepage\fR\&[2]\&. The +MIME +type is mandatory for an attachment\&. +.RE +.PP +\fB\-\-attachment\-name\fR \fIname\fR +.RS 4 +Sets the name that will be stored in the output file for this attachment\&. If this option is not given then the name will be derived from the file name of the attachment as given with the +\fB\-\-attach\-file\fR +or the +\fB\-\-attach\-file\-once\fR +option\&. +.RE +.PP +\fB\-\-attach\-file\fR \fIfile\-name\fR, \fB\-\-attach\-file\-once\fR \fIfile\-name\fR +.RS 4 +Creates a file attachment inside the +Matroska(TM) +file\&. The +MIME +type must have been set before this option can used\&. The difference between the two forms is that during splitting the files attached with +\fB\-\-attach\-file\fR +are attached to all output files while the ones attached with +\fB\-\-attach\-file\-once\fR +are only attached to the first file created\&. If splitting is not used then both do the same\&. +.sp + +\fBmkvextract\fR(1) +can be used to extract attached files from a +Matroska(TM) +file\&. +.RE +.PP +Options that can be used for each input file: +.PP +\fB\-a\fR, \fB\-\-audio\-tracks\fR \fIn,m,\&.\&.\&.\fR +.RS 4 +Copy the audio tracks +\fIn\fR, +\fIm\fR +etc\&. The numbers are track IDs which can be obtained with the +\fB\-\-identify\fR +switch\&. They\'re not simply the track numbers (see section +track IDs)\&. Default: copy all audio tracks\&. +.RE +.PP +\fB\-d\fR, \fB\-\-video\-tracks\fR \fIn,m,\&.\&.\&.\fR +.RS 4 +Copy the video tracks +\fIn\fR, +\fIm\fR +etc\&. The numbers are track IDs which can be obtained with the +\fB\-\-identify\fR +switch\&. They\'re not simply the track numbers (see section +track IDs)\&. Default: copy all video tracks\&. +.RE +.PP +\fB\-s\fR, \fB\-\-subtitle\-tracks\fR \fIn,m,\&.\&.\&.\fR +.RS 4 +Copy the subtitle tracks +\fIn\fR, +\fIm\fR +etc\&. The numbers are track IDs which can be obtained with the +\fB\-\-identify\fR +switch\&. They\'re not simply the track numbers (see section +track IDs)\&. Default: copy all subtitle tracks\&. +.RE +.PP +\fB\-b\fR, \fB\-\-button\-tracks\fR \fIn,m,\&.\&.\&.\fR +.RS 4 +Copy the button tracks +\fIn\fR, +\fIm\fR +etc\&. The numbers are track IDs which can be obtained with the +\fB\-\-identify\fR +switch\&. They\'re not simply the track numbers (see section +track IDs)\&. Default: copy all button tracks\&. +.RE +.PP +\fB\-\-track\-tags\fR \fIn,m,\&.\&.\&.\fR +.RS 4 +Copy the tags for tracks +\fIn\fR, +\fIm\fR +etc\&. The numbers are track IDs which can be obtained with the +\fB\-\-identify\fR +switch (see section +track IDs)\&. They\'re not simply the track numbers\&. Default: copy tags for all tracks\&. +.RE +.PP +\fB\-m\fR, \fB\-\-attachments\fR \fIn\fR\fI[:all|first]\fR\fI,m\fR\fI[:all|first]\fR\fI,\&.\&.\&.\fR +.RS 4 +Copy the attachments with the IDs +\fIn\fR, +\fIm\fR +etc to all or only the first output file\&. Each ID can be followed by either \':all\' (which is the default if neither is entered) or \':first\'\&. If splitting is active then those attachments whose IDs are specified with \':all\' are copied to all of the resulting output files while the others are only copied into the first output file\&. If splitting is not active then both variants have the same effect\&. +.sp +The default is to copy all attachments to all output files\&. +.RE +.PP +\fB\-A\fR, \fB\-\-no\-audio\fR +.RS 4 +Don\'t copy any audio track from this file\&. +.RE +.PP +\fB\-D\fR, \fB\-\-no\-video\fR +.RS 4 +Don\'t copy any video track from this file\&. +.RE +.PP +\fB\-S\fR, \fB\-\-no\-subtitles\fR +.RS 4 +Don\'t copy any subtitle track from this file\&. +.RE +.PP +\fB\-B\fR, \fB\-\-no\-buttons\fR +.RS 4 +Don\'t copy any button track from this file\&. +.RE +.PP +\fB\-T\fR, \fB\-\-no\-track\-tags\fR +.RS 4 +Don\'t copy any track specific tags from this file\&. +.RE +.PP +\fB\-\-no\-chapters\fR +.RS 4 +Don\'t copy chapters from this file\&. +.RE +.PP +\fB\-M\fR, \fB\-\-no\-attachments\fR +.RS 4 +Don\'t copy attachments from this file\&. +.RE +.PP +\fB\-\-no\-global\-tags\fR +.RS 4 +Don\'t copy global tags from this file\&. +.RE +.PP +\fB\-\-chapter\-charset\fR \fIcharacter\-set\fR +.RS 4 +Sets the charset that is used for the conversion to UTF\-8 for chapter information contained in the source file\&. See the section about +text files and character sets +for an explanation how +\fBmkvmerge\fR(1) +converts between character sets\&. +.RE +.PP +\fB\-\-chapter\-language\fR \fIlanguage\-code\fR +.RS 4 +Sets the ISO639\-2 language code that is written for each chapter entry\&. This option can be used for source files that contain chapters but no information about the chapters\' languages, e\&.g\&. for MP4 and OGM files\&. +.RE +.PP +\fB\-y\fR, \fB\-\-sync\fR \fITID:d\fR\fI[,o[/p]]\fR +.RS 4 +Adjust the timecodes of the track with the id +\fITID\fR +by +\fId\fR +ms\&. The track IDs are the same as the ones given with +\fB\-\-identify\fR +(see section +track IDs)\&. +.sp + +\fIo\fR/\fIp\fR: adjust the timestamps by +\fIo\fR/\fIp\fR +to fix linear drifts\&. +\fIp\fR +defaults to 1 if omitted\&. Both +\fIo\fR +and +\fIp\fR +can be floating point numbers\&. +.sp +Defaults: no manual sync correction (which is the same as +\fId\fR += +\fB0\fR +and +\fIo\fR/\fIp\fR += +\fB1\&.0\fR)\&. +.sp +This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time\&. +.RE +.PP +\fB\-\-cues\fR \fITID:none|iframes|all\fR +.RS 4 +Controls for which tracks cue (index) entries are created for the given track (see section +track IDs)\&. \'none\' inhibits the creation of cue entries\&. For \'iframes\' only blocks with no backward or forward references ( = I frames in video tracks) are put into the cue sheet\&. \'all\' causes +\fBmkvmerge\fR(1) +to create cue entries for all blocks which will make the file very big\&. +.sp +The default is \'iframes\' for video tracks and \'none\' for all others\&. See also option +\fB\-\-no\-cues\fR +which inhibits the creation of cue entries regardless of the +\fB\-\-cues\fR +options used\&. +.sp +This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time\&. +.RE +.PP +\fB\-\-default\-track\fR \fITID\fR\fI[:bool]\fR +.RS 4 +Sets the \'default\' flag for the given track (see section +track IDs) if the optional argument +\fIbool\fR +is not present\&. If the user does not explicitly select a track himself then the player should prefer the track that has his \'default\' flag set\&. Only one track of each kind (audio, video, subtitles, buttons) can have his \'default\' flag set\&. If the user wants no track to have the default track flag set then he has to set +\fIbool\fR +to +\fB0\fR +for all tracks\&. +.sp +This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time\&. +.RE +.PP +\fB\-\-blockadd\fR \fITID:level\fR +.RS 4 +Keep only the +BlockAdditions +up to the level +\fIlevel\fR +for the given track\&. The default is to keep all levels\&. This option only affects certain kinds of codecs like WAVPACK4\&. +.RE +.PP +\fB\-\-track\-name\fR \fITID:name\fR +.RS 4 +Sets the track name for the given track (see section +track IDs) to +\fIname\fR\&. +.RE +.PP +\fB\-\-language\fR \fITID:language\fR +.RS 4 +Sets the language for the given track (see section +track IDs)\&. Both ISO639\-2 language codes and ISO639\-1 country codes are allowed\&. The country codes will be converted to language codes automatically\&. All languages including their ISO639\-2 codes can be listed with the +\fB\-\-list\-languages\fR +option\&. +.sp +This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time\&. +.RE +.PP +\fB\-t\fR, \fB\-\-tags\fR \fITID:file\-name\fR +.RS 4 +Read tags for the track with the number +\fITID\fR +from the file +\fIfile\-name\fR\&. See the section about +tags +below for details\&. +.RE +.PP +\fB\-\-aac\-is\-sbr\fR \fITID\fR\fI[:0|1]\fR +.RS 4 +Tells +\fBmkvmerge\fR(1) +that the track with the ID +\fITID\fR +is +SBR AAC +(also known as +HE\-AAC +or +AAC+)\&. This options is needed if a) the source file is an +AAC +file (\fInot\fR +for a +Matroska(TM) +file) and b) the +AAC +file contains +SBR AAC +data\&. The reason for this switch is that it is technically impossible to automatically tell normal +AAC +data from +SBR AAC +data without decoding a complete +AAC +frame\&. As there are several patent issues with +AAC +decoders +\fBmkvmerge\fR(1) +will never contain this decoding stage\&. So for +SBR AAC +files this switch is mandatory\&. The resulting file might not play back correctly or even not at all if the switch was omitted\&. +.sp +If the source file is a +Matroska(TM) +file then the +CodecID +should be enough to detect +SBR AAC\&. However, if the +CodecID +is wrong then this switch can be used to correct that\&. +.sp +If mkvmerge wrongfully detects that an +AAC +file is +SBR +then you can add \':0\' to the track ID\&. +.RE +.PP +\fB\-\-timecodes\fR \fITID:file\-name\fR +.RS 4 +Read the timecodes to be used for the specific track ID from +\fIfile\-name\fR\&. These timecodes forcefully override the timecodes that +\fBmkvmerge\fR(1) +normally calculates\&. Read the section about +external timecode files\&. +.RE +.PP +\fB\-\-default\-duration\fR \fITID:x\fR +.RS 4 +Forces the default duration of a given track to the specified value\&. Also modifies the track\'s timecodes to match the default duration\&. The argument +\fIx\fR +must be postfixed with \'s\', \'ms\', \'us\', \'ns\' or \'fps\' to specify the default duration in seconds, milliseconds, microseconds, nanoseconds or \'frames per second\' respectively\&. The number +\fIx\fR +itself can be a floating point number or a fraction\&. +.sp +If the default duration is not forced then mkvmerge will try to derive the track\'s default duration from the container and/or codec used\&. One case in which this option is of use is when adding +AVC/h\&.264 +elementary streams because these do not contain information about their number of frames or a default duration for each frame\&. For such files +\fBmkvmerge\fR(1) +will assume a default duration of \'25fps\' unless overridden\&. +.sp +This option can also be used to change the +FPS +of video tracks without having to use an external timecode file\&. +.RE +.PP +\fB\-\-nalu\-size\-length\fR \fITID:n\fR +.RS 4 +Forces the +NALU +size length to +\fIn\fR +bytes\&. This parameter is only used if the +AVC/h\&.264 +elementary stream packetizer is used\&. If left out it defaults to 4 bytes, but there are files that contain frames or slices that are a4ll smaller than 65536 bytes\&. For such files you can use this parameter and decrease the size to 2\&. +.RE +.PP +Options that only apply to video tracks: +.PP +\fB\-f\fR, \fB\-\-fourcc\fR \fITID:FourCC\fR +.RS 4 +Forces the +FourCC +to the specified value\&. Works only for video tracks in the \'MS compatibility mode\'\&. +.RE +.PP +\fB\-\-display\-dimensions\fR \fITID:widthxheight\fR +.RS 4 + +Matroska(TM) +files contain two values that set the display properties that a player should scale the image on playback to: display width and display height\&. These values can be set with this option, e\&.g\&. \'1:640x480\'\&. +.sp +Another way to specify the values is to use the +\fB\-\-aspect\-ratio\fR +or the +\fB\-\-aspect\-ratio\-factor\fR +option (see below)\&. These options are mutually exclusive\&. +.RE +.PP +\fB\-\-aspect\-ratio\fR \fITID:ratio|width/height\fR +.RS 4 + +Matroska(TM) +files contain two values that set the display properties that a player should scale the image on playback to: display width and display height\&. With this option +\fBmkvmerge\fR(1) +will automatically calculate the display width and display height based on the image\'s original width and height and the aspect ratio given with this option\&. The ratio can be given either as a floating point number +\fIratio\fR +or as a fraction \'\fIwidth\fR/\fIheight\fR\', e\&.g\&. \'16/9\'\&. +.sp +Another way to specify the values is to use the +\fB\-\-aspect\-ratio\-factor\fR +or +\fB\-\-display\-dimensions\fR +options (see above and below)\&. These options are mutually exclusive\&. +.RE +.PP +\fB\-\-aspect\-ratio\-factor\fR \fITID:factor|n/d\fR +.RS 4 +Another way to set the aspect ratio is to specify a +\fIfactor\fR\&. The original aspect ratio is first multiplied with this +\fIfactor\fR +and used as the target aspect ratio afterwards\&. +.sp +Another way to specify the values is to use the +\fB\-\-aspect\-ratio\fR +or +\fB\-\-display\-dimensions\fR +options (see above)\&. These options are mutually exclusive\&. +.RE +.PP +\fB\-\-cropping\fR \fITID:left,top,right,bottom\fR +.RS 4 +Sets the pixel cropping parameters of a video track to the given values\&. +.RE +.PP +\fB\-\-stereo\-mode\fR \fITID:n|keyword\fR +.RS 4 +Sets the stereo mode for the video track with the track ID +\fITID\fR\&. The mode can either be a number +\fIn\fR +between +\fB0\fR +and +\fB3\fR +or one of the keywords \'none\' (same as +\fIn\fR=\fB0\fR), \'right\' (same as +\fIn\fR=\fB1\fR), \'left\' (same as +\fIn\fR=\fB2\fR) or \'both\' (same as +\fIn\fR=\fB3\fR)\&. +.RE +.PP +\fB\-\-compression\fR \fITID:method\fR +.RS 4 +Selects the compression method to be used for the VobSub track\&. Note that the player also has to support this method\&. Valid values are \'none\', \'zlib\', \'lzo\'/\'lxo1x\', \'bz2\'/\'bzlib\' and \'mpeg4_p2\'/\'mpeg4p2\'\&. The values \'lzo\'/\'lxo1x\' and \'bz2\'/\'bzlib\' are only available if +\fBmkvmerge\fR(1) +has been compiled with support for the +liblzo(TM) +respectively +bzlib(TM) +compression libraries\&. +.sp +The compression method \'mpeg4_p2\'/\'mpeg4p2\' is a special compression method called \'header removal\' that is only available for MPEG4 part 2 video tracks\&. The other methods are general compression methods that can be used with any type of track\&. +.sp +The default is \'zlib\' compression\&. This compression method is also the one that most if not all playback applications support\&. Support for other compression methods other than \'none\' is not assured\&. +.RE +.PP +Options that only apply to text subtitle tracks: +.PP +\fB\-\-sub\-charset\fR \fITID:character\-set\fR +.RS 4 +Sets the character set for the conversion to UTF\-8 for UTF\-8 subtitles for the given track ID\&. If not specified the charset will be derived from the current locale settings\&. Note that a charset is not needed for subtitles read from +Matroska(TM) +files or from Kate streams, as these are always stored in UTF\-8\&. See the section about +text files and character sets +for an explanation how +\fBmkvmerge\fR(1) +converts between character sets\&. +.sp +This option can be used multiple times for an input file applying to several tracks by selecting different track IDs each time\&. +.RE +.PP +Other options: +.PP +\fB\-i\fR, \fB\-\-identify\fR \fIfile\-name\fR +.RS 4 +Will let +\fBmkvmerge\fR(1) +probe the single file and report its type, the tracks contained in the file and their track IDs\&. If this option is used then the only other option allowed is the filename\&. +.RE +.PP +\fB\-l\fR, \fB\-\-list\-types\fR +.RS 4 +Lists supported input file types\&. +.RE +.PP +\fB\-\-list\-languages\fR +.RS 4 +Lists all languages and their ISO639\-2 code which can be used with the +\fB\-\-language\fR +option\&. +.RE +.PP +\fB\-\-priority\fR \fIpriority\fR +.RS 4 +Sets the process priority that +\fBmkvmerge\fR(1) +runs with\&. Valid values are \'lowest\', \'lower\', \'normal\', \'higher\' and \'highest\'\&. If nothing is given then \'normal\' is used\&. On Unix like systems +\fBmkvmerge\fR(1) +will use the +\fBnice\fR(2) +function\&. Therefore only the super user can use \'higher\' and \'highest\'\&. On Windows all values are useable for every user\&. +.RE +.PP +\fB\-\-command\-line\-charset\fR \fIcharacter\-set\fR +.RS 4 +Sets the character set to convert strings given on the command line from\&. It defaults to the character set given by system\'s current locale\&. This settings applies to arguments of the following options: +\fB\-\-title\fR, +\fB\-\-track\-name\fR +and +\fB\-\-attachment\-description\fR\&. +.RE +.PP +\fB\-\-output\-charset\fR \fIcharacter\-set\fR +.RS 4 +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\&. +.RE +.PP +\fB\-r\fR, \fB\-\-redirect\-output\fR \fIfile\-name\fR +.RS 4 +Writes all messages to the file +\fIfile\-name\fR +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 +\fB\-\-output\-charset\fR +is honored\&. +.RE +.PP +\fB\-\-ui\-language\fR \fIcode\fR +.RS 4 +Forces the translations for the language +\fIcode\fR +to be used (e\&.g\&. \'de_DE\' for the German translations)\&. It is preferable to use the environment variables +\fILANG\fR, +\fILC_MESSAGES\fR +and +\fILC_ALL\fR +though\&. Entering \'list\' as the +\fIcode\fR +will cause +\fBmkvmerge\fR(1) +to output a list of available translations\&. +.RE +.PP +\fB@\fRoptions\-file +.RS 4 +Reads additional command line arguments from the file +\fIoptions\-file\fR\&. 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\&. +.sp +The command line \'\fBmkvmerge \-o "my file\&.mkv" \-A "a movie\&.avi" sound\&.ogg\fR\' could be converted into the following option file: +.sp +.RS 4 +.nf +# Write to the file "my file\&.mkv"\&. +\-o +my file\&.mkv +# Only take the video from "a movie\&.avi"\&. +\-A +a movie\&.avi +sound\&.ogg + +.fi +.RE +.RE +.PP +\fB\-\-capabilities\fR +.RS 4 +Lists information about optional features that have been compiled in and exit\&. The first line output will be the version information\&. All following lines contain exactly one word whose presence indicates that the feature has been compiled in\&. These features are: +.sp +.RS 4 +\h'-04'\(bu\h'+03'\'BZ2\' \-\- the +bzlib(TM) +compression library\&. Affects the available compression methods for the +\fB\-\-compression\fR +option\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\'LZO\' \-\- the +lzo(TM) +compression library\&. Affects the available compression methods for the +\fB\-\-compression\fR +option\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\'FLAC\' \-\- reading raw +FLAC +files and handling +FLAC +tracks in other containers, e\&.g\&. +Ogg(TM) +or +Matroska(TM)\&. +.RE +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show usage information and exit\&. +.RE +.PP +\fB\-V\fR, \fB\-\-version\fR +.RS 4 +Show version information and exit\&. +.RE +.SH "USAGE" +.PP +For each file the user can select which tracks +\fBmkvmerge\fR(1) +should take\&. They are all put into the file specified with +\fB\-o\fR\&. A list of known (and supported) source formats can be obtained with the +\fB\-l\fR +option\&. +.SH "EXAMPLES" +.PP +Let\'s assume you have a file called MyMovie\&.avi and the audio track in a separate file, e\&.g\&. \'MyMovie\&.wav\'\&. First you want to encode the audio to +OggVorbis(TM): +.sp +.RS 4 +.nf +$ oggenc \-q4 \-oMyMovie\&.ogg MyMovie\&.wav +.fi +.RE +.PP +After a couple of minutes you can join video and audio: +.sp +.RS 4 +.nf +$ mkvmerge \-o MyMovie\-with\-sound\&.mkv MyMovie\&.avi MyMovie\&.ogg +.fi +.RE +.PP +If your +AVI +already contains an audio track then it will be copied as well (if +\fBmkvmerge\fR(1) +supports the audio format)\&. To avoid that simply do +.sp +.RS 4 +.nf +$ mkvmerge \-o MyMovie\-with\-sound\&.mkv \-A MyMovie\&.avi MyMovie\&.ogg +.fi +.RE +.PP +After some minutes of consideration you rip another audio track, e\&.g\&. the director\'s comments or another language to \'MyMovie\-add\-audio\&.wav\'\&. Encode it again and join it up with the other file: +.sp +.RS 4 +.nf +$ oggenc \-q4 \-oMyMovie\-add\-audio\&.ogg MyMovie\-add\-audio\&.wav +$ mkvmerge \-o MM\-complete\&.mkv MyMovie\-with\-sound\&.mkv MyMovie\-add\-audio\&.ogg + +.fi +.RE +.PP +The same result can be achieved with +.sp +.RS 4 +.nf +$ mkvmerge \-o MM\-complete\&.mkv \-A MyMovie\&.avi MyMovie\&.ogg MyMovie\-add\-audio\&.ogg +.fi +.RE +.PP +Now fire up +mplayer(TM) +and enjoy\&. If you have multiple audio tracks (or even video tracks) then you can tell +mplayer(TM) +which track to play with the \'\fB\-vid\fR\' and \'\fB\-aid\fR\' options\&. These are 0\-based and do not distinguish between video and audio\&. +.PP +If you need an audio track synchronized you can do that easily\&. First find out which track ID the Vorbis track has with +.sp +.RS 4 +.nf +$ mkvmerge \-\-identify outofsync\&.ogg +.fi +.RE +.PP +Now you can use that ID in the following command line: +.sp +.RS 4 +.nf +$ mkvmerge \-o goodsync\&.mkv \-A source\&.avi \-y 12345:200 outofsync\&.ogg +.fi +.RE +.PP +This would add 200ms of silence at the beginning of the audio track with the ID +\fB12345\fR +taken from \'outofsync\&.ogg\'\&. +.PP +Some movies start synced correctly but slowly drift out of sync\&. For these kind of movies you can specify a delay factor that is applied to all timestamps \-\- no data is added or removed\&. So if you make that factor too big or too small you\'ll get bad results\&. An example is that an episode I transcoded was +\fB0\&.2\fR +seconds out of sync at the end of the movie which was +\fB77340\fR +frames long\&. At +\fB29\&.97fps\fR +\fB0\&.2\fR +seconds correspond to approx\&. +\fB6\fR +frames\&. So I did +.sp +.RS 4 +.nf +$ mkvmerge \-o goodsync\&.mkv \-y 23456:0,77346/77340 outofsync\&.mkv +.fi +.RE +.PP +The result was fine\&. +.PP +The sync options can also be used for subtitles in the same manner\&. +.PP +For text subtitles you can either use some Windows software (like +SubRipper(TM)) or the +subrip(TM) +package found in +\fBtranscode\fR(1)\'s sources in the \'contrib/subrip\' directory\&. The general process is: +.sp +.RS 4 +\h'-04' 1.\h'+02'extract a raw subtitle stream from the source: +.sp +.RS 4 +.nf +$ tccat \-i /path/to/copied/dvd/ \-T 1 \-L | tcextract \-x ps1 \-t vob \-a 0x20 | subtitle2pgm \-o mymovie +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+02'convert the resulting PGM images to text with gocr: +.sp +.RS 4 +.nf +$ pgm2txt mymovie +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+02'spell\-check the resulting text files: +.sp +.RS 4 +.nf +$ ispell \-d american *txt +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+02'convert the text files to a SRT file: +.sp +.RS 4 +.nf +$ srttool \-s \-w \-i mymovie\&.srtx \-o mymovie\&.srt +.fi +.RE +.RE +.PP +The resulting file can be used as another input file for +\fBmkvmerge\fR(1): +.sp +.RS 4 +.nf +$ mkvmerge \-o mymovie\&.mkv mymovie\&.avi mymovie\&.srt +.fi +.RE +.PP +If you want to specify the language for a given track then this is easily done\&. First find out the ISO639\-2 code for your language\&. +\fBmkvmerge\fR(1) +can list all of those codes for you: +.sp +.RS 4 +.nf +$ mkvmerge \-\-list\-languages +.fi +.RE +.PP +Search the list for the languages you need\&. Let\'s assume you have put two audio tracks into a +Matroska(TM) +file and want to set their language codes and that their track IDs are 2 and 3\&. This can be done with +.sp +.RS 4 +.nf +$ mkvmerge \-o with\-lang\-codes\&.mkv \-\-language 2:ger \-\-language 3:dut without\-lang\-codes\&.mkv +.fi +.RE +.PP +As you can see you can use the +\fB\-\-language\fR +switch multiple times\&. +.PP +Maybe you\'d also like to have the player use the Dutch language as the default language\&. You also have extra subtitles, e\&.g\&. in English and French, and want to have the player display the French ones by default\&. This can be done with +.sp +.RS 4 +.nf +$ mkvmerge \-o with\-lang\-codes\&.mkv \-\-language 2:ger \-\-language 3:dut \-\-default\-track 3 without\-lang\-codes\&.mkv \-\-language 0:eng english\&.srt \-\-default\-track 0 \-\-language 0:fre french\&.srt +.fi +.RE +.PP +If you do not see the language or default track flags that you\'ve specified in +\fBmkvinfo\fR(1)\'s output then please read the section about +default values\&. +.SH "TRACK IDS" +.PP +Some of the options for +\fBmkvmerge\fR(1) +need a track ID to specify which track they should be applied to\&. Those track IDs are printed by the readers when demuxing the current input file, or if +\fBmkvmerge\fR(1) +is called with the +\fB\-\-identify\fR +option\&. An example for such output: +.sp +.RS 4 +.nf +$ mkvmerge \-i v\&.mkv +File \'v\&.mkv\': container: Matroska(TM) +Track ID 1: video (V_MS/VFW/FOURCC, DIV3) +Track ID 2: audio (A_MPEG/L3) + +.fi +.RE +.PP +Track IDs are assigned like this: +.sp +.RS 4 +\h'-04'\(bu\h'+03' +AVI +files: The video track has the ID 0\&. The audio tracks get IDs in ascending order starting at 1\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +AAC, +AC3, +MP3, +SRT +and +WAV +files: The one \'track\' in that file gets the ID 0\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'Ogg/OGM +files: The track IDs are assigned in order the tracks are found in the file starting at 0\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +Matroska(TM) +files: The track\'s ID is the track number as reported by +\fBmkvinfo\fR(1)\&. It is +\fInot\fR +the track UID\&. +.RE +.PP +The special track ID \'\fB\-1\fR\' is a wild card and applies the given switch to all tracks that are read from an input file\&. +.PP +The options that use the track IDs are the ones whose description contains \'TID\'\&. The following options use track IDs as well: +\fB\-\-atracks\fR, +\fB\-\-vtracks\fR, +\fB\-\-stracks\fR +and +\fB\-\-btracks\fR\&. +.SH "TEXT FILES AND CHARACTER SET CONVERSIONS" +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +Note +.PP +This section applies to all programs in MkvToolNix even if it only mentions +\fBmkvmerge\fR(1)\&. +.PP +All text in a +Matroska(TM) +file is encoded in UTF\-8\&. This means that +\fBmkvmerge\fR(1) +has to convert every text file it reads as well as every text given on the command line from one character set into UTF\-8\&. In return this also means that +\fBmkvmerge\fR(1)\'s output has to be converted back to that character set from UTF\-8, e\&.g\&. if a non\-English translation is used with +\fB\-\-ui\-language\fR +or for text originating from a +Matroska(TM) +file\&. +.PP + +\fBmkvmerge\fR(1) +does this conversion automatically based on the presence of a +byte order marker +(short: +BOM) or the system\'s current locale\&. How the character set is inferred from the locale depends on the operating system that +\fBmkvmerge\fR(1) +is run on\&. +.PP +Text files that start with a BOM are already encoded in one representation of UTF\&. +\fBmkvmerge\fR(1) +supports the following five modes: UTF\-8, UTF\-16 Little and Big Endian, UTF\-32 Little and Big Endian\&. Text files with a BOM are automatically converted to UTF\-8\&. Any of the parameters that would otherwise set the character set for such a file (e\&.g\&. +\fB\-\-sub\-charset\fR) is silently ignored\&. +.PP +On Unix\-like systems +\fBmkvmerge\fR(1) +uses the +\fBsetlocale\fR(3) +system call which in turn uses the environment variables +\fILANG\fR, +\fILC_ALL\fR +and +\fILC_CYPE\fR\&. The resulting character set is often one of UTF\-8 or the ISO\-8859\-* family and is used for all text file operations and for encoding strings on the command line and for output to the console\&. +.PP +On Windows there are actually two different character sets that +\fBmkvmerge\fR(1) +uses due to the way the Windows shell program +\fBcmd\&.exe\fR +is implemented\&. The first character set is determined by a call to the +\fBGetCP()\fR +system call\&. This character set is used as the default for text file conversions and for all elements displayed by the +GUI +programs in the MkvToolNix package\&. +\fBcmd\&.exe\fR +uses another character set which is determined by a call to the +\fBGetACP()\fR +system call\&. This is the default character set for all strings read from the command line and for all strings output to the console\&. +.PP +The following options exist that allow specifying the character sets: +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB\-\-sub\-charset\fR +for text subtitle files and for text subtitle tracks stored in container formats for which the character set cannot be determined unambiguously (e\&.g\&. Ogg files), +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB\-\-chapter\-charset\fR +for chapter text files and for chapters and file titles stored in container formats for which the character set cannot be determined unambiguously (e\&.g\&. Ogg files for chapter information, track and file titles etc; MP4 files for chapter information), +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB\-\-command\-line\-charset\fR +for all strings on the command line, +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB\-\-output\-charset\fR +for all strings written to the console or to a file if the output has been redirected with the +\fB\-\-redirect\-output\fR +option\&. +.RE +.SH "SUBTITLES" +.PP +There are several text subtitle formats that can be embedded into +Matroska(TM)\&. At the moment +\fBmkvmerge\fR(1) +supports only text, VobSub and Kate subtitle formats\&. Text subtitles must be recoded to UTF\-8 so that they can be displayed correctly by a player (see the section about +text files and character sets +for an explanation how +\fBmkvmerge\fR(1) +converts between character sets)\&. Kate subtitles are already encoded in UTF\-8 and do not have to be re0encoded\&. +.PP +The following subtitle formats are supported at the moment: +.sp +.RS 4 +\h'-04'\(bu\h'+03'Subtitle Ripper (SRT) files +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'Substation Alpha (SSA) / Advanced Substation Alpha scripts (ASS) +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'OggKate streams +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'VobSub bitmap subtitle files +.RE +.SH "FILE LINKING" +.PP + +Matroska(TM) +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(TM) +segments\&. As most files will probably only contain one +Matroska(TM) +segment the following explanations use the term \'file linking\' although \'segment linking\' would be more appropriate\&. +.PP +Each segment is identified by a unique 128 bit wide segment UID\&. This UID is automatically generated by +\fBmkvmerge\fR(1)\&. The linking is done primarily via putting the segment UIDs (short: +SID) of the previous/next file into the segment header information\&. +\fBmkvinfo\fR(1) +prints these +SIDs +if it finds them\&. +.PP +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 +\fBmkvmerge\fR(1) +does not use file linking\&. If you want that you can turn it on with the +\fB\-\-link\fR +option\&. This option is only useful if splitting is activated as well\&. +.PP +Regardless of whether splitting is active or not the user can tell +\fBmkvmerge\fR(1) +to link the produced files to specific +SIDs\&. This is achieved with the options +\fB\-\-link\-to\-previous\fR +and +\fB\-\-link\-to\-next\fR\&. These options accept a segment +SID +in the format that +\fBmkvinfo\fR(1) +outputs: 16 hexadecimal numbers between +\fB0x00\fR +and +\fB0xff\fR +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 +\fB0x00\fR +and +\fB0xff\fR +without the \'0x\' prefixes and without the spaces, e\&.g\&. \'41da7366d9cfb21eae78ebb45ecab393\'\&. +.PP +If splitting is used then the first file is linked to the +SID +given with +\fB\-\-link\-to\-previous\fR +and the last file is linked to the +SID +given with +\fB\-\-link\-to\-next\fR\&. If splitting is not used then the one output file will be linked to both of the two +SIDs\&. +.SH "DEFAULT VALUES" +.PP +The +Matroska(TM) +specification states that some elements have a default value\&. Usually an element is not written to the file if its value is equal to its default value in order to save space\&. The elements that the user might miss in +\fBmkvinfo\fR(1)\'s output are the +\fIlanguage\fR +and the +\fIdefault track flag\fR +elements\&. The default value for the +\fIlanguage\fR +is English (\'eng\'), and the default value for the +\fIdefault track flag\fR +is +\fItrue\fR\&. Therefore if you used +\fB\-\-language 0:eng\fR +for a track then it will not show up in +\fBmkvinfo\fR(1)\'s output\&. +.SH "ATTACHMENTS" +.PP +Maybe you also want to keep some photos along with your +Matroska(TM) +file, or you\'re using +SSA +subtitles and need a special +TrueType(TM) +font that\'s really rare\&. In these cases you can attach those files to the +Matroska(TM) +file\&. They will not be just appended to the file but embedded in it\&. A player can then show those files (the \'photos\' case) or use them to render the subtitles (the \'TrueType(TM) +fonts\' case)\&. +.PP +Here\'s an example how to attach a photo and a +TrueType(TM) +font to the output file: +.sp +.RS 4 +.nf +$ mkvmerge \-o output\&.mkv \-A video\&.avi sound\&.ogg \-\-attachment\-description "Me and the band behind the stage in a small get\-together" \-\-attachment\-mime\-type image/jpeg \-\-attach\-file me_and_the_band\&.jpg \-\-attachment\-description "The real rare and unbelievably good looking font" \-\-attachment\-type application/octet\-stream \-\-attach\-file really_cool_font\&.ttf + +.fi +.RE +.PP +If a +Matroska(TM) +containing attachments file is used as an input file then +\fBmkvmerge\fR(1) +will copy the attachments into the new file\&. The selection which attachments are copied and which are not can be changed with the options +\fB\-\-attachments\fR +and +\fB\-\-no\-attachments\fR\&. +.SH "CHAPTERS" +.PP +The +Matroska(TM) +chapter system is more powerful than the old known system used by +OGM +files\&. The full specifications can be found at +\fIthe Matroska(TM) website\fR\&[1]\&. +.PP + +\fBmkvmerge\fR(1) +supports two kinds of chapter files as its input\&. The first format, called \'simple chapter format\', is the same format that the +OGM +tools expect\&. The second format is a +XML +based chapter format which supports all of +Matroska(TM)\'s chapter functionality\&. +.SS "The simple chapter format" +.PP +This formmat consists of pairs of lines that start with \'CHAPTERxx=\' and \'CHAPTERxxNAME=\' respectively\&. The first one contains the start timecode while the second one contains the title\&. Here\'s an example: +.sp +.RS 4 +.nf +CHAPTER01=00:00:00\&.000 +CHAPTER01NAME=Intro +CHAPTER02=00:02:30\&.000 +CHAPTER02NAME=Baby prepares to rock +CHAPTER03=00:02:42\&.300 +CHAPTER03NAME=Baby rocks the house + +.fi +.RE +.PP + +\fBmkvmerge\fR(1) +will transform every pair or lines into one +Matroska(TM) +ChapterAtom\&. It does not set any +ChapterTrackNumber +which means that the chapters all apply to all tracks in the file\&. +.PP +As this is a text file character set conversion may need to be done\&. See the section about +text files and character sets +for an explanation how +\fBmkvmerge\fR(1) +converts between character sets\&. +.SS "The XML based chapter format" +.PP +The +XML +based chapter format looks like this example: +.sp +.RS 4 +.nf + + + + + + 00:00:30\&.000 + 00:01:20\&.000 + + A short chapter + eng + + + 00:00:46\&.000 + 00:01:10\&.000 + + A part of that short chapter + eng + + + + + + +.fi +.RE +.PP +With this format three things are possible that are not possible with the simple chapter format: +.sp +.RS 4 +\h'-04' 1.\h'+02'The timestamp for the end of the chapter can be set, +.RE +.sp +.RS 4 +\h'-04' 2.\h'+02'chapters can be nested, +.RE +.sp +.RS 4 +\h'-04' 3.\h'+02'the language and country can be set\&. +.RE +.PP +The mkvtoolnix distribution contains some sample files in the +\fIdoc\fR +subdirectory which can be used as a basis\&. +.SS "General notes" +.PP +When splitting files +\fBmkvmerge\fR(1) +will correctly adjust the chapters as well\&. This means that each file only includes the chapter entries that apply to it, and that the timecodes will be offset to match the new timecodes of each output file\&. +.PP + +\fBmkvmerge\fR(1) +is able to copy chapters from +Matroska(TM) +source files unless this is explicitly disabled with the +\fB\-\-no\-chapters\fR +option\&. The chapters from all sources (Matroska(TM) +files, Ogg files, +MP4 +files, chapter text files) are usually not merged but end up in separate +ChapterEditions\&. Only if chapters are read from several +Matroska(TM) +or +XML +files that share the same edition UIDs will chapters be merged into a single +ChapterEdition\&. If such a merge is desired in other situations as well then the user has to extract the chapters from all sources with +\fBmkvextract\fR(1) +first, merge the +XML +files manually and mux them afterwards\&. +.SH "TAGS" +.SS "Introduction" +.PP + +Matroska(TM) +supports an extensive set of tags that is deprecated and a new, simpler system like it is is used in most other containers: +\fIKEY=VALUE\fR\&. However, in +Matroska(TM) +these tags can also be nested, and both the +\fIKEY\fR +and the +\fIVALUE\fR +are elements of their own\&. The example file +\fIexample\-tags\-2\&.xml\fR +shows how to use this new system\&. +.SS "Scope of the tags" +.PP + +Matroska(TM) +tags do not automatically apply to the complete file\&. They can, but they also may apply to different parts of the file: to one or more tracks, to one or more chapters, or even to a combination of both\&. The +\fIthe Matroska(TM) specification\fR\&[3] +gives more details about this fact\&. +.PP +One important fact is that tags are linked to tracks or chapters with the +Targets +Matroska(TM) +tag element, and that the UIDs used for this linking are +\fInot\fR +the track IDs +\fBmkvmerge\fR(1) +uses everywhere\&. Instead the numbers used are the UIDs which +\fBmkvmerge\fR(1) +calculates automatically (if the track is taken from a file format other than +Matroska(TM)) or which are copied from the source file if the track\'s source file is a +Matroska(TM) +file\&. Therefore it is difficult to know which UIDs to use in the tag file before the file is handed over to +\fBmkvmerge\fR(1)\&. +.PP + +\fBmkvmerge\fR(1) +knows two options with which you can add tags to +Matroska(TM) +files: The +\fB\-\-global\-tags\fR +and the +\fB\-\-tags\fR +options\&. The difference is that the former option, +\fB\-\-global\-tags\fR, will make the tags apply to the complete file by removing any of those +Targets +elements mentioned above\&. The latter option, +\fB\-\-tags\fR, automatically inserts the UID that +\fBmkvmerge\fR(1) +generates for the tag specified with the +\fITID\fR +part of the +\fB\-\-tags\fR +option\&. +.SS "Example" +.PP +Let\'s say that you want to add tags to a video track read from an +AVI\&. +\fBmkvmerge \-\-identify file\&.avi\fR +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 +Targets +elements and call +\fBmkvmerge\fR(1): +.sp +.RS 4 +.nf +$ mkvmerge \-o file\&.mkv \-\-tags 0:tags\&.xml file\&.avi + +.fi +.RE +.SS "Tag file format" +.PP + +\fBmkvmerge\fR(1) +supports a +XML +based tag file format\&. The format is very closely modeled after +\fIthe Matroska(TM) specification\fR\&[3]\&. Both the binary and the source distributions of MkvToolNix come with a sample file called +\fIexample\-tags\-2\&.xml\fR +which simply lists all known tags and which can be used as a basis for real life tag files\&. +.PP +The basics are: +.sp +.RS 4 +\h'-04'\(bu\h'+03'The outermost element must be +\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'One logical tag is contained inside one pair of + +XML +tags\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'White spaces directly before and after tag contents are ignored\&. +.RE +.SS "Data types" +.PP +The new +Matroska(TM) +tagging system only knows two data types, a UTF\-8 string and a binary type\&. The first is used for the tag\'s name and the + +element while the binary type is used for the + +element\&. +.PP +As binary data itself would not fit into a +XML +file +\fBmkvmerge\fR(1) +supports two other methods of storing binary data\&. If the contents of a +XML +tag starts with \'@\' then the following text is treated as a file name\&. The corresponding file\'s content is copied into the +Matroska(TM) +element\&. +.PP +Otherwise the data is expected to be +Base64 +encoded\&. This is an encoding that transforms binary data into a limited set of +ASCII +characters and is used e\&.g\&. in email programs\&. +\fBmkvextract\fR(1) +will output +Base64 +encoded data for binary elements\&. +.PP +The deprecated tagging system knows some more data types which can be found in the official +Matroska(TM) +tag specs\&. As +\fBmkvmerge\fR(1) +does not support this system anymore these types aren\'t described here\&. +.SH "MATROSKA(TM) FILE LAYOUT" +.PP +The +Matroska(TM) +file layout is quite flexible\&. +\fBmkvmerge\fR(1) +will render a file in a predefined way\&. The resulting file looks like this: +.PP +[EBML head] [segment {meta seek #1} {attachments} {chapters} [segment information] [track information] [cluster 1] {cluster 2} \&.\&.\&. {cluster n} {cues} {meta seek #2} {tags}] +.PP +The elements in curly braces are optional and depend on the contents and options used\&. A couple of notes: +.sp +.RS 4 +\h'-04'\(bu\h'+03'meta seek #1 includes only a small number of level 1 elements, and only if they actually exist: attachments, chapters, cues, tags, meta seek #2\&. Older versions of +\fBmkvmerge\fR(1) +used to put the clusters into this meta seek element as well\&. Therefore some imprecise guessing was necessary to reserve enough space\&. It often failed\&. Now only the clusters are stored in meta seek #2, and meta seek #1 refers to the meta seek element #2\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'Attachment, chapter and tag elements are only present if they were added\&. +.RE +.PP +The shortest possible Matroska file would look like this: +.PP +[EBML head] [segment [segment information] [track information] [cluster 1]] +.PP +This might be the case for audio\-only files\&. +.SH "EXTERNAL TIMECODE FILES" +.PP + +\fBmkvmerge\fR(1) +allows the user to chose the timecodes for a specific track himself\&. This can be used in order to create files with variable frame rate video or include gaps in audio\&. A frame in this case is the unit that +\fBmkvmerge\fR(1) +creates separately per +Matroska(TM) +block\&. For video this is exactly one frame, for audio this is one packet of the specific audio type\&. E\&.g\&. for +AC3 +this would be a packet containing +\fB1536\fR +samples\&. +.PP +Timecode files that are used when tracks are appended to each other must only be specified for the first part in a chain of tracks\&. For example if you append two files, v1\&.avi and v2\&.avi, and want to use timecodes then your command line must look something like this: +.sp +.RS 4 +.nf +mkvmerge \&.\&.\&. \-\-timecodes 0:my_timecodes\&.txt v1\&.avi +v2\&.avi + +.fi +.RE +.PP +There are four formats that are recognized by +\fBmkvmerge\fR(1)\&. The first line always contains the version number\&. Empty lines, lines containing only whitespace and lines beginning with \'#\' are ignored\&. +.SS "Timecode file format v1" +.PP +This format starts with the version line\&. The second line declares the default number of frames per second\&. All following lines contain three numbers separated by commas: the start frame (\fB0\fR +is the first frame), the end frame and the number of frames in this range\&. The +FPS +is a floating point number with the dot \'\&.\' as the decimal point\&. The ranges can contain gaps for which the default +FPS +is used\&. An example: +.sp +.RS 4 +.nf +# timecode format v1 +assume 27\&.930 +800,1000,25 +1500,1700,30 + +.fi +.RE +.SS "Timecode file format v2" +.PP +In this format each line contains a timecode for the corresponding frame\&. This timecode must be given in millisecond precision\&. It can be a floating point number, but it doesn\'t have to be\&. You +\fIhave to\fR +give at least as many timecode lines as there are frames in the track\&. The timecodes in this file must be sorted\&. Example for 25fps: +.sp +.RS 4 +.nf +# timecode format v2 +0 +40 +80 + +.fi +.RE +.SS "Timecode file format v3" +.PP +In this format each line contains a duration in seconds followed by an optional number of frames per second\&. Both can be floating point numbers\&. If the number of frames per second is not present the default one is used\&. For audio you should let the codec calculate the frame timecodes itself\&. For that you should be using +\fB0\&.0\fR +as the number of frames per second\&. You can also create gaps in the stream by using the \'gap\' keyword followed by the duration of the gap\&. Example for an audio file: +.sp +.RS 4 +.nf +# timecode format v3 +assume 0\&.0 +25\&.325 +7\&.530,38\&.236 +gap, 10\&.050 +2\&.000,38\&.236 + +.fi +.RE +.SS "Timecode file format v4" +.PP +This format is identical to the v2 format\&. The only difference is that the timecodes do not have to be sorted\&. This format should almost never be used\&. +.SH "EXIT CODES" +.PP + +\fBmkvmerge\fR(1) +exits with one of three exit codes: +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB0\fR +\-\- This exit codes means that muxing has completed successfully\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB1\fR +\-\- In this case +\fBmkvmerge\fR(1) +has output at least one warning, but muxing did continue\&. A warning is prefixed with the text \'Warning:\'\&. Depending on the issues involved the resulting file might be ok or not\&. The user is urged to check both the warning and the resulting file\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03' +\fB2\fR +\-\- This exit code is used after an error occured\&. +\fBmkvmerge\fR(1) +aborts right after outputting the error message\&. Error messages range from wrong command line arguments over read/write errors to broken files\&. +.RE +.SH "SEE ALSO" +.PP + +\fBmkvinfo\fR(1), +\fBmkvextract\fR(1), +\fBmmg\fR(1) +.SH "WWW" +.PP +The latest version can always be found at +\fIthe MKVToolNix homepage\fR\&[4]\&. +.SH "AUTHOR" +.PP +\fBMoritz Bunkus\fR <\&moritz@bunkus\&.org\&> +.sp -1n +.IP "" 4 +Developer +.SH "NOTES" +.IP " 1." 4 +the Matroska(TM) website +.RS 4 +\%http://www.matroska.org/ +.RE +.IP " 2." 4 +the IANA homepage +.RS 4 +\%http://www.iana.org/assignments/media-types/ +.RE +.IP " 3." 4 +the Matroska(TM) specification +.RS 4 +\%http://matroska.org/technical/specs/index.html +.RE +.IP " 4." 4 +the MKVToolNix homepage +.RS 4 +\%http://www.bunkus.org/videotools/mkvtoolnix/ +.RE diff --git a/doc/man/mmg.1 b/doc/man/mmg.1 new file mode 100644 index 000000000..3c21b0f7a --- /dev/null +++ b/doc/man/mmg.1 @@ -0,0 +1,76 @@ +.\" Title: mmg +.\" Author: Moritz Bunkus +.\" Generator: DocBook XSL Stylesheets v1.73.2 +.\" Date: July 2009 +.\" Manual: User Commands +.\" Source: MkvToolNix 2.9.7 +.\" +.TH "MMG" "1" "July 2009" "MkvToolNix 2\&.9\&.7" "User Commands" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +mmg \- a GUI for mkvmerge1 including a chapter and a header editor +.SH "SYNOPSIS" +.HP 4 +\fBmmg\fR [[{\-\-edit\-headers}\ {filename\&.mkv}] | [preferences\-file\&.mmg] | [source\-file\&.ext]] +.SH "DESCRIPTION" +.PP + +\fBmmg\fR(1) +is a +wxWindows(TM) +based +GUI +for +\fBmkvmerge\fR(1)\&. It offers easy access to all of +\fBmkvmerge\fR(1)\'s options\&. All settings (e\&.g\&. source files, track options etc) can be saved and restored\&. Included is a chapter editor that can read +OGM +style and +XML +style chapter files, write +XML +style chapter files and even read chapters from +Matroska(TM) +files and write chapters directly to +Matroska(TM) +files\&. Included is also a header editor that can be used to quickly change properties of existing +Matroska(TM) +files without needing a complete remux\&. +.PP + +\fBmmg\fR(1) +knows few options\&. The first possibility is to start it with a single file name\&. If that file name\'s extenion is \'\&.mmg\' then it will be treated as a preferences file and +\fBmmg\fR(1) +will load its setting when it starts\&. Otherwise the name is interpreted as being the name of an input file which will be added\&. +.PP +The second operation mode is invoked with the option +\fB\-\-edit\-headers\fR +and a file name\&. This lets +\fBmmg\fR(1) +run its header editor and load the file\&. +.PP +The full documentation is available in HTML form (\fIdoc/mkvmerge\-gui\&.html\fR)\&. +.SH "SEE ALSO" +.PP + +\fBmkvmerge\fR(1), +\fBmkvextract\fR(1), +\fBmkvinfo\fR(1) +.SH "WWW" +.PP +The latest version can always be found at +\fIthe MKVToolNix homepage\fR\&[1]\&. +.SH "AUTHOR" +.PP +\fBMoritz Bunkus\fR <\&moritz@bunkus\&.org\&> +.sp -1n +.IP "" 4 +Developer +.SH "NOTES" +.IP " 1." 4 +the MKVToolNix homepage +.RS 4 +\%http://www.bunkus.org/videotools/mkvtoolnix/ +.RE diff --git a/doc/mkvextract.1 b/doc/mkvextract.1 deleted file mode 100644 index 2f05a62cf..000000000 --- a/doc/mkvextract.1 +++ /dev/null @@ -1,299 +0,0 @@ -.TH MKVEXTRACT "1" "July 2009" "mkvextract v2.9.7" "User Commands" - - -.SH NAME -mkvextract \- extract tracks from Matroska files into other files - - -.SH SYNOPSIS -.B mkvextract -tracks <\fIinname\fR> [\fIoptions\fR] [\fITID1\fR:\fIout1\fR [\fITID2\fR:\fIout2\fR ...]] -.br -.B mkvextract -tags <\fIinname\fR> [\fIoptions\fR] -.br -.B mkvextract -attachments <\fIinname\fR> [\fIoptions\fR] [\fIAID1\fR:\fI[out1]\fR [\fIAID2\fR:\fI[out2]\fR ...]] -.br -.B mkvextract -chapters <\fIinname\fR> [\fIoptions\fR] -.br -.B mkvextract -cuesheet <\fIinname\fR> [\fIoptions\fR] -.br -.B mkvextract -timecodes_v2 <\fIinname\fR> [\fITID1\fR:\fIout1\fR [\fITID2\fR:\fIout2\fR ...]] -.br -.B mkvextract -<\-h|\-V> - - -.SH DESCRIPTION -.LP -This program extracts specific parts from a Matroska file to other useful -formats. The first argument tells \fBmkvextract\fR what to extract. Currently -supported is the extraction of \fBtracks\fR, \fBtags\fR, \fBattachments\fR, -\fBchapters\fR, \fBCUE sheets\fR and \fBtimecodes\fR. -The second argument is the name of the source file. It must be a Matroska file. - -.LP -The following command line options are available for each track in the -\fBtracks\fR extraction mode. -They have to appear in front of the track specification (see below) they should -be applied to. -.TP -\fB\-c\fR \fIcharset\fR -Sets the charset to convert the next text subtitle track to. Only valid if the -next track ID targets a text subtitle track. It defaults to UTF-8. -.TP -\fB\-\-blockadd\fR \fIlevel\fR -Keep only the BlockAdditions up to this level. -The default is to keep all levels. -This option only affects certain kinds of codecs like WAVPACK4. -.TP -\fB\-\-cuesheet\fR -Causes \fBmkvextract\fR to extract a CUE sheet from the chapter information -and tag data for the following track into a file whose name is the track's -output name with ".cue" appended to it. -.TP -\fB\-\-fullraw\fR -Extracts the raw data into a file without any container data around it. -The contents of the CodecPrivate element will be written to the file first -if the track contains such a header element. -This mode works with all CodecIDs, even the ones that \fBmkvextract\fR doesn't -support otherwise, but the resulting files might not be usable. -.TP -\fB\-\-no\-ogg\fR -Only valid for FLAC tracks. Normally FLAC tracks are embedded in an Ogg -transport stream. With this switch they are extracted to raw FLAC files -instead. -.TP -\fB\-\-raw\fR -Extracts the raw data into a file without any container data around it. -Unlike the \fB\-\-fullraw\fR flag this flag does not cause the contents of -the CodecPrivate element to be written to the file. -This mode works with all CodecIDs, even the ones that \fBmkvextract\fR doesn't -support otherwise, but the resulting files might not be usable. -.TP -\fITID\fR:\fIoutname\fR -Causes extraction of the track with the ID \fITID\fR into the file -\fIoutname\fR if such a track exists in the source file. This option can be -given multiple times. The track IDs are the same as the ones output by -\fBmkvmerge\fR's \fB--identify\fR option. -.br -Each output name should be used only once. The exception are RealAudio and -RealVideo tracks. If you use the same name for different tracks then those -tracks will be saved in the same file. Example: -.br -\fBmkvextract tracks input.mkv 1:output-two-tracks.rm 2:output-two-tracks.rm\fR -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Be verbose and show all the important Matroska elements as they're read. - -.LP -Command line syntax for the \fBtags\fR extraction mode: -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Be verbose and show all the important Matroska elements as they're read. - -.LP -Command line syntax for the \fBattachments\fR extraction mode: -.TP -\fIAID\fR:\fIoutname\fR -Causes extraction of the attachment with the ID \fIAID\fR into the file -\fIoutname\fR if such an attachment exists in the source file. -If the \fIoutname\fR is left empty then the name of the attachment inside -the Matroska file is used instead. -This option can be given multiple times. -The attachment IDs are the same as the ones output by \fBmkvmerge\fR's -\fB--identify\fR option. -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Be verbose and show all the important Matroska elements as they're read. - -.LP -Command line syntax for the \fBchapters\fR extraction mode: -.TP -\fB\-s\fR, \fB\-\-simple\fR -Exports the chapter information in the simple format used in the OGM tools -(CHAPTER01=..., CHAPTER01NAME=...). In this mode some information has to be -discarded. Default is to output the chapters in XML format. -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Be verbose and show all the important Matroska elements as they're read. - -.LP -Command line syntax for the \fBcuesheet\fR extraction mode: -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Be verbose and show all the important Matroska elements as they're read. - -.LP -Command line syntax for the \fBtimecodes_v2\fR extraction mode: -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Be verbose and show all the important Matroska elements as they're read. - -.LP -If one of the following options is used as the only command line argument -additional information about \fBmkvextract\fR is output. -.TP -\fB\-h\fR, \fB\-\-help\fR -Show usage information. -.TP -\fB\-V\fR, \fB\-\-version\fR -Show version information. - -.LP -The following options can always be used no matter which mode has been -selected: -.TP -\fB\-\-output\-charset\fR <\fIcharset\fR> -Sets the charset to which strings are converted that are to be output. -It defaults to the charset given by system's current locale. -.TP -\fB-r\fR, \fB\-\-redirect\-output\fR <\fIfilename\fR> -Writes all messages to the file \fIfilename\fR 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 charset set with \fB\-\-output-charset\fR is honored. -.TP -\fB\-\-ui\-language\fR <\fIcode\fR> -Forces the translations for the language \fIcode\fR to be used (e.g. -\fIde_DE\fR for the German translations). If is preferable to use the -environment variables LANG, LC_MESSAGES and LC_ALL though. Entering "list" as -the \fIcode\fR will cause mkextract to output a list of available translations. - - -.SH NOTES -The decision about the output format is based on the track type, not on the -extension used for the output file name. The following track types are -supported at the moment: -.TP -V_MPEG4/ISO/AVC -H.264 / AVC video tracks are written to H.264 elementary streams which -can be processed further with e.g. MP4Box from the GPAC package. -.TP -V_MS/VFW/FOURCC -Fixed FPS video tracks with this CodecID are written to AVI files. -.TP -V_REAL/* -RealVideo tracks are written to RealMedia files. -.TP -A_MPEG/L3, A_AC3 -These will be extracted to raw MP3 and AC3 files. -.TP -A_PCM/INT/LIT -Raw PCM data will be written to a WAV file. -.TP -A_AAC/MPEG2/* -All MPEG2 AAC files will be written into an AAC file with ADTS headers before -each packet. -.TP -A_AAC/MPEG4/* -All MPEG4 AAC files will be written into an AAC file with ADTS headers before -each packet. The ADTS headers will not contain the deprecated emphasis field. -.TP -A_VORBIS -Vorbis audio will be written into an Ogg/Vorbis file. -.TP -A_REAL/* -RealAudio tracks are written to RealMedia files. -.TP -A_TTA1 -TrueAudio tracks are written to TTA files. Please note that due to Matroska's -limited timecode precision the extracted file's header will be different -regarding two fields: data_length (the total number of samples in the file) -and the CRC. -.TP -S_TEXT/UTF8 -Simple text subtitles will be written as SRT files. -.TP -S_TEXT/SSA, S_TEXT/ASS -SSA and ASS text subtitles will be written as SSA/ASS files respectively. -.TP -S_KATE -Kate streams will be written within an Ogg container. -.LP -\fBTags\fR are converted to a XML format. This format is the same that -\fBmkvmerge\fR supports for reading tags. -.LP -\fBAttachments\fR are written to they output file as they are. No conversion -whatsoever is done. -.LP -\fBChapters\fR are converted to a XML format. This format is the same that -\fBmkvmerge\fR supports for reading chapters. Alternatively a stripped-down -version can be output in the simple OGM style format. -.LP -\fBTimecodes\fR are first sorted and then output as a timecode v2 format -compliant file ready to be fed to mkvmerge. -The extraction to other formats (v1 and v3) is not supported. - -.SH EXAMPLES -Let's assume you've made a Matroska file with one video track, two audio tracks -and two subtitle tracks, and you need the second audio track and the first -subtitle track. So first fire up \fBmkvmerge\fR with the \fB--identify\fR -option: -.LP -$ \fBmkvmerge -i movie.mkv\fR -.br -File 'movie.mkv': container: Matroska -.br -Track ID 1: video (V_MS/VFW/FOURCC, DIV3) -.br -Track ID 2: audio (A_MPEG/L3) -.br -Track ID 3: audio (A_VORBIS) -.br -Track ID 4: subtitles (S_TEXT/UTF8) -.br -Track ID 5: subtitles (S_TEXT/UTF8) -.LP -Now you can call \fBmkvextract\fR like this: -.LP -$ \fBmkvextract tracks movie.mkv 3:audio.ogg 4:subtitles.srt\fR -.LP -Another example. Let's assume you have a Matroska file with one RealVideo v10 -track, one Vorbis audio track and one RealAudio (COOK) track. The -identification output might look like this: -.LP -$ \fB mkvmerge -i movie2.mkv\fR -.br -File 'movie2.mkv': container: Matroska -.br -Track ID 1: video (V_REAL/RV40) -.br -Track ID 2: audio (A_VORBIS) -.br -Track ID 3: audio (A_REAL/COOK) -.LP -Let's further assume you want only need the video and the RealAudio track but -both in the same output file. This is possible for RealMedia files by using -the same output name for those tracks that you want to end up in the same -file: -.LP -$ \fBmkvextract tracks movie2.mkv 1:extracted.rm 3:extracted.rm\fR -.LP -Sometimes you the raw data of a track might even be useful, e.g. for MPEG-1 -tracks. -In this case you can use a track flag like this: -.LP -$ \fBmkvextract tracks movie3.mkv --fullraw 1:extracted.mpeg\fR -.LP -If you need the timecodes for all the blocks of track 2 from a file then -you can let mkvextract create a timecode v2 format file like this: -.LP -$ \fBmkvextract timecodes_v2 input.mkv 2:timecodes-track2.txt\fR - -.SH AUTHOR -.I mkvextract -was written by Moritz Bunkus . -.SH SEE ALSO -.BR mkvmerge (1), -.BR mkvinfo (1) -.SH WWW -The newest version can always be found at -.UR http://www.bunkus.org/\:videotools/\:mkvtoolnix/ -www.bunkus.org -.UE diff --git a/doc/mkvinfo.1 b/doc/mkvinfo.1 deleted file mode 100644 index ee00172a7..000000000 --- a/doc/mkvinfo.1 +++ /dev/null @@ -1,91 +0,0 @@ -.TH MKVINFO "1" "July 2009" "mkvinfo v2.9.7" "User Commands" -.SH NAME -mkvinfo \- Print information about tracks in Matroska files -.SH SYNOPSIS -.B mkvinfo -[\fIoptions\fR] \fIinname\fR -.SH DESCRIPTION -.LP -This program lists all tracks contained in a Matroska file including -information about the codecs used. -.TP -inname -Use '\fIinname\fR' as the source. -.TP -\fB\-g\fR, \fB\-\-gui\fR -Start the GUI. This option is only available if mkvinfo was compiled with -GUI support. -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Be verbose and show all Matroska elements. See the section -\'\fBVERBOSITY LEVELS\fR' for details. -.TP -\fB\-c\fR, \fB\-\-checksums\fR -Calculates and display the Adler32 checksum for each frame. Useful for -debugging only. -.TP -\fB\-s\fR, \fB\-\-summary\fR -Only show a terse summary of what \fBmkvinfo\fR finds and not each element. -.TP -\fB\-\-output\-charset\fR <\fIcharset\fR> -Sets the charset to which strings are converted that are to be output. -It defaults to the charset given by system's current locale. -.TP -\fB-r\fR, \fB\-\-redirect\-output\fR <\fIfilename\fR> -Writes all messages to the file \fIfilename\fR 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 charset set with \fB\-\-output-charset\fR is honored. -.TP -\fB\-\-ui\-language\fR <\fIcode\fR> -Forces the translations for the language \fIcode\fR to be used (e.g. -\fIde_DE\fR for the German translations). If is preferable to use the -environment variables LANG, LC_MESSAGES and LC_ALL though. Entering "list" as -the \fIcode\fR will cause mkvinfo to output a list of available translations. -.TP -\fB\-h\fR, \fB\-\-help\fR -Show usage information. -.TP -\fB\-V\fR, \fB\-\-version\fR -Show version information. -.SH VERBOSITY LEVELS -.LP -The \fB-v\fR option can be used to increase \fBmkvinfo\fR's verbosity level -and print more information about the current file. -.TP -level 0 -will print only the track headers it finds and their types. \fBmkvinfo\fR -will exit as soon as the headers are parsed completely (more technical: -as soon as the first cluster is encountered). In this level the seek head -entries and the cues will not be displayed - even if they're located in -front of the track information. -.TP -level 1 -will also print all Matroska elements encountered for the complete file but -the seek head entries and the cue entries. If the summary mode is enabled -then \fBmkvinfo\fR will output the frame position as well. -.TP -level 2 -will also print the seek head entries, the cue entries and the file position -at which each Matroska element can be found at. -.TP -level 3 -will print some information that is not directly connected to a Matroska -element. All other elements only print stuff about the elements that were -just found. Level 3 adds meta information to ease debugging (read: it's -intended for developers only). All lines written by level 3 are enclosed -in square brackets to make filtering them out easy. -.LP -.SH AUTHOR -.I mkvinfo -was written by Moritz Bunkus . -.SH SEE ALSO -.BR mkvmerge (1), -.BR mkvextract (1), -.BR mmg (1) -.SH WWW -The newest version can always be found at -.UR http://www.bunkus.org/\:videotools/\:mkvtoolnix/ -www.bunkus.org -.UE diff --git a/doc/mkvmerge.1 b/doc/mkvmerge.1 deleted file mode 100644 index 2ed6638c7..000000000 --- a/doc/mkvmerge.1 +++ /dev/null @@ -1,1343 +0,0 @@ -.TH MKVMERGE "1" "July 2009" "mkvmerge v2.9.7" "User Commands" - - -.SH NAME -mkvmerge \- Merge multimedia streams into a Matroska file - - -.SH SYNOPSIS -.B mkvmerge -[\fIglobal options\fR] \-o \fIout\fR [\fIoptions1\fR] [[\fIoptions2\fR] ...] [@optionsfile] - - -.SH DESCRIPTION -.LP -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 -.UR http://www.\:matroska.\:org/ -www.matroska.org -.UE - -.LP -Global options: -.TP -\fB\-v\fR, \fB\-\-verbose\fR -Increase verbosity. -.TP -\fB\-q\fR, \fB\-\-quiet\fR -Suppress status output. -.TP -\fB\-o\fR, \fB\-\-output\fR \fIout\fR -Write to the file '\fIout\fR'. -If splitting is used then this parameter is treated a bit differently. -See the \fB\-\-split\fR parameter discussion for details. -.TP -\fB\-\-title\fR <\fItitle\fR> -Sets the general title for the output file, e.g. the movie name. -.TP -\fB\-\-global\-tags\fR <\fIfile\fR> -Read global tags from the XML \fIfile\fR. See the section about tags -below for details. -.TP -\fB\-\-default\-language\fR <\fIlng\fR> -Sets the default language code. Unless overridden with the \fB\-\-language\fR -option this language code will be used. The default language code is 'und' -for 'undefined'. - -.LP -Chapter handling: (global options) -.TP -\fB\-\-chapter\-language\fR <\fIlanguage\fR> -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. -.TP -\fB\-\-chapter\-charset\fR <\fIcharset\fR> -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. -.TP -\fB\-\-cue\-chapter\-name\-format\fR <\fIformat\fR> -\fBmkvmerge\fR supports reading CUE sheets for audio files as the input for -chapters. CUE sheets usually contain the entries \fIPERFORMER\fR and -\fITITLE\fR for each index entry. \fBmkvmerge\fR uses these two strings -in order to construct the chapter name. With this option the format used -for this name can be set. The following meta characters are supported: -.br -\fB%p\fR is replaced by the current entry's \fIPERFORMER\fR string, -.br -\fB%t\fR is replaced by the current entry's \fITITLE\fR string, -.br -\fB%n\fR is replaced by the current track number and -.br -\fB%N\fR is replaced by the current track number padded with a leading zero if -it is < 10. -.br -Everything else is copied as-is. -.br -If this option is not given then \fBmkvmerge\fR defaults to the -format '\fI%p - %t\fR' (the performer, followed by a space, a dash, -another space and the title). -.TP -\fB\-\-chapters <\fIfile\fR> -Read chapter information from the \fIfile\fR. See the section about chapters -below for details. - -.LP -General output control (advanced global options): -.TP -\fB\-\-track\-order\fR <\fIFID1:TID1\fR[,\fIFID2:TID2\fR,...]> -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. -.TP -\fB\-\-cluster\-length \fR \fIn[ms]\fR -Put at most \fIn\fR data blocks into each cluster. If the number is -postfixed with 'ms' then put at most \fIn\fR milliseconds of data into -each cluster. The maximum length for a cluster that \fBmkvmerge\fR 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. -.TP -\fB\-\-no\-cues\fR -Tells \fBmkvmerge\fR 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 -\fB\-\-cues\fR which can be specified for each input file. -.TP -\fB\-\-no\-clusters\-in\-meta\-seek\fR -Tells \fBmkvmerge\fR not to create a meta seek element at the end of the file -containing all clusters. See also the section about \fBMATROSKA FILE LAYOUT\fR. -.TP -\fB\-\-disable\-lacing\fR -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. -.TP -\fB\-\-enable\-durations\fR -Write durations for all blocks. This will increase file size and does not -offer any additional value for players at the moment. -.TP -\fB\-\-timecode\-scale\fR <\fIn\fR> -Forces the timecode scale factor to \fIn\fR. -Valid values are in the range 1000..10000000 or the value -1. -Normally \fBmkvmerge\fR 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 \fBmkvmerge\fR will automatically chose a timecode scale factor so -that all timecodes and durations have a precision of one sample. -This causes bigger overhead but allows precise seeking and extraction. -If the magical value -1 is used then \fBmkvmerge\fR will use sample precision -even if a video track is present. - -.LP -File splitting and linking (more global options): -.TP -\fB\-\-split\fR size:<\fId[k|m|g]\fR> or shorter \fB\-\-split\fR <\fId[k|m|g]\fR> -.TP -\fB\-\-split\fR duration:<\fIHH:MM:SS.nnnnnnnnn\fR|\fIn\fRs> or shorter \fB\-\-split\fR <\fIHH:MM:SS.nnnnnnnnn\fR|\fIn\fRs> -.TP -\fB\-\-split\fR timecodes:\fIA\fR[,\fIB\fR[,\fIC\fR...]] -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 \fBmkvmerge\fR 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. -.br -At the moment \fBmkvmerge\fR supports three different modes. -.br -1. Splitting by size. -.br -The parameter \fId\fR may end with \fBk\fR, \fBm\fR or \fBg\fR 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 \fBsize:\fR prefix may be omitted for compatibility reasons. -.br -2. Splitting after a duration. -.br -The paramter must have the form \fIHH:MM:SS.nnnnnnnnn\fR for specifying the -duration in up to nano-second precision or a number \fIn\fR 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 \fBduration:\fR prefix may be omitted for compatibility reasons. -.br -3. Splitting after specific timecodes. -.br -The parameters \fIA\fR, \fIB\fR 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 \fRtimecodes:\fR prefix must not be omitted. -.br -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. -.TP -\fB\-\-split\-max\-files\fR <\fIn\fR> -Create at most \fIn\fR files, even if the last file will be longer or larger -than indicated by the \fB\-\-split\fR option. -.TP -\fB\-\-link\fR -Link files to one another when splitting the output file. See the -section \fBFILE LINKING\fR below for details. -.TP -\fB\-\-link\-to\-previous\fR <\fISID\fR> -Links the first output file to the segment with the given \fISID\fR. See the -section \fBFILE LINKING\fR below for details. -.TP -\fB\-\-link\-to\-next\fR <\fISID\fR> -Links the last output file to the segment with the given \fISID\fR. See the -section \fBFILE LINKING\fR below for details. - -.LP -Attachment support (more global options): -.TP -\fB\-\-attachment\-description\fR <\fIdescription\fR> -Plain text description of the following attachment. Applies to the next -\fB\-\-attach\-file\fR or \fB\-\-attach\-file\-once\fR command. -.TP -\fB\-\-attachment\-mime\-type\fR <\fIMIME type\fR> -MIME type of the following attachment. Applies to the next -\fB\-\-attach\-file\fR or \fB\-\-attach\-file\-once\fR command. -A list of officially recognized MIME types can be found e.g. at -.UR http://www.iana.org/\:assignments/\:media-types/ -www.iana.org -.UE -The MIME type is mandatory for an attachment. -.TP -\fB\-\-attachment\-name\fR <\fIname\fR> -Sets the name that will be stored in the output file for this attachment. -If this option is not given then the name will be derived from the -file name of the attachment as given with the \fB\-\-attach\-file\fR or -the \fB\-\-attach\-file\-once\fR option. -.TP -\fB\-\-attach\-file\fR <\fIfile name\fR> -.TP -\fB\-\-attach\-file\-once\fR <\fIfile name\fR> -Creates a file attachment inside the Matroska file. The MIME type must have -been set before this option can used. The difference between the two forms -is that during splitting the files attached with \fB\-\-attach\-file\fR are -attached to all output files while the ones attached with -\fB\-\-attach\-file\-once\fR are only attached to the first file created. -If splitting is not used then both do the same. -.br -\fBmkvextract\fR can be used to extract attached files from a Matroska file. - - -.LP -Options that can be used for each input file: -.TP -\fB\-a\fR, \fB\-\-audio\-tracks\fR <\fIn\fR,\fIm\fR,...> -Copy the audio tracks \fIn\fR, \fIm\fR etc. The numbers are track IDs which -can be obtained with the \fB\-\-identify\fR switch. They're \fBnot\fR simply -the track numbers (see section \fBTRACK IDS\fR). Default: copy all audio -tracks. -.TP -\fB\-d\fR, \fB\-\-video\-tracks\fR <\fIn\fR,\fIm\fR,...> -Copy the video tracks \fIn\fR, \fIm\fR etc. The numbers are track IDs which -can be obtained with the \fB\-\-identify\fR switch (see -section \fBTRACK IDS\fR). They're \fBnot\fR simply -the track numbers. Default: copy all video tracks. -.TP -\fB\-s\fR, \fB\-\-subtitle\-tracks\fR <\fIn\fR,\fIm\fR,...> -Copy the subtitle tracks \fIn\fR, \fIm\fR etc. The numbers are track IDs which -can be obtained with the \fB\-\-identify\fR switch (see -section \fBTRACK IDS\fR). They're \fBnot\fR simply -the track numbers. Default: copy all subtitle tracks. -.TP -\fB\-b\fR, \fB\-\-button\-tracks\fR <\fIn\fR,\fIm\fR,...> -Copy the button tracks \fIn\fR, \fIm\fR etc. -The numbers are track IDs which can be obtained with the \fB\-\-identify\fR -switch (see section \fBTRACK IDS\fR). -They're \fBnot\fR simply the track numbers. -Default: copy all button tracks. -.TP -\fB\-\-tracks\-tags\fR <\fIn\fR,\fIm\fR,...> -Copy the tags for tracks \fIn\fR, \fIm\fR etc. -The numbers are track IDs which can be obtained with the \fB\-\-identify\fR -switch (see section \fBTRACK IDS\fR). -They're \fBnot\fR simply the track numbers. -Default: copy tags for all tracks. -.TP -\fB\-A\fR, \fB\-\-no-audio\fR -Don't copy any audio track from this file. -.TP -\fB\-D\fR, \fB\-\-no-video\fR -Don't copy any video track from this file. -.TP -\fB\-S\fR, \fB\-\-no-subtitles\fR -Don't copy any subtitle track from this file. -.TP -\fB\-B\fR, \fB\-\-no-buttons\fR -Don't copy any button track from this file. -.TP -\fB\-T\fR, \fB\-\-no\-track\-tags\fR -Don't copy any track specific tags from this file. -.TP -\fB\-\-no\-chapters\fR -Don't copy chapters from this file. -.TP -\fB\-\-no\-attachments\fR -Don't copy attachments from this file. -.TP -\fB\-\-no\-global\-tags\fR -Don't copy global tags from this file. -.TP -\fB\-\-chapter\-charset\fR <\fIcharset\fR> -Sets the charset that is used for the conversion to UTF-8 for chapter information -contained in the source file. -.TP -\fB\-\-chapter\-language\fR <\fIlanguage\fR> -Sets the ISO639-2 language code that is written for each chapter entry. -This option can be used for source files that contain chapters but no information -about the chapters' languages, e.g. for MP4 and OGM files. -.TP -\fB\-y\fR, \fB\-\-sync\fR <\fITID\fR:\fId\fR[,\fIo\fR[/\fIp\fR]]> -Adjust the timecodes of the track with the id \fITID\fR by \fId\fR -ms. The track IDs are the same as the ones given with \fB\-\-identify\fR (see -section \fBTRACK IDS\fR). -.br -\fIo\fR/\fIp\fR: adjust the timestamps by \fIo\fR/\fIp\fR to fix -linear drifts. \fIp\fR defaults to 1 if omitted. Both \fIo\fR and -\fIp\fR can be floating point numbers. -.br -Defaults: no manual sync correction (which is the same as \fId\fR = 0 and -\fIo\fR/\fIp\fR = 1.0). -.br -This option can be used multiple times for an input file applying to several -tracks by selecting different track IDs each time. -.TP -\fB\-\-cues\fR <\fITID\fR:\fInone\fR|\fIiframes\fR|\fIall\fR> -Controls for which tracks cue (index) entries are created for the given track -(see section \fBTRACK IDS\fR). \fInone\fR inhibits the creation of cue entries. -For \fIiframes\fR only blocks with no backward or forward -references ( = I frames in video tracks) are put into the cue sheet. \fIall\fR -causes \fBmkvmerge\fR to create cue entries for all blocks which will make -the file very big. -.br -The default is \fIiframes\fR for video tracks and \fInone\fR for all others. -See also option \fB\-\-no\-cues\fR which inhibits the creation of cue -entries regardless of the \fB\-\-cues\fR options used. -.br -This option can be used multiple times for an input file applying to several -tracks by selecting different track IDs each time. -.TP -\fB\-\-default\-track\fR <\fITID[:bool]\fR> -Sets the 'default' flag for the given track (see section \fBTRACK IDS\fR) -if the optional argument \fIbool\fR is not present. -If the user does not explicitly select a track himself then the player should -prefer the track that has his 'default' flag set. Only one track of each kind -(audio, video, subtitles, buttons) can have his 'default' flag set. -If the user wants no track to have the default track flag set then he has to -set \fIbool\fR to \fI0\fR for all tracks. -.br -This option can be used multiple times for an input file applying to several -tracks by selecting different track IDs each time. -.TP -\fB\-\-blockadd\fR <\fITID\fR:\fIlevel\fR> -Keep only the BlockAdditions up to this \fIlevel\fR for the given track. -The default is to keep all levels. -This option only affects certain kinds of codecs like WAVPACK4. -.TP -\fB\-\-track\-name\fR <\fITID\fR:\fIname\fR> -Sets the track name for the given track (see section \fBTRACK IDS\fR) to -\fIname\fR. -.TP -\fB\-\-language\fR <\fITID\fR:\fIlanguage\fR> -Sets the language for the given track (see section \fBTRACK IDS\fR). Both -ISO639-2 language codes and ISO639-1 country codes are allowed. The country -codes will be converted to language codes automatically. -All languages including their ISO639-2 codes can be -listed with the \fB\-\-list\-languages\fR option. -.br -This option can be used multiple times for an input file applying to several -tracks by selecting different track IDs each time. -.TP -\fB\-t\fR, \fB\-\-tags\fR <\fITID\fR:\fIfile\fR> -Read tags for the track with the number \fITID\fR from the \fIfile\fR. See -the section about tags below for details. -.TP -\fB\-\-aac\-is\-sbr\fR <\fITID[:0|1]\fR> -Tells \fBmkvmerge\fR that the track with the ID \fITID\fR is SBR AAC (also -known as HE-AAC or AAC+). This options is needed if a) the source file is an -AAC file (NOT for a Matroska file) and b) the AAC file contains SBR AAC data. -The reason for this switch is that it is technically impossible to -automatically tell normal AAC data from SBR AAC data without decoding a -complete AAC frame. As there are several patent issues with AAC decoders I -won't implement this decoding stage. So for SBR AAC files this switch is -mandatory. The resulting file might not play back correctly or even not at -all if the switch was omitted. -.br -If the source file is a Matroska file then the CodecID should be enough to -detect SBR AAC. However, if the CodecID is wrong then this switch can be used -to correct that. -.br -If mkvmerge wrongfully detects that an AAC file is SBR then you can add -":0" to the track ID. -.TP -\fB\-\-timecodes\fR <\fITID\fR:\fIfilename\fR> -Read the timecodes to be used for the specific track ID from \fIfilename\fR. -These timecodes forcefully override the timecodes that \fBmkvmerge\fR -normally calculates. Read the section about \fBEXTERNAL TIMECODE FILES\fR. -.TP -\fB\-\-default\-duration\fR <\fITID\fR:\fIx\fR> -Forces the default duration of a given track to the specified value. -Also modifies the track's timecodes to match the default duration. -The argument \fIx\fR must be postfixed with \fBs\fR, \fBms\fR, \fBus\fR, -\fBns\fR or \fBfps\fR to specify the default duration in seconds, milliseconds, -microseconds, nanoseconds or "frames per second" respectively. -The number \fIx\fR itself can be a floating point number or a fraction. -.br -If the default duration is not forced then mkvmerge will try to derive the -track's default duration from the container and/or codec used. -One case in which this option is of use is when adding AVC/h.264 -elementary streams because these do not contain information about their -number of frames or a default duration for each frame. -For such files \fBmkvmerge\fR will assume a default duration of 25fps -unless overridden. -.br -This option can also be used to change the FPS of video tracks without -having to use an external timecode file. -.TP -\fB\-\-nalu\-size\-length\fR <\fITID\fR:\fIn\fR> -Forces the NALU size length to \fIn\fR bytes. -This parameter is only used if the AVC/h.264 elementary stream packetizer -is used. -If left out it defaults to 2 bytes, but there are files that contain frames or -slices that are bigger than 65535 bytes. -For such files you have to use this parameter and increase the size to 3 or -\fBmkvmerge\fR will abort with an error. -.TP -\fB\-\-append\-mode\fR <\fImode\fR> -Determines how timecodes are calculated when appending files. -The parameter \fImode\fR can have two values: \fIfile\fR which is also -the default and \fItrack\fR. -.br -When mkvmerge appends a track (called \fItrack2_1\fR from now on) from -a second file (called \fIfile2\fR) to a track (called \fItrack1_1\fR) -from the first file (called \fIfile1\fR) then it has to offset all -timecodes for \fItrack2_1\fR by an amount. For \fIfile\fR mode this -amount is the highest timecode encountered in \fIfile1\fR even if that -timecode was from a different track than \fItrack1_1\fR. In -\fRtrack\fR mode the offset is the highest timecode of \fItrack1_1\fR. -.br -Unfortunately mkvmerge cannot detect which mode to use -reliably. Therefore it defaults \fIfile\fR mode. \fIfile\fR mode -usually works better for files that have been created independently of -each other; e.g. when appending AVI or MP4 files. \fItrack\fR mode may -work better for sources that are essentially just parts of one big -file, e.g. for VOB and EVO files. -.br -Subtitle tracks are always treated as if \fIfile\fR mode were active -even if \fItrack\fR mode actually is. -.TP -\fB\-\-append\-to\fR <\fISFID1:STID1:DFID1:DTID1\fR[,...]> -This option controls to which track another track is appended. -Each spec contains four IDs: a file ID, a track ID, another file ID and -a second track ID. -The first pair, "source file ID" and "source track ID", identifies the track -that is to be appended. -The second pair, "destination file ID" and "destination track ID", identifies -the track the first one is appended to. -.br -If this option has been omitted then a standard mapping is used. -This standard mapping appends each track from the current file to a track -from the previous file with the same track ID. -This allows for easy appending if a movie has been split into two parts -and both file have the same number of tracks and track IDs with the -command -.br -\fBmkvmerge -o output.mkv part1.mkv +part2.mkv\fR - -.LP -Options that only apply to video tracks: -.TP -\fB\-f\fR, \fB\-\-fourcc\fR <\fITID\fR:\fIFourCC\fR> -Forces the FourCC to the specified value. Works only for video tracks in the -\'MS compatibility mode'. -.TP -\fB\-\-display\-dimensions\fR <\fITID\fR:\fIwidth\fRx\fIheight\fR> -Matroska files contain two values that set the display properties that a -player should scale the image on playback to: display width and display height. -These values can be set with this option, e.g. '1:640x480'. -.br -Another way to specify the values is to use the -\fB\-\-aspect\-ratio\fR or the \fB\-\-aspect\-ratio\-factor\fR -option (see below). -These options are mutually exclusive. -.TP -\fB\-\-aspect\-ratio\fR <\fITID\fR:\fIar\fR|\fIw\fR/\fIh\fR> -Matroska files contain two values that set the display properties that -a player should scale the image on playback to: display width and -display height. With this option \fBmkvmerge\fR will automatically -calculate the display width and display height based on the image's -original width and height and the aspect ratio given with this option. -The ratio can be given either as a floating point number or as -\'width/height', e.g. 16/9. -.TP -\fB\-\-aspect\-ratio\-factor\fR <\fITID\fR:\fIar\fR|\fIw\fR/\fIh\fR> -Another way to set the aspect ratio is to specify a factor. The original -aspect ratio is first multiplied with this factor and used as the target -aspect ratio afterwards. -.br -Another way to specify the values is to use the -\fB\-\-aspect\-ratio\fR option (see above). These options are mutually -exclusive. -.TP -\fB\-\-cropping\fR <\fITID\fR:\fIleft\fR,\fItop\fR,\fIright\fR,\fIbottom\fR> -Sets the pixel cropping parameters of a video track to the given values. -.TP -\fB\-\-stereo\-mode\fR <\fITID\fR:\fIn\fR|\fIkeyword\fR> -Sets the stereo mode for the video track with the track ID \fITID\fR. -The mode can either be a number \fIn\fR between 0 and 3 or one of the -keywords \fInone\fR (same as n=0), \fIright\fR (same as n=1), \fIleft\fR -(same as n=2) or \fIboth\fR (same as n=3). -.LP -Options that only apply to text subtitle tracks: -.TP -\fB\-\-sub\-charset\fR <\fITID\fR:\fIcharset\fR> -Sets the charset for the conversion to UTF-8 for UTF-8 subtitles for the given -track ID. If not specified the charset will be derived from the current locale -settings. Note that a charset is not needed for subtitles read from Matroska -files or from Kate streams, as these are always stored in UTF-8. -.br -This option can be used multiple times for an input file applying to several -tracks by selecting different track IDs each time. -.LP -Options that only apply to VobSub subtitle tracks: -.TP -\fB\-\-compression\fR <\fITID\fR:\fImethod\fR> -Selects the compression method to be used for the VobSub track. Note that the -player also has to support this method! Valid values are 'none' and 'zlib'. -The default is 'zlib' compression. -.LP -Other options: -.TP -\fB\-i\fR, \fB\-\-identify\fR <\fIfilename\fR> -Will let \fBmkvmerge\fR probe the single file and report its type, the tracks -contained in the file and their track IDs. If this option is used then the -only other option allowed is the filename. -.TP -\fB\-l\fR, \fB\-\-list\-types\fR -Lists supported input file types. -.TP -\fB\-\-list\-languages\fR -Lists all languages and their ISO639-2 code which can be used with the -\fB\-\-language\fR option. -.TP -\fB\-\-priority\fR <\fIpriority\fR> -Sets the process priority that \fBmkvmerge\fR runs with. Valid values are -"lowest", "lower", "normal", "higher" and "highest". If nothing is given then -"normal" is used. On Unix like systems \fBmkvmerge\fR will use the nice(2) -function. Therefore only the super user can use "higher" and "highest". On -Windows all values are useable for every user. -.TP -\fB\-\-command\-line\-charset\fR <\fIcharset\fR> -Sets the charset to convert strings given on the command line from. It defaults -to the charset given by system's current locale. This settings applies to -arguments of the following options: \fB\-\-title\fR, \fB\-\-track\-name\fR and -\fB\-\-attachment\-description\fR. -.TP -\fB\-\-output\-charset\fR <\fIcharset\fR> -Sets the charset to which strings are converted that are to be output. -It defaults to the charset given by system's current locale. -.TP -\fB-r\fR, \fB\-\-redirect\-output\fR <\fIfilename\fR> -Writes all messages to the file \fIfilename\fR 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 charset set with \fB\-\-output-charset\fR is honored. -.TP -\fB\-\-ui\-language\fR <\fIcode\fR> -Forces the translations for the language \fIcode\fR to be used (e.g. -\fIde_DE\fR for the German translations). If is preferable to use the -environment variables LANG, LC_MESSAGES and LC_ALL though. Entering "list" as -the \fIcode\fR will cause mkvmerge to output a list of available translations. -.TP -\fB@\fR\fIoptionsfile\fR -Reads additional command line arguments from the file \fIoptionsfile\fR. -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. -.br -The command line \fBmkvmerge \-o "my file.mkv" -A "a movie.avi" sound.ogg\fR -could be converted into the following option file: -.br -# Write to the file "my file.mkv". -.br -\-o -.br -my file.mkv -.br -# Only take the video from "a movie.avi". -.br -\-A -.br -a movie.avi -.br -sound.ogg -.TP -\fB\-h\fR, \fB\-\-help\fR -Show usage information. -.TP -\fB\-V\fR, \fB\-\-version\fR -Show version information. - - -.SH USAGE -.LP -For each file the user can select which tracks \fBmkvmerge\fR should take. -They are all put into the file specified with '-o'. A list of known -(and supported) source formats can be obtained with the '-l' option. - - -.SH EXAMPLES -.LP -Let's assume you have a file called \fIMyMovie.avi\fP and the audio track in a -separate file, e.g. \fIMyMovie.wav\fP. First you want to encode the audio to -OGG: -.LP -$ \fBoggenc -q4 -oMyMovie.ogg MyMovie.wav\fP -.LP -After a couple of minutes you can join video and audio: -.LP -$ \fBmkvmerge -o MyMovie-with-sound.mkv MyMovie.avi MyMovie.ogg\fP -.LP -If your AVI already contains an audio track then it will be copied as well -(if \fBmkvmerge\fR supports the audio format). To avoid that simply do -.LP -$ \fBmkvmerge -o MyMovie-with-sound.mkv -A MyMovie.avi MyMovie.ogg\fP -.LP -After some minutes of consideration you rip another audio track, e.g. -the director's comments or another language to \fIMyMovie-add-audio.wav\fP. -Encode it again and join it up with the other file: -.LP -$ \fBoggenc -q4 -oMyMovie-add-audio.ogg MyMovie-add-audio.wav\fP -.br -$ \fBmkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-audio.ogg\fP -.LP -The same result can be achieved with -.LP -$ \fBmkvmerge -o MM-complete.mkv -A MyMovie.avi MyMovie.ogg \\\fP -.br - \fBMyMovie-add-audio.ogg\fP -.LP -Now fire up mplayer and enjoy. If you have multiple audio tracks (or even -video tracks) then you can tell mplayer which track to play with the -\&'\fB-vid\fP' and '\fB-aid\fP' parameters. These are 0-based and do not -distinguish between video and audio. -.LP -If you need an audio track synchronized you can do that easily. First find -out which track ID the Vorbis track has with -.LP -$ \fBmkvmerge --identify outofsync.ogg\fP -.LP -Now you can use that ID in the following command line: -.LP -$ \fBmkvmerge -o goodsync.mkv -A source.avi -y 12345:200 outofsync.ogg\fP -.LP -This would add 200ms of silence at the beginning of the audio track with the -ID 12345 taken from \fIoutofsync.ogg\fP. -.LP -Some movies start synced correctly but slowly drift out of sync. For these -kind of movies you can specify a delay factor that is applied to all -timestamps - no data is added or removed. So if you make that factor too -big or too small you'll get bad results. An example is that an episode -I transcoded was 0.2 seconds out of sync at the end of the movie which -was 77340 frames long. At 29.97fps 0.2 seconds correspond to approx. 6 -frames. So I did -.LP -$ \fBmkvmerge -o goodsync.mkv -y 23456:0,77346/77340 outofsync.mkv\fP -.LP -The result was fine. -.LP -The sync options can also be used for subtitles in the same manner. -.LP -For text subtitles you can either use some Windows software (like -\fBSubRipper\fR) or the \fBsubrip\fR package found in \fBtranscode(1)\fR's -sources (in \fBcontrib/subrip\fR). The general process is: -.TP -1. -extract a raw subtitle stream from the source: -.br -$ \fBtccat -i /path/to/copied/dvd/ -T 1 -L | \\ -.br - tcextract -x ps1 -t vob -a 0x20 | \\ -.br - subtitle2pgm -o mymovie\fP -.TP -2. -convert the resulting PGM images to text with \fBgocr\fP: -.br -$ \fBpgm2txt mymovie\fP -.TP -3. -spell-check the resulting text files: -.br -$ \fBispell -d american *txt\fP -.TP -4. -convert the text files to a SRT file: -.br -$ \fBsrttool -s -w -i mymovie.srtx -o mymovie.srt\fP -.LP -The resulting file can be used as another input file for \fBmkvmerge\fR: -.LP -$ \fBmkvmerge -o mymovie.mkv mymovie.avi mymovie.srt\fP -.LP -If you want to specify the language for a given track then this is easily -done. First find out the ISO639-2 code for your language. \fBmkvmerge\fR -can list all of those codes for you: -.LP -$ \fBmkvmerge --list-languages\fR -.LP -Search the list for the languages you need. Let's assume you have put two -audio tracks into a Matroska file and want to set their language codes and -that their track IDs are 2 and 3. This can be done with -.LP -$ \fBmkvmerge -o with-lang-codes.mkv --language 2:ger --language 3:dut -without-lang-codes.mkv\fR -.LP -As you can see you can use the \fB--language\fR switch multiple times. -.LP -Maybe you'd also like to have the player use the Dutch language as the default -language. You also have extra subtitles, e.g. in English and French, and want -to have the player display the French ones by default. This can be done with -.LP -$ \fBmkvmerge -o with-lang-codes.mkv --language 2:ger --language 3:dut ---default-track 3 without-lang-codes.mkv --language 0:eng english.srt ---default-track 0 --language 0:fre french.srt\fR -.LP -If you do not see the language or default track flags that you've specified -in \fBmkvinfo\fR's output then please read the section about \fBDEFAULT -VALUES\fR. - - -.SH TRACK IDS -.LP -Some of the options for \fBmkvmerge\fR need a track ID to specify which track -they should be applied to. -Those track IDs are printed by the readers when demuxing the current input -file, or if \fBmkvmerge\fR is called with the \fB\-\-identify\fR option. -An example for such output: -.LP -$ \fBmkvmerge -i v.mkv\fR -.br -File 'v.mkv': container: Matroska -.br -Track ID 1: video (V_MS/VFW/FOURCC, DIV3) -.br -Track ID 2: audio (A_MPEG/L3) -.LP -Track IDs are assigned like this: -.TP -* -AVI files: The video track has the ID 0. All audio tracks get the ID 1, 2... -.TP -* -AAC, AC3, MP3, SRT and WAV files: The one 'track' in that file gets the ID 0. -.TP -* -Ogg/OGM files: The track's ID is its position in the Ogg stream. -The first stream encountered has the ID 0, the second one the ID 1 etc. -.TP -* -Matroska files: The track's ID is the track number as reported by \fBmkvinfo\fR -or \fBmkvmerge \-\-identify\fR. It is \fBnot\fR the track UID. -.LP -The special track ID '-1' is a wild card and applies the given switch to all -tracks that are read from an input file. -.LP -The options that use the track IDs are the ones whose description contains -\'TID\'. -The following options use track IDs as well: \fB\-\-atracks\fR, -\fB\-\-vtracks\fR, \fB\-\-stracks\fR and \fB\-\-btracks\fR. - - -.SH SUBTITLES -.LP -There are several text subtitle formats that can be embedded into -Matroska. At the moment \fBmkvmerge\fR supports only text, VobSub and -Kate subtitle formats. Text subtitles must be recoded to UTF-8 so that -they can be displayed correctly by a player. Kate subtitles are -already in UTF-8 format. -.LP -\fBmkvmerge\fR does this conversion automatically based on the system's current -locale. If the subtitle charset is not the same as -the system's current charset then the user can use \fB\-\-sub\-charset\fR -switch. If the subtitles are already encoded in UTF-8 then you can use -\fB\-\-sub\-charset UTF\-8\fR. -.LP -The following subtitle formats are supported at the moment: -.TP -* -Subtitle Ripper (SRT) files -.TP -* -Substation Alpha (SSA) / Advanced Substation Alpha scripts (ASS) -.TP -* -Kate streams in Ogg - - -.SH FILE LINKING -.LP -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 I simply say 'file linking' -although 'segment linking' would be more appropriate. -.LP -Each segment is identified by a unique 128 bit wide segment UID. This -UID is automatically generated by \fBmkvmerge\fR. The linking is done -primarily via putting the segment UIDs (short: SID) of the -previous/next file into the segment header -information. \fBmkvinfo(1)\fR prints these SIDs if it finds them. -.LP -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 \fBmkvmerge\fR does not -use file linking. If you want that you can turn it on with the -\'\fB\-link\fR\' option. This option is only useful if splitting -is activated as well. -.LP -Regardless of whether splitting is active or not the user can tell -\fBmkvmerge\fR to link the produced files to specific SIDs. This is achieved -with the options '\fB\-\-link\-to\-previous\fR' and '\fB\-\-link\-to\-next\fR'. -These options accept a segment SID in the format that \fBmkvinfo(1)\fR -outputs: 16 hexadecimal numbers between 0x00 and 0xff prefixed with '0x' each, -e.g. \fI0x41 0xda 0x73 0x66 0xd9 0xcf 0xb2 0x1e 0xae 0x78 0xeb 0xb4 0x5e 0xca -0xb3 0x93\fR. Alternatively a shorter form can be used: 16 hexadecimal numbers -between 0x00 and 0xff without the '0x' prefixes and without the spaces, e.g. -\fI41da7366d9cfb21eae78ebb45ecab393\fR. -.LP -If splitting is used then the first file is linked to the SID given with -\'\fB\-\-link\-to\-previous\fR\' and the last file is linked to the SID given -with \'\fB\-\-link\-to\-next\fR\'. If splitting is not used then the one -output file will be linked to both of the two SIDs. - - -.SH DEFAULT VALUES -.LP -The Matroska specs say that some elements have a default value. Usually an -element is not written to the file if its value is equal to its default -value in order to save space. The elements that the user might miss in -\fBmkvinfo\fR's output are the \fIlanguage\fR and the \fIdefault track flag\fR. -The default value for the \fIlanguage\fR is English (\fIeng\fR), -and the default value for the \fIdefault track flag\fR is \fItrue\fR. Therefore -if you used \fB--language 0:eng\fR for a track then it will not show up -in \fBmkvinfo\fR's output. - - -.SH ATTACHMENTS -.LP -Maybe you also want to keep some photos along with your Matroska file, or -you're using SSA subtitles and need a special TrueType font that's really -rare. In these cases you can attach those files to the Matroska file. They -will not be just appended to the file but embedded in it. A player can then -show those files (the 'photos' case) or use them to render the subtitles -(the 'TrueType fonts' case). -.LP -Here's an example how to attach a photo and a TrueType font to the output -file: -.br -$ \fBmkvmerge -o output.mkv -A video.avi sound.ogg \-\-attachment\-description -"Me and the band behind the stage in a small get-together" -\-\-attachment\-mime\-type image/jpeg \-\-attach\-file me_and_the_band.jpg -\-\-attachment\-description "The real rare and unbelievably good looking font" -\-\-attachment\-type application/octet\-stream -\-\-attach\-file really_cool_font.ttf - - -.SH CHAPTERS -.LP -The Matroska chapter system is more powerful than the old known system used -by OGMs. The full specs can be found at -.UR http://\:www.matroska.org/\:technical/\:specs/\:chapters/\:index.html -www.matroska.org -.UE - -.LP -\fBmkvmerge\fR supports two kinds of chapter files as its input. The first -format, called 'simple chapter format', is the same format that the OGM tools -expect. The second format is a XML based chapter format which supports all -of Matroska's chapter functionality. -.LP -\fBThe simple chapter format\fR - -It looks basically like this: -.LP -CHAPTER01=00:00:00.000 -.br -CHAPTER01NAME=Intro -.br -CHAPTER02=00:02:30.000 -.br -CHAPTER02NAME=Baby prepares to rock -.br -CHAPTER03=00:02:42.300 -.br -CHAPTER03NAME=Baby rocks the house -.LP -\fBmkvmerge\fR will transform every pair or lines (CHAPTERxx and CHAPTERxxNAME) -into one Matroska \fIChapterAtom\fR. It does not set any -\fIChapterTrackNumber\fR which means that the chapters all apply to all -tracks in the file. -.LP -The charset used in the file is assumed to be the same charset that the -current system's locale returns. If this is not the case then the switch -\fI\-\-chapter\-charset\fR should be used. If the file contains a valid -BOM (byte order marker) then all UTF styles are converted automatically. -In this case \fI\-\-chapter\-charset\fR is simply ignored. You can use -\fBmkvinfo\fR or \fBmkvextract\fR to verify that the chapter names have -been converted properly. -.LP -\fBThe XML based chapter format\fR - -The XML based chapter format looks like this: -.LP - -.br - -.br - -.br - -.br - -.br - 00:00:30.000 -.br - 00:01:20.000 -.br - -.br - A short chapter -.br - eng -.br - -.br - -.br - 00:00:46.000 -.br - 00:01:10.000 -.br - -.br - A part of that short chapter -.br - eng -.br - -.br - -.br - -.br - -.br - - -With this format three things are possible that are not possible with the -simple chapter format: 1) The timestamp for the end of the chapter can be -set, 2) chapters can be nested, 3) the language and country can be set. -.LP -The mkvtoolnix distribution contains some sample files in the \fIdoc\fR -subdirectory which can be used as a basis. -.LP -\fBGeneral notes\fR - -.LP -When splitting files \fBmkvmerge\fR will correctly adjust the chapters as -well. This means that each file only includes the chapter entries that -apply to it, and that the timecodes will be offset to match the new timecodes -of each output file. -.LP -\fBmkvmerge\fR is able to copy chapters from Matroska source files unless this -is explicitly disabled with the \fI\-\-no\-chapters\fR option. At the -moment \fBmkvmerge\fR is limited to one 'bunch of chapters' globally. This means -that only the first chapter section found in all source files is used. If -the user specified chapters on the command line then these take precedence -over any chapters found in source files. \fBmkvmerge\fR does not merge -chapters. This must be done manually by using \fBmkvextract\fR to extract -the chapter information and editing the resulting files. -.LP -One shortcoming is that \fBmkvmerge\fR cannot parse chapter information found -in OGM files. - - -.SH TAGS -.LP -\fBIntroduction\fR - -Matroska supports an extensive set of tags that is deprecated and a -new, simpler system like it is is used in most other containers: -\fIKEY=VALUE\fR. However, in Matroska these tags can also be nested, -and both the \fIKEY\fR and the \fIVALUE\fR are elements of their -own. The example file \fIexample-tags-2.xml\fR shows how to use this new -system. - -.LP -\fBScope of the tags\fR - -Matroska tags do not automatically apply to the complete file. They can, -but they also may apply to different parts of the file: to one or more -tracks, to one or more chapters, or even to a combination of both. The -aforementioned URL gives more details about this fact. - -.LP - -One important fact is that tags are linked to tracks or chapters with -the \fITargets\fR Matroska tag element, and that the UIDs used for -this linking are NOT the track IDs \fBmkvmerge\fR uses -everywhere. Instead the numbers used are the UIDs which \fBmkvmerge\fR -calculates automatically (if the track is taken from a file format -other than Matroska) or which are copied from the source file if the -track's source file is a Matroska file. Therefore it is difficult to -know which UIDs to use in the tag file before the file is handed -over to \fBmkvmerge\fR. - -.LP - -\fBmkvmerge\fR knows two options with which you can add tags to -Matroska files: The \fB\-\-global\-tags\fR and the \fB\-\-tags\fR -options. The difference is that the former option, -\fB\-\-global\-tags\fR, will make the tags apply to the complete file -by removing any of those \fITargets\fR elements mentioned above. The -latter option, \fB\-\-tags\fR, automatically inserts the UID that -\fBmkvmerge\fR generates for the tag specified with the \fITID\fR part -of the \fB\-\-tags\fR option. - -.LP -\fBExample\fR - -Let's say that you want to add tags to a video track read from -an AVI. \fBmkvmerge -i file.avi\fR 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 any \fITargets\fR element and call \fBmkvmerge\fR: -.br -$ \fBmkvmerge -o file.mkv --tags 0:tags.xml file.avi\fR - -.LP -\fBTag file format\fR - -\fBmkvmerge\fR supports a XML based tag file format. The format is -very easy and closely connected to the Matroska tag specs found at the -URL mentioned above. Both the binary and the source \fBmkvtoolnix\fR -distributions come with a sample file called \example-tags-2.xml\fR -which simply lists all known tags and which can be used as a basis for -real life tag files. - -.LP - -The basics are: -.TP -* -The outermost element must be \fB\fR. -.TP -* -One logical tag is contained inside one pair of \fB\fR XML tags. -.TP -* -White spaces directly before and after tag contents are ignored. - -.LP -\fBData types\fR - -The new Matroska tagging system only knows two data types, a UTF-8 string -and a binary type. The first is used for the tag's name and the \fI\fR -element while the binary type is used for the \fI\fR type. - -.LP - -As binary data itself would not fit into a XML file \fBmkvmerge\fR -supports two other methods of storing binary data. If the contents of -a XML tag starts with '@' then the following text is treated as a -\fIfile name\fR. The corresponding file's content is copied into the -Matroska element. - -.LP - -Otherwise the data is expected to be \fIBase64\fR encoded. This is an -encoding that transforms binary data into a limited set of ASCII -characters and is used e.g. in email programs. \fBmkvtoolnix\fR comes -with a utility, \fBbase64tool\fR, that can be used to encode to and -decode from Base64. \fBmkvextract\fR will output Base64 encoded data -for binary elements. - -.LP - -The deprecated tagging system knows some more data types which can be -found in the official Matroska tag specs. \fBThe following two paragraphs only -apply to the deprecated tags\fR (an example file is still available and called -\fIexample-tags-deprecated.xml\fR): - -.LP - -The types \fIinteger\fR, \fIunsigned integer\fR, \fIfloat\fR, \fIstring\fR -and \fIUTF-8 string\fR look just like you expect them to: \fI4254\fR, -\fI-2\fR, \fI5.0\fR, \fIhello world\fR and \fIhello world\fR. - -.LP - -The date format used by both \fBmkvmerge\fR when reading XML tag files -and by \fBmkvextract\fR when outputting XML tag data is the \fIISO-8601\fR -format. It has the following structure: -\fIYYYY\fR-\fIMM\fR-\fIDD\fRT\fIHH\fR:\fIMM\fR:\fISS\fR\fI+TZTZ\fR. -\fIYYYY\fR is the year (four digits long), \fIMM\fR the month (two digits -long starting with 01), \fIDD\fR the day of the month (two digits long -starting with 01), \fIHH\fR the hour of the day (two digits long, range -00 - 23), \fIMM\fR the minute (two digits long, range 00 - 59), \fISS\fR -the seconds (two digits long, range 00 - 59). \fI+TZTZ\fR is the time zone, -e.g. +0100 or -0200. An example would be 2003-07-30T19:10:16+0200. - - - -.SH MATROSKA FILE LAYOUT -.LP -The Matroska file layout is quite flexible. \fBmkvmerge\fR will render a file -in a predefined way. The resulting file looks like this: -.LP -[EBML head] [segment {meta seek #1} {attachments} {chapters} -[segment information] [track information] [cluster 1] {cluster 2} ... -{cluster n} {cues} {meta seek #2} {tags}] -.LP -The elements in curly braces are optional and depend on the contents and -options used. Some notes: -.TP -* -meta seek #1 includes only a small number of level 1 elements, and only if -they actually exist: attachments, chapters, cues, tags, meta seek #2. Older -versions of \fBmkvmerge\fR used to put the clusters into this meta seek -element as well. Therefore some imprecise guessing was necessary to reserve -enough space. It often failed. Now only the clusters are stored in meta -seek #2, and meta seek #1 refers to the meta seek element #2. -.TP -* -Attachment, chapter and tag elements are only present if they were added. -.LP -The shortest possible Matroska file would look like this: -.LP -[EBML head] [segment [segment information] [track information] [cluster 1]] -.LP -This might be the case for audio-only files. - - -.SH EXTERNAL TIMECODE FILES -.LP -\fBmkvmerge\fR allows the user to chose the timecodes for a specific track -himself. This can be used in order to create files with variable frame rate -video or include gaps in audio. A frame in this case is the unit that -\fBmkvmerge\fR creates separately per Matroska block. For video this -is exactly one frame, for audio this is one packet of the specific -audio type. E.g. for AC3 this would be a packet containing 1536 -samples. -.LP -Timecode files that are used when tracks are appended to each other must -only be specified for the first part in a chain of tracks. -For example if you append two files, v1.avi and v2.avi, and want to use -timecodes then your command line must look something like this: -.br -\fBmkvmerge ... --timecodes 0:my_timecodes.txt v1.avi +v2.avi\fR -.LP -There are three formats that are recognized by \fBmkvmerge\fR. The first -line always contains the version number. Empty lines, lines containing only -whitespace and lines beginning with '#' are ignored. -.LP -\fBTimecode file format v1\fR -.LP -This format starts with this line: -.br -\fB# timecode format v1\fR -.br -The second line gives the default number of frames per second: -.br -\fBassume 27.930\fR -.br -All following lines contain three numbers separated by commas: the -start frame (0 is the first frame), the end frame and the number of -frames in this range. The FPS is a floating point number with the dot -'.' as the decimal point. The ranges can contain gaps for which the -default FPS is used. Example: -.br -\fB800,1000,25\fR -.br -\fB1500,1700,30\fR -.LP -\fBTimecode file format v2\fR -.LP -In this format each line contains a timecode for the corresponding frame. -This timecode must be given in ms precision. -It can be a floating point number, but it doesn't have to be. -You \fBmust\fR give at least as many timecode lines as there are frames in -the track. -The timecodes in this file must be sorted. -Example for 25fps: -.br -\fB# timecode format v2\fR -.br -\fB0\fR -.br -\fB40\fR -.br -\fB80\fR -.br -etc. -.LP -\fBTimecode file format v3\fR -.LP -In this format each line contains a duration in seconds followed by an -optional number of frames per second. -Both can be floating point numbers. -If the number of frames per second is not present the default one is used. -For audio you should let the codec calculate the frame timecodes itself. -For that you should be using 0.0 as the number of frames per second. -You can also create gaps in the stream by using the \fBgap\fR keyword followed -by the duration of the gap. -Example for an audio file: -.br -\fB# timecode format v3\fR -.br -\fBassume 0.0\fR -.br -\fB25.325\fR -.br -\fB7.530,38.236\fR -.br -\fBgap, 10.050\fR -.br -\fB2.000,38.236\fR -.br -etc. -.LP -\fBTimecode file format v4\fR -.LP -This format is identical to the v2 format. -The only difference is that the timecodes do not have to be sorted. -This format should almost never be used. - - -.SH EXIT CODES -.LP -\fBmkvmerge\fR exits with one of three exit codes: -.TP -0 -This exit codes means that muxing has completed successfully. -.TP -1 -In this case \fBmkvmerge\fR has output at least one warning, but muxing did -continue. -A warning is prefixed with the text \'Warning:\'. -Depending on the issues involved the resulting file might be ok or not. -The user is urged to check both the warning and the resulting file. -.TP -2 -This exit code is used after an error occured. -\fBmkvmerge\fR aborts right after outputting the error message. -Error messages range from wrong command line arguments over read/write errors -to broken files. - - -.SH NOTES -.LP -What works (this list is probably outdated): -.TP -* -AVI as the video and audio source (only raw PCM, MP3 and AC3 audio tracks at -the moment) -.TP -* -OGG as the source for video, audio (Vorbis, raw PCM, MP3 and AC3 audio) -and subtitle streams (Kate and simple text formats). -.TP -* -WAV as the audio source -.TP -* -AAC audio files (ADTS AAC files and AAC from MP4) -.TP -* -AC3 audio files -.TP -* -DTS audio files -.TP -* -MP3 audio files -.TP -* -RealVideo and RealAudio from RealMedia files -.TP -* -FLAC audio files (both raw FLAC and OggFLAC) -.TP -* -Track selection -.TP -* -Manual audio synchronization by adding silence/removing packets for Vorbis -audio and for text streams by adjusting the starting point and duration. -.TP -* -Manual audio synchronization for AAC, AC3, DTS and MP3 audio by duplicating -or removing packets at the beginning. -.TP -* -Subtitles can be read as text from SRT (SubRipper / subrip) files, -taken from other OGM files, or from Kate streams in Ogg files. -.TP -* -SSA/ASS subtitles from SSA/ASS files -.TP -* -Simple chapters. -.TP -* -Full tags support. -.LP -What not works: -.TP -* -Manual audio synchronization for PCM sound (who needs it anyway?) - - -.SH AUTHOR -.I mkvmerge -was written by Moritz Bunkus . -.SH SEE ALSO -.BR mkvinfo (1), -.BR mkvextract (1), -.BR mmg (1) -.SH WWW -The newest version can always be found at -.UR http://www.bunkus.org/\:videotools/\:mkvtoolnix/ -www.bunkus.org -.UE diff --git a/doc/mmg.1 b/doc/mmg.1 deleted file mode 100644 index 23019294d..000000000 --- a/doc/mmg.1 +++ /dev/null @@ -1,50 +0,0 @@ -.TH MMG "1" "July 2009" "mmg v2.9.7" "User Commands" - - -.SH NAME -mmg \- a GUI for mkvmerge including a chapter editor - - -.SH SYNOPSIS -.B mmg -[\fIpreferences.mmg\fR|\fIinput_file.ext\fR] -.br -.B mmg -\-\-edit\-headers <\fIfile.mkv\fR> -.br - - -.SH DESCRIPTION -.LP -\fBmmg\fR is a wxWindows based GUI for \fBmkvmerge\fR. It offers easy -access to all of \fBmkvmerge\fR's options. All settings (e.g. source -files, track options etc) can be saved and restored. Included is a -chapter editor that can read OGM style and XML style chapter files, -write XML style chapter files and even read chapters from Matroska -files and write chapters directly to Matroska files. -.LP -\fBmmg\fR knows few options. The first possibility is to start it with -a single file name. If that file name's extenion is '\fI.mmg\fR' then -it will be treated as a preferences file and \fBmmg\fR will load its -setting when it starts. Otherwise the name is interpreted as being -the name of an input file which will be added. -.LP -The second operation mode is invoked with the -option '\-\-edit\-headers' and a file name. This lets \fBmmg\fR run -its header editor and load the file. -.LP -The full documentation is available in HTML form (doc/mkvmerge-gui.html). - - -.SH AUTHOR -.I mmg -was written by Moritz Bunkus . -.SH SEE ALSO -.BR mkvmerge (1), -.BR mkvinfo (1), -.BR mkvextract (1) - -.SH WWW -The newest version can always be found at -.UR http://www.bunkus.org/\:videotools/\:mkvtoolnix/ -.UE