Migrating to version 2.0

Version 2.0 introduced many changes to the API and is NOT backwards compatible. However a little effort is all that is required to migrate existing codes.

Base API / Player Providers

The API library has been broken down into multiple modules to further improve the projects' development cycle and simpler custom player integration:

  • The Base API provides the basic classes and interfaces for developing and/or working with media player widgets. The Base API is packaged as bst-player-api-<version>.jar file and will be required in every project.
  • The Player Providers provides the various widgets that are used to embed media players. Different player providers are available for different player widgets, such as:
    • Core Player Provider: provides the WinMediaPlayer, FlashPlayer, DivXPlayer, VLCPlayer, QuickTimePlayer widgets
    • Sample Player Provider: provides the FlatVideoPlayer and Capsule player widgets, which are examples of media players with HTML custom controls
    • YouTube Player Provider: provides the widgets to embed YouTube video players
    • Vimeo Player Provider: provides the widgets to embed Vimeo video players

You will only need to include the player providers that are required for your application. Kindly refer to the documentation of each provider for details.

Deprecated classes/methods removed

In order to clean up the codebase, classes and methods that have been deprecated in earlier release versions have been removed from the API. This version is NOT backwards compatible anyway.

Changed class/method definitions

In an attempt to simplify the API, a definition of a couple of class methods have changed. These include (but not limited to ...):

  • LoadException is no longer thrown in Player widgets' constructor methods.
  • AbstractMediaPlayer.showLogger(boolean) method is removed. The Logger widget is no longer attached to player widgets by default. You may choose to use it or instead use other standard GWT logging frameworks.
  • AbstractMediaPlayer.setConfigParameter(ConfigParameter, Object) replaces all overloaded AbstractMediaPlayer.setConfigParameter(ConfigParameter, ConfigValue) methods.

Migrating to version 1.3

Version 1.3 introduced many enhancements to the API and is backwards compatible. However the following is worth taking note of:

GWT 2.2 dependency

The library now depends on GWT 2.2 or later.

Flash Player 10 dependency

The FlashMediaPlayer widget now requires Flash Player 10 or later. PluginVersionException will be thrown if lower versions were found. This may not be an issue anyway since most browsers have upgraded Flash Player to version 10 or higher

Migrating to version 1.2

Version 1.2 introduce many enhancements that may affect existing code. The effect may not be much but it is worth taking note of.

GWT 2.x dependency

The library now requires GWT 2.0 or later. GWT has come a long way since version 1.6 so this may not be an issue, as most GWT projects are based on 2.x already.

WinMediaPlayer and non-IE browsers

WinMediaPlayer widget now requires the Windows Media Player plugin for Firefox in non-IE browsers to guarantee programmable control. Since this may not always be required, two operating modes are defined - the embed-only and programmable modes.

In embed-only mode, the widget is expected to be used for rendering only without any programmatic control. Consequently method calls on the widget in this mode may fail and such errors/failures are suppressed.

In programmable mode - the default, the widget throws PluginNotFoundException in non-IE browsers without the Windows Media Player plugin for Firefox.

Migrating from version 0.6

The following improvements on version 0.6 may require minor tweaks to existing code. Such changes however, should only take a few minutes to rectify.

Code Refactoring

The library is now split into different modules consisting of:

  • com.bramosystems.oss.player.core.Core - The core classes of the API (including the base player widgets)
  • com.bramosystems.oss.player.core.event.Event - The new event classes (inherited by the Core module)
  • com.bramosystems.oss.player.capsule.Capsule - The sample custom sound player (inherits the Core module)
  • com.bramosystems.oss.player.flat.FlatVideoPlayer - The sample custom video player (inherits the Core module)

Consequently, existing codes that inherits the com.bramosystems.gwt.player.BSTPlayer module will now need to inherit:

com.bramosystems.oss.player.core.Core - if using only the base player widgets (such as WinMediaPlayer, QuickTimePlayer etc)

com.bramosystems.oss.player.capsule.Capsule - if using the sample custom sound player

com.bramosystems.oss.player.flat.FlatVideoPlayer - if using the sample custom video player

New Event Handlers

GWT 1.6 introduced a new EventHandler system which makes the development of complex, decoupled applications easier. Inline with this, the MediaStateListener class has been replaced with the following handlers in the com.bramosystems.oss.player.core.event.client package:

PlayerStateHandler handles events that are fired when the state of the player changes
PlayStateHandler handles events that are fired when the state of media playback changes
MediaInfoHandler handles MediaInfoEvent fired whenever media metadata is available
LoadingProgressHandler handles events that are fired when the progress of a loading media changes
DebugHandler handles events that are fired when info/error level messages are generated by the embedded plugin

Also, VolumeChangeListener used for volume control is replaced with VolumeChangeHandler, while SeekChangeListener used for seek controls is replaced with SeekChangeHandler.

Existing codes that use:

player.addMediaStateListener{ new MediaStateListener() {

will now need to do:

player.addPlayerStateHandler { new PlayerStateHandler() {
    // if interested in player state changes
player.addPlayStateHandler { new PlayStateHandler() {
    // if interested in play state changes


Please check the API for details.

New FlashMediaPlayer

The FlashMP3Player and FlashVideoPlayer widgets has been removed in favour of FlashMediaPlayer widget. The new widget is designed to handle all media types supported by the Adobe Flash player including MP3 sound, FLV video and MP4 sound/video.

New CustomPlayerControl widget

The FlatCustomControl widget has been replaced with the new CustomPlayerControl widget. The widget provides a simple player UI with play/pause/stop buttons as well as a seekbar to control the supported media plugins.