# Getting started with THEOplayer for Millicast on Android

## Usage

1. Follow our [Getting Started guide](https://docs-preview.optiview.dolby.com/pr-863/theoplayer/getting-started/sdks/android/getting-started.md) 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](https://docs-preview.optiview.dolby.com/pr-863/millicast/playback/players-sdks/android/sdk.md) to your module `build.gradle` file, as demonstrated below:

```groovy
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](https://docs-preview.optiview.dolby.com/pr-863/theoplayer/getting-started/sdks/android/features.md#adding-integrations-automatically), you can skip this step.

Create and add the `MillicastIntegration` to your `THEOplayerView`:

```kotlin
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:

```kotlin
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](https://millicast.github.io/doc/latest/android/android/com.millicast.subscribers/-option/index.html).

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

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

### 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](https://www.theoplayer.com/docs/theoplayer/v8/api-reference/android/com/theoplayer/android/api/THEOplayerSettings.html#setAllowBackgroundPlayback\(boolean\)) API on the player.

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-863/theoplayer/v11/api-reference/android/com/theoplayer/android/api/millicast/package-summary)