'\" t .\" Title: mkvextract .\" Author: Moritz Bunkus .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: 2017-05-20 .\" Manual: User Commands .\" Source: MKVToolNix 12.0.0 .\" Language: English .\" .TH "MKVEXTRACT" "1" "2017\-05\-20" "MKVToolNix 12\&.0\&.0" "User Commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" mkvextract \- extract tracks from Matroska files into other files .SH "SYNOPSIS" .HP \w'\fBmkvextract\fR\ 'u \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, timecodes and cues\&. The second argument is the name of the source file\&. It must be a Matroska 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\-f\fR, \fB\-\-parse\-fully\fR .RS 4 Sets the parse mode to \*(Aqfull\*(Aq\&. The default mode does not parse the whole file but uses the meta seek elements for locating the required elements of a source file\&. In 99% of all cases this is enough\&. But for files that do not contain meta seek elements or which are damaged the user might have to use this mode\&. A full scan of a file can take a couple of minutes while a fast scan only takes seconds\&. .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\*(Aqs 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\*(Aqs 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\&. \*(Aqde_DE\*(Aq for the German translations)\&. Entering \*(Aqlist\*(Aq as the \fIcode\fR will cause the program to output a list of available translations\&. .RE .PP \fB\-\-debug\fR \fItopic\fR .RS 4 Turn on debugging for a specific feature\&. This option is only useful for developers\&. .RE .PP \fB\-\-engage\fR \fIfeature\fR .RS 4 Turn on experimental features\&. A list of available features can be requested with \fBmkvextract \-\-engage list\fR\&. These features are not meant to be used in normal situations\&. .RE .PP \fB\-\-gui\-mode\fR .RS 4 Turns on GUI mode\&. In this mode specially\-formatted lines may be output that can tell a controlling GUI what\*(Aqs happening\&. These messages follow the format \*(Aq#GUI#message\*(Aq\&. The message may be followed by key/value pairs as in \*(Aq#GUI#message#key1=value1#key2=value2\&...\*(Aq\&. Neither the messages nor the keys are ever translated and always output in English\&. .RE .PP \fB\-v\fR, \fB\-\-verbose\fR .RS 4 Be verbose and show all the important Matroska elements as they\*(Aqre 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\-\-check\-for\-updates\fR .RS 4 Checks online for new releases by downloading the URL \m[blue]\fBhttp://mkvtoolnix\-releases\&.bunkus\&.org/latest\-release\&.xml\fR\m[]\&. Four lines will be output in key=value style: the URL from where the information was retrieved (key version_check_url), the currently running version (key running_version), the latest release\*(Aqs version (key available_version) and the download URL (key download_url)\&. .sp Afterwards the program exists with an exit code of 0 if no newer release is available, with 1 if a newer release is available and with 2 if an error occured (e\&.g\&. if the update information could not be retrieved)\&. .sp This option is only available if the program was built with support for libcurl\&. .RE .PP \fB@\fR\fIoptions\-file\&.json\fR .RS 4 Reads additional command line arguments from the file \fIoptions\-file\fR\&. For a full explanation on the supported formats for such files see the section called "Option files" in the \fBmkvmerge\fR(1) man page\&. .RE .SS "Track extraction mode" .PP Syntax: \fBmkvextract \fR\fB\fBtracks\fR\fR\fB \fR\fB\fIsource\-filename\fR\fR\fB \fR\fB[\fIoptions\fR]\fR\fB \fR\fB\fITID1:dest\-filename1\fR\fR\fB \fR\fB[\fITID2:dest\-filename2\fR \&.\&.\&.]\fR .PP The following command line options are available for each track in the \*(Aqtracks\*(Aq 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\*(Aqs output name with \*(Aq\&.cue\*(Aq 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\*(Aqt 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\*(Aqt support otherwise, but the resulting files might not be usable\&. .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)\*(Aqs \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 .if n \{\ .RS 4 .\} .nf $ mkvextract tracks input\&.mkv 1:output\-two\-tracks\&.rm 2:output\-two\-tracks\&.rm .fi .if n \{\ .RE .\} .RE .SS "Tags extraction mode" .PP Syntax: \fBmkvextract \fR\fB\fBtags\fR\fR\fB \fR\fB\fIsource\-filename\fR\fR\fB \fR\fB[\fIoptions\fR]\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\fB\fBattachments\fR\fR\fB \fR\fB\fIsource\-filename\fR\fR\fB \fR\fB[\fIoptions\fR]\fR\fB \fR\fB\fIAID1:outname1\fR\fR\fB \fR\fB[\fIAID2:outname2\fR \&.\&.\&.]\fR .PP \fIAID\fR:\fIoutname\fR .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 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)\*(Aqs \fB\-\-identify\fR option\&. .RE .SS "Chapters extraction mode" .PP Syntax: \fBmkvextract \fR\fB\fBchapters\fR\fR\fB \fR\fB\fIsource\-filename\fR\fR\fB \fR\fB[\fIoptions\fR]\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 \fB\-\-simple\-language\fR \fIlanguage\fR .RS 4 If the simple format is enabled then \fBmkvextract\fR(1) will only output a single entry for each chapter atom encountered even if a chapter atom contains more than one chapter name\&. By default \fBmkvextract\fR(1) will use the first chapter name found for each atom regardless of its language\&. .sp Using this option allows the user to determine which chapter names are output if atoms contain more than one chapter name\&. The \fIlanguage\fR parameter must be an ISO 639\-1 or ISO 639\-2 code\&. .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\fB\fBcuesheet\fR\fR\fB \fR\fB\fIsource\-filename\fR\fR\fB \fR\fB[\fIoptions\fR]\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\fB\fBtimecodes_v2\fR\fR\fB \fR\fB\fIsource\-filename\fR\fR\fB \fR\fB[\fIoptions\fR]\fR\fB \fR\fB\fITID1:dest\-filename1\fR\fR\fB \fR\fB[\fITID2:dest\-filename2\fR \&.\&.\&.]\fR .PP The extracted timecodes are written to the console unless the output is redirected (see the section about output redirection for details)\&. .PP \fITID:outname\fR .RS 4 Causes extraction of the timecodes for 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)\*(Aqs \fB\-\-identify\fR option\&. .sp Example: .sp .if n \{\ .RS 4 .\} .nf $ mkvextract timecodes_v2 input\&.mkv 1:tc\-track1\&.txt 2:tc\-track2\&.txt .fi .if n \{\ .RE .\} .RE .SS "Cues extraction mode" .PP Syntax: \fBmkvextract \fR\fB\fBcues\fR\fR\fB \fR\fB\fIsource\-filename\fR\fR\fB \fR\fB[\fIoptions\fR]\fR\fB \fR\fB\fITID1:dest\-filename1\fR\fR\fB \fR\fB[\fITID2:dest\-filename2\fR \&.\&.\&.]\fR .PP \fITID:dest\-filename\fR .RS 4 Causes extraction of the cues for 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)\*(Aqs \fB\-\-identify\fR option and not the numbers contained in the CueTrack element\&. .RE .PP The format output is a simple text format: one line per CuePoint element with key=value pairs\&. If an optional element is not present in a CuePoint (e\&.g\&. CueDuration) then a dash will be output as the value\&. .PP Example: .sp .if n \{\ .RS 4 .\} .nf timecode=00:00:13\&.305000000 duration=\- cluster_position=757741 relative_position=11 .fi .if n \{\ .RE .\} .PP The possible keys are: .PP timecode .RS 4 The cue point\*(Aqs timecode with nanosecond precision\&. The format is HH:MM:SS\&.nnnnnnnnn\&. This element is always set\&. .RE .PP duration .RS 4 The cue point\*(Aqs duration with nanosecond precision\&. The format is HH:MM:SS\&.nnnnnnnnn\&. .RE .PP cluster_position .RS 4 The absolute position in bytes inside the Matroska file where the cluster containing the referenced element starts\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br Inside the Matroska file the CueClusterPosition is relative to the segment\*(Aqs data start offset\&. The value output by \fBmkvextract\fR(1)\*(Aqs cue extraction mode, however, contains that offset already and is an absolute offset from the beginning of the file\&. .sp .5v .RE .RE .PP relative_position .RS 4 The relative position in bytes inside the cluster where the BlockGroup or SimpleBlock element the cue point refers to starts\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br Inside the Matroska file the CueRelativePosition is relative to the cluster\*(Aqs data start offset\&. The value output by \fBmkvextract\fR(1)\*(Aqs cue extraction mode, however, is relative to the cluster\*(Aqs ID\&. The absolute position inside the file can be calculated by adding cluster_position and relative_position\&. .sp .5v .RE .RE .PP Example: .sp .if n \{\ .RS 4 .\} .nf $ mkvextract cues input\&.mkv 1:cues\-track1\&.txt 2:cues\-track2\&.txt .fi .if n \{\ .RE .\} .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\*(Aqs builtin redirection mechanism is used by appending \*(Aq> output\-filename\&.ext\*(Aq to the command line\&. Example: .sp .if n \{\ .RS 4 .\} .nf $ mkvextract tags source\&.mkv > tags\&.xml .fi .if n \{\ .RE .\} .PP \fBmkvextract\fR(1)\*(Aqs own redirection is invoked with the \fB\-\-redirect\-output\fR option\&. Example: .sp .if n \{\ .RS 4 .\} .nf $ mkvextract tags source\&.mkv \-\-redirect\-output tags\&.xml .fi .if n \{\ .RE .\} .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP On Windows you should probably use the \fB\-\-redirect\-output\fR option because \fBcmd\&.exe\fR sometimes interpretes special characters before they\*(Aqre written into the output file resulting in broken output\&. .sp .5v .RE .SH "TEXT FILES AND CHARACTER SET CONVERSIONS" .PP For an in\-depth discussion about how all tools in the MKVToolNix suite handle character set conversions, input/output encoding, command line encoding and console encoding please see the identically\-named section in the \fBmkvmerge\fR(1) man page\&. .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 from the GPAC 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 tracks are written to RealMedia files\&. .RE .PP V_THEORA .RS 4 Theora streams will be written within an Ogg container .RE .PP V_VP8, V_VP9 .RS 4 VP8 / VP9 tracks are written to IVF files\&. .RE .PP A_MPEG/L2 .RS 4 MPEG\-1 Audio Layer II streams will be extracted to raw MP2 files\&. .RE .PP A_MPEG/L3, A_AC3 .RS 4 These will be extracted to raw MP3 and AC\-3 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 file\&. .RE .PP A_REAL/* .RS 4 RealAudio tracks are written to RealMedia files\&. .RE .PP A_TTA1 .RS 4 TrueAudio tracks are written to TTA files\&. Please note that due to Matroska\*(Aqs limited timecode precision the extracted file\*(Aqs header will be different regarding two fields: \fIdata_length\fR (the total number of samples in the file) and the CRC\&. .RE .PP A_ALAC .RS 4 ALAC tracks are written to CAF files\&. .RE .PP A_FLAC .RS 4 FLAC tracks are written to raw FLAC files\&. .RE .PP A_WAVPACK4 .RS 4 WavPack tracks are written to WV files\&. .RE .PP A_OPUS .RS 4 Opus tracks are written to OggOpus files\&. .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 streams will be written within an Ogg container\&. .RE .PP S_VOBSUB .RS 4 VobSub subtitles will be written as SUB files along with the respective index files, as IDX files\&. .RE .PP S_TEXT/USF .RS 4 USF text subtitles will be written as USF files\&. .RE .PP S_HDMV/PGS .RS 4 PGS subtitles will be written as SUP files\&. .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 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB0\fR \-\- This exit codes means that extraction has completed successfully\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \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 \*(AqWarning:\*(Aq\&. 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 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB2\fR \-\- This exit code is used after an error occurred\&. \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 "ESCAPING SPECIAL CHARS IN TEXT" .PP There are a few places in which special characters in text must or should be escaped\&. The rules for escaping are simple: each character that needs escaping is replaced with a backslash followed by another character\&. .PP The rules are: \*(Aq \*(Aq (a space) becomes \*(Aq\es\*(Aq, \*(Aq"\*(Aq (double quotes) becomes \*(Aq\e2\*(Aq, \*(Aq:\*(Aq becomes \*(Aq\ec\*(Aq, \*(Aq#\*(Aq becomes \*(Aq\eh\*(Aq and \*(Aq\e\*(Aq (a single backslash) itself becomes \*(Aq\e\e\*(Aq\&. .SH "ENVIRONMENT VARIABLES" .PP \fBmkvextract\fR(1) uses the default variables that determine the system\*(Aqs locale (e\&.g\&. \fILANG\fR and the \fILC_*\fR family)\&. Additional variables: .PP \fIMKVEXTRACT_DEBUG\fR, \fIMKVTOOLNIX_DEBUG\fR and its short form \fIMTX_DEBUG\fR .RS 4 The content is treated as if it had been passed via the \fB\-\-debug\fR option\&. .RE .PP \fIMKVEXTRACT_ENGAGE\fR, \fIMKVTOOLNIX_ENGAGE\fR and its short form \fIMTX_ENGAGE\fR .RS 4 The content is treated as if it had been passed via the \fB\-\-engage\fR option\&. .RE .PP \fIMKVEXTRACT_OPTIONS\fR, \fIMKVTOOLNIX_OPTIONS\fR and its short form \fIMTX_OPTIONS\fR .RS 4 The content is split on white space\&. The resulting partial strings are treated as if it had been passed as command line options\&. If you need to pass special characters (e\&.g\&. spaces) then you have to escape them (see the section about escaping special characters in text)\&. .RE .SH "SEE ALSO" .PP \fBmkvmerge\fR(1), \fBmkvinfo\fR(1), \fBmkvpropedit\fR(1), \fBmkvtoolnix-gui\fR(1) .SH "WWW" .PP The latest version can always be found at \m[blue]\fBthe MKVToolNix homepage\fR\m[]\&\s-2\u[1]\d\s+2\&. .SH "AUTHOR" .PP \fBMoritz Bunkus\fR <\&moritz@bunkus\&.org\&> .RS 4 Developer .RE .SH "NOTES" .IP " 1." 4 the MKVToolNix homepage .RS 4 \%https://mkvtoolnix.download/ .RE