FEC-9696 subtitles positioning

documentation/player-portal/android/ads-android.md

@@ -5,16 +5,26 @@ weight: 110
 ---
 This article describes the steps required for adding support for the IMA Plugin functionality on Android devices. IMA (Interactive Media Ads) was developed by Google to enable you to display ads in your application's video, audio, and game content.
 
+### Add imaplugin dependency in `build.gradle` 
+
+```
+implementation 'com.kaltura.playkit:imaplugin:4.x.x'
+```
 ### Configure the Plugin Configuration Object  
 
 To configure the plugin, add the following configuration to your `pluginConfig` file as follows:
 
 ```java
-private void configureIMAPlugin(PlayerConfig pluginConfig) {
-    String adTagUrl = VIOAdUtil.getCastAdTag(mVideoDetailsModel);
+private IMAConfig getIMAPluginConfig() {
+    String adTagUrl = adUtil.getAdTag(mVideoDetailsModel);
     List<String> videoMimeTypes = new ArrayList<>();
-    IMAConfig adsConfig = new IMAConfig("en", false, true, -1, videoMimeTypes, adTagUrl, true, true);
+    videoMimeTypes.add(PKMediaFormat.mp4.mimeType);
+    videoMimeTypes.add(PKMediaFormat.hls.mimeType);
+    IMAConfig adsConfig = new IMAConfig().setAdTagUrl(adTagUrl).enableDebugMode(false).setVideoMimeTypes(videoMimeTypes);
 ```
+
+for more configuration options check IMAConfig API.
+
 ### IMConfig Constructor  
 
 ```java
@@ -26,24 +36,38 @@ IMAConfig(String language, boolean enableBackgroundPlayback, boolean autoPlayAdB
 For the IMA Plugin to start loading, you'll need to set the plugin configuration you created as follows:
 
 ```java
-PlayerConfig config = new PlayerConfig();
-PlayerConfig.Plugins plugins = config.plugins;
-pluginConfig.plugins.setPluginConfig(IMAPlugin.factory.getName(), adsConfig.toJSONObject());
+
+PlayKitManager.registerPlugins(getActivity(), IMAPlugin.factory);
+
+PKPluginConfigs pluginConfig = new PKPluginConfigs();
+
+pluginConfig.setPluginConfig(IMAPlugin.factory.getName(), getIMAPluginConfig());
+
+player = PlayKitManager.loadPlayer(this.getActivity(), pluginConfig);
+
+```
+
+### Change media 
+This scenario requires a new adTag url within `IMAPluginConfig`.
+The application must update the `IMAPlugin` with this information.
+To update, call the `player.updatePluginConfig` API before calling `player.prepare`.
+
+##### Example
+
+```java
+player.updatePluginConfig(IMAPlugin.factory.getName(), getIMAPluginConfig());
+
 ```
 
 ### Register to the Ad Started Event  
 
 The Ad Started event includes the `AdInfo` payload. You can fetch this data in the following way:
 
 ```java 
-player.addEventListener(new PKEvent.Listener() {
-            @Override
-            public void onEvent(PKEvent event) {
-                log.d("AD_STARTED");
-                mAdStartedEventInfo = (AdEvent.AdStartedEvent) event;
-                appProgressBar.setVisibility(View.INVISIBLE);
-            }
-        }, AdEvent.Type.STARTED);
+player.addListener(this, AdEvent.started, event -> {
+      log("AD STARTED adInfo AdPositionType =" + event.adInfo.getAdPositionType());
+});
+
 ```
 
 ### AdInfo API  
@@ -67,35 +91,49 @@ player.addEventListener(new PKEvent.Listener() {
 
 
 ```java
-        public void onEvent(PKEvent event) {
-                log.d("AD_CONTENT_PAUSE_REQUESTED");
-                PKAdInfo adInfo = player.getAdInfo();
-                appProgressBar.setVisibility(View.VISIBLE);
+        player.addListener(this, AdEvent.cuepointsChanged, event -> {
+            adCuePoints = event.cuePoints;
+            if (adCuePoints != null) {
+                log.d("Has Postroll = " + adCuePoints.hasPostRoll());
             }
-        }, AdEvent.Type.CONTENT_PAUSE_REQUESTED);
+        });
 
-        player.addEventListener(new PKEvent.Listener() {
-            @Override
-            public void onEvent(PKEvent event) {
-                log.d("Ad Event AD_RESUMED");
-                nowPlaying = true;
-                appProgressBar.setVisibility(View.INVISIBLE);
-            }
-        }, AdEvent.Type.RESUMED);
-        player.addEventListener(new PKEvent.Listener() {
-            @Override
-            public void onEvent(PKEvent event) {
-                log.d("Ad Event AD_ALL_ADS_COMPLETED");
-                appProgressBar.setVisibility(View.INVISIBLE);
-            }
-        }, AdEvent.Type.ALL_ADS_COMPLETED);
-        player.addEventListener(new PKEvent.Listener() {
-            @Override
-            public void onEvent(PKEvent event) {
-                log.d("Ad Error Event VAST_LOAD_TIMEOUT");
-            }
-        }, AdError.Type.VAST_LOAD_TIMEOUT);
+        player.addListener(this, AdEvent.adRequested, event -> {
+            AdEvent.AdRequestedEvent adRequestEvent = event;
+            log("AD_REQUESTED adtag = " + adRequestEvent.adTagUrl);
+        });
+
+        player.addListener(this, AdEvent.contentPauseRequested, event -> {
+            log("ADS_PLAYBACK_START");
+        });
+
+        player.addListener(this, AdEvent.contentResumeRequested, event -> {
+            log("ADS_PLAYBACK_ENDE");
+        });
+
+         player.addListener(this, AdEvent.resumed, event -> {
+            log("ADS_PLAYBACK_RESUMED");
+        });
+
+        player.addListener(this, AdEvent.allAdsCompleted, event -> {
+            log("ALL_ADS_COMPLETED");
+        });
+
+        player.addListener(this, AdEvent.error, event -> {
+            AdEvent.Error adError = event;
+            Log.d(TAG, "AD_ERROR " + adError.type + " "  + adError.error.message);
+            appProgressBar.setVisibility(View.INVISIBLE);
+            log("AD_ERROR");
+        });
 ```
+
+#### Please deregister all the events on player destroy phase
+
+```java
+player.removeListeners(this);
+player.destroy()
+```
+
 ### Ad Events  
 
 The IMA Plugin supports the following ad events:

documentation/player-portal/android/getting-started-android.md

@@ -263,3 +263,63 @@ We made a few other changes to the activity XML, like turning the view into a `L
 
 [Download](https://github.com/kaltura/kaltura-player-android-samples/tree/master/OVPSamples/GettingStarted)
 
+
+### Gradle Dependencies for Playkit SDK 
+
+##### A. Kaltura Player: 
+This dependency can be used on client app side. If client app use this then *there is no need to use Playkit, Kava, DTG and Providers dependency separately*. Because it is inbuilt in Kaltura Player.
+Find more [here](https://github.com/kaltura/kaltura-player-android/blob/develop/README.md)
+
+`implementation 'com.kaltura.player:tvplayer:kaltura_player_version'`
+
+Please check our [Kaltura Player samples](https://github.com/kaltura/kaltura-player-android-samples/blob/8c743c7083ec2848cc0db979a194b9c92ce1a36b/AdvancedSamples/FullDemo/playkitdemo/build.gradle#L34)
+
+#####B. Use Player components standalone: 
+If client app wants to use player and its plugins standalone then other dependecies should be added.Find more [here](https://kaltura.github.io/playkit/guide/android/)
+
+Please check our [Playkit Samples](https://github.com/kaltura/playkit-android-samples/blob/fd33d9709396fce6c4df983fc5efe7652fd1427b/FullDemo/app/build.gradle#L29)
+
+##### 1. Playkit: 
+Core Player which handles Non-DRM/Clear and DRM content playback.
+`implementation 'com.kaltura.playkit:playkit:latest_version'`
+##### 2. DTG (Download To Go):
+Plugin which handles download of dash(including DRM) and hls streams(clear streams)
+`implementation 'com.kaltura.dtg:dtglib:dtg_latest_version'`
+##### 3. Phoenix Provider Plugin: 
+If you are Kaltura customer then this plugin which handles Kaltura OTT and OVP BE api calls.
+`implementation 'com.kaltura.playkit:playkitproviders:latest_version'`
+##### 4. IMA Ads Plugin: 
+Plugin which handles ads playback. 
+`implementation 'com.kaltura.playkit:imaplugin:latest_version'`
+##### 5. Kava Analytics Plugin: 
+Plugin for analytics.
+`implementation 'com.kaltura.playkit:kavaplugin:latest_version'`
+##### 6. Youbora Analytics Plugin: 
+Plugin for Youbora analytics.
+`implementation 'com.kaltura.playkit:youboraplugin:latest_version'`
+##### 7. Googlecast Plugin: 
+Plugin for content playback on Googlecast.
+`implementation 'com.kaltura.playkit:googlecast:latest_version'`
+##### 8. VR Plugin: 
+Plugin for 360 or VR content playback.
+`implementation 'com.kaltura.playkit:vrplugin:latest_version'`
+
+If client apps want to exclude the playkit from other plugins in case they find any cyclic dependency issue on app side then simply it can exclude the tree from the relavant dependency.
+
+######Example
+```
+implementation 'com.kaltura.playkit:anyPlugin:latest_version', {
+exclude group: 'com.kaltura.playkit', module: 'playkit'
+}
+
+```
+
+######Note
+> `latest_version` can be picked up from [here](https://github.com/kaltura/playkit-android/releases).
+> 
+> `dtg_latest_version ` can be picked from [here](https://github.com/kaltura/playkit-dtg-android/releases)
+> 
+> `kaltura_player_version` can be picked from [here](https://github.com/kaltura/kaltura-player-android/releases)
+
+
+

documentation/player-portal/android/player-settings-android.md

@@ -484,6 +484,67 @@ player.updateSubtitleStyle(subtitleStyleSettings);
 
 {% endhighlight %}
 
+### Subtitle View Positioning Configuration
+> Since Playkit version 4.8.0
+
+* {% highlight java %}PKSubtitlePosition pkSubtitlePosition = PKSubtitlePosition(boolean overrideInlineCueConfig){% endhighlight %}
+
+	If `overrideInlineCueConfig` is set to `true` then player will use the given Cue Settings to override the values coming in Cue Settings.
+
+* {% highlight java %}setVerticalPosition(int verticalPositionPercentage){% endhighlight %}  
+
+	Set the subtitle position only in Vertical direction (Up or Down) on the video frame. This method only allows to move in Y - coordinate.
+
+* {% highlight java %}setPosition(int horizontalPositionPercentage, int verticalPositionPercentage, Layout.Alignment horizontalAlignment){% endhighlight %}
+
+	Set the subtitle position anywhere on the video frame. This method allows moving in X-Y coordinates.
+
+* {% highlight java %}setToDefaultPosition(boolean overrideInlineCueConfig){% endhighlight %}
+
+	If `overrideInlineCueConfig` is `false` that means; app does not want to override the inline Cue configuration. App wants to go with Cue configuration.
+
+	Note! If `setOverrideInlineCueConfig(boolean)` is called with `false` value means after that in next call, app needs to `setOverrideInlineCueConfig(boolean)` with the required value.
+
+	Otherwise
+
+	If `overrideInlineCueConfig` is `true` then it will move subtitle to Bottom-Center which is a standard position for it.
+
+* {% highlight java %}setOverrideInlineCueConfig(boolean overrideInlineCueConfig){% endhighlight %} 
+
+	If `overrideInlineCueConfig` is set to true then player will use the given Cue Settings to override the values coming in Cue Settings.
+
+##### Note: Horizontal / Vertical position percentage limit is between 10% up to 100%.
+
+##### Vertical positioning  - 100% Top to 10% Bottom
+##### Horizontal positioning- 10% Center to 100% Screen Edge - (ALIGN_NORMAL - LEFT, ALIGN_OPPOSITE - RIGHT) in RTL languages it will be the oposite
+
+#### Example
+
+Subtitle position configuration is done by updating the `SubtitleStyleSettings` object
+
+{% highlight java %}
+SubtitleStyleSettings subtitleStyleSettings = new SubtitleStyleSettings("MyCustomSubtitleStyle");
+PKSubtitlePosition pkSubtitlePosition = new PKSubtitlePosition(true);
+pkSubtitlePosition.setPosition(70, 30, Layout.Alignment.ALIGN_NORMAL);
+subtitleStyleSettings.setSubtitlePosition(pkSubtitlePosition);
+player.getSettings().setSubtitleStyle(subtitleStyleSettings);
+{% endhighlight %} 
+
+#### To update the subtitle position, use a new `PKSubtitlePosition` configuration or call `setToDefault` API
+
+{% highlight java %}
+pkSubtitlePosition.setToDefaultPosition(true);
+subtitleStyleSettings.setSubtitlePosition(pkSubtitlePosition);
+player.updateSubtitleStyle(subtitleStyleSettings);
+{% endhighlight %}
+
+{% highlight java %}
+SubtitleStyleSettings subtitleStyleSettings = new SubtitleStyleSettings("MyCustomSubtitleStyle");
+PKSubtitlePosition pkSubtitlePosition = new PKSubtitlePosition(true);
+pkSubtitlePosition.setVerticalPosition(80);
+subtitleStyleSettings.setSubtitlePosition(pkSubtitlePosition);
+player.getSettings().setSubtitleStyle(subtitleStyleSettings);
+{% endhighlight %}
 
 ### Set ABR Settings
 
@@ -493,9 +554,9 @@ To enable track selection to select subset of tracks that participate in the ABR
 
 {% highlight java %}
 player.getSettings().setABRSettings(new ABRSettings().
-setMinVideoBitrate(900000).
-setMaxVideoBitrate(3000000).
-setInitialBitrateEstimate(100000));
+setMinVideoBitrate(500000).
+setMaxVideoBitrate(1500000).
+setInitialBitrateEstimate(400000));
 {% endhighlight %}
 
 In order to reset these values in Change Media if needed:
@@ -592,7 +653,6 @@ player.getSettings().setVRSettings(new VRSettings().setInteractionMode(VRInterac
                 VRSettings vrSettings = new VRSettings();
                 vrSettings.setFlingEnabled(true);
                 vrSettings.setVrModeEnabled(false);
-
                 vrSettings.setZoomWithPinchEnabled(true);
                 VRInteractionMode interactionMode = vrSettings.getInteractionMode();
                 if (VRUtil.isModeSupported(MainActivity.this, VRInteractionMode.MotionWithTouch)) {