1. Introduction

The Plex Media Framework provides a simple yet powerful platform that enables developers to easily create plug-ins for Plex Media Server. The framework consists of an API containing a set of tightly integrated modules, and a small runtime environment that manages the execution of a plug-in’s code.

The framework API builds upon a great foundation provided by the Python programming language, and concentrates on making the areas of Python most frequently used when developing plug-ins even easier to access. The modules handle a lot of the boilerplate code internally, allowing the developer to focus on functionality, and the runtime environment manages most of the interaction between plug-ins and the media server.

Plug-ins created using the Plex Media Framework are typically very small and lightweight, and can achieve a great deal of functionality in hardly any time. You’ll be amazed at what you can accomplish!

1.1. How plug-ins work

Each media server plug-in runs in its’ own process, in a separate Python instance. This ensures that plug-ins can’t interfere with each other, or with the operation of the server. Plug-ins communicate with the media server over pipes and act like mini HTTP servers, receiving standard HTTP requests and responding with XML-formatted data. This process is completely transparent to the plug-in developer - the framework will handle receiving requests, routing them to the correct place within a plug-in, and sending a response back to the server.

Plug-in’s don’t behave quite like normal Python programs. A plug-in isn’t a program in its’ own right - the framework’s runtime environment is the program, which dynamically loads the plug-in code as part of the initialization routine. The runtime handles common tasks like run loop management, request handling, logging and data storage, and calls specific functions in the plug-in when necessary.

1.2. Differences between plug-ins and regular Python programs

Because media server plug-ins are a little different to regular Python programs, they can behave strangely in certain situations. There are a few key areas where regular Python rules do not apply that you should be aware of.

1.2.1. The print statement

If you’ve used Python before, you’ll probably have come across the print statement. This statement simply passes whatever follows it to the standard output. However, because plug-ins operate using pipes, anything you try to output using print will actually be returned to the media server.

If the server doesn’t understand the data you’re returning, your plug-in will exhibit unexpected behaviour and may become unstable. Therefore, you should never use the print statement in a plug-in. If you need to output some data for debugging purposes, you can use the Log() function to add text to the plug-in’s log file. More information can be found in the Debugging section.

1.2.2. Code structure

Because plug-ins are executed within the framework’s runtime environment, the code structure is more strict than in a normal Python program. All of the plug-in’s code needs to be contained within functions. Although it is generally safe to initialize simple variables with types like string, int or bool outside a function, anything more complicated (especially involving framework functions) may produce unexpected results or fail completely. This is because the runtime environment needs to be fully initialized before using any of the framework modules, and code in plug-ins that exists outside a function is executed as soon as the plug-in is loaded. Any code you want to execute when the plug-in loads should be put inside the Start() function. More information can be found in the Plug-in functions section.

1.2.3. The framework modules

One of the biggest hurdles for existing Python developers to overcome is breaking old habits when it comes to developing plug-ins. For instance, many developers may already be familiar with using the urllib and urllib2 modules to make HTTP requests, but all of the code required to perform a request can be replaced by calling a single function in the HTTP module. This also has other benefits, like automatic cookie handling and the option to cache the server’s response.

While creating the framework modules, a great deal of care was taken to make plug-in development as easy as possible. If you take the time to familiarize yourself with how the framework operates and the features it provides, you’ll become much more productive when writing plug-ins.

1.2.4. Plug-in execution

Another side effect of the plug-in architecture is that plug-ins are incapable of running by themselves. Because they rely heavily on the framework modules and the runtime environment, plug-ins must be started by the media server. More information on development practices and testing can be found in the Debugging section.