Android SDK Setup

1. System Requirements

The THEOplayer Android SDK can be used for Android devices using Android 4.1+ (minSdkVersion 16).

2. Importing the library

Importing the THEOplayer Android SDK Library can be done following these steps:

  1. In your Android Studio, go to File > New Module > Import .JAR / .AAR Package.
  2. Navigate to the location where the theoplayer SDK aar file is stored and select it.
  3. Go to your project dependencies by going to File > Project Structure > dependencies tab.
  4. Add a new dependency by clicking the plus sign in the top-right corner and choose Module Dependency. Select the THEOplayer SDK aar file and click OK.

Additionally, you can import the sources jar to be able to immediately see the API java source files with their documentation in Android Studio. Follow the following after successfully importing the library steps for that:

  1. In the Projects Overview, set the view to the project view. You should now see “External Libraries”
  2. Under “External Libraries” you should be able to find the theoplayer-android SDK library, right click and select “Library Properties”.
  3. In the top left corner of the Library Properties window, click the first green plus sign.
  4. Find and select the theoplayer-android SDK jar file and click ok.

3. Using the THEOplayerView

In order to use THEOplayer in an Android app, you will need the THEOplayerView as the central component. This class can be loaded in a Layout and this will create a new player object for you to interact with.

Important: In order to react to the activity state, users need to call the onResume, onPause and onDestroy when the matching methods are called in the activity using the THEOplayerView.

3.1. Setting up the THEOplayerView using XML

When using XML to set your layout, you can add the following code to your XML file:

<com.theoplayer.android.THEOplayerView
    android:id="@+id/theoplayer_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Once you have the THEOplayerView in your layout, you can get a reference to it by using the findViewById-method.

3.2. Setting up the THEOplayerView using Java

Next to using XML to configure your view, you can also instantiate the view programmatically in Java. This can be done in the following way:

THEOplayerView view = new THEOplayerView(activity);

This view can then be placed inside another view and positioned in your layout.

3.3. Add custom CSS and JavaScript

3.3.1 Register custom css and JavaScript files

If you want to use custom CSS or JavaScript files you can add the cssPaths and jsPaths properties to your layout.

When a relative path is used, it will be relative to the assets folder.

XML configuration

<com.theoplayer.android.api.THEOplayerView android:id="@+id/theo_player_view" android:layout_width="match_parent" android:layout_height="match_parent"
app:defaultCss="true" app:cssPaths="path/to/style1.css,path/to/style2.css"
app:jsPaths="path/to/script1.js,path/to/script2.js" /> 

Java configuration

THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
.chromeless(false)
.defaultCss(true)
.cssPaths("path/to/style1.css,path/to/style2.css")
.jsPaths("path/to/script1.js,path/to/script2.js")
.build();>THEOplayerView tpv = new THEOplayerView(this, playerConfig);

3.3.2 Custom CSS and the Chromeless flag

With the chromeless flag you can choose to use the chromeless version of the player which does not contain the THEOplayer UI. This allows you to write your own custom UI.

The THEOplayer css is not loaded when chromeless is enabled.

When chromeless is false, the THEOplayer UI is used. In that case the default style can still be disabled by setting the defaultCss flag to false.

 

4. Adding support for Chromecast

In order to enable chromecast, a few extra steps need and can be taken. These steps are described below.

4.1 Steps to enable Chromecast:

  1. Upgrade to the latest THEOplayer Android SDK release (≥ 1.0.9)
  2. To add chromecast support the first thing you need is to include the Cast Framework and Media Router libraries under the dependencies node in your build.gradle file.
    compile 'com.android.support:mediarouter-v7:25.3.1'
    compile 'com.google.android.gms:play-services-cast-framework:10.2.1'
  3. To enable chromecast on android a CastOptionsProvider should be specified. This class contains the configuration for chromecast on Android. A DefaultCastOptionsProvider is provided as part of the THEOplayer Android SDK. This OptionsProvider associates the THEOplayer chromecast receiver with your sender application. You will need to register this class in your AndroidManifest.xml file within a meta-data tag under your application node.
    <meta-data
            android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
            android:value="com.theoplayer.android.api.cast.chromecast.DefaultCastOptionsProvider"/>
    
    If you need custom settings for your chromecast (for example a custom receiver id) you can create your own CastOptionsProvider by subclassing com.google.android.gms.cast.framework.OptionsProvider and implementing the getCastOptions method.
    @Override
    public CastOptions getCastOptions(Context context) {
            return new CastOptions.Builder()
                .setReceiverApplicationId(DEFAULT_APP_ID)
                .build();
            }

4.2 Optional extra steps:

4.2.1 Add routing button to your app:

In order to get this button to appear in your application's Toolbar, the easiest way is to include it in the menu XML file for your Activity.

  1. In your res folder add a menu folder
  2. Add a activity_main.menu.xml file
  3. Add the following contents to this file
    <?xml version="1.0" encoding="utf-8"?>
    <menu xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto">
        <item
        android:id="@+id/media_route_menu_item"
        android:title="Cast"
        app:actionProviderClass="android.support.v7.app.MediaRouteActionProvider"
        app:showAsAction="always" />
    </menu>
  4. Initialize this new MenuItem in the onCreateOptionsMenu method of your Activity (Make sure you have an AppCompatActivity).
    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
            super.onCreateOptionsMenu(menu);
            getMenuInflater().inflate(R.menu.activity_main_menu, menu);
            CastButtonFactory.setUpMediaRouteButton(getApplicationContext(),
                menu, R.id.media_route_menu_item);
            return true;
            }
    

4.2.2 Add MiniController to your app:

  1. In your main activity xml add the following fragment
    <fragment
            android:id="@+id/castMiniController"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_alignParentBottom="true"
            android:visibility="gone"
            class="com.google.android.gms.cast.framework.media.widget.MiniControllerFragment" />