mkvpropedit -- Змінити властивості існуючих файлів Matroska(tm) без повного перезбирання

# 1. Короткий опис

mkvpropedit options {source-filename} {actions}

# 2. Опис

Ця програма аналізує існуючий файл Matroska(tm) і змінює деякі його властивості. Потім він записує ці зміни в існуючий файл. Серед властивостей, які можна змінити, є елементи інформації про сегменти (наприклад, назва) і заголовки доріжок (наприклад, код мови, прапор «доріжка за замовчуванням» або назва).

Параметри:

Option | Description
--- | ---
-l, --list-property-names | Перелічує всі відомі і редаговані імена властивостей, їх тип (рядок, ціле число, логічне значення тощо) і короткий опис. Після цього програма завершується. Тому параметр source-filename не потрібно вказувати.
-p, --parse-mode mode | Встановлює режим розбору. Параметр 'режим' може бути 'швидким' (який також є за замовчуванням) або 'повним'. 'Швидкий' режим не аналізує весь файл, а використовує мета-елементи пошуку для пошуку необхідних елементів вихідного файлу. У 99% випадків цього достатньо. Але для файлів, які не містять елементів мета пошуку або пошкоджених, користувачеві доведеться встановити 'повний' режим аналізу. Повне сканування файлу може зайняти кілька хвилин, а швидке — лише секунди.

Дії, які впливають на інформаційні властивості доріжки та сегменту:

Option | Description
--- | ---
-e, --edit selector | Встановлює розділ файлу Matroska(tm) (інформацію про сегмент або заголовки певної доріжки), з яким діють усі наступні дії add, set та delete. Цей параметр можна використовувати кілька разів, щоб внести зміни до кількох елементів. За замовчуванням mkvpropedit(1) відредагує розділ інформації про сегмент. Дивіться розділ про редагування селекторів для повного опису синтаксу.
-a, --add name=value | Додає властивість name зі значенням value. Властивість буде додано, навіть якщо така властивість вже існує. Зауважте, що більшість властивостей унікальні і не можуть зустрічатися більше одного разу.
-s, --set name=value | Встановлює для всіх входжень властивості name значення value. Якщо такої властивості немає, вона буде додана.
-d, --delete name | Видаляє всі входження властивості name. Зауважте, що деякі властивості є обов’язковими і не можуть бути видалені.

Дії, які впливають на теґи та розділи:

Option | Description
--- | ---
-t, --tags selector:filename | Додає або заміняє теги у файлі на теги з filename або видаляє їх, якщо filename порожній. mkvpropedit(1) читає ті самі формати тегів XML, які читає mkvmerge(1). selector має бути одним із слів all, global або track. Для all mkvpropedit(1) замінить або видалить усі теги у файлі. З global тільки глобальні теги будуть замінені або видалені. З доріжкою mkvpropedit(1) замінить теги для певної доріжки. Крім того, теги, прочитані з filename, будуть призначені до тієї ж доріжки. Доріжка вказується так само, як вказуються селектори редагування (див. нижче), напр. --tags track:a1:new-audio-tags.xml.
--add-track-statistics-tags | Обчислює статистику для всіх доріжок у файлі та додає для них нові теги статистики. Якщо файл уже містить такі теги, вони будуть оновлені.
--delete-track-statistics-tags | Видаляє всі наявні теги статистики доріжки з файлу. Якщо файл не містить тегів статистики відстеження, він не буде змінено.
-c, --chapters filename | Додає або замінює розділи у файлі такими з filename або видаляє їх, якщо filename порожній. mkvpropedit(1) читає ті самі XML і простий формати розділів, які читає mkvmerge(1).

Дії для обробки вкладень:

Option | Description
--- | ---
--add-attachment filename | Додати нове вкладення з filename. Якщо параметр --attachment-name використовувався до цього параметра, його значення використовується як ім'я нового вкладення. Інакше він є похідним від filename. Якщо параметр --attachment-mime-type використовувався до цього параметра, його значення використовується як тип MIME нового вкладення. Інакше це автоматично виявляється зі змісту filename. Якщо параметр --attachment-description використовувався до цього параметра, його значення ввикористовується як опис нового вкладення. Інакше опис не встановлюється. Якщо параметр --attachment-uid використовувався до цього параметра, його значення використовується як UID нового вкладення. Інакше рандомний UID буде згенеровано автоматично.
--replace-attachment selector: filename | Замінює одне або кілька вкладень, які відповідають selector на файл filename. Якщо більше одного наявного вкладення відповідає selector, то весь їх вміст буде замінено вмістом filename. selector може мати одну з чотирьох форм. Вони пояснюються нижче в розділі Селектор вкладень. Якщо параметр --attachment-name використовувався до цього параметра, його значення встановлюється як нове ім'я для кожного зміненого вкладення. Інакше імена не змінюються. Якщо параметр --attachment-mime-type використовувався до цього параметра, його значення встановлюється як новий тип MIME для кожного зміненого вкладення. Інакше тип MIME не змінюється. Якщо параметр --attachment-description використовувався до цього параметра, його значення встановлюється як новий опис для кожного зміненого вкладення. Інакше опис не змінюється. Якщо параметр --attachment-uid використовувався до цього параметра, його значення встановлюється як новий UID для кожного зміненого вкладення. Інакше UID не змінюються.
--update-attachment selector | Встановлює властивості одного або кількох вкладень, які відповідають selector. Якщо більше одного наявного вкладення відповідає selector, усі їхні властивості будуть оновлені. selector може мати одну з чотирьох форм. Вони пояснюються нижче в розділі Селектор вкладень. Якщо параметр --attachment-name використовувався до цього параметра, його значення встановлюється як нове ім'я для кожного зміненого вкладення. Інакше імена не змінюються. Якщо параметр --attachment-mime-type використовувався до цього параметра, його значення встановлюється як новий тип MIME для кожного зміненого вкладення. Інакше тип MIME не змінюється. Якщо параметр --attachment-description використовувався до цього параметра, його значення встановлюється як новий опис для кожного зміненого вкладення. Інакше опис не змінюється. Якщо параметр --attachment-uid використовувався до цього параметра, його значення встановлюється як новий UID для кожного зміненого вкладення. Інакше UID не змінюються.
--delete-attachment selector | Видаляє одне або кілька вкладень, які відповідають селектору. selector може мати одну з чотирьох форм. Вони пояснюються нижче в розділі Селектор вкладень.

Параметри дій з вкладенням:

Option | Description
--- | ---
--attachment-name name | Встановлює назву для наступної операції --add-attachment або --replace-attachment.
--attachment-mime-type mime-type | Встановлює тип MIME для використання для наступної операції --add-attachment або --replace-attachment .
--attachment-description description | Встановлює опис для наступної операції --add-attachment або --replace-attachment.
--enable-legacy-font-mime-types | Дозволяє використовувати застарілі типи MIME для певних типів вкладень шрифтів. Наприклад, 'application/x-truetype-font' використовуватиметься для шрифтів TrueType замість '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 mode | Дозволяє нормалізувати всі мовні теги IETF BCP 47 до їхньої канонічної форми з режимом 'canonical', до форми розширених мовних підтегів за допомогою режиму 'extlang' або вимикає його в режимі 'off'. За замовчуванням застосовується нормалізація до канонічної форми. У канонічній формі всі підтеги, для яких існують бажані значення, замінюються цими бажаними значеннями. Це перетворює, наприклад, 'zh-yue-jyutping' до 'yue-jyutping' або 'fr-FX' до 'fr-FR'. Для форми розширених мовних підтегів спочатку будується канонічна форма. Після цього всі основні мови, для яких існує розширений мовний підтег, замінюються цим розширеним мовним підтегом та його префіксом. Це перетворює, наприклад, 'yue-jyutping' повертається до 'zh-yue-jyutping', але не впливає на 'fr-FR', оскільки 'fr' не є розширеним мовним підтегом. Ця нормалізація застосовується лише до елементів, які фактично змінені: Під час редагування заголовків доріжок піддаються впливу лише ті елементи мови доріжки, які встановлені за допомогою специфікацій редагування. Мови доріжок, які не редагуються, не змінюються. Редагування доріжки, але встановлення лише властивостей, крім мови, також не вплине на мову. Під час редагування розділів піддаються впливу всі мовні елементи всіх елементів розділу, оскільки розділи, що вже існують, завжди замінюються повністю. Під час редагування тегів піддаються впливу лише ті мовні елементи тегів, які фактично замінені. Наприклад, заміна глобальних тегів не впливає на наявні теги доріжок. Найкращий спосіб нормалізувати всі наявні мовні теги у файлі - це зробити його ремукс за допомогою mkvmerge(1) і встановити його параметр '--normalize-language-ietf' у потрібний режим.
--command-line-charset character-set | Встановлює набір символів заданого в командному рядку для конвертації. Типово використовується набір символів згідно поточної локалі системи.
--output-charset character-set | Встановлює вихідний набір символів заданого в командному рядку для конвертації. Типово використовується набір символів згідно поточної локалі системи.
-r, --redirect-output file-name | Записує всі повідомлення у файл file-name, замість консолі. Хоча це можна легко зробити за допомогою переспрямування виводу, є випадки, коли цей параметр потрібний: коли термінал повторно інтерпретує вихід перед записом його у файл. Набір символів встанвлений з --output-charset враховується.
--no-bom | Normally text files that are created & encoded in one of the UTF variants will start with a byte order marker (BOM). Using this option disables writing that byte order marker.
--ui-language code | Використовується примусовий переклад для мови code (наприклад, 'de_DE' для німецького перекладу). Після введення list' як code програма відобразить список доступних перекладів.
--abort-on-warnings | Повідомляє програмі припинити роботу після першого попередження. Код виходу з програми буде 1.
--debug topic | Увімкнути налагодження для певної функції. Цей параметр корисний лише для розробників.
--engage feature | Вмикає експериментальні функції. Список доступних функцій можна запросити за допомогою mkvpropedit --engage list. Ці функції не призначені для використання в звичайних ситуаціях.
--gui-mode | Вмикає режим графічного інтерфейсу. У цьому режимі можуть бути виведені спеціально відформатовані рядки, які можуть повідомляти керуючому графічному інтерфейсу, що відбувається. Ці повідомлення мають формат '#GUI#message'. За повідомленням можуть слідувати пари ключ/значення, як у '#GUI#message#key1=value1#key2=value2…'. Ані повідомлення, ані ключі ніколи не перекладаються і завжди виводяться англійською.
-v, --verbose | Задає відображення розширеної інформації про важливі елементи Matroska(tm).
-h, --help | Відображається інформація про використання додатку і відбувається завершення роботи додатку.
-V, --version | Відображається інформація про версію додатку і відбувається завершення роботи додатку.
@options-file.json | Читає додаткові аргументи командного рядка з файлу options-file. Повне пояснення про підтримувані формати для таких файлів див. розділ "Файли параметрів" у посібнику користувача mkvmerge(1).

# 3. Селектори редагування

Параметр --edit встановлює розділ файлу Matroska(tm) (інформація про сегмент або заголовки певної доріжки), з яким діють усі наступні дії add, set та delete. Це залишається дійсним, доки не буде знайдено наступний параметр --edit. Аргумент цього параметра називається селектором редагування.

За замовчуванням mkvpropedit(1) відредагує розділ інформації про сегмент.

## 3.1. Інформація сегмента

Інформацію про сегмент можна вибрати одним із трьох слів: 'info', 'segment_info' або 'segmentinfo'. Він містить такі властивості, як заголовок сегмента або UID сегмента.

## 3.2. Заголовки доріжки

Заголовки доріжок можна вибрати за допомогою дещо складнішого селектора. Усі варіанти починаються з 'track:'. Властивості заголовка доріжки включають такі елементи, як код мови, прапоруць 'доріжка за замовчуванням' або назва доріжки.

Option | Description
--- | ---
track: n | Якщо параметр n є числом, то буде вибрано n-на доріжка. Порядок доріжок такий самий, як і параметр --identify виводу mkvmerge(1). Нумерування починається з 1.
track: tn | Якщо параметр починається з одного символу t, за яким слідує n, то буде вибрано n-на доріжка певного типу доріжок. Параметр типу доріжки t має бути одним із чотирьох символів: 'a' для звукової доріжки, 'b' для доріжки кнопки, 's' для доріжки субтитрів і 'v' для відеодоріжки. Порядок відстеження такий самий, як і параметр --identify виводу mkvmerge(1). Нумерування починається з 1.
track:=uid | Якщо параметр починається з '=', за яким слідує число uid, буде обрано доріжку, елемент доріжки UID якої дорівнює заданому uid. Доріжки UID можна отримати за допомогою mkvinfo(1).
track:@number | Якщо параметр починається з '@', за яким слідує число number, буде вибрано доріжку, елемент якої доріжки дорівнює цьому number. Номери доріжок можна отримати за допомогою mkvinfo(1).

## 3.3. Примітки

Через природу селекторів редагування доріжок можливо, що кілька селекторів дійсно відповідають одному і тому заголовку доріжки. У таких випадках усі дії для цих селекторів редагування будуть об’єднані та виконані в тому порядку, у якому вони вказані в командному рядку.

# 4. Селектори вкладень

Селектор вкладень використовується з двома діями: --replace-attachment і --delete-attachment. Він може мати одну з наступних чотирьох форм:

1. Вибір за ідентифікатором вкладення. У цій формі селектор — це просто число, ідентифікатор вкладення, який виводить команда ідентифікації mkvmerge(1).

2. Вибір за UID вкладення (унікальний ідентифікатор). У цій формі селектором є знак рівності =, що слідує за номером, унікальний ідентифікатор вкладення, який виводить команда детальної ідентифікації mkvmerge(1).

3. Вибір за назвою вкладення. У цій формі селектором є буквене слово name:, за яким слідує ім’я наявного вкладення. Якщо цей селектор використовується з --replace-attachment, то двокрапки в назві для відповідності мають екрануватися за допомогою \c.

4. Вибір за типом MIME. У цій формі селектором є буквене слово mime-type:, за яким слід MIME-тип існуючого вкладення. Якщо цей селектор використовується з --replace-attachment, то двокрапки в типі MIME для відповідності мають екрануватися за допомогою \c.

# 5. Робота з мовами

mkvpropedit(1) переважно намагається робити правильні речі за умовчанням. Тому зміни властивості language змусять mkvpropedit(1) застосувати таку ж зміну як до нового елемента «LanguageIETF», так і до старого елемента «Language», подібно до того, як mkvmerge(1) застосовує мову до обох елементів. Наприклад, під час використання mkvpropedit movie.mkv --edit track:2 --set language=zh-TW елемент «LanguageIETF» буде встановлений на zh-TW, а старий елемент "Language" на chi.

Крім того, є нова властивість заголовка доріжки під назвою language-ietf, яку можна встановити або видалити. Зміни цієї властивості застосовуються лише до нового елемента заголовка доріжки "LanguageIETF". Застереження полягає в тому, що старий елемент заголовка доріжки «Language» є обов'язковим елементом у Matroska — це означає, що навіть якщо він відсутній у файлі, він має однакове значення. Коли користувач встановлює лише властивість language-ietf, але не властивість language, mkvpropedit(1) буде додавати старий елемент "Language" у певних випадках і встановить його в und (що означає "невизначений"), оскільки користувач не вказав для нього значення.

Під час читання файлів розділів XML або файлів теґів mkvpropedit(1) працює так само, як mkvmerge(1).

Створення нових елементів може бути повністю відключено за допомогою командного рядка «--disable-language-ietf», який діє на всі три нові елементи.

За допомогою параметра --normalize-language-ietf можна вибрати метод нормалізації, який застосовується до розширених мовних підтегів.

# 6. Приклади

Наступний приклад редагує файл під назвою 'movie.mkv'. Він встановлює назву сегмента та змінює код мови аудіо та доріжки субтитрів. Зауважте, що цей приклад можна скоротити, виключивши перший параметр --edit, оскільки редагування елемента інформації про сегмент є за замовчуванням для всіх параметрів, знайдених перед першим параметром --edit.

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

Другий приклад видаляє «прапор доріжка за замовчуванням» з першої доріжки субтитрів і встановлює його для другої. Зауважте, що mkvpropedit(1), на відміну від mkvmerge(1), не встановлює «прапор доріжка за замовчуванням» для інших доріжок на «0», якщо для деякої доріжки автоматично встановлено значення «1».

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

Заміна тегів для другої доріжки субтитрів у файлі виглядає так:

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

Щоб видалити всі теги, потрібно залишити ім’я файлу:

    $ mkvpropedit movie.mkv --tags all:

Заміна розділів у файлі має такий вигляд:

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

Щоб видалити всі розділи, потрібно залишити ім’я файлу:

    $ mkvpropedit movie.mkv --chapters ''

Додавання файла шрифта (Arial.ttf) у якості вкладення:

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

Додавання файла шрифта (89719823.ttf) у якості вкладення і надання деякої інформації, оскільки це насправді просто 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

Заміна одного файла шрифту вкладення (Comic.ttf) іншим (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

Видалення другого вкладеного файлу, яким би він не був:

    $ mkvpropedit movie.mkv --delete-attachment 2

Видалення всіх вкладених шрифтів за типом MIME:

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

# 7. Коди завершення

mkvpropedit; завершає роботу з одним з трьох кодів виходу:

- 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. WWW

Остання версія завжди може бути знайдена на веб-сторінці MKVToolNix.