Getting Started with the IVS Android Player SDK

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

Install the Library

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.37.0'
}

Alternately, to install the SDK manually, download the latest version from this location:

Create the Player and Set Up Event Listener

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

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 in the Android developer reference). Use the SurfaceHolder.Callback to receive events about surface changes (see 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

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

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

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

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

SDK Size

The Amazon IVS player SDKs are designed to be as lightweight as possible. For current information about SDK size, see the Release Notes.

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 to serve optimized apps for each device configuration.