Skip to main content
Version: 10.0.0

Migrating to THEOplayer Android SDK 10.x

This article will guide you through updating from THEOplayer Android SDK version 10 (from version 9), and the changes needed in your code.

Update THEOplayer​

Update THEOplayer Android SDK to version 10 in your module-level build.gradle file:

dependencies {
    implementation 'com.theoplayer.theoplayer-sdk-android:core:10.+'
}

If you're using the Open Video UI for Android or one of our connectors, make sure to update them to the latest version too to ensure proper support for THEOplayer version 10.

Update minSdkVersion to API 23 or higher​

The minimum supported Android version of the THEOplayer Android SDK has been raised from API 21 (Android 5.0 "Lollipop") to API 23 (Android 6.0 "Marshmallow"). This aligns with other Android Jetpack libraries requiring API 23 as of June 2025.

Update the minSdkVersion to be 23 (or higher) in your module-level build.gradle file:

android {
    defaultConfig {
        minSdkVersion 23
    }
}

Update compileSdk to 36 or higher​

THEOplayer depends on the AndroidX Core library, which requires compileSdk 36 as of version 1.17.0.

Update the compileSdk to be 36 (or higher) in your module-level build.gradle file:

android {
    compileSdk 36
}

We also recommend updating the Android Gradle Plugin to the latest version. In Android Studio, go to Tools → AGP Upgrade Assistant and follow the steps to update AGP in your project.

Update to Kotlin Gradle plugin 2.0.0 or higher​

THEOplayer now targets the Kotlin 2.0 language level, so you must build your app with Kotlin Gradle Plugin 2.0 or higher. This aligns with the AndroidX Core library also targeting Kotlin 2.0 as of version 1.17.0.

Update the version of the org.jetbrains.kotlin.android plugin to be 2.0.0 (or higher) in your project-level build.gradle file:

plugins {
    id 'org.jetbrains.kotlin.android' version '2.2.20' apply false
}

Media3 as single playback pipeline​

THEOplayer now always uses Jetpack Media3 as its playback pipeline, providing more stable playback on a wider range of devices. The legacy playback pipeline (from version 8.x) has been fully retired, and the TypedSource.playbackPipeline property has been removed.

Caching is now also handled by Media3. Any previously created caching tasks that used the legacy backend (using CachingParameters.storageType = CacheStorageType.LEGACY) will automatically be switched over to the Media3 backend, although their cached content will not be preserved. They can be re-downloaded by calling CachingTask.start() again.

See our Media3 guide for more information.

Use modern network stack by default​

THEOplayer will now use a modern network stack when available, to take advantage of their HTTP/2 and HTTP/3 support for more optimal media streaming.

The player supports both HttpEngine (available in Android 14 or higher) and Cronet (when added as a library to your app). When neither of these APIs are available, the player falls back to HTTP/1.1 using HttpURLConnection.

If you're not yet ready for this switch, you can opt out of this behavior and revert back to HttpURLConnection by setting NetworkConfiguration.useHttpEngine to false.

Replace usages of deprecated APIs​

Some properties and methods that were previously deprecated have been removed from the API. Update your code to use the new APIs instead.

  • Removed TypedSource.playbackPipeline and SourceChangeEvent.playbackPipeline. The player will now always use the Media3 playback pipeline.
  • Removed unused GoogleDaiConfiguration.format.
  • Removed MediaTailorSource.adParams. Use MediaTailorSource.adsParams instead.
  • Removed the DashPlaybackConfiguration.ignoreAvailabilityWindow() method. Use the .ignoreAvailabilityWindow property instead.
  • Removed KeySystemConfiguration.isUseCredentials. Use KeySystemConfiguration.useCredentials instead.
  • Removed ConaxDRMConfiguration.Builder.fairPlay(). Use ConaxDRMConfiguration.Builder.fairplay() instead.
  • Removed THEOlive publication events (PublicationLoadStartEvent, PublicationLoadedEvent and PublicationOfflineEvent). Use the equivalent distribution events instead (DistributionLoadStartEvent, EndpointLoadedEvent and DistributionOfflineEvent respectively).
  • Removed THEOplayerGlobal.playbackSettings.