Докладна анатомія простого плагіна для XBMC, Блог розробників phpBB
Вступ
Цілком плагін можна завантажити звідси.
Примітка: далі в тексті щодо деяких файлів та папок застосовується термін "робочий". Це означає, що XBMC шукає такі папки та файли без прямої вказівки на них у коді плагіна. «Робочий» != «неодмінний», і більше примітивні плагіни можуть містити якихось службових файлів.
Загальна інформація
Для написання плагінів XBMC використовується мова Пітон. XBMC під Windows компілюється з версією 2.6.6, а під Linux, як я розумію, версія Пітона залежить від встановлених девелоперських бібліотек, які використовуються при збиранні. У будь-якому випадку, при написанні коду плагіна варто орієнтуватися на синтаксис та ймовірність Пітона 2.6. Пітон в XBMC повнофункціональний: є приблизно кожна стандартна бібліотека, крім, хіба що, Tkinter/ttk/tix (які тут очевидно зайві). Для взаємодії з XBMC додано 5 модулів: xbmc, xbmcgui, xbmcplugin, xbmcaddon та xbmcvfs, які спільно становлять XBMC Python API. Коротку довідку по модулях можна знайти тут. На жаль, у довідці трапляються неточності. Крім того, оператор print замість консолі пише в лог XBMC з ярусом Notice, що можна використовувати при налагодженні, скажімо для результату значень змінних. Трішки про термінологію: спочатку розробники XBMC застосовували термін «аддон» (addon) для будь-яких доповнень, які, у свою чергу, поділяються на плагіни (джерела контенту), скрипти (програми), скрепери (завантажувачі інформації до медіаконтенту) та інші . Втім, згодом уявлення «аддон» і «плагін» переплуталися, і тепер їх часто застосовують для позначення будь-якого доповнення.
Налаштування IDE
Увага: це саме модулі-заглушки, нещо містять придатний код, і спроба запустити програму, яка на них посилається, прямо з IDE призведе до непередбачених результатів. Втім, бажаючі можуть додати в ці модулі код налагодження, що імітує поведінку реальних функцій і способів XBMC Python API.
Конструкція плагіна
Мій «навчальний» плагін має таку конструкцію:
Зараз докладніше про призначення всіх цих файлів та папок.
addon.xml – робочий файл плагіну, з якого вбудований каталогізатор плагінів XBMC бере всю потрібну інформацію. Це винятковий неодмінний файл плагіну, і деякі типи плагінів (скрепери, репозиторії тощо) можуть взагалі не містити програмного коду та інших службових файлів.
Рядки 8-10 містять інформацію про зовнішні залежності - інші компоненти, необхідні для роботи плагіна. Як видно, цей плагін вимагає тільки XBMC Python API версії не нижче 2.0. Точний номер версії, що застосовується в реальний час, я не знаю, але 2.0 — свідомо робочий варіант. Якщо для роботи вашого плагіна потрібно якийсь інший плагін, вказуємо його тут у такому самому тегу. Скажімо, якщо для вашого плагіна для чогось потрібний плагін Youtube, в розділ необхідно додати наступний тег:
Теоретично, відсутні залежності повинні встановитися механічно при встановленні плагіна.
Далі найдокладніший розбір. ? Суттєві речі пропускаю.
Рядки 11-15 - Визначення параметрів плагіна. У більшості плагінів застосовуються змінні з подвійними підкресленнями, але вони естетично не подобаються, і, до того ж, їх не рекомендує PEP 8.
11: задаємо ім'я плагіна. Ім'я плагіна має збігатися з ім'ям, вказаним в addon.xml, і ім'ям папки (у разі плагін може не працювати).
12: створюємо екземпляр класу Addon для доступу до налаштуваньплагіна.
13: отримуємо runtime-ідентифікатор плагіна (handle). Ідентифікатор — це ціле число, яке передається як 2-й аргумент при виклику плагіна з XBMC. Цей ідентифікатор застосовується як один із аргументів функції утворення списків контенту addDirectoryItem(). Тут варто докладніше зупинитись на параметрах виклику плагіна. Як було сказано вище, відмінність від плагінів-джерел контенту і плагінів-скриптів полягає в тому, що в плагіни-джерела є списки (каталоги) контенту, в той час як скрипти можуть робити все, що бажано в межах ймовірностей мови Пітон і XBMC API . Додаткова відмінність полягає у параметрах виклику, що передаються плагіну. При виклику з інтерфейсу XBMC або рекурсивному виклику з самого себе (про це нижче) плагін-джерело отримує 3 параметри в списку sys.argv: свій уявний URL, runtime-ідентифікатор (рядок, що містить ціле число), і додаткові параметри виклику у вигляді URL -Encoded послідовності. Плагін-скрипт, у свою чергу, не отримує жодних параметрів, і для нього sys.argv є порожнім списком. Тому функції і методи, що вимагають runtime-ідентифікатор плагіна як аргумент, скажімо addDirectoryItem(), в плагінах-скриптах працювати не будуть. Про віртуальну URL-адресу та додаткові параметри виклику нижче.
52-64: функція утворення списку груп подкастів сайту cnet.com - по суті списку віртуальних папок. Розглянемо її детально.
57: тут для кожного елемента списку ми створюємо екземпляр класу xbmcgui.ListItem. Цей клас є контейнером для зберігання властивостей деякого елемента списку, що представляє мультимедійний контент. Елемент списку повинен мати як мінімум текстовий підпис, але для позитивного оформлення для нього бажано вказати картинку(ескіз) та шпалери (фанарт).
59: додаємо фанарт до списку. Як видно, для всіх елементів списку застосовується фанарт плагіна, але ніщо не заважає призначити кожному елементу особистий фанарт.
61: Складаємо посилання для рекурсивного виклику плагіна. Як докази виклику виступають очищені від зайвих символів найменування груп подкастів. Відповідно, при виборі відповідної групи запущений рекурсивний плагін сформує список подкастів цієї групи.
63: функція додавання елемента до списку контенту. Саме тут нам потрібний ідентифікатор плагіна, отриманий із sys.argv[1]. Нагадаю, що цей параметр передається лише плагінам-джерел контенту. Відповідно, у всіх інших видах плагінів функцію addDirectoryItem() застосовувати неможливо. Параметр isFolder=True говорить XBMC, що цей елемент списку - віртуальна папка, тобто при виборі цього елемента необхідно відобразити деякий вкладений список, а не відкрити посилання в плеєрі. У параметрі url ми додаємо посилання на віртуальні папки, що формуються плагіном, але тут також можна використовувати шляхи до реальних папок з мультимедійними файлами на локальному або мережному диску.
65: додаємо спосіб сортування. Справа в тому, що за умовчанням елементи списку відображаються в порядку додавання, що не завжди бажано.
67: кажемо XBMC, що освіта списку завершено.
72-77: власне функція перемикання образу. Ми отримуємо нинішній скін і перемикаємось на необхідний вигляд. Код 500 відповідає виду "Ескізи" стандартного скіна Confluence, а код 512 - виду "Інфо-стіна" скіна "Aeon-Nox". Для решти скінів буде застосовуватися їх типовий вигляд.
101: отримуємо необхідну якість подкастів, вибрану в панелі налаштувань плагіна. Будь-які налаштування незмінноповертаються у вигляді рядків, і їх необхідно наводити до необхідного типу, якщо потрібно.
Папка resources - службова, і в ній містяться різні додаткові файли плагіна.
settings.xml
settings.xml — робочий файл, в якому особливою мовою, заснованою на XML, описується панель налаштувань плагіна, яка викликається при виборі підменю «Налаштування». Внаслідок такого підходу панель налаштувань плагіна незмінно має «рідний» вигляд у будь-якому скіні.
У цьому випадку панель налаштувань має один орган управління - спинбокс (labelenum) для вибору якості показованих подкастів (HD або SD). Параметри label= містять текстові викладення елементів панелі налаштувань, і вони можуть бути як легкий текст, і номери рядків з мовних файлів. Для доступу до певних параметрів застосовуються текстові ідентифікатори в параметрах > Детальний виклад синтаксису файлу settings.xml і доступних елементів керування можна знайти в керівництві «XBMC Addon Developers Guide» (англійська мова). Це начальство з написання плагінів дещо застаріло, але все одно містить багато придатної інформації, у тому числі про організацію панелі налаштувань плагіну.
Підпапка language є службовою. У ній, у підпапках нижнього ярусу, що мають імена, що відповідають англійським найменуванням різних мов, лежать мовні файли плагіна strings.po. У нашому плагіні є підпапки English, Russian та Ukrainian, тобто плагін має інтерфейс англійською, українською та українською мовами. Плагін, що має свій інтерфейс, повинен містити щонайменше папку English з відповідним мовним файлом. Однак, у деяких випадках можна обійтися і без своїх мовних файлів, але про це трохи нижче.
Очевидно, файл має формат .po GNU Gettext. Втім, XBMC не використовуєсправжній Gettext: двомовні файли не компілюються в .mo, і для ідентифікації окремих рядків інтерфейсу застосовуються номери, що вказуються в параметрах msgctxt. Пов'язано це з історичними причинами: раніше XBMC застосовував особистий формат мовних файлів на базі XML, проте з переходом на онлайнову систему перекладу www.transifex.net було вирішено перейти на загальновідомий і підтримуваний формат локалізації. Очевидно, такий проміжний варіант із застосуванням текстових файлів .po було впровадити простіше, ніж повністю перейти на Gettext. Як вже було сказано, рядки інтерфейсу витягуються методом getLocalizedString() за номером в msgctxt. При цьому використовується наскрізна нумерація: стрижневий мовний файл XBMC мовний файл плагіна. Бажано, щоб номери рядків основного мовного файлу та плагіна не повторювалися. У тезі при збігу номерів в обох файлах пріоритет має мовний файл плагіна, але, абсолютно припустимо, це є багом, і покладатися на таку поведінку неможливо. Отже вибирайте для рядків інтерфейсу плагіна особисті номери. Номери рядків мовних файлів застосовуються як у коді плагіна при створенні елементів інтерфейсу та результаті повідомлень, так і у файлі з викладенням панелі налаштувань settings.xml для відображення підписів до елементів керування. У тезі, якщо всі необхідні рядки інтерфейсу можна виявити в основному мовному файлі XBMC, то в самому плагіні мовні файли можна не створювати. У такому разі у відповідних місцях будуть застосовуватися номери рядків із основного мовного файлу.
У підпапці lib міститься наш додатковий пітонівський модуль, який експортується в плагін. Подапка lib не службова. Вона може іменуватися як бажано, і самі модулі, що експортуються, можуть розташовуватися де бажано: поряд з основним скриптомплагіна, в підпапці першого ярусу і т. п. Головне, щоб вони були доступні для імпорту. Легко, як правило, комфортніше, якщо всі додаткові файли плагіна, як службові, так і ні, розміщувалися в одному місці.
thumbnails
У підпапці thumbnails лежать картинки з логотипами подкастів cnet.com. Як іlib, ця підпапка не є службовою, і картинки можуть лежати в будь-якому доступному місці на ваш вибір.
Завершення
На цьому аналіз конструкції щодо простого плагіна XBMC закінчено. Незважаючи на свою простоту, плагін має приблизно всі елементи, притаманні більш важким плагінам. Бажаючі можуть використовувати цей плагін як «скелет» для свого плагіна. Наступний раз, якщо буде час і бажання, я розповім про те, як зробити плагін із власним інтерфейсом.