Media3 pipeline for Android

The THEOplayer Android Media3 pipeline is a new and rebuilt base layer for playback of video and audio files for the THEOplayer Android SDK. 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.

Usage

The Media3 pipeline is part of the THEOplayer Android SDK. Follow our Getting Started guide to set up THEOplayer in your Android app.

info

In THEOplayer version 8.x, the Media3 pipeline was available as a separate integration package. Starting with version 9.0, this pipeline is now part of the THEOplayer Android SDK itself.

See our migration guide for instructions on how to migrate from the Media3 integration package to the built-in version.

Playback using Media3

By default, THEOplayer will play all types of sources (except Millicast) using the Media3 playback pipeline.

You can opt in or opt out of this behavior by setting TypedSource.playbackPipeline to either PlaybackPipeline.MEDIA3 (to always use Media3 playback) or PlaybackPipeline.LEGACY (to never use Media3 playback).

Kotlin

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

Java

TypedSource typedSource = new 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();

SourceDescription sourceDescription = new SourceDescription
    .Builder(typedSource)
    .build();

theoPlayerView.getPlayer().setSource(sourceDescription);

Caching and offline playback with Media3

By default, THEOplayer will cache sources using the Media3 storage backend. Sources cached with this backend can only be played using the Media3 playback pipeline.

You can opt in or opt out of this behavior by setting CachingParameters.storageType to either CacheStorageType.MEDIA3 (to always use Media3 caching) or CacheStorageType.LEGACY (to never use Media3 caching) when creating your caching task.

Kotlin

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

Java

Cache cache = THEOplayerGlobal.getSharedInstance(context).getCache();
SourceDescription 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();
CachingParameters cachingParameters = CachingParameters.Builder()
    .storageType(CacheStorageType.MEDIA3)
    .build();
CachingTask cachingTask = cache.createTask(sourceDescription, cachingParameters);
cachingTask.start();

Known limitations

Media3 playback is ready for production use and should work with most streams. However, there are currently some features and use cases that are not yet fully supported:

• The metrics API is not yet implemented and returns dummy values.
• Sources cached with the Media3 backend (CacheStorageType.MEDIA3) cannot be played using the legacy playback pipeline (PlaybackPipeline.LEGACY).
• THEOplayerConfig.networkConfiguration is not yet supported.
• THEOplayerGlobal.playbackSettings is not supported.

FAQ

How does Media3 affect the THEOplayer Android SDK?

Media3 replaces the media playback 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 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.