# IVS Player SDK: Android Guide
<a name="player-android"></a>

The Amazon Interactive Video Service (IVS) Android player SDK provides the interfaces required to use the Amazon IVS player on Android.

We guarantee playback performance only for Android mobile devices (phones and tablets). We do not support Android TV, Fire TV, IoT devices, and emulators.

The `com.amazonaws.ivs.player` package implements the interface described in this document. The following operations are supported: 
+ Set up (initialize) a player. 
+ Manage playback. 
+ Manage quality. 
+ Receive events. 
+ Receive errors. 

**Latest version of Android player:** 1.51.0 ([Release Notes](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/release-notes.html#apr16-26-player-mobile-ll)) 

**Reference documentation:** For information on the most important methods available in the Amazon IVS Android player, see the reference documentation at [https://aws.github.io/amazon-ivs-player-docs/1.51.0/android/](https://aws.github.io/amazon-ivs-player-docs/1.51.0/android/).

**Sample code: **See the Android sample repository on GitHub: [https://github.com/aws-samples/amazon-ivs-player-android-sample](https://github.com/aws-samples/amazon-ivs-player-android-sample).

**Platform requirements:** Android 6.0\$1

A **React Native wrapper** for the Amazon IVS Player SDK is available. For the code and documentation, see [https://github.com/aws/amazon-ivs-react-native-player](https://github.com/aws/amazon-ivs-react-native-player).

# Getting Started with the IVS Android Player SDK
<a name="android-getting-started"></a>

This document takes you through the steps involved in getting started with the Amazon IVS Android player SDK.

## Install the Library
<a name="android-install"></a>

To add the Amazon IVS Android player library to your Android development environment, add the library to your module’s `build.gradle` file, as shown here (for the latest version of the Amazon IVS player).

```
repositories {
    mavenCentral()
}
 
dependencies {
     implementation 'com.amazonaws:ivs-player:1.51.0'
}
```

Alternately, to install the SDK manually, download the latest version from this location:
+ [https://search.maven.org/artifact/com.amazonaws/ivs-player](https://search.maven.org/artifact/com.amazonaws/ivs-player)

## Using the SDK with Debug Symbols
<a name="player-android-using-debug-symbols-ll"></a>

We also publish a version of the Android player SDK which includes debug symbols. You can use this version to improve the quality of debug reports (stack traces) in Firebase Crashlytics, if you run into crashes in the IVS player SDK; i.e., `libplayercore.so`. When you report these crashes to the IVS SDK team, the higher quality stack traces make it easier to fix the issues.

To use this version of the SDK, in your Gradle build files, replace this line:

```
implementation "com.amazonaws:ivs-player:$version@aar"
```

with this:

```
implementation "com.amazonaws:ivs-player:$version:unstripped@aar"
```

### Uploading Symbols to Firebase Crashlytics
<a name="player-android-debug-symbols-ll-firebase-crashlytics"></a>

Ensure that your Gradle build files are set up for Firebase Crashlytics. Follow Google’s instructions here:

[https://firebase.google.com/docs/crashlytics/ndk-reports](https://firebase.google.com/docs/crashlytics/ndk-reports)

Be sure to include `com.google.firebase:firebase-crashlytics-ndk` as a dependency.

When building your app for release, the Firebase Crashlytics plugin should upload symbols automatically. To upload symbols manually, run either of the following:

```
gradle uploadCrashlyticsSymbolFileRelease
```

```
./gradlew uploadCrashlyticsSymbolFileRelease
```

(It will not hurt if symbols are uploaded twice, both automatically and manually.)

### Preventing your Release .apk from Becoming Larger
<a name="player-android-debug-symbols-ll-sizing-apk"></a>

Before packaging the release `.apk` file, the Android Gradle Plugin automatically tries to strip debug information from shared libraries (including the IVS player SDK's `libplayercore.so` library). However, sometimes this does not happen. In that case, your `.apk` file could become larger and you could get a warning message from the Android Gradle Plugin that it’s unable to strip debug symbols and is packaging `.so` files as is. If this happens, do the following:
+ Install an Android NDK. Any recent version will work.
+ Add `ndkVersion <your_installed_ndk_version_number>` to your application’s `build.gradle` file. Do this even if your application itself does not contain native code.

For more information, see this [issue report](https://issuetracker.google.com/issues/353554169).

## Create the Player and Set Up Event Listener
<a name="android-create-player"></a>

The player interface is `com.amazonaws.ivs.player.Player`. Initialize it as shown below:

```
// Create a player instance
// <this> refers to the current Android Activity
player = Player.Factory.create(this);

// Set up to receive playback events and errors 
player.addListener(this);
```

Alternately, initialize by using `PlayerView`:

```
// Create a player instance
// <this> refers to the current Android Activity
PlayerView playerView = new PlayerView(this);
Player player = playerView.getPlayer();
// Set up to receive playback events and errors 
player.addListener(this);
```

**Note:** The listener callback methods are executed in the main thread of your Android application.

## Set the Surface View for Video
<a name="android-set-surface-view"></a>

If not using `PlayerView` add a `SurfaceView` to your Android UI layout for displaying a video. This `Surface` must be available before you can play any video streams. You can access the underlying surface through the `SurfaceHolder` interface, which is retrieved by calling `getHolder()`. (See [SurfaceView](https://developer.android.com/reference/android/view/SurfaceView.html) in the Android developer reference). Use the `SurfaceHolder.Callback` to receive events about surface changes (see [SurfaceHolder.Callback](https://developer.android.com/reference/android/view/SurfaceHolder.Callback)).

```
surfaceView = (SurfaceView) findViewById(R.id.surfaceView);
surfaceView.getHolder().addCallback(this);

@Override
public void surfaceCreated(SurfaceHolder holder) {
   this.surface = holder.getSurface();
   if (player != null) {
       player.setSurface(this.surface);
   }
}

@Override
public void surfaceDestroyed(SurfaceHolder holder) {
   this.surface = null;
   if (player != null) {
       player.setSurface(null);
   }
}
```

## Play a Stream
<a name="android-play-stream"></a>

Because the stream is loaded asynchronously, the player must be in a `READY` state before your application can call the `play` method to begin playback. Use the `Player.Listener` interface to determine when the player is in the correct state.

See the following sample code:

```
player.load(Uri.parse(url));

@Override
public void onStateChanged(Player.State state) {
    switch (state) {
        case BUFFERING:
            // player is buffering
            break;
        case READY:
            player.play();
            break;
        case IDLE:
            break;
        case PLAYING:
            // playback started
            break;
     }
}
```

## Release the Player
<a name="android-release-player"></a>

The `player.release()` method *must* be called when the player is no longer in use, to free the resources used by the library. Typically this is done in the `onDestroy` callback of the Activity or Fragment containing the player.

```
@Override
protected void onDestroy() {
    super.onDestroy();
    player.removeListener(this);
    player.release();
}
```

After the `player.release()` method is called the player can no longer be used.

## Permissions
<a name="android-permissions"></a>

The Android player SDK requires the following permission: 

```
<uses-permission android:name="android.permission.INTERNET" />
```

In addition, these optional permissions can improve the playback experience: 

```
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
```

## Thread Safety
<a name="android-thread-safety"></a>

The player API is not thread safe. All calls made to a player instance should be from the same thread.

## SDK Size
<a name="android-sdk-size"></a>

The Amazon IVS player SDKs are designed to be as lightweight as possible. For current information about SDK size, see the [Release Notes](release-notes.md).

**Important:** When evaluating size impact, the size of the AAB/APK produced by Android Studio is not representative of the size of your app downloaded to a user’s device. The Google Play Store performs optimizations to reduce the size of your app. We recommend that you use [Android App Bundles](https://developer.android.com/guide/app-bundle) to serve optimized apps for each device configuration.

# Known Issues & Workarounds in the IVS Android Player SDK
<a name="android-issues"></a>

This document lists known issues that you might encounter when using the Amazon IVS Android player SDK and suggests potential workarounds.
+ The Android player SDK has a runtime dependency on OkHttp version 4.x. Using OkHttp version 3.x may cause instability or crashes due to an API signature mismatch and OkHttp backwards compatibility issues. Specifically, the player depends on OkHttp version 4.2.2, but it should be compatible with any 4.x version.

  **Workaround:** Use a 4.x version of OkHttp or remove OkHttp from your application.
+ When using an Android 11 (API level 30) emulator, you may experience video-layout issues (specifically, zooming of the stream).

  **Workaround:** Play back on the real device instead.