Android

Mobile

Private Videos

Player

Player update

Normal

thumbnail_thibault_rond.png

thibault_rond.png

Thibault Beyou

Tutorials

Kotlin

We have now released an [api.video](https://api.video/) player for Android. The api.video player helps you to include your videos in your Android applications very easily and quickly. In this tutorial, we are going to show how to add an api.video player to your Android application. It will only take 5 minutes. Let’s do this! 👊

Before starting this tutorial, you can upload a video to your api.video. If you haven’t yet, you can check [Upload your first video guide](https://docs.api.video/docs/upload-your-first-video), which will walk you through your first video upload. The video that you have uploaded to your api.video account will have an assigned `videoId`. In the following steps, we will call for your videoId using the `YOUR_VIDEO_ID` parameter.

To just give you a quick preview, we are going to create an Android application with an api.video player that looks like this:

## The api.video player for Android

The api.video Android player is available on GitHub and comes with an example application, and the artifact is hosted on Maven Central.

The minimum Android API version supported by the api.video Android player is 24. Make sure that you don’t have a `minSdk` version under 24.

The API is divided into 2 main components:

- **The player view:** This component displays the video and its controls: `ApiVideoExoPlayerView` class.
- **The player controller:** This component controls the video and its events: `ApiVideoPlayerController` class.

## Add api.video Android player to your project

If you don’t have an Android application yet, you need to create one before you go further. The [Build Your First Android App in Java](https://developer.android.com/codelabs/build-your-first-android-app#0) is a simple guide that will help you create your Android application. 

### Dependency

The first thing is to add the [api.video](https://api.video/) Android player to your project dependencies. In your application `build.gradle`, add your `dependencies` tag as shown below:

It’s always good to check out if a [new version](https://github.com/apivideo/api.video-android-player/releases) is available.

To have access to the view, I am going to use `ViewBinding` in this tutorial because it is elegant to use as it will be more user-friendly. Now we add the `android` tag:

### XML Layout

In your `Activity` layout, add a player view:

You might have some constraints to add depending on the parent layout.

With `ViewBinding`, we can access our `ApiVideoExoPlayerView` by using the following field:

### Implementation

The main part of the implementation is to create a player controller, but it depends on several other components.

To manipulate video from api.video, the `videoId` is wrapped in an object called `VideoOptions`:

Create a player controller in your `Activity`. For example, in the `onResume`:

Launch the application. You have successfully integrated the [api.video](http://api.video) Android player in your application! 🥳🥳🥳

### Video privacy setting

For more information on changing video privacy settings, see this [article](https://api.video/blog/product-updates/video-access-management-how-to-create-deliver-and-manage-private-videos-and-what/).

If your application requires the use of private videos, then pass your private token to the `VideoOptions`:

### Fullscreen

For the fullscreen button, you will have to develop the fullscreen behavior. The base principles are: 

* When full screen is activated, hide all surrounding views, menu,…, and lock the application in landscape mode.
* When the full screen is deactivated, display surrounding views and unlock the application orientation.

These behaviors must be implemented on the `onFullScreenModeChanged` of `ApiVideoExoPlayerView.Listener`:

In this quick tutorial, you learned about how to simply add an [api.video](http://api.video) player for your Android application. Now you know how to add the api.video player as a dependency, configure the XML layout, and implement the player controller. Moreover, you learned how to change your video privacy and how to set up a fullscreen behavior. 

You can successfully integrate the api.video Android player in your own application by following the steps in this tutorial. For an example of api.video Android player, see the [example](https://github.com/apivideo/api.video-android-player/tree/main/example) provided in the player repository.

If you miss any features, face any bugs, or come across any other issues, we will be happy to help you on our [GitHub issues](https://github.com/apivideo/api.video-android-player/issues) page.🤝

large_23nov22-1.png

medium_23nov22-1.png

small_23nov22-1.png

thumbnail_23nov22-1.png

23nov22-1.png

How to add an api.video player to your Android application

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Your company’s brand is unique.  Shouldn’t the video player that you use your 
branding & your colour scheme… not the YouTube/Google corporate colour scheme?

## api.video player

api.video, in addition to fast video [encoding](https://api.video/encoding), [streaming](https://api.video/streaming) and storage, has a fully customisable player that allows you to have greater control over how your video is presented. By default, here’s what it looks like:

This is a video of Bucky Badger (the mascot for the University of Wisconsin-Madison) dancing at a basketball game. (On Wisconsin!)

Sports teams are **highly** identifiable by their colors - fans wear scarves, shirts in “their” teams colours to show their support. 

The colors for the Wisconsin Badgers are Badger (Cardinal Red) and White. A close look at the screenshot above shows that the api.video logo (while awesome) is closer to the colours of the University of Minnesota (and we just can't Gopher that!). The play button is blue, and while unlikely to be mistaken for the dark blue of Penn State or (shudder) the University of Michigan, it certainly does not match the Badger color scheme.  Let’s dive in and learn how to build a custom player with api.video that uses the [University of Wisconsin color scheme](https://brand.wisc.edu/web/colors/).

## Create a New Player

The first step in creating your new player is, well, to create a new player.  You’ll need your api key from the [api.video dashboard](https://my.api.video/).  Use this to [authenticate your account](https://api.video/blog/tutorials/authentication-tutorial), and receive an access token that will be good for an hour. 



To create a player, we’ll use the [create player](https://docs.api.video/reference/post_players) endpoint. A quick scan of the API shows that you can pretty much customise the player completely on creation, but we’ll go one step at a time to show the differences each change incurs.

To create the default player, we’ll use the API and use no parameters in the JSON (make sure you replace {accessToken} with the token you received in the last step):


To which we will receive a response that resembles:

Hooray! We’ve created a player (ptSQlESqn5KIn9tGxlA88Q1) that we can now customise. Before we begin customising the player, we must associate it with a video to see it.  Using the [Update Video](https://docs.api.video/reference/patch-video) endpoint, and the videoId (vi3666MejLyqtJOOHFIwGCA9) for the Bucky Badger video, we will change the playerId parameter to our new player:


The response JSON (not shown) for the video shows that the new playerId is now present in the response, indicating that the change was successful. Now we can begin walking through the various customisations that are possible with the player, and see them with this video.  

### Assets

There are 2 API endpoints to edit a player. The [Upload Logo](https://docs.api.video/reference/post_players-playerid-logo) endpoint is specifically for changing the logo on the player.  It requires 2 parameters, an image file (JPG or PNG, 100x200 pixels max) and a url.  When the icon in the player is clicked, a new tab will open the url. For example: the default api.video player features the api.video logo, that, when clicked, takes the user to the [api.video](https://api.video) homepage.


small_bucky-default1.png

thumbnail_bucky-default1.png

bucky-default1.png

Our new player has no asset (logo and link are ```null``` in the JSON), and therefore no icon to click on:

thumbnail_bucknoasset1.png

bucknoasset1.png

Let’s go ahead and add an icon to this player..  In this case, we’ll use the official University of WIsconsin “motion W” logo, downloaded from Wikipedia.  For the url, we’ll point to Bucky’s Twitter account (https://twitter.com/uwbuckybadger)


I am using the ```multipart/form-data``` mimetype, which allows me to update a text form field (```link=https://twitter.com/uwbuckybadger``` ), and also upload a file (in this case the motionW.png image in my downloads folder).  Now my video features the official icon of the university, and when clicked, opens Bucky’s Twitter page in a new tab.


small_screenshot-2020-08-26-at-15-55-33.png

thumbnail_screenshot-2020-08-26-at-15-55-33.png

screenshot-2020-08-26-at-15-55-33.png

## Update Player

The second endpoint for customizing the player is the [Update Player](https://docs.api.video/reference/patch_players-playerid) endpoint. We could have made all of these changes on creation, but for the sake of showing examples, we will be making small incremental changes to the player, and investigating the differences.

Let’s take a look at which areas we can change in the api.video player:

all the places color can be added in player

medium_screenshot-2020-08-26-at-17-35-09.jpg

small_screenshot-2020-08-26-at-17-35-09.jpg

thumbnail_screenshot-2020-08-26-at-17-35-09.jpg

screenshot-2020-08-26-at-17-35-09.jpg


### Customising player colors

The display parameters we can adjust are named as follows:

* ```backgroundText``` changes the video title.
* ```text``` affects playback timers (total and elapsed time). 
* ```lineActive``` & ```linkHover``` affect icon colors and hover state color, 
* Playback bar: The colors indicating video playback status can be changed:
* ```trackPlayed``` to the left of the current playback location (video that has been played)
* ```trackUnplayed``` To the right of current playback location, indicating the video downloaded.  You can also think of this as the locally buffered video.
*   ```trackUnplayed``` To the right of current playback location, indicating the video downloaded.  You can also think of this as the locally buffered video.
* ```trackBackground```: To the right of trackUnplayed: this is where no video is yet downloaded.
* ```backgroundTop``` & ```backgroundBottom``` are used to create a gradient effect when the menu is opened.

Let's see how each of these features work!

### Text Coloring

The video name attribute is controlled by the ```backgroundText``` parameter.  The primary UW color is Badger Red, and the branding guide provides a HEX code:  #c5050c. Using an [online converting tool](https://www.webfx.com/web-design/hex-to-rgb/), this corresponds to rgb(197,5,12).  The default alpha is 1, so we’ll add ```rgba(197,5,12,1)``` as follows:




This call results in a success, so we can reopen the video to see if the title in red is easy to read:

small_redtitle.png

thumbnail_redtitle.png

redtitle.png

Looks good to me!  Using the same red color for the playback times, using the ```text``` API parameter is not as successful. The text is hard to read in places, like when the text goes across Bucky’s striped sweater:  

medium_redtime.png

small_redtime.png

thumbnail_redtime.png

redtime.png

Rather than revert to white, we can use the UW-gray-blue specified in the branding guide: ```{"text":"rgba(218,223,225,1)"}```

thumbnail_graytime.png

graytime.png

### Playback bar

There are 3 statuses that appear in the playback bar:
* Played: video that has been played (to the left of the current playback location)
* Buffered: Unplayed, but downloaded - to the right of the current playback locations
* Not yet downloaded: Appears early in playback - for the end of the video that is not yet downloaded. 

The default colors here are blue -> white -> white, and the alpha channel goes from 0.95 -> 0.35 -> 0.2 (unplayed video is more transparent than video that is played).

Let’s keep the same transparency, but use UW-dark-red-> UW-gray-darker -> UW-gray-blue. The data I send is:


large_videobar1.png

medium_videobar1.png

small_videobar1.png

thumbnail_videobar1.png

videobar1.png

The red ‘played’ color on the left looks great, but it is hard to see the difference between the unplayed and background colors on the right.  Using UW -*gray blue* for both unplayed and returning the alpha channel values to the default values seems like a good compromise with excellent visibility:


medium_videobar2.png

small_videobar2.png

thumbnail_videobar2.png

videobar2.png

### Icons

The icons are all white, and probably could remain that way, but because this is a walkthrough of changing all the colors, we’ll change the icons to UW-gray-darker, with a white hover.  


### Background colours

In the upper righthand corner is an icon with three dots.  When it is clicked, the video is paused, and placed in the background with a gradiant of colours from top to bottom over the video.  These colours are adjusted with the ```backgroundTop``` and ```backgroundBottom``` parameters.

Since this is the UW Badgers player, we'll use Badger Red to White for the gradient:

medium_backgroundgradient.jpg

small_backgroundgradient.jpg

thumbnail_backgroundgradient.jpg

backgroundgradient.jpg

### Video Playback



The last few API configurable features control the video playback inside the player.
* ```enableApi``` when true, allows the [player SDK](https://docs.api.video/docs/video-player-sdk) to control the player.
* ```forceAutoplay``` when true, the video will automatically autoplay. Note that due to browser limitations, the video will be muted when set to autplay. 
* ```enableControls``` will hide all the playback controls from the user. This is great if you are using your video as a background on a page, and there is no need to start/stop the video. Note: without controls, the video should be set to autoplay.
* ```hideTitle``` Remove the title and logo from the video.
* ```forceLoop``` For the video on an endless loop.

With these tools, you can simulate an animated gif: hide the controls and the title, force autoplay and looping.

In the case of my UW Badgers video, I'll force autoplay and looping, but also keep the title, controls and API access:

##  Conclusion

Well, we've done it.  Here is the final player with all of our edits:




Pretty neat! I was able to upload a video, create a player for my video, and customise it to meet the brand requirements of the organisation. 

medium_playerb.jpg

small_playerb.jpg

thumbnail_playerb.jpg

playerb.jpg

Tutorial: video player customisation

Featured article

# api.video blog

Blog

Follow the api.video Blog to explore tutorials, video use cases, and learn about on-demand and live-streaming video updates.