While there is NO Plug-In development guide out there yet ...

[rnio]

‎**** UPDATE ****‎



This is my third re-write of this little info piece :-)‎



Version 0.3.2



‎__________________________________‎



OVERVIEW:‎



The PLEX developers made it easy to write PYHTON scripts to collect MEDIA-ITEMS

from the internet.‎



A lot of complexity is hidden behind a FRAMEWORK, which takes care of CACHING ‎

/ Complexity of function calls / automatic UPDATES etc. etc.‎



THE CURRENT version for the FRAMEWORK is #1 (#0 was the initial cut). The ‎

Framework itself, along all other plug-ins are located in:‎



‎"~/Library/Application Support/Plex Media Server/Plug-ins/"‎



A big update to the FW is getting ready as I write this (05-29-09). With many more

bells and whistles! (Thank you JAMES & ELAN!)



As a plug-in developer your job is to collect / scape for MEDIA-ITEMS and then

give it back to PLEX.‎



Your plug-in returns a MEDIACONTAINER back to PLEX.

“spaceman” described SEVEN-ITMES these containers may provide:‎

MEDA-ITEM: it’s a list of items with URL / THUMB/ TITEL etc. etc. ==> This ‎

will be presented within PLEX as a clickable item with as much info as you ‎

supplied (scraped etc.)‎ Depending of the kind and location of an item PLEX

differentiates 4 types:

• VideoItem: The target should be a regular video item (e.g. avi, asf, mov, mpeg)
  
• WebVideoItem: The target should be a webpage which contains an embedded video player (e.g. Flash, Silverlight)
  
• PhotoItem: Exactly what it sounds like.
  
• TrackItem: Audio.

DIRECTORY-ITEM: In some cases your selected web-site has nested layers for ‎

selection before you get to the actual MEDIA-ITEMS. PLEX allows you to re- ‎

create this kind of structure and provide DIRECTORIES (pages) with items you ‎

can select to get to the MEDIA-ITEM of your choice.‎

POP-UP-DIRECTORY-ITEM (PopupDirectoryItem):

This is a “fancy” directory, which pops in a WINDOW on top of PLEX. You probably

saw it when you used the APP-STORE to install a plug-in. The item there is the INSTALL-MENU.

The menu displays on top of the current one. Looks like a contextual menu.

.

SEARCH-ITEM (SearchDirectoryItem): This works like a directory-item, just giving you a PROMPT-FOR- ‎

INPUT before it will display the new directory.‎

MESSAGE-DIRECTORY-ITEM (MessageContainer): This is a dialog box, which you can present with

just an “OK” button; Used mostly with redirects

The MEDIACONTAINERS can contain any MIXURE of these items, EXCEPT the POP-UP-DIRECTORY-ITEM.‎

The best way to get started with your project, is to look at existing plug- ‎
ins. Below you will find some info on how to best setup your system to make ‎
your development a little easier. I will also start a new topic about the ‎
best tools / tricks of the trade ... the next revision of this will have a ‎
LINK to this.‎

This is NOT rocket science the PLEX developers made it very easy and help you
‎
along your way; I just started April 14th 2009 ... learning PYTHON, the PLEX ‎
framework, LXML, etc. from scratch and have four nice plug-in under development
(two are finished)
‎
right now: ‎

‎[*****> COMPIZmediacenter <*****](http://wiki.plexapp.com/index.php/COMPIZmediacenter)‎

HAPPY CODING

Robert

_____________________‎_____________________________________‎

START:‎

Just take an existing plug-in; if you can: similar to the one you want to ‎
develop.‎

_____________________‎_____________________________________‎

FRAMEWORK SELECTION

NOTE: You should use Version 1 as this is the current one MUCH improved
over ‎#0. This tutorial is based on #1.‎

To SELECT the correct FRAMEWORK, please add

‎[codebox]Start a Terminal

then type

$ killall "Plex Media Server"

this will kill an existing one

then you type:

$ ~/Library/Application\ Support/Plex/Plex\ Media\ Server.app/Contents/MacOS/Plex\ Media\ Server

(you can copy and paste this, but leave off the "$", of course)
[/codebox]

_____________________‎_____________________________________‎

Missing items within this DOCUMENTATION:‎

‎- "exotic / advanced" things one can do from within a plug-in (e.g. run an ‎
EXTERNAL function (dll etc.) / start - stop other programs, multithreading)‎

Any feedback is welcome :-)‎

[jam]

Thanks for the info! I know it’s taken us longer than originally planned to get the documentation ready, but it’s coming soon, I promise You should take a look at the 4oD and Vimeo plug-ins - these make use of the new v1 framework; a lot of the code has changed to make things simpler.



Also, you should avoid using the Python libraries when it’s possible to use the PMS framework modules. Use PMS.HTTP instead of urllib2, PMS.XML instead of etree, etc. - these simplify the code a great deal and are interlinked. For example, the XML and JSON modules automatically share caching & cookies with the HTTP module without you having to do anything extra.

[rnio]

Thanks for the feedback.



Now that I “learned” a few more things, I now have some suggestions:



Make a DUMMY subset of functions available for “out-of-box” development.



I would like to just have a normal PYTHON envionment where I can debug and test the code up until the actual streams are played. Unformtunately the PMS libraries are not available when I do this, by the python libraries are. Alternative give us a conversion table for the main fucntions and when the code is ready … we can just swap the call and have those mapped to the PMS framework.



When I started a few days ago, I just used the text editor / plex / log-system to do the development … very difficult especially, when you also just start outr learning python … lots of little things I tend to forget … a comma here , a colon there …within an IDE its so much nicer … colorful syntax / auto complete etc. ect.



Just my $0.02



All in all I m very please with the ease to integrate our selfmade plugins … its just hard to get started learning so many new things at once.

[jam]

Unfortunately, it’s not that easy - the media server runs a specialised Python environment so we can modify the system path & load custom libraries that aren’t available in the default OS X Python system, required by the framework. The best way I’ve found for debugging is to run the media server inside a terminal window & view realtime debug output. Make sure you stop the media server, open Terminal, then run:

~/Library/Application\ Support/Plex/Plex\ Media\ Server.app/Contents/MacOS/Plex\ Media\ Server

There are a couple of other useful tools for developmet. One is the Xpath Checker extension for Firefox that allows you to test the results of Xpath queries. Another is HTTP Client ([http://ditchnet.org/httpclient/](http://ditchnet.org/httpclient/)) - you can use it to view the XML output of your plug-in by accessing [http://localhost:32400](http://localhost:32400).

[rnio]

Update … see TOP

[rnio]

Update … see TOP

[OrbMan]

Thanks for taking the time to write this, rnio. I am going to write my first Plex plugin and this just lowered the bar a whole lot!

[embeddedcoder]

Some more media item types:

MessageContainer: Displays a dialog box. Used mostly with redirects

PopupDirectoryItem: Displays a menu on top of the current one. Looks like a contextual menu. Note: The items within the popup menu should be Directory items.

SearchDirectoryItem: Displays a keyboard entry dialog. When used within a Function (see below) the target function should have parameters sender and query.

VideoItem: The target should be a regular video item (e.g. avi, asf, mov, mpeg)

WebVideoItem: The target should be a webpage which contains an embedded video player (e.g. Flash, Silverlight)

PhotoItem: Exactly what it sounds like.

TrackItem: Audio.



Function: If you’re writing a new plugin (i.e. one that doesn’t need to run in framework v0) you should place all directory item declarations inside a Function()

The first argument to the directory item is the name of the Python function that should be called when the item is selected.

After the directory item you can have any number of named arguments. These will be passed to the Python function you specified.



The called function should have sender as its first argument followed by the arguments you specified in the directory item.

Missing, extra or misnamed arguments in the function definition will result in an error.

[jam]

PopupDirectoryItem: Displays a menu on top of the current one. Looks like a contextual menu. Note: The items within the popup menu should be Directory items.

Actually, the items in a popup menu can be of any type (e.g. photo or video), and they'll work as expected :)

[rnio]

Thanks for the great feedback … I will play around with it … and update my little document at the top.



Keep the good tips & tricks coming

[grimmet]

Hey mio: Special thanks for the comprehensive overview. i was going to start a plugin by myself. this helps a lot!

[rnio]

***** UPDATE *****



See FIRST post

[embeddedcoder]

Hi again,



A few more points for you.

On Unix based systems directories are separated with / not . So ‎"\Users\plex\Library\Application Support\Plex Media Server\Plug-ins"‎ becomes ‎"/Users/plex/Library/Application Support/Plex Media Server/Plug-ins/"‎.



Python is smart enough to tell the difference between a named parameter and a variable. That means you can write:

dir.Append(VideoItem(url, title=title, subtitle=subtitle,‎ summary=summary,‎ thumb=thumb,‎ art=art))

You don’t have to use caps. btw, by convention names in ALL_CAPS are only for constants.



If you’d like to use a file from the Resources folder there’s already a function for that. R(“fileName”)

Also, you should avoid using the Python libraries when it’s possible to use the PMS framework modules.

To expand on that future versions may prevent loading external libraries completely. If there's anything you really need from an external library please let James know.

[pygmalion]

To expand on that future versions may prevent loading external libraries completely. If there’s anything you really need from an external library please let James know.

Can we still put python libraries inside the plugin bundle and import them?
My plugin interfaces with a SOAP server to get its media and I'm using the suds library:
[https://fedorahosted.org/suds/](https://fedorahosted.org/suds/)

I don't know of any built-in SOAP libraries in PMS Framework on the standard OS X Python installation,
please correct me if I'm wrong.

[sansnipple]

When I started a few days ago, I just used the text editor / plex / log-system to do the development … very difficult especially, when you also just start outr learning python … lots of little things I tend to forget … a comma here , a colon there …within an IDE its so much nicer … colorful syntax / auto complete etc. ect.

i STRONGLY suggest that you use TextMate for your editor. It has great syntax coloring, its python bundle has a syntax validator that once you install py-checker (via macports) is actually really good. TextMate was designed from the ground up as a programer's text editor, i can't imagine having to write python without it. I've been using it for a while now and i've just barely scratched the surface of the awesome stuff it can do.

[jam]

Can we still put python libraries inside the plugin bundle and import them?

My plugin interfaces with a SOAP server to get its media and I’m using the suds library:

https://fedorahosted.org/suds/



I don’t know of any built-in SOAP libraries in PMS Framework on the standard OS X Python installation,

please correct me if I’m wrong.

Yes, if you create a Libraries directory inside the bundle you'll be able to import anything you put inside. The framework may log a warning message, but it's safe to ignore it.

My comment about using PMS modules where possible is 1) because we'll hopefully be able to sandbox plug-ins eventually, so relying on too many system modules is a bad idea since some will eventually be unavailable for security reasons, and 2) because the modules are interlinked nicely with eachother (like sharing a common HTTP cache, cookies, localisation, etc) so you get a lot of features "for free" that you'd have to implement manually using the standard system modules.

I've never used SOAP personally, and so far we haven't come across any sites that require it, but if you can give me some examples of how it works & where you'd use it I'd be happy to add it to the framework :) I'm sure it'd be useful to lots of other devs! PM me if you're interested.

[oortmanp]

Hi rnio,



thanks for the guide!



an update to the last lines in your first post.

To execute python code when selecting a media item:



elan:

In order to execute it when hitting a media item, you can use the v1 of the framework and use a Function() item to call back into your plug-in. Check out any of the myriad of v1 plug-ins for good example code.

oortmanp

[rnio]

Hi rnio,



thanks for the guide!



an update to the last lines in your first post.

To execute python code when selecting a media item:



elan:





oortmanp

Its NOT that simple ... PLEX is expecting specific return values ... thus if not done properly ... plex will be screwed up.