diff --git a/.gitignore b/.gitignore index 82ae83b93..10f40f684 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ config.sub configure data /doc/docbook/mkvmerge.1 +/doc/docbook/mkvextract.1 diff --git a/doc/docbook/mkvextract.xml b/doc/docbook/mkvextract.xml new file mode 100644 index 000000000..2fdf0f37f --- /dev/null +++ b/doc/docbook/mkvextract.xml @@ -0,0 +1,606 @@ + + + + + + +mkvmerge1"> +mkvinfo1"> +mkvextract1"> +mmg1"> + +Matroska"> +OggVorbis"> +XML"> + +]> + + + + &product; + &date; + + + Developer + Moritz + Bunkus + moritz@bunkus.org + + + + + &product; + 1 + &version; + &date; + www.bunkus.org + http://www.bunkus.org/videotools/mkvtoolnix/doc + + + + &product; + extract tracks from &matroska; files into other files + + + + Synopsis + + mkvextract + mode + source-filename + options + extraction-spec + + + + + Description + + This program extracts specific parts from a Matroska file to other useful formats. The first argument, , tells + &mkvextract; 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; file. All following arguments are options and extraction specifications; both of which depend on the selected mode. + + + + Common options + + + The following options are available in all modes and only described once in this section. + + + + + character-set + + + Sets the character set to convert strings given on the command line from. It defaults to the character set given by system's current + locale. + + + + + + character-set + + + Sets the character set to which strings are converted that are to be output. It defaults to the character set given by system's + current locale. + + + + + + , file-name + + + Writes all messages to the file file-name instead of to the console. While this can be done easily with + output redirection there are cases in which this option is needed: when the terminal reinterprets the output before writing it to a + file. The character set set with is honored. + + + + + + code + + + Forces the translations for the language code to be used (e.g. 'de_DE' for the German + translations). It is preferable to use the environment variables LANG, LC_MESSAGES and + LC_ALL though. Entering 'list' as the code will cause &mkvextract; to + output a list of available translations. + + + + + + , + + + Be verbose and show all the important &matroska; elements as they're read. + + + + + + , + + + Show usage information and exit. + + + + + + , + + + Show version information and exit. + + + + + + options-file + + + Reads additional command line arguments from the file options-file. Lines whose first non-whitespace + character is a hash mark ('#') are treated as comments and ignored. White spaces at the start and end of a line + will be stripped. Each line must contain exactly one option. There is no meta character escaping. + + + + The command line 'mkvextract tracks source.mkv --raw 1:destination.raw' could be converted into the following + option file: + + + +# Extract a track from source.mkv +tracks +source.mkv +# Output the track as raw data. +--raw +1;destination.raw + + + + + + + + Track extraction mode + + + Syntax: mkvextract source-filename options TID1:dest-filename1 TID2:dest-filename2 ... + + + + 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. + + + + + character-set + + + 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. + + + + + + level + + + 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. + + + + + + + + + Causes &mkvextract; 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. + + + + + + + + + Extracts the raw data into a file without any container data around it. Unlike the 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 &mkvextract; doesn't support otherwise, but the resulting files might not be usable. + + + + + + + + + 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 &mkvextract; doesn't support otherwise, but the resulting files might not be + usable. + + + + + + + + + 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. + + + + + + TID:outname + + + Causes extraction of the track with the ID TID into the file + outname 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 + &mkvmerge;'s option. + + + + 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: + + + +$ mkvextract tracks input.mkv 1:output-two-tracks.rm 2:output-two-tracks.rm + + + + + + + + Tags extraction mode + + + Syntax: mkvextract source-filename options + + + + The extracted tags are written to the console unless the output is redirected (see the section about output redirection for details). + + + + + Attachments extraction mode + + + Syntax: mkvextract source-filename options AID1:outname1 AID2:outname2 ... + + + + + AID:outname + + + Causes extraction of the attachment with the ID AID into the file outname if such an + attachment exists in the source file. If the outname 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 &mkvmerge;'s option. + + + + + + + + Chapters extraction mode + + + Syntax: mkvextract source-filename options + + + + + , + + + 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. + + + + + + + The extracted chapters are written to the console unless the output is redirected (see the section about output redirection for details). + + + + + Cue sheet extraction mode + + + Syntax: mkvextract source-filename options + + + + The extracted cue sheet is written to the console unless the output is redirected (see the section about output redirection for details). + + + + + Timecode extraction mode + + + Syntax: mkvextract source-filename options + + + + The extracted timecodes are written to the console unless the output is redirected (see the section about output redirection for details). + + + + + + Output redirection + + + Several extraction modes cause &mkvextract; 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 &mkvextract; itself. + + + + The shell's builtin redirection mechanism is used by appending '> output-filename.ext' to the command + line. Example: + + + +$ mkvextract tags source.mkv > tags.xml + + + + &mkvextract;'s own redirection is invoked with the option. Example: + + + +$ mkvextract tags source.mkv --redirect-output tags.xml + + + + + On Windows you should probably use the option because + cmd.exe sometimes interpretes special characters before they're written into the output file resulting in broken + output. + + + + + + Output file formats + + + 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: + + + + + 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. + + + + + + V_MS/VFW/FOURCC + + + Fixed FPS video tracks with this CodecID are written to AVI files. + + + + + + V_REAL/* + + + RealVideo tracks are written to RealMedia files. + + + + + + A_MPEG/L3, A_AC3 + + + These will be extracted to raw MP3 and AC3 files. + + + + + + A_PCM/INT/LIT + + + Raw PCM data will be written to a WAV file. + + + + + + A_AAC/MPEG2/*, A_AAC/MPEG4/*, A_AAC + + + 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. + + + + + + A_VORBIS + + + Vorbis audio will be written into an &oggvorbis; file. + + + + + + A_REAL/* + + + RealAudio tracks are written to RealMedia files. + + + + + + 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. + + + + + + S_TEXT/UTF8 + + + Simple text subtitles will be written as SRT files. + + + + + + S_TEXT/SSA, S_TEXT/ASS + + + SSA and ASS text subtitles will be written as SSA/ASS files + respectively. + + + + + + S_KATE + + + Kate streams will be written within an Ogg container. + + + + + + Tags + + + Tags are converted to a &xml; format. This format is the same that &mkvmerge; supports for reading tags. + + + + + + Attachments + + + Attachments are written to they output file as they are. No conversion whatsoever is done. + + + + + + Chapters + + + Chapters are converted to a &xml; format. This format is the same that &mkvmerge; supports for reading chapters. Alternatively a + stripped-down version can be output in the simple OGM style format. + + + + + + Timecodes + + + Timecodes 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, v3 and v4) is not supported. + + + + + + + + Exit codes + + + &mkvextract; exits with one of three exit codes: + + + + + + 0 -- This exit codes means that extraction has completed successfully. + + + + + + 1 -- In this case &mkvextract; 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. + + + + + + 2 -- This exit code is used after an error occured. &mkvextract; aborts right after outputting the error message. + Error messages range from wrong command line arguments over read/write errors to broken files. + + + + + + + See also + + &mkvmerge;, &mkvinfo;, &mmg; + + + + + WWW + + The latest version can always be found at the MKVToolNix homepage. + + + +