Skip to main content
Version: 8.14.0

Getting started with Media3 on Android

The THEOplayer Android Media3 pipeline is a new integration for the THEOplayer Android SDK that serves as a new and rebuilt base layer for playback of video and audio files. It is based on Jetpack Media3 components, and it provides more stable playback covering a broader range of use cases, all while being lighter in size and more performant. Note that the integration is still under active development, see the Known limitations section for more information.

Usage​

  1. Follow our Getting Started guide to set up THEOplayer in your Android app.
  2. Add the Media3 integration as a dependency in your module-level build.gradle file.
  3. Add the Media3 integration to the player.

Add the Media3 integration dependency​

Add the Media3 integration as a dependency in your module-level build.gradle file:

dependencies {
    implementation "com.theoplayer.theoplayer-sdk-android:core:8.+"
    implementation "com.theoplayer.theoplayer-sdk-android:integration-media3:8.+"
}

Add the Media3 integration to the player​

To make use of the Media3 integration, create and add the Media3Integration to your THEOplayerView:

val media3Integration = Media3IntegrationFactory.createMedia3Integration()
theoplayerView.player.addIntegration(media3Integration)

Once the Media3Integration is added to the player, all subsequent sources set on the player will use the Media3 pipeline.

val typedSource = TypedSource
    .Builder("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
    .type(SourceType.DASH)
    .build()

val sourceDescription = SourceDescription
    .Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription

By default, the Media3Integration will play all types of sources except Millicast. You can opt in or opt out of this behavior by setting TypedSource.playbackPipeline to either PlaybackPipeline.MEDIA3 (to always use the Media3 integration) or PlaybackPipeline.LEGACY (to never use the Media3 integration).

val typedSource = TypedSource
    .Builder("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
    .type(SourceType.DASH)
    .playbackPipeline(PlaybackPipeline.MEDIA3)
    .build()

val sourceDescription = SourceDescription
    .Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription

Caching and offline playback with Media3​

The Media3 integration supports playing all sources cached by the default pipeline. However, you can also choose to use the Media3 integration to cache sources, allowing it to more optimally read and write files from the cache.

To use Media3 for caching, create and add the Media3Integration to the global Cache API:

val cache = THEOplayerGlobal.getSharedInstance(context).cache
val media3Integration = Media3IntegrationFactory.createMedia3Integration()
cache.addIntegration(media3Integration)
note

The Media3Integration object does not need to be the same instance that you use in player.addIntegration(), it's okay to create a different one.

Then, set CachingParameters.storageType to CacheStorageType.MEDIA3 when creating your caching task:

val cache = THEOplayerGlobal.getSharedInstance(context).cache
val sourceDescription = SourceDescription.Builder(
    TypedSource.Builder("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
        .playbackPipeline(PlaybackPipeline.MEDIA3)
        .build()
    ).build()
val cachingParameters = CachingParameters.Builder()
    .storageType(CacheStorageType.MEDIA3)
    .build()
val cachingTask = cache.createTask(sourceDescription, cachingParameters)
cachingTask.start()

Known limitations​

As this integration is still under development, there are currently some known limitations and features that are still under development and not yet supported:

  • The metrics API is not yet implemented and returns dummy values.

FAQ​

When should I use the Media3 integration?​

The Media3 integration is being built to improve stability and performance. If you're targeting performance restricted devices and/or aiming to broaden your device coverage, and you have encountered playback issues on particular device segments, we recommend trying out the Media3 integration.

How does this integration affect the THEOplayer Android SDK?​

This integration replaces the media playback base layer of the THEOplayer Android SDK, offering improvements in performance and stability for playback over our current implementation. As only core media playback is affected, all player APIs remain identical and other features and integrations (such as ads, analytics or Chromecast) are not affected and will function the same. See the Known limitations section for more info on what features might currently be affected.

Does this integration use ExoPlayer?​

While we make use of ExoPlayer components, this is not a plain ExoPlayer implementation. In addition to the integrations, features and support already offered by the THEOplayer Android SDK, we've reused what makes sense to implement our own playback pipeline that offers improvements, bugfixes and additional functionality over ExoPlayer.

Will this integration replace the current THEOplayer Android playback pipeline?​

We are developing this integration to offer significant improvements over our current playback implementation on Android. While currently this is still under development, the goal is for this pipeline to become the default playback pipeline for the THEOplayer Android SDK starting with version 9.0.0.

More information​