Skip to main content

Media3 Exoplayer

Media3 ExoPlayer is the newest and native video player for Android, created and maintained by Google until version 2.19.1.

note

The QUANTEEC plugin documentation on this page is only for the newest versions of ExoPlayer that are contained in the package "androidx.media3:media3-exoplayer."

Compatibility with Media3 ExoPlayer and QUANTEEC plugin​

The QUANTEEC plugin has been tested for version 1.30 until version 1.3.1 of Media3 ExoPlayer. For each major version of Media3 ExoPlayer (1.0.X, 1.1.X ...) you must used the corresponding version of the QUANTEEC Exoplayer adapter.

Exoplayer VersionQUANTEEC Media3 Exoplayer Adapter to use
1.3.Xcom.quanteec:quanteecMedia3Exoplayer:1.4.1
1.2.Xcom.quanteec:quanteecMedia3Exoplayer:1.4.1
1.1.Xcom.quanteec:quanteecMedia3Exoplayer:1.4.1
1.0.Xcom.quanteec:quanteecMedia3Exoplayer:1.4.1

Add QUANTEEC plugin as a dependency​

Add QUANTEEC plugin modules​

The easiest way to get started using QUANTEEC plugin with Media3 ExoPlayer is to add Gradle dependencies to the libraries you need.

First, you need to declare the QUANTEEC Maven repository with your credentials. This declaration must be made in your settings.gradle file or build.gradle file, depending on the configuration of your project.

repositories {
  ...
  maven {
      url 'https://maven.quanteec.com/repository/internal/'
      credentials {
        username "username"
        password "password"
      }
      authentication {
        basic(BasicAuthentication)
      }
  }
}
info

To obtain your credentials for QUANTEEC Maven repository, please contact us by mail.

Then, you can add the dependencies in your build.gradle file of your app module:

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

}

Where 1.4.1 is your preferred version. All the modules must have the same version. The com.quanteec:quanteecExoPlugin library can be changed according to your Media3 Exoplayer version as explained above

Setting up the permissions​

In order to function correctly, QUANTEEC plugin needs to have access to the network state of the Android devices. The network state is used to determine the type of network your device uses (mobile, wi-fi, or Ethernet) and adapt the behavior of the plugin to download segments.

Add the following permissions in the AndroidManifest.xml of your app module:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Create the QUANTEEC elements​

Create the QUANTEEC Core​

You can create a QuanteecMedia3ExoCore instance first by creating a QuanteecConfig instance, which will describe the initial configuration of the QUANTEEC plugin. Next, you can create a QuanteecMedia3ExoCore instance using the QuanteecConfig you created as one of its parameters. The following code is the simplest example of creating an instance:

val quanteecConfig = QuanteecConfig.Builder("<your-quanteec-key>").setVideoID("<enter-your-custom-videoID>").build();
val quanteecCore = QuanteecMedia3ExoCore(context, quanteecConfig);
note

The creation of a QuanteecConfig instance with a Builder is only available for versions 1.3.0 and later. For older versions you must use a constructor :

val quanteecConfig = QuanteecConfig("<enter-your-custom-videoID>", "<your-quanteec-key>");
val quanteecCore = QuanteecMedia3ExoCore(context, quanteecConfig);
warning

In your QUANTEEC configuration, remember to set a different videoID if you have different formats of the same stream (e.g., one DASH stream and one HLS stream) or two variants of the same stream (one stream with English audio and one stream with another language).

Click here to find more informations on videoID

Create the QUANTEEC Datasource Factory​

The QUANTEEC Datasource will receive requests from the Media3 ExoPlayer instance and will forward them to the quanteecCore created, which in turn will download the requested data. A QUANTEEC data source factory instance will allow Media3 Exoplayer to create QUANTEEC Datasource instances to download the data it needs. The following code is the simplest example of creating a QUANTEEC Datasource Factory instance:

val quanteecDataSourceFactory = QuanteecBaseDataSource.Factory(quanteecCore);

Create the QUANTEEC Bandwidth meters​

In order to avoid the users' quality changing frequently due to the way the data is downloaded through QUANTEEC (from CDN or P2P), we slightly change the way the bandwidth of the user is calculated when using QUANTEEC through a custom BandwidthMeter called QuanteecBandwidthMeters. The following code is the simplest example of creating a QuanteecBandwidthMeters instance:

val quanteecBandwidthMeters = QuanteecBandwidthMeters.Builder(context).build();

Attach the QUANTEEC elements to Media3 ExoPlayer​

To be functional, the QuanteecCore and the QuanteecBandwidthMeters created must be attached to a Media3 ExoPlayer instance during its creation. The following code shows an example of how to attach QUANTEEC elements to a Media3 ExoPlayer instance:

val mExoPlayer = remember(mContext) {
    ExoPlayer.Builder(mContext).setMediaSourceFactory(DefaultMediaSourceFactory(mContext).setDataSourceFactory(quanteecDataSourceFactory) 
    ).setBandwidthMeter(quanteecBandwidthMeters
    ).build().apply {
        val mediaItem = MediaItem.Builder(
        ).setUri(Uri.parse("your-video-url")
        ).build()

       setMediaItem(mediaItem)

        playWhenReady = true
        }
}

Register Media3 ExoPlayer instance inside QUANTEEC Core​

Once created, the player instance must be registered inside the QUANTEEC core. The following code shows how to register a Media3 ExoPlayer instance inside a QUANTEEC Core:

quanteecCore.setPlayer(mExoPlayer);
tip

Good practice: try-catch block​

One good practice is to encapsulate the instantiation of the QUANTEEC object within a try-catch block. This approach provides a robust mechanism for handling situations where QUANTEEC might not be available or may encounter compatibility issues.

Error handling​

Embedding QUANTEEC in an Android app involves configuring and initializing the QUANTEEC plugin instance. If any issues arise during this process, such as missing dependencies or runtime errors, a try-catch block allows you to catch and handle these errors gracefully.

Unusual environments​

Android devices and versions vary, and not all devices may support certain features or configurations of QUANTEEC. Wrapping the QUANTEEC initialization in a try-catch block allows you to account for scenarios where certain features might not be available on the user's device or where there are compatibility issues with the Android version.

QUANTEEC plugin and Android activity lifecycle​

In order to manage efficiently the ressources used by the QUANTEEC plugin, it's important to take into account the activity lifecycle during the development of your application.

note

Releasing the ressources used by the Android plugin are not mandatory. But, if the application goes into background without doing it, the plugin will always be connected to others peer and will be able to send them data. This will happen even if you release the Media3 Exoplayer instance or stop the playback.

When you're application goes into background you have to possibiliy to free the ressources used by QUANTEEC. The first one is to totally release the QUANTEEC plugin by using this code for example :

quanteecCore?.release();
quanteecCore = null;

In this case when your application come back in the foreground you'll have to recreate a new QUANTEEC plugin instance and link it to the player.

The second possibility is just to deactivate the plugin by using the function quanteecCore.activateQuanteec(false). This function will totally deactivate the use of QUANTEEC plugin. To activate it again all you have to do is to called quanteecCore.activateQuanteec(true) when the application came back in the foreground. With this method, the reactivation of the QUANTEEC plugin will be faster. However some ressources, especially store in memory will not be free with such method.