1MKVEXTRACT(1) User Commands MKVEXTRACT(1)
2
6 mkvextract - extract tracks from Matroska(TM) files into other files
7
9 mkvextract {source-filename} {mode1} [options] [extraction-spec1]
10 [mode2] [options] [extraction-spec2] [...]
11
13 This program extracts specific parts from a Matroska(TM) file to other
14 useful formats. The first argument is the name of the source file which
15 must be a Matroska(TM) file.
16 All other arguments either switch to a certain extraction mode, change
18 options for the currently active mode or specify what to extract into
19 which file. Multiple modes can be used in the same invocation of
20 mkvextract allowing the extraction of multiple things in a single pass.
21 Most options can only be used in certain modes with a few options
22 applying to all modes.
23 Currently supported is the extraction of tracks, tags, attachments,
25 chapters, CUE sheets, timestamps and cues.
26 Common options
28 The following options are available in all modes and only described
29 once in this section.
30 -f, --parse-fully
32 Sets the parse mode to 'full'. The default mode does not parse the
33 whole file but uses the meta seek elements for locating the
34 required elements of a source file. In 99% of all cases this is
35 enough. But for files that do not contain meta seek elements or
36 which are damaged the user might have to use this mode. A full scan
37 of a file can take a couple of minutes while a fast scan only takes
38 seconds.
39 --command-line-charset character-set
41 Sets the character set to convert strings given on the command line
42 from. It defaults to the character set given by system's current
43 locale.
44 --output-charset character-set
46 Sets the character set to which strings are converted that are to
47 be output. It defaults to the character set given by system's
48 current locale.
49 -r, --redirect-output file-name
51 Writes all messages to the file file-name instead of to the
52 console. While this can be done easily with output redirection
53 there are cases in which this option is needed: when the terminal
54 reinterprets the output before writing it to a file. The character
55 set set with --output-charset is honored.
56 --flush-on-close
58 Tells the program to flush all data cached in memory to storage
59 when closing files opened for writing. This can be used to prevent
60 data loss on power outages or to circumvent certain problems in the
61 operating system or drivers. The downside is that multiplexing will
62 take longer as mkvmerge will wait until all data has been written
63 to the storage before exiting. See issues #2469 and #2480 on the
64 MKVToolNix bug tracker for in-depth discussions on the pros and
65 cons.
66 --ui-language code
68 Forces the translations for the language code to be used (e.g.
69 'de_DE' for the German translations). Entering 'list' as the code
70 will cause the program to output a list of available translations.
71 --abort-on-warnings
73 Tells the program to abort after the first warning is emitted. The
74 program's exit code will be 1.
75 --debug topic
77 Turn on debugging for a specific feature. This option is only
78 useful for developers.
79 --engage feature
81 Turn on experimental features. A list of available features can be
82 requested with mkvextract --engage list. These features are not
83 meant to be used in normal situations.
84 --gui-mode
86 Turns on GUI mode. In this mode specially-formatted lines may be
87 output that can tell a controlling GUI what's happening. These
88 messages follow the format '#GUI#message'. The message may be
89 followed by key/value pairs as in
90 '#GUI#message#key1=value1#key2=value2...'. Neither the messages nor
91 the keys are ever translated and always output in English.
92 -v, --verbose
94 Be verbose and show all the important Matroska(TM) elements as
95 they're read.
96 -h, --help
98 Show usage information and exit.
99 -V, --version
101 Show version information and exit.
102 @options-file.json
104 Reads additional command line arguments from the file options-file.
105 For a full explanation on the supported formats for such files see
106 the section called "Option files" in the mkvmerge(1) man page.
107 Track extraction mode
109 Syntax: mkvextract source-filename tracks [options] TID1:dest-filename1
110 [TID2:dest-filename2 ...]
111 The following command line options are available for each track in the
113 'tracks' extraction mode. They have to appear in front of the track
114 specification (see below) they should be applied to.
115 -c character-set
117 Sets the character set to convert the next text subtitle track to.
118 Only valid if the next track ID targets a text subtitle track. It
119 defaults to UTF-8.
120 --blockadd level
122 Keep only the BlockAdditions up to this level. The default is to
123 keep all levels. This option only affects certain kinds of codecs
124 like WAVPACK4.
125 --cuesheet
127 Causes mkvextract(1) to extract a CUE sheet from the chapter
128 information and tag data for the following track into a file whose
129 name is the track's output name with '.cue' appended to it.
130 --raw
132 Extracts the raw data into a file without any container data around
133 it. Unlike the --fullraw flag this flag does not cause the contents
134 of the CodecPrivate element to be written to the file. This mode
135 works with all CodecIDs, even the ones that mkvextract(1) doesn't
136 support otherwise, but the resulting files might not be usable.
137 --fullraw
139 Extracts the raw data into a file without any container data around
140 it. The contents of the CodecPrivate element will be written to the
141 file first if the track contains such a header element. This mode
142 works with all CodecIDs, even the ones that mkvextract(1) doesn't
143 support otherwise, but the resulting files might not be usable.
144 TID:outname
146 Causes extraction of the track with the ID TID into the file
147 outname if such a track exists in the source file. This option can
148 be given multiple times. The track IDs are the same as the ones
149 output by mkvmerge(1)'s --identify option.
150 Each output name should be used only once. The exception are
152 RealAudio and RealVideo tracks. If you use the same name for
153 different tracks then those tracks will be saved in the same file.
154 Example:
155 $ mkvextract input.mkv tracks 0:video.h264 2:output-two-vobsub-tracks.idx 3:output-two-vobsub-tracks.idx
157 Attachments extraction mode
159 Syntax: mkvextract source-filename attachments [options] AID1:outname1
160 [AID2:outname2 ...]
161 AID:outname
163 Causes extraction of the attachment with the ID AID into the file
164 outname if such an attachment exists in the source file. If the
165 outname is left empty then the name of the attachment inside the
166 source Matroska(TM) file is used instead. This option can be given
167 multiple times. The attachment IDs are the same as the ones output
168 by mkvmerge(1)'s --identify option.
169 Chapters extraction mode
171 Syntax: mkvextract source-filename chapters [options]
172 output-filename.xml
173 -s, --simple
175 Exports the chapter information in the simple format used in the
176 OGM tools (CHAPTER01=..., CHAPTER01NAME=...). In this mode some
177 information has to be discarded. Default is to output the chapters
178 in XML format.
179 --simple-language language
181 If the simple format is enabled then mkvextract(1) will only output
182 a single entry for each chapter atom encountered even if a chapter
183 atom contains more than one chapter name. By default mkvextract(1)
184 will use the first chapter name found for each atom regardless of
185 its language.
186 Using this option allows the user to determine which chapter names
188 are output if atoms contain more than one chapter name. The
189 language parameter must be an ISO 639-1 or ISO 639-2 code.
190 The chapters are written to specified output file. By default the XML
192 format understood by mkvmerge(1) is used. If no chapters are found in
193 the file, the output file is not created.
194 Tags extraction mode
196 Syntax: mkvextract source-filename tags [options] output-filename.xml
197 The tags are written to specified output file in the XML format
199 understood by mkvmerge(1). If no tags are found in the file, the output
200 file is not created.
201 Cue sheet extraction mode
203 Syntax: mkvextract source-filename cuesheet [options]
204 output-filename.cue
205 The cue sheet is written to specified output file. If no chapters or
207 tags are found in the file, the output file is not created.
208 Timestamp extraction mode
210 Syntax: mkvextract source-filename timestamps_v2 [options]
211 TID1:dest-filename1 [TID2:dest-filename2 ...]
212 TID:outname
214 Causes extraction of the timestamps for the track with the ID TID
215 into the file outname if such a track exists in the source file.
216 This option can be given multiple times. The track IDs are the same
217 as the ones output by mkvmerge(1)'s --identify option.
218 Example:
220 $ mkvextract input.mkv timestamps_v2 1:ts-track1.txt 2:ts-track2.txt
222 Cues extraction mode
224 Syntax: mkvextract source-filename cues [options] TID1:dest-filename1
225 [TID2:dest-filename2 ...]
226 TID:dest-filename
228 Causes extraction of the cues for the track with the ID TID into
229 the file outname if such a track exists in the source file. This
230 option can be given multiple times. The track IDs are the same as
231 the ones output by mkvmerge(1)'s --identify option and not the
232 numbers contained in the CueTrack element.
233 The format output is a simple text format: one line per CuePoint
235 element with key=value pairs. If an optional element is not present in
236 a CuePoint (e.g. CueDuration) then a dash will be output as the value.
237 Example:
239 timestamp=00:00:13.305000000 duration=- cluster_position=757741 relative_position=11
241 The possible keys are:
243 timestamp
245 The cue point's timestamp with nanosecond precision. The format is
246 HH:MM:SS.nnnnnnnnn. This element is always set.
247 duration
249 The cue point's duration with nanosecond precision. The format is
250 HH:MM:SS.nnnnnnnnn.
251 cluster_position
253 The absolute position in bytes inside the Matroska(TM) file where
254 the cluster containing the referenced element starts.
255 Note
257 Inside the Matroska(TM) file the CueClusterPosition is relative
258 to the segment's data start offset. The value output by
259 mkvextract(1)'s cue extraction mode, however, contains that
260 offset already and is an absolute offset from the beginning of
261 the file.
262 relative_position
264 The relative position in bytes inside the cluster where the
265 BlockGroup or SimpleBlock element the cue point refers to starts.
266 Note
268 Inside the Matroska(TM) file the CueRelativePosition is
269 relative to the cluster's data start offset. The value output
270 by mkvextract(1)'s cue extraction mode, however, is relative to
271 the cluster's ID. The absolute position inside the file can be
272 calculated by adding cluster_position and relative_position.
273 Example:
275 $ mkvextract input.mkv cues 1:cues-track1.txt 2:cues-track2.txt
277
279 Extracting both chapters and tags in their respective XML formats at
280 the same time:
281 $ mkvextract movie.mkv chapters movie-chapters.xml tags movie-tags.xml
283 Extracting a couple of tracks and their respective timestamps at the
285 same time:
286 $ mkvextract "Another Movie.mkv" tracks 0:video.h265 "1:main audio.aac" "2:director's comments.aac" timestamps_v2 "0:timestamps video.txt" "1:timestamps main audio.txt" "2:timestamps director's comments.txt"
288 Extracting chapters in the Ogg/OGM format and re-encoding a text
290 subtitle track to another character set:
291 $ mkvextract "My Movie.mkv" chapters --simple "My Chapters.txt" tracks -c MS-ANSI "2:My Subtitles.srt"
293
295 For an in-depth discussion about how all tools in the MKVToolNix suite
296 handle character set conversions, input/output encoding, command line
297 encoding and console encoding please see the identically-named section
298 in the mkvmerge(1) man page.
299
301 The decision about the output format is based on the track type, not on
302 the extension used for the output file name. The following track types
303 are supported at the moment:
304 A_AAC/MPEG2/*, A_AAC/MPEG4/*, A_AAC
306 All AAC files will be written into an AAC file with ADTS headers
307 before each packet. The ADTS headers will not contain the
308 deprecated emphasis field.
309 A_AC3, A_EAC3
311 These will be extracted to raw AC-3 files.
312 A_ALAC
314 ALAC tracks are written to CAF files.
315 A_DTS
317 These will be extracted to raw DTS files.
318 A_FLAC
320 FLAC tracks are written to raw FLAC files.
321 A_MPEG/L2
323 MPEG-1 Audio Layer II streams will be extracted to raw MP2 files.
324 A_MPEG/L3
326 These will be extracted to raw MP3 files.
327 A_OPUS
329 Opus(TM) tracks are written to OggOpus(TM) files.
330 A_PCM/INT/LIT, A_PCM/INT/BIG
332 Raw PCM data will be written to a WAV file. Big-endian integer data
333 will be converted to little-endian data in the process.
334 A_REAL/*
336 RealAudio(TM) tracks are written to RealMedia(TM) files.
337 A_TRUEHD, A_MLP
339 These will be extracted to raw TrueHD/MLP files.
340 A_TTA1
342 TrueAudio(TM) tracks are written to TTA files. Please note that due
343 to Matroska(TM)'s limited timestamp precision the extracted file's
344 header will be different regarding two fields: data_length (the
345 total number of samples in the file) and the CRC.
346 A_VORBIS
348 Vorbis audio will be written into an OggVorbis(TM) file.
349 A_WAVPACK4
351 WavPack(TM) tracks are written to WV files.
352 S_HDMV/PGS
354 PGS subtitles will be written as SUP files.
355 S_HDMV/TEXTST
357 TextST subtitles will be written as a special file format invented
358 for mkvmerge(1) and mkvextract(1).
359 S_KATE
361 Kate(TM) streams will be written within an Ogg(TM) container.
362 S_TEXT/SSA, S_TEXT/ASS, S_SSA, S_ASS
364 SSA and ASS text subtitles will be written as SSA/ASS files
365 respectively.
366 S_TEXT/UTF8, S_TEXT/ASCII
368 Simple text subtitles will be written as SRT files.
369 S_VOBSUB
371 VobSub(TM) subtitles will be written as SUB files along with the
372 respective index files, as IDX files.
373 S_TEXT/USF
375 USF text subtitles will be written as USF files.
376 S_TEXT/WEBVTT
378 WebVTT text subtitles will be written as WebVTT files.
379 V_MPEG1, V_MPEG2
381 MPEG-1 and MPEG-2 video tracks will be written as MPEG elementary
382 streams.
383 V_MPEG4/ISO/AVC
385 H.264 / AVC video tracks are written to H.264 elementary streams
386 which can be processed further with e.g. MP4Box(TM) from the
387 GPAC(TM) package.
388 V_MPEG4/ISO/HEVC
390 H.265 / HEVC video tracks are written to H.265 elementary streams
391 which can be processed further with e.g. MP4Box(TM) from the
392 GPAC(TM) package.
393 V_MS/VFW/FOURCC
395 Fixed FPS video tracks with this CodecID are written to AVI files.
396 V_REAL/*
398 RealVideo(TM) tracks are written to RealMedia(TM) files.
399 V_THEORA
401 Theora(TM) streams will be written within an Ogg(TM) container
402 V_VP8, V_VP9
404 VP8 / VP9 tracks are written to IVF files.
405 Tags
407 Tags are converted to a XML format. This format is the same that
408 mkvmerge(1) supports for reading tags.
409 Attachments
411 Attachments are written to the output file as they are. No
412 conversion whatsoever is done.
413 Chapters
415 Chapters are converted to a XML format. This format is the same
416 that mkvmerge(1) supports for reading chapters. Alternatively a
417 stripped-down version can be output in the simple OGM style format.
418 Timestamps
420 Timestamps are first sorted and then output as a timestamp v2
421 format compliant file ready to be fed to mkvmerge(1). The
422 extraction to other formats (v1, v3 and v4) is not supported.
423
425 mkvextract(1) exits with one of three exit codes:
426 • 0 -- This exit code means that extraction has completed
428 successfully.
429 • 1 -- In this case mkvextract(1) has output at least one warning,
431 but extraction did continue. A warning is prefixed with the text
432 'Warning:'. Depending on the issues involved the resulting files
433 might be ok or not. The user is urged to check both the warning and
434 the resulting files.
435 • 2 -- This exit code is used after an error occurred. mkvextract(1)
437 aborts right after outputting the error message. Error messages
438 range from wrong command line arguments over read/write errors to
439 broken files.
440
442 mkvextract(1) uses the default variables that determine the system's
443 locale (e.g. LANG and the LC_* family). Additional variables:
444 MKVEXTRACT_DEBUG, MKVTOOLNIX_DEBUG and its short form MTX_DEBUG
446 The content is treated as if it had been passed via the --debug
447 option.
448 MKVEXTRACT_ENGAGE, MKVTOOLNIX_ENGAGE and its short form MTX_ENGAGE
450 The content is treated as if it had been passed via the --engage
451 option.
452
454 mkvmerge(1), mkvinfo(1), mkvpropedit(1), mkvtoolnix-gui(1)
455
457 The latest version can always be found at the MKVToolNix homepage[1].
458
460 Moritz Bunkus <moritz@bunkus.org>
461 Developer
462
464 1. the MKVToolNix homepage
465 https://mkvtoolnix.download/
466MKVToolNix 80.0 2023-10-29 MKVEXTRACT(1)