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...
[attachment=6777]

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.
  

@JiRo: co sa stalo s tvojim blogom? Uz nebude verejny? Dobre citanie tam bolo.
Beriem spet, znovu funkcne. 

Vkládání funkcí do contentu seznamu playable položek

Velmi často autoři doplňků ve snaze nabídnout uživatelům dokonalé funkce, používají řešení, kdy do seznamu přehratelných položek, nejčastěji jeho začátku nebo konci, vloží odkazy na aktivaci nějakých funkcí. Bylo a je to vidět jak na legendárním Stream Cinema Community, tak na stále ještě funkčním Stream Cinema, ale podobné řešení se objevilo i na zcela novém doplňku Nokturno, autora @matata:. Což je obzvlášť škoda, protože se zdá, že se ten doplněk začíná stávat poměrně populární.

O co konkrétně jde, budu asi nejlépe dokladovat na následujcíích screenshotech. Na prvním je vidět volba funkce TV program na základní úrovni menu doplňku. Na druhém, jaký seznam se po jejím zvolení zobrazí a na třetím, jak to dopadne, když tento seznam zadám jako zdroj widgetu.

Myslím, že to problém, který se tu snažím popsat a případně řešit, celkem jasně vysvětluje.

Snažil jsme se v průběhu doby (od prvních pokusů už proběhlo několik let) tento problém řešit na několika úrovních:

1. Začal jsm tím, co je mi nejbližší, tedy do skinu nějak dostat možnost, že se pro daný widget přeskočí prvních n-položek a začnou se zobrazovat až od té n+1. Skin engin tuto možnost nenabízí a i když jsme se o tom snažil diskutovat i s členy Kodi teamu, zda by se nedalo změnit, nebyl jsem v té době úspěšný. Bylo tedy jasné, že to na úrovni skinu nevyřeším. Nevím, jaká je situace dnes, své řešení mám, cestu k němu popíši dále, takže jsem se o další vývoj těchto funkcí skin enginu už nezajímal.
   
2. V dalších pokusech jsem se tedy soustředil na možnost, jak zdroj skinu "přesvědčit", aby ve chvíli, kdy je zobrazován ve widgetu, prvních n položek nezobrazil. V každém případě by to samozřejmě znamenalo, že bych tuto funkci musel do doplňku, jako jeho autor, doplnit. A tak se postupně stalo. Se střídavými úspěchy. Dokonce jsme si postupně vypracoval i několk variant řešení, které jsem u mých vlastních doplňků používal, takže se mohou stát předlohou k úvahám ostatních autorů:
   
   1. První verzí byl, doplnit volání dané úrovně dalším parametrem (...&widget=1&...) a pokud se v řetezci volání vyskytl, dopněk ze seznamu vyloučil specifické položky. Existovalo ještě nekolik podvariant, kdy se do parametrů například přidával počet vyloučených položek na začátku i konce seznamu, případně ještě i další. Tohle fungovalo a funguje dobře. Mělo to jen nevýhodu v tom, že pokud se widgety definovaly u skinů, kde se jejich zdroj zdával v ráci nastavení (sofistikované skiny z rodiny Arctic Horizon, Titan, Aura, ...), ted kdy nešlo o editaci definičního souboru, ale definice widgetů byla součástí nastavení. Tady to  znamenalo postupovat nadvakrát. Nejdříve definovat zdroj a pak do jeho řetězce doplnit příslušné parametry pro widget.
      
   2. Pak přišel nápad na úplnou automatizacei zadávání. V doplňku se u každého seznamu, který takové vložené funkce obsahoval, se kontrololovalo v jakém okně je seznam použit. Pokud tím oknem bylo Home, tak se předem definované položky do seznamu nepromítly. Zdále se to být jako geniální nápad, ale brzy se ukázalo, že ne tak úplně. Widget se totiž může aktualizovat i ve chvíli, kdy není v Home okně zobrazen, a v takovém případě se do seznamu znova dostaly ony nežádoucí položky.
      
   3. Nevýhody předchozího řešení jsem se pak snažil eliminovat tím, že jsem ještě zavedl pro každý dopněk specifickou property, do které jsem zapisoval stav, kdy doplněk běží, ale ukázalo se, že je to poměrně náchylné na chyby při nestandardním chování Kodi.
      
   4. Nakonec zvítězilo řešení, které se ukázalo jako nejspolehlivější, a svým způsobem vycházelo z toho prvního (a). Znamenalo to ale v routeru doplňku, pro ty položky menu, pro které to mělo smysl (tedy pro ty, co se mohou stát zdrojem widgetu), vytvořit dvě větve. První, která se zobrazovala a tvořila vlastně ui daného doplňku, druhá, která se nezobrazovala, ale sloužila pokuze k definici zdroje widgetu. Zdá se to být trochu komplikované, ale pokud doplněk navrhuje a programuje někdo, kdo ví, jak taková ideální struktura může (a má) vypadat, velkým problémem přidání další vrstvy v router nepředstvuje. Mohlo to vypadat například takto. Pro volání v základní větvi:
      Kód:

      plugin://plugin.video.doplnek/movies/trending/
      a pro volání ve větvi pro widgety:
      
      Kód:

      plugin://plugin.video.doplnek/widget/movies/trending/

 
Ale to není všechno...

Výše uvedný přístup ale vycházel z předpokladu, že do seznamu playable položek prostě ty jiné vkládat potřebujeme. Jistě, jsou takové, bez kterých se v Kodi a zejména video doplňcích neobejdeme. Za všechny typická položka Další stránka... (i když i tady se dá najít jisté řešení, ale to si nechám na někdy jindy). Ale co ty položky z výše uvdeného screenshotu Nokturna? Jsou tam vůbec potřeba? Jaké je jejich funkce:

1. Umožňují změnit nastavené jednotlivých položek filtru
   
2. Nastavení jednotlivých položek filtru zobrazují
   

Vlastní nastavení je už řešeno mimo rámec pluginu. Pro to, abychom tyto položky dostali ze seznamu, tedy potřebujeme:

1. Zajistit aktivaci příšlušných funkcí - na to se dá velmi jednoduše použít kontextové menu, kde se v 1. úrovni jeho zobrazení zopakuje přesně to, co je dnes zobrazeno v prvních čtyřech položkách seznamu, a pak už je to vlastrně stejná jako teď...
   
2. U zobrazení už to bude trochu složitější, protože v zobrazeném seznamu položek video pluginu pro to žádné další místo není. Ale myslím, že úplně postačí, pokud se aktuální nastavení filtru zobrazí v plot položky TV Program v hlavním menu doplňku. Ostatně i u této položky bude v kontext menu možnost volby nastavení filtru.
   

Jak pak práce uživatele vypadá:

• zobrazení hlavního menu doplňku
  
• najetí na položku TV Porgram
  • v plot vidí uživatel nastavení filtru
    • pokud je s ním spokojen, pokračuje volbou TV Program
      
    • pokud ne, v kontext menu spustí nastavení filtru
      
• volba TV Program
  
• zobrazení seznamu podle aktuálního nastavení filtru
  • pokud je s ním spokojen, pokračuje výběrem a spuštěním přehrávání pořadu
    
  • pokud ne, v kontext menu spustí nastavení filtru
    

---

A mimochodem, když už jsem se tak otřel o doplněk Nokturno (který ale pokládám za velmi podařený), doporučil bych, aby autor věnoval větši pozornost tomu, co se zobrazuje v záhlaví jeho seznamů. To, že doplněk ne vždy zobrazuje obsah podle toho, v jaké větvi menu doplňku se uživatel právě nachází, je škoda.

---

Když jsem v předchozím příspěvku použil jako příklad pro ne úplně optimálního řešení doplňku v jedné z jeho funkcí doplněk Nokturno, tak bych tu měl explicitně uvést něco, co je s ohledem na témata v tomo vlákně u tohoto doplňku, kromě celé řady jiných aspektů, potřeba vyzdvihnout. A to je správné použití položet Title a Label. Psal jsem o tom v tomto tématu hned v 1. příspěvku #1.