mkvpropedit -- 在不进行完整的重新混流的情况下修改现有 Matroska(tm) 文件的属性

# 1. 概要

mkvpropedit 选项 {输入文件名} {操作}

# 2. 摘要說明

此程序可分析现有 Matroska(tm) 文件，并修改其部分属性。然后它将将变更写入现有文件。可修改的属性包括剪辑信息元素（如标题）和轨道头部（如语言代码、'默认轨' 标记或轨道名称）。

選項:

Option | Description
--- | ---
-l, --list-property-names | 列出所有已知的可编辑的属性名称、它们的类型（字符串型、整数型、布尔型等等）及简短说明。程序随后将退出执行。因此不必提供 source-filename 参数。
-p, --parse-mode 模式 | 设置解析模式。参数 '模式' 可以为 'fast（快速）'（此项为默认值）或 'full（完整）'。'fast（快速）'模式不解析整个文件，而是使用元定位元素确定输入文件中所需元素的位置。99% 的情况下这就足够了。但如果碰到不含元定位元素或者元定位元素损坏的文件，用户可能得考虑 'full（完整）' 解析模式。完整扫描文件可能要花费几分钟，而快速扫描只需要几秒钟。

轨道、剪辑信息属性处理操作:

Option | Description
--- | ---
-e, --edit 選擇 | 设置后续的 添加、设置 或 删除 操作所针对的 Matroska(tm) 文件区域（即剪辑信息或某个轨道的头部）。此选项可多次使用，以同时修改多个元素。 默认情况下，mkvpropedit(1) 将编辑剪辑信息区段。 完整的語法描述詳細資訊請參閱下列 編輯選擇器 。
-a, --add 名称=数值 | 添加名为 名称、值为 数值 的属性。即使已存在这样的属性，也将执行添加属性操作。注意大多数属性是唯一的，不能出现多个。
-s, --set 名稱=數值 | 设置所有名为 名称 的属性的数值为 数值。如果不存在这样的属性，则将添加该属性。
-d, --delete 名稱 | 删除所有名为 名称 的属性。注意部分属性是必需的，不能删除。

标签及章节处理操作:

Option | Description
--- | ---
-t, --tags 選擇:檔名 | 用 文件名 中的标签添加或替换文件中的标签，或者如果 文件名 为空则移除标签。mkvpropedit(1) 读取的 XML 标签格式与 mkvmerge(1) 所读取的相同。 选择器 必须是 all、global 或 track 之一。对于all 选择器，mkvpropedit(1) 将替换或移除文件中的所有标签。对于 global 选择器，将只替换或移除全局标签。 对于 track 选择器，mkvpropedit(1) 将替换特定轨道的标签。读取自 文件名 的其他标签将分配给相同轨道。轨道与 编辑选择器 以相同格式指定 (参见下文)，如 --tags track:a1:新音频标签.xml。
--add-track-statistics-tags | 计算文件所有轨道的统计信息，并为每个轨道新增一个统计信息标签。若文件中已经存在此类标签，则将更新这些标签。
--delete-track-statistics-tags | 从文件中删除现有的全部轨道统计标签。若文件不包括轨道统计标签，则不会被修改。
-c, --chapters 檔名 | 用 文件名 中的标签添加或替换文件中的章节，或者如果 文件名 为空则移除章节。mkvpropedit(1) 读取的 XML 及简单章节格式与 mkvmerge(1) 所读取的相同。

附件處理執行選項:

Option | Description
--- | ---
--add-attachment 檔名 | 從 檔名 增加新的附件。 若本选项之前使用了 --attachment-name 选项，则其值将用作新附件的名称。否则附件名称将从 文件名 得出。 若本选项之前使用了 --attachment-mime-type 选项，则其值将用作新附件的 MIME 类型。否则将根据 文件名 的内容自动侦测。 若本选项之前使用了 --attachment-description 选项，则其值将用作新附件的描述。否则将不设置描述信息。 若本选项之前使用了 --attachment-uid 选项，则其值将用作新附件的 UID。否则将自动生成随机的 UID。
--replace-attachment 选择器:文件名 | 用文件 文件名 替换与 选择器 相匹配的一或多个附件。如果有超过一个现有附件与 选择器 相匹配，则其所有内容均将被 文件名 的内容替代。 选择器 可以有四种格式。各格式说明位于下文 附件选择器 段落。 若本选项之前使用了 --attachment-name 选项，则其值将设为每个被修改的附件的新名称。否则不修改名称。 若本选项之前使用了 --attachment-mime-type 选项，则其值将设为每个被修改的附件的新 MIME 类型。否则不修改 MIME 类型。 若本选项之前使用了 --attachment-description 选项，则其值将设为每个被修改的附件的新描述。否则不修改描述。

若本选项之前使用了 --attachment-uid 选项，则其值将设为每个被修改的附件的新 UID。否则不修改 UID。

--update-attachment 選擇 | 设置 选择器 所匹配的一或多个附件的属性。如果匹配 选择器 的现有附件超过一个，则每个附件的属性都将被更新。 选择器 可以有四种格式。各格式说明位于下文 附件选择器 段落。 若本选项之前使用了 --attachment-name 选项，则其值将设为每个被修改的附件的新名称。否则不修改名称。 若本选项之前使用了 --attachment-mime-type 选项，则其值将设为每个被修改的附件的新 MIME 类型。否则不修改 MIME 类型。 若本选项之前使用了 --attachment-description 选项，则其值将设为每个被修改的附件的新描述。否则不修改描述。

若本选项之前使用了 --attachment-uid 选项，则其值将设为每个被修改的附件的新 UID。否则不修改 UID。

--delete-attachment 選擇 | 删除与 选择器 相匹配的一或多个附件。 选择器 可以有四种格式。各格式说明位于下文 附件选择器 段落。

附件執行選項:

Option | Description
--- | ---
--attachment-name 名稱 | 设置接下来 --add-attachment 或 --replace-attachment 操作要使用的名称。
--attachment-mime-type MIME 類型 | 设置接下来 --add-attachment 或 --replace-attachment 操作要使用的 MIME 类型。
--attachment-description 描述 | 设置接下来 --add-attachment 或 --replace-attachment 操作要使用的描述。
--enable-legacy-font-mime-types | 对于特定类型的字体附件，使用传统的 MIME 类型。例如，TrueType 字体的类型将标注为「application/x-truetype-font」而非「fonts/ttf」。 这将同时影响到新增附件与替换现有附件的操作，但仅当用户未指定新版 MIME 类型时才起作用。其他现有的附件不受影响。 受影响的 MIME 类型如下：「font/sfnt」「font/ttf」「font/collection」将全部映射至「application/x-truetype-fonts」，「 font/otf」将被映射至「application/vnd.ms-opentype」。

其他選項:

Option | Description
--- | ---
--disable-language-ietf | 通常情况下，当用户要求更改轨道头部属性「language」(语言) 时，mkvpropedit(1) 会同时更改全新的「LanguageIETF」轨道头部元素以及传统的「Language」元素。若使用本选项，则只会更改传统的「Language」元素。 此选项不影响通过「language-ietf」轨道头部属性提出的变更要求。
--normalize-language-ietf 模式 | 将 IETF BCP 47 语言标签规范化，支持「canonical」（最简式）、「extlang」（扩展语言子标签形式）以及「off」关闭模式。默认（不添加本选项）会规范化至最简式。 最简式模式下，所有存在推荐值（preferred value）的语言子标签都会被替换为推荐值。依规范会执行下述转换: ｢zh-yue-jyutping｣ 转换为 ｢yue-jyutping｣，｢fr-FX｣ 转换为 ｢fr-FR｣。 扩展语言子标签形式在最简式的基础上生成。所有存在扩展语言子标签（extended language subtag）的主要语言（primary language）都被替换为子标签对应的前缀加上该子标签。该规则将 ｢yue-jyutping｣ 转回传统的 ｢zh-yue-jyutping｣ 形式，但 ｢fr-FR｣ 不会发生变化，因为 ｢fr｣ 不属于扩展语言子标签。

此处的规范化规则只对实际发生变化的元素起作用:

- 编辑轨道头部字段时，只有通过编辑指令设置轨道语言元素值的轨道会受到影响。未被编辑的轨道的语言不会发生变化。编辑某条轨道但只设置语言以外的属性，也不会改变其语言值。

- 编辑章节时，所有章节元素的所有语言元素都会受到影响，因为现有的章节会被完全替换为新章节。

- 编辑标签时，只有实际被替换的标签的语言元素才会受到影响。例如，当您替换全局标签时，现有的轨道标签不会受到影响。

将某个文件内现有的所有语言标签全部作规范化处理的最佳途径是，使用 mkvmerge(1) 将其重新混流，并将程序的「--normalize-language-ietf」选项设为所需的模式。

--command-line-charset 字元集 | 設定在命令列顯示的字串字元集，以轉換為其他字元集。預設為目前系統所在位置指定的字元集。
--output-charset 字元集 | 設定要轉換為輸出字串的字元集。預設為目前系統所在位置指定的字元集。
-r, --redirect-output 檔名 | 將所有訊息寫入到檔案 檔名 而不是命令列。儘管使用輸出重新導向可以輕鬆完成此操作，但在某些情況下需要使用此選項: 當終端在將輸出寫入文件之前重新解釋（覆蓋）輸出時。 優先使用通過 --output-charset 設定字元集。
--ui-language 語言碼 | 強制使用語言 編碼 對應的的翻譯(例如 'zh_TW' 為臺灣正體中文翻譯)。 在編碼欄位中輸入'list' 讓程式輸出時使用可用的對應翻譯清單。
--abort-on-warnings | 發出第一個警告後，終止程式。程式的結束碼為 1 。
--debug 主題 | 針對特定功能開啟除錯。此選項適用於開發者。
--engage 功能 | 開啟實驗中功能。 透過mkvpropedit --engage list啟用可用的列表。這些功能不會在正常情況下使用。
--gui-mode | 開啟 GUI 模式。在這種模式中，可能會輸出特殊格式的行數，可以呈現控制的 GUI 發生什麼事。這些訊息會以 '#GUI#訊息'呈現。訊息可能包含機碼/值，例如 '#GUI#訊息#機碼1=值1#機碼2=值2…'。 無論是訊息或是機碼都不會轉為譯文，而且永遠使用 *英語* 輸出。
-v, --verbose | 輸出時盡量詳細，並在讀取時顯示所有 Matroska(tm) 重要的元件。
-h, --help | 顯示使用方式並退出。
-V, --version | 顯示版本資訊並離開。
@options-file.json | 從檔案選項檔讀取其他命令列引數。有關此類檔案支援格式的完整說明，請參閱 mkvmerge(1) 文件中的 "選項檔案" 章節。

# 3. 編輯選擇器

--edit 选项设置后续的 添加, 设置 或 删除 操作所影响的 Matroska(tm) 文件区域（剪辑信息或者特定轨道的头部）。在出现另一个 --edit 选项之前，此选项将一直有效。此选项的参数就叫做编辑选择器。

默认情况下，mkvpropedit(1) 将编辑剪辑信息区段。

## 3.1. 剪輯資訊

可以通过这三个词中的任意一个选择剪辑信息: 'info'、'segment_info' 或 'segmentinfo'。剪辑信息包含的属性包括剪辑标题、剪辑 UID 等。

## 3.2. 軌道表頭

可用于选择轨道头部的选择器稍显复杂：所有以 'track:' 开头的变体。轨道头部属性包括如语言代码、'默认轨' 标记、轨道名称等属性。

Option | Description
--- | ---
track:n | 如果参数 n 为数字，则将选择第 n 条轨道。轨道顺序与 mkvmerge(1) 的 --identify 选项所输出的相同。 從 1 開始編號。
track:t n | 如果参数以字母 t 后接 n 开头，则将选择选定轨道类型中的第 n 条轨道。轨道类型参数 t 必须为下述四个字母中的一个: 'a' 代表音频轨道，'b' 代表按钮轨道，'s' 代表字幕轨道，'v' 代表视频轨道。轨道顺序与 mkvmerge(1) 的 --identify 选项所输出的相同。 從 1 開始編號。
track:=uid | 若参数以「=」后接数字「uid」开头，则会选择轨道 UID 元素与参数所给出的「uid」相同的轨道。可使用 mkvinfo(1) 获取轨道 UID。
track:@編號 | 若参数以「@」后接数字「number」开头，则会选择轨道编号等于该「 number」的轨道。可以通过 mkvinfo(1) 获取轨道编号。

## 3.3. 備註

由于轨道编辑选择器的特性，一些选择器所匹配的轨道头部可能是相同的。在此情况下，这些编辑选择器的所有操作将被按照在命令行给出的顺序合并运行。

# 4. 附件選擇器

附件选择器可与「--replace-attachment」及「--delete-attachment」这两项操作一起使用。它可以有以下四种格式:

1. 按附件 ID 选择。本格式的选择器仅仅是数字，mkvmerge(1) 的识别命令所输出的附件 ID。

2. 按附件 UID (唯一 ID) 选择。本格式的选择器为等号 = 后接数字，mkvmerge(1) 的详尽识别命令所输出的附件的唯一 ID。

3. 按附件名称选择。本格式的选择器为纯文本「name:」后接现有附件名称。若本选择器与「--replace-attachment」一起使用，则名称中的冒号必须用「\c」转义。

4. 按 MIME 类型选择。本格式的选择器为纯文本「mime-type:」后接现有附件的 MIME 类型。若本选择器与「--replace-attachment」一起使用，则 MIME 类型中的冒号必须用「\c」转义。

# 5. Language handling

mkvpropedit(1) mostly tries to do the right thing by default. Therefore changes to the language property will cause mkvpropedit(1) to apply the same change to both the new "LanguageIETF" element as well as the old "Language" element similar to how mkvmerge(1) applies the language to both elements. For example, when using mkvpropedit movie.mkv --edit track:2 --set language=zh-TW the "LanguageIETF" element will be set to zh-TW and the old "Language" element to chi.

Additionally there's a new track header property named language-ietf 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 language-ietf property but not the language property, mkvpropedit(1) will therefore add the old "Language" element in certain cases & set it to und (meaning "undetermined") as the user didn't specify a value for it.

When reading XML chapter or tag files mkvpropedit(1) works like mkvmerge(1) does.

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.

You can chose the normalization method applied to extended language sub-tags with the parameter --normalize-language-ietf.

# 6. 範例

下面的示例将编辑一个名为 '电影.mkv' 的文件。示例中将设置剪辑标题并修改一条音频轨和一条字幕轨的语言代码。附注，本示例可以简写，即省去 --edit 选项，因为在第一个 --edit 选项之前的所有选项默认编辑的就是剪辑信息元素。

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

第二个示例，将 '默认轨标记' 从第一条字幕轨移除并设置到第二条字幕轨上。注意 mkvpropedit(1) 与 mkvmerge(1) 不同，不会在将另一个轨道的 '默认轨标记'设为 '1' 的时候自动将其他轨道的标记设为 '0'。

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

像这样替换文件中第二个字幕轨的标签:

    $ mkvpropedit 影片.mkv --tags track:s2:新的字幕標簽.xml

移除所有标签需要将文件名留空:

    $ mkvpropedit 影片.mkv --tags all:

像这样替换文件中的章节:

    $ mkvpropedit 影片.mkv --chapters 新的章節.xml

移除所有章节需要将文件名留空:

    $ mkvpropedit 影片.mkv --chapters ''

将字体文件 (Arial.ttf) 作为附件添加:

    $ mkvpropedit 影片.mkv --add-attachment Arial.ttf

将字体文件 (89719823.ttf) 作为附件添加，并提供信息，因为它真的就是 Arial:

    $ mkvpropedit 影片.mkv --attachment-name Arial.ttf --attachment-description 'Arial 字型，TrueType 格式' --attachment-mime-type application/x-truetype-font --add-attachment 89719823.ttf

將一個附加字型 (Comic.ttf) 檔取代成另一個 (Arial.ttf):

    $ mkvpropedit 影片.mkv --attachment-name Arial.ttf --attachment-description 'Arial 字型，TrueType 格式' --replace-attachment name:Comic.ttf:Arial.ttf

刪除第二個附加檔，無論可能是什麼:

    $ mkvpropedit 影片.mkv --delete-attachment 2

依 MIME 類型刪除所有附加的字型:

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

# 7. 結束代碼

使用三個之一的結束代碼結束 mkvpropedit(1) ：

- 0 -- 此結束代碼表示修正已成功完成。

- 1 -- 在此情況下 mkvpropedit(1) 輸出時至少有一則警告，但編輯動作仍然進行。警告訊息會在前端出現 'Warning:' 字樣。依據問題的程度，生成的檔案也許可用。建議使用者檢視警告訊息與輸出檔。

- 2 -- 此結束代碼用於發生錯誤後。 mkvpropedit(1) 在輸出錯誤訊息後立即中止動作。錯誤訊息的範圍包含從錯誤命令列參數的讀/寫至檔案損壞。

# 8. 文字檔案與字元集轉換

关于 MKVToolNix 套件中所有工具如何处理字符集转换、输入/输出编码、命令行编码及控制台编码的深入讨论，请参见 mkvmerge(1) 手册中相对应名称的段落。

# 9. 環境變數

mkvpropedit(1) 使用決定系統的地區設定的變數 (例如： LANG 與 LC_* 系列)。 附加變數：

Option | Description
--- | ---
MKVPROPEDIT_DEBUG, MKVTOOLNIX_DEBUG 與其的簡短形式 MTX_DEBUG | 視為通過 --debug 選項傳遞的內容。
MKVPROPEDIT_ENGAGE, MKVTOOLNIX_ENGAGE 與其簡短形式 MTX_ENGAGE | 視為通過 --engage 選項傳遞的內容。

# 10. 參閱

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

# 11. 網路

永遠可在 MKVToolNix 首頁 找到最新版。