Přihlásit se na XBMC-Kodi.cz

Toto téma je určené především autorům video doplňků (tedy pluginů v terminologii Kodi) a mělo by být jakýmsi shrnutím pravidel, která by bylo vhodné dodržovat pro to, aby způsob zobrazení, které pluginy používají, odpovídal filosofii Kodi. Dodržování pravidel vynikne především v situacích, kdy v Kodi použitý skin nabízí nějaké přehledové funkce zobrazení, ve kterých se potkávají seznamy (widgety) z různých pluginů, případně při zobrazování dalších (doplňkových) informací, u kterých nejednotnost řešení různými pluginy nevypadá hezky. Skinem se toho dá hodně vyřešit, ale ne vždy všechno, nehledě na to, že přizpůsobování skinu pluginu na této úrovni je systémově špatně a je to cesta do pekla. Samozřejmě to neznamená, že by se plugin měl přizpůsobit skinu, to je asi jasné. Přirozené je, aby se skin i plugin "potkaly" na společném rozhraní a obě strany ctily jeho pravidla a zvyklosti použití.

---

Obsah kontejneru

Nejdůležitějším (dalo by se napsat, že i jediným) rozhraním mezi pluginem a skinem z pohledu tohoto tématu jsou procedury gui knihovny (xbmcgui) Kodi. Tady má plugin většinou jedinou možnost vybrat si, jak budou jeho data v Kodi interpretována a prezentována. A pro to má (víceméně), pouze jedinou možnost, a tou je naplnění kontejneru, s jasně danou strukturou a významem jednotlivých položek. A tady bývá ta zásadní potíž. Ne vždy to autoři pluginů dělají podle zvyklostí a pravidel. Jistě, někdy je za tím zcela jasný autorův záměr a v takovém případě nelze, než se s tím smířit. Mně jde ale o ty případy, kdy si autor zásady správného významu jednotlivých položek neuvědomuje, nebo kdy je nezná. Pokusím se pár příkladů popsat, pro identifikaci použiji "jazyk" skinu - ale protože název položek v kontejneru je v přímé relaci s parametry datových objektů v xbmcgui, mělo by to být zřejmé.

Title

Představuje primární a jasnou identifikaci dané položky. Ať už je to film, seriál, epizoda. Pokud chce tvůrce pluginu přidat nějakou další informaci, neměl by to dělat zde. Typickou chybou například je, když se do této položky v případě epizody vloží i název seriálu nebo číslo série. Do Title patří tedy pouze název daného titulu.

TVShowTitle

Obsahuje název seriálu, ke kterému daná položka (epizoda, série) patří. Problémem u pluginů bývá ne to, že je zde umístěna špatná informace, ale spíše to, že zde není umístěna informace žádná. Chybějící příslušnost epizody k seriálu se pak může projevit u widgetů nebo detailů tak, že se prostě nepozná, o jaký seriál jde. To pak často vede k tomu, že se naopak název seriálů přidává k položkám epizod, čímž se problém špatného používání eskaluje. Jedno chybné použití tak vede k druhému...

Velmi často (takřka vždy) se většina odkazů na videa u video pluginů internetových TV a podobných zdrojů, deklaruje jako epizody. Z logiky věci pak jsou pořady, v rámci kterých jsou videa deklarována, vlastně seriály. A právě tak by měly být jednotlivé položky vyplňovány. Tohle pokládám z hlediska skinu za největší problém a přitom problém jednoduše řešitelný. Ze mnou používaných video pluginů to ctí snad pouze Mall.
[attachment=5762]
Na výše uvedeném screenshotu je to hezky vidět. U widgetu Stream - Nejnovější videa (plugin TelevizeSeznam) je název pořadu (s oddělovačem "|") přidán v addon do položky Title, takže se zobrazuje ve spodním řádku popisu epizody spolu s názvem epizody, obsah TVShowTitle není vyplněný, takže horní řádek popisu je prázdný. U widgetu Mall - Nejnovější (plugin Mall) jsou správně vyplněné položky Title i TVShowTitle, takže zobrazení vypadá přesně tak, jak autoři skinu zamýšleli a jak je to i celkem přirozené a pro uživatele příjemné. Oba texty jsou vidět naráz, oba se také mohou nezávisle na sobě posouvat.

Label

Velmi často se vyskytuje názor, že v Label by mělo být to samé co je v Title a u řady pluginů to i tak bývá realizováno. Žádné takové pravidlo ale není (ostatně, kdyby to tak bylo, jaký by měla položka Label asi smysl, že?). Label je určen právě a především pro to, aby se do něj uložila informace, kterou budeme chtít mít zobrazenou v daném seznamu. Chceme-li tedy pro zobrazení k položce přidat nějakou další informaci. Např. již zmíněné přidání názvu seriálu (pořadu) nebo číslo epizody, uděláme to právě v položce Label, která je pro to určena, ale v žádném případě ne v položce Title.

Label2

Label2 obsahuje doplňkovou informaci, které se většinou používá k zobrazení v rámci seznamu položek. Typicky roku, délky videa, hodnocení, a celé řady dalších. Ale opět jen pro potřeby zobrazení, protože hodnoty uvedených informací mají své vlastní, primární položky. Skiny položku Label2 používají pro zobrazení nějaké default informace (kterou do této položky vloží scraper nebo je tam uložena v pluginu). Prakticky u všech skinů je zobrazení této kategorie informací dopočítáváno specifickým způsobem a podle dalších kritérií (typ zobrazení, způsob řazení, atd.) a teprve, pokud dopočet pro danou konstelaci nenajde žádný předpis, použije zpravidla default uložený v Label2. Dobře je to vidět na pluginu Stream-Cinema a jeho typu zobrazení Výchozí. 

Formátování textů

Kodi, umožňuje v rámci skinu, kromě volby fontů, barvy a typů písma, definovat i další vybrané parametry zobrazení textu pomocí formátovacích tagů (bold, italic, color, ...) vkládaných přímo do textu. Autoři addons je pak rádi používají při formátování svých textů. Je to sice efektní a umožňuje to plugin více individualizovat, ale má to i svou stinnou stránku. Je to v první řadě skin, který by měl určovat formátování a pokud se k tomu odhodlá autor addon, pak riskuje, že některé funkce zobrazení (ale nejen ony) nemusí fungovat 100% správně. Mohou se pak objevit vnořené tagy, na které skin neumí (nemůže) správně zareagovat a ve finálním textu se pak objevují artefakty tagů nebo nemusí vždy dobře zafungovat speciální funkce ve skinu, které se opírají o analýzu textu a pokud se v nich formátovací tagy objeví, je s nimi potíž.

Na druhou stranu je třeba říci, že zkušený skinner by měl ve specifických případech pokud možno vyvarovat použití Label a Label2 (třeba i právě proto, že se v něm mohou vyskytnou formátovací znaky) a výstupní text si ve speciálních funkcích addon sestavit z primárních informací, tedy položek jako je Title, TVShowTitle a dalších. Tohle je myslím ukázka toho, jak je důležité ctít pravidla a zvyklosti na obou stranách, jak autory addon, tak autory skinů.

Já osobně jsem Label v řadě případů použil nevhodně a tak nakonec spíš počítám s tím, že se v Label může objevit cokoliv, a pokud ho použiji, tak rozhodně bez toho, že bych do formátování zobrazení jeho obsahu jakkoliv zasahoval.

Protože toto téma nějak nepoutá pozornost, chtěl bych ho oživit upozorněním na pozitivní příklad. Nový autor (respektive ten, kdo se ho po osiření ujal) pluginu Aktuálně @wombat, při jedné z oprav nefunkčního doplňku (za kterou zaslouží dík především), zároveň upravil systém označování jednotlivých položek v seznamu pluginu. Konečně už widget tohoto pluginu obsahuje data ve správné struktuře, přesně tak, jak to autoři skinu zamýšleli a jak to odpovídá zásadám a pravidlům Kodi. Podívejte se na screenshot a porovnejte widget Aktuálně a Televize Seznam...
   

Typy kontejnerů a položek

S rozvíjejícím se tvorbou doplňků typů video plugin, by si bylo dobré pohovořit o tom, jak nejlpépe koncipovat nastavení obsahu kontejnerů. Jsou v podtstatě dvě možnosti. První, celkem přirozená, je možnost označit jak kontejner, tak jendotlivé položky v něm jako video. Je to logické a zdá se, že k tomu neexistuje jiná varianta. Ale ona existuje. Je uvedena v 1. příspěvku tohoto tématu, který vznikl již před časem, a uvedl příklad a důvody, proč ji použít. Ano, příspěvek je tak trochu tendenční, protože reagoval na celou řadu doplňků, zobrazující obsah, mající charakter TV pořadů, s jednotlivými díly, kde je uvedené řešení celkem přirozené. Pořad může, ale nutně nemusí (není totiž "playable", takže na tom zas tak nezáleží), být v takovém případě označen jako tvshow, a tedy i seznam opřadů jako tvshows. Název pořadu by pak, aby byla konzistence dokonalá, měl být uveden jak v TVShowsTitle, tak i Title a případně, klidně už v nějaké modifiované verzi, i v label. Co je však důležité, chceme-li dosáhnout toho, o čem se píše už ve zmíněném 1.příspěvku, je to aby jendotlivé díly pořadu byly ozbačeny jako episode, příslušný kontejner jako episodes, a byly odpovídajícím způsobem vyplněny i odpovídjící položky. Název pořadu v TVShowTitle, název dílu v Title a, klidně už v nějaké modifiované verzi, i v label.

Samozřejěm to není dogma. Video doplňky typu archivu TV vysílání budou fungovat více či méně s jakýmkoliv nastavením příslušných kontejnerů a položek v nich. Ale v okamžiku, když ho bude chtít uživatel použít v nějaké sofistikované verzi skinu nebo doplněk zařadí jako zdroj do nějakého dalšího doplňku, nenarazí sice na úplně nepřekonatelný problém, ale jeho prezentace (doplňku) nebude taková, jaká by mohla být. A to je škoda. Kodi nabízí poměrně dost možností, jak s daty v doplňcích pracovat a pokud daný externí zdroj (v případě plugin-ů) ta data nabízí, tak je podle mne přirozené je do Kodi předat všechna a v odpovídajcíí formě.

Končete funkce pluginu konzistentně, bez ohledu na výsledek.

Zdánlivě nejasné doporučení, ale s celkem jednodcuchým zdůvodněním a vysvětlením.

O co jde?

O to, že v případě, je-li výstupem nějaké funkce (nejčastěji jde v této souvislosti o vyhledávání) prázdný seznam, nebojte se jako prázdný zobrazit. Proč? Je to proto, že když např. použijete volání video pluginu jako zdroj pro nějakou další funkci, např. ve skinu, nebo v jiném doplňku, tak skončíte-li nějak nestandadně - např. chybovým modálním oknem a návratem do základní obrazovky videa, kde to pak po zadání BACK rozhodí logiku posloupností na zásobníku, protože uživatel skončí na Home stránce a je z toho více či méně zmatený. Navíc ztratí původní kontext a musí se do něj pracně vracet.

Výše popsané chování je vidět např. u TMDb Helperu nebo Stream Cinema. Myslím si, že zobrazení prázdného seznamu je pro pro uživatele zcela relevantní výsledek a není třeba mu to ještě explicitně sdělovat. A když už, tak se pro takový případ lépe než modální okno hodí např. Kodi Notifikace, jejíž proces zobrazení je vůči tomu, co se děje při běhu pluginu, asynchornní.

Někdo se možná pozastaví na tím, jak to, že k takovému řešení nedocházelo u Stream Cinema Community. Nejsem si 100% jistý, jestli byly stavy, kdy by seznam hledaného textu byl prázdný, nějak extra ošetřené, co je však zřejmé (a možná pravděpodobnější), že řešení vyhledávání (s využitím elastic search) prostě vždycky a za všech okolností nějaký výsledek vrátilo. Alespoň jsem se tedy za tu dobu používání SCC s ničím jiným nesetkal. To se bohužel o TMDb Helperu i Stream Cinema říci nedá.

Využívejte možnosti Kodi a jejich skinů uvážlivě I.

Velmi často autoři pluginů vkládají do položky Label, kromě názvu položky (filmu, seriálu, epizody) i další informace. Což o to, není to úplně špatný nápad, zvlášť když chceme, aby uživatel dostal na jednom místě přehledně co nejvíce informací. Ale pozor. Často se u toho dělají chyby, resp. volí se postupy, které, z hlediska toho, co Kodi nabízí a jak jeho skiny (které tu informaci nakonec zobrazí) pracují, nemusí být vždy úplně ideální:

• Autor vše, co vloží do Label, vloží i do Title, možná pod dojmem mýtu, že to tak má být. Tak si to totiž někteří vysvětlují, že to co je v Label, to musí být i v Title. Ale kdyby to tak bylo, tak by jedna z těch položek neměla smysl, ne? Je třeba si uvědomit, že Title je klíč záznamu v databázi/containeru, a že by tedy v něm měla být jen to, co je klíčem. Tzn. jednoznačná identifikace položky daného záznamu. Oproti tomu Label je to, co chceme, aby k dané položce uživatel viděl v zobrazeném seznamu.
  
• Autor do Label vkládá i to, co by Kodi dokázalo ve skinu zobrazit i jiným, standardním způsobem. Jedná se o doplňující informace, které se, pravda nemusí vždy zobrazit všechny tak, jak si to autor přeje a jak by bylo i z hlediska logiky vhodné, ale některé druhy takových informací jsou z hlediska konečného výsledku přeci jen k zamyšlení. Posledním takovým příkladem, který se tady na fóru dikutuje, je zobrazení velikosti souborů. Pro to má Kodi poměrně standardní mechanismus, kdy v případě seznamu videí (tzn. seznamu z container-u typu videos), zobrazí velikost souboru v seznamu v pozici zobrazení Label2. Kodi v případě typu videos, pokud ji zná, zobrazí velikost souboru, převedenou optimálně na vhodné jednotky (B, KB, MB, GB) automaticky tak, aby výsledek by co nejlepší. Pokud Kodi tu velikost nezná, tedy například v případech, kdy nejde o fyzicky dostupné soubory, může autor tu velikost do příslušné položky (size) každého záznamu (pokud ji má v pluginu k dipozici) vložit pomocí setInfo. Vkládá se přitom délka souboru v bytech, optimální převod na vhodné jendotky při zobrazení (viz výše) Kodi zajistí automaticky.
  
• Autor použije metakódy pro změnu barvy části textu. Ano, je to efektní, ale je třeba s tímto postupem pracovat uvážlivě. Je totiž třeba pamatovat na to, že ve finále má poslední slovo v barvě textu a jeho pozadí skin. A že barvy textu a jeho pozadí mohou být olivněny jak uživatelským nastavením daného skinu, tak současně s tím i kontextem. Napevno definovaná barva textu pak může kolidovat např. s barvou pozadí vybrané položky. A pokud se barvy sejdou v nevhodném kontrastu nebo budou dokonce stejné, je jasné, že čitelnost textu to může zásadně ovlivnit.