(IV) Streaming Service to a Web Browser – ActionScript Integration

Overview:

There are 3 basic steps to integrate the Streaming service to a Web Browser using ActionScript and start using DNA to deliver content through the DNA peer network:

1. Check that the existing distribution infrastructure conforms to the Basic DNA Integration Requirements
2. Get the DNA ActionScript library from the downloads section of the DNA Analytics.
   
3. Integrate the DNA ActionScript library into your SWF player

1. Check Basic DNA Integration Requirements

Integration of the DNA service relies on some basic requirements from your existing distribution infrastructure.   

You can check whether your content servers meet these requirements by using the DNA URL Requirements Tester Tool. The Tester tool is a simple text box into which you can type the fully qualified URL of a piece of your content on one of your content servers. It will return advice on whether servers conform to ideal DNA requirements.  In cases where your distribution infrastructure does not conform to these requirements, the Tester Tool will provide an error message as to the issue, and the infrastructure should be reconfigured accordingly.  For a list of potential error messages and corresponding solutions see DNA URL Requirements Tester Tool. For any additional assistance use BitTorrent DNA support.

The following is the list of requirements for your distribution infrastructure to conform to ideal DNA requirements:

Web-servers:

• You must have access to web servers and have permissions to host a DNA JavaScript file to be provided by BitTorrent Inc.
• You must have permissions to adjust HTML on your website to load the DNA JavaScript file on each relevant page and be able to modify content URLs on the page to invoke functions that the DNA JavaScript file provides.

Content-servers and Content:

• Your content servers must support “range requests” and should support “persistent” or “keep-alive” connections of at least 2 seconds duration.
• You must have exclusive use of the domain or domains from which the content is served.
• You must know the fully qualified URL or URLs for each piece of content to be DNA-enabled.
• The fully qualified URL or URLs for each piece of content must be persistent over time.
• The actual files to which the fully qualified URL or URLs point must remain unchanged over time.
• Content servers must not require any form of authentication to enable downloads. BitTorrent DNA only supports HTTP (HTTPS is not yet supported).
• All popular content servers are supported with the exception of Microsoft IIS v5.1 (which does not support range requests).

2. Get the DNA ActionScript Library from the download section of the DNA Analytics

{ Missing Content Here }

3. Import and integrate the DNA ActionScript library

At it’s most basic level, the BitTorrent DNA service is controlled through the DNA Proxy API by passing specially-formed URLs (which conform to the DNA Proxy API) to the DNA port on localhost.  The DNA ActionScript library (provided by BitTorrent, Inc.) provides a very simple API that handles all the administrative details of detecting DNA, forming URLs and passing them into the DNA Proxy API.  The DNA ActionScript libraries perform all the functions performed by the DNA JavaScript file. There is no need to use both.

The latest versions of the DNA ActionScript librariesare contained within a zipped file ActionScript SDK that is available from the download section of the DNA Analytics https://analytics.bittorrent.com/downloads

Within this zipped file you will find two main subdirectories: as2 and as3.

To include the DNA ActionScript libraries you need to first point at one of these two main subdirectories from your Flash Player:

ActionScript 2

1. If using a Flash Player based on ActionScript 2:
   1. From the Adobe Flash CS3 toolbar select: Flash->Preferences->ActionScript
   2. Select "ActionScript 2.0 Settings"
   3. In the Classpath include a path to the as2 directory, for example: /Users/dave/Documents/branches/btdna_flash_sdk/trunk/as2

     OR

ActionScript 3

2. If using a Flash Player based on ActionScript 3:
   1. From the Adobe Flash CS3 toolbar select: Flash->Preferences->ActionScript
   2. Select "ActionScript 3.0 Settings"
   3. In the Classpath include a path to the as3 directory, for example: /Users/dave/Documents/branches/btdna_flash_sdk/trunk/as3

Once the DNA ActionScript libraries are included you need only to import the BTNetStream class (called BTNetStream.as) into the top of your ActionScript file.  The BTNetStream class is contained within the COM folder of the path included in the CS3 Classpath (either as2 or as3). The BTNetStream class will also pull in several other related classes that are distributed within the same COM folder. Note that the path to the content source (here signified by the variable “flvURL”) needs to be specified as an absolute path.  See code snippets below for example.

Note DNA currently only supports integration with Flash Players based on NetStream(), and does not support players based on FLVPlayback().

Your code should change from something like:

var flvURL:String=this.flvURL; 
var nc:NetConnection = new NetConnection(); 
nc.connect(null); 
var ns:NetStream = new NetStream(nc); 
video.attachVideo(ns); 
ns.play(flvURL);

to the following (modified code shown in bold):

import com.btdna.video.BTNetStream; var flvURL:String=this.flvURL; 

var nc:NetConnection = new NetConnection(); 
nc.connect(null); 
var ns:BTNetStream = new BTNetStream(nc);  video.attachVideo(ns);  ns.play(flvURL); 

(Note that the only changes are the import BTNetStream command, and the insertion of the characters “BT” in front of the call to the “NetStream” class.)

This integration will detect DNA and only rewrite the URL to address DNA if it is present. It will also handle reporting of stats back to the DNA reporting back-end. This reporting information feed the analytics tools available through DNA as well as provides operational monitoring data so BitTorrent Inc can continue to assure the quality of the service.

You should not need to pass in any parameters about the duration of the file or the expected QOS as these should be detected automatically from metadata available from the FLV.

A slight modification on the integration outlined above will result in statistics only being reported in cases where DNA is present:

var ns:BTNetStream = new BTNetStream(nc, false); 

If the integration is targeting only some people to use the DNA service and others to use the existing server infrastructure, then you should call BTNetStream for those who should use DNA and call NetStream for those that should not use DNA. 

In specifying the content URL you may pass additional parameters that will control the way DNA behaves:

If you want to NOT use DNA acceleration then:

ns.play(flvURL)

becomes:

ns.use_dna=false;
ns.play(flvURL);

If you want to specify a value for buffer_secs then:

ns.play(flvURL)

becomes:

ns.play( { url : flvURL, buffer_secs : 20 } );

If you want to combine multiple HTTP sources of the same file (e.g. multiple CDNs):
In cases where the same content is available from several different sources (e.g. more than one server or CDN), the different URLs that point to that piece of content should be associated together as follows:

ns.play(flvURL)

becomes:

ns.play( { url : [flvURL1, flvURL2] } );

This rewrites the given URLs as joining them in an equivalence class.

Additional DNA ActionScript API Parameters:

Additional DNA parameters can be passed using the ActionScript API to tune the service. Any DNA parameter (a full list is presented in the Advanced Integration section) may be passed to the ActionScript API in the manner described, and multiple parameters may be passed at once, so long as they are separated by commas. Not all of them are relevant (e.g. if you pass the “duration” parameter into the ActionScript API it will be disregarded as the ActionScript library treats the duration extracted from metadata in the FLV as more reliable.)