From 2f45e30218bba65f76f57445761596154b51159a Mon Sep 17 00:00:00 2001 From: bot-api-video Date: Mon, 13 Nov 2023 17:25:06 +0000 Subject: [PATCH] [SDK README - api.video-android-player] README to documentation synchro --- sdks/player/apivideo-android-player.md | 152 +++++++++++++++++++------ 1 file changed, 120 insertions(+), 32 deletions(-) diff --git a/sdks/player/apivideo-android-player.md b/sdks/player/apivideo-android-player.md index 669a750b..0a679b02 100644 --- a/sdks/player/apivideo-android-player.md +++ b/sdks/player/apivideo-android-player.md @@ -3,17 +3,21 @@ title: api.video Android Player meta: description: The official api.video Android Player component for api.video. [api.video](https://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. --- + # api.video Android Player -[api.video](https://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. +[api.video](https://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. ## Project description -Easily integrate a video player for videos from [api.video](https://api.video/) in your Android +Easily integrate a video player for videos from [api.video](https://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](https://api.video/product/video-analytics/). ## Getting started @@ -25,53 +29,58 @@ In your module `build.gradle`, add the following code in `dependencies`: ```groovy dependencies { - implementation 'video.api:android-player:1.3.1' + implementation 'video.api:android-player:1.5.0' } ``` -### Permissions +For Jetpack Compose, also add the following code in `dependencies`: -In your `AndroidManifest.xml`, add the following code in ``: - -```xml - - +```groovy +dependencies { + implementation 'video.api:android-compose-player:1.5.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](https://docs.api.video/vod/upload-a-video-regular-upload/). You'll need +see [how to upload a video](https://docs.api.video/docs/upload-a-video-regular-upload). 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](https://dashboard.api.video/login) or create one [here](https://dashboard.api.video/register). 2. Copy your API key (sandbox or production if you are subscribed to one of - our [plan](https://api.video/pricing)). -3. Go to [the official api.video documentation](https://docs.api.video/). -4. Go to API Reference -> Videos -> [List all videos](https://docs.api.video/reference/api/Videos#list-all-video-objects) -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. + our [plan](https://api.video/pricing)/). +3. Go to [the official api.video documentation](https://docs.api.video/docs). +4. Log into your account in the top right corner. If it's already done, be sure it's the account you + want to use. +5. Go to API Reference -> Videos -> [List all videos](https://docs.api.video/reference/list-videos) +6. On the right, be sure the "Authentication" section contains the API key you want to use. +7. Generate your upload token by clicking the "Try It!" button in the right section +8. Copy the "videoId" value of one of elements of the response in the right section. Alternatively, you can find your video Id in the video details of your [dashboard](https://dashboard.api.video). -### Code sample +### 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: ```xml - ``` -You can also use an ExoPlayer `StyledPlayerView` or a `SurfaceView` according to your customisation level. +You can also use an ExoPlayer `PlayerView` or a `SurfaceView` according to your requirements. +See [Supported player views](#supported-player-views) for more details. 2. Implements the `ApiVideoPlayerController.Listener` interface: @@ -91,9 +100,12 @@ val playerControllerListener = object : ApiVideoPlayerController.Listener { ```kotlin val playerView = findViewById(R.id.playerView) -val player = ApiVideoPlayerController( +val playerController = ApiVideoPlayerController( applicationContext, - VideoOptions("YOUR_VIDEO_ID", VideoType.VOD), // For private video: VideoOptions("YOUR_VIDEO_ID", VideoType.VOD, "YOUR_PRIVATE_VIDEO_TOKEN") + VideoOptions( + "YOUR_VIDEO_ID", + VideoType.VOD + ), // For private video: VideoOptions("YOUR_VIDEO_ID", VideoType.VOD, "YOUR_PRIVATE_VIDEO_TOKEN") playerListener, playerView ) @@ -101,23 +113,99 @@ val player = ApiVideoPlayerController( 4. Fullscreen video -If you requires a fullscreen video. You will have to implement the `ApiVideoPlayerController.ViewListener` interface. +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. + +```kotlin +playerView.fullScreenListener = ApiVideoExoPlayerView( + supportFragmentManager, + playerView, + playerController +) +``` + Check out for the implementation in the [Sample application](#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](https://github.com/apivideo/api.video-android-player/issues). + +Otherwise, in the `ApiVideoPlayerController`, you can also use the following views: + +* [`PlayerView`](https://developer.android.com/reference/androidx/media3/ui/PlayerView): ExoPlayer + views from `media3` +* [`SurfaceView`](https://developer.android.com/reference/android/view/SurfaceView) +* [`Surface`](https://developer.android.com/reference/android/view/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: + +```kotlin +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 + +```kotlin +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: + +```kotlin +val exoplayer = ExoPlayer.Builder(context).build() // You already have that in your code +exoplayer.addMediaSource(videoOptions) +// Or +exoplayer.setMediaSource(videoOptions) +``` + +For MediaPlayer: + +```kotlin +val mediaPlayer = MediaPlayer() // You already have that in your code +mediaPlayer.setDataSource(context, videoOptions) +``` + +For VideoView: + +```kotlin +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 [`/example`](https://github.com/apivideo/api.video-android-player/tree/main/example) +See [`/examples`](https://github.com/apivideo/api.video-android-player/tree/main/examples) folder. On the first run, you will have to set your video Id: + 1. Click on the FloatingActionButton -> Settings -2. Replace "YOUR_VIDEO_ID" by your video Id +2. Replace the video Id with your own video Id ## Documentation -* [API documentation](https://apivideo.github.io/api.video-android-player/) -* [api.video documentation](https://docs.api.video/) +* [Player documentation](https://apivideo.github.io/api.video-android-player/) +* [api.video documentation](https://docs.api.video) ## Dependencies @@ -129,5 +217,5 @@ We are using external library ## FAQ -If you have any questions, ask us here: [https://community.api.video](https://community.api.video). -Or use [Issues]. \ No newline at end of file +If you have any questions, ask us in the [community](https://community.api.video) or +use [issues](https://github.com/apivideo/api.video-android-player/issues).