mirror of
https://gitlab.com/mbunkus/mkvtoolnix.git
synced 2024-12-26 12:53:50 +00:00
401 lines
16 KiB
XML
401 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd"
|
|
[
|
|
<!ENTITY product "mkvpropedit">
|
|
<!ENTITY version "3.2.0">
|
|
<!ENTITY date "2010-02-11">
|
|
|
|
<!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 mmg "<citerefentry><refentrytitle>mmg</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 se 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:
|
|
</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>
|
|
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 occurences 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 occurences of the property <parameter>name</parameter>. Note that some properties are required and cannot be deleted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
Other options:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<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). It is preferable to use the environment variables <varname>LANG</varname>, <varname>LC_MESSAGES</varname> and
|
|
<varname>LC_ALL</varname> though. Entering '<literal>list</literal>' as the <parameter>code</parameter> will cause &mkvextract; to
|
|
output a list of available translations.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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>
|
|
<term><option>-h</option>, <option>--help</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show usage information and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-V</option>, <option>--version</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show version information and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>@</option>options-file</term>
|
|
<listitem>
|
|
<para>
|
|
Reads additional command line arguments from the file <parameter>options-file</parameter>. Lines whose first non-whitespace
|
|
character is a hash mark ('<literal>#</literal>') are treated as comments and ignored. White spaces at the start and end of a line
|
|
will be stripped. Each line must contain exactly one option. There is no meta character escaping.
|
|
</para>
|
|
|
|
<para>
|
|
The command line '<command>mkvpropedit source.mkv --edit track:a2 --set name=Comments</command>' could be converted into the
|
|
following option file:
|
|
</para>
|
|
|
|
<programlisting>
|
|
# Modify source.mkv
|
|
source.mkv
|
|
# Edit the second audio track
|
|
--edit
|
|
track:a2
|
|
# and set the title to 'Comments'
|
|
--set
|
|
title=Comments
|
|
</programlisting>
|
|
</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>
|
|
|
|
<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>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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> then the track whose track
|
|
<abbrev>UID</abbrev> element equals this <parameter>uid</parameter>. Track <abbrev>UIDs</abbrev> can be obtained with &mkvinfo;.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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> then the track whose track
|
|
number element equals this <parameter>number</parameter>. Track number 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.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 flags to '0' if it is set to '1' for a different track
|
|
automatically.
|
|
</para>
|
|
|
|
<screen>
|
|
$ mkvpropedit movie.mkv --edit tracks:s1 --set flag-default=0 --edit tracks:s2 --set flag-default=1
|
|
</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 codes 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 occured. &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="mkvpropedit.seealso">
|
|
<title>See also</title>
|
|
<para>
|
|
&mkvmerge;, &mkvinfo;, &mkvextract;, &mmg;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkvpropedit.www">
|
|
<title>WWW</title>
|
|
<para>
|
|
The latest version can always be found at <ulink url="http://www.bunkus.org/videotools/mkvtoolnix/">the MKVToolNix homepage</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|