Using the Player API SWC

When loading the Brightcove player into a SWF, perhaps a Flex application or an ActionScript project in Flex Builder or Flash, you have the ability to interact with the player through the player's ActionScript API, an extensive collection of module and component interfaces that allow you a high level of control of the player. However, development against the Player API might prove frustrating for those used to the strong typing and code hints provided by their IDE, since all of the player API's objects (modules, components and complex return types) are typed as Object objects. There is a solution for this, and that is to download and use the Player API SWC.

Objects in the Player API

Before discussing the SWC further, it's helpful to understand exactly why the player uses Object objects for its API. The Brightcove player is loaded at runtime into your application. Its classes need to be independent of the code in your application so that Brightcove can update and improve the code each release. If we distributed the internal player classes themselves in order for developers to get strong typing and code hints, then the classes would be compiled into the shell application into which our player was loaded. These classes would not then be updated with new code in the player, so it is important that these internal player classes are not distributed themselves or available outside of the player.

When the player passes a reference to a module to a shell application through a call to player.getModule(), it isn't actually an Object object, but rather an instance of a specific player class, such as com.brightcove.player.api.ContentAPI. However, since you as a developer have no reference to this class, you must deal with it as just an Object instance, as in the following code:

var module:Object = player.getModule("content");
module.getMediaAsynch(12345);

The problem with this, of course, is that there is nothing to tell you what methods may be found on the module except for the external documentation and there would be no compiler warning if you mistyped the method call or were passing the wrong number or type of parameters.

Strongly typed objects and code hints using the Player API SWC

As a solution for this issue, Brightcove has released a Player API SWC, which you can download as part of our player SDK which also includes plenty of example applications. (Note that the SWC can be found in the FlexSearchWithSWC/libs folder, rather than in the apiSWC folder where you might expect to find it.) This SWC contains wrapper classes for all of the API objects that the player returns or requires. What this means is that when an object is returned by the player, it is wrapped in another class that exposes the methods so that an IDE like Flash or Flex Builder can provide compile time errors of the strongly typed objects. In Flex Builder (but not int he Flash IDE), you will also get code hints of what methods are available, what parameters are required and what type a method returns.

Since the classes provided in the SWC are not internal player classes, they are not compiled at all into the Brightcove player. Developers are then safe to compile these into their applications without worry of conflicting with the player classes or being out of synch with new releases.

To use the SWC, you must import it into your project through the methods detailed in the documentation for that particular IDE. For instance, in Flex Builder 3 you would add the SWC through the Library path tab in the project properties. In Flash CS4, you would add the SWC as library path through the ActionScript settings dialog. Once the SWC is imported, you can interact with its classes.

The way to enable the wrapping of the internal player classes with the wrapper classes in the SWC is to pass the original BrightcovePlayer instance you create (the instance created from the ActionScript class obtained from the Brightcove Publishing module) within a com.brightcove.api.BrightcovePlayerWrapper instance. All interaction should then be through this wrapper. That's really it.

As an example, the following code is how you would instantiate the player without using the SWC:

var player:BrightcovePlayer = new BrightcovePlayer();

In this case, all interaction would be through the player variable and no strong typing would be available. However, by wrapping this instance, you can get both strong typing and code hints:

var player:BrightcovePlayer = new BrightcovePlayer();
				
// be sure to import com.brightcove.api.BrightcovePlayerWrapper
// and com.brightcove.api.events.ExperienceEvent!
_player = new BrightcovePlayerWrapper(player);
_player.addEventListener(ExperienceEvent.TEMPLATE_LOADED, onTemplateLoaded);

At this point, all interaction would be through the _player property and strong typing and code hints would be available. The following code demonstrates how you might set up a handler for the TEMPLATE_READY event in the player using the SWC classes.

// be sure to import com.brightcove.api.events.ExperienceEvent,
// com.brightcove.api.APIModules and com.brightcove.api.modules.ExperienceModule
private function onTemplateLoaded(event:ExperienceEvent):void {
  var module:ExperienceModule = _player.getModule(APIModules.EXPERIENCE);
  module.addEventListener(ExperienceEvent.TEMPLATE_READY, onTemplateReady);
}

Note that in addition to the objects like events and modules, you also have access to constants like APIModules.EXPERIENCE so that your code does not need to contain "magic strings".

We hope the Player API SWC will ease development by taking advantage of the capabilities of the IDEs used by most Flash developers and make it easy to interact with the Brightcove player.