ActionScript 3.0 native bandwidth detection

Adobe Media Server 3.0 and later support native bandwidth detection from the server to the client. After the client connects to the server, call NetConnection.call("checkBandwidth", null) to intiate bandwidth detection. The server sends chunks of data to the client and waits for a return value from the client. You do not need to write any server-side code.

Note:

This example is based on the rootinstall/documentation/samples/bandwidthcheck/Bandwidth.as sample.

Enable bandwidth detection in the Application.xml file

  • Verify that bandwidth detection is enabled in the Application.xml file:

     <BandwidthDetection enabled="true"> 
        <MaxRate>-1</MaxRate> 
        <DataSize>16384</DataSize> 
        <MaxWait>2</MaxWait> 
    </BandwidthDetection>

    Bandwidth detection is enabled by default. In addition to enabling and disabling bandwidth detection, you can configure the size of the data chunks the server sends to the client, the rate at which the data is sent, and the amount of time the server waits between data chunks.

    You can edit the Application.xml file at the application level or at the vhost level. See Configuring a single application.

Write the client event handler class

  • Create an ActionScript 3.0 class that handles events and calls bandwidth detection on the server. It must implement the onBWCheck and onBWDone functions:

     class Client { 
         public function onBWCheck(... rest):Number { 
             return 0; 
         } 
         public function onBWDone(... rest):void { 
             var bandwidthTotal:Number; 
             if (rest.length > 0){ 
                bandwidthTotal = rest[0]; 
                 // This code runs 
                 // when the bandwidth check is complete. 
                 trace("bandwidth = " + bandwidthTotal + " Kbps."); 
            } 
         }  
     }

    The onBWCheck() function is required by native bandwidth detection. It takes an argument, ...rest. The function must return a value, even if the value is 0, to indicate to the server that the client has received the data. You can call onBWCheck() multiple times.

    The server calls the onBWDone() function when it finishes measuring the bandwidth. It takes four arguments. The first argument is the bandwidth measured in Kbps. The second and third arguments are not used. The fourth argument is the latency in milliseconds.

Write the main class

  1. Create a main ActionScript 3.0 class, giving it a package and class name of your choice:

     package { 
         import flash.display.Sprite; 
         import flash.net.NetConnection; 
         import flash.events.NetStatusEvent; 
        import flash.events.AsyncErrorEvent; 
      
         public class Bandwidth extends Sprite 
         { 
         } 
     }

    You can create the main and client classes in the same file, like the Bandwidth.as example file.

  2. In the constructor of the main class, create a NetConnection object, set the NetConnection.client property to an instance of the client class, and connect to the server:

     private var nc:NetConnection; 
      
     public function Bandwidth() 
     { 
         nc = new NetConnection(); 
         nc.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); 
        nc.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler); 
         nc.client = new Client(); 
         nc.connect("rtmp://localhost/bandwidthcheck"); 
     }
  3. In the netStatus event handler, call NetConnection.call() if the connection is successful, passing checkBandwidth as the command to execute and null for the response object:

     public function netStatusHandler(event:NetStatusEvent):void 
     { 
        trace(event.info.code); 
         switch (event.info.code) 
         { 
             case "NetConnection.Connect.Success": 
                 // Calls native bandwidth detection code on the server. 
                 // You don’t need to write any server-side code. 
                  nc.call("checkBandwidth", null); 
                 break; 
         } 
     }

    Note:

    The checkBandwidth() method belongs to the Client class on the server.

Run the sample

  • Test the main class from Flash or Flash Builder. The following is the Flash Builder output showing the client’s bandwidth:

     [SWF] C:\samples\Bandwidth\bin\Bandwidth-debug.swf - 2,137 bytes after decompression 
     The connection was made successfully 
     Bandwidth from server to client is 17287 Kpbs

    In this example, the Client class displays the bandwidth value. In your client, you can take some action, such as choosing a video to stream to the client based on the client’s bandwidth.

ActionScript 2.0 native bandwidth detection

You can also use native bandwidth detection from ActionScript 2.0. Just as in ActionScript 3.0, define functions named onBWCheck() and onBWDone(). When the client connects to the server , call to NetConnection.call("checkBandwidth").

Note:

This example uses the rootinstall/documentation/samples/bandwidthcheck/BandwidthAS2.fla sample.

  1. On the server, create a rootinstall/applications/bandwidthcheck folder.

  2. Do one of the following to verify that native bandwidth detection is enabled:

    • Open the rootinstall/conf/_defaultRoot_/_defaultVHost_/Application.xml file and verify that <BandwidthDetection enabled="true">.

    • Create an Application.xml with the following code and copy it to the rootinstall/applications/bandwidthcheck folder:

      <Application> <Client> <BandwidthDetection enabled="true"> </BandwidthDetection> </Client> </Application>
  3. In Flash Professional, choose File > New > ActionScript 2.0 to create a new ActionScript 2.0 file.

  4. Open the Actions panel and paste the following code into frame 1:

    nc = new NetConnection(); 
    nc.onStatus = function(info){ 
        trace(info.code); 
        if(info.code == "NetConnection.Connect.Success"){ 
            checkBandwidth(); 
        } 
    } 
    nc.onBWCheck = function(dataChunk){ 
        return 0; 
    } 
    nc.onBWDone = function(bandwidth){ 
        trace("Bandwidth from server to client is: " + bandwidth + " Kbps"); 
    } 
    function checkBandwidth(){ 
        nc.call("checkBandwidth"); 
    } 
    nc.connect("rtmp://localhost/bandwidthcheck");
  5. Choose Control > Test Movie. The onStatus messages and the bandwidth measurement are traced to the Output panel.

Initiate native bandwidth detection from a server-side script

You can initiate native bandwidth detection from a server-side script. In this case, the server-side code calls the native checkBandwidth() function on the server:

 application.onConnect = function (clientObj){ 
     this.acceptConnection(clientObj); 
     clientObj.checkBandwidth(); 
 }

When initiating bandwidth detection from the server, do not call checkBandwidth() from the client.

The main.asc server-side script that Adobe provides with the vod application calls the checkBandwidth function. To see an example, open rootinstall/samples/applications/vod/main.asc.

Server-side script-based bandwidth detection

You can disable native bandwidth detection and use a server-side script that defines the checkBandwidth function. For example, if you have a legacy application that uses a server-side script to perform bandwidth detection, disable native bandwidth detection. You can disable native bandwidth detection at the application level or at the vhost level.

Script-based bandwidth detection is not as reliable as native bandwidth detection. If you use edge servers, native bandwidth detection is performed at the outermost edge server to reduce the load on the origin servers. Script-based bandwidth detection determines the bandwidth from the origin server to the client, not from the edge server to the client. If latency exists between the origin server and the edge server, it might affect the bandwidth calculation.

Latency between the origin server and the edge server can affect the bandwidth measurement.

A. Origin server B. Edge server C. Client 

To disable native bandwidth detection at the application level:

  1. Open a text editor, create a new file, and save it as Application.xml to the rootinstall/applications/applicationname folder.

  2. Copy the following XML into the file:

    <Application> 
        <Client> 
            <BandwidthDetection enabled="false"> 
            </BandwidthDetection> 
        </Client> 
    </Application>
  3. Save the file. You do not need to restart the server.

To disable native bandwidth detection at the vhost level:

  1. Open the rootinstall\conf\_defaultRoot_\_defaultVHost_\Application.xml file in a text editor.

    Note:

    This path is for the default vhost. You can edit the Application.xml file for any vhost.

  2. Locate the BandwidthDetection tag and set the enabled attribute to false, as in the following:

    <Application> 
        ... 
        <Client> 
            ... 
            <BandwidthDetection enabled="false"> 
            </BandwidthDetection> 
            ... 
        </Client> 
        ... 
    </Application>
  3. Save the file. Restart the server or vhost.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy