Captions Chapter 12: Video 349 Providing Captions in Multiple Languages Feature-rich DVD titles frequently have multiple caption programs available, each in a different language. This broadens the reach of the title across cul- tures and supports a wider audience with accessibility needs. It’s possible to achieve the same thing using the FLVPlaybackCaptioning component. All you need to do is prepare multiple Timed Text files, one for each lan- guage, and switch among them when needed. Off the shelf, however, the FLVPlaybackCaptioning component does a couple of things that make this an odd experience. First, if you change the caption content between times specified in a Timed Text document, the component will overwrite the caption field only if the current caption is empty or contains only white space (tab, return, or space). If that’s not the case (such as when switching captions from one language to another at any moment), it adds the new text to the existing caption. Only when the next Timed Text caption time comes along will the field contents be replaced cor- rectly. Second, the method it uses to determine whether or not the Timed Text file has already been loaded results in no immediate change. Therefore, you must wait for the next caption to come along to see a language update. Fortunately, there’s an easy workaround. All you have to do is turn off caption display before making the caption source switch, and then turn the display back on again. The example file, video_comp_skin_full_captions_multilingual.fla, demonstrates this using the Button component to toggle the caption source files. 15 import fl.controls.Button; 16 var capsLangBtn:Button = new Button(); 17 capsLangBtn.label = "English/Spanish"; 18 capsLangBtn.x = vid.x + vid.width + 20; 19 capsLangBtn.y = vid.y + vid.height; 20 addChild(capsLangBtn); 21 capsLangBtn.addEventListener(MouseEvent.CLICK, switchTTCaps, 22 false, 0, true); 23 24 function switchTTCaps(evt:MouseEvent):void { 25 cap.showCaptions = false; 26 if (cap.source == "nero_timed_text.xml") { 27 cap.source = "nero_timed_text_sp.xml"; 28 } else { 29 cap.source = "nero_timed_text.xml"; 30 } 31 cap.showCaptions = true; 32 } Line 15 imports the Button class so we can instantiate the Button in line 16. Lines 17 through 20 set the buttons label, position it next to the lower-right corner of the FLVPlayback component, and add it to the display list. Lines 21 and 22 add an event listener to call the switchTTCaps() function upon each mouse click event. Finally, the switchTTCaps() function (lines 24 through 32) turns off caption display, checks to see which caption source is in use and switches to the other file, and then turns caption display back on again. N O T E As with the FLVPlayback and FLVPlaybackCaptioning components, you must have this component, found in the User Interface category of the Components panel, in your library. Download from Wow! eBook <www.wowebook.com> Part IV: Sound and Video 350 Writing Your Own Player Writing Your Own Player Wrapping up the chapter, we want to introduce you to some of the ActionScript required to create a customized player. We’ll start with coding your own controls for the FLVPlayback component, to give you freedom to design your own controller bar. Then we’ll show you how to write your own player to eliminate reliance on the FLVPlayback component altogether. In both cases, we’ll create play, pause, and stop buttons using the RoundRectButton class discussed in Chapter 8. While not a fully functional controller, this will give you the foundation necessary to set properties and call methods in the FLVPlayback and NetStream classes. You can then decide which features you want to implement in your custom controllers. Scripting Buttons to Control the FLVPlayback Component This exercise, found in the video_comp_custom_buttons.fla source file, builds on the first example in the chapter. That example showed that you can use the FLVPlayback component without having to use a skin. This exercise will add custom buttons to the file to control video playback. Lines 1 and 2 import the FLVPlayback and RoundRectButton classes. Lines 4 through 7 initialize the FLVPlayback component, as previously discussed. In this exercise, however, we’ve added line 6 to set the autoPlay property to false. This will prevent the video from playing automatically and let the user choose when to play it. Lines 9 through 24 create three buttons using the RoundRectButton class. The class was introduced in Chapter 8, and we’ve used this technique in several chapters. Briefly, a function is used to create an instance of the class, as well as position the button and assign a function to the event listener. This approach is designed to minimize the number of lines required to create the buttons, and it can be customized to fit your needs. We’ll discuss the functions that control the video after the code. 1 import fl.video.FLVPlayback; 2 import com.learningactionscript3.ui.RoundRectButton; 3 4 var vid:FLVPlayback = new FLVPlayback(); 5 vid.source = "nero.flv"; 6 vid.autoPlay = false; 7 addChild(vid); 8 9 createButton(50, "Play", playVideo); 10 createButton(130, "Pause", pauseVideo); 11 createButton(210, "Stop", stopVideo); 12 createButton(240, "Full Screen", fullScreenVideo); 13 14 function createButton(xLoc:Number, labl:String, 15 func:Function):void { 16 var btn:RoundRectButton = Download from Wow! eBook <www.wowebook.com> Writing Your Own Player Chapter 12: Video 351 17 new RoundRectButton(60, 20, 10, 2, 0x000099, 18 labl, 0xFFFFFF); 19 btn.x = xLoc; 20 btn.y = 240; 21 btn.addEventListener(MouseEvent.CLICK, func, 22 false, 0, true); 23 addChild(btn); 24 } 25 26 function playVideo(evt:MouseEvent):void { 27 vid.play(); 28 } 29 30 function pauseVideo(evt:MouseEvent):void { 31 vid.pause(); 32 } 33 34 function stopVideo(evt:MouseEvent):void { 35 vid.stop(); 36 vid.seek(0); 37 } 38 39 function fullScreenVideo(evt:MouseEvent):void { 40 stage.displayState = StageDisplayState.FULL_SCREEN; 41 } Lines 26 through 41 contain the functions used to control the video. The functions and methods used are self-explanatory, with two exceptions. First, in addition to stopping the video in the stopVideo() function, we also use the seek() method to seek through the video to a specific point in time. Seeking to 0 returns the video to its starting point. This is a user-experience consideration that differentiates the functionality of the pause and stop but- tons. Second, to switch to full screen, you set the displayState property of the stage to StageDisplayState.FULL_SCREEN. By default, changing the stage’s display state to full screen mode when an FLVPlayback component is in use mimics the behavior of the component. The video will fill the screen and show only the video regardless of any other user interface elements. In this case, however, we’re not using a skin that’s designed to show the controller on top of the video. As a result, the control buttons disappear. To show the control buttons, you can prevent the video from taking over the stage after resizing by setting the fullScreenTakeOver property of the FVLPlayback instance to false. One side effect of this is that you can then see the Full Screen button and it won’t do anything because the display state will already be in full screen mode. So, you can write a simple if statement that will toggle between the dis- play states as needed. The script below replaces the fullScreenVideo() function in the previous example and appears in the video_comp_custom_buttons_full.fla source file. 39 vid.fullScreenTakeOver = false; 40 function fullScreenVideo(evt:MouseEvent):void { 41 if (stage.displayState == StageDisplayState.NORMAL) { 42 stage.displayState = StageDisplayState.FULL_SCREEN; Download from Wow! eBook <www.wowebook.com> Part IV: Sound and Video 352 Writing Your Own Player 43 } else { 44 stage.displayState = StageDisplayState.NORMAL; 45 } 46 } Finally, you can even control how much of the stage is visible in full screen mode by setting the stage’s fullScreenSourceRect property to a rectangular area. The following line is included in the video_comp_custom_buttons_full.fla source file, and specifies a rectangle that encloses the video and buttons. stage.fullScreenSourceRect = new Rectangle(0, 0, 320, 270); This line is initially commented out in the source file, so you publish to HTML multiple times and comment this line in and out to see its effect. A Code-Only Solution Up to this point, we’ve relied on components for video display. Creating your own player exclusively with ActionScript can reduce file size and allow you to customize functionality. In this exercise, you’ll write a class called BasicVideo to create a simple video player that does not use the FLVPlayback component. As a result, the generated SWF file is less than 4K. If you want to preview this exercise before going over the code, it uses a document class called BasicVideo_UI in the main directory of the chapter source archive. Flash Professional users can open the code_only_player.fla source file, which already makes use of this class. BasicVideo is in the com. learn ingactionscript3.video package. We’ll discuss BasicVideo first, and then talk about the document class that creates the user interface. The main video class Line 1 declares the package, and lines 3 through 9 import the required classes. Line 11 declares the class and extends MovieClip so we can use its accessible properties, methods, and events of that class. Lines 13 through 17 declare pri- vate class properties—available throughout the class. 1 package com.learningactionscript3.video { 2 3 import flash.display.MovieClip; 4 import flash.events.AsyncErrorEvent; 5 import flash.events.MouseEvent; 6 import flash.events.NetStatusEvent; 7 import flash.net.NetConnection; 8 import flash.net.NetStream; 9 import flash.media.Video; 10 11 public class BasicVideo extends MovieClip { 12 13 private var _conn:NetConnection; 14 private var _stream:NetStream; 15 private var _vid:Video; 16 private var _vidPlaying:Boolean; 17 private var _source:String; Download from Wow! eBook <www.wowebook.com> Writing Your Own Player Chapter 12: Video 353 Lines 19 through 36 contain the class constructor. It accepts one string parameter for the video path to allow you to select a video when instantiating the class. Later, we’ll add a getter and setter to let you to do this by setting a property instead. Lines 22 through 24 use the two main classes required to play videos with ActionScript. Line 22 creates an instance of the NetConnection class, which establishes a bi-directional connection between the user’s player and a server delivering data, such as a video streaming server. It’s a bit like the cable run- ning between your house and the cable television company. You connect to the server using the connect() method in line 23. In this example, however, we’re not using a server, so we’ll pass null into this method. In this case, the class is designed to connect to a local file. Line 24 creates an instance of the NetStream class and is associated with the NetConnection instance by passing the latter into the former’s constructor. A NetStream instance is a channel of a NetConnection instance, a little like a single cable channel, and transmits data in one direction. For example, a server can send data and a client can receive data. Line 26 creates an instance of the Video class, which is the display object used to show the video. This is a bit like a television set. The NetStream instance is then attached to the video in line 27, a little like picking the cable channel you want to watch. Line 28 adds the video instance to the main class instance so it can become part of the display list. Lines 30 through 33 create a custom object that will serve as a data client for the class. Select data will automatically be sent out when playing the video and if this object (or a similar object like a custom class created for the same purpose) does not exist, errors will occur. For example, any metadata that exists in the video, either by default or that was added during encoding, will be sent soon after the video begins loading. Similarly, any cue points that were embedded in the video will be sent when encountered. Lines 31 and 32 assign the onMetaData() and onCuePoint() methods to their corresponding properties so Flash Player knows where to send the appropriate information. This association is formalized when the object is assigned to the client prop- erty of the NetStream instance in line 33. Finally, event listeners are added to the class in line 35, which we will talk about after the code block. 18 //constructor 19 public function BasicVideo(path:String="") { 20 _source = path; 21 22 _conn = new NetConnection(); 23 _conn.connect(null); 24 _stream = new NetStream(_conn); 25 26 _vid = new Video(); 27 _vid.attachNetStream(_stream); 28 addChild(_vid); 29 30 var _infoClient:Object = new Object(); Download from Wow! eBook <www.wowebook.com> Part IV: Sound and Video 354 Writing Your Own Player 31 _infoClient.onMetaData = this.onMetaData; 32 _infoClient.onCuePoint = this.onCuePoint; 33 _stream.client = _infoClient; 34 35 addEventListeners(); 36 } Lines 38 through 47 add two event listeners each to the NetConnection and NetStream instances. The NET_STATUS event is dispatched when status updates become available from either instance. Similarly, the ASYNC_ERROR event is dispatched when an asynchronous error occurs in either instance. An asyn- chronous error is an error that’s not dependent on a specific (synchronized) order of execution. That is, it need not be the sequential result of another task performed by the class. This event is typically dispatched when a server calls a method that’s not defined in the client. When either event is received, the methods in lines 49 through 60 are called. Both trace information so you can see what’s going on, but onNetStatus() also toggles the value of the _vidPlaying property. When a status update indi- cates that the video has started, the _vidPlaying property is set to true. When the status indicates that the video has stopped it sets the property to false. 37 //event listeners 38 private function addEventListeners():void { 39 _conn.addEventListener(NetStatusEvent.NET_STATUS, 40 onNetStatus,false,0,true); 41 _conn.addEventListener(AsyncErrorEvent.ASYNC_ERROR, 42 onAsyncError,false,0,true); 43 _stream.addEventListener(NetStatusEvent.NET_STATUS, 44 onNetStatus,false,0,true); 45 _stream.addEventListener(AsyncErrorEvent.ASYNC_ERROR, 46 onAsyncError,false,0,true); 47 } 48 49 private function onAsyncError(evt:AsyncErrorEvent):void { 50 trace(evt.text); 51 } 52 53 private function onNetStatus(evt:NetStatusEvent):void { 54 trace(evt.info.level + ": " + evt.info.code); 55 if (evt.info.code == "NetStream.Play.Start") { 56 _vidPlaying = true; 57 } else if (evt.info.code == "NetStream.Play.Stop") { 58 _vidPlaying = false; 59 } 60 } Lines 62 through 74 contain the methods triggered by the metadata and cue points received during video playback. Line 63 traces the duration metadata field to demonstrate reacting to incoming information. You can add metadata during the encoding process, and encoding software can also automatically create metadata for you. Available metadata fields range from such basic items as duration, creation and modified date, width, height, and so on, to the highly specialized, like the DICOM collection of medical fields, depending on the Download from Wow! eBook <www.wowebook.com> Writing Your Own Player Chapter 12: Video 355 encoder. Adobe Media Encoder supports an impressive array of available metadata. Lines 67 through 69 trace the time, name, and type properties of any cue point received, and lines 70 through 73 trace any parameters added to that cue point when it was created. 61 //client methods 62 private function onMetaData(info:Object):void { 63 trace("MetaData duration:", info.duration); 64 } 65 66 private function onCuePoint(info:Object):void { 67 trace("CuePoint time:", info.time); 68 trace("CuePoint type:", info.type); 69 trace("CuePoint name:", info.name); 70 for (var prop in info.parameters) { 71 trace("Cue point parameter " + prop + ": " + 72 info.parameters[prop]); 73 } 74 } Finally, lines 76 through 101 contain the public methods, getters, and setters available outside the class. Lines 76 through 93 contain methods to play, pause, and stop the video, all of which are configured to receive mouse events. However, they also all include default values for the event, making it possible to call the methods directly, rather than as a result of an event. We’ll see this demonstrated in the main document class. The playVideo() method in lines 76 through 83 first checks to see if the _vid- Playing property is true. If so, it calls the resume() method of the NetStream instance. This is because the class changes this property value when a status event indicates that the stream has been started or stopped, but not paused. Therefore, if a play button is clicked and the property is true, the video has been paused and should be resumed. If the property is false, the play() method is called, using the path in the _source property to indicate which video to play. In either case, the _vidPlaying property is set to true to record the fact that the video is playing. The pauseVideo() method in lines 85 through 87 calls the togglePause() method. This is a nice feature because it will automatically pause the video if it’s playing and play the video if it’s paused. Lines 89 through 93 contain the stopVideo() method. This method closes the stream (which is a bit like turning off your cable set top box), clears the Video instance (which is akin to turning off your television), and sets the _vidPlaying property to false. Finally, lines 95 through 101 provide a getter and setter to allow the retrieval and assignment of the _source property from outside the class. 75 //public player methods and getter/setter 76 public function playVideo(evt:MouseEvent=null):void { 77 if (_vidPlaying) { 78 _stream.resume(); N O T E For more information about getters and setters, see the “Encapsulation” section of Chapter 6. Download from Wow! eBook <www.wowebook.com> Part IV: Sound and Video 356 Writing Your Own Player 79 } else { 80 _stream.play(_source); 81 } 82 _vidPlaying = true; 83 } 84 85 public function pauseVideo(evt:MouseEvent=null):void { 86 _stream.togglePause(); 87 } 88 89 public function stopVideo(evt:MouseEvent=null):void { 90 _stream.close(); 91 _vid.clear(); 92 _vidPlaying = false; 93 } 94 95 public function set source(path:String):void { 96 _source = path; 97 } 98 99 public function get source():String { 100 return _source; 101 } 102 } 103 } The document class The BasicVideo_UI class is a document class that instantiates BasicVideo and creates a simple interface with a play, pause, and stop button. Lines 1 through 7 declare the package and import the required classes. Lines 9 through 12 declare the class (which extends MovieClip so it can easily function as a document class) and declare two private properties. The first is a movie clip container to hold the video and buttons, so you can easily position the video interface anywhere on the stage. The second stores a reference to the BasicVideo instance so it can be used throughout the class. Lines 14 through 27 contain the class constructor. Lines 15 through 17 create a container to hold the video and buttons, but also use the drawBackground() method (lines 29 through 36) to draw a black background the size of the video into the container. This is so, when clearing the video object after stop- ping playback, the video doesn’t look like it’s disappearing. (The function simply creates a movie clip, draws a black rectangle into it, and returns it to the point in the script where the function was called.) Lines 19 through 21 create an instance of the BasicVideo class, assign the source property of the instance to the appropriate video path, and add the BasicVideo instance to the container. Line 22 demonstrates how to call the BasicVideo public method playVideo() directly, rather than from an event. This means you can automatically start the video playing without requiring a mouse click from the user. The remainder of the class creates three buttons and assigns a listener to each to control the video, just like we did in the “Scripting Buttons to Control Download from Wow! eBook <www.wowebook.com> Writing Your Own Player Chapter 12: Video 357 the FLVPlayback Component” section of this chapter. The only difference between the two examples is that listeners in this class call the methods in the BasicVideo class, while the previously cited example called methods of the FLVPlayback component. 1 package { 2 3 import flash.display.Graphics; 4 import flash.display.MovieClip; 5 import flash.events.MouseEvent; 6 import com.learningactionscript3.ui.RoundRectButton; 7 import com.learningactionscript3.video.BasicVideo; 8 9 public class BasicVideo_UI extends MovieClip { 10 11 private var _container:MovieClip; 12 private var _vidPlayer:BasicVideo; 13 14 public function BasicVideo_UI() { 15 _container = drawBackground(); 16 _container.x = _container.y = 20; 17 addChild(_container); 18 19 _vidPlayer = new BasicVideo(); 20 _vidPlayer.source = "nero.flv"; 21 _container.addChild(_vidPlayer); 22 _vidPlayer.playVideo(); 23 24 createButton(20, "Play", playVideo); 25 createButton(120, "Pause", pauseVideo); 26 createButton(220, "Stop", stopVideo); 27 } 28 29 private function drawBackground():MovieClip { 30 var sp:MovieClip = new MovieClip(); 31 var g:Graphics = sp.graphics; 32 g.beginFill(0x000000); 33 g.drawRect(0, 0, 320, 240); 34 g.endFill(); 35 return sp; 36 } 37 38 private function createButton(xLoc:Number, labl:String, 39 func:Function):void { 40 var btn:RoundRectButton = 41 new RoundRectButton(80, 20, 10, 2, 0x000099, 42 labl, 0xFFFFFF); 43 btn.x = xLoc; 44 btn.y = 250; 45 btn.addEventListener(MouseEvent.CLICK, func, 46 false, 0, true); 47 _container.addChild(btn); 48 } 49 50 private function playVideo(evt:MouseEvent=null):void { 51 _vidPlayer.playVideo(); 52 } 53 54 private function pauseVideo(evt:MouseEvent=null):void { Download from Wow! eBook <www.wowebook.com> Part IV: Sound and Video 358 What’s Next? 55 _vidPlayer.pauseVideo(); 56 } 57 58 private function stopVideo(evt:MouseEvent=null):void { 59 _vidPlayer.stopVideo(); 60 } 61 } 62 } Although this exercise doesn’t create a full-featured video controller, it demonstrates the basics required to create the remaining functionality on your own, with help from the ActionScript 3.0 Language and Component Reference. Having completed this exercise, try to build a progress bar or a seek option. Try to combine what you’ve learned here with what you learned in Chapter 11 and create a volume or mute button. How you design your controller is up to you. What’s Next? This chapter discussed a few ways to add video features to your projects. You can now decide, typically on a project-by-project basis, whether to use prebuilt components, or your own custom ActionScript player. You also have the ability to add full screen support and captions, if your project calls for these features. In the next chapter, we’ll begin Part V of book, covering input and output. Chapter 13 discusses the basics of loading external assets, including: • Using the universal URLRequest class • Loading visual assets, including graphics and other SWF files • Loading text and variables Project Package This chapter’s contribution to the learningactionscript3 package is the BasicVideo class. With this class, you can add a video display to any project and be free to customize the access controls to fit any design. Download from Wow! eBook <www.wowebook.com> . sp.graphics; 32 g.beginFill(0x 000 000 ); 33 g.drawRect (0, 0, 32 0, 2 40) ; 34 g.endFill(); 35 return sp; 36 } 37 38 private function createButton(xLoc:Number, labl:String, 39 func:Function):void { 40 var. "Pause", pauseVideo); 26 createButton(2 20, "Stop", stopVideo); 27 } 28 29 private function drawBackground():MovieClip { 30 var sp:MovieClip = new MovieClip(); 31 var g:Graphics = sp.graphics; 32 . function playVideo(evt:MouseEvent):void { 27 vid.play(); 28 } 29 30 function pauseVideo(evt:MouseEvent):void { 31 vid.pause(); 32 } 33 34 function stopVideo(evt:MouseEvent):void { 35 vid.stop(); 36