CDN selector

warning

This feature is experimental, starting from version 1.8.16 on Android and 1.4.0 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

Web
Android

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

In your Gradle file, make sure you are using a version above 1.8.16 of the QUANTEEC plugin and the QUANTEEC Media3 Exoplayer adapter. The recommended one is 1.8.17.

repositories {
  dependencies {
        ...
      implementation "com.quanteec:quanteecMedia3Exoplayer:1.8.17"
      implementation "com.quanteec:quanteecPlugin:1.8.17"
    }

}

Get started

Setting URLs via configuration

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

Web
Android

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" }
]
};

Kotlin
Java

val urls = ArrayList<CDNUrl>()
urls.add(CDNUrl("cdn1","https://server1.example.com"))
urls.add(CDNUrl("cdn2","https://server2.example.com"))

val quanteecConfig = QuanteecConfig.Builder("<your-quanteec-key>")
.setVideoID("<enter-your-custom-videoID>")
.setCDNUrls(urls)
.build()

List<CDNUrl> listUrls = new ArrayList<CDNUrl>();
listUrls.add(new CDNUrl("cdn1","https://server1.example.com"));
listUrls.add(new CDNUrl("cdn2","https://server2.example.com"));

QuanteecConfig quanteecConfig = new QuanteecConfig.Builder("<your-quanteec-key>")
.setVideoID("<enter-your-custom-videoID>")
.setCDNUrls(listUrls)
.build();

Accessing the CDN selector instance

Web
Android

var cdnSelector = myQuanteec.getCDNSelector();

Kotlin
Java

val cdnSelector = quanteecCore.cdnSelector

CDNSelector cdnSelector = quanteecCore.getCDNSelector();

Setting URLs at runtime

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

Web
Android

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" }
]);

Kotlin
Java

val urls = ArrayList<CDNUrl>()
urls.add(CDNUrl("cdn1","https://server1.example.com"))
urls.add(CDNUrl("cdn2","https://server2.example.com"))
cdnSelector.urls = urls

List<CDNUrl> listUrls = new ArrayList<CDNUrl>();
listUrls.add(new CDNUrl("cdn1","https://server1.example.com"));
listUrls.add(new CDNUrl("cdn2","https://server2.example.com"));

cdnSelector.setUrls(listUrls);

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.

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.

The CDN selector also performs background probing: after each manifest download, it sends small range requests to non-selected CDNs to keep their statistics up-to-date, ensuring the selector can make informed switching decisions even for CDNs not currently serving content.

API

Web
Android

CDN Selector

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

var cdnSelector = myQuanteec.getCDNSelector();

Methods

URL Management

Method	Return Type	Description
`getUrls()`	`Array`	Returns the list of configured CDN URLs (as `{name, url, useFirst}` objects)
`setUrls(cdnUrls)`	`void`	Sets the CDN URLs. Accepts an array of strings or `{name, url, useFirst}` objects
`getSelectedUrl()`	`Object	null`
`forceUrl(name)`	`boolean`	Forces the use of a specific CDN by name. Returns `false` if the name is not found
`getAllPossibleUrl(url)`	`Array`	Returns an array of URLs with the base CDN prefix replaced by each configured CDN
`isActive()`	`boolean`	Returns `true` if the CDN selector is active (2+ CDN URLs configured)
`reset()`	`void`	Clears all CDN URLs, statistics, and listeners. Called automatically when the plugin is destroyed

Statistics

Method	Return Type	Description
`getStats()`	`Array`	Returns CDN statistics. Each entry has `name`, `averageBandwidth`, `averageTtfb`, `mostRecentFail`

Listener Management

Method	Description
`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

Method	Return Type	Description
`getFactorBandwidth()`	`number`	Returns the bandwidth weighting factor (Default: 1)
`setFactorBandwidth(value)`	`void`	Sets the bandwidth weighting factor
`getFactorTtfb()`	`number`	Returns the TTFB weighting factor (Default: -10000)
`setFactorTtfb(value)`	`void`	Sets 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);

CDNSelector

CDNSelector - Documentation

CDNSelector is a class that controls CDN selection.

Package

com.quanteec.plugin.core.models

Class Structure

Constructor

public CDNSelector(CDNSelectorInternal internal)

Creates an instance with an internal implementation.

Parameters:

internal : The internal CDN selector implementation

Methods

URL Management

Method	Return Type	Description
`getUrls()`	`List<CDNUrl>`	Retrieves the list of available CDN URLs
`setUrls(List<CDNUrl> cdnUrls)`	`void`	Sets the list of CDN URLs
`forceUrl(String name)`	`boolean`	Forces the use of a specific CDN by name

Statistics

Method	Return Type	Description
`getStats()`	`List<CDNStat>`	Retrieves CDN statistics

Listener Management

Method	Parameters	Description
`addCDNStatListener(CDNStatListener listener)`	`listener` : statistics listener	Registers a listener for CDN statistics updates
`removeCDNStatListener(CDNStatListener listener)`	`listener` : statistics listener	Unregisters a CDN statistics listener
`addCDNUrlListener(CDNUrlListener listener)`	`listener` : URL listener	Registers a listener for CDN URL changes
`removeCDNUrlListener(CDNUrlListener listener)`	`listener` : URL listener	Unregisters a CDN URL listener

Configuration Factors

Method	Return Type	Description
`getFactorBandwidth()`	`long`	Retrieves the bandwidth weighting factor
`setFactorBandwidth(long factorBandwidth)`	`void`	Sets the bandwidth weighting factor (Default: 1)
`getFactorTtfb()`	`long`	Retrieves the TTFB (Time To First Byte) weighting factor (Default: -10000)
`setFactorTtfb(long factorTtfb)`	`void`	Sets the TTFB weighting factor

CDNUrl

Web
Android

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

Property	Type	Default	Description
`name`	`string`	hostname from URL	CDN identifier name
`url`	`string`	—	Base URL of the CDN
`useFirst`	`boolean`	`false`	If `true`, this CDN is selected on startup

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

CDNUrl - Documentation

CDNUrl is a simple model class (POJO - Plain Old Java Object) that represents a CDN (Content Delivery Network) URL with its associated metadata.

Package

com.quanteec.plugin.core.models

Class Structure

Attributes

Attribute	Type	Description
`name`	`String`	CDN identifier name
`url`	`String`	Complete CDN URL
`useFirst`	`boolean`	Usage priority indicator

Constructors

Simple Constructor

public CDNUrl(String name, String url)

Creates an instance with a name and URL. The useFirst parameter defaults to false.

Parameters:

name : CDN name
url : CDN URL

Complete Constructor

public CDNUrl(String name, String url, boolean useFirst)

Creates an instance with all parameters.

Parameters:

name : CDN name
url : CDN URL
useFirst : Indicates if this CDN should be used first

Methods

Getters

Method	Return Type	Description
`getName()`	`String`	Retrieves the CDN name
`getUrl()`	`String`	Retrieves the CDN URL
`isUseFirst()`	`boolean`	Checks if this CDN has priority

Setters

Method	Parameters	Description
`setName(String name)`	`name` : new name	Modifies the CDN name
`setUrl(String url)`	`url` : new URL	Modifies the CDN URL
`setUseFirst(boolean useFirst)`	`useFirst` : new status	Modifies the CDN priority

CDNStat

Web
Android

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

Property	Type	Description
`name`	`string`	CDN identifier name (matches the CDN URL name)
`averageBandwidth`	`number`	Rolling average bandwidth in bits per second
`averageTtfb`	`number`	Rolling average TTFB in milliseconds
`mostRecentFail`	`number\|null`	Timestamp (ms since epoch) of the most recent failure, or `null`

CDNStat - Documentation

CDNStat is a model class that tracks and manages performance statistics for a CDN (Content Delivery Network), including bandwidth, TTFB (Time To First Byte), and failure metrics.

Package

com.quanteec.plugin.core.models

Class Structure

Attributes

Attribute	Type	Default	Description
`name`	`String`	-	CDN identifier name
`averageBandwidth`	`double`	`0`	Calculated average bandwidth
`averageTtfb`	`double`	`0`	Calculated average TTFB
`mostRecentFail`	`Date`	-	Timestamp of most recent failure
`maxListSize`	`int`	`10`	Maximum number of entries per metric list
`maxAgeMs`	`long`	`300000`	Maximum age of entries (5 minutes)
`listBandwidth`	`List<StatEntry>`	-	List of bandwidth measurements
`listTtfb`	`List<StatEntry>`	-	List of TTFB measurements
`listFails`	`List<StatEntry>`	-	List of failure events

Constructor

public CDNStat()

Creates an instance and initializes all metric lists.

Inner Class: StatEntry

Represents a single statistical measurement.

Attributes

Attribute	Type	Description
`timestamp`	`Date`	Time when the measurement was recorded
`value`	`double`	The measured value

Methods

Method	Return Type	Description
`getTimestamp()`	`Date`	Retrieves the timestamp
`setTimestamp(Date timestamp)`	`void`	Sets the timestamp
`getValue()`	`double`	Retrieves the value
`setValue(double value)`	`void`	Sets the value

Methods

Getters

Method	Return Type	Description
`getName()`	`String`	Retrieves the CDN name
`getAverageBandwidth()`	`double`	Retrieves the average bandwidth
`getAverageTtfb()`	`double`	Retrieves the average TTFB
`getMostRecentFail()`	`Date`	Retrieves the most recent failure timestamp

Setters

Method	Parameters	Description
`setName(String name)`	`name` : CDN name	Sets the CDN name

Events

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

CDNUrlListener

Web
Android

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

CDNUrlListener - Documentation

Overview

CDNUrlListener is a functional interface that defines a callback mechanism for receiving notifications when the active CDN URL changes.

Package

com.quanteec.plugin.core.models

Method

onCDNUrlSelected

public void onCDNUrlSelected(CDNUrl oldCdnUrl, CDNUrl newCdnUrl)

Called when the active CDN URL is changed.

Parameters:

oldCdnUrl : The previously active CDN URL
newCdnUrl : The newly selected CDN URL

Returns:

void

Usage Example

// Lambda implementation
CDNUrlListener listener = (oldUrl, newUrl) -> {
    Log.i("CDNSelector","CDN changed from " + oldUrl.getName() + " to " + newUrl.getName());
    Log.i("CDNSelector","Old URL: " + oldUrl.getUrl());
    Log.i("CDNSelector","New URL: " + newUrl.getUrl());
};

// Register with CDNSelector
CDNSelector selector = new CDNSelector(internal);
selector.addCDNUrlListener(listener);

CDNStatListener

Web
Android

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

CDNStatListener - Documentation

CDNStatListener is a functional interface that defines a callback mechanism for receiving updates when CDN statistics change.

Package

com.quanteec.plugin.core.models

Method

onStatUpdated

public void onStatUpdated(List<CDNStat> stats)

Called when CDN statistics are updated.

Parameters:

stats : List of updated CDN statistics

Returns:

void

Usage Example

// Lambda implementation
CDNStatListener listener = stats -> {
    for (CDNStat stat : stats) {
      Log.d("CDNSelector","CDN: " + stat.getName());
      Log.d("CDNSelector","Avg Bandwidth: " + stat.getAverageBandwidth());
      Log.d("CDNSelector","Avg TTFB: " + stat.getAverageTtfb());
    }
};

// Register with CDNSelector
CDNSelector selector = new CDNSelector(internal);
selector.addCDNStatListener(listener);

CDN selector

Install​

Get started​

Setting URLs via configuration​

Accessing the CDN selector instance​

Setting URLs at runtime​

Behavior​

API​

CDN Selector​

Methods​

URL Management​

Statistics​

Listener Management​

Configuration Factors​

Usage Example​

CDNSelector​

Package​

Class Structure​

Constructor​

Methods​

URL Management​

Statistics​

Listener Management​

Configuration Factors​

CDNUrl​

Package​

Class Structure​

Attributes​

Constructors​

Simple Constructor​

Complete Constructor​

Methods​

Getters​

Setters​

CDNStat​

Package​

Class Structure​

Attributes​

Constructor​

Inner Class: StatEntry​

Attributes​

Methods​

Methods​

Getters​

Setters​

Events​

CDNUrlListener​

Overview​

Package​

Method​

onCDNUrlSelected​

Usage Example​

CDNStatListener​

Package​

Method​

onStatUpdated​

Usage Example​

Install

Get started

Setting URLs via configuration

Accessing the CDN selector instance

Setting URLs at runtime

Behavior

API

CDN Selector

Methods

URL Management

Statistics

Listener Management

Configuration Factors

Usage Example

CDNSelector

Package

Class Structure

Constructor

Methods

URL Management

Statistics

Listener Management

Configuration Factors

CDNUrl

Package

Class Structure

Attributes

Constructors

Simple Constructor

Complete Constructor

Methods

Getters

Setters

CDNStat

Package

Class Structure

Attributes

Constructor

Inner Class: StatEntry

Attributes

Methods

Methods

Getters

Setters

Events

CDNUrlListener

Overview

Package

Method

onCDNUrlSelected

Usage Example

CDNStatListener

Package

Method

onStatUpdated

Usage Example