This guide will provide a end-to-end explanation of how to setup an Android application with THEOplayer included. It will cover setting up an IDE, including all dependencies, adding THEOplayer to your activity and interacting with the API.
You can follow the guide step-by-step, or for each step you will find a link to the corresponding commit in our Android Github repository. We also provide a full project for Android TV and for both together.
Start with opening Android Studio. You will be greeted with the following screen. To begin, choose the "Start a new Android Studio project" option.
On the next screen we can choose from pre-built Activities.
An Activity is a screen of the application, it provides the window in which the app draws its UI. Because we want to show our THEOplayer on the Activity, we will select an empty one.
So select "Empty Activity" and press "Next".
THEOplayer supports Android devices with Android version 4.1 (Jelly Bean - API 16) so select your minimum SDK requirement (Only the phone and tablet option).
Choose your application name, domain and project location, then hit "Next".
Note the Package name as we will need this path later.
We are now done with the setup of the new project. Android Studio will now download the dependencies, project requirements and index your files. You can see the progress at the bottom of the window.
Once this is done you will see the following screen:
By default, Android Studio displays your project files in the Android view. This view does not reflect the actual file hierarchy on the disk. The view is organized by modules and file types to simplify navigation between key source files of your project and to hide certain files or directories that are not commonly used.
To see the actual file structure of the project, including all files hidden from the Android view, select Project from the dropdown at the top of the Project window.
When you select Project view, you can see a lot more files and directories. The most important of which are the following:
app/
build/
libs/
src/
src/androidTest/
src/main/
src/main/java/
src/main/res/
src/main/AndroidManifest.xml
build.gradle(module)
build.gradle (project)
Your THEOplayer Android contains the following files:
theoplayer-android-xxx-VERSION-minapi21-release.aar
theoplayer-android-xxx-VERSION-minapi16-release.aar
theoplayer-android-xxx-VERSION-javadoc.jar
theoplayer-android-xxx-VERSION-sources.aar
About the file extensions:
With the minApi16 version, you can support the largest possible amount of devices. However, the file size of this version is about 50MB while the minApi21 version is around 2MB. For that reason, it is useful to use both in a way so that the users who have Android Lollipop or higher will have a much smaller APK file.
We will demonstrate the steps with the minApi16 version, but they are the same for the minApi21 version.
First add your THEOplayer minApi16 AAR file to "app/libs" folder (in our example project we call it theoplayer.aar)
Now we have to modify the build.gradle files to load "theoplayer.aar" library.
In your top-level (project) build.gradle file add the following lines to allow loading library files from the "libs" folder
allprojects {
repositories {
google()
jcenter()
flatDir {
dirs 'libs'
}
}
}
And your Gradle file now looks like this:
Next we need to edit the Gradle file on the module-level("app/build.gradle")
we need to specify for Gradle to load and compile our library from the libs folder.
THEOplayer SDK has an external dependency on Gson from Google. We use this library to convert Java object to and from JSON representation.
In the Gradle file, edit the dependencies to:
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
implementation(name:'theoplayer', ext:'aar')
implementation 'com.google.code.gson:gson:2.8.2'
implementation 'androidx.appcompat:appcompat:1.2.0'
implementation 'androidx.constraintlayout:constraintlayout:2.0.1'
testImplementation 'junit:junit:4.12'
androidTestImplementation 'androidx.test.ext:junit:1.1.2'
androidTestImplementation 'androidx.test.espresso:espresso-core:3.3.0'
}
After the modification of the .gradle files, Android Studio asks you to sync with Gradle. Do so by pressing the "Sync Now" button on the top right of the window. (in the blue border)
To play online videos with THEOplayer, first we need to add INTERNET permission into the AndroidManifest.xml file ("app/src/main/AndroidManifest.xml"):
<uses-permission android:name="android.permission.INTERNET" />
The manifest should look like:
We will add some code to the activity_main.xml file.
We can now add the THEOplayerView to the layout of the MainActivity ("/app/src/main/java/com/theoplayer/theoplayerexample/MainActivity.java").
The example "Hello World!" text can be completely removed. We put the THEOplayerView instead.
At least the "width", "height" and "id" attributes need to be specified on the new view.
The "id" is important, it is used to identify the view object in you MainActivity class.
<com.theoplayer.android.api.THEOplayerView
android:layout_width="match_parent"
android:layout_height="300dp"
android:id="@+id/theoplayer"
app:layout_constraintTop_toTopOf="parent">
</com.theoplayer.android.api.THEOplayerView>
Now in the MainActivity.java we can retrieve the THEOplayerView by the "id" we set earlier using the findViewById method.
...
import com.theoplayer.android.api.THEOplayerView;
public class MainActivity extends AppCompatActivity{
THEOplayerView theoPlayerView;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
theoPlayerView = findViewById(R.id.theoplayer);
}
}
To play a video in THEOplayer, we need to configure a source for the player in our MainActivity:
TypedSource typedSource = TypedSource.Builder
.typedSource()
.src("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
.type(SourceType.DASH)
.build();
SourceDescription sourceDescription = SourceDescription.Builder
.sourceDescription(typedSource)
.build();
theoPlayerView.getPlayer().setSource(sourceDescription);
We will now introduce a button to start/stop the video in the player.
First add the button to our activity_main.xml layout file
<Button
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:id="@+id/btn_playpause"
android:text="PLAY/PAUSE"
app:layout_constraintTop_toBottomOf="@+id/theoplayer"
app:layout_constraintLeft_toLeftOf="parent"
app:layout_constraintRight_toRightOf="parent"/>
Navigate to the MainActivity.java file and import the android button functionality.
import android.widget.Button;
import android.view.View;
Then set an OnClickListener() on the button in our MainActivity code to trigger play and pause in the player.
Button btnPlayPause;
...
btnPlayPause = findViewById(R.id.btn_playpause);
btnPlayPause.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
if (theoPlayerView.getPlayer().isPaused()) {
theoPlayerView.getPlayer().play();
} else {
theoPlayerView.getPlayer().pause();
}
}
});
The next step is listening for player events.
First, we need to create two more TextViews in the activity_main.xml file.
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:id="@+id/txt_playstatus"
app:layout_constraintLeft_toRightOf="@+id/btn_playpause"
app:layout_constraintTop_toBottomOf="@+id/theoplayer"
app:layout_constraintBaseline_toBaselineOf="@+id/btn_playpause"
android:layout_marginLeft="20dp"/>
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:id="@+id/txt_timeupdate"
app:layout_constraintLeft_toRightOf="@+id/txt_playstatus"
app:layout_constraintTop_toBottomOf="@+id/theoplayer"
app:layout_constraintBaseline_toBaselineOf="@+id/btn_playpause"
android:layout_marginLeft="20dp"/>
Then import the following Android and THEOplayer libraries in the MainActivity file:
...
import android.widget.TextView;
...
import com.theoplayer.android.api.event.player.PauseEvent;
import com.theoplayer.android.api.event.EventListener;
import com.theoplayer.android.api.event.player.PlayEvent;
import com.theoplayer.android.api.event.player.PlayerEventTypes;
import com.theoplayer.android.api.event.player.TimeUpdateEvent;
We will now listen for "PLAY", "PAUSE" and "TIMEUPDATE" in this example.
TextView txtPlayStatus, txtTimeUpdate;
...
txtPlayStatus = findViewById(R.id.txt_playstatus);
txtTimeUpdate = findViewById(R.id.txt_timeupdate);
theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.PLAY, new EventListener<PlayEvent>() {
@Override
public void handleEvent(PlayEvent playEvent) {
txtPlayStatus.setText("Playing");
}
});
theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.PAUSE, new EventListener<PauseEvent>() {
@Override
public void handleEvent(PauseEvent pauseEvent) {
txtPlayStatus.setText("Paused");
}
});
theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.TIMEUPDATE, new EventListener<TimeUpdateEvent>() {
@Override
public void handleEvent(TimeUpdateEvent timeUpdateEvent) {
txtTimeUpdate.setText(String.valueOf(timeUpdateEvent.getCurrentTime()));
}
});
When the events are triggered we will update the MainActivity UI with the corresponding state.
<Button
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:id="@+id/btn_playpause"
android:text="PLAY/PAUSE"
app:layout_constraintLeft_toLeftOf="parent"
app:layout_constraintRight_toRightOf="parent"
app:layout_constraintTop_toBottomOf="@+id/theoplayer"/>
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:id="@+id/txt_playstatus"
app:layout_constraintRight_toRightOf="@+id/btn_playpause"
app:layout_constraintTop_toBottomOf="@+id/theoplayer"
app:layout_constraintBaseline_toBaselineOf="@+id/btn_playpause"
android:layout_marginLeft="20dp"/>
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:id="@+id/txt_timeupdate"
app:layout_constraintLeft_toRightOf="@+id/txt_playstatus"
app:layout_constraintTop_toBottomOf="@+id/theoplayer"
app:layout_constraintBaseline_toBaselineOf="@+id/btn_playpause"
android:layout_marginLeft="20dp"/>
</androidx.constraintlayout.widget.ConstraintLayout>
THEOplayer SDK contains a default fullscreen activity which can be started automatically when you rotate your device.
We have to configure our player instance in the MainActivity to react to orientation changes and start the Fullscreen activity.
@Override
protected void onCreate(Bundle savedInstanceState) {
// ...
theoPlayerView = findViewById(R.id.theoplayer);
theoPlayerView.getSettings().setFullScreenOrientationCoupled(true);
// ...
}
In the AndroidManifest.xml we can disable the default orientation behaviour on our MainActivity and lock it in portrait.
Then, because we enabled fullscreen orientation coupling with the setFullScreenOrientationCoupled(true) method eariler, THEOplayer will take care of the support of seamless landscape activity transition at rotation.
<activity android:name=".MainActivity"
android:screenOrientation="userPortrait"
android:configChanges="orientation|screenSize"
>
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
In order to work properly and in sync with the Activity lifecycle changes (e.g. when we rotate the device or start a new Activity or the app goes to background). We need to call the "onResume", "onPause" and "onDestroy" methods of the THEOplayerView when the matching methods are called in the Activity.
public class MainActivity extends AppCompatActivity{
// ...
@Override
protected void onPause() {
super.onPause();
theoPlayerView.onPause();
}
@Override
protected void onResume() {
super.onResume();
theoPlayerView.onResume();
}
@Override
protected void onDestroy() {
super.onDestroy();
theoPlayerView.onDestroy();
}
// ...
}
If you would like to customize the Fullscreen Activity, you can follow our tutorial here.
To run your application, you have to click on the green "Play" icon next to the "app" module on the Toolbar of Android Studio.
Then you have two choices:
We suggest you to run the application on a real device for the best performance.
You can either plug in a usb cable between your device and your computer, or enable network debugging on your device and connect using adb connect IP-ADDRESS.
Also keep in mind, on emulators which run Android 7.0 and above the video in THEOplayer is not showing. If you want to still test in emulators you need to use a version with Android 6.0 or below.
And finally, here you have some screenshots from the running application:
Start screen
Playing screen
Paused screen
Rotated fullscreen
In this guide we have focused on creating an Android application from scratch and we integrated it with THEOplayer.
We have learned how to interact with the player via the available APIs in Java, we have registered for player events and we have learned how to enable automatic orientation detection.
You can find much more interesting features of THEOplayer on our demo page.
The full source of this application is available on GitHub.
In case you encountered any problems, please contact us at support@theoplayer.com!