(III) Streaming Service to a Web Browser – JavaScript Integration
Overview:
There are 4 basic steps to integrate the Download service to a Web Browser using JavaScript and start using DNA to deliver content through the DNA peer network:
- Check that the existing distribution infrastructure conforms to the Basic DNA Integration Requirements
- Access the DNA JavaScript file at http://btdna.bittorrent.com/btdna.js or host it somewhere on your website
- Load the DNA JavaScript file on each page that links to content to be DNA-enabled
- Use the DNA JavaScript API to modify the URLs of each piece of content to be DNA-enabled
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. Access or Host the DNA JavaScript file
The DNA JavaScript file btdna.js (provided by BitTorrent, Inc.) is an important part of the DNA service. It detects whether DNA is present on the end-user’s computer, and if so it automatically rewrites the URL of the DNA-enabled content so that the DNA service is used rather than just the HTTP infrastructure. The latest version of the DNA JavaScript file is always hosted at:
http://btdna.bittorrent.com/btdna.jsThe DNA JavaScript file can be remotely invoked at this location or alternatively it can be hosted anywhere else accessible from within the host website infrastructure.
If you choose to host a copy of the btdna.js file yourself you must be prepared to update it to keep up with any updates to the btdna.js software.
3. Load the DNA JavaScript file
Each HTML page containing objects to be accelerated by DNA must load the JavaScript file btdna.js. This should be loaded from inside the HTML header. For example:
<head>
<script type="text/javascript" src http://btdna.bittorrent.com/btdna.js "></script>
</head>The DNA JavaScript file is used to check for the presence of DNA on an end-user’s computer when that end user is looking at a page which is DNA enabled. In case DNA is present, the DNA JavaScript file will automatically rewrite the URL to communicate with the DNA client using the DNA Proxy API. (More details about the DNA Proxy API are described in the integration guide “Advanced Integration” section). In case DNA is not present on an end-user’s computer there are no changes made and the end-user will be able to get the content as usual.
4. Use the DNA JavaScript API within the HTML on the page:
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 Javascript API handles all the administrative details of forming URLs and passing them into the DNA Proxy API, combining everything into a single, simple function call, btdna().
Specify the Streaming Service:
DNA is invoked for a piece of content on a page by modifying the URL which points to the actual content – the modification is performed automatically by enclosing the URL inside a function call to btdna.js and including some parameters. The simplest modification is as follows:
btdna({url:'http://my/own/video', service:'streaming' })
This will detect the presence of DNA on the end user’s computer and will return a rewritten URL. This rewritten URL will use DNA to access the content using the DNA Streaming service. If DNA is not available the URL will not be rewritten and the end-user will get the content directly from the server as normal.
(NOTE: in case the service: parameter is not specified, DNA will default to download the file using the standard DNA Download service unless the MIME type or file extension suggests that it is a stream-able file, in which case the DNA Streaming service will be used.)
Specify the Duration Parameter for the Streaming Service:
For the DNA Streaming service the duration: parameter MUST be set (NOTE: the duration: parameter is only required for the Javascript integration with DNA Streaming service. Using the ActionScript integration with DNA Streaming service avoids the requirement for duration: to be set. See ActionScript Integration section for additional details.
The duration is defined as the length of the media clip in seconds if viewed continuously without interruption. DNA will deliver streamed content to the media player maintaining a buffer of cached content ahead of the play head. DNA will ensure this buffer is always full (falling back on an HTTP server if necessary), while otherwise downloading the maximum possible bytes from the peer network.
Setting the duration: parameter is achieved as follows:
btdna({url:'http://my/own/video.flv', duration:'10:04', service:'streaming'})
or
btdna({url:'http://my/own/video.flv', duration:'604', service:'streaming'})
This specifies that the URL points to a streamable media object (in this case a “.flv” file) which is 10 minutes and 4 seconds (604 seconds) long.
(NOTE: as a precaution, if the duration parameter is set, but service type is not set or is set to min_rate_data (data download), DNA will nevertheless assume that the file is destined for the DNA streaming service.)
For streaming, the quality of service or qos: parameter may be used as an alternative to duration, and may be convenient if all videos are guaranteed to be encoded at the same bitrate. However, care must be taken in setting the appropriate quality of service. In practice the relevant encoded bitrate for a video file includes the bitrate of the video plus the bitrate of the audio plus a small overhead. The most reliable way of calculating the encoded bitrate value for the purpose of DNA is to divide the file size (in bytes) by the duration of the entire file (in seconds). The qos parameter should be set equal to this encoded bitrate value, but specified as bytes per second.
(NOTE: there are 8 bits for every byte, and 1024 bytes in a kilobyte etc.)
(NOTE: failure to set either a duration: or a qos: parameter for streaming will cause DNA to fail.)
The qos: parameter should be set as follows:
btdna({url:'http://my/own/video.flv', qos:x, service:'streaming'})
This rewrites the given URL, which sets qos to x, and returns a rewritten URL as follows: 'http://dna/prefix/x/http%3A//my/own/ video.flv''.
(NOTE: in the case of both qos: and duration: being passed in as parameters for streaming, DNA will discard the qos: value and use the duration: value only.)
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:
btdna({url:['http://my/own/video', 'http://another/url/for/the/same/video']})
This rewrites the given URLs as joining them in an equivalence class.
(NOTE: in DNA Streaming service each client will make two http connections, to one URL if only one is specified, and to different URLs if they are specified. This differs from the behavior of DNA Downloads service where each client will only make a single http connection. Making multiple http connections generally provides a more consistent download rate from origin servers to clients. This tends to be important when dealing with DNA Streaming where multi-media content is presented to the user in real-time, and less important when dealing with DNA Download content which must be downloaded in its entirety before user interaction.
For information on increasing the number of HTTP connections see the DNA Advanced Integration section under “min_http_connections”.)
Additional DNA JavaScript API Parameters:
Additional DNA parameters can be passed using the JavaScript API to tune the service. Any DNA parameter (a full list is presented in the Advanced Integration section) may be passed to the Javascript API in the manner described, and multiple parameters may be passed at once, so long as they are separated by commas.
Working demos with example code can be seen at the following locations:
| DNA Streaming WMV Integration: | |
|---|---|
| Example Code using btdna.js | http://www.bittorrent.com/dna/wmvtest |
| DNA Streaming FLV-JavaScript Integration: | |
|---|---|
| Example Code using btdna.js | http://www.bittorrent.com/dna/flvtest |
