The information in this document applies to version 1.0 and later. Check here for previous versions.

Getting Started

Before getting started, download the library and add it to your application classpath. You can download the library on the projects download page on Google Code.

If you are developing with Maven, you can add the library to your projects' dependencies: 

<dependency>
    <groupId>com.bramosystems.oss.player</groupId>
    <artifactId>bst-player-api</artifactId>
    <version>${appropriate-version}</version>
    <scope>provided</scope>
</dependency>

However, you will need to add the Bramosystems Maven Repository definition to your POM: 

<repositories>
    . . .
    <repository>
        <id>bramosystems-releases</id>
        <name>Bramosystems Release Repository</name>
        <url>http://downloads.bramosystems.com/maven2/releases</url>
    </repository>
    . . .
</repositories>

If you will also like to use the snapshots; 

<repositories>
    . . .
    <repository>
        <id>bramosystems-snapshot</id>
        <name>Bramosystems Snapshots Repository</name>
        <url>http://downloads.bramosystems.com/maven2/snapshots</url>
    </repository>
    . . .
</repositories>
Top

Developing with BST Player

The following sections describe the basic usage of the library. Ensure your application module inherits the com.bramosystems.oss.player.core.Core module.

Embedding the core player widgets

All core player widgets share the same API definition and can be used in almost the same way. 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

The following table lists all core widgets, the supported plugin and the minimum plugin version required on the browser.

Player widget Media Plugin Minimum plugin version
DivXPlayer DivX® Web Player plugin 2.0.1
FlashMediaPlayer Flash® Player plugin 10.0
QuickTimePlayer Quicktime Player plugin 7.2.1
VLCPlayer VLC Media Player plugin 1.0.0
WinMediaPlayer Windows Media Player 7.0

Refer to the API documentation for details.

Top

Embedding HTML 5 media handlers

As of version 1.1, the NativePlayer class in the com.bramosystems.oss.player.core.client.ui package wraps the HTML 5 video element for use in HTML 5 supported browsers.

The following example shows a basic usage: 

SimplePanel panel = new SimplePanel();   // create panel to hold the player
AbstractMediaPlayer player = null;
try {
    // create the player, specifing URL of media
    player = new NativePlayer("www.example.com/mediafile.ogv");
    panel.setWidget(player); // add player to panel.
} catch(PluginNotFoundException e) {
    // catch PluginNotFoundException, thrown if client
    // browser is not HTML 5 compliant
    panel.setWidget(PlayerUtil.getMissingPluginNotice(e.getPlugin()));
}

NOTE:- Works only on HTML 5 supported browsers

Top

Embedding YouTube video

As of version 1.1, the YouTube module exposes the YouTube Player API inline with the interface/event handler definitions of the BST Player API.

The YouTubePlayer class in the com.bramosystems.oss.player.youtube.client package wraps the YouTube video player

Following is an example: 

SimplePanel panel = new SimplePanel();   // create panel to hold the player
AbstractMediaPlayer player = null;
try {
    // create the player, specifing URL of media
    player = new YouTubePlayer("http://www.youtube.com/v/video-id");
    panel.setWidget(player); // add player to panel.
} catch(PluginVersionException e) {
    // required Flash 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) {
    // required Flash plugin not found, display a friendly notice.
    panel.setWidget(PlayerUtil.getMissingPluginNotice(e.getPlugin()));
}

The ChromelessPlayer class is also available to enable custom controls with the YouTube player.

The following is an example: 

SimplePanel panel = new SimplePanel();   // create panel to hold the player
AbstractMediaPlayer player = null;
try {
    // create the player, specifing URL of media
    player = new ChromelessPlayer("http://www.youtube.com/v/video-id",
        "100%", "350px");
    CustomPlayerControl cpc = new CustomPlayerControl(cp);

    FlowPanel fp = new FlowPanel();
    fp.add(player);
    fp.add(cpc);
    panel.setWidget(fp); // add player and custom control to panel.
} catch(PluginVersionException e) {
    // required Flash 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) {
    // required Flash plugin not found, display a friendly notice.
    panel.setWidget(PlayerUtil.getMissingPluginNotice(e.getPlugin()));
}

NOTE:- Modules that use the YouTubePlayer widget should inherit the com.bramosystems.oss.player.youtube.YouTube module.

Select a suitable player dynamically

The PlayerUtil class in the com.bramosystems.oss.player.core.client package 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.

What next ?

Using Events

Use the player widgets with UiBinder

Integrate the API in page-based applications

Create custom player controls

Export your players as Javascript objects

Top