mkvpropedit -- Úprava vlastností existujících souborů Matroska bez úplného opětovného multiplexování

mkvpropedit -- Úprava vlastností existujících souborů Matroska(tm) bez úplného opětovného multiplexování

# 1. Přehled

mkvpropedit options {source-filename} {actions}

# 2. Popis

Tento program analyzuje existující soubor Matroska(tm) a upraví některé jeho vlastnosti. Změny poté zapíše do existujícího souboru. Mezi upravitelné vlastnosti patří prvky informací o úseku (např. název) a hlavičky stop (např. kód jazyka, příznak „výchozí stopa“ nebo název).

Volby:

Option | Description
--- | ---
-l, --list-property-names | Vypíše všechny známé a upravitelné názvy vlastností, jejich typ (řetězec, celé číslo, logická hodnota atd.) a stručný popis. Program poté skončí. Parametr source-filename proto není nutné zadávat.
-p, --parse-mode mode | Nastaví režim analýzy. Parametr 'mode' může mít hodnotu 'fast' (ta je zároveň výchozí) nebo 'full'. Režim 'fast' neanalyzuje celý soubor, ale k nalezení požadovaných prvků zdrojového souboru používá prvky hlavičky vyhledávání. V 99 % případů to stačí. U souborů, které prvky hlavičky vyhledávání neobsahují nebo jsou poškozené, však uživatel možná bude muset nastavit režim analýzy 'full'. Úplná kontrola souboru může trvat několik minut, zatímco rychlá kontrola trvá jen několik sekund.

Akce pracující s vlastnostmi hlaviček stop a informací o úseku:

Option | Description
--- | ---

-e, --edit selector

Nastaví oddíl souboru Matroska(tm) (informace o úseku nebo hlavičky určité stopy), se kterým budou pracovat všechny následující akce přidání, nastavení a odstranění. Tuto volbu lze použít vícekrát, a upravit tak více než jeden prvek.

Ve výchozím nastavení bude mkvpropedit(1) upravovat oddíl informací o úseku.

Úplný popis syntaxe najdete v oddílu o selektorech úprav.

-a, --add name=value | Přidá vlastnost name s hodnotou value. Vlastnost se přidá i v případě, že už taková vlastnost existuje. Většina vlastností je jedinečná a nemůže se vyskytovat vícekrát.
-s, --set name=value | Nastaví všechny výskyty vlastnosti name na hodnotu value. Pokud taková vlastnost neexistuje, přidá se.
-d, --delete name | Odstraní všechny výskyty vlastnosti name. Některé vlastnosti jsou povinné a nelze je odstranit.

Akce pracující se štítky a kapitolami:

Option | Description
--- | ---

-t, --tags selector:filename

Přidá nebo nahradí štítky v souboru štítky ze souboru filename, případně je odstraní, je-li filename prázdný. mkvpropedit(1) načítá stejný formát štítků XML jako mkvmerge(1).

Parametr selector musí být jedno ze slov all, global nebo track. Při hodnotě all mkvpropedit(1) nahradí nebo odstraní všechny štítky v souboru. Při hodnotě global nahradí nebo odstraní pouze globální štítky.

Při hodnotě track mkvpropedit(1) nahradí štítky konkrétní stopy. Štítky načtené ze souboru filename budou navíc přiřazeny stejné stopě. Stopa se zadává stejným způsobem jako selektory úprav (viz níže), například --tags track:a1:new-audio-tags.xml.

--add-track-statistics-tags | Vypočítá statistiky všech stop v souboru a přidá pro ně nové statistické štítky. Pokud soubor takové štítky již obsahuje, aktualizují se.
--delete-track-statistics-tags | Odstraní ze souboru všechny existující statistické štítky stop. Pokud soubor statistické štítky stop neobsahuje, nezmění se.
-c, --chapters filename | Přidá nebo nahradí kapitoly v souboru kapitolami ze souboru filename, případně je odstraní, je-li filename prázdný. mkvpropedit(1) načítá stejné formáty XML a jednoduchých kapitol jako mkvmerge(1).

Akce pro práci s přílohami:

Option | Description
--- | ---

--add-attachment filename

Přidá novou přílohu ze souboru filename.

Byla-li před touto volbou použita volba --attachment-name, použije se její hodnota jako název nové přílohy. Jinak se název odvodí z parametru filename.

Byla-li před touto volbou použita volba --attachment-mime-type, použije se její hodnota jako typ MIME nové přílohy. Jinak se typ automaticky zjistí z obsahu souboru filename.

Byla-li před touto volbou použita volba --attachment-description, použije se její hodnota jako popis nové přílohy. Jinak se žádný popis nenastaví.

Byla-li před touto volbou použita volba --attachment-uid, použije se její hodnota jako UID nové přílohy. Jinak se automaticky vytvoří náhodné UID.

--replace-attachment selector: filename

Nahradí jednu či více příloh odpovídajících parametru selector souborem filename. Odpovídá-li parametru selector více existujících příloh, obsah všech se nahradí obsahem souboru filename.

Parametr selector může mít jeden ze čtyř tvarů. Ty jsou vysvětleny níže v oddílu selektory příloh.

Byla-li před touto volbou použita volba --attachment-name, nastaví se její hodnota jako nový název každé upravené přílohy. Jinak se názvy nezmění.

Byla-li před touto volbou použita volba --attachment-mime-type, nastaví se její hodnota jako nový typ MIME každé upravené přílohy. Jinak se typy MIME nezmění.

Byla-li před touto volbou použita volba --attachment-description, nastaví se její hodnota jako nový popis každé upravené přílohy. Jinak se popisy nezmění.

Byla-li před touto volbou použita volba --attachment-uid, nastaví se její hodnota jako nové UID každé upravené přílohy. Jinak se UID nezmění.

--update-attachment selector

Nastaví vlastnosti jedné či více příloh odpovídajících parametru selector. Odpovídá-li parametru selector více existujících příloh, aktualizují se vlastnosti všech.

Parametr selector může mít jeden ze čtyř tvarů. Ty jsou vysvětleny níže v oddílu selektory příloh.

Byla-li před touto volbou použita volba --attachment-name, nastaví se její hodnota jako nový název každé upravené přílohy. Jinak se názvy nezmění.

Byla-li před touto volbou použita volba --attachment-mime-type, nastaví se její hodnota jako nový typ MIME každé upravené přílohy. Jinak se typy MIME nezmění.

Byla-li před touto volbou použita volba --attachment-description, nastaví se její hodnota jako nový popis každé upravené přílohy. Jinak se popisy nezmění.

Byla-li před touto volbou použita volba --attachment-uid, nastaví se její hodnota jako nové UID každé upravené přílohy. Jinak se UID nezmění.

--delete-attachment selector | Odstraní jednu či více příloh odpovídajících parametru selector. Parametr selector může mít jeden ze čtyř tvarů. Ty jsou vysvětleny níže v oddílu selektory příloh.

Volby pro akce s přílohami:

Option | Description
--- | ---
--attachment-name name | Nastaví název, který se použije pro následující operaci --add-attachment nebo --replace-attachment.
--attachment-mime-type mime-type | Nastaví typ MIME, který se použije pro následující operaci --add-attachment nebo --replace-attachment.
--attachment-description description | Nastaví popis, který se použije pro následující operaci --add-attachment nebo --replace-attachment.

--enable-legacy-font-mime-types

Povolí používání zastaralých typů MIME pro určité typy příloh písem. Například pro písma TrueType se použije 'application/x-truetype-font' namísto 'fonts/ttf'.

Týká se to přidávání nových příloh i nahrazování existujících příloh, ale pouze tehdy, není-li zadán nový typ MIME. Ostatní existující přílohy se nezmění.

Dotčenými typy MIME jsou 'font/sfnt', 'font/ttf' a 'font/collection', které se všechny mapují na 'application/x-truetype-fonts', a 'font/otf', který se mapuje na 'application/vnd.ms-opentype'.

Další volby:

Option | Description
--- | ---

--disable-language-ietf

Za běžných okolností mkvpropedit(1) při požadavku uživatele na změnu vlastnosti hlavičky stopy 'language' použije stejnou změnu také na nový prvek hlavičky stopy LanguageIETF, vedle staršího prvku Language. Při použití této volby se změna použije pouze na starší prvek Language.

Tato volba nemá vliv na změny požadované prostřednictvím vlastnosti hlavičky stopy 'language-ietf'.

--normalize-language-ietf mode

Povolí normalizaci všech jazykových značek IETF BCP 47 buď na jejich kanonickou podobu v režimu 'canonical', na podobu rozšířených jazykových podznaček v režimu 'extlang', nebo ji vypne režimem 'off'. Ve výchozím nastavení se používá normalizace na kanonickou podobu.

V kanonické podobě se všechny podznačky, pro něž existují upřednostňované hodnoty, nahradí těmito hodnotami. Tím se např. 'zh-yue-jyutping' převede na 'yue-jyutping' nebo 'fr-FX' na 'fr-FR'.

Pro podobu rozšířených jazykových podznaček se nejprve vytvoří kanonická podoba. Poté se všechny primární jazykové podznačky, pro něž existuje rozšířená jazyková podznačka, nahradí touto rozšířenou jazykovou podznačkou a její předponou. Tím se např. 'yue-jyutping' převede zpět na 'zh-yue-jyutping', na 'fr-FR' to však nemá vliv, protože 'fr' není rozšířená jazyková podznačka.

Tato normalizace se použije pouze na prvky, které se skutečně mění:

- Při úpravách hlaviček stop jsou ovlivněny pouze ty jazykové prvky stop, které jsou nastaveny prostřednictvím specifikací úprav. Jazyky neupravovaných stop se nezmění. Jazyk neovlivní ani úprava stopy, při které se nastavují pouze jiné vlastnosti než jazyk.

- Při úpravách kapitol jsou ovlivněny všechny jazykové prvky všech prvků kapitol, protože existující kapitoly se vždy zcela nahrazují.

- Při úpravách štítků jsou ovlivněny pouze jazykové prvky skutečně nahrazovaných štítků. Když například nahradíte globální štítky, existující štítky stop nebudou ovlivněny.

Nejlépe se všechny existující jazykové značky v souboru normalizují jeho opětovným multiplexováním pomocí mkvmerge(1) s volbou '--normalize-language-ietf' nastavenou na požadovaný režim.

--command-line-charset character-set | Nastavuje znakovou sadu, ze které se převádějí řetězce zadané na příkazovém řádku. Výchozí je znaková sada daná aktuálním národním prostředím systému.
--output-charset character-set | Nastavuje znakovou sadu, do které se převádějí řetězce určené k výstupu. Výchozí je znaková sada daná aktuálním národním prostředím systému.
-r, --redirect-output file-name | Zapíše všechny zprávy do souboru file-name místo na konzoli. Ačkoli to lze snadno provést přesměrováním výstupu, tato volba je potřeba v případech, kdy terminál výstup před zápisem do souboru znovu interpretuje. Je respektována znaková sada nastavená pomocí --output-charset.
--no-bom | Textové soubory vytvořené & kódované v některé z variant UTF obvykle začínají značkou pořadí bajtů (BOM). Tato volba zakáže zápis této značky pořadí bajtů.
--ui-language code | Vynutí použití překladů pro jazyk code (např. 'de_DE' pro německé překlady). Zadáním 'list' jako code program vypíše seznam dostupných překladů.
--abort-on-warnings | Ukončí program po vydání prvního upozornění. Návratový kód programu bude 1.
--debug topic | Zapne ladění určité funkce. Tato volba je užitečná pouze pro vývojáře.
--engage feature | Zapne experimentální funkce. Seznam dostupných funkcí lze vyžádat pomocí mkvpropedit --engage list. Tyto funkce nejsou určeny pro běžné použití.
--gui-mode | Zapne režim GUI. V tomto režimu mohou být vypisovány speciálně formátované řádky, které řídicímu GUI sdělují, co se děje. Tyto zprávy mají formát '#GUI#message'. Za zprávou mohou následovat dvojice klíč/hodnota jako v '#GUI#message#key1=value1#key2=value2…'. Zprávy ani klíče se nikdy nepřekládají a vždy jsou vypisovány anglicky.
-v, --verbose | Vypisuje podrobné informace a zobrazuje všechny důležité prvky Matroska(tm) při jejich čtení.
-h, --help | Zobrazí informace o použití a ukončí se.
-V, --version | Zobrazí informace o verzi a ukončí se.
@options-file.json | Načte další argumenty příkazového řádku ze souboru options-file. Úplné vysvětlení podporovaných formátů takových souborů naleznete v oddílu „Option files“ manuálové stránky mkvmerge(1).

# 3. Selektory úprav

Volba --edit nastaví oddíl souboru Matroska(tm) (informace o úseku nebo hlavičky určité stopy), se kterým budou pracovat všechny následující akce přidání, nastavení a odstranění. Nastavení zůstává platné až do nalezení další volby --edit. Argument této volby se nazývá selektor úprav.

Ve výchozím nastavení bude mkvpropedit(1) upravovat oddíl informací o úseku.

## 3.1. Informace o úseku

Informace o úseku lze vybrat jedním z těchto tří slov: 'info', 'segment_info' nebo 'segmentinfo'. Obsahují vlastnosti, jako je název úseku nebo UID úseku.

## 3.2. Hlavičky stop

Hlavičky stop lze vybrat o něco složitějším selektorem. Všechny varianty začínají řetězcem 'track:'. Vlastnosti hlavičky stopy zahrnují prvky, jako je kód jazyka, příznak „výchozí stopa“ nebo název stopy.

Option | Description
--- | ---
track: n | Je-li parametr n číslo, vybere se stopa s pořadovým číslem n. Pořadí stop je stejné jako ve výstupu volby --identify programu mkvmerge(1). Číslování začíná od 1.

track: tn

Začíná-li parametr jediným znakem t následovaným číslem n, vybere se stopa s pořadovým číslem n v rámci daného typu. Parametr typu stopy t musí být jeden z těchto čtyř znaků: 'a' pro zvukovou stopu, 'b' pro tlačítkovou stopu, 's' pro titulkovou stopu a 'v' pro video stopu. Pořadí stop je stejné jako ve výstupu volby --identify programu mkvmerge(1).

Číslování začíná od 1.

track:=uid | Začíná-li parametr znakem '=' následovaným číslem uid, vybere se stopa, jejíž prvek UID stopy se rovná zadanému uid. Hodnoty UIDs stop lze získat pomocí mkvinfo(1).
track:@number | Začíná-li parametr znakem '@' následovaným číslem number, vybere se stopa, jejíž prvek s číslem stopy se rovná tomuto parametru number. Čísla stop lze získat pomocí mkvinfo(1).

## 3.3. Poznámky

Vzhledem k povaze selektorů úprav stop může několik selektorů ve skutečnosti odpovídat téže hlavičce stopy. V takových případech se všechny akce pro tyto selektory úprav spojí a provedou v pořadí, v němž jsou uvedeny na příkazovém řádku.

# 4. Selektory příloh

Selektor příloh se používá se dvěma akcemi --replace-attachment a --delete-attachment. Může mít jeden z následujících čtyř tvarů:

1. Výběr podle ID přílohy. V tomto tvaru je selektorem jednoduše číslo: ID přílohy vypsané identifikačním příkazem programu mkvmerge(1).

2. Výběr podle UID přílohy (jedinečného ID). V tomto tvaru je selektorem rovnítko = následované číslem: jedinečným ID přílohy vypsaným podrobným identifikačním příkazem programu mkvmerge(1).

3. Výběr podle názvu přílohy. V tomto tvaru je selektorem doslovný řetězec name: následovaný názvem existující přílohy. Použije-li se tento selektor s volbou --replace-attachment, musí být dvojtečky v porovnávaném názvu zapsány pomocí escape sekvence \c.

4. Výběr podle typu MIME. V tomto tvaru je selektorem doslovný řetězec mime-type: následovaný typem MIME existující přílohy. Použije-li se tento selektor s volbou --replace-attachment, musí být dvojtečky v porovnávaném typu MIME zapsány pomocí escape sekvence \c.

# 5. Zpracování jazyků

mkvpropedit(1) se ve výchozím nastavení většinou snaží postupovat správně. Změna vlastnosti language proto způsobí, že mkvpropedit(1) použije stejnou změnu pro nový prvek „LanguageIETF“ i starší prvek „Language“, podobně jako mkvmerge(1) nastavuje jazyk v obou prvcích. Při použití příkazu mkvpropedit movie.mkv --edit track:2 --set language=zh-TW se například prvek „LanguageIETF“ nastaví na zh-TW a starší prvek „Language“ na chi.

Kromě toho existuje nová vlastnost hlavičky stopy nazvaná language-ietf, kterou lze nastavit nebo odstranit. Změny této vlastnosti se vztahují pouze na nový prvek hlavičky stopy „LanguageIETF“. Komplikací je, že starší prvek hlavičky stopy „Language“ je v Matrosce povinný — i když tedy v souboru není přítomen, má stále předpokládanou hodnotu. Nastaví-li uživatel pouze vlastnost language-ietf, ale nikoli vlastnost language, mkvpropedit(1) proto v určitých případech přidá starší prvek „Language“ & nastaví jej na und (tedy „neurčeno“), protože uživatel jeho hodnotu nezadal.

Při načítání souborů XML s kapitolami nebo štítky pracuje mkvpropedit(1) stejně jako mkvmerge(1).

Vytváření nových prvků lze zcela zakázat volbou příkazového řádku `--disable-language-ietf`, která se vztahuje na všechny tři nové prvky.

Parametrem --normalize-language-ietf lze zvolit metodu normalizace používanou pro rozšířené jazykové podznačky.

# 6. Příklady

Následující příklad upravuje soubor nazvaný 'movie.mkv'. Nastaví název úseku a změní kód jazyka zvukové a titulkové stopy. Tento příklad lze zkrátit vynecháním první volby --edit, protože úprava prvku informací o úseku je výchozí pro všechny volby uvedené před první volbou --edit.

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

Druhý příklad odstraní příznak „výchozí stopa“ z první titulkové stopy a nastaví jej pro druhou. Upozorňujeme, že mkvpropedit(1) na rozdíl od mkvmerge(1) automaticky nenastaví příznak „výchozí stopa“ ostatních stop na „0“, když je u jiné stopy nastaven na „1“.

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

Nahrazení štítků druhé titulkové stopy v souboru vypadá takto:

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

Při odstraňování všech štítků je nutné vynechat název souboru:

    $ mkvpropedit movie.mkv --tags all:

Nahrazení kapitol v souboru vypadá takto:

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

Při odstraňování všech kapitol je nutné vynechat název souboru:

    $ mkvpropedit movie.mkv --chapters ''

Přidání souboru písma (Arial.ttf) jako přílohy:

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

Přidání souboru písma (89719823.ttf) jako přílohy a uvedení několika informací, protože ve skutečnosti jde pouze o 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

Nahrazení jednoho přiloženého souboru písma (Comic.ttf) jiným (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

Odstranění druhého přiloženého souboru bez ohledu na to, o jaký soubor jde:

    $ mkvpropedit movie.mkv --delete-attachment 2

Odstranění všech přiložených písem podle typu MIME:

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

# 7. Návratové kódy

mkvpropedit(1) končí jedním ze tří návratových kódů:

- 0 – Tento návratový kód znamená, že úprava byla úspěšně dokončena.

- 1 – V tomto případě mkvpropedit(1) vypsal alespoň jedno upozornění, ale úprava pokračovala. Upozornění má předponu 'Warning:'. V závislosti na daných problémech mohou, ale nemusí být výsledné soubory v pořádku. Uživatel by měl zkontrolovat upozornění i výsledné soubory.

- 2 – Tento návratový kód se použije po výskytu chyby. mkvpropedit(1) se ukončí hned po vypsání chybové zprávy. Chybové zprávy sahají od chybných argumentů příkazového řádku přes chyby čtení a zápisu až po poškozené soubory.

# 8. Textové soubory a převody znakových sad

Podrobnou diskusi o způsobu, jakým všechny nástroje sady MKVToolNix pracují s převody znakových sad, kódováním vstupu/výstupu, příkazového řádku a konzole, naleznete ve stejnojmenném oddílu manuálové stránky mkvmerge(1).

# 9. Proměnné prostředí

mkvpropedit(1) používá výchozí proměnné určující národní prostředí systému (např. LANG a rodinu LC_*). Další proměnné:

Option | Description
--- | ---
MKVPROPEDIT_DEBUG, MKVTOOLNIX_DEBUG a její zkrácený tvar MTX_DEBUG | Obsah se zpracuje, jako by byl předán pomocí volby --debug.
MKVPROPEDIT_ENGAGE, MKVTOOLNIX_ENGAGE a její zkrácený tvar MTX_ENGAGE | Obsah se zpracuje, jako by byl předán pomocí volby --engage.

# 10. Viz také

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

# 11. WWW

Nejnovější verzi lze vždy najít na domovské stránce MKVToolNix.