Media Players API

MediaDrop was designed to make it straightforward to fully integrate new audio/video players into the display system.

While MediaDrop supports 9 Flash and/or HTML5 players out of the box (including the popular JWPlayer, Flowplayer, and Sublime Video Players, as well as several players customized to display embedded material from third-party websites), we recognize that some users may want to incorporate different players.

To this end, we have designed the playback system around a well-defined API. All of MediaDrop’s default players implement this API.


Players have 3 parts.

  1. A Python class that implements the mediadrop.lib.players.AbstractPlayer abstract class,
  2. A Genshi template (all players use the same template, mediadrop/templates/players/html5_or_flash.html; its use is defined in mediadrop.lib.players.media_player()),
  3. A JavaScript manager class, written using Google’s closure library, that inherits from goog.ui.Component and is responsible for handling player interactions (resizes, clicks, etc.).

When a Media object is selected to be rendered, a list of StorageURIs is generated from that object’s MediaFiles. Each enabled Player is then asked, in order, if it can use any of the available StorageURIs. The first Player that can play one of the StorageURIs is rendered. This logic is contained in mediadrop.lib.players.media_player().

Players can optionally define a dict of editable properties in their default_data dict if they also provide a subclass of mediadrop.forms.admin.players.PlayerPrefsForm whose display and save_data methods can map the form values to and from the data dict. Players that do this will have links, in MediaDrop’s admin backend, to a page where an admin can use the rendered form to edit the Player instance. An example of a player that has this feature is mediadrop.lib.players.YoutubeFlashPlayer.

Implementation - Python

Any new player class will need to be imported and registered like so:

from mediadrop.lib.players import AbstractPlayer

class MyPlayer(AbstractPlayer):
    Implement all abstract properties and abstract methods here ...


See the players in mediadrop/lib/ for examples.

Implementation - JavaScript

Developers should familiarize themselves with MediaDrop’s Javascript Development with Closure Tools guide and the library class goog.ui.Component.

Every Player has a JavaScript class that is responsible for handling the decoration and resizing of the player element in the page. It is this class that is instantiated using the code produced by render_js_player.

This managing class inherits from goog.ui.Component. It must implement the MediaDrop-specific getSize() and setSize().

See the files in mediadrop/public/scripts/mcore/players/ for examples.

Abstract Base Class

class mediadrop.lib.players.AbstractPlayer(media, uris, data=None, width=None, height=None, autoplay=False, autobuffer=False, qualified=False, **kwargs)

Player Base Class that all players must implement.

__init__(media, uris, data=None, width=None, height=None, autoplay=False, autobuffer=False, qualified=False, **kwargs)

Initialize the player with the media that it will be playing.

  • media ( instance) – The media object that will be rendered.
  • uris (list) – The StorageURIs this player has said it can_play().
  • data (dict or None) – Optional player preferences from the database.
  • elem_id (unicode, None, Default) – The element ID to use when rendering. If left undefined, a sane default value is provided. Use None to disable.

Return the desired viewable height + the height of the controls.


Return the desired viewable width + any extra for the player.


Test all the given URIs to see if they can be played by this player.

This is a class method, not an instance or static method.

Parameters:uris (list) – A collection of StorageURI tuples to test.
Return type:tuple
Returns:Boolean result for each of the given URIs.
default_data = {}

An optional default data dictionary for user preferences.


A unicode display name for the class, to be used in the settings UI.


Return a subset of the uris for this player.

This allows for easy filtering of URIs by feeding any number of kwargs to this function. See mediadrop.lib.uri.pick_uris().


A unicode string identifier for this class.


Render a javascript string to instantiate a javascript player.

Each player has a client-side component to provide a consistent way of initializing and interacting with the player. For more information see mediadrop/public/scripts/mcore/players/.

Return type:unicode
Returns:A javascript string which will evaluate to an instance of a JS player class. For example: new mcore.Html5Player().

Render the XHTML markup for this player instance.

Parameters:error_text – Optional error text that should be included in the final markup if appropriate for the player.
Return type:unicode or genshi.core.Markup
Returns:XHTML that will not be escaped by Genshi.
settings_form_class = None

An optional mediadrop.forms.admin.players.PlayerPrefsForm.

supports_resizing = True

A flag that allows us to mark the few players that can’t be resized.

Setting this to False ensures that the resize (expand/shrink) controls will not be shown in our player control bar.

Player Preferences Form

class mediadrop.forms.admin.players.PlayerPrefsForm(*args, **kw)
display(value, player, **kwargs)

Display the form with default values from the given player.

If the value dict is not fully populated, populate any missing entries with the values from the given player’s _data dict.

  • value (dict) – A (sparse) dict of values to populate the form with.
  • player (mediadrop.model.player.PlayerPrefs subclass) – The player prefs mapped object to retrieve the default values from.
save_data(player, **kwargs)

Map validated field values to

Since form widgets may be nested or named differently than the keys in the dict, it is necessary to manually map field values to the data dictionary.

  • player (mediadrop.model.player.PlayerPrefs subclass) – The player prefs mapped object to store the data in.
  • **kwargs – Validated and filtered form values.
Raises formencode.Invalid:

If some post-validation error is detected in the user input. This will trigger the same error handling behaviour as with the @validate decorator.

You're reading the documentation for MediaDrop 0.11dev (current git master). For the latest stable release please consult the documentation for MediaCore CE 0.10.