1MKVEXTRACT(1)                    User Commands                   MKVEXTRACT(1)
2
3
4

NAME

6       mkvextract - extract tracks from Matroska(TM) files into other files
7

SYNOPSIS

9       mkvextract {source-filename} {mode1} [options] [extraction-spec1]
10                  [mode2] [options] [extraction-spec2] [...]
11

DESCRIPTION

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
17       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
24       Currently supported is the extraction of tracks, tags, attachments,
25       chapters, CUE sheets, timestamps and cues.
26
27   Common options
28       The following options are available in all modes and only described
29       once in this section.
30
31       -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
40       --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
45       --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
50       -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
57       --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
67       --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
72       --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
76       --debug topic
77           Turn on debugging for a specific feature. This option is only
78           useful for developers.
79
80       --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
85       --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
93       -v, --verbose
94           Be verbose and show all the important Matroska(TM) elements as
95           they're read.
96
97       -h, --help
98           Show usage information and exit.
99
100       -V, --version
101           Show version information and exit.
102
103       @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
108   Track extraction mode
109       Syntax: mkvextract source-filename tracks [options] TID1:dest-filename1
110       [TID2:dest-filename2 ...]
111
112       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
116       -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
121       --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
126       --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
131       --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
138       --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
145       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
151           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
156               $ mkvextract input.mkv tracks 0:video.h264 2:output-two-vobsub-tracks.idx 3:output-two-vobsub-tracks.idx
157
158   Attachments extraction mode
159       Syntax: mkvextract source-filename attachments [options] AID1:outname1
160       [AID2:outname2 ...]
161
162       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
170   Chapters extraction mode
171       Syntax: mkvextract source-filename chapters [options]
172       output-filename.xml
173
174       -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
180       --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
187           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
191       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
195   Tags extraction mode
196       Syntax: mkvextract source-filename tags [options] output-filename.xml
197
198       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
202   Cue sheet extraction mode
203       Syntax: mkvextract source-filename cuesheet [options]
204       output-filename.cue
205
206       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
209   Timestamp extraction mode
210       Syntax: mkvextract source-filename timestamps_v2 [options]
211       TID1:dest-filename1 [TID2:dest-filename2 ...]
212
213       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
219           Example:
220
221               $ mkvextract input.mkv timestamps_v2 1:ts-track1.txt 2:ts-track2.txt
222
223   Cues extraction mode
224       Syntax: mkvextract source-filename cues [options] TID1:dest-filename1
225       [TID2:dest-filename2 ...]
226
227       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
234       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
238       Example:
239
240           timestamp=00:00:13.305000000 duration=- cluster_position=757741 relative_position=11
241
242       The possible keys are:
243
244       timestamp
245           The cue point's timestamp with nanosecond precision. The format is
246           HH:MM:SS.nnnnnnnnn. This element is always set.
247
248       duration
249           The cue point's duration with nanosecond precision. The format is
250           HH:MM:SS.nnnnnnnnn.
251
252       cluster_position
253           The absolute position in bytes inside the Matroska(TM) file where
254           the cluster containing the referenced element starts.
255
256               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
263       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
267               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
274       Example:
275
276           $ mkvextract input.mkv cues 1:cues-track1.txt 2:cues-track2.txt
277

EXAMPLES

279       Extracting both chapters and tags in their respective XML formats at
280       the same time:
281
282           $ mkvextract movie.mkv chapters movie-chapters.xml tags movie-tags.xml
283
284       Extracting a couple of tracks and their respective timestamps at the
285       same time:
286
287           $ 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
289       Extracting chapters in the Ogg/OGM format and re-encoding a text
290       subtitle track to another character set:
291
292           $ mkvextract "My Movie.mkv" chapters --simple "My Chapters.txt" tracks -c MS-ANSI "2:My Subtitles.srt"
293

TEXT FILES AND CHARACTER SET CONVERSIONS

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

OUTPUT FILE FORMATS

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
305       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
310       A_AC3, A_EAC3
311           These will be extracted to raw AC-3 files.
312
313       A_ALAC
314           ALAC tracks are written to CAF files.
315
316       A_DTS
317           These will be extracted to raw DTS files.
318
319       A_FLAC
320           FLAC tracks are written to raw FLAC files.
321
322       A_MPEG/L2
323           MPEG-1 Audio Layer II streams will be extracted to raw MP2 files.
324
325       A_MPEG/L3
326           These will be extracted to raw MP3 files.
327
328       A_OPUS
329           Opus(TM) tracks are written to OggOpus(TM) files.
330
331       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
335       A_REAL/*
336           RealAudio(TM) tracks are written to RealMedia(TM) files.
337
338       A_TRUEHD, A_MLP
339           These will be extracted to raw TrueHD/MLP files.
340
341       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
347       A_VORBIS
348           Vorbis audio will be written into an OggVorbis(TM) file.
349
350       A_WAVPACK4
351           WavPack(TM) tracks are written to WV files.
352
353       S_HDMV/PGS
354           PGS subtitles will be written as SUP files.
355
356       S_HDMV/TEXTST
357           TextST subtitles will be written as a special file format invented
358           for mkvmerge(1) and mkvextract(1).
359
360       S_KATE
361           Kate(TM) streams will be written within an Ogg(TM) container.
362
363       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
367       S_TEXT/UTF8, S_TEXT/ASCII
368           Simple text subtitles will be written as SRT files.
369
370       S_VOBSUB
371           VobSub(TM) subtitles will be written as SUB files along with the
372           respective index files, as IDX files.
373
374       S_TEXT/USF
375           USF text subtitles will be written as USF files.
376
377       S_TEXT/WEBVTT
378           WebVTT text subtitles will be written as WebVTT files.
379
380       V_MPEG1, V_MPEG2
381           MPEG-1 and MPEG-2 video tracks will be written as MPEG elementary
382           streams.
383
384       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
389       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
394       V_MS/VFW/FOURCC
395           Fixed FPS video tracks with this CodecID are written to AVI files.
396
397       V_REAL/*
398           RealVideo(TM) tracks are written to RealMedia(TM) files.
399
400       V_THEORA
401           Theora(TM) streams will be written within an Ogg(TM) container
402
403       V_VP8, V_VP9
404           VP8 / VP9 tracks are written to IVF files.
405
406       Tags
407           Tags are converted to a XML format. This format is the same that
408           mkvmerge(1) supports for reading tags.
409
410       Attachments
411           Attachments are written to the output file as they are. No
412           conversion whatsoever is done.
413
414       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
419       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

EXIT CODES

425       mkvextract(1) exits with one of three exit codes:
426
4270 -- This exit code means that extraction has completed
428           successfully.
429
4301 -- 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
4362 -- 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

ENVIRONMENT VARIABLES

442       mkvextract(1) uses the default variables that determine the system's
443       locale (e.g.  LANG and the LC_* family). Additional variables:
444
445       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
449       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

SEE ALSO

454       mkvmerge(1), mkvinfo(1), mkvpropedit(1), mkvtoolnix-gui(1)
455

WWW

457       The latest version can always be found at the MKVToolNix homepage[1].
458

AUTHOR

460       Moritz Bunkus <moritz@bunkus.org>
461           Developer
462

NOTES

464        1. the MKVToolNix homepage
465           https://mkvtoolnix.download/
466
467
468
469MKVToolNix 80.0                   2023-10-29                     MKVEXTRACT(1)
Impressum