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.

Summary

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 ...
    """

AbstractPlayer.register(MyPlayer)

See the players in mediadrop/lib/players.py 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.

Parameters:

• media (mediadrop.model.media.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.

adjusted_height

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

adjusted_width

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

can_play(uris)

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.

display_name

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

get_uris(**kwargs)

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().

name

A unicode string identifier for this class.

render_js_player()

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_markup(error_text=None)

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.

Parameters:

• 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 PlayerPrefs.data.

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

Parameters:

• 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.

Related Functions

mediadrop.lib.players.media_player(media, is_widescreen=False, show_like=True, show_dislike=True, show_download=False, show_embed=False, show_playerbar=True, show_popout=True, show_resize=False, show_share=True, js_init=None, **kwargs)

Instantiate and render the preferred player that can play this media.

We make no effort to pick the “best” player here, we simply return the first player that can play any of the URIs associated with the given media object. It’s up to the user to declare their own preferences wisely.

Player preferences are fetched from the database and the mediadrop.model.players.c.data dict is passed as kwargs to AbstractPlayer.__init__().

Parameters:

• media (mediadrop.model.media.Media) – A media instance to play.
• js_init – Optional function to call after the javascript player controller has been instantiated. Example of a function literal: function(controller){ controller.setFillScreen(true); }. Any function reference can be used as long as it is defined in all pages and accepts the JS player controller as its first and only argument.
• **kwargs – Extra kwargs for AbstractPlayer.__init__().

Return type:

str or None

Returns:

A rendered player.