xbmcswift2 - micro-framework for writing plug-ins to Kodi (XBMC)

Introduction

This, so to speak, is a “bonus” article in my series of articles about plug-ins for the Kodi Media Center (XBMC). First of all, it should be noted that, starting with version 14.0, the popular media center changes its name from XBMC to Kodi. The reasons for changing the name can be read on the official website and forum, and for our article they are not fundamental. However, later in the article will be used a new name - Kodi.

Previous articles

Detailed anatomy of a simple XBMC plugin
Writing a plugin for XBMC with its own interface: Part I - the theory and the simplest example
Writing a plugin for XBMC with its own interface: Part II - Dialogues and Decorations
Writing a plug-in for XBMC with its own interface: Part III - API and micro-framework

xbmcswift2

In the first article, “Detailed Anatomy of a Simple XBMC Plug-in” , the basic principles of plug-in content sources, i.e., plug-ins that allow you to watch videos and listen to music from various online resources, were discussed. There are two basic principles:

1. Each item in a virtual directory (a link to a subsection or file to play) is an object of class xbmcgui.listItem containing all the information about an item in a virtual directory. When creating a list of items, we sequentially create xbmcgui.listItem objects, set their properties (thumbnail, fanart, link, additional information) and feed these elements to the xbmcplugin.addDirectoryItem function.
2. To create multi-level directories, the plugin recursively calls itself, passing parameters in the form of a URL-encoded string via the sys.argv [2] list item. In this case, we need to decode these parameters and call the appropriate part of the code, for example, to form a directory of the lower level (subsection) or play the video by reference. That is, we need to organize the routing of such recursive calls.

As a result, the plugin developer is charged with extra work that is not directly related to receiving information, organizing content and playing it.
')
When creating xbmcswift2, the developer was obviously inspired by the popular Python micro-frameworks for web development - Flask and Bottle. The recursive call routing mechanism is clearly borrowed from these frameworks - call paths and parameter passing are implemented through function decorators.
In addition, in xbmcswift2 the structure of virtual directory elements is unified. Now a separate element is a Python dictionary with all the necessary properties in the form of key-value pairs. These elements are combined into a list, and to display a list of elements in the Kodi interface, the function “decorated” with the route decorator should return this list. Further processing of the list and decoding of dictionaries describing the elements of this list takes on xbmcswift2.
In addition to simplifying the creation of content lists and routing recursive calls, xbmcswift2 offers such nice features as caching objects returned by functions and methods, as well as permanent storage for storing the state of objects between recursive calls. xbmcswift2 also allows you to debug plug-in code in the console, without using Kodi.

To illustrate the use of xbmcswift2, I will take the plugin from the article “Detailed anatomy of a simple XBMC plugin” and rewrite it under this framework. For simplicity, the new plugin will not display any messages on the screen, so there are no language files in it.



Now, as always, line by line analysis. To display line numbers, use a text editor with the appropriate function, such as Notepad ++. Obvious things and what is clear from the comments, I skip.

30: The @ plugin.cached () decorator is used to cache objects returned by functions or methods. This decorator is recommended to "decorate" the functions that receive content from websites, so as not to create an excessive load on these sites. The caching time in minutes is set as a parameter to the decorator.
49: The @ plugin.route () decorator is used to route plug-in calls. A plugin must necessarily contain at least the root route ('/').
55-61: The properties of a list item are set in the form of a fairly simple and clear dictionary.
61: The url_for () method generates the correct path for the recursive plugin call, so that this path can be decoded xbmcswift2. The first parameter is the name of the function being called as a string, and additional information is passed through named parameters. Only simple strings can be used as parameters. Accordingly, all other data types should be cast to strings. Non-ASCII characters can be transmitted as URL-encoded sequences (for example, “Vasya”> “% D0% 92% D0% B0% D1% 81% D1% 8F” or in base64 encoding.
65: The finish () method is used to pass additional parameters for displaying the content list (besides the list itself). If you do not need to return any additional parameters, you can return the list itself without using the finish () method.
69.70: Call the function that creates the list of podcasts. As a parameter, we pass the section number in the list (more precisely, the tuple) FEEDS.
83: Indicate that this element does not contain nested elements (in this case, the list element is a file for playback). By default, this parameter is False, so it is omitted in the previous function.
89—90: here, a special function play_podcast () is used to send the file to the main Kodi code for playback, which, in turn, calls the set_resolved_url () method. This method is a "wrapper" of xbmcswift2 around the standard Kodi Python API function xbmcplugin.setResolvedUrl () . The use of xbmcplugin.setResolvedUrl () is poorly documented, but this is the preferred method to start playing multimedia files. Of course, you can use direct links to these files (and in the example from the article “Detailed Anatomy of a Simple XBMC Plugin” , a simple version with direct links was used), but there are undesirable side effects when using direct links. For example, when generating a list of files, Kodi tries to read the metadata of these files, which, with a large number of list items and a slow connection, leads to the fact that the list is formed for a very long time. In addition, when using direct links, auto-bookmarks and browsing marks are not supported. The reason for the latter is not clear (most likely, a bug.) However, if xbmcplugin.setResolvedUrl () and its counterpart from xbmcswift2 are used - set_resolved_url () - these side effects are not observed.

Conclusion

The xbmcswift2 microframe is available in the official Kodi repository, and when creating a plug-in based on it, the micro-framework must be specified as a dependency in the Kodi plug-in metadata file - addon.xml. For more on this, see previous articles and the official Wiki.
You can download the finished demo plugin based on xbmcswift2 from here .

I hope the information from these articles will help you in writing useful plug-ins for Kodi. As practice shows, the most difficult task when writing a plug-in is to pull links to videos or music from one site or another, and organizing information and links in a plug-in is much easier.

Information sources

Official documentation xbmcswift2 .