BST Player - Getting Started

Getting Started developing with BST Player

Starting with BST Player 2, while the Base API provides the basic classes and methods to work with player widgets, all media player widgets are made available via different Player Provider package libraries. These separation provides the following benefits:

Use only the player widgets you need. Instead of adding the entire library to your application, you can include only the subset that is actually required.
Simpler project management. Each player widget can evolve within its provider package with little impact on the revision cycles of other provider packages and the Base API.
Improved API/Provider architecture. It is much easier to add new widgets to support more media players in a 'pluggable' manner

The API/Provider structure also provides multiple methods of adding player widgets to your application - either working directly with the Player Providers or using the Base API.

Whichever method you choose, ensure your application module inherits the modules of the player providers that you will be using. The following sections describe the methods using the Core Player Provider.

Embedding with the Player Providers

The various player providers adds support for different media player widgets to the API. Deriving from the Base API, all player widgets share similar API definitions and can be used in almost the same way.

The simplest way of embedding a player widget is to create the respective widget directly. The following describes an example using the WinMediaPlayer class in the com.bramosystems.oss.player.core.client.ui package. WinMediaPlayer wraps the Windows Media Player plugin as a GWT widget.

SimplePanel panel = new SimplePanel();   // create panel to hold the player
AbstractMediaPlayer player = null;
try {
    // create the player, specifing URL of media
    player = new WinMediaPlayer("www.example.com/mediafile.wma");
    panel.setWidget(player); // add player to panel.
} catch(PluginVersionException e) {
    // required plugin version is not available, alert user
    // possibly providing a link to the plugin download page.
    panel.setWidget(new HTML(".. some nice message telling the user
           to download plugin first .."));
} catch(PluginNotFoundException e) {
    // catch PluginNotFoundException and display a friendly notice.
    panel.setWidget(PlayerUtil.getMissingPluginNotice(Plugin.WinMediaPlayer));
}

The above code adds a Windows Media Player object to the panel and loads the media at the specified URL. Controlling the plugin is straight forward as shown below:

player.playMedia();  // starts playback
player.pauseMedia();  // pauses playback
player.stopMedia();  // stops playback
player.setVolume(0.8); // sets the playback volume to 80% of maximum

Top

Embedding with the Base API

The Base API provides utility methods to embed media player widgets indirectly. The following describes an example using the WinMediaPlayer widget.

SimplePanel panel = new SimplePanel();   // create panel to hold the player
AbstractMediaPlayer player = null;
try {
    // retrieve the basic information about the player as registered with the API
    PlayerInfo pi = PlayerUtil.getPlayerInfo("core", "WinMediaPlayer");

    // create the player, using the PlayerInfo object and specifing URL of media
    player = PlayerUtil.getPlayer(pi, "www.example.com/mediafile.wma", false, 
        "width", "height");
    panel.setWidget(player); // add player to panel.
} catch(PluginVersionException e) {
    // required plugin version is not available, alert user
    // possibly providing a link to the plugin download page.
    panel.setWidget(new HTML(".. some nice message telling the user
           to download plugin first .."));
} catch(PluginNotFoundException e) {
    // catch PluginNotFoundException and display a friendly notice.
    panel.setWidget(PlayerUtil.getMissingPluginNotice(Plugin.WinMediaPlayer));
}

During GWT compilation, all player provider packages on the classpath are searched and all player widgets found are linked to the Base API. The PlayerInfo class is a utility class that gives the basic information about all player widgets that are found on the classpath

All player providers are identified by a name which is unique in the application and all player widgets have a name which is unique with its provider package. This way, every player widget is identified by its name and the name of its provider package.

Referring to the above example, the PlayerInfo object that describes the player widget "WinMediaPlayer" in the player provider package named "core" was retrieved and thereafter used to create the player.

This method provides a more flexible way of creating player widgets since it is possible to use these few lines of code to create all possible player widgets. Also, it is easier to manipulate String names than instantiating all possible player widget implementation classes

Top

Select a suitable player dynamically

The PlayerUtil class defines overloaded methods to dynamically select a player that can playback a specfied media.

A suitable player is determined based on the features/capabilities derivable from the player plugin, its availability on the browser, and its suitability to playback the specified media.

Here goes an example:

SimplePanel panel = new SimplePanel();   // create panel to hold the player
AbstractMediaPlayer player = null;
try {
    // get any player that can playback media
    player = PlayerUtil.getPlayer(Plugin.AUTO, 
        "http://www.example.com/some-funny-video.qt",
        false, "50px", "100%");
    panel.setWidget(player); // add player to panel.
} catch (PluginVersionException e) {
    // catch PluginVersionException, thrown if required plugin version is not found
    panel.setWidget(PlayerUtil.getMissingPluginNotice(e.getPlugin()));
} catch(PluginNotFoundException e) {
    // catch PluginNotFoundException, thrown if no plugin is not found
    panel.setWidget(PlayerUtil.getMissingPluginNotice(e.getPlugin()));
}

Top

Conclusion

With a simple set of API, BST Player provides an abstraction of popular media player plugins available on the web, therefore making media playback control much more fun filled. Even more appealing is the dynamic player plugin selection that makes the development of custom media player controls more interesting.