mirror of
https://gitlab.com/mbunkus/mkvtoolnix.git
synced 2024-10-22 07:21:21 +00:00
899 lines
37 KiB
XML
899 lines
37 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
|
|
[
|
|
<!ENTITY product "mkvpropedit">
|
|
<!ENTITY version "88.0">
|
|
<!ENTITY date "2024-10-19">
|
|
|
|
<!ENTITY mkvmerge "<citerefentry><refentrytitle>mkvmerge</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
|
<!ENTITY mkvinfo "<citerefentry><refentrytitle>mkvinfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
|
<!ENTITY mkvextract "<citerefentry><refentrytitle>mkvextract</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
|
<!ENTITY mkvpropedit "<citerefentry><refentrytitle>mkvpropedit</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
|
<!ENTITY mtxgui "<citerefentry><refentrytitle>mkvtoolnix-gui</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
|
|
|
|
<!ENTITY matroska "<productname>Matroska</productname>">
|
|
<!ENTITY oggvorbis "<productname>OggVorbis</productname>">
|
|
<!ENTITY xml "<abbrev>XML</abbrev>">
|
|
|
|
]>
|
|
|
|
<refentry lang="en" id="mkvextract">
|
|
<refentryinfo>
|
|
<productname>&product;</productname>
|
|
<date>&date;</date>
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Moritz</firstname>
|
|
<surname>Bunkus</surname>
|
|
<email>moritz@bunkus.org</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
<refmeta>
|
|
<refentrytitle>&product;</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="version">&version;</refmiscinfo>
|
|
<refmiscinfo class="date">&date;</refmiscinfo>
|
|
<refmiscinfo class="source">MKVToolNix</refmiscinfo>
|
|
<refmiscinfo class="manual">User Commands</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>&product;</refname>
|
|
<refpurpose>Modify properties of existing &matroska; files without a complete remux</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv id="mkvpropedit.synopsis">
|
|
<title>Synopsis</title>
|
|
<cmdsynopsis>
|
|
<command>mkvpropedit</command>
|
|
<arg>options</arg>
|
|
<arg choice="req">source-filename</arg>
|
|
<arg choice="req">actions</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="mkvpropedit.description">
|
|
<title>Description</title>
|
|
<para>
|
|
This program analyses an existing &matroska; 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).
|
|
</para>
|
|
|
|
<para>
|
|
Options:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.description.list_property_names">
|
|
<term><option>-l</option>, <option>--list-property-names</option></term>
|
|
<listitem>
|
|
<para>
|
|
Lists all known and editable property names, their type (string, integer, boolean etc) and a short description. The program exits
|
|
afterwards. Therefore the <parameter>source-filename</parameter> parameter does not have to be supplied.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.parse_mode">
|
|
<term><option>-p</option>, <option>--parse-mode</option> <parameter>mode</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the parse mode. The parameter '<parameter>mode</parameter>' can either be '<literal>fast</literal>' (which is also the default)
|
|
or '<literal>full</literal>'. The '<literal>fast</literal>' 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 '<literal>full</literal>' parse mode. A full scan of a file can take a
|
|
couple of minutes while a fast scan only takes seconds.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Actions that deal with track and segment info properties:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.description.edit">
|
|
<term><option>-e</option>, <option>--edit</option> <parameter>selector</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the &matroska; file section (segment information or a certain track's headers) that all following <link
|
|
linkend="mkvpropedit.description.add">add</link>, <link linkend="mkvpropedit.description.set">set</link> and <link
|
|
linkend="mkvpropedit.description.delete">delete</link> actions operate on. This option can be used multiple times in order to make
|
|
modifications to more than one element.
|
|
</para>
|
|
|
|
<para>
|
|
By default &mkvpropedit; will edit the segment information section.
|
|
</para>
|
|
|
|
<para>
|
|
See the section about <link linkend="mkvpropedit.edit_selectors">edit selectors</link> for a full description of the syntax.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.add">
|
|
<term><option>-a</option>, <option>--add</option> <parameter>name</parameter>=<parameter>value</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Adds a property <parameter>name</parameter> with the value <parameter>value</parameter>. The property will be added even if such a
|
|
property exists already. Note that most properties are unique and cannot occur more than once.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.set">
|
|
<term><option>-s</option>, <option>--set</option> <parameter>name</parameter>=<parameter>value</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets all occurrences of the property <parameter>name</parameter> to the value <parameter>value</parameter>. If no such property exists
|
|
then it will be added.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.delete">
|
|
<term><option>-d</option>, <option>--delete</option> <parameter>name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Deletes all occurrences of the property <parameter>name</parameter>. Note that some properties are required and cannot be deleted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Actions that deal with tags and chapters:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.description.tags">
|
|
<term><option>-t</option>, <option>--tags</option> <parameter>selector</parameter>:<parameter>filename</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Add or replace tags in the file with the ones from <filename>filename</filename> or remove them if <filename>filename</filename> is
|
|
empty. &mkvpropedit; reads the same XML tag format that &mkvmerge; reads as well.
|
|
</para>
|
|
|
|
<para>
|
|
The <parameter>selector</parameter> must be one of the words <constant>all</constant>, <constant>global</constant> or
|
|
<constant>track</constant>. For <constant>all</constant> &mkvpropedit; will replace or remove all tags in a file. With
|
|
<constant>global</constant> only global tags will be replaced or removed.
|
|
</para>
|
|
|
|
<para>
|
|
With <constant>track</constant> &mkvpropedit; will replace tags for a specific track. Additionally the tags read from
|
|
<filename>filename</filename> will be assigned to the same track. The track is specified in the same way <link
|
|
linkend="mkvpropedit.edit_selectors">edit selectors</link> are specified (see below), e.g. <code>--tags
|
|
track:a1:new-audio-tags.xml</code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.add_track_statistics_tags">
|
|
<term><option>--add-track-statistics-tags</option></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.delete_track_statistics_tags">
|
|
<term><option>--delete-track-statistics-tags</option></term>
|
|
<listitem>
|
|
<para>
|
|
Deletes all existing track statistics tags from a file. If the file doesn't contain track statistics tags then it won't be modified.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.chapters">
|
|
<term><option>-c</option>, <option>--chapters</option> <parameter>filename</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Add or replace chapters in the file with the ones from <filename>filename</filename> or remove them if <filename>filename</filename> is
|
|
empty. &mkvpropedit; reads the same XML and simple chapter formats that &mkvmerge; reads as well.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Actions for handling attachments:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.description.add_attachment">
|
|
<term><option>--add-attachment</option> <parameter>filename</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Adds a new attachment from <parameter>filename</parameter>.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-name</option> has been used prior to this option then its value is used as the new attachment's
|
|
name. Otherwise it is derived from <parameter>filename</parameter>.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-mime-type</option> 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 <parameter>filename</parameter>.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-description</option> has been used prior to this option then its value is used as the new
|
|
attachment's description. Otherwise no description will be set.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-uid</option> 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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.replace_attachment">
|
|
<term><option>--replace-attachment</option> <parameter>selector</parameter><literal>:</literal><parameter>filename</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Replaces one or more attachments that match <parameter>selector</parameter> with the file <parameter>filename</parameter>. If more
|
|
than one existing attachment matches <parameter>selector</parameter> then all of their contents will be replaced by the content of
|
|
<parameter>filename</parameter>.
|
|
</para>
|
|
|
|
<para>
|
|
The <parameter>selector</parameter> can have one of four forms. They're explained below in the section <link
|
|
linkend="mkvpropedit.attachment_selectors">attachment selectors</link>.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-name</option> 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.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-mime-type</option> 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.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-description</option> 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.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-uid</option> 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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.update_attachment">
|
|
<term><option>--update-attachment</option> <parameter>selector</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the properties of one or more attachments that match <parameter>selector</parameter>. If more than one existing attachment
|
|
matches <parameter>selector</parameter> then all of their properties will be updated.
|
|
</para>
|
|
|
|
<para>
|
|
The <parameter>selector</parameter> can have one of four forms. They're explained below in the section <link
|
|
linkend="mkvpropedit.attachment_selectors">attachment selectors</link>.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-name</option> 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.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-mime-type</option> 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.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-description</option> 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.
|
|
</para>
|
|
|
|
<para>
|
|
If the option <option>--attachment-uid</option> 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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.delete_attachment">
|
|
<term><option>--delete-attachment</option> <parameter>selector</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Deletes one or more attachments that match <parameter>selector</parameter>.
|
|
</para>
|
|
|
|
<para>
|
|
The <parameter>selector</parameter> can have one of four forms. They're explained below in the section <link
|
|
linkend="mkvpropedit.attachment_selectors">attachment selectors</link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Options for attachment actions:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.description.attachment_name">
|
|
<term><option>--attachment-name</option> <parameter>name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the name to use for the following <option>--add-attachment</option> or <option>--replace-attachment</option> operation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.attachment_mime_type">
|
|
<term><option>--attachment-mime-type</option> <parameter>mime-type</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the MIME type to use for the following <option>--add-attachment</option> or <option>--replace-attachment</option> operation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.attachment_description">
|
|
<term><option>--attachment-description</option> <parameter>description</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the description to use for the following <option>--add-attachment</option> or <option>--replace-attachment</option> operation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.enable_legacy_font_mime_types">
|
|
<term><option>--enable-legacy-font-mime-types</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enables the use of legacy <abbrev>MIME</abbrev> types for certain types of font attachments. For example,
|
|
'<literal>application/x-truetype-font</literal>' will be used for TrueType fonts instead of '<literal>fonts/ttf</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
This affects both adding new attachments and replacing existing attachments, but only if the new <abbrev>MIME</abbrev> type isn't
|
|
specified. Other existing attachments aren't changed.
|
|
</para>
|
|
|
|
<para>
|
|
The affected <abbrev>MIME</abbrev> types are '<literal>font/sfnt</literal>', '<literal>font/ttf</literal>' and
|
|
'<literal>font/collection</literal>' which are all mapped to '<literal>application/x-truetype-fonts</literal>' and
|
|
'<literal>font/otf</literal>' which is mapped to '<literal>application/vnd.ms-opentype</literal>'.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Other options:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.description.disable_language_ietf">
|
|
<term><option>--disable-language-ietf</option></term>
|
|
<listitem>
|
|
<para>
|
|
Normally when the user requests changes to the '<literal>language</literal>' track header property, &mkvpropedit; will apply the same
|
|
change to the new <classname>LanguageIETF</classname> track header element in addition to the legacy <classname>Language</classname>
|
|
element. If this option is used, the change is only applied to the legacy <classname>Language</classname> element.
|
|
</para>
|
|
|
|
<para>
|
|
This option does not affect changes requested via the '<literal>language-ietf</literal>' track header property.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.normalize_language_ietf">
|
|
<term><option>--normalize-language-ietf</option> <parameter>mode</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Enables normalizing all IETF BCP 47 language tags to either their canonical form with mode '<literal>canonical</literal>', to their
|
|
extended language subtags form with mode '<literal>extlang</literal>' or turns it off with mode '<literal>off</literal>'. By default
|
|
normalization to the canonical form is applied.
|
|
</para>
|
|
|
|
<para>
|
|
In the canonical form all subtags for which preferred values exist are replaced by those preferred values. This converts
|
|
e.g. '<literal>zh-yue-jyutping</literal>' to '<literal>yue-jyutping</literal>' or '<literal>fr-FX</literal>' to '<literal>fr-FR</literal>'.
|
|
</para>
|
|
|
|
<para>
|
|
For the extended language subtags form the canonical form is built first. Afterwards all primary languages for which an extended
|
|
language subtag exists are replaced by that extended language subtag and its prefix. This converts
|
|
e.g. '<literal>yue-jyutping</literal>' back to '<literal>zh-yue-jyutping</literal>' but has no effect on '<literal>fr-FR</literal>' as
|
|
'<literal>fr</literal>' is not an extended language subtag.
|
|
</para>
|
|
|
|
<para>
|
|
This normalization is only applied to elements that are actually changed:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
When editing track headers only those track language elements that are set via edit specifications are affected. Languages of tracks
|
|
that aren't edited aren't changed. Editing a track but setting only properties other than the language won't affect the language
|
|
either.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
When editing chapters all language elements of all chapter elements are affected as existing chapters are always fully replaced.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
When editing tags only the language elements of the tags that are actually replaced are affected. For example, when you replace
|
|
global tags then existing track tags aren't affected.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The best way to normalize all existing language tags in a file is to remux it with &mkvmerge; and set its
|
|
'<literal>--normalize-language-ietf</literal>' option to the desired mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.command_line_charset">
|
|
<term><option>--command-line-charset</option> <parameter>character-set</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.output_charset">
|
|
<term><option>--output-charset</option> <parameter>character-set</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.redirect_output">
|
|
<term><option>-r</option>, <option>--redirect-output</option> <parameter>file-name</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Writes all messages to the file <parameter>file-name</parameter> 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 <link
|
|
linkend="mkvpropedit.description.output_charset"><option>--output-charset</option></link> is honored.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.ui_language">
|
|
<term><option>--ui-language</option> <parameter>code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Forces the translations for the language <parameter>code</parameter> to be used (e.g. '<literal>de_DE</literal>' for the German
|
|
translations). Entering '<literal>list</literal>' as the <parameter>code</parameter> will cause the program to output a list of
|
|
available translations.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.abort_on_warnings">
|
|
<term><option>--abort-on-warnings</option></term>
|
|
<listitem>
|
|
<para>
|
|
Tells the program to abort after the first warning is emitted. The program's exit code will be 1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.debug">
|
|
<term><option>--debug</option> <parameter>topic</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Turn on debugging for a specific feature. This option is only useful for developers.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.engage">
|
|
<term><option>--engage</option> <parameter>feature</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Turn on experimental features. A list of available features can be requested with <command>mkvpropedit --engage list</command>. These
|
|
features are not meant to be used in normal situations.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.gui_mode">
|
|
<term><option>--gui-mode</option></term>
|
|
<listitem>
|
|
<para>
|
|
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 '<literal>#GUI#message</literal>'. The message may be followed by key/value pairs as in
|
|
'<literal>#GUI#message#key1=value1#key2=value2…</literal>'. Neither the messages nor the keys are ever translated and always output
|
|
in English.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.verbose">
|
|
<term><option>-v</option>, <option>--verbose</option></term>
|
|
<listitem>
|
|
<para>
|
|
Be verbose and show all the important &matroska; elements as they're read.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.help">
|
|
<term><option>-h</option>, <option>--help</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show usage information and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.version">
|
|
<term><option>-V</option>, <option>--version</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show version information and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.at_sign">
|
|
<term><option>@</option><parameter>options-file.json</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Reads additional command line arguments from the file <parameter>options-file</parameter>. For a full explanation on the supported
|
|
formats for such files see the section called "Option files" in the &mkvmerge; man page.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.edit_selectors">
|
|
<title>Edit selectors</title>
|
|
<para>
|
|
The <link linkend="mkvpropedit.description.edit"><option>--edit</option></link> option sets the &matroska; file section (segment
|
|
information or a certain track's headers) that all following <link linkend="mkvpropedit.description.add">add</link>, <link
|
|
linkend="mkvpropedit.description.set">set</link> and <link linkend="mkvpropedit.description.delete">delete</link> actions operate
|
|
on. This stays valid until the next <link linkend="mkvpropedit.description.edit"><option>--edit</option></link> option is found. The
|
|
argument to this option is called the edit selector.
|
|
</para>
|
|
|
|
<para>
|
|
By default &mkvpropedit; will edit the segment information section.
|
|
</para>
|
|
|
|
<refsect2 id="mkvpropedit.edit_selectors.segment_info">
|
|
<title>Segment information</title>
|
|
<para>
|
|
The segment information can be selected with one of these three words: '<literal>info</literal>', '<literal>segment_info</literal>' or
|
|
'<literal>segmentinfo</literal>'. It contains properties like the segment title or the segment <abbrev>UID</abbrev>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="mkvpropedit.edit_selectors.track_headers">
|
|
<title>Track headers</title>
|
|
<para>
|
|
Track headers can be selected with a slightly more complex selector. All variations start with '<literal>track:</literal>'. The track
|
|
header properties include elements like the language code, 'default track' flag or the track's name.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.description.track_nth">
|
|
<term><option>track:</option><parameter>n</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If the parameter <parameter>n</parameter> is a number then the <parameter>n</parameter>th track will be selected. The track order is
|
|
the same that &mkvmerge;'s <option>--identify</option> option outputs.
|
|
</para>
|
|
|
|
<para>
|
|
Numbering starts at 1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.track_type_nth">
|
|
<term><option>track:</option><parameter>t</parameter><parameter>n</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If the parameter starts with a single character <parameter>t</parameter> followed by a <parameter>n</parameter> then the
|
|
<parameter>n</parameter>th track of a specific track type will be selected. The track type parameter <parameter>t</parameter> must be
|
|
one of these four characters: '<literal>a</literal>' for an audio track, '<literal>b</literal>' for a button track,
|
|
'<literal>s</literal>' for a subtitle track and '<literal>v</literal>' for a video track. The track order is the same that
|
|
&mkvmerge;'s <option>--identify</option> option outputs.
|
|
</para>
|
|
|
|
<para>
|
|
Numbering starts at 1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.track_uid">
|
|
<term><option>track:</option>=<parameter>uid</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If the parameter starts with a '<literal>=</literal>' followed by a number <parameter>uid</parameter>, the track whose track
|
|
<abbrev>UID</abbrev> element equals the given <parameter>uid</parameter> will be selected. Track <abbrev>UIDs</abbrev> can be
|
|
obtained with &mkvinfo;.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.description.track_number">
|
|
<term><option>track:</option>@<parameter>number</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If the parameter starts with a '<literal>@</literal>' followed by a number <parameter>number</parameter>, the track whose track
|
|
number element equals this <parameter>number</parameter> will be selected. Track numbers can be obtained with &mkvinfo;.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2 id="mkvpropedit.edit_selectors.notes">
|
|
<title>Notes</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.attachment_selectors">
|
|
<title>Attachment selectors</title>
|
|
|
|
<para>
|
|
An attachment selector is used with the two actions <link
|
|
linkend="mkvpropedit.description.replace_attachment"><option>--replace-attachment</option></link> and <link
|
|
linkend="mkvpropedit.description.delete_attachment"><option>--delete-attachment</option></link>. It can have one of the following four
|
|
forms:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Selection by attachment ID. In this form the selector is simply a number, the attachment's ID as output by &mkvmerge;'s
|
|
identification command.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Selection by attachment UID (unique ID). In this form the selector is the equal sign <literal>=</literal> followed by a number, the
|
|
attachment's unique ID as output by &mkvmerge;'s verbose identification command.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Selection by attachment name. In this form the selector is the literal word <literal>name:</literal> followed by the existing
|
|
attachment's name. If this selector is used with <option>--replace-attachment</option> then colons within the name to match must be
|
|
escaped as <literal>\c</literal>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Selection by MIME type. In this form the selector is the literal word <literal>mime-type:</literal> followed by the existing
|
|
attachment's MIME type. If this selector is used with <option>--replace-attachment</option> then colons within the MIME type to match
|
|
must be escaped as <literal>\c</literal>.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.language_handling">
|
|
<title>Language handling</title>
|
|
|
|
<para>
|
|
&mkvpropedit; mostly tries to do the right thing by default. Therefore changes to the <option>language</option> property will cause
|
|
&mkvpropedit; to apply the same change to both the new "LanguageIETF" element as well as the old "Language" element similar to how
|
|
&mkvmerge; applies the language to both elements. For example, when using <literal>mkvpropedit movie.mkv --edit track:2 --set
|
|
language=zh-TW</literal> the "LanguageIETF" element will be set to <literal>zh-TW</literal> and the old "Language" element to
|
|
<literal>chi</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
Additionally there's a new track header property named <option>language-ietf</option> that can be set or removed. Changes to this
|
|
property only apply to the new "LanguageIETF" track header element. A caveat is that the old "Language" track header element is a
|
|
mandatory element in Matroska — meaning even if it isn't present in the file it still has an implied value. When the user only sets the
|
|
<option>language-ietf</option> property but not the <option>language</option> property, &mkvpropedit; will therefore add the old
|
|
"Language" element in certain cases & set it to <literal>und</literal> (meaning "undetermined") as the user didn't specify a value
|
|
for it.
|
|
</para>
|
|
|
|
<para>When reading XML chapter or tag files &mkvpropedit; works like &mkvmerge; does.</para>
|
|
|
|
<para>The creation of the new elements can be disabled completely with the command-line option `--disable-language-ietf` which operates on
|
|
all three new elements.</para>
|
|
|
|
<para>You can chose the normalization method applied to extended language sub-tags with the parameter
|
|
<option>--normalize-language-ietf</option>.</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.examples">
|
|
<title>Examples</title>
|
|
<para>
|
|
The following example edits a file called '<literal>movie.mkv</literal>'. 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 <link
|
|
linkend="mkvpropedit.description.edit"><option>--edit</option></link> option because editing the segment information element is the
|
|
default for all options found before the first <link linkend="mkvpropedit.description.edit"><option>--edit</option></link> option anyway.
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --edit info --set "title=The movie" --edit track:a1 --set language=fre --edit track:a2 --set language=ita</screen>
|
|
|
|
<para>
|
|
The second example removes the 'default track flag' from the first subtitle track and sets it for the second one. Note that
|
|
&mkvpropedit;, unlike &mkvmerge;, does not set the 'default track flag' of other tracks to '0' if it is set to '1' for a different track
|
|
automatically.
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --edit track:s1 --set flag-default=0 --edit track:s2 --set flag-default=1</screen>
|
|
|
|
<para>
|
|
Replacing the tags for the second subtitle track in a file looks like this:
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --tags track:s2:new-subtitle-tags.xml</screen>
|
|
|
|
<para>
|
|
Removing all tags requires leaving out the file name:
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --tags all:</screen>
|
|
|
|
<para>
|
|
Replacing the chapters in a file looks like this:
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --chapters new-chapters.xml</screen>
|
|
|
|
<para>
|
|
Removing all chapters requires leaving out the file name:
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --chapters ''</screen>
|
|
|
|
<para>
|
|
Adding a font file (<literal>Arial.ttf</literal>) as an attachment:
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --add-attachment Arial.ttf</screen>
|
|
|
|
<para>
|
|
Adding a font file (<literal>89719823.ttf</literal>) as an attachment and providing some information as it really is just Arial:
|
|
</para>
|
|
|
|
<screen>$ 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</screen>
|
|
|
|
<para>
|
|
Replacing one attached font (<literal>Comic.ttf</literal>) file with another one (<literal>Arial.ttf</literal>):
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --attachment-name Arial.ttf --attachment-description 'The Arial font as a TrueType font' --replace-attachment name:Comic.ttf:Arial.ttf</screen>
|
|
|
|
<para>
|
|
Deleting the second attached file, whatever it may be:
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --delete-attachment 2</screen>
|
|
|
|
<para>
|
|
Deleting all attached fonts by MIME type:
|
|
</para>
|
|
|
|
<screen>$ mkvpropedit movie.mkv --delete-attachment mime-type:application/x-truetype-font</screen>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Exit codes</title>
|
|
|
|
<para>
|
|
&mkvpropedit; exits with one of three exit codes:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<constant>0</constant> -- This exit code means that the modification has completed successfully.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<constant>1</constant> -- In this case &mkvpropedit; has output at least one warning, but the modification did continue. A warning is
|
|
prefixed with the text '<literal>Warning:</literal>'. 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.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<constant>2</constant> -- This exit code is used after an error occurred. &mkvpropedit; aborts right after outputting the error message.
|
|
Error messages range from wrong command line arguments over read/write errors to broken files.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvinfo.text_files_and_charsets">
|
|
<title>Text files and character set conversions</title>
|
|
|
|
<para>
|
|
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; man page.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.environment_variables">
|
|
<title>Environment variables</title>
|
|
|
|
<para>
|
|
&mkvpropedit; uses the default variables that determine the system's locale (e.g. <varname>LANG</varname> and the <varname>LC_*</varname>
|
|
family). Additional variables:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="mkvpropedit.environment_variables.debug">
|
|
<term><varname>MKVPROPEDIT_DEBUG</varname>, <varname>MKVTOOLNIX_DEBUG</varname> and its short form <varname>MTX_DEBUG</varname></term>
|
|
<listitem>
|
|
<para>The content is treated as if it had been passed via the <link
|
|
linkend="mkvpropedit.description.debug"><option>--debug</option></link> option.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="mkvpropedit.environment_variables.engage">
|
|
<term><varname>MKVPROPEDIT_ENGAGE</varname>, <varname>MKVTOOLNIX_ENGAGE</varname> and its short form <varname>MTX_ENGAGE</varname></term>
|
|
<listitem>
|
|
<para>The content is treated as if it had been passed via the <link
|
|
linkend="mkvpropedit.description.engage"><option>--engage</option></link> option.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.seealso">
|
|
<title>See also</title>
|
|
<para>
|
|
&mkvmerge;, &mkvinfo;, &mkvextract;, &mtxgui;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.www">
|
|
<title>WWW</title>
|
|
<para>
|
|
The latest version can always be found at <ulink url="https://mkvtoolnix.download/">the MKVToolNix homepage</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|