Javascript API

There is a newer version of this page. You can find it here.

Description

A JavaScript API for controlling the player should help web designers/developers create HTML/JavaScript/CSS based player controls. The same JavaScript API could potentially be used for our future work on the HTML5 fallback and should allow site-owner to provide exactly the same controls for both Flash based video player and the HTML5 fall back player.

We will focus on the control API, since the SWFObject library is enough for most JavaScript configuration scenarios.

Use Case:

As Jason, The Web developer, working a lot with Dreamweaver I know that I can use SwfObject to embed the player and configure
it but I would also want to be able to control it from JavaScript : play/pause, seek, etc.

Details

We expose the MediaPlayer public API as JavaScript API.
That means that all the MediaPlayer public methods and properties are accessible from JavaScript. The only difference is that we need to use getter/setters instead of accessing the properties directly - bufferTime is exposed as getBufferTime() and setBufferTime(value).
At the same time we expose a method that can be used for registering for all the events that MediaPlayer dispatches.
You simply need to register for the event using the API that is already familiar to any OSMF or AS3 developer:
addEventListener(eventName, callback)
We also provide an utility function, named addEventListeners, which takes an object containing key-value pairs. This method should help in speeding up the configuration process.
Once the strobe StrobeMediaPlayback is loaded it will call onJavaScriptBridgeCreated javascript function. You need to use this callback function for starting the interaction with the player.

It's important to set the id and the name attribute of the embedded player. As a convention, we recommend using the same value for both of them.
Here is a restriction comming from the ExternalInterface reference documentation:
Note: When embedding SWF files within an HTML page, make sure that the id and name attributes of the object and embed tags do not include the following characters:

. - + * / \

http://www.adobe.com/livedocs/flash/9.0/ActionScriptLangRefV3/flash/external/ExternalInterface.html

HelloWorld Sample

The Hello World Sample (hello-world-javascript.html) will be updating the current video time and the the video duration in a HTML div.
At the same time it allows you to pause/resume the video.

Basic workflow:
1. Embed the player
2. Create a onJavaScriptBridgeCreated function
3. Retrieve a reference to the video player
4. Register event listeners
4. Check the state of the player and control the player in your event handlers.

Demo

This demo (jsdemo.html) demostrates most of the features of the JavaScript API, except metadata and the plugin interactions which will be provided as deliverables of a future feature.

Playlists - you can change dynamically the current video without reloading the HTML page
JavaScript ControlBar which mirrors the StrobeMediaPlayback control bar.
DynamicStreaming - manual switching widget. For a dynamic stream, a widget will become visible on the control bar. Once you click on it, you'll be able to switch between the bitrates or revert to automatic switching.
CloseCaptioning Interactice Widget + CloseCaptioning Overlay.

Notes:

All the javascript calls are asynchronous. This should prevent the player from waiting the response from the javascript side.
All the calls from javascript to StrobeMediaPlayback are synchronous. This is important, since the flow of the javascript code might depend on the result of a function call (for ex. if (player.getState() == "ready")).

Known Issues

- We don't provide utility javascript classes that contain literals. We can provide an external JS file for this - and a javascript dev will need to link to it. I think that most javascript devs will simply use literals directly, instead of linking to an external js file. And we don't need to maintain one more external file. We should reconsider this if we ever decide to provide a higher level API.
- We don't prevent the javascript API users from calling methods when the player is not in the required state. Calling a method in a wrong state might break the video playback (for ex. calling play before the player is ready will trigger a MediaError).
- We don't expose metadata related APIs. This will be our focus when providing support for javascript API.
- We didn't asses the performance implications of this.
- Displaying HTML overlays over the video is a performance

- Some JavaScript API users might be tempted into turning the wmode into "opaque" or "transparent" so that they can display HTML content over the StrobeMediaPlayback video content. This would be wrong from a perfromance perspective because flash 10.1 won't be able to use hardware acceleration for rendering the video. Flash Player 10.1 hardware rendering is automatically enabled on supported devices, and it's not necessary to add the wmode=gpu embed parameter to enable it. However, when working with Flash Player 10.1, the wmode=opaque or wmode=transparent embed parameters will disable hardware rendering, causing the software to render the graphics.