Controlling Flash Video with the External API

The following procedure shows you how to control Flash Video (FLV) files using controls in an HTML page and displays information about the video in an HTML text field. This procedure uses the External API to achieve this functionality.

To build a Flash application using the External API:

Create a new Flash document and save it as video.fla.

Add a new video symbol to the library by selecting New Video from the pop-up menu in the Library panel.

Drag the video symbol to the Stage and give it an instance name of selected_video.

Select the selected_video instance and then the Property inspector to resize the instance to 320 pixels wide by 240 pixels high.

Set both the x and y coordinates for the video's position to 0.

Select the Stage and use the Property inspector to resize its dimensions to 320 pixels by 240 pixels.

Now the Stage matches the dimensions of the video instance.

Add the following ActionScript to Frame 1 of the main Timeline:

import flash.external.ExternalInterface;

/* Register playVideo() and pauseResume() so that it is possible
to call them from JavaScript in the container HTML page. */
ExternalInterface.addCallback("playVideo", null, playVideo);
ExternalInterface.addCallback("pauseResume", null, pauseResume);

/* The video requires a NetConnection and NetStream object. */
var server_nc:NetConnection = new NetConnection();
server_nc.connect(null);
var video_ns:NetStream = new NetStream(server_nc);

/* Attach the NetStream object to the Video object on Stage so
that the NetStream data is displayed in the Video object. */
selected_video.attachVideo(video_ns);

/* The onStatus() method is called automatically when the status of
the NetStream object is updated (the video starts playing, for example).
When that occurs, send the value of the code property to the HTML page by
calling the JavaScript updateStatus() function via ExternalInterface. */
video_ns.onStatus = function(obj:Object):Void {
    ExternalInterface.call("updateStatus", "  " + obj.code);
};

function playVideo(url:String):Void {
    video_ns.play(url);
}

function pauseResume():Void {
    video_ns.pause();
}

The first part of this ActionScript code defines two ExternalInterface callback functions, playVideo() and pauseResume(). These functions are called from the JavaScript in the next procedure. The second part of the code creates a new NetConnection and NetStream object, which you use with the video instance to dynamically play back FLV files.

The code in the next procedure defines an onStatus event handler for the video_ns NetStream object. Whenever the NetStream object changes its status, Flash uses the ExternalInterface.call() method to trigger the custom JavaScript function, updateStatus(). The final two functions, playVideo() and pauseResume(), control the playback of the video instance on the Stage. Both of these functions are called from JavaScript written in the following procedure.

Save the Flash document.

Select File > Publish Settings and then select the Formats tab, and make sure that HTML and Flash are both selected.

Click Publish to publish the SWF and HTML files to your hard disk.

When you're finished, go on to the next procedure to create the container for the SWF file.

For a sample source file, external.fla, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download and decompress the Samples file and navigate to the ActionScript2.0/ExternalAPI folder to access the sample.

In the following procedure, you modify the HTML code generated by Flash in the previous procedure. This procedure creates the JavaScript and HTML required to make the FLV files play back within the SWF file.

To create the container for the SWF file:

Complete the previous procedure.

Open the video.html document that you published in the last step of the previous procedure.

Modify the existing code so that it matches the following code:

NOTE

Review the code comments in the following example. A code overview follows this code example.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>ExternalInterface</title>

<script language="JavaScript">
    // Use a variable to reference the embedded SWF file.
    var flashVideoPlayer;
    
    /* When the HTML page loads (through the onLoad event of the <body> tag), it calls the initialize() function. */
    function initialize() {
        /* Check whether the browser is IE. If so, flashVideoPlayer is
window.videoPlayer. Otherwise, it's document.videoPlayer. The
videoPlayer is the ID assigned to the <object> and <embed> tags. */
        var isIE = navigator.appName.indexOf("Microsoft") != -1;
        flashVideoPlayer = (isIE) ? window['videoPlayer'] : document['videoPlayer'];
    }

    /* When the user clicks the play button in the form, update the videoStatus text area, and call the playVideo() function within the SWF file, passing it the URL of the FLV file. */
    function callFlashPlayVideo() {
        var comboBox = document.forms['videoForm'].videos;
        var video = comboBox.options[comboBox.selectedIndex].value;
        updateStatus("____" + video + "____");
        flashVideoPlayer.playVideo("http://www.helpexamples.com/flash/video/" + video);
    }

    // Call the pauseResume() function within the SWF file.
    function callFlashPlayPauseVideo() {
        flashVideoPlayer.pauseResume();
    }

    /* The updateStatus() function is called from the SWF file from the onStatus() method of the NetStream object. */
    function updateStatus(message) {
        document.forms['videoForm'].videoStatus.value += message + "\n";
    }
</script>
</head>
<body bgcolor="#ffffff" onLoad="initialize();">

<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
    codebase="http://fpdownload.adobe.com/pub/shockwave/cabs/flash/swflash.cab#version=8,0,0,0" width="320" height="240" id="videoPlayer" align="middle">
<param name="allowScriptAccess" value="sameDomain" />
<param name="movie" value="video.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#ffffff" />
<embed src="video.swf" quality="high" bgcolor="#ffffff" width="320" height="240" name="videoPlayer" align="middle" allowScriptAccess="sameDomain" type="application/x-shockwave-flash" pluginspage="http://www.adobe.com/go/getflashplayer" />
</object>

<form name="videoForm">
    Select a video:<br />
    <select name="videos">
        <option value="lights_long.flv">lights_long.flv</option>
        <option value="clouds.flv">clouds.flv</option>
        <option value="typing_long.flv">typing_long.flv</option>
        <option value="water.flv">water.flv</option>
    </select>
    <input type="button" name="selectVideo" value="play" onClick="callFlashPlayVideo();" />
    <br /><br />

    Playback <input type="button" name="playPause" value="play/pause" onClick="callFlashPlayPauseVideo();" />

    <br /><br />
    Video status messages <br />
    <textarea name="videoStatus" cols="50" rows="10"></textarea>
</form>

</body>
</html>

This HTML code defines four JavaScript functions: initialize(), callFlashPlayVideo(), callFlashPlayPauseVideo(), and updateStatus(). The initialize() function is called within the body tag in the onLoad event. Both the callFlashPlayVideo() and callFlashPlayPauseVideo() functions are called when the user clicks on either the play button or play/pause button within the HTML document, and trigger the playVideo() and pauseResume() functions in the SWF file.

The final function, updateStatus(), gets called by the SWF file whenever the video_ns NetStream object's onStatus event handler is triggered. This HTML code also defines a form that has a combo box of videos that the user can choose from. Whenever the user selects a video and clicks the play button, the callFlashPlayVideo() JavaScript function is called, which then calls the playVideo() function within the SWF file. This function passes the URL of the SWF file to load into the video instance. As the video plays back and the NetStream object's status changes, the contents of the HTML text area on the Stage are updated.

Save your changes to the HTML document, and then upload both the HTML and SWF files to a website.

Open the remote video.html document from the website, select a video from the combo box, and click the play button.

Flash plays the selected FLV file and updates the contents of the videoStatus text area within the HTML document.

For more information on the External API, see ExternalInterface (flash.external.ExternalInterface) in the ActionScript 2.0 Language Reference.

NOTE

Avoid using other methods of accessing the plug-in object, such as document.getElementById("pluginName") or document.all.pluginName, because these other methods do not work consistently across all browsers.

Flash CS3