[SDK README - api.video-android-player] README to documentation synchro

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.
 ---
+<!--
+THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT!
+ IF YOU NEED TO CHANGE THIS FILE,  CREATE A PR IN THE SOURCE REPOSITORY.
+-->
 
 # 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 `<manifest>`:
-
-```xml
-
-<uses-permission android:name="android.permission.INTERNET" />
+```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
 
-<video.api.player.ApiVideoExoPlayerView
+<video.api.player.ApiVideoExoPlayerView 
     android:id="@+id/playerView"
-    android:layout_width="wrap_content"
+    android:layout_width="wrap_content" 
     android:layout_height="wrap_content"
-    app:show_fullscreen_button="true"
-    app:show_controls="true"
+    app:show_controls="true" 
     app:show_subtitles="true" />
 ```
 
-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,33 +100,112 @@ val playerControllerListener = object : ApiVideoPlayerController.Listener {
 ```kotlin
 val playerView = findViewById<ApiVideoExoPlayerView>(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
 )
 ```
 
 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].
+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).