Amazon IVS Player SDK: Android Guide - Amazon Interactive Video Service

Amazon IVS Player SDK: Android Guide

The Amazon Interactive Video Player (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, and IoT devices.

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.17.0 (Release Notes)

Reference documentation: For information on the most important methods available in the Amazon IVS Android player, see the reference documentation at

Sample code: See the Android sample repository on GitHub:

Platform requirements: Android 5.0 (Lollipop) or greater is required for development.

A React Native wrapper for the Amazon IVS Player SDK is available. For the code and documentation, see

Getting Started

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.17.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 PlayerActivity class 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 PlayerActivity class 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(; 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:; 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.


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. You should create and use a player instance from one thread; typically this is the application main 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.

Known Issues and Workarounds

Please report all issues to Amazon IVS Support.

  • 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.