ActionScript Basics

The following applications/features are supported via the Brightcove Developer's Group.
If you need help with the following instructions please go to the Brightcove Developer's Group.
In the Developer's Group you can find help from other developers, including some Brightcove folks.

This article presents an introductory exercise in basic ActionScript scripting with the Brightcove Player. The exercise shows how to use the Brightcove API to access your content in the Brightcove Service.

Before You Begin

Before you begin, you'll need to have created a Flash movie and placed the ActionScript snippet for the player you want to script against. If you need help doing that read Embedding the Player in Flash.

You may need to alter the code in the examples below to fit into your exact environment, depending on where you've placed the snippet.

Customize the onTemplateLoaded function

Although the bcPlayer object is created immediately when the snippet is executed by Flash Player, the Brightcove Player takes time to load into it. And after that loads, your chosen template must load into the player as well. This only takes a couple of seconds, but you need to wait until these loading steps are complete before you attempt to access the Brightcove ActionScript API. When this happens, the onTemplateLoaded method of the bcPlayer object will be called. This is an important point, because it is at that point that you can begin to interact with the player, add event listeners, etc. In the snippet you should see the following code:

bcln.onLoadInit = function():Void {
	bcPlayer.onTemplateLoaded = function() {};
	bcPlayer.onTemplateLoadStart = function() {};
	bcPlayer.onTemplateLoadProgress = function(bytesLoaded:Number, bytesTotal:Number) {};
	};
	bcln.onLoadProgress = function(player:MovieClip, bytesLoaded:Number, bytesTotal:Number):Void {
	// place preload feedback here for shell movie
};

When onTemplateLoaded is called, the template has completely loaded and you can start interacting with the bcPlayer object via the ActionScript API. There are a couple of ways of doing this. One is to place your code right there in between the curly brackets, like so:

bcPlayer.onTemplateLoaded = function() {
// code interacting with bcPlayer via AS API
};

Probably more preferable though, is to create a separate function, outside the snippet, and assign the name that function to bcPlayer.onTemplateLoaded, like so:

bcPlayer.onTemplateLoaded = initializePlayer;

In this example, there would be another function written below the snippet itself, named initializePlayer. This function would be called as soon as the template was loaded and the ActionScript API was ready to use.

One thing to note: if you create your own function as described above, the scope of that function will still be within bcPlayer. In other words, this will refer to bcPlayer not _root as you might expect. To avoid this, you can use the Delegate class included with Flash, like so:

bcPlayer.onTemplateLoaded = mx.utils.Delegate.create(_root, initializePlayer);

Note that "template loaded" means just that. The template you created has loaded. As its next step, it will start loading the content (titles, lineups, categories) that you added in the console. Realize that while you can now interact with the player, you cannot yet access that content. Before you can deal with titles and lineups that are a part of your player, you have to wait for them to load in. You can do that by listening for the contentLoad event. Using event listeners is described in the next section.

You may have noticed the other two functions, onTemplateLoadStart and onTemplateLoadProgress. If desired, you can create a preloader for the shell movie within the bcln.onLoadProgress function, and for the template itself in the bcPlayer.onTemplateLoadProgress function, and even hook in to the event that fires when the template begins loading by putting some code in the bcPlayer.onTemplateLoadStart function. But for the most part, the shell and the template load quickly enough that it is not necessary to write any kind of preloader.

Add event listeners

Nearly all interaction with the player comes from calling functions on the bcPlayer object and listening for events that it generates.

There are many events available, for things like when a lineup or title loads, when a video is started or stopped or is complete, when an ad starts or stops, etc. Also, when you perform a search or fetch a title or lineup that is not already assigned to a player, the results of these actions are not delivered immediately, but are loaded in asynchronously, and you must listen for an event to know when the results are available. Therefore, it is important to understand how to add event listeners to the bcPlayer object.

If you have used the Flash V2 component framework you are already familiar with how events and event listeners work. The bcPlayer event framework is very similar, but has a few important changes worth noting.

Event listeners are added with the bcPlayer's addEventListener() method. In its simplest form, this takes a string containing the name of the event you want to listen for, and an object that will be the listener. For example, say you wanted to listen to the "contentLoad" event, and have the main timeline be the listening object:

bcPlayer.addEventListener("contentLoad", this);

In this case, when the event occurs, bcPlayer will attempt to call a function on _root, with the same name as the event, contentLoad. You would simply define a function with that name and it would be called when content had loaded in.

If you want to specify a function with a different name, you can pass the function name in as a third parameter. Note that this parameter is a String containing the name of the function, not a reference to the function itself.

All of the available events, and when they occur, are listed in the API reference.

Write event handlers

Presumably, you've now added an event listener and specified a function to be called as a handler for that event. Event handling functions are automatically passed an object containing information about the event, usually known at the event object or info object. Let's write an event handler for the contentLoad event we registered for above:

function contentLoad(evt:Object) {
	for (var i in evt.parameters) {
		trace(i + ":" + evt.parameters[i]);
	}
}

The most important property of the event info object is called parameters. This in turn may have other properties that contain specific information about the event that just occurred. In this example, we're iterating through the parameters of the contentLoad event, which, depending on what's been programmed to the player in the console, may contain an array of lineups, an array of titles, or even just a single title.

These data structures are called DTOs (Data Transfer Objects). If you wanted to display the name of a title that had just loaded, you could add an event listener for the titleLoad event, and then do as follows:

function titleLoad(infoObj:Object):Void {
	var titleDTO:Object = infoObj.parameters.title;
	trace("title loaded: " + titleDTO.displayName);
}

The specific DTOs returned for each event are detailed in the help entries for the events themselves. Details on the contents of the various DTOs can be found in the DTO reference.

Getting/Fetching content

Now that we are prepared to handle the events broadcast by the bcPlayer object we're ready to start making calls.

There are two families of methods that we use for requesting content. One family of methods is prefixed by "get," the other by "fetch." The difference between these two is important.

Fetch methods are asynchronous, and make a server request to obtain DTOs. Event handlers are required to handle the data that comes back. Get methods, on the other hand, are synchronous and return immediately. However they can only return DTO's that have already been loaded into the player - whether in the initial content load or on a subsequent load. If the content is unavailable a get function will return undefined.

Therefore, the recommended way to go about requesting additional content from the server is to use both methods. The following example shows to request and play a title presuming you know its id before hand:

var title_id = "000000000";

if (bcPlayer.getTitleById(title_id) == undefined) {
	bcPlayer.addEventListener("titleLoad", this);
	bcPlayer.fetchTitleById(title_id);
} else {
	bcPlayer.loadTitleById(title_id);
}

function titleLoad(evt:Object) {
	bcPlayer.loadTitleById(evt.parameters.id);
}