Skip to main content

CDN selector

warning

This feature is experimental, starting from version 1.8.16 on Android and 1.3.8 on Web.

The CDN selector allows to balance the client HTTP requests between several CDN. The CDN selector uses QoS/QoE metrics to select the most appropriate server.

Install​

No additional package is required. The CDN selector is included in all QUANTEEC web player plugins starting from version 1.3.8.

Get started​

Setting URLs via configuration​

The CDN URLs can be set directly in the QUANTEEC configuration object:

The servers parameter accepts an array of strings (base URLs) or objects with name, url, and useFirst properties:

// Simple string array
var quanteecConfig = {
quanteecKey: "<your-quanteec-key>",
videoID: "<enter-your-custom-videoID>",
servers: [
"https://server1.example.com",
"https://server2.example.com"
]
};

// Or with named CDN objects
var quanteecConfig = {
quanteecKey: "<your-quanteec-key>",
videoID: "<enter-your-custom-videoID>",
servers: [
{ name: "cdn1", url: "https://server1.example.com", useFirst: true },
{ name: "cdn2", url: "https://server2.example.com" }
]
};
warning

All of the URL of the CDNs must be provided to Quanteec, not only the alternative ones. Quanteec will modify the base URL of the requests only if the request is made to a URL that matches one of the provided CDN URLs.

Accessing the CDN selector instance​

var cdnSelector = myQuanteec.getCDNSelector();

Setting URLs at runtime​

The CDN URLs can also be set or updated at runtime via the CDN selector instance:

var cdnSelector = myQuanteec.getCDNSelector();

// Using string URLs (names are derived from hostnames)
cdnSelector.setUrls([
"https://server1.example.com",
"https://server2.example.com"
]);

// Or using named CDN objects
cdnSelector.setUrls([
{ name: "cdn1", url: "https://server1.example.com", useFirst: true },
{ name: "cdn2", url: "https://server2.example.com" }
]);

Behavior​

The CDN selector uses QoS/QoE metrics to select the appropriate server. Every time a HTTP request is started, the CDN selector monitors and saves the QoS/QoE metrics: observed bandwidth, time-to-first-byte, and failures over a rolling time window. The CDN selector is activated automatically when two or more CDN server URLs are configured.

The CDN selector can switch to another server because a server fails to deliver requests or because another server with better metrics has been found.

Starting from Android SDK 1.9.2, each HTTP request can be retried across every configured CDN. The selector tries each CDN up to maxRetry times before returning the failure to the player. The retry limit defaults to 2; set it to -1 to retry indefinitely. Retry counters are scoped to a single request, so a CDN that failed for one URL remains available for subsequent URLs.

To compute the CDN with the best stat:

factorBandwidth × cdnStat.average_bandwidth + factorTtfb × cdnStat.average_ttfb

Where factorBandwidth and factorTtfb are configurable weighting factors (default values are 1 and -10000 respectively).

A CDN is only promoted over the current selection if it has both a bandwidth and a TTFB measurement. A CDN also wins unconditionally if the currently selected CDN has a recent failure and the candidate does not (or its most recent failure is older).

Statistics are kept in a rolling window of up to 10 entries per metric, with entries older than 5 minutes automatically discarded.

On Android, the CDN selector also performs bounded background probing. When a manifest request provides an opportunity and the probe cadence is due, it sends a small range request to one non-selected CDN at a time, rotating between them. This keeps inactive CDN statistics up to date without blocking playback.

API​

CDN Selector​

The CDN selector is accessed via getCDNSelector() on the QUANTEEC instance:

var cdnSelector = myQuanteec.getCDNSelector();

Methods​

URL Management​
MethodReturn TypeDescription
getUrls()ArrayReturns the list of configured CDN URLs (as {name, url, useFirst} objects)
setUrls(cdnUrls)voidSets the CDN URLs. Accepts an array of strings or {name, url, useFirst} objects
getSelectedUrl()`Objectnull`
forceUrl(name)booleanForces the use of a specific CDN by name. Returns false if the name is not found
getAllPossibleUrl(url)ArrayReturns an array of URLs with the base CDN prefix replaced by each configured CDN
isActive()booleanReturns true if the CDN selector is active (2+ CDN URLs configured)
reset()voidClears all CDN URLs, statistics, and listeners. Called automatically when the plugin is destroyed
Statistics​
MethodReturn TypeDescription
getStats()ArrayReturns CDN statistics. Each entry has name, averageBandwidth, averageTtfb, mostRecentFail
Listener Management​
MethodDescription
addCDNStatListener(callback)Registers a callback function(stats) called when CDN statistics are updated
removeCDNStatListener(callback)Unregisters a CDN statistics callback
addCDNUrlListener(callback)Registers a callback function(oldCdnUrl, newCdnUrl) called when the selected CDN changes
removeCDNUrlListener(callback)Unregisters a CDN URL callback
Configuration Factors​
MethodReturn TypeDescription
getFactorBandwidth()numberReturns the bandwidth weighting factor (Default: 1)
setFactorBandwidth(value)voidSets the bandwidth weighting factor
getFactorTtfb()numberReturns the TTFB weighting factor (Default: -10000)
setFactorTtfb(value)voidSets the TTFB weighting factor

Usage Example​

var cdnSelector = myQuanteec.getCDNSelector();

// Check if CDN selector is active
console.log("Active:", cdnSelector.isActive());
console.log("Selected:", cdnSelector.getSelectedUrl()?.name);

// Listen for CDN switches
cdnSelector.addCDNUrlListener(function(oldCdn, newCdn) {
console.log("CDN switch: " + (oldCdn ? oldCdn.name : "none") + " → " + newCdn.name);
});

// Listen for stat updates
cdnSelector.addCDNStatListener(function(stats) {
stats.forEach(function(s) {
console.log(s.name + ": BW=" + s.averageBandwidth + ", TTFB=" + s.averageTtfb);
});
});

// Force a specific CDN
cdnSelector.forceUrl("cdn1");

// Adjust scoring factors
cdnSelector.setFactorBandwidth(1);
cdnSelector.setFactorTtfb(-10000);

CDNUrl​

On web, CDN URLs can be passed as simple strings or as objects:

PropertyTypeDefaultDescription
namestringhostname from URLCDN identifier name
urlstring—Base URL of the CDN
useFirstbooleanfalseIf true, this CDN is selected on startup

When passing strings, the name is automatically derived from the URL hostname.

CDNStat​

Each stat object returned by getStats() has the following properties:

PropertyTypeDescription
namestringCDN identifier name (matches the CDN URL name)
averageBandwidthnumberRolling average bandwidth in bits per second
averageTtfbnumberRolling average TTFB in milliseconds
mostRecentFailnumber|nullTimestamp (ms since epoch) of the most recent failure, or null

Events​

Two events are available to monitor the CDN selection and the stats.

CDNUrlListener​

cdnSelector.addCDNUrlListener(function(oldCdnUrl, newCdnUrl) {
console.log("CDN changed from " + (oldCdnUrl ? oldCdnUrl.name : "none")
+ " to " + newCdnUrl.name);
});

CDNStatListener​

cdnSelector.addCDNStatListener(function(stats) {
stats.forEach(function(stat) {
console.log("CDN: " + stat.name
    + ", BW: " + stat.averageBandwidth
    + ", TTFB: " + stat.averageTtfb);
});
});