(I) DNA Proxy API
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. Calls using the URL-based DNA Proxy API obey the following syntax, where key-value pairs can be provided in any order:
http://localhost:btdna_proxy_port/proxy?
&url=origin_url_1
&url=origin_url_N
&service=service_name
&service_parameter_1=value_1
&service_parameter_N=value_NSpecify the IP address of the localhost or just the localhost itself:
The default IP address of localhost is
127.0.0.1 this value may optionally be used instead of
localhost(NOTE: using the explicit IP address rather than “localhost” may prove more resilient if IPV6 networks are used. In most cases (including if you’re not sure), localhost will be adequate.)
Specify the port over which the DNA proxy is active:
The DNA Proxy API requires correctly-formed URLs to be passed to the btdna_proxy_port. This is an integer which represents the port on which the DNA localhost proxy is active.
The DNA JavaScript API can speak to a DNA browser plugin to identify the btdna_proxy_port. However, the DNA JavaScript API is only appropriate for accelerating objects downloaded in a web browser (as described in DNA Basic Integration sections I and III).
A different platform-specific method will be required for other applications (e.g. download managers or media players) using DNA acceleration. In Windows, the platform-specific mechanism is the Windows registry – the port is stored as a DWORD value under HKEY_CURRENT_USER\Software\BitTorrent\engine\port.
This is the port at which BitTorrent DNA receives requests. (Pseudo-code for discovering btdna_proxy_port and constructing an appropriate URL follows.)
- Set
recordedPortTimestamptoHKEY_CURRENT_USER\Software\BitTorrent\engine\portTimestampor0, if key does not exist. - Launch
btdna.exe - Wait for:
HKEY_CURRENT_USER\Software\BitTorrent\engine\portTimestamp > recordedPortTimestampto be true (optional: timeout and fetch original URL) - Get port from:
HKEY_CURRENT_USER\Software\BitTorrent\engine\port
Specify the URL (or URLs) of the Origin Content:
Each piece of content passed to the DNA Proxy API must be identified by an origin_url. Every such origin_url must be “URL-encoded” (sometimes called “percent-encoded”) meaning that some “reserved characters” must be input using a special convention. This function is done automatically if using the DNA JavaScript or DNA ActionScript APIs. However, if addressing the DNA Proxy API directly, this additional step is important. The type of URL-encoding required is equivalent to that performed by the standard JavaScript function encodeURIComponent().
An origin_url is any valid URL that references an object on a server that communicates using HTTP 1.1 supporting range requests and persistent (“keep alive”) connections. The domain name may refer to a web server or CDN. DNA does not currently support SSL.
In cases where the same content is available from several different sources (e.g. more than one server or CDN), then multiple origin_urls may be added as follows:
&url=origin_url_1 &url=another_url_for_the_same_thing &url=origin_url_NThis will join the URLs together in an equivalence class.
(NOTE: in case DNA parameters are set for each individual URL and if there are conflicting parameter settings on individual URLs that are then grouped with no value explicitly specified for the class as a whole, the value from the last listed URL with an explicitly specified value becomes the value for the class as a whole.)
BitTorrent DNA Proxy API Parameters
Any object enabled for BitTorrent DNA acceleration is downloaded by modifying its origin URL and directing HTTP requests to the DNA client running on localhost. An application such as a download manager or a media player can fetch such an object by modifying its URL accordingly:
http://localhost:btdna_proxy_port/proxy?url=origin_url&service=service_name&service_parameter_1=value_1&...&service_parameter_N=value_N Beyond url=, DNA accepts a number of DNA Proxy API parameters so that it’s behavior can be adapted to each piece of content and each user’s network conditions. Some parameters are mandatory, some are recommended, and some are optional.
| Parameter: |
|
| Type: |
highly recommended (not mandatory) – if parameter is not set, DNA will identify streamable files by file extension/MIME type and will try to stream them – otherwise the service will default to min_rate_data |
| Values: |
|
| Explanation: |
If neither service=min_rate_data nor service=streaming is passed, DNA will guess which mode to use based on the extension or MIME type of the file being downloaded. To be specific, if one of the following extensions OR MIME types is detected, then DNA will use the streaming service. Extensions: 3gp, 3g2, aac, aif, aiff, asf, au, divx, flv, m1v, m2v, m4v, mkv, mka, mp1, mp2, mp3, mp4, m4a, mpa, mpg, mpeg, mov, moov, qt, ogg, ogm, ogv, oga, ogx, ram, rm, swa, vob, wav, wma, wmv. If DNA does not detect one of these file extensions or MIME types it will download the object with the min_rate_data service. |
| Parameter: |
|
| Type: |
highly recommended (for downloads/min_rate_data); optional (for streaming) – if not set explicitly it will default to zero |
| Value: |
(zero or any positive integer) |
| Explanation: |
For the DNA Download service the qos parameter must be set. Quality of service is defined as the minimum acceptable download speed for downloads – it does not guarantee a quality of service from the peer network, but rather indicates a delivery speed which DNA will attempt to achieve from the peer network but will fall back to the web server to maintain in case the peer network is not sufficient. The ability to actually meet this quality of service is ultimately determined by the origin servers, not by DNA. The qos parameter is specified in bytes-per-second. Setting a quality of service of 1 byte-per-second will result in the maximum possible bytes being pulled from the peer network. DNA will pull everything it can from the peer network and will only pull from the HTTP server to ensure that it can maintain a minimum data rate of (in this case) 1 byte-per-second. In this scenario, if there are no peers available, the download may take a long time. This may not matter if the end-user is not expected to be actively watching a download (e.g. in the case of background downloads.) Setting a quality of service at a higher value (e.g. 100,000 bytes-per-second (i.e. 800 kilobits-per-second)) will cause DNA to pull everything it can from the peer network but fall back on the HTTP server if necessary to maintain a minimum data rate of 100,000 bytes-per-second. This type of setting may be important if the end-user is expected to be actively watching a download (e.g. in the case of foreground or user-visible downloads). Setting a quality of service at 0 is a special setting which is essentially the same as setting it to an infinitely large amount. The behavior of DNA in this scenario is to pull data from the server and from peers as quickly as possible in unison. In practice the “offload” (peer-network-delivered bytes) will usually be lower in this scenario although DNA will always retain a small amount of bandwidth for attempting to obtain data from the peer network. In cases where peers can deliver faster than a server, those peers will be preferred over the server. In the case that no quality of service parameter value is specified, DNA will apply a qos value of 0 (which will eliminate any expected impact to the end-user experience but may reduce the level of offload).
A special exception is a qos rate of 0. If qos is set to 0, DNA will use its bandwidth management functionality to estimate each user’s downstream capacity, and set the qos to near the maximum download rate that user’s connection can sustain. 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. Example: A sample URL, where [bt port] is set to ‘4096’, [qos rate] to ‘125000’ (i.e. 125000 bytes per second, or 1 Mbps), and [origin URL] to http://actlab.tv/media/Metroid_2211.avi: |
| Parameter: | duration= (specifies the duration of a streamed file) |
| Type: |
mandatory (for streaming, unless |
| Values: |
any positive integer (seconds) or time signified in the form mm:ss where mm = minutes and ss = seconds. |
| Explaination: |
The duration parameter refers to the duration of a video file being streamed. This allows DNA to automatically calculate the encoded bitrate of the file, and set the right qos rate automatically. This makes streaming mode performance more robust and it is recommended that customers use the duration parameter rather than the qos parameter for the Streaming service. Duration is specified as a number of seconds. If the duration parameter is present, the service parameter is set to streaming and any other service parameter passed is ignored. |
| Parameter: |
|
| Type: |
optional (for streaming); not required (for downloads/min_rate_data – ignored if set) |
| Values: |
any positive integer (seconds); default value is 5 seconds if parameter is not specified |
| Explaination: |
The buffer_secs parameter specifies number of seconds worth of video that DNA attempts to maintain in its buffer to account for encoding variability in order to assure smooth streaming performance. If using Variable Bitrate Encoding, set the buffer_secs parameter greater than or equal to the Video Buffer Verifier (VBV). VBV is the largest allowed buffering by the VBR encoder and defines how far ahead streaming must remain to avoid “buffering” errors. buffer_secs is only applicable in streaming mode. DNA also adds on some additional overhead seconds to account for other types of variability. |
| Parameter: |
|
| Type: |
optional (for downloads/min_rate_data); not required (for streaming) – if parameter not set, then defaults to “attachment” for will determine what to do with a file. |
| Values: |
attachment or inline |
| Explaination: |
The content disposition header determines how a browser will treat a file – specifically whether it will try to render that file directly “inline” or whether it will treat the object as an “attachment” and provide the end user with the option to save that file. If unspecified, browsers have their own default behavior for how they handle files based on MIME type and file extension. This parameter provides flexibility for a content provider to use the min_rate_data service to download content and then instruct the browser to whether to directly render that content (e.g. a SWF file) or alternatively to give the end user the opportunity to save that content (e.g. saving a WMV video file). This can be specified as either "attachment" or "inline". It can be used to override the default value of the Content-Disposition HTTP header passed back to the application (or browser). The default is "attachment" in min_rate_data mode, and to not include the header in streaming mode. |
| Parameter: |
|
| Type: |
not required (for downloads/min_rate_data); optional (for streaming) – parameter is ignored for downloads/min_rate_data (DNA will only use 1 HTTP connection); for streaming the default value is 2. |
| Values: |
any positive integer |
| Explaination: |
When using the streaming service, the ability make more than one HTTP connection can provide robustness to a stream. This helps provide path diversity as well as on the internet as well as mitigate potential problems with TCP stalling. The effect of min_http_connections is applied across however many URLs are specified for a particular piece of content. E.g. if the content is specified as available from only one URL, then DNA will open more than one connection with the same origin server. In the case that the content is available from 2 or more URLs, then the connections will be spread among the available URLs. The default value for streaming is 2. In most cases this will be the best value. There may be some cases where additional connections may be useful although greatly increasing the number of concurrent HTTP connections may have negative consequences for robust delivery. |
Additional Streaming Considerations
Performance of the DNA streaming service relies to some extent on the type of file that is being streamed. While all stream-able formats are supported, it is highly recommended that you use an encoding method that is optimized for streaming over a communications network rather than local playback only. This is a condition set at the time the encoding is made, not necessarily just a matter of which codec is used.
More specifically, you ought to use an encoding method such as “Constant Bit Rate” / “CBR” with a reasonably small “Video Buffering Verifier” / ”VBV” / buffer size. As a rule of thumb, if a file can be successfully streamed over a network without DNA, then there should be no problem with using DNA to stream that same piece of content.
In the case that an end user has a connection speed that is slower than the average bitrate of the encoded file, there will be playback problems (either a long wait until playback begins or else recurring buffer under-runs as the player stalls while waiting for more content to arrive.) This is a problem that is independent of whether or not you use DNA.
DNA will perform no worse than HTTP in delivering the content, but it will also not be able to increase the speed of an end-user’s last-mile connection, and will not allow streaming to take place at a rate that is theoretically possible using only HTTP.
In cases where origin servers or CDN servers have problems in “saturating” the available last mile connection of an end user, if DNA is used to combine more than one origin server connected to the same end user, DNA can actually improve performance by improving the chances that the last mile pipe is indeed “saturated”.
DNA recognizes the following file extensions and MIME types as stream-able:
Extensions: 3gp, 3g2, aac, aif, aiff, asf, au, divx, flv, m1v, m2v, m4v, mkv, mka, mp1, mp2, mp3, mp4, m4a, mpa, mpg, mpeg, mov, moov, qt, ogg, ogm, ogv, oga, ogx, ram, rm, swa, vob, wav, wma, wmv.
MIME types: video/x-ms-wmv, video/mp4, video/mpeg, audio/mpeg, video/x-m4v.
