October 20, 2006

Akamai® StreamingAkamaiConnection ActionScript ClassSpecification and Usage

Akamai ConfidentialFor Customer Use Under NDA Only

Akamai Technologies, Inc.Akamai Customer Care: 1-877-425-2832 or, for routine requests, e-mail ccare@akamai.com

The EdgeControl® Management Center, for customers and resellers: http://control.akamai.com

Akamai® StreamingAkamaiConnection ActionScript Class Specification and Usage

Copyright © 2006 Akamai Technologies, Inc. All Rights Reserved.

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any language in any form by any means without the written permission of Akamai Technologies, Inc. While every precaution has been taken in the prep-aration of this document, Akamai Technologies, Inc. assumes no responsibility for errors, omissions, or for damages resulting from the use of the information herein. The information in these documents is believed to be accurate as of the date of this publication but is sub-ject to change without notice. The information in this document is subject to the confidentiality provisions of the Terms & Conditions governing your use of Akamai services.

Akamai, the Akamai wave logo, and EdgeControl are registered service marks of Akamai Technologies, Inc. Other products or corporate names may be trademarks or registered trademarks of other companies and are used only for the explanation and to the owner’s benefit, without intent to infringe or to imply any endorsement of Akamai or its services by, or relationship between Akamai and, the owners of such marks or to imply that Akamai will continue to offer services compatible with technology offered by such owners.

Macromedia and Flash are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

US Headquarters8 Cambridge Center

Cambridge, MA 02142

Tel: 617.444.3000Fax: 617.444.3001

US Toll free 877.4AKAMAI (877.425.2624)

For a list of offices around the world, see: http://www.akamai.com/en/html/about/locations.html

ContentsDescription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1Public Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1play() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3pause(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4seek() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4getStreamLength(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4getMp3Id3Info() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5onConnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5onFailure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5onStreamLength() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5onEndDetected(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5onNetConnectionStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6onNetStreamStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6onNetStreamPlayStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6onNetStreamMetaData(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6onNetStreamCuePoint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6onId3Info() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Public properties: Read-Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7bandwidthInKbps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7serverIPaddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7bufferLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7currentFps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7netConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7netStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Public properties: Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7maxBufferLength. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7useFastStartBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Example Connect Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential. i

ii Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential.

Description

The AkamaiConnection class is an ActionScript 2.0 class designed to assist Macrome-dia® Flash® application developers in establishing a robust connection with the Aka-mai Streaming (for Macromedia Flash Video) service using current best practices for connection expedition, client-proxy penetration, and buffer management. The class will always create a NetConnection and can also, optionally, create a NetStream on that NetConnection. Connections are initiated by a public method and events are used to notify the parent class of connection success, connection failure, errors, and NetStream- and NetConnection-specific events.

Constructor public AkamaiConnection()

Creates an object that can be used to establish both a NetConnection and NetStream on the Akamai Streaming (for Macromedia Flash Video) network.

Public Methods

connect() Usage:

Returns: Void

Description: This method uses the ident function to request the optimal Akamai Streaming server, and then connects using port/protocol negotiation over 1935/80 and RTMP/RTMPT. It then optionally establishes a NetStream instance on the established NetConnection. Events are triggered by a successful or failed connection, as well as native NetConnection and NetStream events which are proxied.

Note: The parameters must be given in the order they appear in the usage example above. In addition, if you want to include a parameter that appears further along in the list, you must also include all parameters that precede it. For example, to use the createNetStream parameter, you must also include the detectBandwidth parameter.

Following are descriptions of the method’s parameters (the minimum usage require-ment is connect(AkamaiHostname:String)).

Required: Yes

Default: None

Description: Specifies the Akamai Streaming account for the connection.

connect(AkamaiHostname:String, detectBandwidth:Boolean, createNetStream:Boolean, maxBufferLength:Number, useFastStartBuffer:Boolean, isLive:Boolean, port:String, protocol:String)

AkamaiHostName:String

Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential. 1

Required: No

Default: False

Description: If set to true, then once the connection is made, bandwidth is mea-sured using the Akamai Streaming bandwidth-estimation functions. The resulting measurement is returned with the connect event as the bandwidth parameter; the connect event is delayed until the bandwidth measurement is complete.

Required: No

Default: False

Description: If set to true, the class establishes a NetStream on the successful con-nection. A reference to this stream is passed as one of the connect event parameters.

Required: No

Default: 5

Description: This sets the NetStream’s default buffer length in seconds. This parame-ter is only meaningful if createNetStream is set to true.

Required: No

Default: False

Description: If set to true, then every time the NetStream.Play.Start NetStream event is detected, the NetStream buffer is set to 0.1 seconds. As soon as the netStream.Buffer.Full event is received, the buffer length is set to the value of maxBufferLength. This parameter is only meaningful if createNetStream is set to true.

Note: The isLive parameter is not presently implemented and is reserved for Akamai’s forthcoming support of live Flash streaming. If you need to include this parameter to use the port or protocol parameters, set its value to false.

Required: No

detectBandwidth:Boolean

createNetStream:Boolean

maxBufferLength:Number

useFastStartBuffer:Boolean

isLive:Boolean

2 Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential.

Public Methods

Default: False

Description: If set to true, the connection takes into account the different actions required when connecting to the Akamai Streaming (for live Macromedia Flash Video) service.

Required: No

Default: any

Valid Values: any, 1935, and 80

Description: If set to 1935 or 80, the connection attempt is restricted to a specific port, effectively disabling connection expedition. The default value of any means that connection expedition will occur, and the class will use the port/protocol combina-tion that connects first.

Note: This is a string parameter, not a number.

Required: No

Default: any

Valid Values: any, rtmp, or rtmpt

Description: If set to rtmp or rtmpt, the connection attempt is restricted to a specific protocol, effectively disabling connection expedition. The default value of any means that connection expedition will occur, and the class will use the port/protocol combi-nation that connects first.

play() Usage:

Returns: Void

Description: Used to play files on the existing NetStream. This method can only be called if createNetStream was set to true when connect() was called and the onConnect event has fired. If the NetStream does not exist, calling this method will cause the onError event to fire. The parameters are identical to those used by the NetStream class’s native play method.

Note: To play an MP3 file, the name parameter should contain the prefix "mp3:".

port:String

protocol:String

play(name:String, start:Number, len:Number, reset:Boolean)

Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential. 3

pause() Usage:

Returns: Void

Description: Pauses or resumes playback of an existing stream. This method can only be called if createNetStream was set to true when connect() was called and the onConnect event has fired. If the NetStream does not exist, calling this method will cause the onError event to fire. Omitting the flag will toggle playback. Setting the flag to true will always pause the stream and setting it to false will always resume playback. This method’s behavior is identical to the NetStream class’s native pause method.

seek() Usage:

Returns: Void

Description: Seeks to a new position within the stream, where position is specified in seconds. This method can only be called if createNetStream was true when connect() was called and the onConnect event has fired. If the NetStream does not exist, calling this method will cause the onError event to fire. This method’s behavior is identical to the NetStream class’s native seek() method.

close() Usage:

Returns: Void

Description: Used to explicitly close any open NetConnections and NetStreams cre-ated by the class. This resolves a Flash 9 bug in which certain NetStream instances are not removed when the class that initiated them is removed from the stage.

getStreamLength() Usage:

Returns: Boolean—Returns true if the NetConnection is defined, and it can make the request to the server. Otherwise, returns false.

Description: Allows the user to request the streaming file’s duration (in seconds). The class does this by proxying the request to the server. This method does not itself return a response, since the server request is asynchronous. Rather, you request the stream length using this method and set a listener on the onStreamLength event that returns the result once it is available from the server.

pause(flag:Boolean)

seek(position:Number)

close()

getStreamLength(filename:String)

4 Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential.

Events

getMp3Id3Info() Usage:

Returns: Boolean—Returns true if the NetConnection is defined, and it can make the request to the server. Otherwise, returns false.

Description: Allows you to initiate a request to extract the ID3 metadata from an MP3 file (this occurs independently of file playback). The data can be obtained by listening to the onId3Info event after using this method.

Note: The filename should not contain the prefix "id3:". The class adds this automatically.

Events

Notification of a successful or failed connection is sent via event, rather than by the polling mechanism used by the this class’s previous version (AkamaiFCSPlayBack).

onConnect() Usage:

Returned once the class has successfully connected to Akamai Streaming. A reference to the active NetConnection instance is always returned. References to the measured bandwidth and NetStream are only returned if connect was called with both detectBandwidth and createNetStream, respectively, set to true.

onFailure() Usage:

Holds a verbose description of the error that occurred. If the class either successfully connects to a server, but is rejected, or times out while connecting to a server, the error event will be thrown. The default time-out interval is ten (10) seconds.

onStreamLength() Usage:

Returns the duration (in seconds) of the file described by filename. This event will be thrown after the getStreamLength function is called.

onEndDetected() Usage:

Notification that the end of the stream has been reached. While theonNetStreamPlayStatus can be monitored for the complete event, that event is only triggered when connected to a Flash Media Server 2.x server, whereas the

getMp3Id3Info(mp3_filename:String)

onConnect(type:String, target:Object, nc:NetConnection, bandwidthInKbps:Number, ns:NetStream);

onFailure(type:String, target:Object, description:String);

onStreamLength(type:String, target:Object, filename:String, streamlength:Number);

onEndDetected(type:String, target:Object);

Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential. 5

onEndDetected event will fire reliably against all Flash Communication Server and Flash Media Server variants.

onNetConnectionStatus()

Usage:

Makes available the same infoObject that the native NetConnection.onStatus event offers. This event is offered so that users can set listeners against theAkamaiConnection instance and not have to set them against objects internal to the class.

Note: This event is only thrown for a NetConnection which has successfully connected. If the connection attempt is rejected by the server, this event will never fire. You should mon-itor the onFailure event to receive notice of a failed connection.

onNetStreamStatus()

Usage:

Makes available the infoObject from the NetStream.onStatus event.

onNetStreamPlayStatus()

Usage:

Makes available the infoObject from the NetStream.onPlayStatus event.

Note: This event is only thrown when connected to a Flash Media Server 2.x server.

onNetStreamMetaData()

Usage:

Makes available the infoObject from the NetStream.onMetaData event. This can be used to extract metadata from any file being played over the NetStream.

onNetStreamCuePoint()

Usage:

Makes available the infoObject from the NetStream.onCuePoint event. Allows users to synchronize content to precise points within a stream.

onNetConnectionStatus(type:String, target:Object, infoObject:Object);

onNetStreamStatus(type:String, target:Object, infoObject:Object);

onNetStreamPlayStatus(type:String, target:Object, infoObject:Object);

onNetStreamMetaData(type:String, target:Object, infoObject:Object);

onNetStreamCuePoint(type:String, target:Object, infoObject:Object);

6 Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential.

Public properties: Read-Only

onId3Info() Usage:

Makes available the infoObject when ID3 metatdata is detected within a MP3 file. This event will only fire if you first call the getMp3Id3Info() method.

Public properties: Read-Only

bandwidthInKbps Number—Returns the bandwidth measured when the connection was established. Returned as undefined if bandwidth was not detected.

serverIPaddress String—Returns the IP address of the optimal Akamai Streaming server.

bufferLength Number—Returns the current size of the buffer in seconds.

time Number—Returns the current stream playhead time in seconds.

currentFps Number—Returns the current stream’s rendered frames per second.

port Number—Returns the port used to connect, either 1935 or 80.

protocol String—Returns the protocol used to connect, either rtmp or rtmpt.

netConnection NetConnection—A reference to the NetConnection instance.

netStream NetStream—A reference to the NetStream instance. Only valid only if createNetStream was set to true in the initial connect() request.

version String—A reference to the version of the class. Initially, this will be 1.0.

Public properties: Read and Write

maxBufferLength Number—The number of seconds the NetStream buffer is required to store. Only valid if createNetStream was set to true in the initial connect() request. If useFastStart was set to true in the initial connection request, then the buffer will initially be set to 0.1 seconds at play.start and then to maxBufferLength when buffer.full is reached.

onId3Info(type:String, target:Object, infoObject:Object);

Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential. 7

useFastStartBuffer Boolean—If set to true, this enables the fastStart buffer optimization routines. If set to false, it disables them and sets the buffer length to the fixed maxBufferlength value.

Example Connect Calls

1. Establish a NetConnection only:

2. Establish a NetConnection and measure bandwidth:

3. Establish a NetConnection and NetStream without measuring bandwidth:

4. Establish a NetConnection and NetStream, measuring bandwidth and using a fastStart buffer:

Example Usage

connect("cp9391.edgefcs.net");

connect("cp9391.edgefcs.net",true);

connect("cp9391.edgefcs.net",false,true);

connect("cp9391.edgefcs.net",true,true,5,true);

import AkamaiConnection;var connection:AkamaiConnection = new AkamaiConnection();connection.addEventListener("onConnect", this);connection.connect("cp9391.edgefcs.net", true, true);function onConnect(event:Object) {

trace("Connected on port "+connection.port+" using "+connection.protocol);

trace("Bandwidth measured at "+event.bandwidthInKbps+" kbps");myVideo.attachVideo(event.ns);connection.play("myfile");

}

8 Akamai® Streaming - AkamaiConnection ActionScript Class Specification and Usage. Akamai Confidential.