api.video Android player

api.video is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.

Table of contents

• Table of contents
• Project description
• Getting started
  • Installation
    • Gradle
  • Retrieve your video Id
  • View-based usage
    • Supported player views
  • Jetpack compose usage
  • Play your api.video video with ExoPlayer, MediaPlayer and VideoView
• Sample application
• Documentation
• Dependencies
• FAQ

Project description

Easily integrate a video player for videos from api.video in your Android application. The api.video Android player will help you to play the HLS video from api.video. It also generates analytics of your viewers usage.

Getting started

Installation

Gradle

In your module build.gradle, add the following code in dependencies:

dependencies {
    implementation 'video.api:android-player:1.6.0'
}

For Jetpack Compose, also add the following code in dependencies:

dependencies {
    implementation 'video.api:android-compose-player:1.6.0'
}

Retrieve your video Id

At this point, you must have uploaded a least one video to your account. If you haven't see how to upload a video. You'll need a video Id to use this component and play a video from api.video. To get yours, follow these steps:

1. Log into your account or create one here.
2. Copy your API key (sandbox or production if you are subscribed to one of our plan).
3. Go to the official api.video documentation.
4. Go to API Reference -> Videos -> List all videos
5. Create a get request to the /videos endpoint based on the reference, using a tool like Postman.
6. Copy the "videoId" value of one of elements of the API response.

Alternatively, you can find your video Id in the video details of your dashboard.

View-based usage

The api.video Android player comes with a view ApiVideoExoPlayerView to display the video and its controller ApiVideoPlayerController.

1. Add a ApiVideoExoPlayerView to your Activity/Fragment layout:

<video.api.player.ApiVideoExoPlayerView 
    android:id="@+id/playerView"
    android:layout_width="wrap_content" 
    android:layout_height="wrap_content"
    app:show_controls="true" 
    app:show_subtitles="true" />

You can also use an ExoPlayer PlayerView or a SurfaceView according to your requirements. See Supported player views for more details.

2. Implements the ApiVideoPlayerController.Listener interface:

val playerControllerListener = object : ApiVideoPlayerController.Listener {
    override fun onError(error: Exception) {
        Log.e(TAG, "An error happened", error)
    }
    override fun onReady() {
        Log.I(TAG, "Player is ready")
    }
}

3. Instantiate the ApiVideoPlayerController in an your Activity/Fragment:

val playerView = findViewById<ApiVideoExoPlayerView>(R.id.playerView)

val playerController = ApiVideoPlayerController(
    applicationContext,
    VideoOptions(
        "YOUR_VIDEO_ID",
        VideoType.VOD
    ), // For private video: VideoOptions("YOUR_VIDEO_ID", VideoType.VOD, "YOUR_PRIVATE_VIDEO_TOKEN")
    playerListener,
    playerView
)

4. Fullscreen video

If you require a fullscreen video. You will have to implement the ApiVideoExoPlayerView.FullScreenListener interface. To help you, you can use the ApiVideoPlayerFullScreenController that will handle the fullscreen. As it implements the ApiVideoExoPlayerView.FullScreenListener interface, you can pass it to your ApiVideoExoPlayerView instance.

playerView.fullScreenListener = ApiVideoExoPlayerView(
    supportFragmentManager,
    playerView,
    playerController
)

Check out for the implementation in the Sample application.

Supported player views

The api.video Android player comes with a specific view ApiVideoExoPlayerView to display the video and its controller. If you require a customization of this view such as changing a button color,..., you can contact us.

Otherwise, in the ApiVideoPlayerController, you can also use the following views:

• PlayerView: ExoPlayer views from media3
• SurfaceView
• Surface

The SurfaceView and the Surface require more work to be used.

Jetpack compose usage

The api.video Android player comes with a composable ApiVideoPlayer to display the video from a compose application. In your application, you can add:

ApiVideoPlayer(
    videoOptions = VideoOptions("YOUR_VIDEO_ID", VideoType.VOD),
)

Play your api.video video with ExoPlayer, MediaPlayer and VideoView

If you want to use the ExoPlayer directly, you can use the api.video Android extensions:

1. Create a video

val videoOptions = VideoOptions("YOUR_VIDEO_ID", VideoType.VOD)
// For private video: VideoOptions("YOUR_VIDEO_ID", VideoType.VOD, "YOUR_PRIVATE_VIDEO_TOKEN")

2. Pass it to your player

For ExoPlayer:

val exoplayer = ExoPlayer.Builder(context).build() // You already have that in your code
exoplayer.addMediaSource(videoOptions)
// Or
exoplayer.setMediaSource(videoOptions)

For MediaPlayer:

val mediaPlayer = MediaPlayer() // You already have that in your code
mediaPlayer.setDataSource(context, videoOptions)

For VideoView:

val videoView = binding.videoView // You already have that in your code
videoView.setVideo(videoOptions)

Sample application

A demo application demonstrates how to use player. See /examples folder.

On the first run, you will have to set your video Id:

1. Click on the FloatingActionButton -> Settings
2. Replace the video Id with your own video Id

Documentation

• Player documentation
• api.video documentation

Dependencies

We are using external library

Plugin	README
Exoplayer	README.md

FAQ

If you have any questions, ask us in the community or use issues.