Getting started with THEOplayer for Millicast on Android

Usage

1. Follow our Getting Started guide to set up THEOplayer in your Android app.
2. Add the integration-millicast dependency to your module's build.gradle.
3. Add the MillicastIntegration to the player.
4. Add a MillicastSource to your player's source.

Add the integration-millicast dependency

Add the Millicast integration along with the Millicast SDK to your module build.gradle file, as demonstrated below:

dependencies {
    // ...
    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-millicast:+'
    // ...
}

This table defines which Millicast SDK version is integrated in which THEOplayer version:

THEOplayer version	Millicast SDK version
11.5.0+	2.6.+
11.3.0 – 11.4.x	2.5.+
10.11.0 – 11.2.+	2.5.3
9.12.0 – 10.10.+	2.5.0
9.7.0 – 9.11.+	2.4.3
9.6.0 – 9.6.+	2.4.2
8.10.0 – 9.5.+	2.0.0

Add the Millicast integration to the player

tip

If you're using automatic integrations, you can skip this step.

Create and add the MillicastIntegration to your THEOplayerView:

val millicastIntegration = MillicastIntegrationFactory.createMillicastIntegration()
theoplayerView.player.addIntegration(millicastIntegration)

Add a MillicastSource

After setting up a THEOplayerView in your app's activity, set its source to a SourceDescription containing a MillicastSource. You'll need a Millicast account ID and stream name to identify your Millicast stream:

import com.theoplayer.android.api.millicast.MillicastSource

theoplayerView.player.source = SourceDescription.Builder(
    MillicastSource(
        src = "multiview",
        streamAccountId = "k9Mwad",
        apiUrl = "https://director.millicast.com/api/director/subscribe",
        subscriberToken = "<token>" // This is only required for subscribing to secure streams and should be omitted otherwise.
    )
).build()

Add configuration

Optionally, you can provide additional configuration to the source, specific for working with Millicast streams. To configure these settings, add an Option object as the connectOptions parameter of the source object and specify the options.

In the example below, the configuration is used to disable any audio from the Millicast stream. For an exhaustive list of these options, visit the documentation.

import com.millicast.subscribers.Option
import com.theoplayer.android.api.millicast.MillicastSource

theoplayerView.player.source = SourceDescription.Builder(
    MillicastSource(
        // ...
        connectOptions = Option(
            disableAudio = true
        )
    )
).build()

Limit the maximum resolution

Since THEOplayer 11.5.0, you can cap the resolution of a Millicast stream through abr.preferredMaximumResolution. You can set it before playback starts, or change it during playback, for example when the device rotates between portrait and landscape. Changes are applied without reconnecting to the stream, and the media server keeps switching between the layers within that limit when network conditions change.

import android.util.Size

// Limit playback to layers of at most 1280x720
theoplayerView.player.abr.preferredMaximumResolution = Size(1280, 720)

// Remove the limit and use the full ABR range again
theoplayerView.player.abr.preferredMaximumResolution = null

Selecting a specific video quality through targetQuality pins playback to that layer and turns off ABR. While a quality is pinned, preferredMaximumResolution is ignored.

Background playback

Known issue on Android Millicast background playback

Currently there is a known issue where after an indeterminate amount of time background playback of Millicast sources can stop playing unexpectedly. This issue is being investigated and will be fixed in an upcoming release.

In order to play Millicast sources in the background, ensure you've configured allowing background playback using the setAllowBackgroundPlayback API on the player.

More information

• API references