1MKVMERGE(1) User Commands MKVMERGE(1)
2
6 mkvmerge - Merge multimedia streams into a Matroska file
7
11 mkvmerge [global options] -o out [options1] <file1> [[options2] <file2>
12 ...] [@optionsfile]
13
17 This program takes the input from several media files and joins their
18 streams (all of them or just a selection) into a Matroska file.
19 <http://www.matroska.org/> ⟨http://www.matroska.org/⟩
20 Global options:
24 -v, --verbose
26 Increase verbosity.
27 -q, --quiet
29 Suppress status output.
30 -o, --output out
32 Write to the file 'out'. If splitting is used then this parame‐
33 ter is treated a bit differently. See the --split parameter
34 discussion for details.
35 --title <title>
37 Sets the general title for the output file, e.g. the movie name.
38 --global-tags <file>
40 Read global tags from the XML file. See the section about tags
41 below for details.
42 --default-language <lng>
44 Sets the default language code. Unless overridden with the
45 --language option this language code will be used. The default
46 language code is 'und' for 'undefined'.
47 Chapter handling: (global options)
50 --chapter-language <language>
52 Sets the ISO639-2 language code that is written for each chapter
53 entry. Applies only to simple chapter files. Defaults to "eng".
54 See the section about chapters below for details.
55 --chapter-charset <charset>
57 Sets the charset that is used for the conversion to UTF-8 for
58 simple chapter files. Defaults to the current system locale.
59 This switch does also apply to chapters that are copied from an
60 Ogg/OGM file. See the section about chapters below for details.
61 --cue-chapter-name-format <format>
63 mkvmerge supports reading CUE sheets for audio files as the
64 input for chapters. CUE sheets usually contain the entries PER‐
65 FORMER and TITLE for each index entry. mkvmerge uses these two
66 strings in order to construct the chapter name. With this option
67 the format used for this name can be set. The following meta
68 characters are supported:
69 %p is replaced by the current entry's PERFORMER string,
70 %t is replaced by the current entry's TITLE string,
71 %n is replaced by the current track number and
72 %N is replaced by the current track number padded with a leading
73 zero if it is < 10.
74 Everything else is copied as-is.
75 If this option is not given then mkvmerge defaults to the format
76 '%p - %t' (the performer, followed by a space, a dash, another
77 space and the title).
78 --chapters <file>
80 Read chapter information from the file. See the section about
81 chapters below for details.
82 General output control (advanced global options):
85 --track-order <FID1:TID1[,FID2:TID2,...]>
87 This option changes the order in which the tracks for an input
88 file are created. The argument is a comma separated list of
89 pairs IDs. Each pair contains first the file ID which is simply
90 the number of the file on the command line starting at 0. The
91 second is a track ID from that file. If some track IDs are
92 omitted then those tracks are created after the ones given with
93 this option have been created.
94 --cluster-length n[ms]
96 Put at most n data blocks into each cluster. If the number is
97 postfixed with 'ms' then put at most n milliseconds of data into
98 each cluster. The maximum length for a cluster is 32767ms. Pro‐
99 grams will only be able to seek to clusters, so creating larger
100 clusters may lead to imprecise seeking and/or processing.
101 --no-cues
103 Tells mkvmerge not to create and write the cue data which can be
104 compared to an index in an AVI. Matroska files can be played
105 back without the cue data, but seeking will probably be impre‐
106 cise and slower. Use this only if you're really desperate for
107 space or for testing purposes. See also option --cues which can
108 be specified for each input file.
109 --no-clusters-in-meta-seek
111 Tells mkvmerge not to create a meta seek element at the end of
112 the file containing all clusters. See also the section about
113 MATROSKA FILE LAYOUT.
114 --disable-lacing
116 Disables lacing for all tracks. This will increase the file's
117 size, especially if there are many audio tracks. This option is
118 not intended for everyday use.
119 --enable-durations
121 Write durations for all blocks. This will increase file size and
122 does not offer any additional value for players at the moment.
123 --timecode-scale <n>
125 Forces the timecode scale factor to n. Valid values are in the
126 range 1000..10000000 or the value -1. Normally mkvmerge will
127 use a value of 1000000 which means that timecodes and durations
128 will have a precision of 1ms. For files that will not contain a
129 video track but at least one audio track mkvmerge will automati‐
130 cally chose a timecode scale factor so that all timecodes and
131 durations have a precision of one sample. This causes bigger
132 overhead but allows precise seeking and extraction. If the mag‐
133 ical value -1 is used then mkvmerge will use sample precision
134 even if a video track is present.
135 File splitting and linking (more global options):
138 --split size:<d[k|m|g]> or shorter --split <d[k|m|g]>
140 --split duration:<HH:MM:SS.nnnnnnnnn|ns> or shorter --split
142 <HH:MM:SS.nnnnnnnnn|ns>
143 --split timecodes:A[,B[,C...]]
145 Splits the output file after a given size or a given time.
146 Please note that tracks can only be split right before a key
147 frame. Due to buffering mkvmerge will split right before the
148 next key frame after the split point has been reached. There‐
149 fore the split point may be a bit off from what the user has
150 specified.
151 At the moment mkvmerge supports three different modes.
152 1. Splitting by size.
153 The parameter d may end with k, m or g to indicate that the size
154 is in KB, MB or GB respectively. Otherwise a size in Bytes is
155 assumed. After the current output file has reached this size
156 limit a new one will be started. The size: prefix may be omit‐
157 ted for compatibility reasons.
158 2. Splitting after a duration.
159 The paramter must have the form HH:MM:SS.nnnnnnnnn for specify‐
160 ing the duration in up to nano-second precision or a number n
161 followed by the letter 's' for the duration in seconds. "HH" is
162 the number of hours, "MM" the number of minutes, "SS" the number
163 of seconds and "nnnnnnnnn" the number of nanoseconds. Both the
164 number of hours and the number of nanoseconds can be omitted.
165 There can be up to nine digits after the decimal point. After
166 the duration of the contents in the current output has reached
167 this limit a new output file will be started. The duration:
168 prefix may be omitted for compatibility reasons.
169 3. Splitting after specific timecodes.
170 The parameters A, B etc must all have the same format as the
171 ones used for the duration (see above). The list of timecodes
172 is separated by commas. After the current file has reached the
173 current split point's timecode a new file is created. Then the
174 next split point given in this list is used. The timecodes:
175 prefix must not be omitted.
176 For this splitting mode the output filename is treated differ‐
177 ently than for the normal operation. It may contain a printf
178 like expression '%d' including an optional field width, e.g.
179 '%02d'. If it does then the current file number will be format‐
180 ted appropriately and inserted at that point in the filename.
181 If there is no such pattern then a pattern of '-%03d' is assumed
182 right before the file's extension: '-o output.mkv' would result
183 in 'output-001.mkv' and so on. If there's no extension then
184 '-%03d' will be appended to the name.
185 --split-max-files <n>
187 Create at most n files, even if the last file will be longer or
188 larger than indicated by --split.
189 --link Link files to one another when splitting the output file. See
191 the section FILE LINKING below for details.
192 --link-to-previous <SID>
194 Links the first output file to the segment with the given SID.
195 See the section FILE LINKING below for details.
196 --link-to-next <SID>
198 Links the last output file to the segment with the given SID.
199 See the section FILE LINKING below for details.
200 Attachment support (more global options):
203 --attachment-description <description>
205 Plain text description of the following attachment. Applies to
206 the next --attach-file or --attach-file-once command.
207 --attachment-mime-type <MIME type>
209 MIME type of the following attachment. Applies to the next
210 --attach-file or --attach-file-once command. A list of offi‐
211 cially recognized MIME types can be found e.g. at
212 <ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/media-
213 types> The MIME type is mandatory for an attachment.
214 --attachment-name <name>
216 Sets the name that will be stored in the output file for this
217 attachment. If this option is not given then the name will be
218 derived from the file name of the attachment as given with the
219 --attach-file or the --attach-file-once option.
220 --attach-file <file name>
222 --attach-file-once <file name>
224 Creates a file attachment inside the Matroska file. The MIME
225 type must have been set before this option can used. The
226 difference between the two forms is that during splitting the
227 files attached with --attach-file are attached to all output
228 files while the ones attached with --attach-file-once are only
229 attached to the first file created. If splitting is not used
230 then both do the same.
231 mkvextract can be used to extract attached files from a Matroska
232 file.
233 Note: If an input file is a Matroska file then the attached
234 files will not be copied to the output file(s). This may change
235 in the future.
236 Options that can be used for each input file:
240 -a, --atracks <n,m,...>
242 Copy the audio tracks n, m etc. The numbers are track IDs which
243 can be obtained with the --identify switch. They're not simply
244 the track numbers (see section TRACK IDS). Default: copy all
245 audio tracks.
246 -d, --vtracks <n,m,...>
248 Copy the video tracks n, m etc. The numbers are track IDs which
249 can be obtained with the --identify switch (see section TRACK
250 IDS). They're not simply the track numbers. Default: copy all
251 video tracks.
252 -s, --stracks <n,m,...>
254 Copy the subtitle tracks n, m etc. The numbers are track IDs
255 which can be obtained with the --identify switch (see section
256 TRACK IDS). They're not simply the track numbers. Default: copy
257 all subtitle tracks.
258 -b, --btracks <n,m,...>
260 Copy the button tracks n, m etc. The numbers are track IDs
261 which can be obtained with the --identify switch (see section
262 TRACK IDS). They're not simply the track numbers. Default:
263 copy all button tracks.
264 -A, --noaudio
266 Don't copy any audio track from this file.
267 -D, --novideo
269 Don't copy any video track from this file.
270 -S, --nosubs
272 Don't copy any subtitle track from this file.
273 -B, --nobuttons
275 Don't copy any button track from this file.
276 --no-chapters
278 If the source is a Matroska file then don't copy chapters from
279 it.
280 --no-attachments
282 If the source is a Matroska file then don't copy attachments
283 from it.
284 --no-tags
286 If the source is a Matroska file then don't copy tags from it.
287 -y, --sync <TID:d[,o[/p]]>
289 Synchronize manually, delay the audio track with the id TID by d
290 ms. The track IDs are the same as the ones given with --identify
291 (see section TRACK IDS).
292 d > 0: Pad with silent samples.
293 d < 0: Remove samples from the beginning.
294 o/p: adjust the timestamps by o/p to fix linear drifts. p
295 defaults to 1000 if omitted. Both o and p can be floating point
296 numbers.
297 Defaults: no manual sync correction (which is the same as d = 0
298 and o/p = 1.0).
299 This option can be used multiple times for an input file
300 applying to several tracks by selecting different track IDs each
301 time.
302 --delay <TID:x>
304 The delay to apply to the packets of the track by simply
305 adjusting the timecodes. The argument x must be postfixed with
306 s, ms, us or ns to specify seconds, milliseconds, microseconds
307 and nanoseconds respectively.
308 --cues <TID:none|iframes|all>
310 Controls for which tracks cue (index) entries are created for
311 the given track (see section TRACK IDS). none inhibits the
312 creation of cue entries. For iframes only blocks with no
313 backward or forward references ( = I frames in video tracks) are
314 put into the cue sheet. all causes mkvmerge to create cue
315 entries for all blocks which will make the file very big.
316 The default is iframes for video tracks and none for all others.
317 See also option --no-cues which inhibits the creation of cue
318 entries regardless of the --cues options used.
319 This option can be used multiple times for an input file
320 applying to several tracks by selecting different track IDs each
321 time.
322 --default-track <TID[:bool]>
324 Sets the 'default' flag for the given track (see section TRACK
325 IDS) if the optional argument bool is not present. If the user
326 does not explicitly select a track himself then the player
327 should prefer the track that has his 'default' flag set. Only
328 one track of each kind (audio, video, subtitles, buttons) can
329 have his 'default' flag set. If the user wants no track to have
330 the default track flag set then he has to set bool to 0 for all
331 tracks.
332 This option can be used multiple times for an input file
333 applying to several tracks by selecting different track IDs each
334 time.
335 --blockadd <TID:level>
337 Keep only the BlockAdditions up to this level for the given
338 track. The default is to keep all levels. This option only
339 affects certain kinds of codecs like WAVPACK4.
340 --track-name <TID:name>
342 Sets the track name for the given track (see section TRACK IDS)
343 to name.
344 --language <TID:language>
346 Sets the language for the given track (see section TRACK IDS).
347 Both ISO639-2 language codes and ISO639-1 country codes are
348 allowed. The country codes will be converted to language codes
349 automatically. All languages including their ISO639-2 codes can
350 be listed with the --list-languages option.
351 This option can be used multiple times for an input file
352 applying to several tracks by selecting different track IDs each
353 time.
354 -t, --tags <TID:file>
356 Read tags for the track with the number TID from the file. See
357 the section about tags below for details.
358 --aac-is-sbr <TID[:0|1]>
360 Tells mkvmerge that the track with the ID TID is SBR AAC (also
361 known as HE-AAC or AAC+). This options is needed if a) the
362 source file is an AAC file (NOT for a Matroska file) and b) the
363 AAC file contains SBR AAC data. The reason for this switch is
364 that it is technically impossible to automatically tell normal
365 AAC data from SBR AAC data without decoding a complete AAC
366 frame. As there are several patent issues with AAC decoders I
367 won't implement this decoding stage. So for SBR AAC files this
368 switch is mandatory. The resulting file might not play back
369 correctly or even not at all if the switch was omitted.
370 If the source file is a Matroska file then the CodecID should be
371 enough to detect SBR AAC. However, if the CodecID is wrong then
372 this switch can be used to correct that.
373 If mkvmerge wrongfully detects that an AAC file is SBR then you
374 can add ":0" to the track ID.
375 --timecodes <TID:filename>
377 Read the timecodes to be used for the specific track ID from
378 filename. These timecodes forcefully override the timecodes
379 that mkvmerge normally calculates. Read the section about
380 EXTERNAL TIMECODE FILES.
381 --default-duration <TID:x>
383 Forces the default duration of a given track to the specified
384 value. The argument x must be postfixed with s, ms, us, ns or
385 fps to specify the default duration in seconds, milliseconds,
386 microseconds, nanoseconds or "frames per second" respectively.
387 The number x itself can be a floating point number or a
388 fraction.
389 This argument is mainly useful for debugging purposes and should
390 normally not be used. If the default duration is not forced
391 then mkvmerge will try to derive the track's default duration
392 from the container and/or codec used. The only case in which
393 this option is of use is when adding AVC/h.264 elementary
394 streams because these do not contain information about their
395 number of frames or a default duration for each frame. For such
396 files mkvmerge will assume a default duration of 25fps unless
397 overridden.
398 --nalu-size-length <TID:n>
400 Forces the NALU size length to n bytes. This parameter is only
401 used if the AVC/h.264 elementary stream packetizer is used. If
402 left out it defaults to 2 bytes, but there are files that
403 contain frames or slices that are bigger than 65535 bytes. For
404 such files you have to use this parameter and increase the size
405 to 3 or mkvmerge will abort with an error.
406 --append-to <SFID1:STID1:DFID1:DTID1[,...]>
408 This option controls to which track another track is appended.
409 Each spec contains four IDs: a file ID, a track ID, another file
410 ID and a second track ID. The first pair, "source file ID" and
411 "source track ID", identifies the track that is to be appended.
412 The second pair, "destination file ID" and "destination track
413 ID", identifies the track the first one is appended to.
414 If this option has been omitted then a standard mapping is used.
415 This standard mapping appends each track from the current file
416 to a track from the previous file with the same track ID. This
417 allows for easy appending if a movie has been split into two
418 parts and both file have the same number of tracks and track IDs
419 with the command
420 mkvmerge -o output.mkv part1.mkv +part2.mkv
421 Options that only apply to video tracks:
424 -f, --fourcc <TID:FourCC>
426 Forces the FourCC to the specified value. Works only for video
427 tracks in the ´MS compatibility mode'.
428 --display-dimensions <TID:widthxheight>
430 Matroska files contain two values that set the display
431 properties that a player should scale the image on playback to:
432 display width and display height. These values can be set with
433 this option, e.g. '1:640x480'.
434 Another way to specify the values is to use the --aspect-ratio
435 or the --aspect-ratio-factor option (see below). These options
436 are mutually exclusive.
437 --aspect-ratio <TID:ar|w/h>
439 Matroska files contain two values that set the display
440 properties that a player should scale the image on playback to:
441 display width and display height. With this option mkvmerge
442 will automatically calculate the display width and display
443 height based on the image's original width and height and the
444 aspect ratio given with this option. The ratio can be given
445 either as a floating point number or as ´width/height', e.g.
446 16/9.
447 --aspect-ratio-factor <TID:ar|w/h>
449 Another way to set the aspect ratio is to specify a factor. The
450 original aspect ratio is first multiplied with this factor and
451 used as the target aspect ratio afterwards.
452 Another way to specify the values is to use the --aspect-ratio
453 option (see above). These options are mutually exclusive.
454 --cropping <TID:left,top,right,bottom>
456 Sets the pixel cropping parameters of a video track to the given
457 values.
458 --stereo-mode <TID:n|keyword>
460 Sets the stereo mode for the video track with the track ID TID.
461 The mode can either be a number n between 0 and 3 or one of the
462 keywords none (same as n=0), right (same as n=1), left (same as
463 n=2) or both (same as n=3).
464 Options that only apply to text subtitle tracks:
466 --sub-charset <TID:charset>
468 Sets the charset for the conversion to UTF-8 for UTF-8 subtitles
469 for the given track ID. If not specified the charset will be
470 derived from the current locale settings. Note that a charset is
471 not needed for subtitles read from Matroska files as these are
472 always stored in UTF-8.
473 This option can be used multiple times for an input file
474 applying to several tracks by selecting different track IDs each
475 time.
476 Options that only apply to VobSub subtitle tracks:
478 --compression <TID:method>
480 Selects the compression method to be used for the VobSub track.
481 Note that the player also has to support this method! Valid
482 values are 'none' and 'zlib'. The default is 'zlib'
483 compression.
484 Other options:
486 -i, --identify <filename>
488 Will let mkvmerge probe the single file and report its type, the
489 tracks contained in the file and their track IDs. If this option
490 is used then the only other option allowed is the filename.
491 -l, --list-types
493 Lists supported input file types.
494 --list-languages
496 Lists all languages and their ISO639-2 code which can be used
497 with the --language option.
498 --priority <priority>
500 Sets the process priority that mkvmerge runs with. Valid values
501 are "lowest", "lower", "normal", "higher" and "highest". If
502 nothing is given then "normal" is used. On Unix like systems
503 mkvmerge will use the nice(2) function. Therefore only the super
504 user can use "higher" and "highest". On Windows all values are
505 useable for every user.
506 --command-line-charset <charset>
508 Sets the charset to convert strings given on the command line
509 from. It defaults to the charset given by system's current
510 locale. This settings applies to arguments of the following
511 options: --title, --track-name and --attachment-description.
512 --output-charset <charset>
514 Sets the charset to which strings are converted that are to be
515 output. It defaults to the charset given by system's current
516 locale.
517 -r, --redirect-output <filename>
519 Writes all messages to the file filename instead of to the
520 console. While this can be done easily with output redirection
521 there are cases in which this option is needed: when the
522 terminal reinterprets the output before writing it to a file.
523 The charset set with --output-charset is honored.
524 @optionsfile
526 Reads additional command line arguments from the file
527 optionsfile. Lines whose first non-whitespace character is a
528 hash mark (#) are treated as comments and ignored. White spaces
529 at the start and end of a line will be stripped. Each line must
530 contain exactly one option. There is no meta character
531 escaping.
532 The command line mkvmerge -o "my file.mkv" -A "a movie.avi"
533 sound.ogg could be converted into the following option file:
534 # Write to the file "my file.mkv".
535 -o
536 my file.mkv
537 # Only take the video from "a movie.avi".
538 -A
539 a movie.avi
540 sound.ogg
541 -h, --help
543 Show usage information.
544 -V, --version
546 Show version information.
547
551 For each file the user can select which tracks mkvmerge should take.
552 They are all put into the file specified with '-o'. A list of known
553 (and supported) source formats can be obtained with the '-l' option.
554
558 Let's assume you have a file called MyMovie.avi and the audio track in
559 a separate file, e.g. MyMovie.wav. First you want to encode the audio
560 to OGG:
561 $ oggenc -q4 -oMyMovie.ogg MyMovie.wav
563 After a couple of minutes you can join video and audio:
565 $ mkvmerge -o MyMovie-with-sound.mkv MyMovie.avi MyMovie.ogg
567 If your AVI already contains an audio track then it will be copied as
569 well (if mkvmerge supports the audio format). To avoid that simply do
570 $ mkvmerge -o MyMovie-with-sound.mkv -A MyMovie.avi MyMovie.ogg
572 After some minutes of consideration you rip another audio track, e.g.
574 the director's comments or another language to MyMovie-add-audio.wav.
575 Encode it again and join it up with the other file:
576 $ oggenc -q4 -oMyMovie-add-audio.ogg MyMovie-add-audio.wav
578 $ mkvmerge -o MM-complete.mkv MyMovie-with-sound.mkv MyMovie-add-
579 audio.ogg
580 The same result can be achieved with
582 $ mkvmerge -o MM-complete.mkv -A MyMovie.avi MyMovie.ogg \
584 MyMovie-add-audio.ogg
585 Now fire up mplayer and enjoy. If you have multiple audio tracks (or
587 even video tracks) then you can tell mplayer which track to play with
588 the '-vid' and '-aid' parameters. These are 0-based and do not
589 distinguish between video and audio.
590 If you need an audio track synchronized you can do that easily. First
592 find out which track ID the Vorbis track has with
593 $ mkvmerge --identify outofsync.ogg
595 Now you can use that ID in the following command line:
597 $ mkvmerge -o goodsync.mkv -A source.avi -y 12345:200 outofsync.ogg
599 This would add 200ms of silence at the beginning of the audio track
601 with the ID 12345 taken from outofsync.ogg.
602 Some movies start synced correctly but slowly drift out of sync. For
604 these kind of movies you can specify a delay factor that is applied to
605 all timestamps - no data is added or removed. So if you make that
606 factor too big or too small you'll get bad results. An example is that
607 an episode I transcoded was 0.2 seconds out of sync at the end of the
608 movie which was 77340 frames long. At 29.97fps 0.2 seconds correspond
609 to approx. 6 frames. So I did
610 $ mkvmerge -o goodsync.mkv -y 23456:0,77346/77340 outofsync.mkv
612 The result was fine.
614 The sync options can also be used for subtitles in the same manner.
616 For text subtitles you can either use some Windows software (like
618 SubRipper) or the subrip package found in transcode(1)'s sources (in
619 contrib/subrip). The general process is:
620 1. extract a raw subtitle stream from the source:
622 $ tccat -i /path/to/copied/dvd/ -T 1 -L | \
623 tcextract -x ps1 -t vob -a 0x20 | \
624 subtitle2pgm -o mymovie
625 2. convert the resulting PGM images to text with gocr:
627 $ pgm2txt mymovie
628 3. spell-check the resulting text files:
630 $ ispell -d american *txt
631 4. convert the text files to a SRT file:
633 $ srttool -s -w -i mymovie.srtx -o mymovie.srt
634 The resulting file can be used as another input file for mkvmerge:
636 $ mkvmerge -o mymovie.mkv mymovie.avi mymovie.srt
638 If you want to specify the language for a given track then this is
640 easily done. First find out the ISO639-2 code for your language.
641 mkvmerge can list all of those codes for you:
642 $ mkvmerge --list-languages
644 Search the list for the languages you need. Let's assume you have put
646 two audio tracks into a Matroska file and want to set their language
647 codes and that their track IDs are 2 and 3. This can be done with
648 $ mkvmerge -o with-lang-codes.mkv --language 2:ger --language 3:dut
650 without-lang-codes.mkv
651 As you can see you can use the --language switch multiple times.
653 Maybe you'd also like to have the player use the Dutch language as the
655 default language. You also have extra subtitles, e.g. in English and
656 French, and want to have the player display the French ones by default.
657 This can be done with
658 $ mkvmerge -o with-lang-codes.mkv --language 2:ger --language 3:dut
660 --default-track 3 without-lang-codes.mkv --language 0:eng english.srt
661 --default-track 0 --language 0:fre french.srt
662 If you do not see the language or default track flags that you've
664 specified in mkvinfo's output then please read the section about
665 DEFAULT VALUES.
666
670 Some of the options for mkvmerge need a track ID to specify which track
671 they should be applied to. Those track IDs are printed by the readers
672 when demuxing the current input file, or if mkvmerge is called with the
673 --identify option. An example for such output:
674 $ mkvmerge -i v.mkv
676 File 'v.mkv': container: Matroska
677 Track ID 1: video (V_MS/VFW/FOURCC, DIV3)
678 Track ID 2: audio (A_MPEG/L3)
679 Track IDs are assigned like this:
681 * AVI files: The video track has the ID 0. All audio tracks get
683 the ID 1, 2...
684 * AAC, AC3, MP3, SRT and WAV files: The one 'track' in that file
686 gets the ID 0.
687 * Ogg/OGM files: The track's ID is its position in the Ogg stream.
689 The first stream encountered has the ID 0, the second one the ID
690 1 etc.
691 * Matroska files: The track's ID is the track number as reported
693 by mkvinfo or mkvmerge --identify. It is not the track UID.
694 The special track ID '-1' is a wild card and applies the given switch
696 to all tracks that are read from an input file. This was the behavior
697 of these switches prior to version 0.4.4.
698 The options that use the track IDs are the ones whose description
700 contains ´TID´. The following options use track IDs as well:
701 --atracks, --vtracks, --stracks and --btracks.
702
706 There are several text subtitle formats that can be embedded into
707 Matroska. At the moment mkvmerge supports only text subtitle formats.
708 These subtitles must be recoded to UTF-8 so that they can be displayed
709 correctly by a player.
710 mkvmerge does this conversion automatically based on the system's
712 current locale. If the subtitle charset is not the same as the system's
713 current charset then the user can use --sub-charset switch. If the
714 subtitles are already encoded in UTF-8 then you can use --sub-charset
715 UTF-8.
716 The following subtitle formats are supported at the moment:
718 * Subtitle Ripper (SRT) files
720 * Substation Alpha (SSA) / Advanced Substation Alpha scripts (ASS)
722
726 Matroska supports file linking which simply says that a specific file
727 is the predecessor or successor of the current file. To be precise,
728 it's not really the files that are linked but the Matroska segments. As
729 most files will probably only contain one Matroska segment I simply say
730 'file linking' although 'segment linking' would be more appropriate.
731 Each segment is identified by a unique 128 bit wide segment UID. This
733 UID is automatically generated by mkvmerge. The linking is done
734 primarily via putting the segment UIDs (short: SID) of the
735 previous/next file into the segment header information. mkvinfo(1)
736 prints these SIDs if it finds them.
737 If a file is split into several smaller ones and linking is used then
739 the timecodes will not start at 0 again but will continue where the
740 last file has left off. This way the absolute time is kept even if the
741 previous files are not available (e.g. when streaming). If no linking
742 is used then the timecodes should start at 0 for each file. By default
743 mkvmerge does not use file linking. If you want that you can turn it on
744 with the ´-link´ option. This option is only useful if splitting is
745 activated as well.
746 Regardless of whether splitting is active or not the user can tell
748 mkvmerge to link the produced files to specific SIDs. This is achieved
749 with the options '--link-to-previous' and '--link-to-next'. These
750 options accept a segment SID in the format that mkvinfo(1) outputs: 16
751 hexadecimal numbers between 0x00 and 0xff prefixed with '0x' each, e.g.
752 0x41 0xda 0x73 0x66 0xd9 0xcf 0xb2 0x1e 0xae 0x78 0xeb 0xb4 0x5e 0xca
753 0xb3 0x93. Alternatively a shorter form can be used: 16 hexadecimal
754 numbers between 0x00 and 0xff without the '0x' prefixes and without the
755 spaces, e.g. 41da7366d9cfb21eae78ebb45ecab393.
756 If splitting is used then the first file is linked to the SID given
758 with ´--link-to-previous´ and the last file is linked to the SID given
759 with ´--link-to-next´. If splitting is not used then the one output
760 file will be linked to both of the two SIDs.
761
765 The Matroska specs say that some elements have a default value. Usually
766 an element is not written to the file if its value is equal to its
767 default value in order to save space. The elements that the user might
768 miss in mkvinfo's output are the language and the default track flag.
769 The default value for the language is English (eng), and the default
770 value for the default track flag is true. Therefore if you used
771 --language 0:eng for a track then it will not show up in mkvinfo's
772 output.
773
777 Maybe you also want to keep some photos along with your Matroska file,
778 or you're using SSA subtitles and need a special TrueType font that's
779 really rare. In these cases you can attach those files to the Matroska
780 file. They will not be just appended to the file but embedded in it. A
781 player can then show those files (the 'photos' case) or use them to
782 render the subtitles (the 'TrueType fonts' case).
783 Here's an example how to attach a photo and a TrueType font to the
785 output file:
786 $ mkvmerge -o output.mkv -A video.avi sound.ogg
787 --attachment-description "Me and the band behind the stage in a small
788 get-together" --attachment-mime-type image/jpeg --attach-file
789 me_and_the_band.jpg --attachment-description "The real rare and
790 unbelievably good looking font" --attachment-type
791 application/octet-stream --attach-file really_cool_font.ttf
792
796 The Matroska chapter system is more powerful than the old known system
797 used by OGMs. The full specs can be found at
798 <http://www.matroska.org/technical/specs/chapters/index.html>
799 mkvmerge supports two kinds of chapter files as its input. The first
801 format, called 'simple chapter format', is the same format that the OGM
802 tools expect. The second format is a XML based chapter format which
803 supports all of Matroska's chapter functionality.
804 The simple chapter format
806 It looks basically like this:
808 CHAPTER01=00:00:00.000
810 CHAPTER01NAME=Intro
811 CHAPTER02=00:02:30.000
812 CHAPTER02NAME=Baby prepares to rock
813 CHAPTER03=00:02:42.300
814 CHAPTER03NAME=Baby rocks the house
815 mkvmerge will transform every pair or lines (CHAPTERxx and
817 CHAPTERxxNAME) into one Matroska ChapterAtom. It does not set any
818 ChapterTrackNumber which means that the chapters all apply to all
819 tracks in the file.
820 The charset used in the file is assumed to be the same charset that the
822 current system's locale returns. If this is not the case then the
823 switch --chapter-charset should be used. If the file contains a valid
824 BOM (byte order marker) then all UTF styles are converted
825 automatically. In this case --chapter-charset is simply ignored. You
826 can use mkvinfo or mkvextract to verify that the chapter names have
827 been converted properly.
828 The XML based chapter format
830 The XML based chapter format looks like this:
832 <?xml version="1.0" encoding="ISO-8859-1"?>
834 <!DOCTYPE Chapters SYSTEM "matroskachapters.dtd">
835 <Chapters>
836 <EditionEntry>
837 <ChapterAtom>
838 <ChapterTimeStart>00:00:30.000</ChapterTimeStart>
839 <ChapterTimeEnd>00:01:20.000</ChapterTimeEnd>
840 <ChapterDisplay>
841 <ChapterString>A short chapter</ChapterString>
842 <ChapterLanguage>eng</ChapterLanguage>
843 </ChapterDisplay>
844 <ChapterAtom>
845 <ChapterTimeStart>00:00:46.000</ChapterTimeStart>
846 <ChapterTimeEnd>00:01:10.000</ChapterTimeEnd>
847 <ChapterDisplay>
848 <ChapterString>A part of that short chapter</ChapterString>
849 <ChapterLanguage>eng</ChapterLanguage>
850 </ChapterDisplay>
851 </ChapterAtom>
852 </ChapterAtom>
853 </EditionEntry>
854 </Chapters>
855 With this format three things are possible that are not possible with
857 the simple chapter format: 1) The timestamp for the end of the chapter
858 can be set, 2) chapters can be nested, 3) the language and country can
859 be set.
860 The mkvtoolnix distribution contains some sample files in the doc
862 subdirectory which can be used as a basis.
863 General notes
865 When splitting files mkvmerge will correctly adjust the chapters as
868 well. This means that each file only includes the chapter entries that
869 apply to it, and that the timecodes will be offset to match the new
870 timecodes of each output file.
871 mkvmerge is able to copy chapters from Matroska source files unless
873 this is explicitly disabled with the --no-chapters option. At the
874 moment mkvmerge is limited to one 'bunch of chapters' globally. This
875 means that only the first chapter section found in all source files is
876 used. If the user specified chapters on the command line then these
877 take precedence over any chapters found in source files. mkvmerge does
878 not merge chapters. This must be done manually by using mkvextract to
879 extract the chapter information and editing the resulting files.
880 One shortcoming is that mkvmerge cannot parse chapter information found
882 in OGM files.
883
887 Introduction
888 Matroska supports an extensive set of tags that is deprecated and a
890 new, simpler system like it is is used in most other containers:
891 KEY=VALUE. However, in Matroska these tags can also be nested, and both
892 the KEY and the VALUE are elements of their own. The example file
893 example-tags-2.xml shows how to use this new system.
894 Scope of the tags
897 Matroska tags do not automatically apply to the complete file. They
899 can, but they also may apply to different parts of the file: to one or
900 more tracks, to one or more chapters, or even to a combination of both.
901 The aforementioned URL gives more details about this fact.
902 One important fact is that tags are linked to tracks or chapters with
905 the Targets Matroska tag element, and that the UIDs used for this
906 linking are NOT the track IDs mkvmerge uses everywhere. Instead the
907 numbers used are the UIDs which mkvmerge calculates automatically (if
908 the track is taken from a file format other than Matroska) or which are
909 copied from the source file if the track's source file is a Matroska
910 file. Therefore it is difficult to know which UIDs to use in the tag
911 file before the file is handed over to mkvmerge.
912 mkvmerge knows two options with which you can add tags to Matroska
915 files: The --global-tags and the --tags options. The difference is that
916 the former option, --global-tags, will make the tags apply to the
917 complete file by removing any of those Targets elements mentioned
918 above. The latter option, --tags, automatically inserts the UID that
919 mkvmerge generates for the tag specified with the TID part of the
920 --tags option.
921 Example
924 Let's say that you want to add tags to a video track read from an AVI.
926 mkvmerge -i file.avi tells you that the video track's ID (do not mix
927 this ID with the UID!) is 0. So you create your tag file, leave out any
928 Targets element and call mkvmerge:
929 $ mkvmerge -o file.mkv --tags 0:tags.xml file.avi
930 Tag file format
933 mkvmerge supports a XML based tag file format. The format is very easy
935 and closely connected to the Matroska tag specs found at the URL
936 mentioned above. Both the binary and the source mkvtoolnix
937 distributions come with a sample file called \xample-tags-2.xml which
938 simply lists all known tags and which can be used as a basis for real
939 life tag files.
940 The basics are:
943 * The outermost element must be <Tags>.
945 * One logical tag is contained inside one pair of <Tag> XML tags.
947 * White spaces directly before and after tag contents are ignored.
949 Data types
952 The new Matroska tagging system only knows two data types, a UTF-8
954 string and a binary type. The first is used for the tag's name and the
955 <String> element while the binary type is used for the <Binary> type.
956 As binary data itself would not fit into a XML file mkvmerge supports
959 two other methods of storing binary data. If the contents of a XML tag
960 starts with '@' then the following text is treated as a file name. The
961 corresponding file's content is copied into the Matroska element.
962 Otherwise the data is expected to be Base64 encoded. This is an
965 encoding that transforms binary data into a limited set of ASCII
966 characters and is used e.g. in email programs. mkvtoolnix comes with a
967 utility, base64tool, that can be used to encode to and decode from
968 Base64. mkvextract will output Base64 encoded data for binary elements.
969 The deprecated tagging system knows some more data types which can be
972 found in the official Matroska tag specs. The following two paragraphs
973 only apply to the deprecated tags (an example file is still available
974 and called example-tags-deprecated.xml):
975 The types integer, unsigned integer, float, string and UTF-8 string
978 look just like you expect them to: 4254, -2, 5.0, hello world and hello
979 world.
980 The date format used by both mkvmerge when reading XML tag files and by
983 mkvextract when outputting XML tag data is the ISO-8601 format. It has
984 the following structure: YYYY-MM-DDTHH:MM:SS+TZTZ. YYYY is the year
985 (four digits long), MM the month (two digits long starting with 01), DD
986 the day of the month (two digits long starting with 01), HH the hour of
987 the day (two digits long, range 00 - 23), MM the minute (two digits
988 long, range 00 - 59), SS the seconds (two digits long, range 00 - 59).
989 +TZTZ is the time zone, e.g. +0100 or -0200. An example would be
990 2003-07-30T19:10:16+0200.
991
996 The Matroska file layout is quite flexible. mkvmerge will render a file
997 in a predefined way. The resulting file looks like this:
998 [EBML head] [segment {meta seek #1} {attachments} {chapters} [segment
1000 information] [track information] [cluster 1] {cluster 2} ... {cluster
1001 n} {cues} {meta seek #2} {tags}]
1002 The elements in curly braces are optional and depend on the contents
1004 and options used. Some notes:
1005 * meta seek #1 includes only a small number of level 1 elements,
1007 and only if they actually exist: attachments, chapters, cues,
1008 tags, meta seek #2. Older versions of mkvmerge used to put the
1009 clusters into this meta seek element as well. Therefore some
1010 imprecise guessing was necessary to reserve enough space. It
1011 often failed. Now only the clusters are stored in meta seek #2,
1012 and meta seek #1 refers to the meta seek element #2.
1013 * Attachment, chapter and tag elements are only present if they
1015 were added.
1016 The shortest possible Matroska file would look like this:
1018 [EBML head] [segment [segment information] [track information] [cluster
1020 1]]
1021 This might be the case for audio-only files.
1023
1027 mkvmerge allows the user to chose the timecodes for a specific track
1028 himself. This can be used in order to create files with variable frame
1029 rate video or include gaps in audio. A frame in this case is the unit
1030 that mkvmerge creates separately per Matroska block. For video this is
1031 exactly one frame, for audio this is one packet of the specific audio
1032 type. E.g. for AC3 this would be a packet containing 1536 samples.
1033 Timecode files that are used when tracks are appended to each other
1035 must only be specified for the first part in a chain of tracks. For
1036 example if you append two files, v1.avi and v2.avi, and want to use
1037 timecodes then your command line must look something like this:
1038 mkvmerge ... --timecodes 0:my_timecodes.txt v1.avi +v2.avi
1039 There are three formats that are recognized by mkvmerge. The first line
1041 always contains the version number. Empty lines, lines containing only
1042 whitespace and lines beginning with '#' are ignored.
1043 Timecode file format v1
1045 This format starts with this line:
1047 # timecode format v1
1048 The second line gives the default number of frames per second:
1049 assume 27.930
1050 All following lines contain three numbers separated by commas: the
1051 start frame (0 is the first frame), the end frame and the number of
1052 frames in this range. The FPS is a floating point number with the dot
1053 default FPS is used. Example:
1054 800,1000,25
1055 1500,1700,30
1056 Timecode file format v2
1058 In this format each line contains a timecode for the next frame. This
1060 timecode must be given in ms precision. It can be a floating point
1061 number, but it doesn't have to be. You must give at least as many
1062 timecode lines as there are frames in the track. The timecodes in this
1063 file must be sorted. Example for 25fps:
1064 # timecode format v2
1065 0
1066 40
1067 80
1068 etc.
1069 Timecode file format v3
1071 In this format each line contains a duration in seconds followed by an
1073 optional number of frames per second. Both can be floating point
1074 numbers. If the number of frames per second is not present the default
1075 one is used. For audio you should let the codec calculate the frame
1076 timecodes itself. For that you should be using 0.0 as the number of
1077 frames per second. You can also create gaps in the stream by using the
1078 gap keyword followed by the duration of the gap. Example for an audio
1079 file:
1080 # timecode format v3
1081 assume 0.0
1082 25.325
1083 7.530,38.236
1084 gap, 10.050
1085 2.000,38.236
1086 etc.
1087 Timecode file format v4
1089 This format is identical to the v2 format. The only difference is that
1091 the timecodes do not have to be sorted. This format should almost
1092 never be used.
1093
1097 mkvmerge exits with one of three exit codes:
1098 0 This exit codes means that muxing has completed successfully.
1100 1 In this case mkvmerge has output at least one warning, but
1102 muxing did continue. A warning is prefixed with the text
1103 ´Warning:´. Depending on the issues involved the resulting file
1104 might be ok or not. The user is urged to check both the warning
1105 and the resulting file.
1106 2 This exit code is used after an error occured. mkvmerge aborts
1108 right after outputting the error message. Error messages range
1109 from wrong command line arguments over read/write errors to
1110 broken files.
1111
1115 What works (this list is probably outdated):
1116 * AVI as the video and audio source (only raw PCM, MP3 and AC3
1118 audio tracks at the moment)
1119 * OGG as the source for video, audio (Vorbis, raw PCM, MP3 and AC3
1121 audio) and text streams (subtitles).
1122 * WAV as the audio source
1124 * AAC audio files (ADTS AAC files and AAC from MP4)
1126 * AC3 audio files
1128 * DTS audio files
1130 * MP3 audio files
1132 * RealVideo and RealAudio from RealMedia files
1134 * FLAC audio files (both raw FLAC and OggFLAC)
1136 * Track selection
1138 * Manual audio synchronization by adding silence/removing packets
1140 for Vorbis audio and for text streams by adjusting the starting
1141 point and duration.
1142 * Manual audio synchronization for AAC, AC3, DTS and MP3 audio by
1144 duplicating or removing packets at the beginning.
1145 * Text subtitles can be read from SRT (SubRipper / subrip) files
1147 or taken from other OGM files.
1148 * SSA/ASS subtitles from SSA/ASS files
1150 * Simple chapters.
1152 * Full tags support.
1154 What not works:
1156 * Manual audio synchronization for PCM sound (who needs it
1158 anyway?)
1159
1163 mkvmerge was written by Moritz Bunkus <moritz@bunkus.org>.
1164
1166 mkvinfo(1), mkvextract(1), mmg(1)
1167
1169 The newest version can always be found at
1170 <http://www.bunkus.org/videotools/mkvtoolnix/>
1171 ⟨http://www.bunkus.org/videotools/mkvtoolnix/⟩
1172mkvmerge v2.1.0 August 2007 MKVMERGE(1)