Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MKVPROPEDIT(1)			 User Commands			MKVPROPEDIT(1)

NAME
       mkvpropedit - Modify properties of existing Matroska(TM)	files without
       a complete remux

SYNOPSIS
       mkvpropedit [options] {source-filename} {actions}

DESCRIPTION
       This program analyses an	existing Matroska(TM) file and modifies	some
       of its properties. Then it writes those modifications to	the existing
       file. Among the properties that can be changed are the segment
       information elements (e.g. the title) and the track headers (e.g. the
       language	code, 'default track' flag or the name).

       Options:

       -l, --list-property-names
	   Lists all known and editable	property names,	their type (string,
	   integer, boolean etc) and a short description. The program exits
	   afterwards. Therefore the source-filename parameter does not	have
	   to be supplied.

       -p, --parse-mode	mode
	   Sets	the parse mode.	The parameter 'mode' can either	be 'fast'
	   (which is also the default) or 'full'. The 'fast' mode does not
	   parse the whole file	but uses the meta seek elements	for locating
	   the required	elements of a source file. In 99% of all cases this is
	   enough. But for files that do not contain meta seek elements	or
	   which are damaged the user might have to set	the 'full' parse mode.
	   A full scan of a file can take a couple of minutes while a fast
	   scan	only takes seconds.

       Actions that deal with track and	segment	info properties:

       -e, --edit selector
	   Sets	the Matroska(TM) file section (segment information or a
	   certain track's headers) that all following add, set	and delete
	   actions operate on. This option can be used multiple	times in order
	   to make modifications to more than one element.

	   By default mkvpropedit(1) will edit the segment information
	   section.

	   See the section about edit selectors	for a full description of the
	   syntax.

       -a, --add name=value
	   Adds	a property name	with the value value. The property will	be
	   added even if such a	property exists	already. Note that most
	   properties are unique and cannot occur more than once.

       -s, --set name=value
	   Sets	all occurrences	of the property	name to	the value value. If no
	   such	property exists	then it	will be	added.

       -d, --delete name
	   Deletes all occurrences of the property name. Note that some
	   properties are required and cannot be deleted.

       Actions that deal with tags and chapters:

       -t, --tags selector:filename
	   Add or replace tags in the file with	the ones from filename or
	   remove them if filename is empty.  mkvpropedit(1) reads the same
	   XML tag format that mkvmerge(1) reads as well.

	   The selector	must be	one of the words all, global or	track. For all
	   mkvpropedit(1) will replace or remove all tags in a file. With
	   global only global tags will	be replaced or removed.

	   With	track mkvpropedit(1) will replace tags for a specific track.
	   Additionally	the tags read from filename will be assigned to	the
	   same	track. The track is specified in the same way edit selectors
	   are specified (see below), e.g.  --tags
	   track:a1:new-audio-tags.xml.

       --add-track-statistics-tags
	   Calculates statistics for all tracks	in a file and adds new
	   statistics tags for them. If	the file already contains such tags
	   then	they'll	be updated.

       --delete-track-statistics-tags
	   Deletes all existing	track statistics tags from a file. If the file
	   doesn't contain track statistics tags then it won't be modified.

       -c, --chapters filename
	   Add or replace chapters in the file with the	ones from filename or
	   remove them if filename is empty.  mkvpropedit(1) reads the same
	   XML and simple chapter formats that mkvmerge(1) reads as well.

       Actions for handling attachments:

       --add-attachment	filename
	   Adds	a new attachment from filename.

	   If the option --attachment-name has been used prior to this option
	   then	its value is used as the new attachment's name.	Otherwise it
	   is derived from filename.

	   If the option --attachment-mime-type	has been used prior to this
	   option then its value is used as the	new attachment's MIME type.
	   Otherwise it	is auto-detected from the content of filename.

	   If the option --attachment-description has been used	prior to this
	   option then its value is used as the	new attachment's description.
	   Otherwise no	description will be set.

	   If the option --attachment-uid has been used	prior to this option
	   then	its value is used as the new attachment's UID. Otherwise a
	   random UID will be generated	automatically.

       --replace-attachment selector:filename
	   Replaces one	or more	attachments that match selector	with the file
	   filename. If	more than one existing attachment matches selector
	   then	all of their contents will be replaced by the content of
	   filename.

	   The selector	can have one of	four forms. They're explained below in
	   the section attachment selectors.

	   If the option --attachment-name has been used prior to this option
	   then	its value is set as the	new name for each modified attachment.
	   Otherwise the names aren't changed.

	   If the option --attachment-mime-type	has been used prior to this
	   option then its value is set	as the new MIME	type for each modified
	   attachment. Otherwise the MIME types	aren't changed.

	   If the option --attachment-description has been used	prior to this
	   option then its value is set	as the new description for each
	   modified attachment.	Otherwise the descriptions aren't changed.

	   If the option --attachment-uid has been used	prior to this option
	   then	its value is set as the	new UID	for each modified attachment.
	   Otherwise the UIDs aren't changed.

       --update-attachment selector
	   Sets	the properties of one or more attachments that match selector.
	   If more than	one existing attachment	matches	selector then all of
	   their properties will be updated.

	   The selector	can have one of	four forms. They're explained below in
	   the section attachment selectors.

	   If the option --attachment-name has been used prior to this option
	   then	its value is set as the	new name for each modified attachment.
	   Otherwise the names aren't changed.

	   If the option --attachment-mime-type	has been used prior to this
	   option then its value is set	as the new MIME	type for each modified
	   attachment. Otherwise the MIME types	aren't changed.

	   If the option --attachment-description has been used	prior to this
	   option then its value is set	as the new description for each
	   modified attachment.	Otherwise the descriptions aren't changed.

	   If the option --attachment-uid has been used	prior to this option
	   then	its value is set as the	new UID	for each modified attachment.
	   Otherwise the UIDs aren't changed.

       --delete-attachment selector
	   Deletes one or more attachments that	match selector.

	   The selector	can have one of	four forms. They're explained below in
	   the section attachment selectors.

       Options for attachment actions:

       --attachment-name name
	   Sets	the name to use	for the	following --add-attachment or
	   --replace-attachment	operation.

       --attachment-mime-type mime-type
	   Sets	the MIME type to use for the following --add-attachment	or
	   --replace-attachment	operation.

       --attachment-description	description
	   Sets	the description	to use for the following --add-attachment or
	   --replace-attachment	operation.

       Other options:

       --disable-language-ietf
	   Normally when the user requests changes to the 'language' track
	   header property, mkvpropedit(1) will	apply the same change to the
	   new LanguageIETF track header element in addition to	the legacy
	   Language element. If	this option is used, the change	is only
	   applied to the legacy Language element.

	   This	option does not	affect changes requested via the
	   'language-ietf' track header	property.

       --command-line-charset 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.

       --output-charset	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.

       -r, --redirect-output 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	--output-charset is honored.

       --ui-language code
	   Forces the translations for the language code to be used (e.g.
	   'de_DE' for the German translations). Entering 'list' as the	code
	   will	cause the program to output a list of available	translations.

       --abort-on-warnings
	   Tells the program to	abort after the	first warning is emitted. The
	   program's exit code will be 1.

       --debug topic
	   Turn	on debugging for a specific feature. This option is only
	   useful for developers.

       --engage	feature
	   Turn	on experimental	features. A list of available features can be
	   requested with mkvpropedit --engage list. These features are	not
	   meant to be used in normal situations.

       --gui-mode
	   Turns on GUI	mode. In this mode specially-formatted lines may be
	   output that can tell	a controlling GUI what's happening. These
	   messages follow the format '#GUI#message'. The message may be
	   followed by key/value pairs as in
	   '#GUI#message#key1=value1#key2=value2...'. Neither the messages nor
	   the keys are	ever translated	and always output in English.

       -v, --verbose
	   Be verbose and show all the important Matroska(TM) elements as
	   they're read.

       -h, --help
	   Show	usage information and exit.

       -V, --version
	   Show	version	information and	exit.

       @options-file.json
	   Reads additional command line arguments from	the file options-file.
	   For a full explanation on the supported formats for such files see
	   the section called "Option files" in	the mkvmerge(1)	man page.

EDIT SELECTORS
       The --edit option sets the Matroska(TM) file section (segment
       information or a	certain	track's	headers) that all following add, set
       and delete actions operate on. This stays valid until the next --edit
       option is found.	The argument to	this option is called the edit
       selector.

       By default mkvpropedit(1) will edit the segment information section.

   Segment information
       The segment information can be selected with one	of these three words:
       'info', 'segment_info' or 'segmentinfo'.	It contains properties like
       the segment title or the	segment	UID.

   Track headers
       Track headers can be selected with a slightly more complex selector.
       All variations start with 'track:'. The track header properties include
       elements	like the language code,	'default track'	flag or	the track's
       name.

       track:n
	   If the parameter n is a number then the nth track will be selected.
	   The track order is the same that mkvmerge(1)'s --identify option
	   outputs.

	   Numbering starts at 1.

       track:tn
	   If the parameter starts with	a single character t followed by a n
	   then	the nth	track of a specific track type will be selected. The
	   track type parameter	t must be one of these four characters:	'a'
	   for an audio	track, 'b' for a button	track, 's' for a subtitle
	   track and 'v' for a video track. The	track order is the same	that
	   mkvmerge(1)'s --identify option outputs.

	   Numbering starts at 1.

       track:=uid
	   If the parameter starts with	a '=' followed by a number uid,	the
	   track whose track UID element equals	the given uid will be
	   selected. Track UIDs	can be obtained	with mkvinfo(1).

       track:@number
	   If the parameter starts with	a '@' followed by a number number, the
	   track whose track number element equals this	number will be
	   selected. Track numbers can be obtained with	mkvinfo(1).

   Notes
       Due to the nature of the	track edit selectors it	is possible that
       several selectors actually match	the same track headers.	In such	cases
       all actions for those edit selectors will be combined and executed in
       the order in which they're given	on the command line.

ATTACHMENT SELECTORS
       An attachment selector is used with the two actions
       --replace-attachment and	--delete-attachment. It	can have one of	the
       following four forms:

	1. Selection by	attachment ID. In this form the	selector is simply a
	   number, the attachment's ID as output by mkvmerge(1)'s
	   identification command.

	2. Selection by	attachment UID (unique ID). In this form the selector
	   is the equal	sign = followed	by a number, the attachment's unique
	   ID as output	by mkvmerge(1)'s verbose identification	command.

	3. Selection by	attachment name. In this form the selector is the
	   literal word	name: followed by the existing attachment's name. If
	   this	selector is used with --replace-attachment then	colons within
	   the name to match must be escaped as	\c.

	4. Selection by	MIME type. In this form	the selector is	the literal
	   word	mime-type: followed by the existing attachment's MIME type. If
	   this	selector is used with --replace-attachment then	colons within
	   the MIME type to match must be escaped as \c.

EXAMPLES
       The following example edits a file called 'movie.mkv'. It sets the
       segment title and modifies the language code of an audio	and a subtitle
       track. Note that	this example can be shortened by leaving out the first
       --edit option because editing the segment information element is	the
       default for all options found before the	first --edit option anyway.

	   $ mkvpropedit movie.mkv --edit info --set "title=The	movie" --edit track:a1 --set language=fre --edit track:a2 --set	language=ita

       The second example removes the 'default track flag' from	the first
       subtitle	track and sets it for the second one. Note that
       mkvpropedit(1), unlike mkvmerge(1), does	not set	the 'default track
       flag' of	other tracks to	'0' if it is set to '1'	for a different	track
       automatically.

	   $ mkvpropedit movie.mkv --edit track:s1 --set flag-default=0	--edit track:s2	--set flag-default=1

       Replacing the tags for the second subtitle track	in a file looks	like
       this:

	   $ mkvpropedit movie.mkv --tags track:s2:new-subtitle-tags.xml

       Removing	all tags requires leaving out the file name:

	   $ mkvpropedit movie.mkv --tags all:

       Replacing the chapters in a file	looks like this:

	   $ mkvpropedit movie.mkv --chapters new-chapters.xml

       Removing	all chapters requires leaving out the file name:

	   $ mkvpropedit movie.mkv --chapters ''

       Adding a	font file (Arial.ttf) as an attachment:

	   $ mkvpropedit movie.mkv --add-attachment Arial.ttf

       Adding a	font file (89719823.ttf) as an attachment and providing	some
       information as it really	is just	Arial:

	   $ mkvpropedit movie.mkv --attachment-name Arial.ttf --attachment-description	'The Arial font	as a TrueType font' --attachment-mime-type application/x-truetype-font --add-attachment	89719823.ttf

       Replacing one attached font (Comic.ttf) file with another one
       (Arial.ttf):

	   $ mkvpropedit movie.mkv --attachment-name Arial.ttf --attachment-description	'The Arial font	as a TrueType font' --replace-attachment name:Comic.ttf:Arial.ttf

       Deleting	the second attached file, whatever it may be:

	   $ mkvpropedit movie.mkv --delete-attachment 2

       Deleting	all attached fonts by MIME type:

	   $ mkvpropedit movie.mkv --delete-attachment mime-type:application/x-truetype-font

EXIT CODES
       mkvpropedit(1) exits with one of	three exit codes:

       o   0 --	This exit code means that the modification has completed
	   successfully.

       o   1 --	In this	case mkvpropedit(1) has	output at least	one warning,
	   but the modification	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.

       o   2 --	This exit code is used after an	error occurred.
	   mkvpropedit(1) aborts right after outputting	the error message.
	   Error messages range	from wrong command line	arguments over
	   read/write errors to	broken files.

TEXT FILES AND CHARACTER SET CONVERSIONS
       For an in-depth discussion about	how all	tools in the MKVToolNix	suite
       handle character	set conversions, input/output encoding,	command	line
       encoding	and console encoding please see	the identically-named section
       in the mkvmerge(1) man page.

ENVIRONMENT VARIABLES
       mkvpropedit(1) uses the default variables that determine	the system's
       locale (e.g.  LANG and the LC_* family).	Additional variables:

       MKVPROPEDIT_DEBUG, MKVTOOLNIX_DEBUG and its short form MTX_DEBUG
	   The content is treated as if	it had been passed via the --debug
	   option.

       MKVPROPEDIT_ENGAGE, MKVTOOLNIX_ENGAGE and its short form	MTX_ENGAGE
	   The content is treated as if	it had been passed via the --engage
	   option.

SEE ALSO
       mkvmerge(1), mkvinfo(1),	mkvextract(1), mkvtoolnix-gui(1)

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

AUTHOR
       Moritz Bunkus <moritz@bunkus.org>
	   Developer

NOTES
	1. the MKVToolNix homepage
	   https://mkvtoolnix.download/

MKVToolNix 54.0.0		  2021-02-26			MKVPROPEDIT(1)

NAME | SYNOPSIS | DESCRIPTION | EDIT SELECTORS | ATTACHMENT SELECTORS | EXAMPLES | EXIT CODES | TEXT FILES AND CHARACTER SET CONVERSIONS | ENVIRONMENT VARIABLES | SEE ALSO | WWW | AUTHOR | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mkvpropedit&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help