akamai streaming - kensonger.com · akamai® streaming - akamaiconnection actionscript class...
TRANSCRIPT
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 [email protected]
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.