CDN selector

warning

This feature is experimental.

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

In your Gradle file, replace :

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

}

By:

repositories {
  dependencies {
        ...
      implementation "com.quanteec:quanteecMedia3ExoplayerSelector:1.8.5"
      implementation "com.quanteec:quanteecPluginSelector:1.8.5"
    }

}

Do forget to keep the Media3 wrapper:

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

Get started

The CDN selector instance can be reached with:

Kotlin

val cdnSelector = quanteecCore.cdnSelector

Java

CDNSelector cdnSelector = quanteecCore.getCDNSelector();

Then, the different URLs can be set with:

Kotlin

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

Java

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);

The URLs can be set in the configuration object with:

Kotlin

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()

Java

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();

Behavior

The CDN selector uses QoS/QoE metrics to select the appropriate server. Everytime a HTTP request is started, the CDN selector monitor and saves the QoS/QoE metrics: observed bandwidth, time-to-first-byte, number of stalls over a time period. The CDN selector can start background header or range requests in the background to test other servers.

The CDN selector can select another server because a server fails to deliver the requests in time or because another server with better stats have 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).

API

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

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

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

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());
};

// Anonymous class implementation
CDNUrlListener listener = new CDNUrlListener() {
    @Override
    public void onCDNUrlSelected(CDNUrl oldCdnUrl, CDNUrl newCdnUrl) {
        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

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());
    }
};

// Anonymous class implementation
CDNStatListener listener = new CDNStatListener() {
    @Override
    public void onStatUpdated(List<CDNStat> 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);