mkvtoolnix/doc/man/mkvextract.1

'\" t
.\"     Title: mkvextract
.\"    Author: Moritz Bunkus <moritz@bunkus.org>
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 2011-11-27
.\"    Manual: User Commands
.\"    Source: MKVToolNix 5.1.0
.\"  Language: English
.\"
.TH "MKVEXTRACT" "1" "2011\-11\-27" "MKVToolNix 5\&.1\&.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(TM) 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(TM)
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\-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)\&. It is preferable to use the environment variables
\fILANG\fR,
\fILC_MESSAGES\fR
and
\fILC_ALL\fR
though\&. Entering \*(Aqlist\*(Aq 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\*(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
http://mkvtoolnix\-releases\&.bunkus\&.org/latest\-release\&.xml\&. 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\fR
.RS 4
Reads additional command line arguments from the file
\fIoptions\-file\fR\&. Lines whose first non\-whitespace character is a hash mark (\*(Aq#\*(Aq) 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\&.
.sp
Several chars can be escaped, e\&.g\&. if you need to start a non\-comment line with \*(Aq#\*(Aq\&. The rules are described in
the section about escaping text\&.
.sp
The command line \*(Aq\fBmkvextract tracks source\&.mkv \-\-raw 1:destination\&.raw\fR\*(Aq could be converted into the following option file:
.sp
.if n \{\
.RS 4
.\}
.nf
# Extract a track from source\&.mkv
tracks
source\&.mkv
# Output the track as raw data\&.
\-\-raw
1:destination\&.raw
.fi
.if n \{\
.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 \*(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
\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
\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(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)\*(Aqs
\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]
\fITID1:dest\-filename1\fR
[\fITID2:dest\-filename2\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
.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 "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)\*(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
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
.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 "SEE ALSO"
.PP

\fBmkvmerge\fR(1),
\fBmkvinfo\fR(1),
\fBmkvpropedit\fR(1),
\fBmmg\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
\%http://www.bunkus.org/videotools/mkvtoolnix/
.RE