Javascript Support

Every GWT application ends up as a package of Javascript files optimized for each browser. How about taking advantage of the breath-taking features of GWT in traditional page-based applications?

The API features a module to export the core player and seekbar widgets as Javascript objects for use in page-based applications. The following sections describe how to use the exported widgets.

Add the script to the host page

Download the BST Player JS Library and unzip into a folder of your choice. The library is a GWT application exporting the core player and seekbar widgets as Javascript objects.

Add the bst_player_js/bst_player_js.nocache.js javascript file to the HTML host page. 

<script type="text/javascript" src="folder-name/bst_player_js/bst_player_js.nocache.js">
</script>

Create the widgets HTML container elements

Create the HTML elements that will contain the widgets. This can be as simple as defining HTML <div> tags at required places. 
<div id="my-player" />
<div id="_progress" />

Define the onBSTPlayerReady() function

The library requires the onBSTPlayerReady() function be defined. This function will be called when the player and/or seekbar objects are bound to the host page. 
<script type="text/javascript">
   var onBSTPlayerReady = function() {
   }
</script>
Typically, all player widget creation and manipulation should happen after this function call.

Create the widgets and use as required

The player object is bound as a bstplayer.Player(plugin, mediaURL, autoplay, width, height, options) object where:
  • plugin [String] - is one of the supported media plugins (Note: case-sensitive)
  • mediaURL [String] - the URL of the media
  • autoplay [boolean] - true to autoplay the media, false otherwise
  • width [String] - the width of the widget (in CSS units)
  • height [String] - the height of the widget (in CSS units)
  • options [Javascript Object] - used to pass user-defined map of values to the library (currently not used, should be null)
The seekbar widget is bound as a bstplayer.SeekBar(height, containerId, options) object where:
  • height [String] - the height of the widget (in CSS units)
  • containerId [String] - the HTML element id, where the widget will be placed
  • options [Javascript Object] - used to pass user-defined map of values to the library (currently not used, should be null)
Once the Player object is created, the corresponding widget can be attached to the page by calling the object's inject() method. The inject() method takes the id of the HTML container element as a parameter. Following is an example: 
<script type="text/javascript">
  var onBSTPlayerReady = function() {
      player = new bstplayer.Player("Auto", "some-cool-sound.mp3", false, "100%", "50px", null);
      player.inject('my-player');

      seekbar = new bstplayer.SeekBar(10, '_progress', null);
  }
</script>

The supported plugins

The plugin parameter of the Player object can be one of the following values:

Name Media Plugin
DivXPlayer DivX® Web Player plugin
FlashPlayer Adobe Flash plugin for playing Flash supported file formats
Native HTML 5 video handler in supported browsers
QuickTimePlayer QuickTime plugin
VLCPlayer VLC Media Player plugin
WinMediaPlayer Windows Media Player plugin
Auto Any avaliable media plugin on the client that supports the specified media URL
PlaylistSupport Any available media plugin that supports client side playlist management

Object methods and properties

The Player object supports all the public methods defined in the AbstractMediaPlayer class and the PlaylistSupport interface, with the exception of all the addXXXHandler methods.

The SeekBar object supports the following methods:

Method Parameter Type Description
setLoadingProgress(loadingProgress) float set the progress of the media loading operation
setPlayingProgress(playingProgress) float set the progress of the media playback operation

Event Handling

Instead of the addXXXHandler methods, the Player object defines an addEventListener(name, function) method with the following event names:

Event name Description
onPlayerState for PlayerStateEvent events
onPlayState for PlayStateEvent events
onLoadingProgress for LoadingProgressEvent events
onError for DebugEvent events of the Error type
onDebug for DebugEvent events of the Info type

The SeekBar object also defines an addEventListener(name, function) method with the following event name:

Event name Description
onSeekChanged for SeekChangeEvent events

The function registered as an event listener is passed an event object containing various properties describing the status of the event. The following table lists the properties of each event object

Event name Event properties Property Type Description
onPlayerState playerState String the state of the player. Values can be one of:
Ready - player is initialized and ready for interaction,
BufferingStarted - player has started buffering,
BufferingFinished - player has stopped buffering,
DimensionChangedOnVideo - the dimension of the player has changed to match the size of the current media, especially video
FullScreenStarted - player has entered fullscreen
FullScreenFinished - player has returned from fullscreen
onPlayState playState String the state of media playback. Values can be one of:
Started - playback has started,
Finished - playback has finished,
Paused - playback is currently paused,
Stopped - playback is currently stopped
itemIndex int the index of the media item in the playlist
onLoadingProgress progress float the loading progress. Value is between 0 and 1
onError message String message associated with the error event
onDebug message String message associated with the debug event
onSeekChanged seekPosition float the new position of the seek bar. Value is between 0 and 1

Seekbar styling

The seekbar consists of two indicators - loading and progress indicators. The loading indicator is placed directly under the playing indicator. The loading indicator shows the progress of a media loading operation while the playing indicator shows the progress of media playback

The seekbar has the following CSS style classes registered already and can be used to change the apperance to taste

.player-CSSSeekBar { the seekbar itself }
.player-CSSSeekBar .loading { the loading progress indicator }
.player-CSSSeekBar .playing { the playing progress indicator }

Example

The example below illustrates a custom player implementation:

<style>
    .player-CSSSeekBar {
        background-color: silver;
    }
    .player-CSSSeekBar .loading {
        background-color: yellow;
        cursor: pointer;
    }
    .player-CSSSeekBar .playing {
        background-color: red;
        cursor: pointer;
    }
</style>

<script type='text/javascript'>
 var player;
 var seekbar;
 var onBSTPlayerReady = function() {
      seekbar = new bstplayer.SeekBar(10, '_progress', null);
      seekbar.addEventListener('onSeekChanged', function(evt){
          player.setPlayPosition(evt.seekPosition * player.getMediaDuration());
      });

      player = new bstplayer.Player('Auto', 'demo/bst-player-js/tools/applause.mp3',
                                false, null, null, null);
      player.addEventListener('onPlayState', function(evt){
          switch(evt.playState) {
              case 'Paused':
                  document.getElementById('playButton').disabled = false;
                  document.getElementById('pauseButton').disabled = true;
                  document.getElementById('stopButton').disabled = false;
                  break;
              case 'Started':
                  document.getElementById('playButton').disabled = true;
                  document.getElementById('pauseButton').disabled = false;
                  document.getElementById('stopButton').disabled = false;
                  break;
              case 'Stopped':
              case 'Finished':
                  document.getElementById('playButton').disabled = false;
                  document.getElementById('pauseButton').disabled = true;
                  document.getElementById('stopButton').disabled = true;
                  break;
          }
      });
      player.addEventListener('onPlayerState', function(evt){
          if(evt.playerState == 'Ready') {
              document.getElementById('playButton').disabled = false;
              document.getElementById('pauseButton').disabled = true;
              document.getElementById('stopButton').disabled = true;

              playTimer = window.setInterval(function(){
                  seekbar.setPlayingProgress(player.getPlayPosition() /
                            player.getMediaDuration());
                  document.getElementById('timer').innerHTML =
                    (player.getPlayPosition() / 1000) + ' / ' +
                    (player.getMediaDuration() / 1000);
              }, 1000);
          }
      });
      player.addEventListener('onLoadingProgress', function(evt){
          seekbar.setLoadingProgress(evt.progress);
      });
      player.addEventListener('onError', function(evt){
          window.alert(evt.message);
      });
      player.inject('_pid');
  }
</script>
<script type='text/javascript'
    src='demo/bst-player-js/bst_player_js/bst_player_js.nocache.js'></script>

<div align='center' style='width:350px;margin:20px;border:silver 1px solid;padding:5px'>
    <div id='_pid'></div>
    <div id='_progress'></div>
    <div style='padding:10px'>
        <button id='playButton' onclick='player.playMedia()' disabled>Play</button>
        <button id='pauseButton' onclick='player.pauseMedia()' disabled>Pause</button>
        <button id='stopButton' onclick='player.stopMedia()' disabled>Stop</button>
        <div id='timer'>0 / 0</div>
    </div>
</div>
And the result?
0 / 0