Learn how to use the video.Maru API to create a comboBox navigation.

Use the video.Maru API to change the linkBTN text color when the btn is pressed.

Important: when accessing the video.Maru API you are targeting the SWC that you have placed in your FLA. You do not need to give the SWC an instance name because it does that for itself. That instance name is videoMaru.

The cornerstone to the video.Maru API is the videoMaruCreationComplete function. That is a function that you write and video.Maru will call that function for you when it has finished setting up the video interface.

The videoMaruCreationComplete function is where you’ll place code that is there to set or override certain properties of video.Maru. If for instance you wanted to change the size of the videoWindow on startup to reflect the dimensions reported by the FLV metaData then you’ll have to wait until the video.Maru code gets far enough that it knows what the videoWindow is. You can see a code sample of this below under getVideoMetaHeight.

It’s a good practice to place your videoMaruCreationComplete function on the same layer as the video.Maru SWC.

closeNetstream() ( beta )
Closing the Netstream object halts the download of the video stream and stops playback. When you click on a videoLink it will create a new Netstream and begin playback.

formatTime( s:String ):String
Takes a String that indicates a duration of time and returns a properly formated hour:minute:second display. Note: the reason it takes a String and not a Number is that the video metaData returns a String for the duration. Example: if you pass formatTime( 125 ) it will return 2:05.

getCurrentFLV():String
If you need to know what the current path/fileName.flv then use this. It would be handy if for instance you wanted to give someone the option to download the FLV to their system.

getIsPlaying():Boolean
Returns a true/false regarding the current state of playback. Usage: you might use this in an onEnterFrame if you want to track the current state of the playback so that when the video is not playing you could do something bandwidth intensive.

getLinkButtonArray():Array
Returns an array of all the linkBTNs corresponding to the videos listed in an XML file. Usage: you can loop through the array and add a number to the beginning of each linkBTN.link TextField. Or you could use it to change the appearance of a linkBTN after the user has played that video.

getVideoMetaHeight():Number
Returns the height of the video that is currently playing as reported by the metaData in the FLV. You cannot depend on this value being available in all cases. The Flash video encoder does add this metaData but not all encoders do. For instance the youTube videos that I have checked do not report the width/height in the metaData.

The code sample below will resize the videoWindow to fit the actual size of the FLV each time the video changes. If there is no width/height embedded in the metaData then it defaults to 320×240.

Note: there is a bit of a delay from the video starting to the resize. That’s caused by the delay in the Flash player reading the metaData. I don’t know of anything that can be done about that. Other than including the width/height in your XML file and getting the data from that. But that’s another project.

playVideo(s:String):Void
Send a path/filename.flv to this function and it will play that FLV, if it can be loaded.

setFadeTrayDuration(n:Number):Void
The fadeTray takes 1.5 seconds to fade in and out. If you would like to change that then pass in the number of seconds you would like to change it to. As an example if you wanted it to take 3 seconds to fade in and out then use this:

video.Maru.setFadeTrayDuration(3);

setFullScreenCallback(fn:Function):Void
description

setIsPlaying(b:Boolean):Void
You can bypass the play_btn/pause_btn with your own control by calling this function and passing the state of isPlaying. To pause the video call:

videoMaru.setIsPlaying(false);

This is especially useful if you want to have two separate buttons for the play and the pause. With the video.Maru interface that is not possible. You’ll have to create a button for each state - but don’t give them instance names of play_btn or pause_btn.

Here is some sample code for two buttons placed on the same layer as the video.Maru SWC

setLinkBtnPressed( fn:Function ):Void
Get notified when the user clicks on a linkBTN. Usage: you could use this to change the state of the button when pressed and then switch it back when released with setLinkBtnReleased().

setLinkBtnReleased( fn:Function ):Void
Get notified when the user clicks and releases on a linkBTN. Usage: you could use this to change the state of the button when pressed with setLinkBtnPressed() and then switch it back when released.

setMetaDataChangedCallback(fn:Function):Void
When the Flash player detects a change in the FLV metaData this function that you specify will be called. You can see an example of this under getVideoMetaHeight() above.

setMute(b:boolean):Void
Set the volume mute state: true/false.

setOnCuePoint( fn:Function ):Void
Set the callback function that is called when a cue point in your video is reached. You can read more about it here. Download the example.

setOnVideoComplete(fn:Function):Void
Set the callback function that is called when a video completes playing. See example.

setSmoothing(b:Boolean):Boolean
Turn smoothing on or off. Smoothing determines whether the video should be smoothed (interpolated) when it is scaled. For smoothing to work, the player must be in high-quality mode. The default value is false (no smoothing).

setVideoChangeCallback(fn:Function):Void
If set calls the function you specify when the FLV playing in the videoWindow is changed.

setVideoWindowHeight(n:Number):Void
Change the height of the videoWindow. See getVideoMetaHeight() above for an example.

setVideoWindowWidth(n:Number):Void
Change the width of the videoWindow. See getVideoMetaHeight() above for an example.

setVideoWindowX(n:Number):Void
Change the _x value of the videoWindow.

setVideoWindowY(n:Number):Void
Change the _y value of the videoWindow.

setXmlCallback(fn:Function):Void
Set a function to be called when the XML has been parsed into an object. The callback that you set needs to accept an argument of type Object. See below for an example.

toggleFullScreenVideo():Void
Toggles the fullScreen between fullScreen and in-browser views.

togglePlayPause():Void
Toggles the video playback between paused and playing. It will also change the state of your play_btn/pause_btn if available.

The XML documentation is broken up into two sections. Those attributes associated with the <video> nodes and those attributes associated with the <settings /> node.

Note: the capitalization of these attributes does matter. As opposed to the instance names of the elements of the video interface which do not.

<video>

path=”path/fileName.flv”
The path to the FLV that you would like to play. This can be a relative path to an FLV on the same server or a full HTTP address. If you would like to stream a video for youTube use: youtube=IDnumber.

captions=”path/fileName.xml”
The path to the captions data, if any. The data in this XML file will populate the captions TextField based on the time indexing.

videoTitle=”text goes in the videoTitle TextField”
Text that will populate the videoTitle TextField.

iconSrc=”path/fileName.png”
The path to the graphic that you would like to display in the linkIcon inside the linkBTN that is attached at runtime.

iconWidth=”number”
iconHeight=”number”
Override the intrinsic width/height of the graphic loaded into the linkIcon.

autoPlayNext=”true/false”
Automatically starts playing the next video. If currently playing the last video it will wrap around and begin playing the first video.

showStartPlay=”true/false” ( video.Maru 3.0 addition )
Display the startPlay MovieClip. Autoplay must be set to false for this to work. And the startPlay MovieClip must have been on the stage at authoring time.

loopVideo=”true/false”
Play the current video again.

autoPlayVideo=”true/false”
Determines if the video should be playing - true - or paused - false - on startup

btnX=”number”
btnY=”number”
The x,y coordinates of the associated linkBTN for this video node. The position will be from the registration of the _parent MovieClip or, if it exists, the linkBTNholder.

If you only supply the btnX, btnY value for the first <video> node then all the other buttons will stack vertically with a gap of 2 pixels between each.

linkText=”Text on the linkBTN”
The text that goes on the associated linkBTN.

description
The description is not an attribute. It is the value of the node. The text should be placed between the <video>description text</video> tags.

If you want to display HTML code in the description TextField then use CDATA, as such: <![CDATA[<b>description</b> of the video that goes in the description TextField]]>
description

<settings/>

buttonsX=”number”
Set the x-coordinate for all the linkBTNs.

buttonsY=”number”
Set the y-coordinate for all the linkBTNs.

prevButtonX=”number”
prevButtonY=”number”
The x,y coordinate of the prev button when it is attached at runtime. If no value is given then it will stack under the last linkBTN.

nextButtonX=”number”
nextButtonY=”number”
The x,y coordinate of the next button when it is attached at runtime. If no value is given then it will be placed at the same y-value and just to the right of the prev button.

verticalButtonPadding=”number”
The number of pixels between the linkBTNs if they are stacked vertically.

horizontalButtonPadding=”number”
The number of pixels between the linkBTNs if they are placed horizontally.

Below is a sample XML with all of the available attributes.

If you liked the first video tutorial on XML with video.Maru then you’re gonna love this one.

Note: this takes off where the previous page/tutorial - XML Basics - left off.

If you would like to spruce up your linkIcon with a little icon or thumbnail of the video then you can add a MovieClip to your linkBTN with an instance name of linkIcon. To describe the image/swf to load into that linkIcon go over to your XML and add an attribute to the video node in question like this: iconsrc=”folder/path.png”

That image/swf will then get loaded into the corresponding linkBTN. The size element that gets loaded will default to it’s native size. If you would like to resize it then add the attributes: iconWidth/iconHeight to the node in question.

You’ll notice that the loaded element is always centered inside the linkIcon MovieClip.

Titles and descriptions

video.Maru makes it very easy to display the title of the video and also a description of the currently playing video. Simply create a TextField with an instance name of videoTitle and then add a corresponding attribute to the <video> node in the XML of videoTitle=”someString”.

The description works just the same except the value in the XML for that TextField is the value of the corresponding <video> node. Below is an example of how that works.

Notice that the second node value uses CDATA. That’s a special way of embedding HTML code inside of XML. You can use any of the standard HTML tags that the Flash TextFields support.

This is just an overview of some of the XML support in video.Maru. Check out the complete XML documentation page for all the details.

Watch video tutorial on XML basics with video.Maru 2.0

The XML support in video.Maru is extensive and supports many options. Fortunately most cases will only need to use the basics of XML support.

If you want to enable your users to select from a series of videos, much like you would with using videoLink MovieClips, but you want the list to be dynamic, or at least external to the FLA, then XML is the way to go.

Start by pointing the videoWindow at your XML file, just as you would an FLV. That will cue the video.Maru code to load and parse the XML for use. The XML file can be named anything you wish. What’s important is to get the nodes and attributes correct.

Basic XML structure

That by itself will work.

If all you wanted to do was play a series of videos, one after another you could list them as such:

That would play through those three videos, or more if you added nodes, one after another. It would then loop back to the first video and start over - unless you removed the autoPlayNext=”true” from the last node. Then it would end on the third video.

If you would like video.Maru to create links, like the videoLinks MovieClips, for each FLV in your XML file then you will have to create a MovieClip that is the shell of a button and then give it a Linkage Identifier and export it for Actionscript. Here’s the details.

Create a MovieClip. Inside the MovieClip there should be a dynamic TextField with an instance name of link. There is a corresponding XML attribute named linkText that will populate that field.

In the Library right-click on the MovieClip you just created and select the checkbox Export for Actionscript. The Identifier must be linkBTN.

(Note: you do not need to have this MovieClip on the stage. The video.Maru code will attach this MovieClip at Runtime.)

You can also include an icon in your linkBTN. To do so create a MovieClip inside your linkBTN with an instance name of linkIcon. The corresponding XML attribute is iconsrc=”folder/fileName.png”. The icon can be a .jpg, .gif, .png or .swf.

The icon will be placed at the same x,y coordinates as the linkIcon MovieClip. However, the size of the icon will be whatever size the image or swf happens to be. If you would like to override the native size of the icon then add the iconWidth=”value” and iconHeight=”value” attributes.

Now you will want to describe how video.Maru should place these buttons in your video interface. There are many options for this. The easiest is to give each button an (x,y) coordinate. To do that add the attributes btnX=”value” and btnY=”value”. You would do that for each node.

So far an XML node with everything covered up to now would look like this:

But wait, there’s more

The main problem with placing the linkBTNs with the btnX, btnY combination is that if you want to place them somewhere else you’ll have to update all these attributes. Or if you changed the height of the linkBTNs they may start to overlap. Fortunately there are solutions for these issues.

You can create a <settings> node in the XML to describe how to layout your buttons. So if you wanted to create a vertical stack of buttons, all with the same x_position and a 4 pixel gap between each linkBTN then you would have XML as such:

This will place all your buttons 10 pixels from the left edge of the Stage and stack them with a 4 pixel gap.

I know what you’re saying, “That great but it’s hard to design a video layout when I can’t see where my buttons are going to be until I publish the movie. That’s where the linkBTNholder MovieClip comes in.

If you create a MovieClip with the instance name linkBTNholder then your linkBTNs will be placed inside of that MovieClip. Now you can just move your linkBTNholder around in the authoring tool as you wish. Don’t forget to change the buttonsX=”num” in the <settings> node. That attribute still works but now it places the buttons 10 pixels from the left edge of the linkBTNholder MovieClip.

What’s next, or previous?

Just like the videoLink buttons the linkBTNs support the next and prev buttons. First, you have to create your buttons just like you did with the linkBTN. You’ll need to enable the Export for Actionscript for the next and previous buttons and their Linkage Identifiers are nextBTN and prevBTN.

In the <settings> node you can add attributes to describe where the buttons should be placed. If you wanted to place the prevBTN 200 pixels from left and 300 pixels from the top, and have your nextBTN 50 pixels to the right, then your XML would look like this:

Going Deep

You’ll also want to take a look at the deepLink functionality if you want to start playing a video other than the the one in the first node.

The whole story

Take a look at the XML documentation to get a complete list of all the functionality and attributes.

Watch a video tutorial on creating a fadeTray.

The fadeTray is a MovieClip that you create to put whatever interface elements you want into so that they will fade out when the user doesn’t move their mouse after a specified period of time.

To use one make a MovieClip and give it an instance name of fadeTray#. The # indicates to video.Maru how long you want to wait after the user stops moving their mouse before the fadeTray begins to fade out.

For example, if you gave an instance name of fadeTray4. Then the mouse would have to remain motionless for 4 seconds before your fadeTray began to fade out.

Note: video.Maru will ignore mouse movements of less than 2 pixels per second. This way if the user just giggles the mouse a tiny bit they won’t be distracted by the fadeTray fading back in. This is what we call, “attention to user experience.” Why? Because I care.

By default it takes 1.5 seconds for the fadeTray to completely fade. The only way to change this value is with the video.Maru API.

Keeping the fadeTray on top

The nice thing about a fade tray is that you can put the user controls on top of the video. The problem lies with the fact that the MovieClip that you define as the videoWindow gets dynamically replaced at runtime. That means that the depth of the videoWindow will be on top of anything else on it’s layer regardless of how you stack things.

There is a very simple solution to this. Place your fadeTray on a layer above the videoWindow. Now select the videoWindow and hit F8 to convert it to a MovieClip. It doesn’t matter what you name the Symbol or what, if any, instance name you give to this MovieClip. All that matters is that now the videoWindow is embedded in a MovieClip. Now when it gets replaced at runtime it will stay under your fadeTray. This is all just part of the magic of depths in Flash.

Watch a video tutorial on how to integrate video.Maru with FlashVars for dynamic video interfaces.

FlashVars is a way of passing data from the HTML host page into Flash via the <object><embed> tags. You can read more about FlashVars at the Adobe site.

You can use Flash vars in two ways with video.Maru.

• flvAddress=someString
• xmlIndex=someNumber
  

In the first case if you pass flvAddress=someValue to your SWF then that will replace whatever, if anything, is the target path in the videoWindow. This way you can create one video interface that can then load any video you wish without republishing your FLA.

If you haven’t used FlashVars before it’s common to use them in conjunction with server side scripting languages so that ultimately the data that you pass into Flash originated from a database.

The second case you can can use FlashVars to tell it which node in the XML to start playing on startup.

You can also use the two cases together so that you pass both the path to the XML file to load and which node to first start playing.

If you are using the HTML/JavaScript code generated by the Flash authoring tool to publish your SWFs then you would add a line such as the one below to tell your video.Maru video player to load the following FLV: http://polygeek.com/polyGeekTV/videos/water.flv

‘flashvars’, ‘flvAddress=http://polygeek.com/polyGeekTV/videos/water.flv’,

The full code would look something like the sample below.

If you would like to load an XML file and also point to a specific node of the XML at startup then your code would look something like this:

If you use SWFobject then your code would look something like this:

And as a last example. If you have a Wordpress blog and you use the Kimili plugin - like I do - to load SWFs then your code would look like this:

Watch a video tutorial covering how to use captions with video.Maru.

Download Source files for captions example

video.Maru makes it very easy to add captions to your videos. Simply create a TextField with an instance name of captions. Then make the text value of the TextField the path to your XML file. The image below shows an example.

Caption XML format

The XML format for the caption data is easy. You can set the attributes for hour, min, sec, and duration for each caption. And then the text that you would like to display as the caption - which can be HTML formated text. That’s about it.

Below is a code sample.

Here’s the code used for the captions in the video below.

If you integrating video.Maru with XML to display a series of videos and you would like to display captions then just add a captions=”path-2-file.xml” attribute to the nodes where you want to display captions. That’s about it.

Watch a video tutorial covering how to create a fullScreen video interface with video.Maru.

To create a button that toggles the FullScreen view create a MovieClip and give it an instance name of fullscreen_btn. That button will act as a toggle to switch back and forth from in-browser to FullScreen views.

You’re done as far as video.Maru is concerned. But there’s a bit of work to on the HTML container page to allow this to work.

The <object><embed> tags need to have attributes that give the SWF permission to go FullScreen. The simple version of this is to find the allowFullScreen tag and give it a value of true.

If you would like to read more visit the Exploring full-screen mode in Flash Player 9 on the Adobe.com site for more details.

FullScreen support requires the Flash 9,0,28,0 player or above.

Be sure to read the video.Maru API page for more details about how to control FullScreen and change the layout of your design when switching.

Watch a video tutorial showing how you can stream youTube videos with video.Maru.

NOTE: youTube/Google have changed the process to get to the necessary query strings from the URL. The video tutorial above is inaccurate in the specific details of how to make this work but is still a good general overview of how it works. Just read the info below for the details of the changes.

I have made the necessary changes to video.Maru but streaming youTube videos only works with the latest build of video.Maru 3.0.

Since making the change youTube has changed again and the fix doesn’t seem to be working. If the video below plays when you click the play button then it’s working. Otherwise youTube is messing around with things again. Use this feature at your own risk.

Here’s the new method of getting the ID string:

1 - Go to youTube and pick out the video that you want to stream through video.Maru.

You will get a URL that looks something like this: http://youtube.com/watch?v=IDstring.

2 - Edit the URL string by removing the word watch? And change the “=” sign to a “/”. Here is an example:

3 - Now browse to that URL and you will get a very long URL and the video you were watching will appear in a large video interface. You need to grab two pieces of that new URL as illustrated below:

4 - The string that you want to give to video.Maru in order to play a video is: youtube=SomeID&t=SomeLongString.

To play the video above would be: youtube=uCsdPszJLNQ&t=OEgsToPDskJK0D5QnoklN-REer7a0Cq2

You can use that in your XML or directly in your videoWindow or in a linkBtn.

Watch a video tutorial on creating links to other videos in you video interface.

videoLinks allow you to create links to other videos in your video interface.

Creating a videoLink is similar to creating the videoWindow. Somewhere inside your videoLink MovieClip there needs to be a dynamic TextField with a text value that is the path to the video you would like to play when the user clicks on the MovieClip.

If you have more than one videoLink you must differentiate their instance names by appending an index number to the end of the instance name.

Example, if you have 3 videoLink MovieClips then you could give them instance names of videoLink1, videoLink2, videoLink3. However, the index numbers do not need to be sequential, just make sure they are unique or you will get an error when publishing the FLA: 256 levels of recursion exceeded.

You can also create next and prev (previous) buttons for the user to navigate through the videoLinks. The order of navigation is based on the index number appended to the videoLink MovieClips.

The videoLinks also support states for the currently playing video. To enable states create a keyframe inside your videoLink MovieClip with a frame label of nowPlaying. When the user clicks that MovieClip the nowPlaying state will be displayed. Otherwise it will display frame 1. The next/prev MovieClips are also integrated with the videoLink states.

If the video that plays at startup is also one of the videoLink MovieClips then it will automatically display that MovieClip in the nowPlaying state. Otherwise all of the videoLinks will display frame 1. In that case if the user clicks on either the next or prev button the videoLink with the lowest index number will always be selected first.