Getting started

Things you should know:

  • Each plugin is a subclass one of the plugin types.
  • A .py file can contain multiple plugins.
  • If you have a folder structure the main foler must be a python module.

Plugins are loaded dynamically by traversing the core plugin path and the extraPluginPath, each .py file is checked for any of the plugin type classes.

Basic folderstructure:

                    +-<My Plugin Folder>-+
                                         +- (empty file)
                                         +- <My Plugin .py>
                                         +- <more .py that the plugin needs> (optional)
                                         +- <folder with libarys> (optional)
                                         +- pluginRootLibarys (optional)


Not all .py files are checked. Files that start with ‘__’ or files that are in a folder called pluginRootLibarys are not checked for plugins.

A simple notification plugin

The file structure for this would look like:


Contents of

from xdm.plugins import * # by using this one import line you have everything a plugin will need from XDM

class Printer(Notifier): # subclass Notifier

    def sendMessage(msg, element=None)
        print msg
        return True

This is absolutely sufficient for a Notifier plugin.

Adding configuration

To create settings simply fill the _config attribute of your plugin class:

from xdm.plugins import * # by using this one import line you have everything a plugin will need from XDM

class Printer(Notifier): # subclass Notifier
    _config = {'add_message': 'my print plugin'}

    def sendMessage(msg, element=None)
        print msg
        return True

This will create a text field in on the settings page and the default value is my print plugin.

Each type of default value will determine the input field in the settings

str:Text input field
int / float:Number input field


Only these type are allowed as config values!

To get the config value access the c object of you plugin and then the attribute with the name of your config.

from xdm.plugins import *

class Printer(Notifier):
    _config = {'add_message': 'my print plugin'}

    def sendMessage(msg, element=None)
        userAddition = self.c.add_message # just make sure its the same spelling as the key in the config
        print msg + userAddition
        return True


self.c is only available after the __init__() of Plugin.

It was never explained how the add_message is used, to change that we use the config_meta attribute.

from xdm.plugins import *

class Printer(Notifier):
    _config = {'add_message': 'my print plugin'}
    # add_message: same key as in _config
    config_meta = {'add_message': {'human': 'Additional text', # a more human friendly name
                                    'desc': 'This text will be added after every printed message'}}
                                    # the description will be a tooltip on the input field

    def sendMessage(msg, element=None)
        userAddition = self.c.add_message
        print msg + userAddition
        return True

More info on Plugin configuration

Reserved attributes

Following class / instance attributes are reserved and are not to be set by a plugin!

The configuration manager
The hidden configuration manager
The class name e.g. Printer
Its the plugin type name e.g. Downloader
The instance name
The class name and instance name e.g. Printer (Default)

More info see Plugin

Plugin Types

A simple description of a download type.
These plugins provider the connection to the downloader programs
These plugins provide connection to the sites that have information on releases
These plugins provide means to send notification to third party services or other program’s on certain events
These plugins connect to databases and create elements based on the media type they work for.
These plugins move rename or do whatever they like with a given path and element.
Well there is only one of this kind and maybe there will never be more. The system config is a plugin of this type
These plugins can filter found downloads as they wish.
These plugins can add or remove search terms, before they are used by the Provider
These plugins can add elements. From various sources e.g. watchlist.
These plugins are the core of XDM. These plugins define the structure of a media type and provide functions to save and store them. The look is also defined here.


If you need to include a library that expects to by installed system wide, therefore being in the python path can be used when put in a folder called pluginRootLibarys. The absolute path of that folder is added to the python path.


An info level message when the path is added it created.


class xdm.plugins.bases.Plugin(instance=None)

Plugin base class. loads the config on init


Gets the the config value for given element

addMediaTypeOptions = True

Defines if options defined by a MediaType should be added to the plugin.


This is ignored for plugins of the type MediaTypeManager and System since it’s never done for them.

  • True: this will add all configurations defined by a MediaType
  • False: No configurations are added
a list of MediaType identifiers e.g. ['', ''], this will add only options from the MediaType with the given identifier
only str value allowed is runFor, this will only add runFor options to the plugin.
config_meta = {}

Meta information on the the config keys


The return value of this function is simply injected in the config panel

default is a html comment: <!– nothing here –> you can use this to add dynamic javascript and/or add additional html


The container this is added in is hidden with inline css. to make use of the html use javascript

single = False

if True the gui will not give the option for more configurations. but there is no logic to stop you do it anyways

useConfigsForElementsAs = 'Category'

MediaTypeManager can add configurations for elements. this defines how this configuration is used. This string will be used for:

  • It will be added to the configurations name.
  • A function will be created named get<useConfigsForElementsAs_value>() e.g. getCategory()
version = '0.1'

version string. may only have a major and a minor version number

xdm_version = (0, 0, 0)

this is the greater or equal XDM version this plugin needs to function


By default this is (0, 0, 0) but the json builder will return the current version of XDM if it is not specifically set.